VOR single channel and localizer feature: added documentation

plugins/channelrx/demodvorsc/readme.md

@@ -14,36 +14,60 @@ Note that for aircraft, there is typically a direct line-of-sight to the VOR. Th
 
 <h2>Using it for localization</h2>
 
-Several instances of this plugin can be created to monitor multiple VORs and collate information in the VOR Localizer feature plugin. The VOR Localizer can also perform a round robin on multiple VORs with just one VOR demodulator. Please refer to ... for more information about this feature plugin
+Several instances of this plugin can be created to monitor multiple VORs and collate information in the VOR Localizer feature plugin. The VOR Localizer can also perform a round robin on multiple VORs with just one VOR demodulator. Please refer to [VOR Localizer](../../feature/vorlocalizer/readme.md) for more information about this feature plugin
 
 <h2>Interface</h2>
 
-![VOR Demodulator plugin GUI](../../../doc/img/VORDemod_plugin.png)
+![VOR Demodulator plugin GUI](../../../doc/img/VORDemodSC_plugin.png)
 
-<h3>1: Level meter in dB</h3>
+<h3>1: Frequency shift from center frequency of reception value</h3>
+
+Use the wheels to adjust the frequency shift in Hz from the center frequency of reception. 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. Left click on a digit sets the cursor position at this digit.
+
+<h3>2: 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>2: Channel power</h3>
+<h3>3: Channel power</h3>
 
 Average total power in dB relative to a +/- 1.0 amplitude signal received in the pass band.
 
-<h3>3: Audio mute and audio output select</h3>
+<h3>4: 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.
 
 If you right click on it it will open a dialog to select the audio output device. See [audio management documentation](../../../sdrgui/audio.md) for details.
 
-<h3>6: Morse ident threshold</h3>
+<h3>5: Morse ident threshold</h3>
 
 This is the Morse code ident threshold, expressed as a linear signal to noise (SNR) ratio. This is effectively the signal level required for the Morse demodulator to detect a dot or dash. Setting this to low values will allow the Morse demodulator to detect weak signals, but it also increases the likelyhood that noise will incorrectly be interpreted as a signal, resulting in invalid idents being reported.
 
-<h3>7: Squelch threshold</h3>
+<h3>6: Squelch threshold</h3>
 
 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 0.1 dB steps from 0.0 to -100.0 dB using the dial button.
 
-<h3>8: Volume</h3>
+<h3>7: Volume</h3>
 
 This is the volume of the audio signal from 0.0 (mute) to 10.0 (maximum). It can be varied continuously in 0.1 steps using the dial button.
+
+<h3>8: Radial dircetion</h3>
+
+Demodulated radial direction in degrees (unadjusted for magnetic declination). If there is a low confidence the value is correct (due to a weak signal), it will be displayed in red.
+
+<h3>9: Reference signal power in dB</h3>
+
+Magnitude of the received 30Hz FM reference signal in dB
+
+<h3>10. Variable signal power in dB</h3>
+
+Mangitude of the received 30Hz AM variable signal in dB
+
+<h3>11. VOR identifier code (decoded)</h3>
+
+Demodulated identifier. If an identifier is received that is not 2 or 3 characters, it will be displayed in yellow else in white.
+
+<h3>12. VOR identifier code (Morse)</h3>
+
+Demodulated Morse code identifier. Colour coding is the ame as for the decoded identifier.

plugins/channelrx/demodvorsc/vordemodscgui.ui

@@ -144,30 +144,6 @@
         </property>
        </spacer>
       </item>
-      <item>
-       <layout class="QHBoxLayout" name="channelPowerLayout_2">
-        <item>
-         <widget class="QLabel" name="channelPower_2">
-          <property name="toolTip">
-           <string>Channel power</string>
-          </property>
-          <property name="layoutDirection">
-           <enum>Qt::RightToLeft</enum>
-          </property>
-          <property name="text">
-           <string>0.0</string>
-          </property>
-         </widget>
-        </item>
-        <item>
-         <widget class="QLabel" name="channelPowerUnits_2">
-          <property name="text">
-           <string> dB</string>
-          </property>
-         </widget>
-        </item>
-       </layout>
-      </item>
      </layout>
     </item>
     <item>

plugins/channelrx/demodvorsc/vordemodscplugin.cpp

@@ -29,7 +29,7 @@
 const PluginDescriptor VORDemodSCPlugin::m_pluginDescriptor = {
     VORDemodSC::m_channelId,
     QStringLiteral("VOR Single Channel Demodulator"),
-    QStringLiteral("6.2.0"),
+    QStringLiteral("6.3.0"),
     QStringLiteral("(c) Jon Beniston, M7RCE"),
     QStringLiteral("https://github.com/f4exb/sdrangel"),
     true,

plugins/feature/vorlocalizer/readme.md

@@ -0,0 +1,86 @@
+<h1>VOR Localizer plugin</h1>
+
+<h2>Introduction</h2>
+
+This plugin can control and receive information from single channel VOR demodulators (see [VOR single channel demodulator](../../channelrx/demodvorsc/readme.md) for details) and collate information from multiple VOR demodulators in order to show your position on a map.
+
+<h2>Interface</h2>
+
+![VOR Localizer plugin GUI](../../../doc/img/VORLocalizer_plugin.png)
+
+There are 3 sections in this interface:
+  - **A**: settings
+  - **B**: VOR table
+  - **C**: map (not shown on this picture)
+
+<h2>A: Settings section</h2>
+
+![VOR Localizer settings](../../../doc/img/VORLocalizer_settings.png)
+
+<h3>1: Start/Stop plugin</h3>
+
+This button starts or stops the plugin
+
+<h3>2: Download VOR Database</h3>
+
+Pressing this button downloads the OpenAIP.net Navaid database, which contains the details (position, frequencies, name and ident) for each VOR. This needs to be performed at least once.
+
+<h3>3: Draw Radials Adjusted for Magnetic Declination</h3>
+
+When checked, radials on the map will drawn adjusted for magnetic declination. For example, if a VOR has a magnetic declination of 5 degrees, and the radial is calculated at 0 degrees, the radial will be drawn to magnetic North, i.e. -5 degress from true North. If not checked, the same radial would be drawn to true North (i.e 0 degrees), which may result in a less accurate position estimate.
+
+<h3>4: Round robin turn time</h3>
+
+Available VOR demodulator channels are allocated to service the selected VORs on the map and displayed in the VOR table (B). There could be less available channels than the number of VORs to service in which case the channel(s) of the same device can be used to service VORs in turn in a round robin fashion. This sets the time in seconds dedicated to each turn. More details on channels allocation agorithm is given in (6).
+
+<h3>5: Center frequency shift</h3>
+
+The center frequency of the device may be shifted from its value computed from VOR allocation. This can help moving the channel center away from the device DC if necessary.
+
+<h3>6: List of VOR demodulator channels in the system</h3>
+
+This combo is not used to select anything but just to show the VOR demodulators that have been detected and that will be used to service the list of selected VORs int the (B) table.
+
+The display is `Rn:m` where `n` is the device set index and `m` the channel index in the device set.
+
+Channels may be used in round robin turns if their number is not enough to cover all VORs. The allocation algorithm will use devices with multiple channels first in order to accomodate several VORs with just one device. The baseband must be large enough to fit the VORs simultaneously. If there are VORs remaining more turns are added with just one channel being used. It is always possible to service any number of VORs with a single channel.
+
+When there is more than one turn for a device valid radial directions are averaged and the resulting average is used during the round robin loop. Averaging also takes place for reference and variable signal levels.
+
+<h3>7: Refresh VOR demodulators list and allocation</h3>
+
+Use this button to (re)scan the available VOR demodulators in the SDRangel instance and (re)run the round robin allocation.
+
+<h2>B: VOR Table</h2>
+
+The VOR table displays information about selected VORs. To select or deselect a VOR, double click it on the map. The information displayed includes:
+
+![VOR Demodulator Table](../../../doc/img/VORLocalizer_table.png)
+
+* Name - The name of the VOR. For example: 'LONDON'.
+* Freq (MHz) - The center frequency the VOR transmits on in MHz. The frequency is highlighted in green when the VOR is serviced by a demodulator.
+* Nav Id - This is the VOR unique identifier from the VOR database.
+* Ident - A 2 or 3 character identifier for the VOR. For example: 'LON'.
+* Morse - The Morse code identifier for the VOR. For example: '.-.. --- -.'
+* RX Ident - This contains the demodulated ident. If it matches the expected ident, it will be displayed in green, if not, it will be displayed in red. If an ident is received that is not 2 or 3 characters, it will not be displayed, but the last received ident will be displayed in yellow.
+* RX Morse - This contains the demodulated Morse code ident. Colour coding is as for RX Ident.
+* Radial - This contains the demodulated radial direction in degrees (unadjusted for magnetic declination). If there is a low confidence the value is correct (due to a weak signal), it will be displayed in red.
+* Ref (dB) - This displays the magnitude of the received 30Hz FM reference signal in dB.
+* Var (dB) - This displays the mangitude of the received 30Hz AM variable signal in dB.
+* Mute - This button allows you to mute or unmute the audio from the corresponding VOR.
+
+<h2>C: Map</h2>
+
+The map displays the locations of each VOR, with an information box containing the information about the VOR, such as it's name, frequency, ident (in text and Morse), range and magnetic declination.
+
+To initialise the VORs on the map, first set your position using the Preferences > My position menu. Then press the Download VOR Database button (This only needs to be performed once). The map should then display VORs in your vicinity.
+
+Double clicking on a VOR will select and add it to the list of VORs to demodulate. It will be added to the VOR table. The frequency will be highlighted green when the VOR is serviced by a VOR demodulator. Double clicking a selected VOR, will remove it from the list of VORs to demodulate and it will be removed from the VOR table.
+
+When a signal from a VOR is correctly being demodulated, a radial line will be drawn on the map, at the angle provided by the VOR demodulator or their average over the round robin turn if this is the case. Your receiver should be somewhere along this radial line. The length of the radial line is set according to the range of the VOR as recorded in the database, which is valid for aircraft at altitude. Range on the ground will be considerably less. An approximate position for the receiver is where the radial lines from two or more VORs intersect.
+
+![VOR Demodulator Map](../../../doc/img/VORDemod_plugin_map.png)
+
+<h2>Attribution</h2>
+
+Icons by Denelson83 and mamayer, via Wikimedia Commons and RULI from the Noun Project https://thenounproject.com/