Tutorial
SDR blocks tutorial table of contents
The device arguments are a dictionary of key-value pairs used for specifying a SDR device on the system. If only one SDR device is present on the system, an empty dictionary "{}" may be specified instead.
The key value pairs are the same ones printed by the Soapy SDR Util application:
SoapySDRUtil --find ###################################################### ## Soapy SDR -- the SDR abstraction library ###################################################### Found device 0 backend = libusb device = 0x01:0x02 driver = bladerf instance = 0 serial = 123456789abcdef
- The device argument {"driver":"bladerf"} would cause other devices, such as rtl, to be ignored.
- Or use {"driver":"bladerf", "serial":"123456789abcdef"} if the system has multiple blade RFs.
The data type is a string that specifies the format of the sample stream. Options are available for all complex, integer, and floating point data types, however not all formats may be supported depending upon the underlying driver for the hardware.
- Note: complex float32 and complex int16 are almost universally supported by most hardware drivers.
Channels is an array of channel indexes that will be used for streaming. By default this array is empty, meaning that channel 0 of the device will be used. However when specified, each entry in the array maps a device channel to a streaming port.
Stream arguments are a dictionary of key-value pairs used for passing extra arguments to the stream initialization. Implementation of the stream arguments is specific to the hardware driver, however common uses include specifying the underlying transport sample format and internal scaling. Check your device's manual about stream arguments for more information.
This is the sample rate (in samples per second) for all configured stream ports. All channels listed in the channels parameter will be configured to the same sample rate. Otherwise, use multiple blocks to support heterogeneous sample rates for different channels.
By default, the SDR block is activated upon topology activation. This setting can be disabled for advanced stream control, more on this topic in the sections below.
The receive stream may be decorated with several different labels to indicate configuration and events:
- The "rxTime" label is produced at the start of streaming to indicate the stream time. The data of the label is a 64-bit integer containing the device time in nanoseconds. When using the burst capabilities, each burst will start with an "rxTime" label. In addition, "rxTime" is produced after overflow conditions so that downstream blocks can resynchronize their time-tracking.
- The "rxEnd" label is produced at the end of a burst and when streaming is stopped.
- The "rxFreq" label is produced after the center frequency has been configured. The data of the label is a double value representing the frequency in Hz. Many of the signal analysis plotters use this label to automatically configure the axis.
- The "rxRate" label is produced after the sample rate has been configured. The data of the label is a double value representing the sample rate in samples per second. Many of the signal analysis plotters use this label to automatically configure the axis.
The user has explicit control for bursts and timing using the streamControl() slot. The default behavior of the SDR source is to stream continuously upon activation of the topology. Disable the auto-activation parameter before using advanced the stream control capabilities.
The following arguments can be passed to the streamControl() slot to control streaming:
- streamControl("ACTIVATE") - stream continuously immediately
- streamControl("ACTIVATE_AT", timeNs) - stream continuously starting at timeNs
- streamControl("ACTIVATE_BURST", 0, numElems) - stream a burst of size numElems immediately
- streamControl("ACTIVATE_BURST_AT", timeNs, numElems) - stream a burst of size numElems at timeNs
- streamControl("DEACTIVATE") - halt a continuous stream
- streamControl("DEACTIVATE_AT", timeNs) - halt a continuous stream at timeNs
As a useful demonstration of streamControl(), the periodic trigger block can be used to request bursts at a regular rate. Since many of the plotters only display periodic chunks of the sample stream, this little trick makes it possible to display stream from remote or embedded devices configured at very high sample rates.
Transmit bursts are controlled by stream labels created by upstream blocks. In particular:
- The "txTime" label indicates the transmit time of the first sample in a burst. The data of the label is a 64-bit integer containing the device time in nanoseconds.
- The "txEnd" label indicates the end of a burst to the hardware. Without the end of burst, the hardware may incur an underflow event.
Typically, bursts are sent to the hardware in several fragments. Which means that the hardware can transmit the first fragment before the next arrives. However, burst scheduling can prevent transmission until all fragments arrive.
As a general utility to users and to demonstrate burst-scheduling, the pothos-sdr toolkit comes with a TX burst timer block -- which keeps track of current hardware time and inserts a txTime label into the stream to schedule the bursts.
The frontend map is a hardware-specific string that maps channels to RF frontends. Most hardware doesn't support this option and frontend map should be left empty.
The frequency specifies the center frequency of the channel in Hz.
Advanced:
- The frequency can also be set through the setFrequency() slot to be controlled by graphical widgets and other upstream blocks.
- To specify the frequency on a per-channel basis, simply specify a list of values instead of a single frequency. Example: [1e9, 1.003e9] will set port 0's channel to 1e9 and port 1's channel to 1.003e9.
The tune arguments are a dictionary of key-value pairs that augment the underlying tuning algorithm. Although the tune arguments are hardware-specific, the following conventions are followed by most drivers:
- Tune the frontend with an offset, compensated by the baseband CORDIC: {"OFFSET" : 1e6}
- Tune any specified element in the chain to a specific frequency: {"BB" : 0.0}
- Ignore any specified element when tuning the chain: {"RF" : "IGNORE"}
- Most devices will use "RF" to specify the frontend synthesizer
- Most devices will use "BB" to specify the baseband CORDIC
The gain mode can be used to enable automatic gain control. Its hardware-specific, and most drivers do not implement it.
The gain value can specify the overall amplification (in dB) for the channel, or can be used to specify amplification on a per-element basis. Examples:
- Specify the overall gain in dB: 15.5
- Specify per-element gain settings: {"PGA" : 10.0, "LNA" : 5.5}
Advanced:
- The setGain() slot can be used to control the gain via graphical widgets and other upstream blocks. The setGain() slot also accepts the single value or gain element map format described above.
- To specify the gain on a per-channel basis, simply provide a list of gain settings. Each element in the list can be either a single value or a dictionary mapping: [15.5, {"PGA" : 10.0, "LNA" : 5.5}]
The antenna setting is a string that specifies one of the selectable frontend antenna switches. Not all hardware has configurable antenna options, leave the antenna setting empty in this case.
Advanced:
- The setAntenna() slot can be used to control the antenna switch via graphical widgets and other upstream blocks.
- To specify the antenna on a per-channel basis, provide an array of antenna strings, one string per channel: ["RF1", "RF2"]
The bandwidth setting configures the baseband filter bandwidth in Hz. Not all hardware supports has a baseband filter or supports the exact bandwidth specified. Check your device's manual for more information, or leave the bandwidth at 0.0 Hz to engage the default behavior.
Advanced:
- The setBandwidth() slot can be used to control the filter bandwidth via graphical widgets and other upstream blocks.
- To specify the bandwidth on a per-channel basis, provide an array of filter settings, one value per channel: [10e6, 11e6]
The DC offset mode can be used to enable automatic DC offset removal in the hardware. Not all hardware supports this option. Its recommended to either enable this option when available, or to run the calibration utilities for your hardware. DC removal can also be handled in software using a DC removal block.
