SDRDaemonSource: updated documentation

plugins/channelrx/daemonsink/readme.md

@@ -0,0 +1,46 @@
+<h1>Daemon sink channel plugin</h1>
+
+<h2>Introduction</h2>
+
+This plugin sends I/Q samples from the baseband via UDP to a distant network end point. It can use FEC protection to prevent possible data loss inherent to UDP protocol.
+
+It is present only in Linux binary releases.
+
+<h2>Build</h2>
+
+The plugin will be built only if the [CM256cc library](https://github.com/f4exb/cm256cc) is installed in your system. For CM256cc library you will have to specify the include and library paths on the cmake command line. Say if you install cm256cc in `/opt/install/cm256cc` you will have to add `-DCM256CC_INCLUDE_DIR=/opt/install/cm256cc/include/cm256cc -DCM256CC_LIBRARIES=/opt/install/cm256cc/lib/libcm256cc.so` to the cmake commands.
+
+<h2>Interface</h2>
+
+![Daemon sink channel plugin GUI](../../../doc/img/DaemonSink.png)
+
+<h3>1: Distant address</h2>
+
+IP address of the distant network interface from where the I/Q samples are sent via UDP
+
+<h3>2: Data distant port</h2>
+
+Distant port to which the I/Q samples are sent via UDP
+
+<h3>3: Validation button</h3>
+
+When the return key is hit within the address (1) or port (2) the changes are effective immediately. You can also use this button to set again these values. 
+
+<h3>4: Desired number of FEC blocks per frame</h3>
+
+This sets the number of FEC blocks per frame. A frame consists of 128 data blocks (1 meta data block followed by 127 I/Q data blocks) and a variable number of FEC blocks used to protect the UDP transmission with a Cauchy MDS block erasure correction. The two numbers next are the total number of blocks and the number of FEC blocks separated by a slash (/).
+
+<h3>5: Delay between UDP blocks transmission</h3>
+
+This sets the minimum delay between transmission of an UDP block (send datagram) and the next. This allows throttling of the UDP transmission that is otherwise uncontrolled and causes network congestion.
+
+The value is a percentage of the nominal time it takes to process a block of samples corresponding to one UDP block (512 bytes). This is calculated as follows:
+
+  - Sample rate on the network: _SR_
+  - Delay percentage: _d_
+  - Number of FEC blocks: _F_
+  - There are 127 blocks of I/Q data per frame (1 meta block for 128 blocks) and each I/Q data block of 512 bytes (128 samples) has a 8 bytes header (2 samples) thus there are 126 samples remaining effectively. This gives the constant 127*126 = 16002 samples per frame in the formula
+  
+Formula: ((127 &#x2715; 126 &#x2715; _d_) / _SR_) / (128 + _F_)   
+
+The percentage appears first at the right of the dial button and then the actual delay value in microseconds.

plugins/channeltx/daemonsource/readme.md

@@ -0,0 +1,79 @@
+<h1>Daemon source channel plugin</h1>
+
+<h2>Introduction</h2>
+
+This plugin receives I/Q samples from UDP and copies them to the baseband to be transmitted by the sink output device. It uses SDRDaemon format and possible FEC protection.
+
+It is present only in Linux binary releases.
+
+<h2>Build</h2>
+
+The plugin will be built only if the [CM256cc library](https://github.com/f4exb/cm256cc) is installed in your system. For CM256cc library you will have to specify the include and library paths on the cmake command line. Say if you install cm256cc in `/opt/install/cm256cc` you will have to add `-DCM256CC_INCLUDE_DIR=/opt/install/cm256cc/include/cm256cc -DCM256CC_LIBRARIES=/opt/install/cm256cc/lib/libcm256cc.so` to the cmake commands.
+
+<h2>Interface</h2>
+
+![Daemon source channel plugin GUI](../../../doc/img/DaemonSource.png)
+
+<h3>1: Data local address</h2>
+
+IP address of the local network interface from where the I/Q samples are fetched via UDP
+
+<h3>2: Data local port</h2>
+
+Local port from where the I/Q samples are fetched via UDP
+
+<h3>3: Validation button</h3>
+
+When the return key is hit within the address (1) or port (2) the changes are effective immediately. You can also use this button to set again these values. 
+
+<h3>4: Stream sample rate</h3>
+
+Stream sample rate as specified in the stream meta data
+
+<h3>5: Stream status</h3>
+
+![Daemon source channel plugin GUI](../../../doc/img/DaemonSource_5.png)
+
+<h4>5.1: Total number of frames and number of FEC blocks</h4>
+
+This is the total number of frames and number of FEC blocks separated by a slash '/' as sent in the meta data block thus acknowledged by the distant server. When you set the number of FEC blocks with (4.1) the effect may not be immediate and this information can be used to monitor when it gets effectively set in the distant server.
+
+A frame consists of 128 data blocks (1 meta data block followed by 127 I/Q data blocks) and a variable number of FEC blocks used to protect the UDP transmission with a Cauchy MDS block erasure correction.
+
+Using the Cauchy MDS block erasure correction ensures that if at least the number of data blocks (128) is received per complete frame then all lost blocks in any position can be restored. For example if 8 FEC blocks are used then 136 blocks are transmitted per frame. If only 130 blocks (128 or greater) are received then data can be recovered. If only 127 blocks (or less) are received then none of the lost blocks can be recovered.
+
+<h4>5.2: Stream status</h4>
+
+The color of the icon indicates stream status:
+
+  - Green: all original blocks have been received for all frames during the last polling timeframe (ex: 136)
+  - No color: some original blocks were reconstructed from FEC blocks for some frames during the last polling timeframe (ex: between 128 and 135)
+  - Red: some original blocks were definitely lost for some frames during the last polling timeframe (ex: less than 128)
+  
+<h4>5.3: Actual stream sample rate</h4>
+
+This is the sample rate calculated using the counter of samples between two consecutive polls
+
+<h4>5.4: Reset events counters</h4>
+
+This push button can be used to reset the events counters (5.5 and 5.6) and reset the event counts timer (5.7)
+
+<h4>5.5: Unrecoverable error events counter</h4>
+
+This counter counts the unrecoverable error conditions found (i.e. 4.4 lower than 128) since the last counters reset.
+
+<h4>5.6: Recoverable error events counter</h4>
+
+This counter counts the unrecoverable error conditions found (i.e. 4.4 between 128 and 128 plus the number of FEC blocks) since the last counters reset.
+
+<h4>5.7: events counters timer</h4>
+
+This HH:mm:ss time display shows the time since the reset events counters button (5.4) was pushed.
+
+<h3>6: Transmitter queue length gauge</h3>
+
+This is ratio of the reported number of data frame blocks in the remote queue over the total number of blocks in the queue.
+
+<h3>7: Transmitter queue length status</h3>
+
+This is the detail of the ratio shown in the gauge. Each frame block is a block of 127 &#x2715; 126 samples (16 bit I or Q samples) or 127 &#x2715; 63 samples (24 bit I or Q samples).