AirStack Application Notes¶
Continuous Streaming¶
Data streams are guaranteed to be continuous in with the AirStack driver, SoapyAIRT. That is, there is no gap in time between the last sample in a buffer and the first sample in the following buffer. The following sections outline best practices to maintain a continuous data stream as well as highlighting conditions to avoid where streams may become discontinuous.
Errors - Anytime the SoapyAIRT API returns an error code, any currently active data stream can no longer be considered continuous. Different data streams share a common hardware resource, so errors with one stream can affect others. As a result, users may want to restart all streams if an error is encountered. For application compatibility, we do attempt to restart any stream automatically, however it is STRONGLY recommended that users manually restart affected streams to attempt to fix the root cause of the error. Error codes and their possible root causes are shown below:
| Error Code | Error Name | Description |
|---|---|---|
| -1 | SOAPY_SDR_TIMEOUT | Inactive hardware that has not been properly configured. Has the stream not been activated? |
| -2 | SOAPY_SDR_STREAM_ERROR | Generic streaming error. See logs for more info. |
| -3 | SOAPY_SDR_CORRUPTION | Multiple channels in a single stream are reporting different issues (likely cause is a single channel had an overflow). See kernel logs for specific details. |
| -4 | SOAPY_SDR_OVERFLOW | All channels in the stream have overflowed. The application is not reading samples from the radio fast enough. |
| -5 | SOAPY_SDR_NOT_SUPPORTED | You are asking the AIR-T to do something that it cannot do. |
| -6 | SOAPY_SDR_TIME_ERROR | As of AirStack 0.5 you should not see this error reported by the AIR-T. |
| -7 | SOAPY_SDR_UNDERFLOW | See "TX Streams" below. You are not providing samples to the radio fast enough. |
Finally, it should be noted that in order to make logging more verbose (especially useful when providing log information / output to customer support) that an environment variable may be set appropriately. This is done by export SOAPY_SDR_LOG_LEVEL=DEBUG in the terminal.
Multiple Channel Synchronization - For streams with multiple channels, there are no guarantees that the sample data will be synchronized in any meaningful way. If you require channels to be synchronized, the recommended way of doing so is via the hardware trigger (TODO: LINK GOES HERE). Note that any condition that would cause a discontinuity in the stream (i.e., errors and changes to SDR settings) will cause the synchronization to no longer hold.
Changing SDR Settings - There are specific cases where changing a SDR setting will result in discontinuous data.
First, if the sample rate is changed, any active stream that uses the channel affected by the change will be flushed to remove any samples with the old setting applied. As a result, the data stream will no longer be continuous.
Second, all active data streams are no longer continuous if frequency is changed. This occurs because the RF front end must recalibrate for LO suppression and quadrature error correction. Note that this means that changing the TX frequency may affect RX streams and vice-versa.
Overall, the best practice is to change SDR settings/parameters without an active stream (i.e., deactivate all streams, apply the new setting, and then re-active the streams). We perform these steps inside of the AirStack drivers if an active stream is detected while SDR settings are being changed because we recognize that not all applications can control when settings are being manipulated. With that said, we recommend restarting streams manually in the application code itself in order to explicitly document the fact that a discontinuity will occur when the setting is being changed.
TX Streams -The SoapyAIRT API expects all TX buffers passed to it to be continuous, unless the SOAPY_SDR_END_BURST flag is set when calling writeStream(). That is, without the flag set, the API expects each buffer to be part of a continuous transmission. The flag being set indicates that a transmission has ended and the API expects there to be a gap in time between the current call to writeStream() and any subsequent data transfer.
Note that, by default, underflow conditions (gaps in time between two buffers we are expecting to be continuous) are not reported by the SoapyAIRT API. This is due to compatibility issues with returning the error code and how other applications handle the error. Users can enable underflow checking/reporting by adding report_tx_underflow=true to the device arguments passed in to the SoapySDR constructor (it is not currently recommended to enable this feature in any GNU Radio applications).