NFM: updated documentation

plugins/channelrx/demodnfm/readme.md

@@ -22,44 +22,105 @@ Average total power in dB relative to a +/- 1.0 amplitude signal received in the
   - bottom bar (blue green): instantaneous peak value
   - tip vertical bar (bright green): peak hold value
 
-<h3>4: RF bandwidth</h3>
+<h3>4: Channel spacing presets</h3>
 
-This is the bandwidth in kHz of the channel signal before demodulation. It can take these values with the corresponding nominal frequency deviation:
+This selector will apply RF bandwidth, AF bandwidth and FM deviation settings according to the channel spacing scheme as follows:
 
-  - **5** kHz: &plusmn; 1.25 kHz
-  - **6.25** kHz: &plusmn; 1.25 kHz
-  - **8.33** kHz: &plusmn; 1.67 kHz
-  - **11** kHz: &plusmn; 2.5 kHz (11F3)
-  - **16** kHz: &plusmn; 5 kHz (16F3)
-  - **20** kHz: &plusmn; 7 kHz
-  - **25** kHz: &plusmn; 9.5 kHz
-  - **40** kHz: &plusmn; 14 kHz
+<table>
+    <tr>
+        <th>CS (kHz)</th>
+        <th>RFBW (kHz)</th>
+        <th>AFBW (kHz)</th>
+        <th>FM &Delta; (&plusmn;kHz)</th>
+        <th>&beta;</th>
+    </tr>
+    <tr>
+        <td>5</td>
+        <td>4.8</td>
+        <td>1.7</td>
+        <td>0.7</td>
+        <td>0.43</td>
+    </tr>
+    <tr>
+        <td>6.25</td>
+        <td>6</td>
+        <td>2.1</td>
+        <td>0.9</td>
+        <td>0.43</td>
+    </tr>
+    <tr>
+        <td>7.5</td>
+        <td>7.2</td>
+        <td>2.5</td>
+        <td>1.1</td>
+        <td>0.43</td>
+    </tr>
+    <tr>
+        <td>8.33</td>
+        <td>8</td>
+        <td>2.8</td>
+        <td>1.2</td>
+        <td>0.43</td>
+    </tr>
+    <tr>
+        <td>12.5</td>
+        <td>11</td>
+        <td>3</td>
+        <td>2.5</td>
+        <td>0.83</td>
+    </tr>
+    <tr>
+        <td>25</td>
+        <td>16</td>
+        <td>3</td>
+        <td>5</td>
+        <td>1.67</td>
+    </tr>
+    <tr>
+        <td>40</td>
+        <td>36</td>
+        <td>9</td>
+        <td>9</td>
+        <td>1</td>
+    </tr>
+</table>
+
+  - All these settings apply the Carson's rule: RFBW = 2 &times; (FM&Delta; + AFBW)
+  - The 12.5 and 25 kHz channel spacings correspond to standard 11F3 and 16F3 settings respectively and are widely accepted and mostly used
+  - For spacings lower than 12.5 kHz values are empirically built using Carson's rule from &beta;=0.43 which is the only standard provided
+  - For spacing higher than 25 kHz values are derived from an old 36F9 standard.
+
+When you are lost with the RF, AF bandwidths and FM deviation settings you can always come back to these standards and generally get good results.
 
 &#9758; The demodulation is done at the channel sample rate which is guaranteed not to be lower than the requested audio sample rate but can possibly be equal to it. This means that for correct operation in any case you must ensure that the sample rate of the audio device is not lower than the Nyquist rate required to process this channel bandwidth.
 
 &#9758; The channel sample rate is always the baseband signal rate divided by an integer power of two so depending on the baseband sample rate obtained from the sampling device you could also guarantee a minimal channel bandwidth. For example with a 125 kS/s baseband sample rate and a 8 kS/s audio sample rate the channel sample rate cannot be lower than 125/8 = 15.625 kS/s (125/16 = 7.8125 kS/s is too small) which is still OK for 5 or 6.25 kHz channel bandwidths.
 
-<h3>5: AF bandwidth</h3>
+<h3>5: RF bandwidth</h3>
 
-This is the bandwidth of the audio signal in kHz (i.e. after demodulation). It can be set in continuous kHz steps from 1 to 20 kHz.
+This is the bandwidth in kHz of the filter applied before the discriminator and therefore called "RF" bandwidth but is applied in the device pass band in fact.
 
-<h3>6: Volume</h3>
+<h3>6: AF bandwidth</h3>
 
-This is the volume of the audio signal from 0% (mute) to 200% (maximum) of volume at nominal frequency deviation. It can be varied continuously 1% steps using the dial button.
+This is the bandwidth of the audio signal in kHz (i.e. after demodulation).
 
-<h3>7: Delta/Level squelch</h3>
+<h3>7: Expected FM peak deviation</h3>
+
+This is the peak FM deviation in &plusmn;kHz expected in the received signal and corresponds to 100% audio volume
+
+<h3>8: Delta/Level squelch</h3>
 
 Use this button to toggle between AF (on) and RF power (off) based squelch.
 
-<h3>8: Squelch threshold</h3>
+<h3>9: Squelch threshold</h3>
 
 <h4>Power threshold mode</h4>
 
-Case when the delta/Level squelch control (7) is off (power). This is the squelch threshold in dB. The average total power received in the signal bandwidth before demodulation is compared to this value and the squelch input is open above this value. It can be varied continuously in 1 dB steps from 0 to -100 dB using the dial button.
+Case when the delta/Level squelch control (8) is off (power). This is the squelch threshold in dB. The average total power received in the signal bandwidth before demodulation is compared to this value and the squelch input is open above this value. It can be varied continuously in 1 dB steps from 0 to -100 dB using the dial button.
 
 <h4>Audio frequency delta mode</h4>
 
-Case when the delta/Level squelch control (7) is on (delta). In this mode the squelch compares the power of the demodulated audio signal in a low frequency band and a high frequency band. In the absence of signal the discriminator response is nearly flat and the power in the two bands is more or less balanced. In the presence of a signal the lower band will receive more power than the higher band. The squelch does the ratio of both powers and the squelch is opened if this ratio is lower than the threshold given in percent.
+Case when the delta/Level squelch control (8) is on (delta). In this mode the squelch compares the power of the demodulated audio signal in a low frequency band and a high frequency band. In the absence of signal the discriminator response is nearly flat and the power in the two bands is more or less balanced. In the presence of a signal the lower band will receive more power than the higher band. The squelch does the ratio of both powers and the squelch is opened if this ratio is lower than the threshold given in percent.
 
 A ratio of 1 (100%) will always open the squelch and a ratio of 0 will always close it. The value can be varied to detect more distorted and thus weak signals towards the higher values. The button rotation runs from higher to lower as you turn it clockwise thus giving the same feel as in power mode. The best ratio for a standard NFM transmission is ~40%.
 
@@ -69,27 +130,31 @@ The distinct advantage of this type of squelch is that it guarantees the quality
 
 &#9758; The chosen bands around 1000 and 6000 Hz are optimized for standard voice signals in the 300-3000 Hz range.
 
-<h3>9: Squelch gate</h3>
+<h3>10: Squelch gate</h3>
 
 This is the squelch gate in milliseconds. The squelch input must be open for this amount of time before the squelch actually opens. This prevents the opening of the squelch by parasitic transients. It can be varied continuously in 10ms steps from 10 to 500ms using the dial button.
 
-<h3>10: CTCSS on/off</h3>
+<h3>11: CTCSS on/off</h3>
 
 Use the checkbox to toggle CTCSS activation. When activated it will look for a tone squelch in the demodulated signal and display its frequency (see 10).
 
-<h3>11: CTCSS tone</h3>
+<h3>12: CTCSS tone</h3>
 
 This is the tone squelch in Hz. It can be selected using the toolbox among [these CTCSS values](https://en.wikipedia.org/wiki/Continuous_Tone-Coded_Squelch_System) and `--` for none. When a value is given and the CTCSS is activated the squelch will open only for signals with this tone squelch.
 
-<h3>12: CTCSS tone value</h3>
+<h3>13: CTCSS tone value</h3>
 
 This is the value of the tone squelch received when the CTCSS is activated. It displays `--` if the CTCSS system is de-activated.
 
-<h3>13: Audio high pass filter</h3>
+<h3>14: Volume</h3>
+
+This is the volume of the audio signal from 0% (mute) to 200% (maximum) of volume at nominal frequency deviation. It can be varied continuously 1% steps using the dial button.
+
+<h3>15: Audio high pass filter</h3>
 
 Toggle a 300 Hz cutoff high pass filter on audio to cut-off CTCSS frequencies. It is on by default for normal audio channels usage. You can switch it off to pipe the audio in programs requiring DC like DSD+ or Multimon.
 
-<h3>14: Audio mute and audio output select</h3>
+<h3>16: Audio mute and audio output select</h3>
 
 Left click on this button to toggle audio mute for this channel. The button will light up in green if the squelch is open. This helps identifying which channels are active in a multi-channel configuration.
 

plugins/channeltx/modnfm/readme.md

@@ -12,25 +12,95 @@ This plugin can be used to generate a narrowband frequency modulated signal. "Na
 
 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>3: Channel power</h3>
+<h3>2: Channel power</h3>
 
 Average total power in dB relative to a +/- 1.0 amplitude signal generated in the pass band.
 
-<h3>4: Channel mute</h3>
+<h3>3: Channel mute</h3>
 
 Use this button to toggle mute for this channel.
 
-<h3>5: RF bandwidth</h3>
+<h3>4: Channel spacing presets</h3>
 
-This is the bandwidth in kHz of the channel signal filtered after modulation. It can be set in discrete values: 3, 4, 5, 6.25, 8.33, 10, 12.5, 15, 20, 25 and 40 kHz
+This selector will apply RF bandwidth, AF bandwidth and FM deviation settings according to the channel spacing scheme as follows:
 
-<h3>6: Audio frequency bandwidth</h3>
+<table>
+    <tr>
+        <th>CS (kHz)</th>
+        <th>RFBW (kHz)</th>
+        <th>AFBW (kHz)</th>
+        <th>FM &Delta; (&plusmn;kHz)</th>
+        <th>&beta;</th>
+    </tr>
+    <tr>
+        <td>5</td>
+        <td>4.8</td>
+        <td>1.7</td>
+        <td>0.7</td>
+        <td>0.43</td>
+    </tr>
+    <tr>
+        <td>6.25</td>
+        <td>6</td>
+        <td>2.1</td>
+        <td>0.9</td>
+        <td>0.43</td>
+    </tr>
+    <tr>
+        <td>7.5</td>
+        <td>7.2</td>
+        <td>2.5</td>
+        <td>1.1</td>
+        <td>0.43</td>
+    </tr>
+    <tr>
+        <td>8.33</td>
+        <td>8</td>
+        <td>2.8</td>
+        <td>1.2</td>
+        <td>0.43</td>
+    </tr>
+    <tr>
+        <td>12.5</td>
+        <td>11</td>
+        <td>3</td>
+        <td>2.5</td>
+        <td>0.83</td>
+    </tr>
+    <tr>
+        <td>25</td>
+        <td>16</td>
+        <td>3</td>
+        <td>5</td>
+        <td>1.67</td>
+    </tr>
+    <tr>
+        <td>40</td>
+        <td>36</td>
+        <td>9</td>
+        <td>9</td>
+        <td>1</td>
+    </tr>
+</table>
 
-This is the bandwidth in khz of the modulating signal filtered before modulation. It can be set in kHz steps from 1 to 20 kHz
+  - All these settings apply the Carson's rule: RFBW = 2 &times; (FM&Delta; + AFBW)
+  - The 12.5 and 25 kHz channel spacings correspond to standard 11F3 and 16F3 settings respectively and are widely accepted and mostly used
+  - For spacings lower than 12.5 kHz values are empirically built using Carson's rule from &beta;=0.43 which is the only standard provided
+  - For spacing higher than 25 kHz values are derived from an old 36F9 standard.
+
+When you are lost with the RF, AF bandwidths and FM deviation settings you can always come back to these standards and generally get good results.
+
+<h3>5: Audio frequency bandwidth</h3>
+
+This is the bandwidth in khz of the modulating signal filtered before modulation.
+
+<h3>6: RF bandwidth</h3>
+
+This is the bandwidth in kHz of the channel signal filtered after modulation.
 
 <h3>7: Frequency deviation</h3>
 
-Adjusts the frequency deviation in 0.1 kHz steps from 0 to 30 kHz. This is the full deviation.
+This is the peak FM deviation in &plusmn;kHz that will be effective for nominal (1.0) audio volume
 
 <h3>8: Volume</h3>
 
@@ -66,27 +136,35 @@ Left click to switch to the audio input. You must switch it off to make other in
 
 Right click to select audio input device. See [audio management documentation](../../../sdrgui/audio.md) for details.
 
-<h3>11: CTCSS switch</h3>
+<h3>11: Audio feedback</h3>
+
+Activate or de-activate the input source audio feedback
+
+<h3>12: Audio feedback volume</h3>
+
+Adjust audio feedback volume
+
+<h3>13: CTCSS switch</h3>
 
 Checkbox to switch on the CTCSS sub-audio tone
 
-<h3>12: CTSS tone frequency</h3>
+<h3>14: CTSS tone frequency</h3>
 
 Select the CTCSS sub-audio tone in Hz among [these values](https://en.wikipedia.org/wiki/Continuous_Tone-Coded_Squelch_System)
 
-<h3>14: CW (Morse) text</h3>
+<h3>15: CW (Morse) text</h3>
 
 Enter the text to be keyed when Morse input is active and in text mode
 
-<h3>15: Clear CW text</h3>
+<h3>16: Clear CW text</h3>
 
 Clears the CW (Morse) text
 
-<h3>16: Morse keyer controls</h3>
+<h3>17: Morse keyer controls</h3>
 
 ![Morse keyer control GUI1](../../../doc/img/ModCWControls1.png)
 
-<h4>16.1: CW keying speed</h4>
+<h4>17.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:
 
@@ -95,74 +173,76 @@ Sets the CW speed in Words Per Minute (WPM). This is based on the word "PARIS" s
   - Character silence separator: 3 dot lengths
   - Word silence separator: 7 dot lengths
 
-<h4>16.2: Dots keying</h4>
+<h4>17.2: Dots keying</h4>
 
 Switch this button to send dots continuously
 
-<h4>16.3: Dashes keying</h4>
+<h4>17.3: Dashes keying</h4>
 
 Switch this button to send dashes continuously
 
-<h4>16.4: Text keying</h4>
+<h4>17.4: Text keying</h4>
 
 Switch this button to send the text typed into the text box (14)
 
-<h4>16.5: Text auto repeat</h4>
+<h4>17.5: Text auto repeat</h4>
 
 Switch this button to auto repeat the text keying
 
-<h4>12.6: Text play/stop</h4>
+<h4>17.6: Text play/stop</h4>
 
 Use this button to stop sending text. When resuming keying restarts at the start of text
 
+<h3>18: Use keyboard for morse keying</h3>
+
 ![Morse keyer control GUI2](../../../doc/img/ModCWControls2.png)
 
-&#9888; WARNING: what follows is not really useful if you do not use a proper Morse keyer with direct audio feedback. There is a significant audio delay either with the direct monitoring or by monitoring the transmitted signal so keying with this audio as feedback is not practical
+&#9888; WARNING: this is not really useful if you do not use a proper Morse keyer with direct audio feedback. There is a significant audio delay either with the direct monitoring or by monitoring the transmitted signal so keying with this audio as feedback is not practical
 
-12.7: Activate morse keys keyboard control
+18.7: Activate morse keys keyboard control
 
 This disables text or continuous dots or dashes. Toggle input from keyboard. Occasionnaly the focus may get lost and you will have to deactivate and reactivate it to recover the key bindings.
 
-12.8: Iambic or straight
+18.8: Iambic or straight
 
 Choose iambic or straight keying style. When straight is selected the dot or dash key may be used.
 
-12.9: Register dot key
+18.9: Register dot key
 
 Click on the button and while selected type a character or character and modifier (Shift + key for example) to select which key is used for dots. The key or key sequence appears next (here dot `.`)
 
-12.10: Register dash key
+18.10: Register dash key
 
 Click on the button and while selected type a character or character and modifier (Shift + key for example) to select which key is used for dashes. The key or key sequence appears next (here dot `.`)
 
-<h3>17: Audio file path</h3>
+<h3>19: Audio file path</h3>
 
 The path to the selected audio file to be played or dots if unselected
 
-<h3>18: Audio file play controls</h3>
+<h3>20: Audio file play controls</h3>
 
 ![Modulator audio file play control GUI](../../../doc/img/ModFileControls.png)
 
-<h4>18.1: Audio file select</h4>
+<h4>20.1: Audio file select</h4>
 
 Opens a file dialog to select the audio file to be played. It must be mono 48 kHz F32LE raw format. 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`
 
-<h4>18.2: Audio file loop</h4>
+<h4>20.2: Audio file loop</h4>
 
 Audio replay file at the end
 
-<h4>18.3: Play/pause file play</h4>
+<h4>20.3: Play/pause file play</h4>
 
 Toggle play/pause file play. When paused the slider below (17) can be used to randomly set the position in the file when re-starting.
 
-<h3>19: Play file current position</h3>
+<h3>21: Play file current position</h3>
 
 This is the current audio file play position in time units relative to the start
 
-<h3>20: Play file length</h3>
+<h3>22: Play file length</h3>
 
 This is the audio file play length in time units
 
-<h3>21: Play file position slider</h3>
+<h3>23: 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 18.3)