Update example.ini with more documentation

1 files changed, 77 insertions, 17 deletions

diff --git a/doc/example.ini b/doc/example.ini
index 0f5dfe2..9cdfe03 100644
--- a/doc/example.ini
+++ b/doc/example.ini
@@ -20,33 +20,68 @@ filename=/dev/stderr
 transport=file
 source=/dev/stdin
 
+; When the end of file is reached, it is possible to rewind it
+loop=0
+
 ; When recieving data using ZeroMQ, the source is the URI to be used
 ;transport=zeromq
 ;source=tcp://localhost:8080
-loop=1
 
 [modulator]
 ; Gain mode: 0=FIX, 1=MAX, 2=VAR
+;
+;   Mode 0 (FIX) uses a fixed factor and is really not recommended. It is more
+; useful on an academic perspective for people trying to understand the DAB
+; modulation.
+;
+;   Mode 1 (MAX) is the normalization of every OFDM symbol. No overshoot, no
+; truncating, but varying output power (around 3dB) which might not be the best
+; for some power amplifier. The output samples are limited to a magnitude
+; of 32768.
+;
+;   Mode 2 (VAR) uses the method specified in ETSI 300 798. This method
+; normalizes to 4 times the standard deviation for an approximation of the RMS
+; power. So around 6/100000 samples will be truncated and will introduce some
+; really minor distortion. But this mode also maximizes the output power. This
+; is the gain mode recommended for real world operation as it is based on a DAB
+; standard; the only difference is that ODR-DabMod uses a better resolution
+; with 16 bits instead of 8 bits.
 gainmode=2
 
 ; Transmission mode
 ; If not defined, take the mode from ETI
 ;mode=2
 
-; Set to 0 to disable CicEqualiser
-dac_clk_rate=0
-
+; The digital gain is a value that is multiplied to each sample. It is used
+; to tune the chain to make sure that no non-linearities appear up to the
+; USRP daughterboard programmable gain amplifier (PGA).
+; If there is clipping, the spectral quality of the signal will quickly deteriorate,
+; and wide-band noise will be generated.
+;
+; Be aware that there is a dependency with resampling.
 digital_gain=1.0
 
-; Output sample rate
+; Output sample rate. Values other than 2048000 enable
+; resampling.
+; Warning! digital_gain settings are different if resampling
+; is enabled or not !
 rate=2048000
 
+; CIC equaliser for USRP1 and USRP2
+; Set to 0 to disable CicEqualiser
+; when set to 400000000, an additional USRP2 check is enabled.
+; See DabModulator.cpp line 186
+dac_clk_rate=0
+
 ; The USRP1 does not have flexible clocking, you will need
 ;rate=3200000
 ; and
 ;dac_clk_rate=128000000
 
 [firfilter]
+; The FIR Filter can be used to create a better spectral quality.
+; The filter taps can be calculated with the python script
+; doc/fir-filter/generate-filter.py
 enabled=0
 filtertapsfile=simple_taps.txt
 
@@ -55,15 +90,32 @@ filtertapsfile=simple_taps.txt
 output=uhd
 
 [fileoutput]
+; The file output writes I/Q float values (i.e. complex float)
+; to the file. The I and Q samples can take values up to
+; 100000 in absolute magnitude with gainmode FIX.
+; With gainmode VAR, they should never exceed 50000.
+; With gainmode MAX, thet are limited to 32767.
 filename=/dev/stdout
 
 [uhdoutput]
-; For a USRP B100:
+; The UHD output can be directly used with the Ettus USRP devices
+;
+; You have to set master_clock_rate to a multiple of the
+; sample_rate. Ideally, it should be
+;   master_clock_rate = 4 * sample_rate
+; or even a higher factor.
+;
+; Settings for a USRP B100:
 device=master_clock_rate=32768000,type=b100
 txgain=2
-; Try with small gain values
+; Try first with small gain values
+; Also set rate to 2048000
 
 ; For the B200
+; More information and measurements available on:
+; http://opendigitalradio.org/index.php/USRP_B200_Measurements
+;
+; Settings:
 ;device=master_clock_rate=20480000,type=b200
 ;txgain=40
 ; The B200 needs larger gains (up to 89dB) but,
@@ -73,43 +125,51 @@ txgain=2
 ;    From the B200 User Manual
 ;    http://files.ettus.com/uhd_docs/manual/html/usrp_b200.html
 
-; TODO: measure the RF quality with different values of master_clock_rate:
-;    10240000
-;    20480000
-;    30720000
-;    32768000
-;    and other values
 
 ; For the USRP1
 ;device=type=usrp1
 ; the usrp1 can have two daughterboards, the subdevice parameter allows you
 ; to choose which one to use
 ;subdevice=A:0
+; The USRP1 doesn't support master_clock_rate, you need to enable resamping
+
 
-; you must specify either frequency or channel
+; You must specify either frequency or channel, but not both.
 ;frequency=234208000
 channel=13C
 
+; The reference clock to use.
 ; possible values : internal, external, MIMO
 refclk_source=internal
 
+; The reference one pulse-per second to use
 ; possible values : none, external, MIMO
 pps_source=none
 
-; behaviour when external clock reference lock lost
+; Behaviour when external clock reference lock lost
 ; possible values: ignore, crash
 behaviour_refclk_lock_lost=ignore
 
 
 ; Used for SFN with the UHD output
 [delaymanagement]
+
+; Enable handling of timestamps for SFN
 synchronous=0
 
-; whether to mute the TX when incoming frames have no timestamp
+; Whether to mute the TX when incoming frames have no timestamp
 mutenotimestamps=0
 
-; choose between fixed and dynamic offset definition
+; Choose between fixed and dynamic offset definition
+; fixed defines an offset in this file that cannot be changed while
+; the modulator runs.
+;
+; dynamic reads the offset from a file, and if the value changes,
+; the chain does a re-sync.
 management=dynamic
 
 fixedoffset=0.002
+
+; The file should contain a single floating point value, written
+; in ASCII (it's human-readable, not binary)
 dynamicoffsetfile=modulator_offset