This is the GNU Radio UHD package. It is the interface to the UHD library to connect to and send and receive data between the Ettus Research, LLC product line. To use the UHD blocks, the Python namespaces is in gnuradio.uhd, which would be normally imported as:
The relevant blocks are listed in the UHD Interface group. The most important components are the gr::uhd::usrp_source and gr::uhd::usrp_sink blocks, which act as receivers/transmitters. Both are derived from gr::uhd::usrp_block, which defines many of the shared functions between those blocks.
Ettus Research maintains the comprehensive documentation to the underlying UHD driver, which can be found at:
The list of classes in the UHD Doxygen is located at:
The UHD sink and source can be controlled by a message port. These message ports take commands, which are PMTs formatted as described in Using messages as commands.
There is a legacy format, which will be deprecated in the future, where commands may be tuples, formatted as:
(command, value, [channel])
See older versions of this manual for documentation on this deprecated command format.
In general, every command consists of one or more key/value pairs (either stored as a PMT pair, or a dictionary). A full list of keys is listed below.
This PMT would set the frequency to 1.1 GHz on all channels. We make use of the pmt::mp() function which automatically sets the PMT types. Assume we only want to set the frequency on channel 1 (i.e. the second channel). In this case, we must construct a dictionary:
This command structure becomes more intuitive when thinking of sending the command PMT as a function call, where the key/value pairs are argument names and values, respectively. In the above example, the behaviour is the same as if calling
The main difference is that we can add more properties to the same command PMT, e.g. as such:
When the USRP block interprets this command PMT, all properties will be set.
The following command keys are understood by both UHD Source and Sink:
|Command name||Value Type||Description|
|int||Specifies a channel. If this is not given, either all channels are chosen, or channel 0, depending on the action. A value of -1 forces 'all channels', where possible.|
|double||Sets the Tx or Rx gain (in dB). Defaults to all channels.|
|double||Sets the Tx or Rx frequency. Defaults to all channels. If specified without |
|double||Sets an LO offset. Defaults to all channels. Note this does not affect the effective center frequency.|
|tune_request||Like freq, but sets a full tune request (i.e. center frequency and DSP offset). Defaults to all channels.|
|double||For fully manual tuning: Set the LO frequency (RF frequency). Conflicts with |
|double||For fully manual tuning: Set the DSP frequency (CORDIC frequency). Conflicts with |
|double||See usrp_block::set_samp_rate(). Always affects all channels.|
|double||See usrp_block::set_bandwidth(). Defaults to all channels.|
|timestamp||Sets a command time. See usrp_block::set_command_time(). A value of PMT_NIL will clear the command time.|
|int||Specify mboard index, where applicable.|
|string||See usrp_block::set_antenna(). Defaults to all channels.|
Note: Not all commands are affected by
time. See the UHD manual for details on timed commands.
Given the choices, it may be unclear if it's preferable to send multiple commands to the USRP block with a single key/value pair each, or send a single dict with all the values.
In general, the dictionary should be preferred. It has some distinct advantages:
A typical option parser setup for a UHD device looks like
To use these options to create a UHD source object:
Frequently, your application may need a sample rate that is not supported by the UHD device. If you have extra CPU power to spare, you can easily set the sample rate you want, then ask the device what the actual sample rate set was. Then, you can easily create an arbitrary resampler to take care of the difference.