General Application Notes

Table of Contents

• Tuning Notes
  • Two-stage tuning process
    • Tuning the receive chain:
  • RF front-end settling time
    • Pseudo-code for dealing with settling time after tuning on receive:
• Overflow/Underflow Notes
  • Overflow notes
  • Underrun notes
• Threading Notes
  • Thread safety notes
  • Thread priority scheduling
• Miscellaneous Notes
  • Support for dynamically loadable modules
  • Disabling or redirecting prints to stdout

Tuning Notes

Two-stage tuning process

A USRP device has two stages of tuning:

• RF front-end: translates bewteen RF and IF
• DSP: translates between IF and baseband

In a typical use-case, the user specifies an overall center frequency for the signal chain. The RF front-end will be tuned as close as possible to the center frequency, and the DSP will account for the error in tuning between target frequency and actual frequency. The user may also explicitly control both stages of tuning through through the uhd::tune_request_t object, which allows for more advanced tuning.

In general, Using UHD software's advanced tuning is highly recommended as it makes it easy to move the DC component out of your band-of-interest. This can be done by passing your desired LO offset to the uhd::tune_request_t object, and letting the UHD software handle the rest.

The uhd::tune_request_t object can also be used with certain daughterboards to use Integer-N tuning instead of the default fractional tuning, allowing for better spur performance. The daughterboards that support this functionality are:

• WBX (all revisions)
• WBX-120
• SBX (all revisions)
• SBX-120
• CBX
• CBX-120

Tuning the receive chain:

//tuning to a desired center frequency
usrp->set_rx_freq(target_frequency_in_hz);

--OR--

//advanced tuning with tune_request_t uhd::tune_request_t
tune_req(target_frequency_in_hz, desired_lo_offset);
tune_req.args = uhd::device_addr_t("mode_n=integer"); //to use Int-N tuning
//fill in any additional/optional tune request fields...
usrp->set_rx_freq(tune_req);

More information can be found in uhd::tune_request_t.

RF front-end settling time

After tuning, the RF front-end will need time to settle into a usable state. Typically, this means that the local oscillators must be given time to lock before streaming begins. Lock time is not consistent; it varies depending upon the device and requested settings. After tuning and before streaming, the user should wait for the lo_locked sensor to become true or sleep for a conservative amount of time (perhaps a second).

Pseudo-code for dealing with settling time after tuning on receive:

usrp->set_rx_freq(...);
sleep(1);
usrp->issue_stream_command(...);

--OR--

usrp->set_rx_freq(...);
while (not usrp->get_rx_sensor("lo_locked").to_bool()){
    //sleep for a short time in milliseconds
}
usrp->issue_stream_command(...);

Overflow/Underflow Notes

Note: The following overflow/underflow notes do not apply to USRP1, which does not support the advanced features available in newer products.

Overflow notes

When receiving, the device produces samples at a constant rate. Overflows occurs when the host does not consume data fast enough. When UHD software detects the overflow, it prints an "O" or "D" to stdout, and pushes an inline message packet into the receive stream.

Network-based devices: The host does not back-pressure the receive stream. When the kernel's socket buffer becomes full, it will drop subsequent packets. UHD software detects the overflow as a discontinuity in the packet's sequence numbers, and pushes an inline message packet into the receive stream. In this case the character "D" is printed to stdout as an indication.

Other devices: The host back-pressures the receive stream. Therefore, overflows always occur in the device itself. When the device's internal buffers become full, streaming is shut off, and an inline message packet is sent to the host. In this case the character "O" is printed to stdout as an indication. If the device was in continuous streaming mode, the UHD software will automatically restart streaming when the buffer has space again.

Underrun notes

When transmitting, the device consumes samples at a constant rate. Underflow occurs when the host does not produce data fast enough. When UHD software detects the underflow, it prints a "U" to stdout, and pushes a message packet into the async message stream.

Note: "O" and "U" message are generally harmless, and just mean the host machine can't keep up with the requested rates.

Threading Notes

Thread safety notes

For the most part, UHD software is thread-safe. Please observe the following limitations:

Fast-path thread requirements: There are three fast-path methods for a device: uhd::tx_streamer::send(), uhd::rx_streamer::recv(), and uhd::tx_streamer::recv_async_msg(). All three methods are thread-safe and can be called from different thread contexts. For performance, the user should call each method from a separate thread context. These methods can also be used in a non-blocking fashion by using a timeout of zero.

Slow-path thread requirements: It is safe to change multiple settings simultaneously. However, this could leave the settings for a device in an uncertain state. This is because changing one setting could have an impact on how a call affects other settings. Example: setting the channel mapping affects how the antennas are set. It is recommended to use at most one thread context for manipulating device settings.

Thread priority scheduling

When UHD software spawns a new thread, it may try to boost the thread's scheduling priority. If setting the new priority fails, the UHD software prints a warning to the console, as shown below. This warning is harmless; it simply means that the thread will retain a normal or default scheduling priority.

UHD Warning:
    Unable to set the thread priority. Performance may be negatively affected.
    Please see the general application notes in the manual for instructions.
    EnvironmentError: OSError: error in pthread_setschedparam

Linux Notes:

Non-privileged users need special permission to change the scheduling priority. Add the following line to the file /etc/security/limits.conf:

@GROUP    - rtprio    99

Replace GROUP with a group in which your user is a member. You may need to log out and log back into the account for the settings to take effect. In most Linux distributions, a list of groups and group members can be found in the file /etc/group.

Miscellaneous Notes

Support for dynamically loadable modules

For a module to be loaded at runtime, it must be:

• found in the UHD_MODULE_PATH environment variable,
• installed into the \<install-path\>/share/uhd/modules directory,
• or installed into /usr/share/uhd/modules directory (UNIX only).

Disabling or redirecting prints to stdout

The user can disable the UHD library from printing directly to stdout by registering a custom message handler. The handler will intercept all messages, which can be dropped or redirected. Only one handler can be registered at a time. Make register_handler your first call into the UHD library:

#include <uhd/utils/msg.hpp>

void my_handler(uhd::msg::type_t type, const std::string &msg){
//handle the message...
}

uhd::msg::register_handler(&my_handler);