 |
USRP Hardware Driver and USRP Manual
Version: 4.7.0.0
UHD and USRP Manual
|
|
|
USRP Hardware Driver and USRP Manual
Version: 4.7.0.0
UHD and USRP Manual
|
|
The address string for a device is mainly used to identify a device (see also Device Identification), but it can also be used to propagate settings to the device.
As an example, say you run rx_samples_to_file with the following settings:
$ rx_samples_to_file --args type=b200,master_clock_rate=16e6
This will first use the type flag to search your system for connected B200 or B210 devices, as described on Device Identification. Once it has found one of these, it will connect to it and pass the master_clock_rate=16e6 option to the device initialization (in this case, it will set the master clock rate to 16 MHz as described on Changing the Master Clock Rate).
The following table lists common configuration options you can pass as device arguments. Also check out the individual device manuals for more information and possible more options, as individual devices may have more specialized options available not listed here.
| Key | Description | Supported Devices | Example Value |
|---|---|---|---|
| blank_eeprom | Caution! Having this key will erase the EEPROM and can damage your device! | X3x0 | blank_eeprom=1 |
| fpga | Provide alternative FPGA bitfile | All USB Devices, X3x0 (PCIe only), E310, E1x0 | fpga=/path/to/bitfile.bit |
| fw | Provide alternative firmware | All USB Devices, X3x0 | fw=/path/to/fw.bin |
| ignore-cal-file | Ignores existing device calibration files | All Devices with cal-file support | See Ignoring Calibration Files |
| master_clock_rate | Master Clock Rate in Hz | X3x0, X4x0, B2x0, B1x0, E3xx, E1x0, N3xx | master_clock_rate=16e6 |
| dboard_clock_rate | Daughterboard clock rate in Hz | X3x0 | dboard_clock_rate=50e6 |
| system_ref_rate | Frequency of external reference | X3x0 | system_ref_rate=11.52e6 |
| mcr | Override master clock rate settings (see External clock modification) | USRP1 | mcr=52e6 |
| niusrprpc_port | RPC Port for NI USRP RIO | X3x0 | niusrprpc_port=5445 |
| system_ref_rate | Reference Clock Rate in Hz | X3x0 | system_ref_rate=10e6 |
| self_cal_adc_delay | Run ADC transfer delay self-calibration. | X3x0 | self_cal_adc_delay=1 |
| ext_adc_self_test | Run an extended ADC self test (more than the usual) | X3x0 | ext_adc_self_test=1 |
| recover_mb_eeprom | Disable version checks. Can damage hardware. Only recommended for recovering devices with corrupted EEPROMs. | X3x0 | recover_mb_eeprom=1 |
| serialize_init | Force serial initialization of motherboards (default is parallel) | X3x0, all MPM devices | serialize_init=1 |
| force_reinit | Force reinitialization of device | N3x0, X4x0 | force_reinit=1 |
In addition, many of the streaming-related options can be set per-device at configuration time. See Streaming Arguments (Stream Args) and Transport Notes for more details.
A subdevice specification (or "subdev spec") string for USRP family devices is composed of:
<motherboard slot name>:<daughterboard frontend name>
Ex: The subdev spec markup string to select a WBX on slot B.
B:0
Ex: The subdev spec markup string to select a BasicRX on slot B (on USRP2/N200 devices only).
B:AB -- OR -- B:A -- OR -- B:B
A subdev spec can consist of multiple strings if a motherboard has the option for more than one radio device. In the X300, you may have an SBX in slot A and a CBX in slot B. Both of these daughterboards have one frontend ("0"), so the subdev spec to configure both these radio channels would look like this:
A:0 B:0
The individual subdev specs are separated by spaces. On some devices, such as the X300 or the B200, it is possible to swap these to hint that slot B should be the first radio ("channel 0") and slot A should be the second radio ("channel 1"):
B:0 A:0
On devices with more than one radio, setting the subdev spec to a single value declares that the other radio is not used. In a configuration with multiple USRPs, this means that this device will only be assigned a single channel.
Note that a subdev spec string always only pertains to a single USRP, even if multiple USRPs are configured to run together. For such a configuration, you set a subdev spec string for every device individually.
All USRP family motherboards have a first slot named A:. The USRP1 and X3x0 have two daughterboard subdevice slots, known as A: and B:.
The B210 series have a different configuration, since their two radios are logically connected to the same "daughterboard" (which is in reality the integrated AD9361), but different frontends. To select both radios on a B200, use this string:
A:A A:B
Daughterboard frontend names can be used to specify which signal path is used from a daughterboard. Most daughterboards have only one frontend :0. A few daughterboards (Basic, LF and TVRX2) have multiple frontend names available. The frontend names are documented in Daughterboards.
When initializing a streamer using uhd::device::get_tx_stream() and/or uhd::device::get_rx_stream(), you must specify a uhd::stream_args_t object to configure the streamers. See the manual for this struct and an in-depth explanation of the individual components.
The uhd::stream_args_t object consists of four components:
cpu_format)otw_format)args)channels)The CPU data format is a string that describes the format of the sample data in host memory. When the client application calls recv() on an instance of uhd::rx_streamer or send() on an instance of uhd::tx_streamer, the samples are returned or expected to be provided in this format. The client application is free to choose whichever CPU data format best meets its particular needs.
Conversions for the following CPU formats have been implemented:
| String | Corresponding C++ type | Notes |
|---|---|---|
fc64 | std::complex<double> | Complex-valued double-precision data |
fc32 | std::complex<float> | Complex-valued single-precision data |
sc16 | std::complex<int16_t> | Complex-valued signed 16-bit integer data |
sc8 | std::complex<int8_t> | Complex-valued signed 8-bit integer data |
f32 | float | Single-precision data |
s16 | int16_t | Signed 16-bit integer data |
s8 | int8_t | Signed 8-bit integer data |
The over-the-wire (OTW) data format is a string that describes the format of the sample data as it is carried across the transport to and from the RFNoC stream endpoint associated with the stream. The following over-the-wire formats are supported. In the following, data carried over the wire for each format is denoted by the data type (i8, i16, etc.), which part of the sample is represented (I for in-phase portion, Q for quadrature portion, or R for a real value), and the sample index in square brackets.
sc16 i16 Q[n] | i16 I[n] | i16 Q[n+1] | i16 I[n+1] ... |
sc8 i8 Q[n+1] | i8 I[n+1] | i8 Q[n] | i8 I[n] | i8 Q[n+3] | i8 I[n+3] | i8 Q[n+2] | i8 I[n+2] | ... |
sc12 (only supported by some devices)s16 i16 R[n+1] | i16 R[n] | i16 R[n+3] | i16 R[n+2] | ... |
s8 i8 R[n+3] | i8 R[n+2] | i8 R[n+1] | i8 R[n] | i8 R[n+7] | i8 R[n+6] | ... |
Note that the in-tree RFNoC blocks that are provided with UHD only support sc16 for complex-valued data.
As UHD will convert samples between the CPU and over-the-wire data formats automatically, setting the OTW format should, in theory, be transparent to the application. However, changing the OTW format can have side effects. For example, using an OTW format with fewer bits (sc8 vs. sc16, for instance) reduces the load on the data link and allows more bandwidth, but also reduces the dynamic range of the data and increases quantization noise.
Additional implementation-dependent stream arguments may be provided as key/value pairs to a streamer via the args parameter. These settings control the behavior of the stream under various conditions. Note that the value specified for the key should be in string format, e.g.
The following parameters are supported:
spp: The spp (samples per packet) option controls the size of receive packets. When not specified, the packets are always the maximum frame size that can pass through the graph given the MTU (maximum transmission unit). Using a smaller value for spp may reduce packet latency through a graph.underflow_policy (applies to B100, B2xx and N2xx devices only): This option controls how the TX DSP should recover from an underflow condition. The following options are supported:next_burst: The DSP will drop incoming packets until a new burst has started.next_packet: The DSP will begin transmitting again upon reception of the next packet.wait: (B2xx and N2xx only) The DSP will not transmit until reset.fullscale: (applies to B100, B2xx and N2xx devices only) This option specifies the full-scale amplitude when using floats. By default, the fullscale amplitude with floating point values is 1.0. Clients can scale the samples on the host to the expected input and/or output range of their application by changing this value.peak: (applies to B100, B2xx and N2xx devices only) This option specifies a fractional sample level to calculate when scaling using the sc8 over-the-wire format. When using sc8 samples over the wire, samples must be scaled both on the host and in the device to satisfy dynamic range needs. The peak value specifies a fraction of the maximum sample level (1.0 = 100%). Set peak to the maximum sample level divided by the full scale level to ensure optimum dynamic range.noclear (applies to B100 and N2xx only)port and addr (N2xx only) These settings specify an alternate receiver streamer destination.streamer Specify the type of streamer to use. "replay_buffered" (applies to RFNoC enabled devices with a Replay block in the FPGA image) Adds data buffering in DRAM using the Replay block for TX streamers when using the multi_usrp API.throttle Specify the throttle of the streamer in order to limit its rate. This is for RFNoC-compatible devices starting in UHD 4.5. It is set as a ratio in the range (0, 1] or a percentage in the range (0%, 100%]. For example, use 100% or 1.0 for maximum rate, and 50% or 0.5 for half the maximum rate. Note that other factors may affect the actual rate, such as the rate of the source or the speed supported by the transport.The following arguments that alter the behavior of the underlying transport are normally passed to the USRP device as initialization-time arguments (see Device Configuration through address string):
num_send_framesnum_recv_framessend_frame_sizerecv_frame_sizesend_buff_sizerecv_buff_sizeHowever, for MPMD-based and X3x0 devices, these parameters may also be specified in the stream arguments. When one of these parameters is passed via the stream arguments, they override any value specified in the device arguments. See Transport Notes for more information on the meaning of these parameters and their default values.
The uhd::stream_args_t object allows the specification of a list of channel numbers mapping device channels to the stream. When left unset, the stream defaults to channel 0 (i.e., single-channel operation). For a multi- channel application, this list specifies the mapping of device channels to the data in the stream. Channel mapping also depends on the front-end selection (see also Specifying the Subdevice).
Consider an X300 with two daughterboards and a subdev spec of A:0 B:0. This means the device has two channels available. Here are some simple examples of channel mappings with subdev specs:
stream_args.channels = {0, 1} configures time-aligned streaming from both channels. The first channel in the stream will be mapped to first subdev spec (A:0) and the second channel will be mapped to the mapped to the second subdev spec (B:0).stream_args.channels = {1, 0}) results in the switching of the order of the channels in the stream. The first channel of the stream is mapped to the second subdev spec while the second channel of the stream is mapped to the first subdev spec.stream_args.channels = {1}), the stream will only consist of a single channel of data from the second subdev spec. When streaming a single channel from the B-side radio of a USRP, this is a more versatile solution than setting the subdev globally to B:0.For more detail on how MPM is configured, see also Configuring MPM.
The following key/value pairs are understood:
| Key | Description | Supported Devices | Example Value |
|---|---|---|---|
| enable_gps | Enable/disable power to the GPSDO (can be overridden by UHD on E320). | N3xx, E320 | enable_gps=0 |
| enable_fp_gpio | Enable/disable power to the front-panel GPIOs. | N3xx, E320 | enable_fp_gpio=0 |
| skip_boot_init | Don't init the device during MPM boot, but on the first UHD run. | N3xx | skip_boot_init=1 |
| clock_source | Default clock source for this device (can be overridden by UHD). | N3xx, E320, E31x | clock_source=external |
| time_source | Default time source for this device (can be overridden by UHD). | N3xx, E320, E31x | time_source=external |
| rx_lo_source | Default source for the RX LO (can be overridden by UHD). | N310 | rx_lo_source=external |
| tx_lo_source | Default source for the TX LO (can be overridden by UHD). | N310 | tx_lo_source=external |
| pps_export | Default PPS export value (can be overridden by UHD). | N3xx | pps_export=0 |
| forward_eth | Set forwarding policy for Ethernet packets | N3xx | forward_eth=1 |
| forward_bcast | Set forwarding policy for broadcast packets | N3xx | forward_bcast=1 |
| no_reload_fpga | Don't load an idle image after session terminates | E31x | no_reload_fpga=1 |
| master_clock_rate | Default master clock rate (can be overridden by UHD) | N3xx, E320, E31x | master_clock_rate=1e6 |
1.8.13