VE7UWU/sdrangel
1
0
Fork 0
mirror of https://github.com/f4exb/sdrangel.git synced 2024-12-22 17:45:48 -05:00
Code Issues Projects Releases Wiki Activity

FileSource channel plugin: updated documentation

Browse Source
This commit is contained in:
f4exb 2019-07-10 22:02:34 +02:00
parent 0b0985f918
commit acb5e94c40
4 changed files with 101 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Readme.md
View File

@ -183,6 +183,10 @@ The software is installed in `/usr/bin` for executables and `/usr/lib/sdrangel`
<h2>Windows</h2>
The `.7z` file is a [7Zip](https://www.7-zip.org/) archive of the complete binary distribution that expands to the `sdrangel` directory. You can install it anywhere you like and double click on `sdrangel.exe` to start.
The `.exe` file is a self extracting installation program. Just click on it and follow instructions on the successive panels.
The installation program creates a menu entry that can be invoked like any other Windows program.
Note that the archive can be opened, inspected and extracted using [7Zip](https://www.7-zip.org/).
<b>&#9888; Windows distribution is provided as a by product thanks to the Qt toolchain. The platform of choice to run SDRangel is definitely Linux and very little support can be given for this Windows distribution.</b>

BIN
doc/img/FileSource_plugin.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

BIN
doc/img/FileSource_plugin.xcf Normal file
View File

Binary file not shown.

136
plugins/channeltx/filesource/readme.md
View File

@ -1,79 +1,135 @@
<h1>Remote source channel plugin</h1>
<h1>File 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 SDRangel remote format and possible FEC protection.
This plugin reads a file of I/Q samples that have been previously saved with the file record button of other sampling source devices. The file starts with a 32 byte header of all unsigned integer of various sizes containing meta data:
It is present only in Linux binary releases.
<table>
<tr>
<th>Displ.</th>
<th>Bytes</th>
<th>Description</th>
</tr>
<tr>
<td>0</td>
<td>4</td>
<td>Sample rate in S/s</td>
</tr>
<tr>
<td>4</td>
<td>8</td>
<td>Center frequency in Hz</td>
</tr>
<tr>
<td>12</td>
<td>8</td>
<td>Unix epoch (timestamp) of start</td>
</tr>
<tr>
<td>20</td>
<td>4</td>
<td>Sample size (16 or 24 bits)</td>
</tr>
<tr>
<td>24</td>
<td>4</td>
<td>Filler with zeroes</td>
</tr>
<tr>
<td>28</td>
<td>4</td>
<td>CRC32 of the previous 28 bytes</td>
</tr>
</table>
<h2>Build</h2>
The header takes an integer number of 16 (4 bytes) or 24 (8 bytes) bits samples. To calculate CRC it is assumed that bytes are in little endian order.
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_DIR=/opt/install/cm256cc` to the cmake commands.
The I/Q samples are copied to the baseband to be transmitted by the sink output device with possibly a chain of half-band interpolators for upsampling and shift of bandwidth.
<h2>Interface</h2>
![Remote source channel plugin GUI](../../../doc/img/RemoteSource.png)
![File source channel plugin GUI](../../../doc/img/FileSource_plugin.png)
<h3>1: Data local address</h2>
<h3>1: Interpolation factor</h3>
IP address of the local network interface from where the I/Q samples are fetched via UDP
The device baseband can be interpolated from the channel and its center can be selected with (5). The resulting sample rate of the I/Q stream pulled from the Local Output device sink is the baseband sample rate divided by this value. The value is displayed in (2).
<h3>2: Data local port</h2>
<h3>2: I/Q stream sample rate</h3>
Local port from where the I/Q samples are fetched via UDP
This is the sample rate in kS/s of the I/Q stream pulled from the Local Output device sink instance.
<h3>3: Validation button</h3>
<h3>3: Half-band filters chain sequence</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.
This string represents the sequence of half-band filters used in the interpolation. Each character represents a filter type:
<h3>4: Stream sample rate</h3>
- **L**: lower half-band
- **H**: higher half-band
- **C**: centered
Stream sample rate as specified in the stream meta data
<h3>4: Center frequency shift</h3>
<h3>5: Stream status</h3>
This is the shift of the channel center frequency from the device center frequency. Its value is driven by the device sample rate, the interpolation (1) and the filter chain sequence (5).
![Remote source channel plugin GUI](../../../doc/img/RemoteSource_5.png)
<h3>5: Half-band filter chain sequence</h3>
<h4>5.1: Total number of frames and number of FEC blocks</h4>
The slider moves the channel center frequency roughly from the lower to the higher frequency in the device baseband. The number on the right represents the filter sequence as the decimal value of a base 3 number. Each base 3 digit represents the filter type and its sequence from MSB to LSB in the filter chain:
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.
- **0**: lower half-band
- **1**: centered
- **2**: higher half-band
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.
<h3>6: Level meter in dB</h3>
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.
- top bar (green): average value
- bottom bar (blue green): instantaneous peak value
- tip vertical bar (bright green): peak hold value
<h4>5.2: Stream status</h4>
You must make sure that the peaks do not exceed 0 dB. In fact you should have 1 or 2 dB reserve when you tune the power level with the gain slider (7)
The color of the icon indicates stream status:
<h3>7: Gain</h3>
- 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>
You may use this control to apply a gain to the input signal. You can control the resulting channel power with (6).
This is the sample rate calculated using the counter of samples between two consecutive polls
<h3>8: Open file</h3>
<h4>5.4: Reset events counters</h4>
Opens a file dialog to select the input file. It expects a default extension of `.sdriq`. This button is disabled when the stream is running. You need to pause (button 11) to make it active and thus be able to select another file.
This push button can be used to reset the events counters (5.5 and 5.6) and reset the event counts timer (5.7)
<h3>9: File path</h3>
<h4>5.5: Unrecoverable error events counter</h4>
Absolute path of the file being read
This counter counts the unrecoverable error conditions found (i.e. 4.4 lower than 128) since the last counters reset.
<h3>10: File recorded sample rate</h3>
<h4>5.6: Recoverable error events counter</h4>
Sample rate of the record in kS/s as written in the header. The reading process is based on this sample rate.
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.
<h3>11: Sample size</h3>
<h4>5.7: events counters timer</h4>
This is the sample size in bits as written in the header. The reading process is based on this sample size.
This HH:mm:ss time display shows the time since the reset events counters button (5.4) was pushed.
<h3>12: CRC indicator</h3>
<h3>6: Transmitter queue length gauge</h3>
Indicates if the header block CRC check has succeeded (green) or failed (red) or undetermined yet (grey). If the header is corrupted you may try to reconstruct a valid header using the `rescuesdriq` utility in the folder with the same name. See the [readme](../../../rescuesdriq/readme.md) for details.
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>13: Loop</h3>
<h3>7: Transmitter queue length status</h3>
Use this button to read in a loop or read only once
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).
<h3>14: Play/pause</h3>
This is the play/pause button
<h3>15: Current timestamp</h3>
This is the timestamp of the current pointer in the file based on the start time, number of samples read and sample rate.
<h3>16: Relative timestamp</h3>
Left is the relative timestamp of the current pointer from the start of the record.
<h3>17: Record length</h3>
This is the total record time.
<h3>18: Current pointer gauge</h3>
This represents the position of the current pointer position in the complete recording. It can be used it paused mode to position the current pointer by moving the slider.