Difference between revisions of "Getting Started with UHD and C++"

From Ettus Knowledge Base
Jump to: navigation, search
(→‎UHD_SAFE_MAIN())
(→‎CMake)
 
(43 intermediate revisions by the same user not shown)
Line 8: Line 8:
 
!Details
 
!Details
 
|-
 
|-
−
|style="text-algin:center;"| 2016-05-01   
+
|style="text-align:center;"| 2016-05-01   
−
|style="text-algin:center;"| Neel Pandeya<br> Nate Temple  
+
|style="text-align:center;"| Neel Pandeya<br> Nate Temple  
−
|style="text-algin:center;"| Initial creation
+
|style="text-align:center;"| Initial creation
 
|}
 
|}
  
Line 20: Line 20:
  
 
==UHD Manual==
 
==UHD Manual==
−
 
+
The UHD Manual is hosted at [http://files.ettus.com/manual/index.html http://files.ettus.com/manual/index.html] and provides information on how to use the USRP devices and how to use the UHD API to connect to them through your own software. The manual is split into two parts: The device manual, and the UHD/API manual. The first part describes details of Ettus Research devices, motherboards and daughterboards, as well as aspects of using UHD. The second is meant for developers writing UHD-based applications, and includes descriptions of the API, sorted by namespaces, classes, and files.
−
==Doxygen Documentation==
+
  
 
==Including Header Files==
 
==Including Header Files==
Line 46: Line 45:
  
 
==set_thread_priority_safe()==
 
==set_thread_priority_safe()==
 +
Set the scheduling priority on the current thread. Same as set_thread_priority but does not throw on failure.
 +
 
<syntaxhighlight lang="c++">
 
<syntaxhighlight lang="c++">
 
     uhd::set_thread_priority_safe();
 
     uhd::set_thread_priority_safe();
Line 64: Line 65:
  
 
==Creating a USRP Object==
 
==Creating a USRP Object==
 +
Make a new multi usrp from the device address. 
 +
 
<syntaxhighlight lang="c++">
 
<syntaxhighlight lang="c++">
−
    //create a usrp device
 
−
    std::cout << std::endl;
 
−
    std::cout << boost::format("Creating the usrp device with: %s...") % device_args << std::endl;
 
 
     uhd::usrp::multi_usrp::sptr usrp = uhd::usrp::multi_usrp::make(device_args);
 
     uhd::usrp::multi_usrp::sptr usrp = uhd::usrp::multi_usrp::make(device_args);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==Setting Motherboard Clocks==
+
==Setting the Motherboard Clocks==
 +
Set the clock source for the usrp device. This sets the source for a 10 MHz reference clock. Typical options for source: internal, external, MIMO.
 +
 
 
<syntaxhighlight lang="c++">
 
<syntaxhighlight lang="c++">
−
    // Lock mboard clocks
+
     usrp->set_clock_source(ref)
−
    std::cout << boost::format("Lock mboard clocks: %f") % ref << std::endl;
+
−
     usrp->set_clock_source(ref);
+
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==Selecting Sub Device==
+
==Selecting the Sub Device==
 +
Set the RX frontend specification. The subdev spec maps a physical part of a daughter-board to a channel number. Set the subdev spec before calling into any methods with a channel number. The subdev spec must be the same size across all motherboards. For more details on selecting the Sub Device, see the [http://files.ettus.com/manual/page_configuration.html#config_subdev Specifying the Subdevice] section of the UHD Manual.
 +
 
 
<syntaxhighlight lang="c++">
 
<syntaxhighlight lang="c++">
−
    //always select the subdevice first, the channel mapping affects the other settings
+
     usrp->set_rx_subdev_spec(subdev)
−
    std::cout << boost::format("subdev set to: %f") % subdev << std::endl;
+
−
     usrp->set_rx_subdev_spec(subdev);
+
−
    std::cout << boost::format("Using Device: %s") % usrp->get_pp_string() << std::endl;
+
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==Setting Sample Rate==
+
==Getting the selected Sub Device==
 +
Get a printable summary for this USRP configuration.
 +
 
 
<syntaxhighlight lang="c++">
 
<syntaxhighlight lang="c++">
−
     //set the sample rate
+
     usrp->get_pp_string()
−
    if (rate <= 0.0) {
+
</syntaxhighlight>
−
        std::cerr << "Please specify a valid sample rate" << std::endl;
+
 
−
        return ~0;
+
==Setting the Sample Rate==
−
    }
+
Set the RX sample rate. The rate is in Samples Per Second.
  
−
    // set sample rate
+
<syntaxhighlight lang="c++">
−
    std::cout << boost::format("Setting RX Rate: %f Msps...") % (rate / 1e6) << std::endl;
+
     usrp->set_rx_rate(rate)
−
     usrp->set_rx_rate(rate);
+
</syntaxhighlight>
−
    std::cout << boost::format("Actual RX Rate: %f Msps...") % (usrp->get_rx_rate() / 1e6) << std::endl << std::endl;
+
 
 +
==Getting the Sample Rate==
 +
Gets the RX sample rate. Returns the rate is in Samples Per Second.
 +
 
 +
<syntaxhighlight lang="c++">
 +
    usrp->get_rx_rate()
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
==Setting Center Frequency==
 
==Setting Center Frequency==
 +
Create a tune request, with the RF frequency in Hz. Set the RX center frequency.
 +
 
<syntaxhighlight lang="c++">
 
<syntaxhighlight lang="c++">
−
    // set freq
+
     uhd::tune_request_t tune_request(freq)
−
    std::cout << boost::format("Setting RX Freq: %f MHz...") % (freq / 1e6) << std::endl;
+
     usrp->set_rx_freq(tune_request)
−
     uhd::tune_request_t tune_request(freq);
+
−
     usrp->set_rx_freq(tune_request);
+
−
    std::cout << boost::format("Actual RX Freq: %f MHz...") % (usrp->get_rx_freq() / 1e6) << std::endl << std::endl;
+
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==Setting RF Gain==
+
==Getting the Center Frequency==
 +
Get the RX center frequency. Returns the frequency in Hz.
 +
 
 
<syntaxhighlight lang="c++">
 
<syntaxhighlight lang="c++">
−
     // set the rf gain
+
     usrp->get_rx_freq()
−
    std::cout << boost::format("Setting RX Gain: %f dB...") % gain << std::endl;
+
−
    usrp->set_rx_gain(gain);
+
−
    std::cout << boost::format("Actual RX Gain: %f dB...") % usrp->get_rx_gain() << std::endl << std::endl;
+
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==Setting IF Filter Bandwidth==
+
==Setting the RF Gain==
 +
Set the RX gain value for the specified gain element. For an empty name, distribute across all gain elements. Sets the gain in dB.
 +
 
 
<syntaxhighlight lang="c++">
 
<syntaxhighlight lang="c++">
−
    // set the IF filter bandwidth
+
     usrp->set_rx_gain(gain)
−
    std::cout << boost::format("Setting RX Bandwidth: %f MHz...") % (bw / 1e6) << std::endl;
+
−
     usrp->set_rx_bandwidth(bw);
+
−
    std::cout << boost::format("Actual RX Bandwidth: %f MHz...") % (usrp->get_rx_bandwidth() / 1e6) << std::endl << std::endl;
+
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==Selecting Antenna==
+
==Reading the RF Gain==
 +
Get the RX gain value for the specified gain element. For an empty name, sum across all gain elements. Returns the gain in dB.
 
<syntaxhighlight lang="c++">
 
<syntaxhighlight lang="c++">
−
     std::cout << boost::format("Setting RX Antenna: %s") % ant << std::endl;
+
     usrp->get_rx_gain()
−
     usrp->set_rx_antenna(ant);
+
</syntaxhighlight>
−
    std::cout << boost::format("Actual RX Antenna: %s") % usrp->get_rx_antenna() << std::endl << std::endl;
+
 
 +
==Setting the IF Filter Bandwidth==
 +
Set the RX bandwidth on the frontend. Sets the bandwidth in Hz.
 +
 
 +
<syntaxhighlight lang="c++">
 +
    usrp->set_rx_bandwidth(bw)
 +
</syntaxhighlight>
 +
 
 +
==Getting the IF Filter Bandwidth==
 +
Get the RX bandwidth on the frontend. Returns the bandwidth in Hz.
 +
 
 +
<syntaxhighlight lang="c++">
 +
    usrp->get_rx_bandwidth()
 +
</syntaxhighlight>
 +
 
 +
==Selecting the Antenna==
 +
Select the RX antenna on the frontend.
 +
 
 +
<syntaxhighlight lang="c++">
 +
     usrp->set_rx_antenna(ant)
 +
</syntaxhighlight>
 +
 
 +
==Getting the Antenna==
 +
Get the selected RX antenna on the frontend. Returns the antenna name.
 +
 
 +
<syntaxhighlight lang="c++">
 +
    usrp->get_rx_antenna()
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 214: Line 244:
  
 
==CMake==
 
==CMake==
−
Use the uhd/host/examples/init_usrp/CMakeLists.txt file as template
+
Use the <syntaxhighlight lang="c++" enclose="none">uhd/host/examples/init_usrp/CMakeLists.txt</syntaxhighlight> file as template
−
- Add the names of your C++ source files to the add_executable(...) section
+
−
- Put both modified CMakeLists.txt file and C++ file into an empty folder
+
  
 +
* Add the names of your C++ source files to the add_executable(...) section
 +
* Put both modified CMakeLists.txt file and C++ file into an empty folder
 +
 +
[[File:uhd cpp makefile edits.png|650px]]
  
 
==Compile and Install==
 
==Compile and Install==
−
- Create a “build” folder and invoke CMake the usual way:  
+
* Create a “build” folder and invoke CMake the usual way:  
  
 
     mkdir build
 
     mkdir build
Line 226: Line 258:
 
     cmake ../
 
     cmake ../
 
     make
 
     make
−
 
  
 
==Running the Application==
 
==Running the Application==
−
[example output]
+
<pre>
 +
$ ./usrp_basic
 +
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.git-202-g9e0861e1
 +
 
 +
 
 +
Creating the usrp device with: addr=192.168.10.2...
 +
-- Opening a USRP2/N-Series device...
 +
-- Current recv frame size: 1472 bytes
 +
-- Current send frame size: 1472 bytes
 +
Lock mboard clocks: internal
 +
subdev set to: A:0
 +
Using Device: Single USRP:
 +
  Device: USRP2 / N-Series Device
 +
  Mboard 0: N210r4
 +
  RX Channel: 0
 +
    RX DSP: 0
 +
    RX Dboard: A
 +
    RX Subdev: WBXv2 RX+GDB
 +
  TX Channel: 0
 +
    TX DSP: 0
 +
    TX Dboard: A
 +
    TX Subdev: WBXv2 TX+GDB
 +
 
 +
Setting RX Rate: 1.000000 Msps...
 +
Actual RX Rate: 1.000000 Msps...
 +
 
 +
Setting RX Freq: 915.000000 MHz...
 +
Actual RX Freq: 915.000000 MHz...
 +
 
 +
Setting RX Gain: 10.000000 dB...
 +
Actual RX Gain: 10.000000 dB...
 +
 
 +
Setting RX Bandwidth: 1.000000 MHz...
 +
Actual RX Bandwidth: 1.000000 MHz...
 +
 
 +
Setting RX Antenna: TX/RX
 +
Actual RX Antenna: TX/RX
 +
</pre>
  
 
==Additional Example Programs==
 
==Additional Example Programs==
−
- Github UHD  
+
Additional C++ example programs using the UHD API are provided within the [https://github.com/EttusResearch/uhd/ Ettus Research Github Repository], located in the
 +
<syntaxhighlight lang="c++" enclose="none"> host/examples/ </syntaxhighlight> directory. These examples are installed with UHD and will be located at <syntaxhighlight lang="c++" enclose="none">$prefix/lib/uhd/examples </syntaxhighlight> directory of your system.
  
  

Latest revision as of 11:54, 10 August 2017

Application Note Number

AN-204

Revision History

Date Author Details
2016-05-01 Neel Pandeya
Nate Temple 		Initial creation

Abstract

This AN explains how to write and build C++ programs that use the UHD API.

Overview

This Application Note will walk through building a basic C++ program with UHD. This program will initialize, configure the USRP device, set the sample rate, frequency, gain, bandwidth, and select the antenna.

UHD Manual

The UHD Manual is hosted at http://files.ettus.com/manual/index.html and provides information on how to use the USRP devices and how to use the UHD API to connect to them through your own software. The manual is split into two parts: The device manual, and the UHD/API manual. The first part describes details of Ettus Research devices, motherboards and daughterboards, as well as aspects of using UHD. The second is meant for developers writing UHD-based applications, and includes descriptions of the API, sorted by namespaces, classes, and files.

Including Header Files

    #include <uhd/utils/thread_priority.hpp>
    #include <uhd/utils/safe_main.hpp>
    #include <uhd/usrp/multi_usrp.hpp>
    #include <uhd/exception.hpp>
    #include <uhd/types/tune_request.hpp>
    #include <boost/program_options.hpp>
    #include <boost/format.hpp>
    #include <boost/thread.hpp>
    #include <iostream>

UHD_SAFE_MAIN()

Defines a safe wrapper that places a catch-all around main. If an exception is thrown, it prints to stderr and returns. 

    int UHD_SAFE_MAIN(int argc, char *argv[]) {
        ...
    }

set_thread_priority_safe()

Set the scheduling priority on the current thread. Same as set_thread_priority but does not throw on failure. 

    uhd::set_thread_priority_safe();

Create Variables

    std::string device_args("addr=192.168.10.2");
    std::string subdev("A:0");
    std::string ant("TX/RX");
    std::string ref("internal");

    double rate(1e6);
    double freq(915e6);
    double gain(10);
    double bw(1e6);

Creating a USRP Object

Make a new multi usrp from the device address. 

    uhd::usrp::multi_usrp::sptr usrp = uhd::usrp::multi_usrp::make(device_args);

Setting the Motherboard Clocks

Set the clock source for the usrp device. This sets the source for a 10 MHz reference clock. Typical options for source: internal, external, MIMO. 

    usrp->set_clock_source(ref)

Selecting the Sub Device

Set the RX frontend specification. The subdev spec maps a physical part of a daughter-board to a channel number. Set the subdev spec before calling into any methods with a channel number. The subdev spec must be the same size across all motherboards. For more details on selecting the Sub Device, see the Specifying the Subdevice section of the UHD Manual. 

    usrp->set_rx_subdev_spec(subdev)

Getting the selected Sub Device

Get a printable summary for this USRP configuration. 

    usrp->get_pp_string()

Setting the Sample Rate

Set the RX sample rate. The rate is in Samples Per Second. 

    usrp->set_rx_rate(rate)

Getting the Sample Rate

Gets the RX sample rate. Returns the rate is in Samples Per Second. 

    usrp->get_rx_rate()

Setting Center Frequency

Create a tune request, with the RF frequency in Hz. Set the RX center frequency. 

    uhd::tune_request_t tune_request(freq)
    usrp->set_rx_freq(tune_request)

Getting the Center Frequency

Get the RX center frequency. Returns the frequency in Hz. 

    usrp->get_rx_freq()

Setting the RF Gain

Set the RX gain value for the specified gain element. For an empty name, distribute across all gain elements. Sets the gain in dB. 

    usrp->set_rx_gain(gain)

Reading the RF Gain

Get the RX gain value for the specified gain element. For an empty name, sum across all gain elements. Returns the gain in dB. 

    usrp->get_rx_gain()

Setting the IF Filter Bandwidth

Set the RX bandwidth on the frontend. Sets the bandwidth in Hz. 

    usrp->set_rx_bandwidth(bw)

Getting the IF Filter Bandwidth

Get the RX bandwidth on the frontend. Returns the bandwidth in Hz. 

    usrp->get_rx_bandwidth()

Selecting the Antenna

Select the RX antenna on the frontend. 

    usrp->set_rx_antenna(ant)

Getting the Antenna

Get the selected RX antenna on the frontend. Returns the antenna name. 

    usrp->get_rx_antenna()

Exiting

    return EXIT_SUCCESS;

Full Example

#include <uhd/utils/thread_priority.hpp>
#include <uhd/utils/safe_main.hpp>
#include <uhd/usrp/multi_usrp.hpp>
#include <uhd/exception.hpp>
#include <uhd/types/tune_request.hpp>
#include <boost/program_options.hpp>
#include <boost/format.hpp>
#include <boost/thread.hpp>
#include <iostream>

int UHD_SAFE_MAIN(int argc, char *argv[]) {
    uhd::set_thread_priority_safe();

    std::string device_args("addr=192.168.10.2");
    std::string subdev("A:0");
    std::string ant("TX/RX");
    std::string ref("internal");

    double rate(1e6);
    double freq(915e6);
    double gain(10);
    double bw(1e6);

    //create a usrp device
    std::cout << std::endl;
    std::cout << boost::format("Creating the usrp device with: %s...") % device_args << std::endl;
    uhd::usrp::multi_usrp::sptr usrp = uhd::usrp::multi_usrp::make(device_args);

    // Lock mboard clocks
    std::cout << boost::format("Lock mboard clocks: %f") % ref << std::endl;
    usrp->set_clock_source(ref);
    
    //always select the subdevice first, the channel mapping affects the other settings
    std::cout << boost::format("subdev set to: %f") % subdev << std::endl;
    usrp->set_rx_subdev_spec(subdev);
    std::cout << boost::format("Using Device: %s") % usrp->get_pp_string() << std::endl;

    //set the sample rate
    if (rate <= 0.0) {
        std::cerr << "Please specify a valid sample rate" << std::endl;
        return ~0;
    }

    // set sample rate
    std::cout << boost::format("Setting RX Rate: %f Msps...") % (rate / 1e6) << std::endl;
    usrp->set_rx_rate(rate);
    std::cout << boost::format("Actual RX Rate: %f Msps...") % (usrp->get_rx_rate() / 1e6) << std::endl << std::endl;

    // set freq
    std::cout << boost::format("Setting RX Freq: %f MHz...") % (freq / 1e6) << std::endl;
    uhd::tune_request_t tune_request(freq);
    usrp->set_rx_freq(tune_request);
    std::cout << boost::format("Actual RX Freq: %f MHz...") % (usrp->get_rx_freq() / 1e6) << std::endl << std::endl;

    // set the rf gain
    std::cout << boost::format("Setting RX Gain: %f dB...") % gain << std::endl;
    usrp->set_rx_gain(gain);
    std::cout << boost::format("Actual RX Gain: %f dB...") % usrp->get_rx_gain() << std::endl << std::endl;

    // set the IF filter bandwidth
    std::cout << boost::format("Setting RX Bandwidth: %f MHz...") % (bw / 1e6) << std::endl;
    usrp->set_rx_bandwidth(bw);
    std::cout << boost::format("Actual RX Bandwidth: %f MHz...") % (usrp->get_rx_bandwidth() / 1e6) << std::endl << std::endl;

    // set the antenna
    std::cout << boost::format("Setting RX Antenna: %s") % ant << std::endl;
    usrp->set_rx_antenna(ant);
    std::cout << boost::format("Actual RX Antenna: %s") % usrp->get_rx_antenna() << std::endl << std::endl;

    return EXIT_SUCCESS;
}


CMake

Use the uhd/host/examples/init_usrp/CMakeLists.txt file as template

  • Add the names of your C++ source files to the add_executable(...) section
  • Put both modified CMakeLists.txt file and C++ file into an empty folder

uhd cpp makefile edits.png

Compile and Install

  • Create a “build” folder and invoke CMake the usual way: 
   mkdir build
   cd build
   cmake ../
   make

Running the Application

$ ./usrp_basic
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.git-202-g9e0861e1


Creating the usrp device with: addr=192.168.10.2...
-- Opening a USRP2/N-Series device...
-- Current recv frame size: 1472 bytes
-- Current send frame size: 1472 bytes
Lock mboard clocks: internal
subdev set to: A:0
Using Device: Single USRP:
  Device: USRP2 / N-Series Device
  Mboard 0: N210r4
  RX Channel: 0
    RX DSP: 0
    RX Dboard: A
    RX Subdev: WBXv2 RX+GDB
  TX Channel: 0
    TX DSP: 0
    TX Dboard: A
    TX Subdev: WBXv2 TX+GDB

Setting RX Rate: 1.000000 Msps...
Actual RX Rate: 1.000000 Msps...

Setting RX Freq: 915.000000 MHz...
Actual RX Freq: 915.000000 MHz...

Setting RX Gain: 10.000000 dB...
Actual RX Gain: 10.000000 dB...

Setting RX Bandwidth: 1.000000 MHz...
Actual RX Bandwidth: 1.000000 MHz...

Setting RX Antenna: TX/RX
Actual RX Antenna: TX/RX

Additional Example Programs

Additional C++ example programs using the UHD API are provided within the Ettus Research Github Repository, located in the host/examples/ directory. These examples are installed with UHD and will be located at $prefix/lib/uhd/examples directory of your system.

Retrieved from "https://kb.ettus.com/index.php?title=Getting_Started_with_UHD_and_C%2B%2B&oldid=3560"