SDRDaemonSink: updated documentation

plugins/samplesink/sdrdaemonsink/readme.md

@@ -2,10 +2,14 @@
 
 <h2>Introduction</h2>
 
-This output sample sink plugin sends its samples over tbe network to a SDRdaemon transmitter server using UDP connection. SDRdaemon refers to the SDRdaemon utility `sdrdaemontx`found in [this](https://github.com/f4exb/sdrdaemon) Github repository.
+This output sample sink plugin sends its samples over tbe network to a SDRangel instance's Daemon source channel using UDP connection.
 
 Forward Error Correction with a Cauchy MDS block erasure codec is used to prevent block loss. This can make the UDP transmission more robust particularly over WiFi links.
 
+The distant SDRangel instance to which the data stream is sent is controlled via its REST API using a separate control software for example [SDRangelcli](https://github.com/f4exb/sdrangelcli)
+
+The sample size used in the I/Q stream is the Rx sample size of the local instance. Possible conversion takes place in the distant Daemon source channel plugin to match the Rx sample size of the distant instance. Best performace is obtained when both instances use the same sample size. 
+
 <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.
@@ -23,25 +27,25 @@ Device start / stop button.
   
 <h3>2: Stream sample rate</h3>
 
-Stream I/Q sample rate in kS/s over the network.
+I/Q sample rate in kS/s of the stream that is sent over the network.
 
 <h3>3: Frequency</h3>
 
-This is the center frequency in kHz sent to the remote device.
+This is the center frequency in kHz of the remote instance device.
 
-<h3>4: Sample rate</h3>
+<h3>4: Remote baseband sample rate</h3>
 
-![SDR Daemon sink output sample rate GUI](../../../doc/img/SDRdaemonSink_plugin_04.png)
+This is the remote instance baseband sample rate. It can be a power of two multiple of the stream sample rate (2) but it will not work for other values.
 
-<h4>4.1: Network stream sample rate</h4>
+<h3>5: Stream controls and API destination</h3> 
+
+![SDR Daemon sink output sample rate GUI](../../../doc/img/SDRdaemonSink_plugin_05.png)
+
+<h4>5.1: Network stream sample rate</h4>
 
 This is the I/Q stream sample rate transmitted via UDP over the network
 
-<h4>4.2: Remote interpolation factor</h4>
-
-This is the interpolation set in the remote `sdrdaemontx` server instance.
-
-<h3>5: Delay between UDP blocks transmission</h3>
+<h4>5.2: Delay between UDP blocks transmission</h4>
 
 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.
 
@@ -54,6 +58,14 @@ The value is a percentage of the nominal time it takes to process a block of sam
   
 Formula: ((127 &#x2715; 126 &#x2715; _d_) / _SR_) / (128 + _F_)   
 
+<h4>5.3: remote instance device set index</h4>
+
+This is the device set index in the remote instance to which the stream is connected to. Use this value to properly address the API to get status.
+
+<h4>5.4: remote instance channel index</h4>
+
+This is the channel index of the Daemon source in the remote instance to which the stream is connected to. Use this value to properly address the API to get status.
+
 <h3>6: Forward Error Correction setting and status</h3>
 
 ![SDR Daemon sink output FEC GUI](../../../doc/img/SDRdaemonSink_plugin_06.png)
@@ -62,65 +74,83 @@ Formula: ((127 &#x2715; 126 &#x2715; _d_) / _SR_) / (128 + _F_)
 
 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 (/).
 
-<h4>6.2: Distant transmitter queue length</h4>
-
-This is the samples queue length reported from the distant transmitter. This is a number of vectors of 127 &#x2715; 127 &#x2715; _I_ samples where _I_ is the interpolation factor. This corresponds to a block of 127 &#x2715; 126 samples sent over the network. This numbers serves to throttle the sample generator so that the queue length is close to 8 vectors.
-
-<h4>6.3: Stream status</h4>
+<h4>6.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: 134)
   - No color: some original blocks were reconstructed from FEC blocks for some frames during the last polling timeframe (ex: between 128 and 133)
   - Red: some original blocks were definitely lost for some frames during the last polling timeframe (ex: less than 128)
+  - Blue: stream is idle
 
-<h4>6.4: Frames recovery status</h4>
+<h4>6.3: Remote stream rate</h4>
 
-These are two numbers separated by a slash (/):
+This is the remote stream rate calculated from the samples counter between two consecutive API polls. It is normal for it to oscillate moderately around the nominal stream rate (2).
 
-  - first: minimum total number of blocks per frame during the last polling period. If all blocks were received for all frames then this number is the nominal number of original blocks plus FEC blocks (Green lock icon). In our example this is 128+6 = 134.
-  - second: maximum number of FEC blocks used for original blocks recovery during the last polling timeframe. Ideally this should be 0 when no blocks are lost but the system is able to correct lost blocks up to the nominal number of FEC blocks (Neutral lock icon).
-
-<h4>6.5: Reset events counters</h4>
+<h4>6.4: Reset events counters</h4>
 
 This push button can be used to reset the events counters (6.6 and 6.7) and reset the event counts timer (6.8)
 
-<h4>6.6: Unrecoverable error events counter</h4>
+<h4>6.5: Unrecoverable error events counter</h4>
 
 This counter counts the unrecoverable error conditions found (i.e. 6.4 lower than 128) since the last counters reset.
 
-<h4>6.7: Recoverable error events counter</h4>
+<h4>6.6: Recoverable error events counter</h4>
 
 This counter counts the unrecoverable error conditions found (i.e. 6.4 between 128 and 128 plus the number of FEC blocks) since the last counters reset.
 
-<h4>6.8: events counters timer</h4>
+<h4>6.7: events counters timer</h4>
 
 This HH:mm:ss time display shows the time since the reset events counters button (4.6) was pushed.
 
-<h3>7: Network parameters</h3>
+<h3>7: Distant transmitter queue length gauge</h3>
 
-![SDR Daemon sink output network GUI](../../../doc/img/SDRdaemonSink_plugin_07.png)
+This is ratio of the reported number of data frame blocks in the remote queue over the total number of blocks in the queue.
 
-<h4>7.1: Distant interface IP address</h4>
+<h3>8: Distant transmitter queue length status</h3>
 
-Address of the network interface on the distance (server) machine where the SDRdaemon Tx server runs and receives samples.
+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).
 
-<h4>7.2: Distant data port</h4>
+<h3>9: Distant server API address and port</h3>
 
-UDP port on the distant (server) machine where the SDRdaemon Tx server runs and receives samples.
+![SDR Daemon source input stream GUI](../../../doc/img/SDRdaemonSource_plugin_05.png)
 
-<h4>7.3 Distant configuration port</h4>
+<h4>9.1: API connection indicator</h4>
 
-TCP port on the distant machine hosting the SDRdaemon Tx instance to send control messages to and receive status messages from.
+The "API" label is lit in green when the connection is successful
 
-<h4>7.4: Validation button</h4>
+<h4>9.2: API IP address</h4>
 
-When the return key is hit within the address (7.1), data port (7.2) or configuration port (7.3) boxes the changes are effective immediately. You can also use this button to set again these values.
+IP address of the distant SDRangel instance REST API
 
-<h4>8: Other parameters hardware specific</h4>
+<h4>9.3: API port</h4>
 
-These are the parameters that are specific to the hardware attached to the distant SDRdaemon instance. You have to know which device is attached to send the proper parameters. Please refer to the SDRdaemon documentation or its line help to get information on these parameters. 
+Port of the distant SDRangel instance REST API
 
-<h4>9: Send data to the distant SDRdaemon Rx instance</h4>
+<h4>9.4: Validation button</h4>
 
-When any of the parameters change they get immediately transmitted to the distant server over the TCP link. You can however use this button to send again the complete configuration. This is handy if for some reason you are unsure of the parameters set in the distant server.
+When the return key is hit within the address (9.2) or port (9.3) the changes are effective immediately. You can also use this button to set again these values. Clicking on this button will send a request to the API to get the distant SDRangel instance information that is displayed in the API message box (8) 
+
+<h3>10: Local data address and port</h3>
+
+![SDR Daemon source input stream GUI](../../../doc/img/SDRdaemonSource_plugin_06.png)
+
+<h4>10.1: Data IP address</h4>
+
+IP address of the local network interface the distant SDRangel instance sends the data to
+
+<h4>10.2: Data port</h4>
+
+Local port the distant SDRangel instance sends the data to
+
+<h4>10.3: Validation button</h4>
+
+When the return key is hit within the address (10.2) or port (10.3) the changes are effective immediately. You can also use this button to set again these values. 
+
+<h3>11: Status message</h3>
+
+The API status is displayed in this box. It shows "API OK" when the connection is successful and reply is OK
+
+<h3>12: API information</h3>
+
+This is the information returned by the API and is the distance SDRangel instance information if transaction is successful

plugins/samplesource/sdrdaemonsource/readme.md

@@ -2,7 +2,7 @@
 
 <h2>Introduction</h2>
 
-This input sample source plugin gets its samples over tbe network from a SDRdaemon receiver server using UDP connection. SDRdaemon refers to the SDRdaemon utility `sdrdaemonrx`found in [this](https://github.com/f4exb/sdrdaemon) Github repository.
+This input sample source plugin gets its samples over tbe network from a SDRangel instance's Daemon channel sink using UDP connection.
 
 Forward Error Correction with a Cauchy MDS block erasure codec is used to prevent block loss. This can make the UDP transmission more robust particularly over WiFi links.
 
@@ -10,6 +10,8 @@ Please note that there is no provision for handling out of sync UDP blocks. It i
 
 The distant SDRangel instance that sends the data stream is controlled via its REST API using a separate control software for example [SDRangelcli](https://github.com/f4exb/sdrangelcli)
 
+A sample size conversion takes place if the stream sample size sent by the distant instance and the Rx sample size of the local instance do not match (i.e. 16 to 24 bits or 24 to 16 bits). Best performace is obtained when both instances use the same sample size.
+
 <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.