FreeDV: added documentation

plugins/channelrx/demodfreedv/readme.md

@@ -0,0 +1,95 @@
+<h1>FreeDV demodulator plugin</h1>
+
+<h2>Introduction</h2>
+
+This plugin can be used to demodulate a signal following the [FreeDV digital voice protocol](https://freedv.org/).
+
+<h2>Interface</h2>
+
+![FreeDV Demodulator plugin GUI](../../../doc/img/FreeDVDemod_plugin.png)
+
+<h3>1: Frequency shift from center frequency of reception</h3>
+
+Use the wheels to adjust the frequency shift in Hz from the center frequency of reception. Left click on a digit sets the cursor position at this digit. Right click on a digit sets all digits on the right to zero. This effectively floors value at the digit position. Wheels are moved with the mousewheel while pointing at the wheel or by selecting the wheel with the left mouse click and using the keyboard arrows. Pressing shift simultaneously moves digit by 5 and pressing control moves it by 2.
+
+<h3>2: Channel power</h3>
+
+Average total power in dB relative to a +/- 1.0 amplitude signal received in the pass band.
+
+<h3>3: Manual re-synchronization</h3>
+
+This works only for the presently disabled 700D mode. Use this push button to force loosing and re-acquiring synchronisation.
+  
+<h3>4: FreeDV mode</h3>
+
+Use this combo box to select which FreeDV standard is used. The following are supported:
+
+  - `2400A`: FSK-4 wideband (6 kHz) modulation with 1300 b/s compressed voice to be used at 29 MHz and above similarly to FM analog usage. [Details here](https://www.rowetel.com/?p=5119)
+  - `1600`: OFDM (16 QPSK carriers) narrowband (1.4 kHz) with 700 b/s compressed voice
+  - `800XA`: FSK-4 narrowband (2 kHz) with 700 b/s compressed voice
+  - `700C`: Another OFDM (14 QPSK carriers) narrowband (1.5 kHz) mode with 700 b/s compressed voice
+  
+<h3>5: Level meter in dB</h3>
+
+  - top bar (green): average value
+  - bottom bar (blue green): instantaneous peak value
+  - tip vertical bar (bright green): peak hold value
+
+<h3>6: AGC and volume controls</h3>
+
+![FreeDV volume and AGC controls](../../../doc/img/FreeDVDemod_plugin_1.png)
+
+<h4>6.1: AGC toggle</h4>
+
+Use this checkbox to toggle AGC on and off.
+
+<h4>6.2: Modem input volume</h4>
+
+This is the volume of the signal entering the modem  from 0.0 (mute) to 9.9 (maximum). It can be varied continuously in 0.1 steps using the dial button. Use this control to make sure the peaks do not exceed 100% on the VU meter.
+
+<h4>6.3: Modem input VU meter</h4>
+
+This shows the level of the signal entering the modem and peaks (shown by the tiny red vertical bar) should never exceed 100%. In fact there is a 10% guard so 100% is actually 90% of the signal volume.
+
+<h4>6.4: Audio output volume</h4>
+
+This is the volume of the audio signal from 0.0 (mute) to 9.9 (maximum). It can be varied continuously in 0.1 steps using the dial button. The mid position (5.0) corresponds to the normal level of comfort.
+
+<h3>7: Digital signal quality indicators</h3>
+
+![FreeDV digital signal quality](../../../doc/img/FreeDVDemod_plugin_2.png)
+
+<h4>7.1: Bit Error Rate (BER)</h4>
+
+This shows the number of bit errors per second and is derived from the bit error counter updated at each frame and the frames per second depending on the FreeDV mode.
+
+<h4>7.2: Synchronization indicator</h4>
+
+This indicator lights in green when synchronization is locked. Note that this does not work for FM modes (2400A, 800XA).
+
+<h4>7.3: Digital Signal to Noise Ratio</h4>
+
+This should be derived more or less from the calculated Eb/N0. Note that in 700C mode it takes big jumps and does not seem very reliable.
+
+<h4>7.4: Frequency shift estimation</h4>
+
+This is an estimation of the frequency shift from optimal position. Use the frequency delta dial (1) to make it as close to 0 as possible.
+
+<h3>8: Spectrum display frequency span</h3>
+
+The transmitted signal is further decimated by a power of two before being applied to the channel spectrum display and used to set the in channel filter limits. This effectively sets the total available bandwidth depending on the decimation:
+
+  - 1 (no decimation): 24 kHz (2400A) or 4 kHz (other modes)
+  - 2: 12 kHz (2400A) or 2 kHz (other modes)
+  - 4: 6 kHz (2400A) or 1 kHz (other modes)
+  - 8: 3 kHz (2400A) or 0.5 kHz (other modes)
+  - 16: 1.5 kHz (2400A) or 0.25 kHz (other modes)
+  
+<h3>9: Spectrum display</h3>
+
+This is the spectrum display of the analog signal that enters the modem before AGC and volume control. Controls on the bottom of the panel are identical to the ones of the main spectrum display. It should be optimally centered using the frequency offset control (1) depending on the expected FreeDV mode:
+
+  - `2400A`: 3 kHz (filtered from 0 to 6 kHz)
+  - `1600`: 1.5 kHz (filtered from 0.6 to 2.4 kHz)
+  - `800XA`: 1.4 kHz (filtered from 0.4 to 2.4 kHz)
+  - `700C`: 1.5 kHz (filtered from 0.6 to 2.4 kHz)

plugins/channeltx/modfreedv/readme.md

@@ -0,0 +1,158 @@
+<h1>FreeDV modulator plugin</h1>
+
+<h2>Introduction</h2>
+
+This plugin can be used to generate a signal following the [FreeDV digital voice protocol](https://freedv.org/).
+
+<h2>Interface</h2>
+
+![FreeDV Modulator plugin GUI](../../../doc/img/FreeDVMod_plugin.png)
+
+<h3>1: Frequency shift from center frequency of transmission</h3>
+
+Use the wheels to adjust the frequency shift in Hz from the center frequency of transmission. Left click on a digit sets the cursor position at this digit. Right click on a digit sets all digits on the right to zero. This effectively floors value at the digit position. Wheels are moved with the mousewheel while pointing at the wheel or by selecting the wheel with the left mouse click and using the keyboard arrows. Pressing shift simultaneously moves digit by 5 and pressing control moves it by 2.
+
+<h3>2: Channel power</h3>
+
+Average total power in dB relative to a +/- 1.0 amplitude signal generated in the pass band.
+
+<h3>3: FreeDV mode</h3>
+
+Use this combo box to select which FreeDV standard is used. The following are supported:
+
+  - `2400A`: FSK-4 wideband (6 kHz) modulation with 1300 b/s compressed voice to be used at 29 MHz and above similarly to FM analog usage. [Details here](https://www.rowetel.com/?p=5119)
+  - `1600`: OFDM (16 QPSK carriers) narrowband (1.4 kHz) with 700 b/s compressed voice
+  - `800XA`: FSK-4 narrowband (2 kHz) with 700 b/s compressed voice
+  - `700C`: Another OFDM (14 QPSK carriers) narrowband (1.5 kHz) mode with 700 b/s compressed voice
+
+<h3>4: Reverse left and right channels in binaural mode</h3>
+
+Effective only in binaural mode: reverses left and right audio channels so that the left is connected to Q and the right to the I complex signal channel. 
+
+<h3>4: VU meter selection</h3>
+
+Check to select input audio to be displayed on the VU meter (6)
+
+<h3>5: Volume</h3>
+
+This is the volume of the modulating audio signal from 0.0 (mute) to 2.0 (maximum). It can be varied continuously in 0.1 steps using the dial button. The Loudspeaker button is the audio mute toggle.
+
+<h3>6: Level meter in %</h3>
+
+Use the checkbox (4) to select between input audio and modulator output display
+
+  - top bar (beige): average value
+  - bottom bar (brown): instantaneous peak value
+  - tip vertical bar (bright red): peak hold value
+
+You should aim at keeping the peak value below 100% using the volume control
+
+<h3>7: Input source control</h3>
+
+![Modulator input source control GUI](../../../doc/img/ModControls.png)
+
+<h4>7.1: Tone input select</h4>
+
+Switches to the tone input. You must switch it off to make other inputs available. Note that tone input has been kept from other modulators but does not make much sense for digital voice modes.
+
+<h4>7.2: Morse keyer input select</h4>
+
+Switches to the Morse keyer input. You must switch it off to make other inputs available. Note that the Morse keyer has been kept from other modulators but does not make much sense for digital voice modes.
+
+<h4>7.3: Tone frequency (kHz)</h4>
+
+Adjusts the tone frequency from 0.1 to 2.5 kHz in 0.01 kHz steps.
+
+<h4>7.4: Audio input select and select audio input device</h4>
+
+Left click to switch to the audio input. You must switch it off to make other inputs available.
+
+Right click to select audio input device. See [audio management documentation](../../../sdrgui/audio.md) for details.
+
+<h3>8: CW (Morse) text</h3>
+
+Enter the text to be keyed when Morse input is active and in text mode. 
+
+<h3>9: Clear CW text</h3>
+
+Clears the CW (Morse) text
+
+<h3>10: Morse keyer controls</h3>
+
+![Morse keyer control GUI](../../../doc/img/ModCWControls.png)
+
+<h4>10.1: CW keying speed</h4>
+
+Sets the CW speed in Words Per Minute (WPM). This is based on the word "PARIS" sent 5 times. For 5 WPM the dot length is 240 ms. In other terms the dot length is calculated as 1.2 / WPM seconds. The dot length is used as the base to compute other timings:
+
+  - Element (dot or dash) silence separator: 1 dot length
+  - Dash: 3 dot lengths
+  - Character silence separator: 3 dot lengths
+  - Word silence separator: 7 dot lengths
+  
+<h4>10.2: Dots keying</h4>
+
+Switch this button to send dots continuously
+
+<h4>10.3: Dashes keying</h4>
+
+Switch this button to send dashes continuously
+
+<h4>10.4: Text keying</h4>
+
+Switch this button to send the text typed into the text box (13)
+
+<h4>10.5: Text auto repeat</h4>
+
+Switch this button to auto repeat the text keying
+
+<h4>10.6: Text play/stop</h4>
+
+Use this button to stop sending text. When resuming keying restarts at the start of text
+
+<h3>11: Audio file path</h3>
+
+The path to the selected audio file to be played or dots if unselected
+
+<h3>12: Audio file play controls</h3>
+
+![Modulator audio file play control GUI](../../../doc/img/ModFileControls.png)
+
+<h4>12.1: Audio file select</h4>
+
+Opens a file dialog to select the audio file to be played. It must be 48 kHz F32LE raw format. If binaural mode is selected it takes a 2 channel (stereo) file else it should be mono.
+Using sox a .wav file can be converted with this command: `sox piano.wav -t raw -r 48k -c 1 -b 32 -L -e float piano.raw` (mono) or `sox piano.wav -t raw -r 48k -c 2 -b 32 -L -e float piano.raw` (stereo)
+
+<h4>12.2: Audio file loop</h4>
+
+Audio replay file at the end
+
+<h4>12.3: Play/pause file play</h4>
+
+Toggle play/pause file play. When paused the slider below (20) can be used to randomly set the position in the file when re-starting.
+
+<h3>13: Play file current position</h3>
+
+This is the current audio file play position in time units relative to the start
+
+<h3>14: Play file length</h3>
+
+This is the audio file play length in time units
+
+<h3>15: Play file position slider</h3>
+
+This slider can be used to randomly set the current position in the file when file play is in pause state (button 17.3)
+
+<h3>16: Spectrum display frequency span</h3>
+
+The transmitted signal is further decimated by a power of two before being applied to the channel spectrum display and used to set the in channel filter limits. This effectively sets the total available bandwidth depending on the decimation:
+
+  - 1 (no decimation): 24 kHz (2400A) or 4 kHz (other modes)
+  - 2: 12 kHz (2400A) or 2 kHz (other modes)
+  - 4: 6 kHz (2400A) or 1 kHz (other modes)
+  - 8: 3 kHz (2400A) or 0.5 kHz (other modes)
+  - 16: 1.5 kHz (2400A) or 0.25 kHz (other modes)
+
+<h3>17: Channel spectrum display</h3>
+
+This is the channel spectrum display. Controls at the bottom of the panel are the same as with the central spectrum display.