Ettus Knowledge Base - User contributions [en]

Getting Started with DPDK and UHD

2026-06-25T09:30:11Z

MartinAnderseck: Added X420 to the list of DPDK supported USRPs

== Application Note Number and Authors ==

'''AN-500''' by Nate Temple, Alex Williams, Wade Fife, Matt Prost, and Michael Dickens


==Overview==

This application note walks through the process to get started with the Data Plane Development Kit (DPDK) driver within UHD.

==Abstract==

Up until now, UHD's only support for networked devices was backed by the kernel's sockets implementation. Every call to <code>send()</code> or <code>recv()</code> would cause a context switch and invite the kernel's scheduler to replace our thread with something else. Because the typical scheduler is optimized to distribute CPU time fairly across multiple loads, the timing-critical threads might sporadically be hit with sleeping time, and the thread might be migrated off its current CPU and forced to run on another. The overhead and random latency spikes make it difficult to enable reliable real-time streaming at higher rates.

DPDK is a high-speed packet processing framework that enables a kernel bypass for network drivers. By putting the entire driver in user space, avoiding context switches, and pinning I/O threads to cores, UHD and DPDK combine to largely prevent the latency spikes induced by the scheduler. In addition, the overall overhead for packet processing lowers.

== Supported Devices ==

=== USRPs ===

DPDK is supported on the following USRP devices:

* E320
* N300 / N310
* N320 / N321
* X300 / X310
* X410
* X420
* X440

=== Host Network Cards ===

DPDK is supported on many Intel and Mellanox based 10Gb and 100Gb NICs and lots of other NICs. Below is a list of NICs Ettus Research has tested. For a full list of NICs supported by DPDK, please see the DPDK manual.

* Intel X520-DA1 (1x10Gb)
* Intel X520-DA2 (2x10Gb)
* Intel X710-DA2 (2x10Gb)
* Intel X710-DA4 (4x10Gb)
* Intel XL710-QDA2 (2x40Gb breakout to 4x10Gb)
* Intel E810-CQDA1 (1x100Gb and 1x4x10Gb)
* Intel E810-CQDA2 (1x100Gb and 2x4x10Gb; [https://edc.intel.com/content/www/us/en/design/products/ethernet/perf-tuning-guide-800-series-linux/%E2%80%8Bcheck-system-hardware-capabilities/ note that this NIC does not support 2x100Gb])
* Intel E810-2CQDA2 (1x100Gb and 2x4x10Gb; 2x100Gb with some work)
* Mellanox MCX4121A-ACAT ConnectX-4 Lx (2x10Gb)
* Mellanox MCX515A-CCAT ConnectX-5 EN (2x100Gb or 2x10Gb)
* Mellanox MCX516A-CCAT ConnectX-5 EN (2x100Gb or 2x10Gb)
* Mellanox MCX516A-CDAT ConnectX-5 Ex EN (2x100Gb or 2x10Gb)
* Mellanox MCX623106AN-CDAT ConnectX-6 Dx EN (2x100Gb or 2x10Gb)
* [https://www.ni.com/en-us/support/model.100-gb-ethernet-connectivity-kit.html NI Dual 100 Gigabit Ethernet PCIe Interface Kit (PN 788216-01)]

== References ==

* DPDK: https://www.dpdk.org/
** https://doc.dpdk.org/guides-17.11
** https://doc.dpdk.org/guides-18.11
** https://doc.dpdk.org/guides-19.11
** https://doc.dpdk.org/guides-20.11
** https://doc.dpdk.org/guides-21.11
** https://doc.dpdk.org/guides-22.11
** https://doc.dpdk.org/guides-23.11
** https://doc.dpdk.org/guides-24.11
* UHD Manual: https://files.ettus.com/manual/page_dpdk.html

== Dependencies ==

* UHD 3.x requires DPDK 17.11

* UHD 4.0 and 4.1 require DPDK 18.11

* UHD 4.2 to 4.7 can use any version of DPDK from 18.11 to 21.11

* UHD 4.8 to 4.9 can use any version of DPDK from 18.11 to 24.11

== Installing DPDK ==

We recommend installing DPDK via the system-provided installer; for example with Ubuntu:

sudo apt install dpdk dpdk-dev

While it is possible to install DPDK from source, we recommend using the system-provided install unless there is a very good reason to not do so. DPDK can be challenging to ''correctly'' build from source though more recent versions use meson and ninja along with default settings needed by UHD and hence are relatively simple to build and install. If you require installing DPDK from source, the install guide for various versions is noted below:

* [https://doc.dpdk.org/guides-17.11/linux_gsg/build_dpdk.html DPDK 17.11]
* [https://doc.dpdk.org/guides-18.11/linux_gsg/build_dpdk.html DPDK 18.11]
* [https://doc.dpdk.org/guides-19.11/linux_gsg/build_dpdk.html DPDK 19.11]
* [https://doc.dpdk.org/guides-20.11/linux_gsg/build_dpdk.html DPDK 20.11]
* [https://doc.dpdk.org/guides-21.11/linux_gsg/build_dpdk.html DPDK 21.11]
* [https://doc.dpdk.org/guides-22.11/linux_gsg/build_dpdk.html DPDK 22.11]
* [https://doc.dpdk.org/guides-23.11/linux_gsg/build_dpdk.html DPDK 23.11]
* [https://doc.dpdk.org/guides-24.11/linux_gsg/build_dpdk.html DPDK 24.11]

DPDK releases come three times per year in April (version X.04), July (version X.07), and November (version X.11). The X.11 version is more of a formal release. While any ''can'' be used with UHD, we recommend using just the formal releases.

NOTE: It is sometimes necessary to use NIC device drivers because of improved feature sets or just getting a NIC to work; the system provided NIC drivers are too old. In this case: (1) remove the system provided DPDK and DPDK-DEV and whatever UHD install is in use; you will need to build these from source. (2) Download and install the new NIC drivers, NVM, and anything else that the NIC needs to be updated to the version needed. (3) Download and install DPDK from source. (4) Downlaod and install UHD from source.

== Installing UHD ==

Once the <code>dpdk</code> and <code>dpdk-dev</code> packages are installed, UHD will locate them during a build and you should see DPDK in the enabled components lists when running <code>cmake</code>.

NOTE that in general UHD installed from PPA or system packages ''does not'' include support for DPDK, and even if DPDK is installed alongside these UHD it will not be used. In order to get UHD with DPDK support, [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux UHD generally has to be built from source].

== Enable hugepages ==

Edit your grub configuration file, <code>/etc/default/grub</code> and add the follow parameters to <code>GRUB_CMDLINE_LINUX_DEFAULT</code>:

iommu=pt intel_iommu=on hugepages=2048

On a vanilla Ubuntu system it should look like this:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash iommu=pt intel_iommu=on hugepages=2048"

Close <code>/etc/default/grub</code> and at the command prompt, update your grub configuration with the command:

sudo update-grub

For these settings to take effect, reboot your host machine.

== Preparing your UHD Configuration File ==

You must note the MAC addresses for your NICs before proceeding.

The MAC addresses for your NICs can be found by running the command:

ip a

You must then create a UHD configuration file.

For UHD 3 the location is <code>/root/.uhd/uhd.conf</code>.

sudo su
mkdir -p /root/.uhd
nano /root/.uhd/uhd.conf

For UHD 4 the location is <code>/root/.config/uhd.conf</code>.

sudo su
mkdir -p /root/.config
nano /root/.config/uhd.conf

=== UHD 3.x ===

An example <code>uhd.conf</code> file is listed below. Note that field names in UHD 3.x are slightly different from UHD 4.0.

You should update the following fields for your configuration from this example:

* Update the MAC address variables, <code>dpdk-mac</code>, to match your NIC

* Update the <code>dpdk-driver</code> if the location is different on your system. <code>/usr/lib/x86_64-linux-gnu/dpdk-17.11-drivers/</code> is the default location on Ubuntu 18.04.x when <code>dpdk</code> is installed via <code>apt</code>.

* Update the <code>dpdk-corelist</code> and <code>dpdk-io-cpu</code> fields. In this example, a two port NIC is used. There should be one core for the main <code>dpdk</code> thread (in this example <code>core #2</code>), and then separate cores assigned to each NIC (in this example <code>core #3</code> for the first port on the NIC, <code>core #4</code> for the second port on the NIC)

* Update the <code>dpdk-ipv4</code> fields to your desired IP range.
** <code>192.168.30.2</code>, <code>192.168.40.2</code> on a default X3xx system
** <code>192.168.10.2</code>, <code>192.168.20.2</code> on a default N3xx system
** <code>192.168.10.2</code> on a default E320 system

[use_dpdk=1]
dpdk-mtu=9000
dpdk-driver=/usr/lib/x86_64-linux-gnu/dpdk-17.11-drivers/
dpdk-corelist=2,3,4
dpdk-num-mbufs=4095
dpdk-mbufs-cache-size=315

[dpdk-mac=aa:bb:cc:dd:ee:f1]
dpdk-io-cpu = 3
dpdk-ipv4 = 192.168.10.1/24

[dpdk-mac=aa:bb:cc:dd:ee:f2]
dpdk-io-cpu = 4
dpdk-ipv4 = 192.168.20.1/24

'''Note:''' Additional information on the UHD configuration file can be found here: https://files.ettus.com/manual_archive/v3.15.0.0/html/page_dpdk.html#dpdk_nic_config

=== UHD 4.x ===

An example <code>uhd.conf</code> file is listed below. Note that the field names in UHD 4.x are slightly different from UHD 3.x.

You must verify and/or update the following fields for your configuration from this example:

* The MAC address variables, <code>dpdk_mac</code>, to match your NIC(s) link(s); note that the MAC address info ''must be lowercase''

* The <code>dpdk_driver</code> if the location is different on your system. <code>/usr/local/lib/</code> is the default location on when DPDK is built and installed from source.

* The <code>dpdk_corelist</code> and <code>dpdk_lcore</code> fields. In this example, a two port NIC and both links are used. There must be one core for the main <code>dpdk</code> thread (in this example <code>core #2</code> because it is not otherwise used in the file) and then separate cores assigned to each NIC link (in this example <code>core #3</code> for the one of the NIC links and <code>core #4</code> for the other NIC link).

* The <code>dpdk_ipv4</code> fields to your desired IP range(s).
** <code>192.168.30.2</code>, <code>192.168.40.2</code> on a default X3xx system
** <code>192.168.10.2</code>, <code>192.168.20.2</code> on a default N3xx system
** <code>192.168.10.2</code> on a default E320 system
** <code>192.168.10.2</code> and <code>192.168.20.2</code> on a default X4xx systems

[use_dpdk=1]
dpdk_mtu=9000
dpdk_driver=/usr/lib/x86_64-linux-gnu/dpdk/pmds-20.0/
dpdk_corelist=2,3,4
dpdk_num_mbufs=4096
dpdk_num_desc=4096
dpdk_mbuf_cache_size=315

[dpdk_mac=aa:bb:cc:dd:ee:f1]
dpdk_lcore=3
dpdk_ipv4=192.168.10.1/24

[dpdk_mac=aa:bb:cc:dd:ee:f2]
dpdk_lcore=4
dpdk_ipv4=192.168.20.1/24

'''Notes:'''
* Additional information on the [https://files.ettus.com/manual/page_dpdk.html#dpdk_nic_config UHD DPDK configuration file is in the UHD manual].
* The number of cores listed must be used exactly within the file.
* The number of NIC link(s) listed must exactly match those specified in the UHD instantiation args.
* A simple way to move between different DPDK configurations is to create different files and then symlink from the desired file to <code>uhd.conf</code>

== Additional Host Configuration for NIC Vendors ==

The process for this step is different for Intel and Mellanox NICs and is detailed in individual sections below.

=== Intel X520 / X710 ===

The Intel based NICs will use the <code>vfio-pci</code> driver which must be loaded:

sudo modprobe vfio-pci

Next, you will need to rebind the NIC to the <code>vfio-pci</code> drivers.

First, identify the PCI address your NIC is at via the following command, noting that for older DPDK the command does not contain the trailing <code>.py</code>

dpdk-devbind.py -s

Note the PCI address that your NIC is connected to for the next step.

Before the next step, you will need to turn off the NIC first before doing the rebind.

In Ubuntu under <code>System</code> -> <code>Network</code> -> click the switches to <code>off</code> for the 10Gb ports, then run the <code>dpdk-devbind</code> commands:

'''Note:''' Your PCI address will likely be different than <code>02:00.0</code> as shown in the example below.

sudo dpdk-devbind.py --bind=vfio-pci 02:00.0
sudo dpdk-devbind.py --bind=vfio-pci 02:00.1

You should now see the NICs listed under DPDK devices

# dpdk-devbind.py -s

Network devices using DPDK-compatible driver
============================================
0000:02:00.0 '82599ES 10-Gigabit SFI/SFP+ Network Connection 10fb' drv=vfio-pci unused=ixgbe
0000:02:00.1 '82599ES 10-Gigabit SFI/SFP+ Network Connection 10fb' drv=vfio-pci unused=ixgbe

'''Note:''' More info can be found here on the rebinding process: https://doc.dpdk.org/guides-24.11/linux_gsg/linux_drivers.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules

=== Mellanox NICs ===

The NVIDIA Mellanox ("Mellanox") NICs do ''not'' require rebinding using the <code>vfio-pci</code> driver. Mellanox provides system IC drivers and additional drivers for DPDK to handle the binding to and from VFIO-PCI. In general the Mellanox system-provided NIC and DPDK drivers should work and you should not need to install Mellanox drivers.

If for some reason your host OS does not provide Mellanox DPDK drivers, then these can be installed manually. For example:

sudo apt install librte-pmd-mlx5
sudo modprobe -a ib_uverbs mlx5_core mlx5_ib

If for some reason you are running into issues using a Mellanox NIC, then you can [https://network.nvidia.com/products/infiniband-drivers/linux/mlnx_ofed/ download and install the latest Mellanox drivers from the Mellanox website] (https://network.nvidia.com/products/infiniband-drivers/linux/mlnx_ofed/).

The MLX5 poll mode driver library (librte_pmd_mlx5) in DPDK provides support for Mellanox ConnextX-4 through -7 NICs. For DPDK 20 and older only this driver must be enabled manually with the build option <code>CONFIG_RTE_LIBRTE_MLX5_PMD=y</code> when building DPDK. We recommend DPDK 21 and newer when possible; these versions are easy to build from source using <code>meson</code> and <code>ninja</code>.

== Running UHD Applications with DPDK ==

UHD based application (including GNU Radio flowgraphs) can now be ran using a DPDK transport by passing in the Device Argument: <code>use_dpdk=1</code>.

'''Important Note:''' In order for UHD to use DPDK, the UHD application ''must'' be ran as the <code>root</code> user; this can be done either by prepending <code>sudo</code> to the command or becoming the roort user via <code>sudo su</code>.

For example, running the <code>benchmark_rate</code> utility after issuing <code>sudo su</code> (one can also run this command simply as <code>sudo /usr/local/lib/uhd/examples/benchmark_rate ....</code>:

<pre>
# cd /usr/local/lib/uhd/examples

# ./benchmark_rate --rx_rate 125e6 --rx_subdev "A:0 B:0" --rx_channels 0,1 --tx_rate 125e6 --tx_subdev "A:0 B:0" --tx_channels 0,1 --args "addr=192.168.10.2,second_addr=192.168.20.2,mgmt_addr=10.2.1.19,master_clock_rate=125e6,use_dpdk=1"

[INFO] [UHD] linux; GNU C++ version 7.3.0; Boost_106501; UHD_3.14.0.HEAD-0-gabf0db4e
EAL: Detected 8 lcore(s)
EAL: Some devices want iova as va but pa will be used because.. EAL: IOMMU does not support IOVA as VA
EAL: No free hugepages reported in hugepages-1048576kB
EAL: Probing VFIO support...
EAL: VFIO support initialized
EAL: PCI device 0000:02:00.0 on NUMA socket -1
EAL: Invalid NUMA socket, default to 0
EAL: probe driver: 8086:10fb net_ixgbe
EAL: using IOMMU type 1 (Type 1)
EAL: Ignore mapping IO port bar(2)
EAL: PCI device 0000:02:00.1 on NUMA socket -1
EAL: Invalid NUMA socket, default to 0
EAL: probe driver: 8086:10fb net_ixgbe
EAL: Ignore mapping IO port bar(2)
PMD: ixgbe_dev_link_status_print(): Port 0: Link Down
EAL: Port 0 MAC: aa bb cc dd ee f1
EAL: Port 0 UP: 1
PMD: ixgbe_dev_link_status_print(): Port 1: Link Down
EAL: Port 1 MAC: aa bb cc dd ee f2
EAL: Port 1 UP: 1
EAL: Init DONE!
EAL: Starting I/O threads!
USER2: Thread 1 started
[00:00:00.000003] Creating the usrp device with: addr=192.168.10.2,second_addr=192.168.20.2,mgmt_addr=10.2.1.19,master_clock_rate=125e6,use_dpdk=1...
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=10.2.1.19,type=n3xx,product=n310,serial=313ABDA,claimed=False,addr=192.168.10.2,second_addr=192.168.20.2,master_clock_rate=125e6,use_dpdk=1
[INFO] [MPM.PeriphManager] init() called with device args 'product=n310,time_source=internal,master_clock_rate=125e6,clock_source=internal,use_dpdk=1,second_addr=192.168.20.2,mgmt_addr=10.2.1.19'.
[INFO] [0/DmaFIFO_0] Initializing block control (NOC ID: 0xF1F0D00000000004)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1344 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1341 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1348 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1347 MB/s)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000011312)
[INFO] [0/Radio_1] Initializing block control (NOC ID: 0x12AD100000011312)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000000)
[INFO] [0/DDC_1] Initializing block control (NOC ID: 0xDDC0000000000000)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000002)
[INFO] [0/DUC_1] Initializing block control (NOC ID: 0xD0C0000000000002)
Using Device: Single USRP:
Device: N300-Series Device
Mboard 0: ni-n3xx-313ABDA
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: Magnesium
RX Channel: 1
RX DSP: 0
RX Dboard: B
RX Subdev: Magnesium
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: Magnesium
TX Channel: 1
TX DSP: 0
TX Dboard: B
TX Subdev: Magnesium

[00:00:03.728707] Setting device timestamp to 0...
[INFO] [MULTI_USRP] 1) catch time transition at pps edge
[INFO] [MULTI_USRP] 2) set times next pps (synchronously)
[00:00:05.331920] Testing receive rate 125.000000 Msps on 2 channels
[00:00:05.610789] Testing transmit rate 125.000000 Msps on 2 channels
[00:00:15.878071] Benchmark complete.

Benchmark rate summary:
Num received samples: 2557247854
Num dropped samples: 0
Num overruns detected: 0
Num transmitted samples: 2504266704
Num sequence errors (Tx): 0
Num sequence errors (Rx): 0
Num underruns detected: 0
Num late commands: 0
Num timeouts (Tx): 0
Num timeouts (Rx): 0

Done!
</pre>

== Tuning Notes ==

=== General Host Performance Tuning App Note ===

Perform the [https://kb.ettus.com/USRP_Host_Performance_Tuning_Tips_and_Tricks general host performance tuning tips and tricks].

=== Increasing <code>num_recv_frames</code> ===

If you experience <code>Overflows</code> at higher data rates, adding the device argument <code>num_recv_frames=512</code> can help.

=== Full Rate Streaming (UHD 3.x only) ===

If you're streaming data at the full master clock rate, and there is no interpolation or decimation being performed on the FPGA, you can skip the DUC and DDC blocks within the FPGA with the following parameters:

skip_ddc=1
skip_duc=1

=== Full Rate on X3xx ===

If you're streaming two transmit channels at full rate (200e6) on the X3xx platform, you should additionally set the following device arg:

enable_tx_dual_eth=1

=== Isolate Cores/CPUs ===

Isolating the cores that are used for DPDK can improve performance. This can be done by adding the <code>isolcpus</code> parameter to your <code>/etc/default/grub</code> file in the <code>GRUB_CMDLINE_LINUX_DEFAULT=""</code> (the "<code>GRUB_CONFIG</code>"). For example, to isolate cores 2 through and including 4, add this entry:

isolcpus=2-4

NOTE: After saving the <code>GRUB_CONFIG</code> file, execute <code>sudo update-grub</code> and then reboot the computer for the changes to take effect. It is OK to isolate core used by DPDK via this method.

=== Disable System Interrupts on Cores/CPUs ===

Disabling system interrupts can improve the jitter and performance generally by 1-3%. This can be done by adding the parameters <code>nohz_full</code> and <code>rcu_nocbs</code> to your <code>GRUB_CONFIG</code>. For example, to disable system interrupts on cores 2 through and including 4, add this entry:

nohz_full=2-4 rcu_nocbs=2-4

NOTE: After saving the <code>GRUB_CONFIG</code> file, execute <code>sudo update-grub</code> and then reboot the computer for the changes to take effect. It is OK to isolate core used by DPDK via this method.

=== Streaming on Multiple Channels using 1 Thread Per Stream ===

If you're streaming on multiple channels simultaneously, you can create multiple streamer objects on separate threads. This can be accomplished with the <code>benchmark_rate</code> example by using the parameter <code>--multi_streamer</code>.

=== Elevated Streaming Thread Priority ===

In UHD 4, streaming thread priorities can be elevated with the <code>uhd::set_thread_priority_safe()</code> function call. This can be accomplished with the <code>benchmark_rate</code> example by using parameter <code>--priority high</code>. Note that if the [https://kb.ettus.com/USRP_Host_Performance_Tuning_Tips_and_Tricks#Thread_Priority_Scheduling Thread Schedule Priority] has not been enabled for the current user then this parameter requires <code>sudo</code> to work.

=== Extra <code>nice</code> Priority ===

Beyond elevating streaming thread priority, one can also increase the [https://www.man7.org/linux/man-pages/man1/nice.1.html <code>nice</code> priority level] to maximum to increase the amount of CPU time for the process and its thread by prepending the following to the command being issued:

sudo nice -n -20

=== Limit Execution CPUs/Cores ===

With Linux one can limit the cores being used by the threads in a process via a [https://man7.org/linux/man-pages/man1/taskset.1.html <code>taskset</code>] prepended to a command being executed. When combining with the other techniques listed here, one can fairly well constrain a process and its thread to specific cores and give them maximum CPU time. Note that when using DPDK the MAC cores specified in <code>uhd.conf</code> will already be included as part of the <code>taskset</code> (but those cores will not be isolated nor have system interrupts disabled on them unless using that setting as noted above); it generally won't hurt to include the DPDK cores as part of the overall <code>taskset</code> but it's not required. For example, to limit process/thread execution to cores 2 through and including 4, one would prepend the following (note that <code>sudo</code> is ''not'' required):

taskset -c "2-4"

NOTE: For best performance do ''not'' include the cores used by DPDK in the <code>dpdk_corelist</code> argument in the <code>taskset</code>.

=== Stopping Extraneous Processes ===

The Linux kernel spawns a number of processes and threads that spend most of their time sleeping; one cannot stop these processes/threads. That said, in a typical Linux install (for example Ubuntu) there will be a graphical desktop (e.g., <code>gdm</code>) and various daemons started up by user request (e.g., <code>containerd</code>, <code>docker</code>, <code>snapd</code>). Most of these daemons can be controlled by <code>systemctl</code>; some must be manually quit. Any process that runs regularly stands a chance of interrupting the UHD and DPDK threads, and thus stopping, quitting, or disabling those processes can increase performance. For example, the following commands stop various daemons that execute regularly on Ubuntu; these need to be executed with <code>sudo</code> and some might not exist on your specific system and for these the command will do nothing so it's OK to run it:

systemctl stop containerd containerd.socket
systemctl stop docker docker.socket
systemctl stop dbus dbus.socket
systemctl stop snapd snapd.socket
systemctl stop udev systemd-udevd-control.socket systemd-udevd-kernel.socket

The following command stops the main Ubuntu desktop GUI, so running it will render the system accessible only via networking (e.g., <code>ssh</code>), so make sure network access is enabled before executing this command:

systemctl stop gdm

=== Disable Hyper-threading ===

In some applications which require the highest possible CPU performance per core, disabling hyper-threading can provide roughly a 10% increase in core performance, at the cost of having fewer core threads. Hyper-threading is disabled within the BIOS and how to do this varies by motherboard manufacturer. With other techniques listed here, disabling hyper-threading should only be done as a last resort to eek absolute maximum performance from the CPU.

=== Additional Tuning Notes from Intel ===

* Performance report from Intel on DPDK 17.11: https://fast.dpdk.org/doc/perf/DPDK_17_11_Intel_NIC_performance_report.pdf
* How to get best performance with NICs on Intel platforms: https://doc.dpdk.org/guides/linux_gsg/nic_perf_intel_platform.html

== Known Issues / Troubleshooting ==

=== Regular Overflows on multi-CPU Systems ===

On Multi-CPU systems each CPU is a NUMA node. The NUMA node contains all of the cores on the CPU. For best performance when using CPU/core isolation ("isocpus" per AAA above) make sure that all of the cores are in the same NUMA node.

=== Underruns Every Second with DPDK + Ubuntu ===

With Linux kernels 5.10 and beyond, we have observed periodic underruns on systems that otherwise have no issues. These Linux kernel versions are the default for Ubuntu 20.04.3 LTS and later. The underrun issue is due to the <code>RT_RUNTIME_SHARE</code> feature being disabled by default in these versions of the Linux kernel (shown as <code>NO_RT_RUNTIME_SHARE</code>). The following procedure can be used to enable this feature. This process was tested on Linux kernel version 5.13; the procedure may be slightly different on other kernel versions. To determine the Linux kernel version of your system, in a terminal issue the command <code>uname -r</code>.

<pre>
$ sudo -s
$ cd /sys/kernel/debug/sched
$ cat features | tr ' ' '\n' | grep RUNTIME_SHARE
NO_RT_RUNTIME_SHARE
$ echo RT_RUNTIME_SHARE > features
$ cat features | tr ' ' '\n' | grep RUNTIME_SHARE
RT_RUNTIME_SHARE
</pre>

[[Category:Application Notes]]

About Sampling Rates and Master Clock Rates for the USRP X440

2026-04-30T10:46:57Z

MartinAnderseck: Added new rates after UHD 4.10 release.

== Application Note Number and Authors ==

'''AN-055''' by Marian Koop and Martin Anderseck



= Overview =
This application note guides users through the selection process of Master Clock Rates (MCR) for the [https://kb.ettus.com/X440#X440 USRP X440]. It will highlight possible implications and side effects as well as design specific differences to other USRPs (like the X410).


= USRP X440 Configuration Considerations =
The USRP X440 is a [https://uhd.readthedocs.io/en/latest/page_fbx.html#fbx_too balun-coupled transceiver] without built-in RF signal conditioning. Compared to other RF architectures this enables the USRP X440 to access the full RF bandwidth available to the ADC/DAC, but also requires additional frequency planning. To achieve this, the USRP X440 utilizes its ADC/DAC in direct sampling mode and is susceptible to various effects that may distort the signal of interest. These can be separated into distortions from both signal processing and from the ADC/DAC design.


== Relationship between RF-ADC/DAC Converter Rate, USRP Master Clock Rate (MCR), Data IQ rate ==
Except for the 200 MHz variant, the default USRP X440 FPGA images do not contain a configurable DDC<ref>Digital Down Conversion</ref>/DUC<ref>Digital Up Conversion</ref> block. This means that the IQ sample rate (FIQ) is the same as the Master Clock Rate (MCR) that goes into the RFNoC Radio block. However, unlike most other USRPs the USRP X440 supports a highly variable MCR. The RF Data Converter sampling rate (FS) is chosen by UHD based on the MCR and the available resampling factors of 2, 4, or 8, and defaults to the highest achievable values with these factors. This can be overridden if the desired MCR can be achieved with multiple converter rates (see device argument [https://uhd.readthedocs.io/en/latest/page_usrp_x4xx.html#x4xx_usage_args converter_rate]). The inverse calculation - divide the converter rate by 8, 4 or 2 - has to be done to derive the master clock rate if a specific converter rate shall be used. Figure 1 depicts the simplified signal path block diagram for the USRP X440.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 1. Simplified USRP X440 Signal Path
|-
| style="border-style: none;" | [[File:ANxxx-X440_signal_path.jpg|450px|center]]
|}


== Aliases and Nyquist Zones ==
By itself the USRP X440 can sample input signals at frequencies above the Nyquist frequency<ref>[https://en.wikipedia.org/wiki/Nyquist_frequency Nyquist frequency]</ref>, which is half of the ADC converter sampling rate (FS). However, this method introduces aliasing effects, which cause unwanted signals to appear as mirror images around multiples of the Nyquist frequency (FS/2) in the output spectrum. The first Nyquist zone (N1) is the frequency range from 0 to FS/2, and the second Nyquist zone (N2) goes from FS/2 to FS. Other Nyquist zones are numbered in ascending order, each spanning FS/2. The digital passband in each Nyquist zone can be calculated as 0.4 * FS (see also <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/RF-ADC-Decimation-Filters-Gen-1/Gen-2 Xilinx RF-ADC Decimation Filters (Gen-1)]</ref>). The following figure depicts the Nyquist zones for the minimum and maximum RF-ADC converter rates supported by the USRP X440. Note that the illustrations do not show the effects of external, analog filters on the achievable passband within a Nyquist zone. A typical expectation is, that the unusable frequency range around each Nyquist zone boundary (also often referred to as a guard band) increases with ascending Nyquist zone order and results in decreasing, lopsided achievable passbands.
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 2. Nyquist Zones
|-
| style="border-style: none;" | [[File:ANxxx-X440_nyquist_zones.jpg|450px|center]]
|}

Knowledge of signal aliases can both be exploited and create uncertainties. Applications could utilize intentional under sampling (also referred as "bandpass sampling") to receive signals at greater than FS/2. The same effect may on the other hand lead to garbled or distorted signal detection if the signal of interest spans multiple Nyquist zones or interferer signals are aliased into the observed spectrum. Both effects are depicted in figure 3.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 3. Aliases - Wanted and unwanted
|-
| style="border-style: none;" | [[File:ANxxx-wanted_and_unwanted_aliases.jpg|450px|center]]
|}

Applications should therefore prefer converter rates that can contain the desired signal spectrum in a single Nyquist zone, or split the signal spectrum among multiple channels and devices. While the USRP X440 does not limit the utilized Nyquist zone, performance degrades in higher orders zones and application should focus on operating in Nyquist zones 1 and 2 (For RX, zone 3 is possible, but zones 4 and higher result into significant performance degradation).


== RF-ADC Spurs to consider and how to predict them ==
Another kind of distortion originates from the ADC/DAC itself. The USRP X440 uses the Xilinx RFDC, which is a design that combines multiple converters to
achieve high RF-ADC rates. An RF-ADC in this design has 8 sub-ADCs that are interleaved together. The resulting offset spurs are minimized by the integrated self-calibration (see also <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/Key-CAL-Features-and-Guidance-Summary Key CAL Features and Guidance Summary]</ref>) executed by UHD but may still be detectable in the signal spectrum.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 4. RF-ADC Spurs with MCR = 500 MHz
|-
| style="border-style: none;" | [[File:ANxxx-adc_distortions.jpg|450px|center]]
|}

Even with the best calibration the RF-ADC spurs may still be detectable in the captured spectrum. Knowledge of the location of the spurs, in particular the RF-ADC offset spur may be used during frequency planning to select an MCR (and converter rate) that exclude the offset spur frequencies from the capture spectrum. RF-ADC input spurs on the other hand will be more difficult to avoid, but as rule of thumb for modulated input signals carrier frequencies that fall on an RF-ADC offset spur frequency should be avoided (because offset and input spurs would superimpose each other).

=== How to predict offset spurs ===
Any residual DC offset not corrected appears as a spur at k*FS/N, where FS is the composite converter rate of the RF-ADC, N is the number of sub-RF-ADCs interleaved together (8 for X4xx devices), and k = 0, 1, 2, … N.
For more information on expected spurs levels, refer to OIS at <ref>[https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Performance-Characteristics RF-ADC Performance Characteristics]</ref>.

=== How to predict input spurs ===
Any residual difference from gain and time skew correction results in spurious signals at +/-fin + (k/N)*FS, where FS is the converter rate of the RF-ADC, N is the number of sub-RF-ADCs (8 for X4xx devices), and fin is the frequency of the input signal.
For more information on expected spurs levels, refer to GTIS at <ref>[https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Performance-Characteristics RF-ADC Performance Characteristics]</ref>.


== RF-DAC Distortions ==
Like the RF-ADC, the RF-DAC is also not an ideal circuitry and suffers from zero-order hold reconstruction. To counter this undesired attenuation in all but the first Nyquist zone, the Xilinx RF-DAC offers a Mix-Mode, which improves the power response in the second Nyquist zone and is utilized by the USRP X440. This, together with an inverse sinc filter to counter residual distortion limits the practical use of the RF-DAC to the first two Nyquist zones. For more information on the RF-DAC mix-mode and inverse sinc filter characteristics, refer to <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/RF-DAC-Nyquist-Zone-Operation RF-DAC Nyquist Zone Operation]</ref>.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 5 <ref>[https://docs.xilinx.com/viewer/attachment/wIPPkVrh~0jtjy6aqWeihQ/q5kXcl5Z7lFon2v535oW0w Xilinx: Ideal DAC Output Response, Normalised to Fsample]</ref>. RF-DAC Mix-Mode and normal, ideal roll-off sinc response.
|-
| style="border-style: none;" | [[File:ANxxx-dac_roll-off_sinc_response.png|350px|center]]
|}


Note: Due to the direct sampling architecture without filters on the FBX daughterboard, TX ports will output the converter rate (Fc) with a low power (<-50 dBm) as soon as the corresponding ADCs and DACs are enabled, even if the DACs are not actively transmitting. This is a known limitation of the X440 and FBX design. For instance when acquiring a signal on the RX1 port of RF0, the converter rate (Fc) can be measured on the TX/RX0 port of RF0. While operation around the converter rate (Fc) is not recommended anyway, it is possible to suppress the converter rate (Fc) by using a frontend module with a sufficiently high attenuation at the converter rate.



== Dual Rate ==
Unlike previous USRPs, the USRP X440 supports the operation at two different master clock rates simultaneously. All channels on the first daughterboard will run on the first master clock rate / sampling rate and all channels on the second daughterboard will run on the second configured master clock rate / sampling rate. The main motivation for having two different master clock rates is the direct sampling architecture of the USRP X440 without signal conditioning and filtering. While [[#dsp-distortions|Aliases and Nyquist Zones]] describes the challenges of that, with dual rate this feature can be used to capture an RF spectrum that exceeds the bandwidth abilities of the single rate operation. Using a second rate, one can close the Nyquist gap of the other and monitor a wider spectrum for further processing.
As the clocks of both radios are derived from a common clocking chip, not all combinations are possible. Refer to [[#X440-supported-dual-rates|X440 Supported Dual Rates]] for possible RF Data Converter sampling rate combinations. The section about the [[#converter_rate-mcr-iq_rate|Relationship between RFADC/DAC Converter Rate, USRP Master Clock Rate (MCR) and Data IQ rate]] explains how to derive valid master clock rates from the RF Data converter sampling rates.

Note: When using different MCRs for both daughterboards, the device will skip the multi-tile synchronization. That means that the phase relationship between channels may not be preserved over retunes and reboots for channels of the same daughterboard and no defined phase relationship will be preserved between channels of different daughterboards.



= Use cases =
== Scan Spectrum within single Nyquist zone ==
=== Spectrum Capture between 1.7 and 1.9 GHz. ===
* Min Bandwidth: 200 MHz
* Minimum IQ Rate: 250 MSps
==== Option 1: MCR = 250 MHz, RF-ADC converter rate = 2 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_250e6_2000e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest is very close to a Nyquist zone boundary.

==== Option 2: MCR = 300 MHz, RF-ADC converter rate = 2.4 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_300e6_2400e6.jpg|450px|center]]
|}
This option is better, the spectrum of interest is well within a Nyquist zone. Within the bandwidth of interest falls one of the ADC offset spurs. If the input signal is relatively strong, the impact from this small spur is negligible. If on the other hand the input signal strength is on the low end (for the X440), then maybe a different MCR should be considered.

==== Option 3: MCR = 320 MHz, RF-ADC converter rate = 2.56 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_320e6_2560e6.jpg|450px|center]]
|}
This option avoids a potential impact of an ADC offset spur in the observed spectrum. The only drawback to option 2 is the slightly higher data rate during host post-processing.

=== Spectrum Capture between 500 MHz and 1.5 GHz. ===
The USRP X440 ships with multiple [https://uhd.readthedocs.io/en/latest/page_usrp_x4xx.html#x4xx_updating_fpga_types FPGA image flavors]. These either support 400 MHz or 1600 MHz RF bandwidth per channel. To address this use case, users have the option of using a bit file with 1600 MHz RF bandwidth to capture a contiguous spectrum, or use a 400 MHz bit file and create a stitched spectrum during host side post-processing.
==== Using 1600 MHz image ====
* Min Bandwidth: 1000 MHz
* Minimum IQ Rate: 1250 MSps
===== Option 1: MCR = 1280 MHz, RF-ADC converter rate = 2.56 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1250e6_2560e6.jpg|450px|center]]
|}
Bad option, because desired spectrum spans multiple Nyquist zones.

===== Option 2: MCR = 1600 MHz, RF-ADC converter rate = 3.2 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1600e6_3200e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest is very close to a Nyquist zone boundary.

===== Option 3: MCR = 1689.6 MHz, RF-ADC converter rate = 3.3792 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1689e6_3379e6.jpg|450px|center]]
|}
This option would work. If the input signal strength is low, using an even higher MCR would reduce the number of potential ADC offset spurs. This needs to be traded off against a higher data rate during host post-processing.

==== Using 400 MHz image ====
Due to the smaller bandwidth addressing the use case will require the use of multiple channels. The captured spectra than needs to be stitched (combined) together.
* Max Bandwidth: 400 MHz
===== Option 1: MCR 400 MHz, RF-ADC converter rate = 3.2 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_400e6_3200e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest boundary is very close to a Nyquist zone boundary.

===== Option 2: MCR 450 MHz, RF-ADC converter rate = 3.6 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_450e6_3600e6.jpg|450px|center]]
|}
This option would work. Since the spectrum of interest is larger than the per channel bandwidth the captured spectrum may contain potential ADC offset spurs. For the spectrum of interest the 3 channels would nicely use tune frequencies (680, 1000, 1320 MHz) that do not match ADC offset spur frequencies.

===== Option 3: MCR 512 MHz, RF-ADC converter rate = 4.096 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_512e6_4096e6.jpg|450px|center]]
|}
This option would work as well. Like in option 2, the spectrum of interest may contain one potential ADC offset spur (compared to 2 in option 2). The drawback to option 2 is of course again the higher data rate during host post-processing that may be offset by only having to stitch less spectra (2 vs 3) together.



== Scan Spectrum with dual master clock rate ==
=== Spectrum capture between 1.0 and 2.4 GHz (L-band) ===
* Combination of two RF-ADC converter rates: 4096 MHz and 2560 MHz
* Derived master clock rates: 1024 MHz (resampling factor 4) and 1280 MHz (resampling factor 2). The resampling factors are chosen to produce master clock rates which allow capturing a sufficient bandwidth to not have any gaps.
* Center frequencies: 1.23 GHz and 2.0 GHz respectively
* 1600 MHz FPGA image required due to the bandwidth requirements
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:AN055-L-band-dual-rate.jpg|800px|center]]
|}
In the picture you can see a light-green band between 1.0 GHz and 2.4 GHz which can be covered using two different rates: Radio0 operates at MCR=1024 MHz in its first Nyquist zone and radio1 operates at 1280 MHz in its second Nyquist zone. The coverage is shown as light-blue boxes in both frequency charts. Starting with UHD 4.6, the X440_L_band_capture.py example demonstrates this use case and by default uses center frequencies of 0.9 GHz and 2 GHz respectively. These were choosen to conveniently display the two individual spectra next to each other in a continuous spectra view without any overlap. Practical applications on the other hand need to take into account that the well usable bandwidth of each channel is only about 0.8 * MCR. For the chosen MCRs this means that the first radio has a usable bandwidth of 819.2 MHz and the second one of 1024 MHz. Taking into account that a typical RF passband in the first Nyquist zone has a passband of up to 0.4 * FS and the need for some overlap of the two spectra, the center frequency of radio0 should be set to 1.230 GHz (usable bandwidth spans from ~820 MHz to ~1640 MHz). Radio1 will be used in its second Nyquist zone, so the center frequency should be 2.0 GHz (usable bandwidth from ~1.5 GHz to ~2.5 GHz).


= Appendix =

== X440 Supported Master Clock Rates (MCR) ==
Note: The selected FPGA bitfile may further limit the maximum supported master clock rate.
{| class="wikitable" style="text-align: center; margin:auto"
|-
! MCR (MHz) !! RFDC Converter Rate (GHz)
|-
| 125.0 || 1.0
|-
| 128.0 || 1.024
|-
| 133.12 || 1.06496
|-
| 150.0 || 1.2
|-
| 153.6 || 1.2288
|-
| 160.0 || 1.28
|-
| 163.84 || 1.31072
|-
| 184.32 || 1.47456
|-
| 199.68 || 1.59744
|-
| 200.0 || 1.6
|-
| 204.8 || 1.6384
|-
| 240.0 || 1.92
|-
| 245.76 || 1.96608
|-
| 250.0 || 2.0, 1.0
|-
| 256.0 || 2.048, 1.024
|-
| 266.24 || 2.12992, 1.06496
|-
| 300.0 || 2.4, 1.2
|-
| 307.2 || 2.4576, 1.2288
|-
| 320.0 || 2.56, 1.28
|-
| 327.68 || 2.62144, 1.31072
|-
| 360.0 || 2.88, 1.44
|-
| 368.64 || 1.47456, 2.94912
|-
| 375.0 || 3.0, 1.5
|-
| 384.0 || 1.536, 3.072
|-
| 399.36 || 3.19488, 1.59744
|-
| 400.0 || 3.2, 1.6
|-
| 409.6 || 3.2768, 1.6384
|-
| 450.0 || 1.8, 3.6
|-
| 460.8 || 1.8432, 3.6864
|-
| 480.0 || 3.84, 1.92
|-
| 491.52 || 3.93216, 1.96608
|-
| 500.0 || 4.0, 2.0, 1.0
|-
| 512.0 || 1.024, 2.048, 4.096
|-
| 532.48 || 1.06496, 2.12992
|-
| 552.96 || 2.21184, 1.10592
|-
| 599.04 || 1.19808, 2.39616
|-
| 600.0 || 1.2, 2.4
|-
| 614.4 || 1.2288, 2.4576
|-
| 625.0 || 1.25, 2.5
|-
| 640.0 || 2.56, 1.28
|-
| 655.36 || 1.31072, 2.62144
|-
| 665.6 || 1.3312, 2.6624
|-
| 720.0 || 1.44, 2.88
|-
| 737.28 || 1.47456, 2.94912
|-
| 750.0 || 1.5, 3.0
|-
| 768.0 || 1.536, 3.072
|-
| 798.72 || 3.19488, 1.59744
|-
| 800.0 || 1.6, 3.2
|-
| 819.2 || 3.2768, 1.6384
|-
| 840.0 || 1.68, 3.36
|-
| 860.16 || 3.44064, 1.72032
|-
| 875.0 || 3.5, 1.75
|-
| 896.0 || 3.584, 1.792
|-
| 900.0 || 1.8, 3.6
|-
| 921.6 || 1.8432, 3.6864
|-
| 931.84 || 1.86368, 3.72736
|-
| 960.0 || 3.84, 1.92
|-
| 983.04 || 1.96608, 3.93216
|-
| 998.4 || 3.9936, 1.9968
|-
| 1000.0 || 4.0, 2.0
|-
| 1024.0 || 4.096, 2.048
|-
| 1050.0 || 2.1
|-
| 1064.96 || 2.12992
|-
| 1075.2 || 2.1504
|-
| 1080.0 || 2.16
|-
| 1105.92 || 2.21184
|-
| 1120.0 || 2.24
|-
| 1125.0 || 2.25
|-
| 1146.88 || 2.29376
|-
| 1152.0 || 2.304
|-
| 1198.08 || 2.39616
|-
| 1200.0 || 2.4
|-
| 1228.8 || 2.4576
|-
| 1250.0 || 2.5
|-
| 1280.0 || 2.56
|-
| 1290.24 || 2.58048
|-
| 1310.72 || 2.62144
|-
| 1331.2 || 2.6624
|-
| 1350.0 || 2.7
|-
| 1382.4 || 2.7648
|-
| 1397.76 || 2.79552
|-
| 1400.0 || 2.8
|-
| 1433.6 || 2.8672
|-
| 1440.0 || 2.88
|-
| 1474.56 || 2.94912
|-
| 1500.0 || 3.0
|-
| 1536.0 || 3.072
|-
| 1600.0 || 3.2
|-
| 1625.0 || 3.25
|-
| 1638.4 || 3.2768
|-
| 1650.0 || 3.3
|-
| 1658.88 || 3.31776
|-
| 1664.0 || 3.328
|-
| 1680.0 || 3.36
|-
| 1689.6 || 3.3792
|-
| 1720.32 || 3.44064
|-
| 1730.56 || 3.46112
|-
| 1750.0 || 3.5
|-
| 1760.0 || 3.52
|-
| 1792.0 || 3.584
|-
| 1797.12 || 3.59424
|-
| 1800.0 || 3.6
|-
| 1802.24 || 3.60448
|-
| 1843.2 || 3.6864
|-
| 1863.68 || 3.72736
|-
| 1875.0 || 3.75
|-
| 1920.0 || 3.84
|-
| 1950.0 || 3.9
|-
| 1966.08 || 3.93216
|-
| 1996.8 || 3.9936
|-
| 2000.0 || 4.0
|-
| 2027.52 || 4.05504
|-
| 2048.0 || 4.096
|}


== X440 Supported Master Clock Rate combinations (Dual Rate) ==
Important: For the best RF performance it is required to configure the master clock rate that is connected to the higher RF-ADC/DAC converter rate on the first radio and the MCR connected to the lower converter rate second. Not all master clock rate combinations listed in this table will comply to this requirement by themselves. Specifying the converter_rate argument or swapping the master clock rates will help resolving issues. The selected FPGA bitfile may further limit the maximum supported master clock rate.
{| class="wikitable" style="text-align: center; margin:auto"
|-
| MCR0 (MHz) || MCR1 (MHz)
|-
| 125.0 || 250.0, 375.0, 500.0, 750.0, 875.0, 1000.0, 1125.0, 1625.0, 1750.0, 1875.0, 2000.0
|-
| 128.0 || 384.0, 512.0, 768.0, 1152.0
|-
| 133.12 || 266.24, 399.36, 532.48, 665.6, 798.72, 931.84, 1064.96, 1198.08, 1331.2, 1730.56, 1863.68, 1996.8
|-
| 150.0 || 300.0, 450.0, 600.0, 750.0, 900.0, 1050.0, 1350.0, 1500.0, 1650.0, 1800.0, 1950.0
|-
| 153.6 || 307.2, 614.4, 1228.8
|-
| 160.0 || 320.0, 640.0, 800.0, 1120.0, 1280.0, 1600.0, 1760.0
|-
| 163.84 || 327.68, 655.36, 1146.88, 1310.72, 1474.56, 1802.24
|-
| 184.32 || 368.64, 552.96, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2, 2027.52
|-
| 199.68 || 399.36, 599.04, 798.72, 998.4, 1198.08, 1397.76, 1797.12, 1996.8
|-
| 200.0 || 400.0, 800.0, 1200.0, 1400.0, 1600.0
|-
| 204.8 || 409.6, 819.2, 1433.6, 1638.4
|-
| 240.0 || 360.0, 480.0, 600.0, 720.0, 840.0, 960.0, 1440.0, 1680.0, 1800.0, 1920.0
|-
| 245.76 || 491.52, 860.16, 983.04, 1720.32, 1966.08
|-
| 250.0 || 125.0, 375.0, 500.0, 750.0, 875.0, 1000.0, 1500.0, 1625.0, 1750.0, 1875.0, 2000.0
|-
| 256.0 || 640.0, 896.0, 1024.0, 1280.0, 1664.0, 1792.0, 2048.0
|-
| 266.24 || 133.12, 399.36, 532.48, 665.6, 798.72, 931.84, 1064.96, 1331.2, 1730.56, 1863.68, 1996.8
|-
| 300.0 || 150.0, 450.0, 600.0, 750.0, 900.0, 1050.0, 1500.0, 1650.0, 1800.0, 1950.0
|-
| 307.2 || 153.6, 614.4, 1228.8
|-
| 320.0 || 160.0, 640.0, 800.0, 1120.0, 1280.0, 1600.0, 1760.0
|-
| 327.68 || 163.84, 655.36, 1146.88, 1310.72, 1802.24
|-
| 360.0 || 240.0, 600.0, 720.0, 1080.0, 1800.0
|-
| 368.64 || 184.32, 552.96, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2, 2027.52
|-
| 375.0 || 125.0, 250.0, 750.0, 1125.0, 1500.0, 1875.0
|-
| 384.0 || 128.0, 768.0, 1152.0, 1536.0
|-
| 399.36 || 133.12, 199.68, 266.24, 599.04, 665.6, 798.72, 998.4, 1198.08, 1331.2, 1397.76, 1797.12, 1996.8
|-
| 400.0 || 200.0, 800.0, 1200.0, 1400.0, 1600.0
|-
| 409.6 || 204.8, 819.2, 1433.6, 1638.4
|-
| 450.0 || 150.0, 300.0, 600.0, 750.0, 900.0, 1350.0, 1500.0, 1800.0
|-
| 460.8 || 768.0, 921.6, 1075.2, 1382.4, 1536.0
|-
| 480.0 || 240.0, 720.0, 840.0, 960.0, 1440.0, 1680.0, 1920.0
|-
| 491.52 || 245.76, 860.16, 983.04, 1720.32, 1966.08
|-
| 500.0 || 125.0, 250.0, 750.0, 875.0, 1000.0, 1500.0, 1750.0, 2000.0
|-
| 512.0 || 128.0, 768.0, 1536.0
|-
| 532.48 || 133.12, 266.24, 798.72, 931.84, 1064.96, 1331.2, 1863.68
|-
| 552.96 || 184.32, 368.64, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2
|-
| 599.04 || 199.68, 399.36, 798.72, 998.4, 1198.08, 1397.76, 1797.12, 1996.8
|-
| 600.0 || 150.0, 240.0, 300.0, 360.0, 450.0, 720.0, 900.0, 1000.0, 1050.0, 1500.0, 1800.0, 2000.0
|-
| 614.4 || 153.6, 307.2, 1228.8
|-
| 625.0 || 1250.0
|-
| 640.0 || 160.0, 256.0, 320.0, 800.0, 1120.0, 1280.0, 1600.0
|-
| 655.36 || 163.84, 327.68, 1146.88, 1310.72
|-
| 665.6 || 133.12, 266.24, 399.36, 798.72, 1331.2, 1996.8
|-
| 720.0 || 240.0, 360.0, 480.0, 600.0, 960.0, 1440.0, 1680.0, 1800.0, 1920.0
|-
| 737.28 || 184.32, 368.64, 552.96, 1105.92, 1290.24, 1474.56, 1843.2
|-
| 750.0 || 125.0, 150.0, 250.0, 300.0, 375.0, 450.0, 500.0, 900.0, 1000.0, 1125.0, 1500.0, 1750.0, 1875.0, 2000.0
|-
| 768.0 || 128.0, 384.0, 460.8, 512.0, 921.6, 1152.0, 1536.0
|-
| 798.72 || 133.12, 199.68, 266.24, 399.36, 532.48, 599.04, 665.6, 998.4, 1064.96, 1198.08, 1331.2, 1397.76, 1863.68, 1996.8
|-
| 800.0 || 160.0, 200.0, 320.0, 400.0, 640.0, 1200.0, 1400.0, 1600.0
|-
| 819.2 || 204.8, 409.6, 1433.6, 1638.4
|-
| 840.0 || 240.0, 480.0, 1680.0
|-
| 860.16 || 245.76, 491.52, 1720.32
|-
| 875.0 || 125.0, 250.0, 500.0, 1750.0
|-
| 896.0 || 256.0, 1792.0
|-
| 900.0 || 150.0, 300.0, 450.0, 600.0, 750.0, 1500.0, 1800.0
|-
| 921.6 || 460.8, 768.0, 1536.0
|-
| 931.84 || 133.12, 266.24, 532.48, 1863.68
|-
| 960.0 || 240.0, 480.0, 720.0, 1440.0, 1920.0
|-
| 983.04 || 245.76, 491.52, 1966.08
|-
| 998.4 || 199.68, 399.36, 599.04, 798.72, 1198.08, 1996.8
|-
| 1000.0 || 125.0, 250.0, 500.0, 600.0, 750.0, 1500.0, 2000.0
|-
| 1024.0 || 256.0, 1280.0, 2048.0
|-
| 1050.0 || 150.0, 300.0, 600.0
|-
| 1064.96 || 133.12, 266.24, 532.48, 798.72, 1331.2
|-
| 1075.2 || 460.8
|-
| 1080.0 || 360.0
|-
| 1105.92 || 184.32, 368.64, 552.96, 737.28, 1474.56, 1658.88, 1843.2
|-
| 1120.0 || 160.0, 320.0, 640.0
|-
| 1125.0 || 125.0, 375.0, 750.0, 1500.0, 1875.0
|-
| 1146.88 || 163.84, 327.68, 655.36
|-
| 1152.0 || 128.0, 384.0, 768.0, 1536.0
|-
| 1198.08 || 133.12, 199.68, 399.36, 599.04, 798.72, 998.4, 1797.12, 1996.8
|-
| 1200.0 || 200.0, 400.0, 800.0, 1600.0
|-
| 1228.8 || 153.6, 307.2, 614.4
|-
| 1250.0 || 625.0
|-
| 1280.0 || 160.0, 256.0, 320.0, 640.0, 1024.0, 1600.0
|-
| 1290.24 || 184.32, 368.64, 552.96, 737.28
|-
| 1310.72 || 163.84, 327.68, 655.36
|-
| 1331.2 || 133.12, 266.24, 399.36, 532.48, 665.6, 798.72, 1064.96, 1996.8
|-
| 1350.0 || 150.0, 450.0
|-
| 1382.4 || 460.8
|-
| 1397.76 || 199.68, 399.36, 599.04, 798.72
|-
| 1400.0 || 200.0, 400.0, 800.0
|-
| 1433.6 || 204.8, 409.6, 819.2
|-
| 1440.0 || 240.0, 480.0, 720.0, 960.0, 1920.0
|-
| 1474.56 || 163.84, 184.32, 368.64, 552.96, 737.28, 1105.92
|-
| 1500.0 || 150.0, 250.0, 300.0, 375.0, 450.0, 500.0, 600.0, 750.0, 900.0, 1000.0, 1125.0, 2000.0
|-
| 1536.0 || 384.0, 460.8, 512.0, 768.0, 921.6, 1152.0
|-
| 1600.0 || 160.0, 200.0, 320.0, 400.0, 640.0, 800.0, 1200.0, 1280.0
|-
| 1625.0 || 125.0, 250.0
|-
| 1638.4 || 204.8, 409.6, 819.2
|-
| 1650.0 || 150.0, 300.0
|-
| 1658.88 || 184.32, 368.64, 552.96, 1105.92
|-
| 1664.0 || 256.0
|-
| 1680.0 || 240.0, 480.0, 720.0, 840.0
|-
| 1720.32 || 245.76, 491.52, 860.16
|-
| 1730.56 || 133.12, 266.24
|-
| 1750.0 || 125.0, 250.0, 500.0, 750.0, 875.0
|-
| 1760.0 || 160.0, 320.0
|-
| 1792.0 || 256.0, 896.0
|-
| 1797.12 || 199.68, 399.36, 599.04, 1198.08
|-
| 1800.0 || 150.0, 240.0, 300.0, 360.0, 450.0, 600.0, 720.0, 900.0
|-
| 1802.24 || 163.84, 327.68
|-
| 1843.2 || 184.32, 368.64, 552.96, 737.28, 1105.92
|-
| 1863.68 || 133.12, 266.24, 532.48, 798.72, 931.84
|-
| 1875.0 || 125.0, 250.0, 375.0, 750.0, 1125.0
|-
| 1920.0 || 240.0, 480.0, 720.0, 960.0, 1440.0
|-
| 1950.0 || 150.0, 300.0
|-
| 1966.08 || 245.76, 491.52, 983.04
|-
| 1996.8 || 133.12, 199.68, 266.24, 399.36, 599.04, 665.6, 798.72, 998.4, 1198.08, 1331.2
|-
| 2000.0 || 125.0, 250.0, 500.0, 600.0, 750.0, 1000.0, 1500.0
|-
| 2027.52 || 184.32, 368.64
|-
| 2048.0 || 256.0, 1024.0
|}


== References and Related Documentation ==
* [https://www.ni.com/en/solutions/aerospace-defense/radar-electronic-warfare-sigint/advantages-of-direct-rf-sampling-architectures.html Advantages of Direct RF Sampling Architectures]
* [https://docs.xilinx.com/r/en-US/pg269-rf-data-converter Zynq UltraScale+ RFSoC RF Data Converter v2.6 Gen 1/2/3/DFE LogiCORE IP Product Guide (PG269)]
* [https://events.gnuradio.org/event/21/contributions/392/attachments/123/285/Lo%20and%20behold,%20no%20LO.pdf GRcon 23 - Lo and behold, no LO!]
* [https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Electrical-Characteristics Zynq UltraScale+ RFSoC Data Sheet: DC and AC Switching Characteristics (DS926)]

= Footnotes =
<references />

Knowledge Base

2026-04-27T08:20:56Z

MartinAnderseck: Updated the X4xx motherboards GSG link to point to the manual

Welcome to the Ettus Research Knowledge Base (KB). The KB is continuously being updated and expanded. If you have any suggestions, or do not find what you are looking for, then please [http://www.ettus.com/contact Contact Us].
__NOTOC__
<div class="row">
<div class="col-1-3">
== [[Getting Started Guides| Getting Started Guides]] ==

'''Motherboards'''
* [[B200/B210/B200mini/B205mini/B206mini Getting Started Guides|B200/B210/B200mini/B205mini/B206mini]]
* [[Ettus USRP E300 Embedded Family Getting Started Guides|E310/E312/E313]]
* [[E320 Getting Started Guide|E320]]
* [[N200/N210 Getting Started Guides|N200/N210]]
* [[USRP N300/N310/N320/N321 Getting Started Guide|N300/N310/N320/N321]]
* [[X300/X310 Getting Started Guides|X300/X310]]
* [[USRP-2974 Getting Started Guide|USRP-2974]]
* [https://uhd.readthedocs.io/en/latest/page_usrp_x4xx.html#x4xx_getting_started X410/X420/X440]

'''Daughterboards'''
* [[OBX Getting Started Guides|OBX]]
* [[BasicTX/BasicRX Getting Started Guides|BasicTX/BasicRX]]
* [[CBX Getting Started Guides|CBX]]
* [[LFTX/LFRX Getting Started Guides|LFTX/LFRX]]
* [[SBX Getting Started Guides|SBX]]
* [[TwinRX Getting Started Guides|TwinRX]]
* [[UBX Getting Started Guides|UBX]]
* [[WBX Getting Started Guides|WBX]]

'''Other'''
* [[Getting_Started_with_RFNoC_in_UHD_4.0|RFNoC Development (UHD 4.x)]]
* [[RFNoC_4_Migration_Guide|RFNoC Migration Guide (UHD 3.x to UHD 4.x)]]
* [[Getting_Started_with_RFNoC_Development|RFNoC Development (UHD 3.x)]]
* [[Live SDR Environment Getting Started Guides|Live SDR Environment]]
* [[OctoClock CDA-2990 Getting Started Guides|OctoClock CDA-2990]]
* [[Using Ethernet-Based Synchronization on the USRP™ N3xx Devices|White Rabbit]]
* [[Getting Started with DPDK and UHD|DPDK]]

</div>
<div class="col-1-3">

== [[Hardware Resources| Hardware Resources]] ==
'''Motherboards'''
* [[B200/B210/B200mini/B205mini/B206mini]]
* [[Ettus USRP E300 Embedded Family Hardware Resources|E310/E312/E313]]
* [[E320|E320]]
* [[N200/N210]]
* [[N300/N310]]
* [[N320/N321]]
* [[X300/X310]]
* [[USRP-2974]]
* [[X410]]
* [[X440]]

'''Daughterboards'''
* [[OBX]]
* [[BasicTX/BasicRX]]
* [[CBX]]
* [[LFTX/LFRX]]
* [[SBX]]
* [[TwinRX]]
* [[UBX]]
* [[WBX]]

'''Other'''
* [[OctoClock CDA-2990]]
* [[GPSDO]]
* [[Antennas]]

</div>
<div class="col-1-3">

== [[Software Resources| Software Resources]] ==
'''Ettus Products'''
* [[UHD]]
* [[UHD Python API]]
* [[RFNoC|RFNoC (UHD 4.x)]]
* [[RFNoC (UHD 3.0)|RFNoC (UHD 3.x)]]

'''Third Party'''
* [[GNU Radio]]
* [[LabVIEW]]
* [[Matlab/Simulink]]
* [[OpenBTS]]
* [[Eurecom OpenAirInterface (OAI)]]
* [[srsLTE/srsUE]]
* [[Gqrx]]
* [[Fosphor]]

'''Reference Architectures'''
* [[Multichannel RF Reference Architecture]]
* [[OAI Reference Architecture for 5G and 6G Research with USRP]]
* [[5G OAI Neural Receiver Testbed with USRP X410]]
* [[AI-Based Spectrum Sensing with Nvidia Jetson and USRP]]
* [[5G OAI End-to-End Reference Architecture with USRP]]
* [[5G srsRAN End-to-End Reference Architecture with USRP]]

</div>
</div>

<div class="row">
<div class="col-1-3">

== [[UHD and USRP User Manual| UHD and USRP User Manual]] ==

'''Software'''
* [https://uhd.readthedocs.io/ UHD Manual (master)]
* [https://files.ettus.com/manual_archive/ UHD Manual Archive (previous releases)]

'''Motherboards'''
* [https://files.ettus.com/manual/page_usrp_b200.html B200/B210/B200mini/B205mini/B206mini]
* [https://files.ettus.com/manual/page_usrp_x3x0.html X300/X310]
* [https://files.ettus.com/manual/page_usrp2.html N200/N210]
* [https://files.ettus.com/manual/page_usrp_n3xx.html N300/N310/N320/N321]
* [https://files.ettus.com/manual/page_usrp_e3xx.html E310/E312/E313/E320]
* [https://files.ettus.com/manual/page_usrp_x4xx.html X410/X440]

'''Daughterboards'''
* [https://files.ettus.com/manual/page_dboards.html#dboards_basictx BasicRX/LFRX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_basicrx BasicTX/LFTX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_cbx CBX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_sbx SBX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_wbx WBX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_ubx UBX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_twinrx TwinRX]

'''Other'''
* [https://files.ettus.com/manual/page_octoclock.html OctoClock]

</div>
<div class="col-1-3">

== [[Application Notes| Application Notes]] ==
Application Notes (AN) and technical articles written by engineers, for engineers. These articles offer experienced analysis, design ideas, reference designs, and tutorials—to make you productive and successful using USRP devices.
</div>
<div class="col-1-3">

== [[Additional Resources| Additional Resources]] ==
* [[Workshop_Tutorial|Workshop/Tutorial]]
* [[Suggested Reading|Suggested Reading]]
* [[Suggested Videos|Suggested Videos]]
* [[CGRAN]]
* [[SDR Events]]
* [[GNU Radio Conference]]
* [[NEWSDR]]
* [[FOSDEM]]
* [[Cyberspectrum]]
</div>
</div>

<div class="row">
<div class="col-1-3">

== [[Technical Support| Technical Support]] ==
* [[Email|Email]]
* [[Mailing Lists|Mailing Lists]]
* [[Matrix|GNU Radio Matrix Chat Server]]
* [[SDR_Boston_Slack|SDR Boston Slack Chat Server]]
* [[StackExchange|StackExchange]]
* [[NI_SRM|NI Service Request Manager (SRM)]]

</div>
<div class="col-1-3">

== [[Faq| FAQ]] ==
* [[Technical FAQ|Technical]]
* [[Licensing FAQ|Licensing]]
* [[RFNoC_Frequently_Asked_Questions|RFNoC]]

</div>
<div class="col-1-3">

== [[Legacy Products| Legacy Products]] ==
'''Motherboards'''
* [[USRP1|USRP1]]
* [[USRP2|USRP2]]
* [[E100/E110|E100/E110]]
* [[B100]]

'''Daughterboards'''
* [[DBSRX2]]
* [[TVRX2]]
* [[XCVR2450]]

Knowledge Base

2026-04-27T08:15:24Z

MartinAnderseck: Made the "UHD manual (master)" link point towards readthedocs instead of the last release.

Welcome to the Ettus Research Knowledge Base (KB). The KB is continuously being updated and expanded. If you have any suggestions, or do not find what you are looking for, then please [http://www.ettus.com/contact Contact Us].
__NOTOC__
<div class="row">
<div class="col-1-3">
== [[Getting Started Guides| Getting Started Guides]] ==

'''Motherboards'''
* [[B200/B210/B200mini/B205mini/B206mini Getting Started Guides|B200/B210/B200mini/B205mini/B206mini]]
* [[Ettus USRP E300 Embedded Family Getting Started Guides|E310/E312/E313]]
* [[E320 Getting Started Guide|E320]]
* [[N200/N210 Getting Started Guides|N200/N210]]
* [[USRP N300/N310/N320/N321 Getting Started Guide|N300/N310/N320/N321]]
* [[X300/X310 Getting Started Guides|X300/X310]]
* [[USRP-2974 Getting Started Guide|USRP-2974]]
* [[USRP X410/X440 Getting Started Guide|X410/X440]]

'''Daughterboards'''
* [[OBX Getting Started Guides|OBX]]
* [[BasicTX/BasicRX Getting Started Guides|BasicTX/BasicRX]]
* [[CBX Getting Started Guides|CBX]]
* [[LFTX/LFRX Getting Started Guides|LFTX/LFRX]]
* [[SBX Getting Started Guides|SBX]]
* [[TwinRX Getting Started Guides|TwinRX]]
* [[UBX Getting Started Guides|UBX]]
* [[WBX Getting Started Guides|WBX]]

'''Other'''
* [[Getting_Started_with_RFNoC_in_UHD_4.0|RFNoC Development (UHD 4.x)]]
* [[RFNoC_4_Migration_Guide|RFNoC Migration Guide (UHD 3.x to UHD 4.x)]]
* [[Getting_Started_with_RFNoC_Development|RFNoC Development (UHD 3.x)]]
* [[Live SDR Environment Getting Started Guides|Live SDR Environment]]
* [[OctoClock CDA-2990 Getting Started Guides|OctoClock CDA-2990]]
* [[Using Ethernet-Based Synchronization on the USRP™ N3xx Devices|White Rabbit]]
* [[Getting Started with DPDK and UHD|DPDK]]

</div>
<div class="col-1-3">

== [[Hardware Resources| Hardware Resources]] ==
'''Motherboards'''
* [[B200/B210/B200mini/B205mini/B206mini]]
* [[Ettus USRP E300 Embedded Family Hardware Resources|E310/E312/E313]]
* [[E320|E320]]
* [[N200/N210]]
* [[N300/N310]]
* [[N320/N321]]
* [[X300/X310]]
* [[USRP-2974]]
* [[X410]]
* [[X440]]

'''Daughterboards'''
* [[OBX]]
* [[BasicTX/BasicRX]]
* [[CBX]]
* [[LFTX/LFRX]]
* [[SBX]]
* [[TwinRX]]
* [[UBX]]
* [[WBX]]

'''Other'''
* [[OctoClock CDA-2990]]
* [[GPSDO]]
* [[Antennas]]

</div>
<div class="col-1-3">

== [[Software Resources| Software Resources]] ==
'''Ettus Products'''
* [[UHD]]
* [[UHD Python API]]
* [[RFNoC|RFNoC (UHD 4.x)]]
* [[RFNoC (UHD 3.0)|RFNoC (UHD 3.x)]]

'''Third Party'''
* [[GNU Radio]]
* [[LabVIEW]]
* [[Matlab/Simulink]]
* [[OpenBTS]]
* [[Eurecom OpenAirInterface (OAI)]]
* [[srsLTE/srsUE]]
* [[Gqrx]]
* [[Fosphor]]

'''Reference Architectures'''
* [[Multichannel RF Reference Architecture]]
* [[OAI Reference Architecture for 5G and 6G Research with USRP]]
* [[5G OAI Neural Receiver Testbed with USRP X410]]
* [[AI-Based Spectrum Sensing with Nvidia Jetson and USRP]]
* [[5G OAI End-to-End Reference Architecture with USRP]]
* [[5G srsRAN End-to-End Reference Architecture with USRP]]

</div>
</div>

<div class="row">
<div class="col-1-3">

== [[UHD and USRP User Manual| UHD and USRP User Manual]] ==

'''Software'''
* [https://uhd.readthedocs.io/ UHD Manual (master)]
* [https://files.ettus.com/manual_archive/ UHD Manual Archive (previous releases)]

'''Motherboards'''
* [https://files.ettus.com/manual/page_usrp_b200.html B200/B210/B200mini/B205mini/B206mini]
* [https://files.ettus.com/manual/page_usrp_x3x0.html X300/X310]
* [https://files.ettus.com/manual/page_usrp2.html N200/N210]
* [https://files.ettus.com/manual/page_usrp_n3xx.html N300/N310/N320/N321]
* [https://files.ettus.com/manual/page_usrp_e3xx.html E310/E312/E313/E320]
* [https://files.ettus.com/manual/page_usrp_x4xx.html X410/X440]

'''Daughterboards'''
* [https://files.ettus.com/manual/page_dboards.html#dboards_basictx BasicRX/LFRX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_basicrx BasicTX/LFTX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_cbx CBX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_sbx SBX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_wbx WBX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_ubx UBX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_twinrx TwinRX]

'''Other'''
* [https://files.ettus.com/manual/page_octoclock.html OctoClock]

</div>
<div class="col-1-3">

== [[Application Notes| Application Notes]] ==
Application Notes (AN) and technical articles written by engineers, for engineers. These articles offer experienced analysis, design ideas, reference designs, and tutorials—to make you productive and successful using USRP devices.
</div>
<div class="col-1-3">

== [[Additional Resources| Additional Resources]] ==
* [[Workshop_Tutorial|Workshop/Tutorial]]
* [[Suggested Reading|Suggested Reading]]
* [[Suggested Videos|Suggested Videos]]
* [[CGRAN]]
* [[SDR Events]]
* [[GNU Radio Conference]]
* [[NEWSDR]]
* [[FOSDEM]]
* [[Cyberspectrum]]
</div>
</div>

<div class="row">
<div class="col-1-3">

== [[Technical Support| Technical Support]] ==
* [[Email|Email]]
* [[Mailing Lists|Mailing Lists]]
* [[Matrix|GNU Radio Matrix Chat Server]]
* [[SDR_Boston_Slack|SDR Boston Slack Chat Server]]
* [[StackExchange|StackExchange]]
* [[NI_SRM|NI Service Request Manager (SRM)]]

</div>
<div class="col-1-3">

== [[Faq| FAQ]] ==
* [[Technical FAQ|Technical]]
* [[Licensing FAQ|Licensing]]
* [[RFNoC_Frequently_Asked_Questions|RFNoC]]

</div>
<div class="col-1-3">

== [[Legacy Products| Legacy Products]] ==
'''Motherboards'''
* [[USRP1|USRP1]]
* [[USRP2|USRP2]]
* [[E100/E110|E100/E110]]
* [[B100]]

'''Daughterboards'''
* [[DBSRX2]]
* [[TVRX2]]
* [[XCVR2450]]

USRP X410/X440 Getting Started Guide

2024-08-07T13:19:38Z

MartinAnderseck: Changed 30dB attenuation warning from X440 to X410.

==Kit Contents==
===X4x0===
{|
|style="vertical-align:top"|
* NI Ettus USRP X410 or X440
* DC Power Supply (12V, 20A)
* 1 Gigabit Ethernet Cat-5e Cable (3m)
* USB-A to USB-C Cable (1m)
* Getting Started Guide URL (QR Code)
* Safety, Environmental, and Regulatory Information
||[[File:X410.jpg|450px|center]]
||[[File:X440.jpg|450px|center]]
|}

==USRP X440 Design Considerations==
* https://kb.ettus.com/About_Sampling_Rates_and_Master_Clock_Rates_for_the_USRP_X440

==You Will Need==
* For Network Mode: A host computer with an available 1 or 10 Gigabit Ethernet interface for sample streaming. In addition to the Ethernet interface used for sampling streaming, your host computer will require a separate 1 Gigabit Ethernet interface for command and control streaming.

* For Stand-Alone Embedded Mode: A host computer with an available 1 Gigabit Ethernet port or a USB 2.0 port to remotely access the embedded Linux operating system running on ARM CPU.

==Proper Care and Handling==

All Ettus Research products are individually tested before shipment. The USRP is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP can cause the device to become non-functional. Take the following precautions to prevent damage to the unit.

* Never allow metal objects to touch the circuit board while powered.
* Always properly terminate the transmit port with an antenna or 50Ω load.
* Always handle the board with proper anti-static methods.
* Never allow the board to directly or indirectly come into contact with any voltage spikes.
* Never allow any water or condensing moisture to come into contact with the device.
* Always use caution with FPGA, firmware, or software modifications.

{|
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |X410: Never apply more than +14 dBm continuous <=3GHz, +17 dBm continuous >3GHz, or +20dBm more than 5 minutes >3GHz of power into any RF input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |X440: Never apply more than +13 dBm continuous <=2.5GHz, +17 dBm continuous between 2.5GHz and 3.6 GHz, or +20dBm continuous between 3.6 GHz and 4 GHz of power into any RF input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |X410: Always use at least 30dB attenuation if operating in loopback configuration.
|-
|}

==Install and Setup the Software Tools on Your Host Computer==
In order to use your Universal Software Radio Peripheral (USRP™), you must have the software tools correctly installed and configured on your host computer. The easiest way to install USRP Hardware Driver (UHD) is by getting a binary installer package for your operating system as described in the UHD manual about [https://files.ettus.com/manual/page_install.html Binary Installation]. If no binary packages are available for your operating system or you want to modify the sources by yourself, a step-by-step guide is available at the Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on [[Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on Linux|Linux]], [[Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on OS X|OS X]] and [[Building and Installing the USRP Open Source Toolchain (UHD and GNU Radio) on Windows|Windows]] Application Notes.

To find the latest release of UHD, see the UHD repository at https://github.com/EttusResearch/uhd.

The USRP X410 requires UHD version 4.1 or later.
The USRP X440 requires UHD version 4.5 or later.

'''When you receive a brand-new device, it is strongly recommended that you download the latest filesystem image from the Ettus Research website update the unit. It is not recommended that you use the filesystem from the factory as-is. Instructions on downloading the latest filesystem image and updating it is listed below.'''

'''Note that if you are operating the device in Network Mode, the version of UHD running on the host computer and the USRP X4x0 must match.'''

==Assembling the X4x0==
Inside the kit you will find the X4x0 and an X4x0 power supply. Plug these in, connect the 1GbE RJ45 interface to your network, and power on the device by pressing the power button.

==The STM32 Microcontroller==

The STM32 microcontroller (also referred to as the "SCU") controls various low-level features of the X4x0 series motherboard: It controls the power sequencing, reads out fan speeds and some of the temperature sensors. It is connected to the RFSoC via an I2C bus. It is running software based on Chromium EC.

It is possible to log into the STM32 using the serial interface (see Connecting to the Microcontroller). This will allow certain low-level controls, such as remote power cycling should the CPU have become unresponsive for whatever reason.

===Updating the SCU===

The writable SCU image file is stored on the filesystem under /lib/firmware/ni/ec-titanium-revX.RW.bin (where X is a revision compatibility number). To update, simply replace the .bin file with the updated version and reboot.

==eMMC Storage==

The main non-volatile storage of the USRP is a 16 GB eMMC storage. This storage can be made accessible as a USB Mass Storage device through the USB-OTG connector on the back panel.

The entire root file system (Linux kernel, libraries) and any user data are stored on the eMMC. It is partitioned into four partitions:

Boot partition (contains the bootloader). This partition usually does not require modification.
A data partition, mounted in /data. This is the only partition that is not erased during file system updates.
Two identical system partitions (root file systems). These contain the operating system and the home directory (anything mounted under / that is not the data or boot partition). The reason there are two of these is to enable remote updates: An update running on one partition can update the other one without any effect to the currently running system. Note that the system partitions are erased during updates and are thus unsuitable for permanently storing information.
Note: It is possible to access the currently inactive root file system by mounting it. After logging into the device using serial console or SSH (see the following two sections), run the following commands:

<pre>
$ mkdir temp

$ mount /dev/mmcblk0p3 temp # This assumes mmcblk0p3 is currently not mounted

$ ls temp # You are now accessing the idle partition:

bin data etc lib media proc sbin tmp usr
boot dev home lost+found mnt run sys uboot var
</pre>

The device node in the mount command might differ, depending on which partition is currently already mounted.

==USB Access to eMMC==

While Mender should be used for routine filesystem updates (see Updating Filesystems), it is also possible to access the X4x0's internal eMMC from an external host over USB. This allows accessing or modifying the filesystem, as well as the ability to flash the device with an entirely new filesystem.

In order to do so, you'll need an external computer with two USB ports, and two USB cables to connect the computer to your X4x0. The instructions below assume a Linux host.

First, connect to the APU serial console at a baud rate of 115200. Boot the device, and stop the boot sequence by typing noautoboot at the prompt. Then, run the following command in the U-boot command prompt:

<code>ums 0 mmc 0</code>

This will start the USB mass storage gadget to expose the eMMC as a USB mass storage device. You should see a spinning indicator on the console, which indicates the gadget is active.

Next, connect your external computer to the X4x0's USB to PS port using an OTG cable. Your computer should recognize the X4x0 as a mass storage device, and you should see an entry in your kernel logs (dmesg) that looks like this:

<pre>
usb 3-1: New USB device found, idVendor=3923, idProduct=7a7d, bcdDevice= 2.23
usb 3-1: New USB device strings: Mfr=1, Product=2, SerialNumber=0
usb 3-1: Product: USB download gadget
usb 3-1: Manufacturer: National Instruments
sd 6:0:0:0: [sdc] 30932992 512-byte logical blocks: (15.8 GB/14.8 GiB)
sdc: sdc1 sdc2 sdc3 sdc4
sd 6:0:0:0: [sdc] Attached SCSI removable disk
</pre>

The exact output will depend on your machine, but from this log you can see that the X4x0 was recognized and /dev/sdc is the block device representing the eMMC, with 4 partitions detected (see eMMC Storage for details on the partition layout).

It is now possible to treat the X4x0's eMMC as you would any other USB drive: the individual partitions can be mounted and accessed, or the entire block device can be read/written.

Once you're finished accessing the device over USB, the u-boot gadget may be stopped by hitting Ctrl-C at the APU serial console.

== Flashing the eMMC ==

Once the X4x0's eMMC is accessible over USB, it's possible to write the filesystem image and thus change the device's filesystem. You can obtain the latest filesystem image by running:

<code>uhd_images_downloader -t sdimg -t x4xx</code>

The output of this command will indicate where the downloaded images were put, or specify a custom location using using the <code>-i INSTALL_LOCATION</code> argument.

There are 2 ways to write the image to the X4x0's eMMC: using <code>dd</code> and <code>bmaptool</code>. Run one of the following commands, replacing <code>/dev/sdX</code> with the block device of the X4x0's eMMC (found in the device's kernel log or by running <code>lsblk</code>). Take care to use the correct block device or else you might overwrite the wrong drive!

<code>sudo dd if=/path/to/usrp_x4xx_fs.sdimg of=/dev/sdX bs=1M</code>

<code>sudo bmaptool copy --bmap /path/to/usrp_x4xx_fs.sdimg.bmap /path/to/usrp_x4xx_fs.sdimg /dev/sdX</code>

The former is generally preferred as it will always work, even if it slower than the latter.

==Using a USRP X4x0 from UHD==
Like any other USRP, all X4x0 USRPs are controlled by the UHD software. To integrate a USRP X4x0 into your C++ application, you would generate a UHD device in the same way you would for any other USRP:

<code>auto usrp = uhd::usrp::multi_usrp::make("type=x4xx");</code>

For a list of which arguments can be passed into make(), see Section Device Arguments.

==Updating Filesystems==

Mender is a third-party software that enables remote updating of the root file system without physically accessing the device (see also the [https://mender.io/ Mender website]). Mender can be executed locally on the device, or a Mender server can be set up which can be used to remotely update an arbitrary number of USRP devices. Mender servers can be self-hosted, or hosted by Mender (see mender.io for pricing and availability).

When updating the file system using Mender, the tool will overwrite the root file system partition that is not currently mounted (note: the onboard flash storage contains two separate root file system partitions, only one is ever used at a single time). Any data stored on that partition will be permanently lost, including the currently loaded FPGA image. After updating that partition, it will reboot into the newly updated partition. Only if the update is confirmed by the user, the update will be made permanent. This means that if an update fails, the device will be always able to reboot into the partition from which the update was originally launched (which presumably is in a working state). Another update can be launched now to correct the previous, failed update, until it works.

To obtain the file system Mender image (these are files with a <code>.mender</code> suffix), run the following command on the host computer with Internet access:

$ sudo uhd_images_downloader -t mender -t x4xx --yes

NOTE: In the output of the command, the folder destination where the images are saved is printed out.

Next, you will need to copy this Mender file system image to the USRP X4xx. This can be done with the Linux utility <code>scp</code>.

$ scp /usr/local/share/uhd/images/usrp_x4xx_fs.mender root@192.168.1.51:~/.

Note: The path and IP may different for your configuration, the command above assumes you're using the default installation path of <code>/usr/local</code> and that the X4xx's IP is <code>192.168.1.51</code>.

After copying the Mender file system image to the X4xx, connect to the X4xx using either the Serial Console, or via SSH to gain shell access.

On the X4xx, run <code>mender install /path/to/latest.mender</code> to update the file system:

$ mender install /home/root/usrp_x4xx_fs.mender

The artifact can also be stored on a remote server:
$ mender install <nowiki>http://server.name/path/to/latest.mender</nowiki>

This procedure will take a few minutes to complete. After mender has logged a successful update, reboot the device:
$ reboot

If the reboot worked, and the device seems functional, commit the changes so that the boot loader knows to permanently boot into this partition:
$ mender -commit

To identify the currently installed Mender artifact from the command line, the following file can be queried on the X4x0:
$ cat /etc/mender/artifact_info

If you are using a Mender server, the updates can be initiated from a web dashboard. From there, you can start the updates without having to log into the device, and you can update groups of USRPs with a few clicks in a web GUI. The dashboard can also be used to inspect the state of USRPs. This is a simple way to update groups of rack-mounted USRPs with custom file systems.

If you are running a hosted server, the updates can be initiated from a web dashboard. From there, you can start the updates without having to log into the device, and can update groups of USRPs with a few clicks in a web GUI. The dashboard can also be used to inspect the state of USRPs. This is a simple way to update groups of rack-mounted USRPs with custom file systems.

==Network Interfaces==
The Ettus USRP X4x0 has various network interfaces:

eth0: RJ45 port.

The RJ45 port comes up with a default configuration of DHCP, that will request a network address from your DHCP server (if available on your network). This interface is agnostic of FPGA image flavor.

int0: internal interface for network communication between the embedded ARM processor and FPGA.

The internal network interface is configured with a static address: 169.254.0.1/24. This interface is agnostic of FPGA image flavor.

sfpX [, sfpX_1, sfpX_2, sfpX_3]: QSFP28 network interface(s), up-to four (one per lane) based on implemented protocol.

Each QSFP28 port has four high-speed transceiver lanes. Therefore, depending on the FPGA image flavor, up-to four different network interfaces may exist per QSFP28 port, using the sfpXfor the first lane, and sfpX_1-3 for the other three lanes. Each network interface has a default static IP address. Note that for multi-lane protocols, such as 100 GbE, a single interface is used (sfpX).
The configuration files for these network interfaces are stored in: <code>/data/network/</code>

{| class="wikitable"
|-
! Interface Name
! Description
! Default Configuration
! Configuration File
! Example: X4_200/X4_400 FPGA image
|-
| eth0
| RJ45
| style="vertical-align:middle; background-color:#FFF;" | DHCP
| style="vertical-align:middle; background-color:#FFF;" | eth0.network
| DHCP
|-
| int0
| Internal
| style="vertical-align:middle; background-color:#FFF;" | 169.254.0.1/24
| style="vertical-align:middle; background-color:#FFF;" | int0.network
| style="vertical-align:middle; background-color:#FFF;" | 169.254.0.1/24
|-
| sfp0
| QSFP28 0 (4-lanes interface or lane 0)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.10.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.10.2/24
|-
| style="background-color:#FFF;" | sfp0_1
| QSFP28 0 (lane 1)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.11.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_1.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.11.2/24
|-
| style="background-color:#FFF;" | sfp0_2
| QSFP28 0 (lane 2)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.12.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_2.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.12.2/24
|-
| sfp0_3
| QSFP28 0 (lane 3)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.13.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp0_3.network
| style="vertical-align:middle; background-color:#FFF;" | 192.168.13.2/24
|-
| sfp1
| QSFP28 1 (4-lanes interface or lane 0)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.20.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| sfp1_1
| QSFP28 1 (lane 1)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.21.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_1.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| style="background-color:#FFF;" | sfp1_2
| QSFP28 1 (lane 2)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.22.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_2.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
| style="background-color:#FFF;" | sfp1_3
| QSFP28 1 (lane 3)
| style="vertical-align:middle; background-color:#FFF;" | 192.168.23.2/24
| style="vertical-align:middle; background-color:#FFF;" | sfp1_3.network
| style="vertical-align:middle; background-color:#FFF;" | N/C
|-
|}

==Network Connectivity==
Once the X4x0 has booted, determine the IP address and verify network connectivity by running uhd_find_devices on the host computer:

X410:
<pre>
$ uhd_find_devices

-- UHD Device 0

Device Address:
serial: 1234ABC
addr: 10.2.161.10
claimed: False
mgmt_addr: 10.2.161.10
product: x410
type: x4xx
</pre>

X440:
<pre>
$ uhd_find_devices

-- UHD Device 0

Device Address:
serial: 1234ABC
addr: 10.2.161.10
claimed: False
mgmt_addr: 10.2.161.10
product: x440
type: x4xx
</pre>

By default, an X4x0 will use DHCP to attempt to find an address.

At this point, you should run:

<code>uhd_usrp_probe --args addr=<IP address></code>
to ensure functionality of the device.

Note: If you receive the following error:

<code>Error: RuntimeError: Graph edge list is empty for rx channel 0</code>
then you will need to download a UHD-compatible FPGA as described in Updating the FPGA or using the following command (it assumes that FPGA images have been downloaded previously using uhd_images_downloader, or that the command is run on the device itself):

X410:
<code>uhd_image_loader --args type=x4xx,addr=<ip address>,fpga=X4_200</code>

X440:
<code>uhd_image_loader --args type=x4xx,addr=<ip address>,fpga=X4_400</code>

When running on the device, use <code>127.0.0.1</code> as the IP address.

You can now use existing UHD examples or applications (such as rx_sample_to_file, rx_ascii_art_dft, or tx_waveforms) or other UHD-compatible applications to start receiving and transmitting with the device.

See Network Interfaces for further details on the various network interfaces available on the X4x0.

===Network Status LEDs===
The Ettus USRP X4x0 is equipped with status LEDs for its network-capable ports: RJ45 and QSFP28s, see RJ45 LED Behavior and QSFP28 LED Behavior accordingly.

====RJ45 LED Behavior====
The RJ45 port has two independent LEDs: green (right) and yellow (left). The table below summarizes the LEDs' behavior. Note that link speed indication is not currently supported.

{| class="wikitable"
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
! Link / Activity
! Green LED
! Yellow LED
|-
| style="vertical-align:middle; background-color:#FFF;" | No Link
| Off
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / No Activity
| On
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / Activity
| On
| Blinking
|}

====QSFP28 LED Behavior====
Each QSFP28 connector has four LEDs, one for each high-speed transceiver lane. The table below summarizes the LEDs' behavior, note that for multi-lane protocols, such as 100 GbE, the corresponding LEDs are ganged together. Within the same image, multiple speeds on the same port (e.g., both 10 GbE and 100 GbE) are not supported, therefore link speed indication is not supported.

{| class="wikitable"
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
! Link / Activity
! QSFP28 LED (4 Total)
|-
| style="vertical-align:middle; background-color:#FFF;" | No Link
| Off
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / No Activity
| Green (solid)
|-
| style="vertical-align:middle; background-color:#FFF;" | Link / Activity
| Amber (blinking)
|}

==Security-related Settings==
The X4x0 ships without a root password set. It is possible to ssh into the device by simply connecting as root, and thus gaining access to all subsystems. To set a password, run the command

<code>$ passwd</code>
on the device.

==Serial Connection==
It is possible to gain access to the device using a serial terminal emulator. To do so, the USB debug port needs to be connected to a separate computer to gain access. Most Linux, OSX, or other Unix flavors have a tool called 'screen' which can be used for this purpose, by running the following command:

<code>$ sudo screen /dev/ttyUSB2 115200</code>
In this command, we prepend 'sudo' to elevate user privileges (by default, accessing serial ports is not available to regular users), we specify the device node (in this case, /dev/ttyUSB2), and the baud rate (115200).

The exact device node depends on your operating system's driver and other USB devices that might be already connected. Modern Linux systems offer alternatives to simply trying device nodes; instead, the OS might have a directory of symlinks under /dev/serial/by-id:

<pre>$ ls /dev/serial/by-id
usb-Digilent_Digilent_USB_Device_2516351DDCC0-if02-port0
usb-Digilent_Digilent_USB_Device_2516351DDCC0-if03-port0
</pre>

Note: Exact names depend on the host operating system version and may differ.

The first (with the if02 suffix) connects to the STM32 microcontroller (SCU), whereas the second (with the if03 suffix) connects to Linux running on the RFSoC APU.

<code>$ sudo screen /dev/serial/by-id/usb-Digilent_Digilent_USB_Device_2516351DDCC0-if03-port0 115200</code>
After entering the username root (no password is set by default), you should be presented with a shell prompt similar to the following:

<code>root@ni-x4xx-1234ABC:~#</code>
On this prompt, you can enter any Linux command available. Using the default configuration, the serial console will also show all kernel log messages (unlike when using SSH, for example), and give access to the boot loader (U-boot prompt). This can be used to debug kernel or bootloader issues more efficiently than when logged in via SSH.

==Connecting to the Microcontroller==
The microcontroller (which controls the power sequencing, among other things) also has a serial console available. To connect to the microcontroller, use the other UART device. In the example above:

<code>$ sudo screen /dev/serial/by-id/usb-Digilent_Digilent_USB_Device_2516351DDCC0-if02-port0 115200</code>

It provides a very simple prompt. The command 'help' will list all available commands. A direct connection to the microcontroller can be used to hard-reset the device without physically accessing it and other low-level diagnostics. For example, running the command reboot will emulate a reset button press, resetting the state of the device, while the command powerbtn will emulate a power button press, turning the device back on again.

==SSH Connection==
The USRP X4x0 has two network connections: The dual QSFP28 ports, and an RJ45 connector. The latter is by default configured by DHCP; by plugging it into into 1 Gigabit switch on a DHCP-capable network, it will get assigned an IP address and thus be accessible via ssh.

In case your network setup does not include a DHCP server, refer to the section Serial Connection. A serial login can be used to assign an IP address manually.

After the device obtained an IP address you can log in from a Linux or OSX machine by typing:

<code>$ ssh root@ni-x4xx-1234ABC # Replace with your actual device name!</code>
Depending on your network setup, using a .local domain may work:

<code>$ ssh root@ni-x4xx-1234ABC.local</code>
Of course, you can also connect to the IP address directly if you know it (or set it manually using the serial console).

Note: The device's hostname is derived from its serial number by default (<code>ni-x4xx-$SERIAL</code>). You can change the hostname by creating the file <code>/data/network/hostname</code>, saving the desired hostname in it, then rebooting.

On Microsoft Windows, the connection can be established using a tool such as PuTTY, by selecting a username of root without password.

Like with the serial console, you should be presented with a prompt like the following:

<code>root@ni-x4xx-1234ABC:~#</code>

== Autoboot ==

The USRP X4x0 can be configured to power on and boot automatically when power is applied. This setting can be controlled using the <code>eeprom-set-autoboot</code> script. This script is executed directly on the USRP X4x0. To enable autoboot, run <code>eeprom-set-autoboot on</code>; to disable autoboot, run <code>eeprom-set-autoboot off</code>.

==Updating the FPGA==

The FPGA can be updated simply using uhd_image_loader:

<code>uhd_image_loader --args type=x4xx,addr=<IP address of device> --fpga-path <path to .bit></code>
or

<code>uhd_image_loader --args type=x4xx,addr=<IP address of device>,fpga=FPGA_TYPE</code>
A UHD install will likely have pre-built images in /usr/share/uhd/images/. Up-to-date images can be downloaded using the uhd_images_downloader script:

<code>uhd_images_downloader</code>
will download images into /usr/share/uhd/images/ (the path may differ, depending on how UHD was installed).

Also note that the USRP already ships with compatible FPGA images on the device - these images can be loaded by SSH'ing into the device and running:

X410:
<code>uhd_image_loader --args type=x4xx,mgmt_addr=127.0.0.1,fpga=X4_200</code>

X440:
<code>uhd_image_loader --args type=x4xx,mgmt_addr=127.0.0.1,fpga=X4_400</code>

==FPGA Image Flavors==
Unlike the USRP X310 or other third-generation USRP devices, the FPGA image flavors do not only encode how the QSFP28 connectors are configured, but also which master clock rates are available. This is because the data converter configuration is part of the FPGA image (the ADCs/DACs on the X4x0 are on the same die as the FPGA). The image flavors consist of two short strings, separated by an underscore, e.g. X4_200 (X410) or X4_400 (X440) is an image flavor which contains 4x 10 GbE, and can handle an analog bandwidth of 200 MHz or 400 MHz respectively. The first two characters describe the configuration of the QSFP28 ports: 'X' stands for 10 GbE, 'C' stands for 100 GbE. For details see [https://files.ettus.com/manual/page_usrp_x4xx.html#x4xx_updating_fpga_types FPGA Image Flavor] in the [https://files.ettus.com/manual USRP Hardware Driver and USRP Manual].

The analog bandwidth determines the available master clock rates.

X410: As of UHD 4.1, only the X4_200 image is shipped with UHD, which allows a 245.76 MHz or 250 MHz master clock rate. With UHD 4.2, the CG_400 image was added allowing for 491.52 MHz and 500 MHz master clock rates. With UHD 4.5, the UC_200 image (245.76 MHz and 250 MHz master clock rate) was added.

X440: As of UHD 4.5, UHD ships with X4_400, X4_1600, CG_400 and CG_1600 images. The X4_400 and CG_400 images allow master clock rates between 125 MHz and 512 MHz and the usage of all 8 channels while the X4_1600 and CG_1600 images allow master clock rates between 125 MHz and 2048 MHz but only the usage of channels 0 and 4.

Any other images are considered experimental (unsupported).

==Device Arguments==

{| class="wikitable" style="vertical-align:middle;"
|- style="font-weight:bold; text-align:center;"
! Key
! Description
! Example Value
|-
| addr
| IPv4 address of primary SFP+ port to connect to.
| addr=192.168.30.2
|-
| second_addr
| IPv4 address of secondary SFP+ port to connect to.
| second_addr=192.168.40.2
|-
| mgmt_addr
| IPv4 address or hostname to which to connect the RPC client. Defaults to `addr'.
| mgmt_addr=ni-sulfur-311FE00
|-
| find_all
| When using broadcast, find all devices, even if unreachable via CHDR.
| find_all=1
|-
| master_clock_rate
| Master Clock Rate in Hz.
| master_clock_rate=250e6
|-
| converter_rate
| Converter Rate in Hz. Only X440 and together with master_clock_rate.
| master_clock_rate=250e6,converter_rate=1000e6
|-
| serialize_init
| Force serial initialization of daughterboards.
| serialize_init=1
|-
| skip_init
| Skip the initialization process for the device.
| skip_init=1
|-
| time_source
| Specify the time (PPS) source.
| time_source=internal
|-
| clock_source
| Specify the reference clock source.
| clock_source=internal
|-
| ref_clk_freq
| Specify the external reference clock frequency, default is 10 MHz.
| ref_clk_freq=20e6
|-
| discovery_port
| Override default value for MPM discovery port.
| discovery_port=49700
|-
| rpc_port
| Override default value for MPM RPC port.
| rpc_port=49701
|}

This is only a subset of the existing device arguments. For a complete list please consult the [https://files.ettus.com/manual/page_usrp_x4xx.html#x4xx_usage_args UHD user manual of the X4x0 device series].

==GPS==

The USRP X4x0 includes a Jackson Labs LTE-Lite GPS module. Its antenna port is on the rear panel (see Front and Back Panels). When the X4x0 has access to GPS satellite signals, it can use this module to read out the current GPS time and location as well as to discipline an onboard OCXO.

To use the GPS as a clock and time reference, simply use gpsdo as a clock or time source. Alternatively, set gpsdo as a synchronization source:

<pre>
// Set clock/time individually:
usrp->set_clock_source("gpsdo");
usrp->set_time_source("gpsdo");
// This is equivalent to the previous commands, but faster, as it sets
// both settings simultaneously and avoids duplicating settings that are shared
// between these calls.
usrp->set_sync_source("clock_source=gpsdo,time_source=gpsdo");
</pre>

Note the GPS module is not always enabled. Its power-on status can be queried using the gps_enabled GPS sensor (see also The Sensor API). When disabled, none of the sensors will return useful (if any) values.

When selecting gpsdo as a clock source, the GPS will always be enabled. Note that acquiring a GPS lock can take some time after enabling the GPS, so if a UHD application is enabling the GPS dynamically, it might take some time before a GPS lock is reported.

==Front-Panel Programmable GPIOs==

The USRP X4x0 has two HDMI front-panel connectors, which are connected to the FPGA. For a
description of the GPIO control API, see the
[https://files.ettus.com/manual/page_x400_gpio_api.html USRP X4x0 GPIO UHD Manual Entry],
[https://files.ettus.com/manual/page_usrp_x4xx.html#x4xx_usage_gpio the USRP X4x0 Series Manual],
the [https://files.ettus.com/manual/page_zbx.html#zbx_atr ZBX ATR section] (X410) and the
[https://files.ettus.com/manual/page_fbx.html#fbx_atr FBX ATR section] (X440).

==Subdev Specifications==

The RF ports on the front panel of the X410 + ZBX correspond to the following subdev specifications:

{| class="wikitable"
|-
! Label
! style="text-align:center; vertical-align:middle; font-weight:bold;" | Subdev Spec
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 0
| A:0
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 1
| A:1
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 0
| B:0
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 1
| B:1
|}

The RF ports on the front panel of the X440 + FBX correspond to the following subdev specifications (for xx_400 FPGA images):

{| class="wikitable"
|-
! Label
! style="text-align:center; vertical-align:middle; font-weight:bold;" | Subdev Spec
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 0
| A:0
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 1
| A:1
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 2
| A:2
|- style="vertical-align:middle; background-color:#FFF;"
| DB 0 / RF 3
| A:3
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 0
| B:0
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 1
| B:1
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 2
| B:2
|- style="vertical-align:middle; background-color:#FFF;"
| DB 1 / RF 3
| B:3
|}

When using a xx_1600 FPGA image on X440, only A:0 and B:0 are available.

The subdev spec slot identifiers "A" and "B" are not reflected on the front panel. They were set to match valid subdev specifications of previous USRPs, maintaining backward compatibility.

These values can be used for uhd::usrp::multi_usrp::set_rx_subdev_spec() and uhd::usrp::multi_usrp::set_tx_subdev_spec() as with other USRPs.

==Rear Panel Status LEDs==

The USRP X4x0 is equipped with four LEDs located on the device's rear panel. Each LED supports four different states: Off, Green, Red, and Amber. One LED (PWR) indicates the device's power state (see Power LED below). The other three LEDs (LED 0, LED 1, and LED 2) are user-configurable, different behaviors are supported for each of these LEDs (see User-configurable LEDs below).

[[File:x4xx_rearpanel_status_leds.png|125px]]

===X4x0 Rear Panel Status LEDs===
Power LED
The USRP X4x0's PWR LED is reserved to visually indicate the user the device's power state. Power LED Behavior describes what each LED state represents.

===Power LED Behavior===

{| class="wikitable" style="background-color:#FFF;"
|- style="font-weight:bold; text-align:center;"
! PWR LED State
! style="vertical-align:middle;" | Meaning
|- style="vertical-align:middle;"
| Off
| No power is applied
|- style="vertical-align:middle;"
| Amber
| Power is good but X4x0 is powered off
|- style="vertical-align:middle;"
| Green
| Power is good and X4x0 is powered on
|- style="vertical-align:middle;"
| Red
| Power error state
|}

===User-configurable LEDs===
The USRP X4x0's user-configurable rear panel status LEDs (LED 0, LED 1, and LED 2) allow the user to have visual indication of various device conditions. Supported LED Behaviors provides a complete list of the supported behaviors for each user-configurable LED. By default, these LEDs are configured as described in LEDs Default Behavior.

The user may alter the default LEDs behavior either temporarily or persistently, see the Temporarily change the LED Behavior or Persistently in the UHD manual to change the LED Behavior accordingly.

https://files.ettus.com/manual/page_usrp_x4xx.html

==Technical Support and Community Knowledge Base==
Technical support for USRP hardware is available through email only. If the product arrived in a nonfunctional state or you require technical assistance, please contact [mailto:support@ettus.com support@ettus.com]. Please allow 24 to 48 hours for response by email, depending on holidays and weekends, although we are often able to reply more quickly than that.

We also recommend that you subscribe to the community mailing lists. The mailing lists have a responsive and knowledgeable community of hundreds of developers and technical users who are located around the world. When you join the community, you will be connected to this group of people who can help you learn about SDR and respond to your technical and specific questions. Often your question can be answered quickly on the mailing lists. Each mailing list also provides an archive of all past conversations and discussions going back many years. Your question or problem may have already been addressed before, and a relevant or helpful solution may already exist in the archive.

Discussions involving the USRP hardware and the UHD software itself are best addressed through the '''usrp-users''' mailing list at [http://usrp-users.ettus.com http://usrp-users.ettus.com].

Discussions involving the use of [http://gnuradio.org/ GNU Radio] with USRP hardware and UHD software are best addressed through the '''discuss-gnuradio''' mailing list at [https://lists.gnu.org/mailman/listinfo/discussgnuradio https://lists.gnu.org/mailman/listinfo/discussgnuradio].

Discussions involving the use of [http://openbts.org/ OpenBTS®] with USRP hardware and UHD software are best addressed through the '''openbts-discuss''' mailing list at [https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss].

The support page on our website is located at [https://www.ettus.com/support https://www.ettus.com/support]. The Knowledge Base is located at [https://kb.ettus.com https://kb.ettus.com].

==Legal Considerations==
Every country has laws governing the transmission and reception of radio signals. Users are solely responsible for insuring they use their USRP system in compliance with all applicable laws and regulations. Before attempting to transmit and/or receive on any frequency, we recommend that you determine what licenses may be required and what restrictions may apply.

*NOTE: This USRP product is a piece of test equipment.

==Sales and Ordering Support==
If you have any non-technical questions related to your order, then please contact us by email at [mailto:orders@ettus.com orders@ettus.com], or by phone at +14086106399 (Monday-Friday, 8 AM - 5 PM, Pacific Time). Please be sure to include your order number and the serial number of your USRP.

==Terms and Conditions of Sale==
Terms and conditions of sale can be accessed online at the following link: http://www.ettus.com/legal/terms-and-conditions-of-sale

[[Category:Getting Started Guides]]
[[Category:X4x0]]

Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on Linux

2024-02-22T10:59:01Z

MartinAnderseck: Add Ubuntu 22 dependencies, removing dependencies for Ubuntu 14.04 (will reach end of life in April this year and doesn't have standard support for years already), 15.*, 17.* and 18.10 (all three no LTS versions)

==Application Note Number==
'''AN-445'''

==Abstract==
This Application Note provides a comprehensive guide for building, installing, and maintaining the open-source toolchain for the USRP (UHD and GNU Radio) from source code on the Linux platform. The Ubuntu and Fedora distributions are specifically discussed. Several other alternate installation methods are also discussed.

http://files.ettus.com/manual/page_build_guide.html#build_instructions_unix

==UHD on Linux==

UHD is fully supported on Linux, using the GCC compiler, and should work on most major Linux distributions.

==Devices==
This document applies only to the USRP X300, X310, B200, B210, B200mini, N200, N210 devices. The E310 and E312 devices are embedded devices, and are fundamentally different from the other non-embedded USRP devices, and are not addressed by this document.

==Install Linux==

If you already have a recent version of Linux installed, then you may be able to skip this section. If you are starting from scratch, or simply want to start with a fresh new installation of Linux, then please follow the instructions and recommendations in this section.

We suggest that you use either Ubuntu 16.04.5, Ubuntu 18.04, Ubuntu 18.10, Fedora 27, 28, 29, and that you use a 64-bit architecture, not a 32-bit architecture. There are several re-spins of Ubuntu, such as Xubuntu, Lubuntu, Kubuntu, Linux Mint, all of which should also work. For the purposes of this document, these re-spins can be considered equivalent. Both Ubuntu and Fedora are known to work well with UHD and GNU Radio.

Download and install Ubuntu, Xubuntu, Linux Mint, or Fedora from the links below. Download the appropriate ISO image, and write it to a USB flash drive. Be sure to verify that the ISO file was not corrupted during the download process by checking the MD5 and/or SHA1 hash.

* [http://www.ubuntu.com/download/desktop Ubuntu download page]
* [http://www.xubuntu.org/getxubuntu/ Xubuntu download page]
* [https://www.linuxmint.com/download.php Linux Mint download page]
* [https://getfedora.org/en/workstation/download/ Fedora download page]

You can learn more about Ubuntu, Xubuntu, Linux Mint, and Fedora at the links below.

* [https://en.wikipedia.org/wiki/Ubuntu_%28operating_system%29 Wikipedia article on Ubuntu]
* [https://en.wikipedia.org/wiki/Xubuntu Wikipedia article on Xubuntu]
* [https://en.wikipedia.org/wiki/Linux_Mint Wikipedia article on Linux Mint]
* [https://en.wikipedia.org/wiki/Fedora_%28operating_system%29 Wikipedia article on Fedora]

There are many tools for writing an ISO image to a USB flash drive. In Linux, you can use the "dd" utility, or the UNetbootin utility. On Ubuntu systems, there is also the Startup Disk Creator utility as well.

* [http://unetbootin.sourceforge.net/ UNetbootin homepage]
* [http://en.wikipedia.org/wiki/UNetbootin Wikipedia article on UNetbootin]

* [https://launchpad.net/usb-creator Startup Disk Creator homepage]
* [https://en.wikipedia.org/wiki/Startup_Disk_Creator Wikipedia article on Startup Disk Creator]
* [http://www.ubuntu.com/download/desktop/create-a-usb-stick-on-ubuntu Article about Startup Disk Creator]

Be sure to use a USB flash drive with at least 8 GB capacity, and use a USB 3.0 flash drive, not a USB 2.0 flash drive. If you use a slower USB 2.0 flash drive, then the install process will take significantly longer.

==Update and Install dependencies==

Before building UHD and GNU Radio, you need to make sure that all the dependencies are first installed.

However, before installing any dependencies, you should first make sure that all the packages that are already installed on your system are up-to-date. You can do this from a GUI, or from the command-line, as shown below.

On Ubuntu systems, run:

sudo apt-get update

On Fedora 21 systems, run:

sudo yum update

On Fedora 22, 23, 24 and 25 systems, run:

sudo dnf update

Once the system has been updated, then install the required dependencies for UHD and GNU Radio.

On Ubuntu 22.04 systems, run:

sudo apt-get -y install autoconf automake build-essential ccache cmake cpufrequtils doxygen ethtool fort77 g++ gir1.2-gtk-3.0 git gobject-introspection gpsd gpsd-clients inetutils-tools libasound2-dev libboost-all-dev libcomedi-dev libcppunit-dev libfftw3-bin libfftw3-dev libfftw3-doc libfontconfig1-dev libgmp-dev libgps-dev libgsl-dev liblog4cpp5-dev libncurses5 libncurses5-dev libpulse-dev libqt5opengl5-dev libqwt-qt5-dev libsdl1.2-dev libtool libudev-dev libusb-1.0-0 libusb-1.0-0-dev libusb-dev libxi-dev libxrender-dev libzmq3-dev libzmq5 ncurses-bin python3-cheetah python3-click python3-click-plugins python3-click-threading python3-dev python3-docutils python3-gi python3-gi-cairo python3-gps python3-lxml python3-mako python3-numpy python3-opengl python3-pyqt5 python3-requests python3-scipy python3-setuptools python3-six python3-sphinx python3-yaml python3-zmq python3-ruamel.yaml swig wget

On Ubuntu 20.04 systems, run:

sudo apt-get -y install autoconf automake build-essential ccache cmake cpufrequtils doxygen ethtool fort77 g++ gir1.2-gtk-3.0 git gobject-introspection gpsd gpsd-clients inetutils-tools libasound2-dev libboost-all-dev libcomedi-dev libcppunit-dev libfftw3-bin libfftw3-dev libfftw3-doc libfontconfig1-dev libgmp-dev libgps-dev libgsl-dev liblog4cpp5-dev libncurses5 libncurses5-dev libpulse-dev libqt5opengl5-dev libqwt-qt5-dev libsdl1.2-dev libtool libudev-dev libusb-1.0-0 libusb-1.0-0-dev libusb-dev libxi-dev libxrender-dev libzmq3-dev libzmq5 ncurses-bin python3-cheetah python3-click python3-click-plugins python3-click-threading python3-dev python3-docutils python3-gi python3-gi-cairo python3-gps python3-lxml python3-mako python3-numpy python3-numpy-dbg python3-opengl python3-pyqt5 python3-requests python3-scipy python3-setuptools python3-six python3-sphinx python3-yaml python3-zmq python3-ruamel.yaml swig wget

On Ubuntu 18.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.14-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwtplot3d-qt5-dev pyqt4-dev-tools python-qwt5-qt4 cmake git wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq libqwt-dev libqwt6abi1 python-six libgps-dev libgps23 gpsd gpsd-clients python-gps python-setuptools

On Ubuntu 16.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0v5 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git-core libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq-dev libzmq1 python-requests python-sphinx libcomedi-dev python-zmq python-setuptools

On Fedora 21 systems, run:

sudo yum -y groupinstall "Engineering and Scientific" "Development Tools" "Software Development Tools" "C Development Tools and Libraries"

sudo yum -y install fftw-devel cppunit-devel wxPython-devel boost-devel alsa-lib-devel numpy gsl-devel python-devel pygsl python-cheetah python-mako python-lxml PyOpenGL qt-devel qt qt4 qt4-devel PyQt4-devel qwt-devel qwtplot3d-qt4-devel libusbx-devel cmake git wget python-docutils cppzmq-devel PyQwt PyQwt-devel qwt-devel gtk2-engines xmlrpc-c-"*" tkinter orc orc-devel python-sphinx SDL-devel swig zeromq2-devel python-zmq comedilib comedilib-devel thrift-devel python-thrift scipy zeromq zeromq-devel

On Fedora 22, 23, 24 and 25 systems, run:

sudo dnf -y groupinstall "Engineering and Scientific" "Development Tools" "C Development Tools and Libraries"

sudo dnf -y install fftw-devel cppunit-devel wxPython-devel boost-devel alsa-lib-devel numpy gsl-devel python-devel pygsl python-cheetah python-mako python-lxml PyOpenGL qt-devel PyQt4-devel qwt-devel qwtplot3d-qt4-devel libusbx-devel cmake python-docutils PyQwt PyQwt-devel gtk2-engines xmlrpc-c-"*" tkinter orc-devel python-sphinx SDL-devel swig perl-ZMQ-LibZMQ2 perl-ZMQ-LibZMQ2 zeromq zeromq-devel python-requests gcc-c++ doxygen zeromq-ada-devel cppzmq-devel perl-ZeroMQ amavisd-new-zeromq amavisd-new-snmp-zeromq php-zmq python-zmq czmq uwsgi-logger-zeromq comedilib comedilib-devel pygtk2 ncurses-"*" thrift-devel python-thrift scipy

After installing the dependencies, you should reboot the system.

If the installation of the dependencies completes without any errors, then you can proceed to build and install UHD and GNU Radio.

==Building and installing UHD from source code==

UHD is open-source, and is hosted on GitHub. You can browse the code online at the link below, which points to version 3.14.0.0, which is the the latest release at the time of this writing.

* [https://github.com/EttusResearch/uhd/tree/v3.14.0.0 UHD repository on GitHub]

There are several good reasons to build GNU Radio from source code, especially for doing development and prototyping. It it enables an easy way to customize the location of the installation, and to install multiple UHD versions in parallel, and switch between them. It also provides much more flexibility in upgrading and downgrading versions, and allows the user to modify the code and create customized versions, which could possibly include a patch or other bug-fix.

To build UHD from source code, clone the GitHub repository, check out a branch or tagged release of the repository, and build and install. Please follow the steps below. Make sure that no USRP device is connected to the system at this point.

First, make a folder to hold the repository.

cd $HOME
mkdir workarea
cd workarea

Next, clone the repository and change into the cloned directory.

git clone <nowiki>https://github.com/EttusResearch/uhd</nowiki>
cd uhd

Next, checkout the desired UHD version. You can get a full listing of tagged releases by running the command:

git tag -l

''Example truncated output of <code>git tag -l</code>:''

<pre>
$ git tag -l
...
release_003_009_004
release_003_009_005
release_003_010_000_000
...
</pre>

'''Note''': As of UHD Version 3.10.0.0, the versioning scheme has changed to be a quadruplet format. Each element and version will follow the format of: '''Major.API.ABI.Patch'''. Additional details on this versioning change can be found [https://files.ettus.com/manual/page_semver.html here].

After identifying the version and corresponding release tag you need, check it out:

# Example: For UHD 3.9.5:
git checkout release_003_009_005

# Example: For UHD 3.14.0.0
git checkout v3.14.0.0

Next, create a build folder within the repository.

cd host
mkdir build
cd build

Next, invoke CMake.

cmake ..

'''Note''': By default, UHD will be installed into the prefix <code>/usr/local</code>. This can be changed by adding <code>-DCMAKE_INSTALL_PREFIX=XXX</code> to install into the prefix <code>XXX</code>.

'''Note''': if the shell <code>PATH</code> is set such that <code>/bin</code> comes before <code>/usr/bin</code>, then this step is likely to fail because cmake will set the <code>FIND_ROOT_PATH</code> to <code>/</code> and this setting will fail as a prefix for Boost headers or libraries. The cmake output will include messages such as

-- Boost include directories: /include
-- Boost library directories: /lib/x86_64-linux-gnu

and

CMake Error in lib/CMakeLists.txt:
Imported target "Boost::chrono" includes non-existent path
"/include"
in its INTERFACE_INCLUDE_DIRECTORIES. Possible reasons include:
* The path was deleted, renamed, or moved to another location.
* An install or uninstall procedure did not complete successfully.
* The installation package was faulty and references files it does not provide.

One of the following 3 options should fix this situation:

1. <code>/usr/bin/cmake ..</code>
2. <code>PATH=/usr/bin:$PATH cmake ..</code>
3. <code>cmake -DCMAKE_FIND_ROOT_PATH=/usr ..</code>

Once the cmake command succeeds without errors, build UHD.

make

'''Note''': Use the <code>-j</code> parameter to use more than the default one CPU core, e.g. <code>make -j8</code> for 8 CPU cores.

Next, you can optionally run some basic tests to verify that the build process completed properly.

make test

Next, install UHD, using the default install prefix, which will install UHD under the /usr/local/lib folder. You need to run this as root due to the permissions on that folder.

sudo make install

Next, update the system's shared library cache.

sudo ldconfig

Finally, make sure that the <code>LD_LIBRARY_PATH</code> environment variable is defined and includes the folder under which UHD was installed. Most commonly, you can add the line below to the end of your <code>$HOME/.bashrc</code> file:

export LD_LIBRARY_PATH=/usr/local/lib

On Fedora 22/23/24/25 you will need to set the <code>LD_LIBRARY_PATH</code> to <code>/usr/local/lib64</code>.

export LD_LIBRARY_PATH=/usr/local/lib64

If the <code>LD_LIBRARY_PATH</code> environment variable is already defined with other folders in your <code>$HOME/.bashrc</code> file, then add the line below to the end of your <code>$HOME/.bashrc</code> file to preserve the current settings.

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

For Fedora 21/22/23/24/25

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib64

For this change to take effect, you will need to close the current terminal window, and open a new terminal.

At this point, UHD should be installed and ready to use. You can quickly test this, with no USRP device attached, by running <code>uhd_find_devices</code>. You should see something similar to the following.

<pre>
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

No UHD Devices Found
</pre>

===Downloading the UHD FPGA Images===
You can now download the UHD FPGA Images for this installation. This can be done by running the command <code>uhd_images_downloader</code>.

$ sudo uhd_images_downloader

Note: Since this installation is being installed to a system level directory (e.g. <code>/usr/local</code>), the <code>uhd_images_downloader</code> command requires <code>sudo</code> privileges.

Example ouput for UHD 3.13.3.0:

<pre>
$ sudo uhd_images_downloader
Images destination: /usr/local/share/uhd/images
Downloading images from: http://files.ettus.com/binaries/images/uhd-images_003.010.003.000-release.zip
Downloading images to: /tmp/tmpm46JDg/uhd-images_003.010.003.000-release.zip
57009 kB / 57009 kB (100%)

Images successfully installed to: /usr/local/share/uhd/images
</pre>

Example output for UHD 3.13:

<pre>
$ sudo uhd_images_downloader
[INFO] Images destination: /usr/local/share/uhd/images
[INFO] No inventory file found at /usr/local/share/uhd/images/inventory.json. Creating an empty one.
00006 kB / 00006 kB (100%) usrp1_b100_fw_default-g6bea23d.zip
19484 kB / 19484 kB (100%) x3xx_x310_fpga_default-g494ae8bb.zip
02757 kB / 02757 kB (100%) usrp2_n210_fpga_default-g6bea23d.zip
02109 kB / 02109 kB (100%) n230_n230_fpga_default-g494ae8bb.zip
00522 kB / 00522 kB (100%) usrp1_b100_fpga_default-g6bea23d.zip
00474 kB / 00474 kB (100%) b2xx_b200_fpga_default-g494ae8bb.zip
02415 kB / 02415 kB (100%) usrp2_n200_fpga_default-g6bea23d.zip
05920 kB / 05920 kB (100%) e3xx_e320_fpga_default-g494ae8bb.zip
15883 kB / 15883 kB (100%) n3xx_n310_fpga_default-g494ae8bb.zip
00506 kB / 00506 kB (100%) b2xx_b205mini_fpga_default-g494ae8bb.zip
18676 kB / 18676 kB (100%) x3xx_x300_fpga_default-g494ae8bb.zip
00017 kB / 00017 kB (100%) octoclock_octoclock_fw_default-g14000041.zip
04839 kB / 04839 kB (100%) usb_common_windrv_default-g14000041.zip
00007 kB / 00007 kB (100%) usrp2_usrp2_fw_default-g6bea23d.zip
00009 kB / 00009 kB (100%) usrp2_n200_fw_default-g6bea23d.zip
00450 kB / 00450 kB (100%) usrp2_usrp2_fpga_default-g6bea23d.zip
00142 kB / 00142 kB (100%) b2xx_common_fw_default-g3ff4186b.zip
00460 kB / 00460 kB (100%) b2xx_b200mini_fpga_default-g494ae8bb.zip
00319 kB / 00319 kB (100%) usrp1_usrp1_fpga_default-g6bea23d.zip
00009 kB / 00009 kB (100%) usrp2_n210_fw_default-g6bea23d.zip
11537 kB / 11537 kB (100%) n3xx_n300_fpga_default-g494ae8bb.zip
05349 kB / 05349 kB (100%) e3xx_e310_fpga_default-g494ae8bb.zip
00866 kB / 00866 kB (100%) b2xx_b210_fpga_default-g494ae8bb.zip
[INFO] Images download complete.

</pre>

==Building and installing GNU Radio from source code==

As with UHD, GNU Radio is open-source and is hosted on GitHub. You can browse the code online at the link below, which points to version <code>v3.7.13.4</code>, which is the the latest release at the time of this writing.

* [https://github.com/gnuradio/gnuradio/tree/v3.7.13.4 GNU Radio repository on GitHub]

Note: GNU Radio is currently transitioning from major branches of 3.7.x.x to 3.8.x.x. It is generally recommend at this time to use either the <code>v3.7.13.4</code> or <code>maint-3.7</code> branch of GNU Radio. The <code>master</code> branch includes many major changes such as converting to use Python 3 and may be unstable.

As with UHD, there are several good reasons to build GNU Radio from source code, especially for doing development and prototyping. It it enables an easy way to customize the location of the installation, and to install multiple GNU Radio versions in parallel, and switch between them. It also provides much more flexibility in upgrading and downgrading versions, and allows the user to modify the code and create customized versions, which could possibly include a patch or other bug-fix.

Similar to the process for UHD, to build GNU Radio from source code, clone the GitHub repository, check out a branch or tagged release of the repository, and build and install. Please follow the steps below. Make sure that no USRP device is connected to the system at this point.

First, make a folder to hold the repository.

cd $HOME
cd workarea

Next, clone the repository.

git clone --recursive <nowiki>https://github.com/gnuradio/gnuradio</nowiki>

Next, go into the repository and check out the desired GNU Radio version.

cd gnuradio

To checkout the <code>v3.7.13.4</code> branch:

git checkout v3.7.13.4

Or to checkout the <code>maint-3.7</code> branch:

git checkout maint-3.7

Next, update the submodules:

git submodule update --init --recursive

Next, create a build folder within the repository, invoke CMake, and build GNU Radio:

mkdir build
cd build
cmake ../
make

Next, you can optionally run some basic tests to verify that the build process completed properly.

make test

Next, install GNU Radio, using the default install prefix, which will install GNU Radio under the /usr/local/lib folder. You need to run this as root due to the permissions on that folder.

sudo make install

Finally, update the system's shared library cache.

sudo ldconfig

At this point, GNU Radio should be installed and ready to use. You can quickly test this, with no USRP device attached, by running the following quick tests.

gnuradio-config-info --version
gnuradio-config-info --prefix
gnuradio-config-info --enabled-components

There is a simple flowgraph that you can run that does not require any USRP hardware. It's called the dialtone test, and it produces a PSTN dial tone on the computer's speakers. Running it verifies that all the libraries can be found, and that the GNU Radio run-time is working.

python $HOME/workarea/gnuradio/gr-audio/examples/python/dial_tone.py

You can try launching the GNU Radio Companion (GRC) tool, a visual tool for building and running GNU Radio flowgraphs.

gnuradio-companion

If "gnuradio-companion" does not start and complains about the <code>PYTHONPATH</code> environment variable, then you may have to set this in your <code>$HOME/.bashrc</code> file, as shown below.

export PYTHONPATH=/usr/local/lib/python2.7/dist-packages

On Fedora 21/22/23/24, the <code>PYTHONPATH</code> environment variable will need to be set to:

export PYTHONPATH=/usr/lib/python2.7/site-packages:/usr/local/lib64/python2.7/site-packages/

==Configuring USB==

On Linux, udev handles USB plug and unplug events. The following commands install a udev rule so that non-root users may access the device. This step is only necessary for devices that use USB to connect to the host computer, such as the B200, B210, and B200mini. This setting should take effect immediately and does not require a reboot or logout/login. Be sure that no USRP device is connected via USB when running these commands.

cd $HOME/workarea/uhd/host/utils
sudo cp uhd-usrp.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

==Configuring Ethernet==

For USRP devices that use Ethernet to connect to the host computer, such as the N200, N210, X300, X310, set a static IP address for your system of 192.168.10.1, with a netmask of 255.255.255.0. The default IP address of the USRP is 192.168.10.2, with a netmask of 255.255.255.0. You should probably set the IP address using the graphical Network Manager. If you set the IP address from the command line with <code>ifconfig</code>, Network Manager will probably overwrite these settings.

==Connect the USRP==

The installation of UHD and GNU Radio should now be complete. At this point, connect the USRP to the host computer.

If the interface is Ethernet, then open a terminal window, and try to ping the USRP with "ping 192.168.10.2". The USRP should respond to the ping requests.

If the interface is USB, then open a terminal window, and run "<code>lsusb</code>". You should see the USRP listed on the USB bus with a VID of <code>2500</code> and PID of <code>0020</code>, <code>0021</code>, <code>0022</code>, for B200, B210, B200mini, respectively.

Also try running "<code>uhd_find_devices</code>" and "<code>uhd_usrp_probe</code>".

==Thread priority scheduling==

When UHD 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.

<pre>
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
</pre>

To address this issue, non-privileged (non-root) users need to be given special permission to change the scheduling priority. This can be enabled by creating a group <code>usrp</code>, adding your user to it, and then appending the line <code>@usrp - rtprio 99</code> to the file <code>/etc/security/limits.conf</code>.

sudo groupadd usrp
sudo usermod -aG usrp $USER

Then add the line below to end of the file <code>/etc/security/limits.conf</code>:

@usrp - rtprio 99

You must 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 <code>/etc/group</code> file.

There is further documentation about this in the User Manual at the link below.

* [http://files.ettus.com/manual/page_general.html#general_threading_prio Threading Notes section of the User Manual]

[[Category:Application Notes]]

Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on Linux

2024-02-14T13:47:26Z

MartinAnderseck: Made the -j parameter statement clearer

==Application Note Number==
'''AN-445'''

==Abstract==
This Application Note provides a comprehensive guide for building, installing, and maintaining the open-source toolchain for the USRP (UHD and GNU Radio) from source code on the Linux platform. The Ubuntu and Fedora distributions are specifically discussed. Several other alternate installation methods are also discussed.

http://files.ettus.com/manual/page_build_guide.html#build_instructions_unix

==UHD on Linux==

UHD is fully supported on Linux, using the GCC compiler, and should work on most major Linux distributions.

==Devices==
This document applies only to the USRP X300, X310, B200, B210, B200mini, N200, N210 devices. The E310 and E312 devices are embedded devices, and are fundamentally different from the other non-embedded USRP devices, and are not addressed by this document.

==Install Linux==

If you already have a recent version of Linux installed, then you may be able to skip this section. If you are starting from scratch, or simply want to start with a fresh new installation of Linux, then please follow the instructions and recommendations in this section.

We suggest that you use either Ubuntu 16.04.5, Ubuntu 18.04, Ubuntu 18.10, Fedora 27, 28, 29, and that you use a 64-bit architecture, not a 32-bit architecture. There are several re-spins of Ubuntu, such as Xubuntu, Lubuntu, Kubuntu, Linux Mint, all of which should also work. For the purposes of this document, these re-spins can be considered equivalent. Both Ubuntu and Fedora are known to work well with UHD and GNU Radio.

Download and install Ubuntu, Xubuntu, Linux Mint, or Fedora from the links below. Download the appropriate ISO image, and write it to a USB flash drive. Be sure to verify that the ISO file was not corrupted during the download process by checking the MD5 and/or SHA1 hash.

* [http://www.ubuntu.com/download/desktop Ubuntu download page]
* [http://www.xubuntu.org/getxubuntu/ Xubuntu download page]
* [https://www.linuxmint.com/download.php Linux Mint download page]
* [https://getfedora.org/en/workstation/download/ Fedora download page]

You can learn more about Ubuntu, Xubuntu, Linux Mint, and Fedora at the links below.

* [https://en.wikipedia.org/wiki/Ubuntu_%28operating_system%29 Wikipedia article on Ubuntu]
* [https://en.wikipedia.org/wiki/Xubuntu Wikipedia article on Xubuntu]
* [https://en.wikipedia.org/wiki/Linux_Mint Wikipedia article on Linux Mint]
* [https://en.wikipedia.org/wiki/Fedora_%28operating_system%29 Wikipedia article on Fedora]

There are many tools for writing an ISO image to a USB flash drive. In Linux, you can use the "dd" utility, or the UNetbootin utility. On Ubuntu systems, there is also the Startup Disk Creator utility as well.

* [http://unetbootin.sourceforge.net/ UNetbootin homepage]
* [http://en.wikipedia.org/wiki/UNetbootin Wikipedia article on UNetbootin]

* [https://launchpad.net/usb-creator Startup Disk Creator homepage]
* [https://en.wikipedia.org/wiki/Startup_Disk_Creator Wikipedia article on Startup Disk Creator]
* [http://www.ubuntu.com/download/desktop/create-a-usb-stick-on-ubuntu Article about Startup Disk Creator]

Be sure to use a USB flash drive with at least 8 GB capacity, and use a USB 3.0 flash drive, not a USB 2.0 flash drive. If you use a slower USB 2.0 flash drive, then the install process will take significantly longer.

==Update and Install dependencies==

Before building UHD and GNU Radio, you need to make sure that all the dependencies are first installed.

However, before installing any dependencies, you should first make sure that all the packages that are already installed on your system are up-to-date. You can do this from a GUI, or from the command-line, as shown below.

On Ubuntu systems, run:

sudo apt-get update

On Fedora 21 systems, run:

sudo yum update

On Fedora 22, 23, 24 and 25 systems, run:

sudo dnf update

Once the system has been updated, then install the required dependencies for UHD and GNU Radio.

On Ubuntu 20.04 systems, run:

sudo apt-get -y install autoconf automake build-essential ccache cmake cpufrequtils doxygen ethtool fort77 g++ gir1.2-gtk-3.0 git gobject-introspection gpsd gpsd-clients inetutils-tools libasound2-dev libboost-all-dev libcomedi-dev libcppunit-dev libfftw3-bin libfftw3-dev libfftw3-doc libfontconfig1-dev libgmp-dev libgps-dev libgsl-dev liblog4cpp5-dev libncurses5 libncurses5-dev libpulse-dev libqt5opengl5-dev libqwt-qt5-dev libsdl1.2-dev libtool libudev-dev libusb-1.0-0 libusb-1.0-0-dev libusb-dev libxi-dev libxrender-dev libzmq3-dev libzmq5 ncurses-bin python3-cheetah python3-click python3-click-plugins python3-click-threading python3-dev python3-docutils python3-gi python3-gi-cairo python3-gps python3-lxml python3-mako python3-numpy python3-numpy-dbg python3-opengl python3-pyqt5 python3-requests python3-scipy python3-setuptools python3-six python3-sphinx python3-yaml python3-zmq python3-ruamel.yaml swig wget

On Ubuntu 18.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.14-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses6-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwtplot3d-qt5-dev pyqt4-dev-tools python-qwt5-qt4 cmake git wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq libqwt-dev libqwt6abi1 python-six libgps-dev libgps23 gpsd gpsd-clients python-gps python-setuptools

On Ubuntu 18.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.14-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwtplot3d-qt5-dev pyqt4-dev-tools python-qwt5-qt4 cmake git wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq libqwt-dev libqwt6abi1 python-six libgps-dev libgps23 gpsd gpsd-clients python-gps python-setuptools

On Ubuntu 17.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0v5 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git-core libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq python-setuptools

On Ubuntu 16.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0v5 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git-core libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq-dev libzmq1 python-requests python-sphinx libcomedi-dev python-zmq python-setuptools

On Ubuntu 15.04 and 15.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-1.13-0v5 libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk2.8 git-core libqt4-dev python-numpy ccache python-opengl libgsl0-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq-dev libzmq1 python-requests python-sphinx libcomedi-dev python-zmq python-setuptools

On Ubuntu 14.04 and 14.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk2.8 git-core libqt4-dev python-numpy ccache python-opengl libgsl0-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq1 libzmq-dev python-requests python-sphinx libcomedi-dev python-setuptools

On Fedora 21 systems, run:

sudo yum -y groupinstall "Engineering and Scientific" "Development Tools" "Software Development Tools" "C Development Tools and Libraries"

sudo yum -y install fftw-devel cppunit-devel wxPython-devel boost-devel alsa-lib-devel numpy gsl-devel python-devel pygsl python-cheetah python-mako python-lxml PyOpenGL qt-devel qt qt4 qt4-devel PyQt4-devel qwt-devel qwtplot3d-qt4-devel libusbx-devel cmake git wget python-docutils cppzmq-devel PyQwt PyQwt-devel qwt-devel gtk2-engines xmlrpc-c-"*" tkinter orc orc-devel python-sphinx SDL-devel swig zeromq2-devel python-zmq comedilib comedilib-devel thrift-devel python-thrift scipy zeromq zeromq-devel

On Fedora 22, 23, 24 and 25 systems, run:

sudo dnf -y groupinstall "Engineering and Scientific" "Development Tools" "C Development Tools and Libraries"

sudo dnf -y install fftw-devel cppunit-devel wxPython-devel boost-devel alsa-lib-devel numpy gsl-devel python-devel pygsl python-cheetah python-mako python-lxml PyOpenGL qt-devel PyQt4-devel qwt-devel qwtplot3d-qt4-devel libusbx-devel cmake python-docutils PyQwt PyQwt-devel gtk2-engines xmlrpc-c-"*" tkinter orc-devel python-sphinx SDL-devel swig perl-ZMQ-LibZMQ2 perl-ZMQ-LibZMQ2 zeromq zeromq-devel python-requests gcc-c++ doxygen zeromq-ada-devel cppzmq-devel perl-ZeroMQ amavisd-new-zeromq amavisd-new-snmp-zeromq php-zmq python-zmq czmq uwsgi-logger-zeromq comedilib comedilib-devel pygtk2 ncurses-"*" thrift-devel python-thrift scipy

After installing the dependencies, you should reboot the system.

If the installation of the dependencies completes without any errors, then you can proceed to build and install UHD and GNU Radio.

==Building and installing UHD from source code==

UHD is open-source, and is hosted on GitHub. You can browse the code online at the link below, which points to version 3.14.0.0, which is the the latest release at the time of this writing.

* [https://github.com/EttusResearch/uhd/tree/v3.14.0.0 UHD repository on GitHub]

There are several good reasons to build GNU Radio from source code, especially for doing development and prototyping. It it enables an easy way to customize the location of the installation, and to install multiple UHD versions in parallel, and switch between them. It also provides much more flexibility in upgrading and downgrading versions, and allows the user to modify the code and create customized versions, which could possibly include a patch or other bug-fix.

To build UHD from source code, clone the GitHub repository, check out a branch or tagged release of the repository, and build and install. Please follow the steps below. Make sure that no USRP device is connected to the system at this point.

First, make a folder to hold the repository.

cd $HOME
mkdir workarea
cd workarea

Next, clone the repository and change into the cloned directory.

git clone <nowiki>https://github.com/EttusResearch/uhd</nowiki>
cd uhd

Next, checkout the desired UHD version. You can get a full listing of tagged releases by running the command:

git tag -l

''Example truncated output of <code>git tag -l</code>:''

<pre>
$ git tag -l
...
release_003_009_004
release_003_009_005
release_003_010_000_000
...
</pre>

'''Note''': As of UHD Version 3.10.0.0, the versioning scheme has changed to be a quadruplet format. Each element and version will follow the format of: '''Major.API.ABI.Patch'''. Additional details on this versioning change can be found [https://files.ettus.com/manual/page_semver.html here].

After identifying the version and corresponding release tag you need, check it out:

# Example: For UHD 3.9.5:
git checkout release_003_009_005

# Example: For UHD 3.14.0.0
git checkout v3.14.0.0

Next, create a build folder within the repository.

cd host
mkdir build
cd build

Next, invoke CMake.

cmake ..

'''Note''': By default, UHD will be installed into the prefix <code>/usr/local</code>. This can be changed by adding <code>-DCMAKE_INSTALL_PREFIX=XXX</code> to install into the prefix <code>XXX</code>.

'''Note''': if the shell <code>PATH</code> is set such that <code>/bin</code> comes before <code>/usr/bin</code>, then this step is likely to fail because cmake will set the <code>FIND_ROOT_PATH</code> to <code>/</code> and this setting will fail as a prefix for Boost headers or libraries. The cmake output will include messages such as

-- Boost include directories: /include
-- Boost library directories: /lib/x86_64-linux-gnu

and

CMake Error in lib/CMakeLists.txt:
Imported target "Boost::chrono" includes non-existent path
"/include"
in its INTERFACE_INCLUDE_DIRECTORIES. Possible reasons include:
* The path was deleted, renamed, or moved to another location.
* An install or uninstall procedure did not complete successfully.
* The installation package was faulty and references files it does not provide.

One of the following 3 options should fix this situation:

1. <code>/usr/bin/cmake ..</code>
2. <code>PATH=/usr/bin:$PATH cmake ..</code>
3. <code>cmake -DCMAKE_FIND_ROOT_PATH=/usr ..</code>

Once the cmake command succeeds without errors, build UHD.

make

'''Note''': Use the <code>-j</code> parameter to use more than the default one CPU core, e.g. <code>make -j8</code> for 8 CPU cores.

Next, you can optionally run some basic tests to verify that the build process completed properly.

make test

Next, install UHD, using the default install prefix, which will install UHD under the /usr/local/lib folder. You need to run this as root due to the permissions on that folder.

sudo make install

Next, update the system's shared library cache.

sudo ldconfig

Finally, make sure that the <code>LD_LIBRARY_PATH</code> environment variable is defined and includes the folder under which UHD was installed. Most commonly, you can add the line below to the end of your <code>$HOME/.bashrc</code> file:

export LD_LIBRARY_PATH=/usr/local/lib

On Fedora 22/23/24/25 you will need to set the <code>LD_LIBRARY_PATH</code> to <code>/usr/local/lib64</code>.

export LD_LIBRARY_PATH=/usr/local/lib64

If the <code>LD_LIBRARY_PATH</code> environment variable is already defined with other folders in your <code>$HOME/.bashrc</code> file, then add the line below to the end of your <code>$HOME/.bashrc</code> file to preserve the current settings.

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

For Fedora 21/22/23/24/25

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib64

For this change to take effect, you will need to close the current terminal window, and open a new terminal.

At this point, UHD should be installed and ready to use. You can quickly test this, with no USRP device attached, by running <code>uhd_find_devices</code>. You should see something similar to the following.

<pre>
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

No UHD Devices Found
</pre>

===Downloading the UHD FPGA Images===
You can now download the UHD FPGA Images for this installation. This can be done by running the command <code>uhd_images_downloader</code>.

$ sudo uhd_images_downloader

Note: Since this installation is being installed to a system level directory (e.g. <code>/usr/local</code>), the <code>uhd_images_downloader</code> command requires <code>sudo</code> privileges.

Example ouput for UHD 3.13.3.0:

<pre>
$ sudo uhd_images_downloader
Images destination: /usr/local/share/uhd/images
Downloading images from: http://files.ettus.com/binaries/images/uhd-images_003.010.003.000-release.zip
Downloading images to: /tmp/tmpm46JDg/uhd-images_003.010.003.000-release.zip
57009 kB / 57009 kB (100%)

Images successfully installed to: /usr/local/share/uhd/images
</pre>

Example output for UHD 3.13:

<pre>
$ sudo uhd_images_downloader
[INFO] Images destination: /usr/local/share/uhd/images
[INFO] No inventory file found at /usr/local/share/uhd/images/inventory.json. Creating an empty one.
00006 kB / 00006 kB (100%) usrp1_b100_fw_default-g6bea23d.zip
19484 kB / 19484 kB (100%) x3xx_x310_fpga_default-g494ae8bb.zip
02757 kB / 02757 kB (100%) usrp2_n210_fpga_default-g6bea23d.zip
02109 kB / 02109 kB (100%) n230_n230_fpga_default-g494ae8bb.zip
00522 kB / 00522 kB (100%) usrp1_b100_fpga_default-g6bea23d.zip
00474 kB / 00474 kB (100%) b2xx_b200_fpga_default-g494ae8bb.zip
02415 kB / 02415 kB (100%) usrp2_n200_fpga_default-g6bea23d.zip
05920 kB / 05920 kB (100%) e3xx_e320_fpga_default-g494ae8bb.zip
15883 kB / 15883 kB (100%) n3xx_n310_fpga_default-g494ae8bb.zip
00506 kB / 00506 kB (100%) b2xx_b205mini_fpga_default-g494ae8bb.zip
18676 kB / 18676 kB (100%) x3xx_x300_fpga_default-g494ae8bb.zip
00017 kB / 00017 kB (100%) octoclock_octoclock_fw_default-g14000041.zip
04839 kB / 04839 kB (100%) usb_common_windrv_default-g14000041.zip
00007 kB / 00007 kB (100%) usrp2_usrp2_fw_default-g6bea23d.zip
00009 kB / 00009 kB (100%) usrp2_n200_fw_default-g6bea23d.zip
00450 kB / 00450 kB (100%) usrp2_usrp2_fpga_default-g6bea23d.zip
00142 kB / 00142 kB (100%) b2xx_common_fw_default-g3ff4186b.zip
00460 kB / 00460 kB (100%) b2xx_b200mini_fpga_default-g494ae8bb.zip
00319 kB / 00319 kB (100%) usrp1_usrp1_fpga_default-g6bea23d.zip
00009 kB / 00009 kB (100%) usrp2_n210_fw_default-g6bea23d.zip
11537 kB / 11537 kB (100%) n3xx_n300_fpga_default-g494ae8bb.zip
05349 kB / 05349 kB (100%) e3xx_e310_fpga_default-g494ae8bb.zip
00866 kB / 00866 kB (100%) b2xx_b210_fpga_default-g494ae8bb.zip
[INFO] Images download complete.

</pre>

==Building and installing GNU Radio from source code==

As with UHD, GNU Radio is open-source and is hosted on GitHub. You can browse the code online at the link below, which points to version <code>v3.7.13.4</code>, which is the the latest release at the time of this writing.

* [https://github.com/gnuradio/gnuradio/tree/v3.7.13.4 GNU Radio repository on GitHub]

Note: GNU Radio is currently transitioning from major branches of 3.7.x.x to 3.8.x.x. It is generally recommend at this time to use either the <code>v3.7.13.4</code> or <code>maint-3.7</code> branch of GNU Radio. The <code>master</code> branch includes many major changes such as converting to use Python 3 and may be unstable.

As with UHD, there are several good reasons to build GNU Radio from source code, especially for doing development and prototyping. It it enables an easy way to customize the location of the installation, and to install multiple GNU Radio versions in parallel, and switch between them. It also provides much more flexibility in upgrading and downgrading versions, and allows the user to modify the code and create customized versions, which could possibly include a patch or other bug-fix.

Similar to the process for UHD, to build GNU Radio from source code, clone the GitHub repository, check out a branch or tagged release of the repository, and build and install. Please follow the steps below. Make sure that no USRP device is connected to the system at this point.

First, make a folder to hold the repository.

cd $HOME
cd workarea

Next, clone the repository.

git clone --recursive <nowiki>https://github.com/gnuradio/gnuradio</nowiki>

Next, go into the repository and check out the desired GNU Radio version.

cd gnuradio

To checkout the <code>v3.7.13.4</code> branch:

git checkout v3.7.13.4

Or to checkout the <code>maint-3.7</code> branch:

git checkout maint-3.7

Next, update the submodules:

git submodule update --init --recursive

Next, create a build folder within the repository, invoke CMake, and build GNU Radio:

mkdir build
cd build
cmake ../
make

Next, you can optionally run some basic tests to verify that the build process completed properly.

make test

Next, install GNU Radio, using the default install prefix, which will install GNU Radio under the /usr/local/lib folder. You need to run this as root due to the permissions on that folder.

sudo make install

Finally, update the system's shared library cache.

sudo ldconfig

At this point, GNU Radio should be installed and ready to use. You can quickly test this, with no USRP device attached, by running the following quick tests.

gnuradio-config-info --version
gnuradio-config-info --prefix
gnuradio-config-info --enabled-components

There is a simple flowgraph that you can run that does not require any USRP hardware. It's called the dialtone test, and it produces a PSTN dial tone on the computer's speakers. Running it verifies that all the libraries can be found, and that the GNU Radio run-time is working.

python $HOME/workarea/gnuradio/gr-audio/examples/python/dial_tone.py

You can try launching the GNU Radio Companion (GRC) tool, a visual tool for building and running GNU Radio flowgraphs.

gnuradio-companion

If "gnuradio-companion" does not start and complains about the <code>PYTHONPATH</code> environment variable, then you may have to set this in your <code>$HOME/.bashrc</code> file, as shown below.

export PYTHONPATH=/usr/local/lib/python2.7/dist-packages

On Fedora 21/22/23/24, the <code>PYTHONPATH</code> environment variable will need to be set to:

export PYTHONPATH=/usr/lib/python2.7/site-packages:/usr/local/lib64/python2.7/site-packages/

==Configuring USB==

On Linux, udev handles USB plug and unplug events. The following commands install a udev rule so that non-root users may access the device. This step is only necessary for devices that use USB to connect to the host computer, such as the B200, B210, and B200mini. This setting should take effect immediately and does not require a reboot or logout/login. Be sure that no USRP device is connected via USB when running these commands.

cd $HOME/workarea/uhd/host/utils
sudo cp uhd-usrp.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

==Configuring Ethernet==

For USRP devices that use Ethernet to connect to the host computer, such as the N200, N210, X300, X310, set a static IP address for your system of 192.168.10.1, with a netmask of 255.255.255.0. The default IP address of the USRP is 192.168.10.2, with a netmask of 255.255.255.0. You should probably set the IP address using the graphical Network Manager. If you set the IP address from the command line with <code>ifconfig</code>, Network Manager will probably overwrite these settings.

==Connect the USRP==

The installation of UHD and GNU Radio should now be complete. At this point, connect the USRP to the host computer.

If the interface is Ethernet, then open a terminal window, and try to ping the USRP with "ping 192.168.10.2". The USRP should respond to the ping requests.

If the interface is USB, then open a terminal window, and run "<code>lsusb</code>". You should see the USRP listed on the USB bus with a VID of <code>2500</code> and PID of <code>0020</code>, <code>0021</code>, <code>0022</code>, for B200, B210, B200mini, respectively.

Also try running "<code>uhd_find_devices</code>" and "<code>uhd_usrp_probe</code>".

==Thread priority scheduling==

When UHD 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.

<pre>
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
</pre>

To address this issue, non-privileged (non-root) users need to be given special permission to change the scheduling priority. This can be enabled by creating a group <code>usrp</code>, adding your user to it, and then appending the line <code>@usrp - rtprio 99</code> to the file <code>/etc/security/limits.conf</code>.

sudo groupadd usrp
sudo usermod -aG usrp $USER

Then add the line below to end of the file <code>/etc/security/limits.conf</code>:

@usrp - rtprio 99

You must 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 <code>/etc/group</code> file.

There is further documentation about this in the User Manual at the link below.

* [http://files.ettus.com/manual/page_general.html#general_threading_prio Threading Notes section of the User Manual]

[[Category:Application Notes]]

Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on Linux

2024-02-14T13:17:13Z

MartinAnderseck: Adding hints for new developers

==Application Note Number==
'''AN-445'''

==Abstract==
This Application Note provides a comprehensive guide for building, installing, and maintaining the open-source toolchain for the USRP (UHD and GNU Radio) from source code on the Linux platform. The Ubuntu and Fedora distributions are specifically discussed. Several other alternate installation methods are also discussed.

http://files.ettus.com/manual/page_build_guide.html#build_instructions_unix

==UHD on Linux==

UHD is fully supported on Linux, using the GCC compiler, and should work on most major Linux distributions.

==Devices==
This document applies only to the USRP X300, X310, B200, B210, B200mini, N200, N210 devices. The E310 and E312 devices are embedded devices, and are fundamentally different from the other non-embedded USRP devices, and are not addressed by this document.

==Install Linux==

If you already have a recent version of Linux installed, then you may be able to skip this section. If you are starting from scratch, or simply want to start with a fresh new installation of Linux, then please follow the instructions and recommendations in this section.

We suggest that you use either Ubuntu 16.04.5, Ubuntu 18.04, Ubuntu 18.10, Fedora 27, 28, 29, and that you use a 64-bit architecture, not a 32-bit architecture. There are several re-spins of Ubuntu, such as Xubuntu, Lubuntu, Kubuntu, Linux Mint, all of which should also work. For the purposes of this document, these re-spins can be considered equivalent. Both Ubuntu and Fedora are known to work well with UHD and GNU Radio.

Download and install Ubuntu, Xubuntu, Linux Mint, or Fedora from the links below. Download the appropriate ISO image, and write it to a USB flash drive. Be sure to verify that the ISO file was not corrupted during the download process by checking the MD5 and/or SHA1 hash.

* [http://www.ubuntu.com/download/desktop Ubuntu download page]
* [http://www.xubuntu.org/getxubuntu/ Xubuntu download page]
* [https://www.linuxmint.com/download.php Linux Mint download page]
* [https://getfedora.org/en/workstation/download/ Fedora download page]

You can learn more about Ubuntu, Xubuntu, Linux Mint, and Fedora at the links below.

* [https://en.wikipedia.org/wiki/Ubuntu_%28operating_system%29 Wikipedia article on Ubuntu]
* [https://en.wikipedia.org/wiki/Xubuntu Wikipedia article on Xubuntu]
* [https://en.wikipedia.org/wiki/Linux_Mint Wikipedia article on Linux Mint]
* [https://en.wikipedia.org/wiki/Fedora_%28operating_system%29 Wikipedia article on Fedora]

There are many tools for writing an ISO image to a USB flash drive. In Linux, you can use the "dd" utility, or the UNetbootin utility. On Ubuntu systems, there is also the Startup Disk Creator utility as well.

* [http://unetbootin.sourceforge.net/ UNetbootin homepage]
* [http://en.wikipedia.org/wiki/UNetbootin Wikipedia article on UNetbootin]

* [https://launchpad.net/usb-creator Startup Disk Creator homepage]
* [https://en.wikipedia.org/wiki/Startup_Disk_Creator Wikipedia article on Startup Disk Creator]
* [http://www.ubuntu.com/download/desktop/create-a-usb-stick-on-ubuntu Article about Startup Disk Creator]

Be sure to use a USB flash drive with at least 8 GB capacity, and use a USB 3.0 flash drive, not a USB 2.0 flash drive. If you use a slower USB 2.0 flash drive, then the install process will take significantly longer.

==Update and Install dependencies==

Before building UHD and GNU Radio, you need to make sure that all the dependencies are first installed.

However, before installing any dependencies, you should first make sure that all the packages that are already installed on your system are up-to-date. You can do this from a GUI, or from the command-line, as shown below.

On Ubuntu systems, run:

sudo apt-get update

On Fedora 21 systems, run:

sudo yum update

On Fedora 22, 23, 24 and 25 systems, run:

sudo dnf update

Once the system has been updated, then install the required dependencies for UHD and GNU Radio.

On Ubuntu 20.04 systems, run:

sudo apt-get -y install autoconf automake build-essential ccache cmake cpufrequtils doxygen ethtool fort77 g++ gir1.2-gtk-3.0 git gobject-introspection gpsd gpsd-clients inetutils-tools libasound2-dev libboost-all-dev libcomedi-dev libcppunit-dev libfftw3-bin libfftw3-dev libfftw3-doc libfontconfig1-dev libgmp-dev libgps-dev libgsl-dev liblog4cpp5-dev libncurses5 libncurses5-dev libpulse-dev libqt5opengl5-dev libqwt-qt5-dev libsdl1.2-dev libtool libudev-dev libusb-1.0-0 libusb-1.0-0-dev libusb-dev libxi-dev libxrender-dev libzmq3-dev libzmq5 ncurses-bin python3-cheetah python3-click python3-click-plugins python3-click-threading python3-dev python3-docutils python3-gi python3-gi-cairo python3-gps python3-lxml python3-mako python3-numpy python3-numpy-dbg python3-opengl python3-pyqt5 python3-requests python3-scipy python3-setuptools python3-six python3-sphinx python3-yaml python3-zmq python3-ruamel.yaml swig wget

On Ubuntu 18.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.14-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses6-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwtplot3d-qt5-dev pyqt4-dev-tools python-qwt5-qt4 cmake git wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq libqwt-dev libqwt6abi1 python-six libgps-dev libgps23 gpsd gpsd-clients python-gps python-setuptools

On Ubuntu 18.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.14-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwtplot3d-qt5-dev pyqt4-dev-tools python-qwt5-qt4 cmake git wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq libqwt-dev libqwt6abi1 python-six libgps-dev libgps23 gpsd gpsd-clients python-gps python-setuptools

On Ubuntu 17.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0v5 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git-core libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq python-setuptools

On Ubuntu 16.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0v5 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git-core libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq-dev libzmq1 python-requests python-sphinx libcomedi-dev python-zmq python-setuptools

On Ubuntu 15.04 and 15.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-1.13-0v5 libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk2.8 git-core libqt4-dev python-numpy ccache python-opengl libgsl0-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq-dev libzmq1 python-requests python-sphinx libcomedi-dev python-zmq python-setuptools

On Ubuntu 14.04 and 14.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk2.8 git-core libqt4-dev python-numpy ccache python-opengl libgsl0-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq1 libzmq-dev python-requests python-sphinx libcomedi-dev python-setuptools

On Fedora 21 systems, run:

sudo yum -y groupinstall "Engineering and Scientific" "Development Tools" "Software Development Tools" "C Development Tools and Libraries"

sudo yum -y install fftw-devel cppunit-devel wxPython-devel boost-devel alsa-lib-devel numpy gsl-devel python-devel pygsl python-cheetah python-mako python-lxml PyOpenGL qt-devel qt qt4 qt4-devel PyQt4-devel qwt-devel qwtplot3d-qt4-devel libusbx-devel cmake git wget python-docutils cppzmq-devel PyQwt PyQwt-devel qwt-devel gtk2-engines xmlrpc-c-"*" tkinter orc orc-devel python-sphinx SDL-devel swig zeromq2-devel python-zmq comedilib comedilib-devel thrift-devel python-thrift scipy zeromq zeromq-devel

On Fedora 22, 23, 24 and 25 systems, run:

sudo dnf -y groupinstall "Engineering and Scientific" "Development Tools" "C Development Tools and Libraries"

sudo dnf -y install fftw-devel cppunit-devel wxPython-devel boost-devel alsa-lib-devel numpy gsl-devel python-devel pygsl python-cheetah python-mako python-lxml PyOpenGL qt-devel PyQt4-devel qwt-devel qwtplot3d-qt4-devel libusbx-devel cmake python-docutils PyQwt PyQwt-devel gtk2-engines xmlrpc-c-"*" tkinter orc-devel python-sphinx SDL-devel swig perl-ZMQ-LibZMQ2 perl-ZMQ-LibZMQ2 zeromq zeromq-devel python-requests gcc-c++ doxygen zeromq-ada-devel cppzmq-devel perl-ZeroMQ amavisd-new-zeromq amavisd-new-snmp-zeromq php-zmq python-zmq czmq uwsgi-logger-zeromq comedilib comedilib-devel pygtk2 ncurses-"*" thrift-devel python-thrift scipy

After installing the dependencies, you should reboot the system.

If the installation of the dependencies completes without any errors, then you can proceed to build and install UHD and GNU Radio.

==Building and installing UHD from source code==

UHD is open-source, and is hosted on GitHub. You can browse the code online at the link below, which points to version 3.14.0.0, which is the the latest release at the time of this writing.

* [https://github.com/EttusResearch/uhd/tree/v3.14.0.0 UHD repository on GitHub]

There are several good reasons to build GNU Radio from source code, especially for doing development and prototyping. It it enables an easy way to customize the location of the installation, and to install multiple UHD versions in parallel, and switch between them. It also provides much more flexibility in upgrading and downgrading versions, and allows the user to modify the code and create customized versions, which could possibly include a patch or other bug-fix.

To build UHD from source code, clone the GitHub repository, check out a branch or tagged release of the repository, and build and install. Please follow the steps below. Make sure that no USRP device is connected to the system at this point.

First, make a folder to hold the repository.

cd $HOME
mkdir workarea
cd workarea

Next, clone the repository and change into the cloned directory.

git clone <nowiki>https://github.com/EttusResearch/uhd</nowiki>
cd uhd

Next, checkout the desired UHD version. You can get a full listing of tagged releases by running the command:

git tag -l

''Example truncated output of <code>git tag -l</code>:''

<pre>
$ git tag -l
...
release_003_009_004
release_003_009_005
release_003_010_000_000
...
</pre>

'''Note''': As of UHD Version 3.10.0.0, the versioning scheme has changed to be a quadruplet format. Each element and version will follow the format of: '''Major.API.ABI.Patch'''. Additional details on this versioning change can be found [https://files.ettus.com/manual/page_semver.html here].

After identifying the version and corresponding release tag you need, check it out:

# Example: For UHD 3.9.5:
git checkout release_003_009_005

# Example: For UHD 3.14.0.0
git checkout v3.14.0.0

Next, create a build folder within the repository.

cd host
mkdir build
cd build

Next, invoke CMake.

cmake ..

'''Note''': By default, UHD will be installed into the prefix <code>/usr/local</code>. This can be changed by adding <code>-DCMAKE_INSTALL_PREFIX=XXX</code> to install into the prefix <code>XXX</code>.

'''Note''': if the shell <code>PATH</code> is set such that <code>/bin</code> comes before <code>/usr/bin</code>, then this step is likely to fail because cmake will set the <code>FIND_ROOT_PATH</code> to <code>/</code> and this setting will fail as a prefix for Boost headers or libraries. The cmake output will include messages such as

-- Boost include directories: /include
-- Boost library directories: /lib/x86_64-linux-gnu

and

CMake Error in lib/CMakeLists.txt:
Imported target "Boost::chrono" includes non-existent path
"/include"
in its INTERFACE_INCLUDE_DIRECTORIES. Possible reasons include:
* The path was deleted, renamed, or moved to another location.
* An install or uninstall procedure did not complete successfully.
* The installation package was faulty and references files it does not provide.

One of the following 3 options should fix this situation:

1. <code>/usr/bin/cmake ..</code>
2. <code>PATH=/usr/bin:$PATH cmake ..</code>
3. <code>cmake -DCMAKE_FIND_ROOT_PATH=/usr ..</code>

Once the cmake command succeeds without errors, build UHD.

make

'''Note''': Use e.g. <code>make -j4</code> to use 4 CPU cores during the build.

Next, you can optionally run some basic tests to verify that the build process completed properly.

make test

Next, install UHD, using the default install prefix, which will install UHD under the /usr/local/lib folder. You need to run this as root due to the permissions on that folder.

sudo make install

Next, update the system's shared library cache.

sudo ldconfig

Finally, make sure that the <code>LD_LIBRARY_PATH</code> environment variable is defined and includes the folder under which UHD was installed. Most commonly, you can add the line below to the end of your <code>$HOME/.bashrc</code> file:

export LD_LIBRARY_PATH=/usr/local/lib

On Fedora 22/23/24/25 you will need to set the <code>LD_LIBRARY_PATH</code> to <code>/usr/local/lib64</code>.

export LD_LIBRARY_PATH=/usr/local/lib64

If the <code>LD_LIBRARY_PATH</code> environment variable is already defined with other folders in your <code>$HOME/.bashrc</code> file, then add the line below to the end of your <code>$HOME/.bashrc</code> file to preserve the current settings.

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

For Fedora 21/22/23/24/25

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib64

For this change to take effect, you will need to close the current terminal window, and open a new terminal.

At this point, UHD should be installed and ready to use. You can quickly test this, with no USRP device attached, by running <code>uhd_find_devices</code>. You should see something similar to the following.

<pre>
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

No UHD Devices Found
</pre>

===Downloading the UHD FPGA Images===
You can now download the UHD FPGA Images for this installation. This can be done by running the command <code>uhd_images_downloader</code>.

$ sudo uhd_images_downloader

Note: Since this installation is being installed to a system level directory (e.g. <code>/usr/local</code>), the <code>uhd_images_downloader</code> command requires <code>sudo</code> privileges.

Example ouput for UHD 3.13.3.0:

<pre>
$ sudo uhd_images_downloader
Images destination: /usr/local/share/uhd/images
Downloading images from: http://files.ettus.com/binaries/images/uhd-images_003.010.003.000-release.zip
Downloading images to: /tmp/tmpm46JDg/uhd-images_003.010.003.000-release.zip
57009 kB / 57009 kB (100%)

Images successfully installed to: /usr/local/share/uhd/images
</pre>

Example output for UHD 3.13:

<pre>
$ sudo uhd_images_downloader
[INFO] Images destination: /usr/local/share/uhd/images
[INFO] No inventory file found at /usr/local/share/uhd/images/inventory.json. Creating an empty one.
00006 kB / 00006 kB (100%) usrp1_b100_fw_default-g6bea23d.zip
19484 kB / 19484 kB (100%) x3xx_x310_fpga_default-g494ae8bb.zip
02757 kB / 02757 kB (100%) usrp2_n210_fpga_default-g6bea23d.zip
02109 kB / 02109 kB (100%) n230_n230_fpga_default-g494ae8bb.zip
00522 kB / 00522 kB (100%) usrp1_b100_fpga_default-g6bea23d.zip
00474 kB / 00474 kB (100%) b2xx_b200_fpga_default-g494ae8bb.zip
02415 kB / 02415 kB (100%) usrp2_n200_fpga_default-g6bea23d.zip
05920 kB / 05920 kB (100%) e3xx_e320_fpga_default-g494ae8bb.zip
15883 kB / 15883 kB (100%) n3xx_n310_fpga_default-g494ae8bb.zip
00506 kB / 00506 kB (100%) b2xx_b205mini_fpga_default-g494ae8bb.zip
18676 kB / 18676 kB (100%) x3xx_x300_fpga_default-g494ae8bb.zip
00017 kB / 00017 kB (100%) octoclock_octoclock_fw_default-g14000041.zip
04839 kB / 04839 kB (100%) usb_common_windrv_default-g14000041.zip
00007 kB / 00007 kB (100%) usrp2_usrp2_fw_default-g6bea23d.zip
00009 kB / 00009 kB (100%) usrp2_n200_fw_default-g6bea23d.zip
00450 kB / 00450 kB (100%) usrp2_usrp2_fpga_default-g6bea23d.zip
00142 kB / 00142 kB (100%) b2xx_common_fw_default-g3ff4186b.zip
00460 kB / 00460 kB (100%) b2xx_b200mini_fpga_default-g494ae8bb.zip
00319 kB / 00319 kB (100%) usrp1_usrp1_fpga_default-g6bea23d.zip
00009 kB / 00009 kB (100%) usrp2_n210_fw_default-g6bea23d.zip
11537 kB / 11537 kB (100%) n3xx_n300_fpga_default-g494ae8bb.zip
05349 kB / 05349 kB (100%) e3xx_e310_fpga_default-g494ae8bb.zip
00866 kB / 00866 kB (100%) b2xx_b210_fpga_default-g494ae8bb.zip
[INFO] Images download complete.

</pre>

==Building and installing GNU Radio from source code==

As with UHD, GNU Radio is open-source and is hosted on GitHub. You can browse the code online at the link below, which points to version <code>v3.7.13.4</code>, which is the the latest release at the time of this writing.

* [https://github.com/gnuradio/gnuradio/tree/v3.7.13.4 GNU Radio repository on GitHub]

Note: GNU Radio is currently transitioning from major branches of 3.7.x.x to 3.8.x.x. It is generally recommend at this time to use either the <code>v3.7.13.4</code> or <code>maint-3.7</code> branch of GNU Radio. The <code>master</code> branch includes many major changes such as converting to use Python 3 and may be unstable.

As with UHD, there are several good reasons to build GNU Radio from source code, especially for doing development and prototyping. It it enables an easy way to customize the location of the installation, and to install multiple GNU Radio versions in parallel, and switch between them. It also provides much more flexibility in upgrading and downgrading versions, and allows the user to modify the code and create customized versions, which could possibly include a patch or other bug-fix.

Similar to the process for UHD, to build GNU Radio from source code, clone the GitHub repository, check out a branch or tagged release of the repository, and build and install. Please follow the steps below. Make sure that no USRP device is connected to the system at this point.

First, make a folder to hold the repository.

cd $HOME
cd workarea

Next, clone the repository.

git clone --recursive <nowiki>https://github.com/gnuradio/gnuradio</nowiki>

Next, go into the repository and check out the desired GNU Radio version.

cd gnuradio

To checkout the <code>v3.7.13.4</code> branch:

git checkout v3.7.13.4

Or to checkout the <code>maint-3.7</code> branch:

git checkout maint-3.7

Next, update the submodules:

git submodule update --init --recursive

Next, create a build folder within the repository, invoke CMake, and build GNU Radio:

mkdir build
cd build
cmake ../
make

Next, you can optionally run some basic tests to verify that the build process completed properly.

make test

Next, install GNU Radio, using the default install prefix, which will install GNU Radio under the /usr/local/lib folder. You need to run this as root due to the permissions on that folder.

sudo make install

Finally, update the system's shared library cache.

sudo ldconfig

At this point, GNU Radio should be installed and ready to use. You can quickly test this, with no USRP device attached, by running the following quick tests.

gnuradio-config-info --version
gnuradio-config-info --prefix
gnuradio-config-info --enabled-components

There is a simple flowgraph that you can run that does not require any USRP hardware. It's called the dialtone test, and it produces a PSTN dial tone on the computer's speakers. Running it verifies that all the libraries can be found, and that the GNU Radio run-time is working.

python $HOME/workarea/gnuradio/gr-audio/examples/python/dial_tone.py

You can try launching the GNU Radio Companion (GRC) tool, a visual tool for building and running GNU Radio flowgraphs.

gnuradio-companion

If "gnuradio-companion" does not start and complains about the <code>PYTHONPATH</code> environment variable, then you may have to set this in your <code>$HOME/.bashrc</code> file, as shown below.

export PYTHONPATH=/usr/local/lib/python2.7/dist-packages

On Fedora 21/22/23/24, the <code>PYTHONPATH</code> environment variable will need to be set to:

export PYTHONPATH=/usr/lib/python2.7/site-packages:/usr/local/lib64/python2.7/site-packages/

==Configuring USB==

On Linux, udev handles USB plug and unplug events. The following commands install a udev rule so that non-root users may access the device. This step is only necessary for devices that use USB to connect to the host computer, such as the B200, B210, and B200mini. This setting should take effect immediately and does not require a reboot or logout/login. Be sure that no USRP device is connected via USB when running these commands.

cd $HOME/workarea/uhd/host/utils
sudo cp uhd-usrp.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

==Configuring Ethernet==

For USRP devices that use Ethernet to connect to the host computer, such as the N200, N210, X300, X310, set a static IP address for your system of 192.168.10.1, with a netmask of 255.255.255.0. The default IP address of the USRP is 192.168.10.2, with a netmask of 255.255.255.0. You should probably set the IP address using the graphical Network Manager. If you set the IP address from the command line with <code>ifconfig</code>, Network Manager will probably overwrite these settings.

==Connect the USRP==

The installation of UHD and GNU Radio should now be complete. At this point, connect the USRP to the host computer.

If the interface is Ethernet, then open a terminal window, and try to ping the USRP with "ping 192.168.10.2". The USRP should respond to the ping requests.

If the interface is USB, then open a terminal window, and run "<code>lsusb</code>". You should see the USRP listed on the USB bus with a VID of <code>2500</code> and PID of <code>0020</code>, <code>0021</code>, <code>0022</code>, for B200, B210, B200mini, respectively.

Also try running "<code>uhd_find_devices</code>" and "<code>uhd_usrp_probe</code>".

==Thread priority scheduling==

When UHD 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.

<pre>
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
</pre>

To address this issue, non-privileged (non-root) users need to be given special permission to change the scheduling priority. This can be enabled by creating a group <code>usrp</code>, adding your user to it, and then appending the line <code>@usrp - rtprio 99</code> to the file <code>/etc/security/limits.conf</code>.

sudo groupadd usrp
sudo usermod -aG usrp $USER

Then add the line below to end of the file <code>/etc/security/limits.conf</code>:

@usrp - rtprio 99

You must 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 <code>/etc/group</code> file.

There is further documentation about this in the User Manual at the link below.

* [http://files.ettus.com/manual/page_general.html#general_threading_prio Threading Notes section of the User Manual]

[[Category:Application Notes]]

About Sampling Rates and Master Clock Rates for the USRP X440

2024-01-16T10:10:46Z

MartinAnderseck: Add note about Fc in the TX as soon as ADCs/DACs are turned on.

== Application Note Number and Authors ==

'''AN-055''' by Marian Koop and Martin Anderseck



= Overview =
This application note guides users through the selection process of Master Clock Rates (MCR) for the [https://kb.ettus.com/X440#X440 USRP X440]. It will highlight possible implications and side effects as well as design specific differences to other USRPs (like the X410).


= USRP X440 Configuration Considerations =
The USRP X440 is a [https://uhd.readthedocs.io/en/latest/page_fbx.html#fbx_too balun-coupled transceiver] without built-in RF signal conditioning. Compared to other RF architectures this enables the USRP X440 to access the full RF bandwidth available to the ADC/DAC, but also requires additional frequency planning. To achieve this, the USRP X440 utilizes its ADC/DAC in direct sampling mode and is susceptible to various effects that may distort the signal of interest. These can be separated into distortions from both signal processing and from the ADC/DAC design.


== Relationship between RF-ADC/DAC Converter Rate, USRP Master Clock Rate (MCR), Data IQ rate ==
Except for the 200 MHz variant, the default USRP X440 FPGA images do not contain a configurable DDC<ref>Digital Down Conversion</ref>/DUC<ref>Digital Up Conversion</ref> block. This means that the IQ sample rate (FIQ) is the same as the Master Clock Rate (MCR) that goes into the RFNoC Radio block. However, unlike most other USRPs the USRP X440 supports a highly variable MCR. The RF Data Converter sampling rate (FS) is chosen by UHD based on the MCR and the available resampling factors of 2, 4, or 8, and defaults to the highest achievable values with these factors. This can be overridden if the desired MCR can be achieved with multiple converter rates (see device argument [https://uhd.readthedocs.io/en/latest/page_usrp_x4xx.html#x4xx_usage_args converter_rate]). The inverse calculation - divide the converter rate by 8, 4 or 2 - has to be done to derive the master clock rate if a specific converter rate shall be used. Figure 1 depicts the simplified signal path block diagram for the USRP X440.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 1. Simplified USRP X440 Signal Path
|-
| style="border-style: none;" | [[File:ANxxx-X440_signal_path.jpg|450px|center]]
|}


== Aliases and Nyquist Zones ==
By itself the USRP X440 can sample input signals at frequencies above the Nyquist frequency<ref>[https://en.wikipedia.org/wiki/Nyquist_frequency Nyquist frequency]</ref>, which is half of the ADC converter sampling rate (FS). However, this method introduces aliasing effects, which cause unwanted signals to appear as mirror images around multiples of the Nyquist frequency (FS/2) in the output spectrum. The first Nyquist zone (N1) is the frequency range from 0 to FS/2, and the second Nyquist zone (N2) goes from FS/2 to FS. Other Nyquist zones are numbered in ascending order, each spanning FS/2. The digital passband in each Nyquist zone can be calculated as 0.4 * FS (see also <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/RF-ADC-Decimation-Filters-Gen-1/Gen-2 Xilinx RF-ADC Decimation Filters (Gen-1)]</ref>). The following figure depicts the Nyquist zones for the minimum and maximum RF-ADC converter rates supported by the USRP X440. Note that the illustrations do not show the effects of external, analog filters on the achievable passband within a Nyquist zone. A typical expectation is, that the unusable frequency range around each Nyquist zone boundary (also often referred to as a guard band) increases with ascending Nyquist zone order and results in decreasing, lopsided achievable passbands.
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 2. Nyquist Zones
|-
| style="border-style: none;" | [[File:ANxxx-X440_nyquist_zones.jpg|450px|center]]
|}

Knowledge of signal aliases can both be exploited and create uncertainties. Applications could utilize intentional under sampling (also referred as "bandpass sampling") to receive signals at greater than FS/2. The same effect may on the other hand lead to garbled or distorted signal detection if the signal of interest spans multiple Nyquist zones or interferer signals are aliased into the observed spectrum. Both effects are depicted in figure 3.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 3. Aliases - Wanted and unwanted
|-
| style="border-style: none;" | [[File:ANxxx-wanted_and_unwanted_aliases.jpg|450px|center]]
|}

Applications should therefore prefer converter rates that can contain the desired signal spectrum in a single Nyquist zone, or split the signal spectrum among multiple channels and devices. While the USRP X440 does not limit the utilized Nyquist zone, performance degrades in higher orders zones and application should focus on operating in Nyquist zones 1 and 2 (For RX, zone 3 is possible, but zones 4 and higher result into significant performance degradation).


== RF-ADC Spurs to consider and how to predict them ==
Another kind of distortion originates from the ADC/DAC itself. The USRP X440 uses the Xilinx RFDC, which is a design that combines multiple converters to
achieve high RF-ADC rates. An RF-ADC in this design has 8 sub-ADCs that are interleaved together. The resulting offset spurs are minimized by the integrated self-calibration (see also <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/Key-CAL-Features-and-Guidance-Summary Key CAL Features and Guidance Summary]</ref>) executed by UHD but may still be detectable in the signal spectrum.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 4. RF-ADC Spurs with MCR = 500 MHz
|-
| style="border-style: none;" | [[File:ANxxx-adc_distortions.jpg|450px|center]]
|}

Even with the best calibration the RF-ADC spurs may still be detectable in the captured spectrum. Knowledge of the location of the spurs, in particular the RF-ADC offset spur may be used during frequency planning to select an MCR (and converter rate) that exclude the offset spur frequencies from the capture spectrum. RF-ADC input spurs on the other hand will be more difficult to avoid, but as rule of thumb for modulated input signals carrier frequencies that fall on an RF-ADC offset spur frequency should be avoided (because offset and input spurs would superimpose each other).

=== How to predict offset spurs ===
Any residual DC offset not corrected appears as a spur at k*FS/N, where FS is the composite converter rate of the RF-ADC, N is the number of sub-RF-ADCs interleaved together (8 for X4xx devices), and k = 0, 1, 2, … N.
For more information on expected spurs levels, refer to OIS at <ref>[https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Performance-Characteristics RF-ADC Performance Characteristics]</ref>.

=== How to predict input spurs ===
Any residual difference from gain and time skew correction results in spurious signals at +/-fin + (k/N)*FS, where FS is the converter rate of the RF-ADC, N is the number of sub-RF-ADCs (8 for X4xx devices), and fin is the frequency of the input signal.
For more information on expected spurs levels, refer to GTIS at <ref>[https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Performance-Characteristics RF-ADC Performance Characteristics]</ref>.


== RF-DAC Distortions ==
Like the RF-ADC, the RF-DAC is also not an ideal circuitry and suffers from zero-order hold reconstruction. To counter this undesired attenuation in all but the first Nyquist zone, the Xilinx RF-DAC offers a Mix-Mode, which improves the power response in the second Nyquist zone and is utilized by the USRP X440. This, together with an inverse sinc filter to counter residual distortion limits the practical use of the RF-DAC to the first two Nyquist zones. For more information on the RF-DAC mix-mode and inverse sinc filter characteristics, refer to <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/RF-DAC-Nyquist-Zone-Operation RF-DAC Nyquist Zone Operation]</ref>.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 5 <ref>[https://docs.xilinx.com/viewer/attachment/wIPPkVrh~0jtjy6aqWeihQ/q5kXcl5Z7lFon2v535oW0w Xilinx: Ideal DAC Output Response, Normalised to Fsample]</ref>. RF-DAC Mix-Mode and normal, ideal roll-off sinc response.
|-
| style="border-style: none;" | [[File:ANxxx-dac_roll-off_sinc_response.png|350px|center]]
|}


Note: Due to the direct sampling architecture without filters on the FBX daughterboard, TX ports will output the converter rate (Fc) with a low power (<-50 dBm) as soon as the corresponding ADCs and DACs are enabled, even if the DACs are not actively transmitting. This is a known limitation of the X440 and FBX design. For instance when acquiring a signal on the RX1 port of RF0, the converter rate (Fc) can be measured on the TX/RX0 port of RF0. While operation around the converter rate (Fc) is not recommended anyway, it is possible to suppress the converter rate (Fc) by using a frontend module with a sufficiently high attenuation at the converter rate.



== Dual Rate ==
Unlike previous USRPs, the USRP X440 supports the operation at two different master clock rates simultaneously. All channels on the first daughterboard will run on the first master clock rate / sampling rate and all channels on the second daughterboard will run on the second configured master clock rate / sampling rate. The main motivation for having two different master clock rates is the direct sampling architecture of the USRP X440 without signal conditioning and filtering. While [[#dsp-distortions|Aliases and Nyquist Zones]] describes the challenges of that, with dual rate this feature can be used to capture an RF spectrum that exceeds the bandwidth abilities of the single rate operation. Using a second rate, one can close the Nyquist gap of the other and monitor a wider spectrum for further processing.
As the clocks of both radios are derived from a common clocking chip, not all combinations are possible. Refer to [[#X440-supported-dual-rates|X440 Supported Dual Rates]] for possible RF Data Converter sampling rate combinations. The section about the [[#converter_rate-mcr-iq_rate|Relationship between RFADC/DAC Converter Rate, USRP Master Clock Rate (MCR) and Data IQ rate]] explains how to derive valid master clock rates from the RF Data converter sampling rates.

Note: When using different MCRs for both daughterboards, the device will skip the multi-tile synchronization. That means that the phase relationship between channels may not be preserved over retunes and reboots for channels of the same daughterboard and no defined phase relationship will be preserved between channels of different daughterboards.



= Use cases =
== Scan Spectrum within single Nyquist zone ==
=== Spectrum Capture between 1.7 and 1.9 GHz. ===
* Min Bandwidth: 200 MHz
* Minimum IQ Rate: 250 MSps
==== Option 1: MCR = 250 MHz, RF-ADC converter rate = 2 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_250e6_2000e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest is very close to a Nyquist zone boundary.

==== Option 2: MCR = 300 MHz, RF-ADC converter rate = 2.4 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_300e6_2400e6.jpg|450px|center]]
|}
This option is better, the spectrum of interest is well within a Nyquist zone. Within the bandwidth of interest falls one of the ADC offset spurs. If the input signal is relatively strong, the impact from this small spur is negligible. If on the other hand the input signal strength is on the low end (for the X440), then maybe a different MCR should be considered.

==== Option 3: MCR = 320 MHz, RF-ADC converter rate = 2.56 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_320e6_2560e6.jpg|450px|center]]
|}
This option avoids a potential impact of an ADC offset spur in the observed spectrum. The only drawback to option 2 is the slightly higher data rate during host post-processing.

=== Spectrum Capture between 500 MHz and 1.5 GHz. ===
The USRP X440 ships with multiple [https://uhd.readthedocs.io/en/latest/page_usrp_x4xx.html#x4xx_updating_fpga_types FPGA image flavors]. These either support 400 MHz or 1600 MHz RF bandwidth per channel. To address this use case, users have the option of using a bit file with 1600 MHz RF bandwidth to capture a contiguous spectrum, or use a 400 MHz bit file and create a stitched spectrum during host side post-processing.
==== Using 1600 MHz image ====
* Min Bandwidth: 1000 MHz
* Minimum IQ Rate: 1250 MSps
===== Option 1: MCR = 1280 MHz, RF-ADC converter rate = 2.56 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1250e6_2560e6.jpg|450px|center]]
|}
Bad option, because desired spectrum spans multiple Nyquist zones.

===== Option 2: MCR = 1600 MHz, RF-ADC converter rate = 3.2 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1600e6_3200e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest is very close to a Nyquist zone boundary.

===== Option 3: MCR = 1689.6 MHz, RF-ADC converter rate = 3.3792 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1689e6_3379e6.jpg|450px|center]]
|}
This option would work. If the input signal strength is low, using an even higher MCR would reduce the number of potential ADC offset spurs. This needs to be traded off against a higher data rate during host post-processing.

==== Using 400 MHz image ====
Due to the smaller bandwidth addressing the use case will require the use of multiple channels. The captured spectra than needs to be stitched (combined) together.
* Max Bandwidth: 400 MHz
===== Option 1: MCR 400 MHz, RF-ADC converter rate = 3.2 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_400e6_3200e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest boundary is very close to a Nyquist zone boundary.

===== Option 2: MCR 450 MHz, RF-ADC converter rate = 3.6 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_450e6_3600e6.jpg|450px|center]]
|}
This option would work. Since the spectrum of interest is larger than the per channel bandwidth the captured spectrum may contain potential ADC offset spurs. For the spectrum of interest the 3 channels would nicely use tune frequencies (680, 1000, 1320 MHz) that do not match ADC offset spur frequencies.

===== Option 3: MCR 512 MHz, RF-ADC converter rate = 4.096 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_512e6_4096e6.jpg|450px|center]]
|}
This option would work as well. Like in option 2, the spectrum of interest may contain one potential ADC offset spur (compared to 2 in option 2). The drawback to option 2 is of course again the higher data rate during host post-processing that may be offset by only having to stitch less spectra (2 vs 3) together.



== Scan Spectrum with dual master clock rate ==
=== Spectrum capture between 1.0 and 2.4 GHz (L-band) ===
* Combination of two RF-ADC converter rates: 4096 MHz and 2560 MHz
* Derived master clock rates: 1024 MHz (resampling factor 4) and 1280 MHz (resampling factor 2). The resampling factors are chosen to produce master clock rates which allow capturing a sufficient bandwidth to not have any gaps.
* Center frequencies: 1.23 GHz and 2.0 GHz respectively
* 1600 MHz FPGA image required due to the bandwidth requirements
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:AN055-L-band-dual-rate.jpg|800px|center]]
|}
In the picture you can see a light-green band between 1.0 GHz and 2.4 GHz which can be covered using two different rates: Radio0 operates at MCR=1024 MHz in its first Nyquist zone and radio1 operates at 1280 MHz in its second Nyquist zone. The coverage is shown as light-blue boxes in both frequency charts. Starting with UHD 4.6, the X440_L_band_capture.py example demonstrates this use case and by default uses center frequencies of 0.9 GHz and 2 GHz respectively. These were choosen to conveniently display the two individual spectra next to each other in a continuous spectra view without any overlap. Practical applications on the other hand need to take into account that the well usable bandwidth of each channel is only about 0.8 * MCR. For the chosen MCRs this means that the first radio has a usable bandwidth of 819.2 MHz and the second one of 1024 MHz. Taking into account that a typical RF passband in the first Nyquist zone has a passband of up to 0.4 * FS and the need for some overlap of the two spectra, the center frequency of radio0 should be set to 1.230 GHz (usable bandwidth spans from ~820 MHz to ~1640 MHz). Radio1 will be used in its second Nyquist zone, so the center frequency should be 2.0 GHz (usable bandwidth from ~1.5 GHz to ~2.5 GHz).


= Appendix =

== X440 Supported Master Clock Rates (MCR) ==
Note: The selected FPGA bitfile may further limit the maximum supported master clock rate.
{| class="wikitable" style="text-align: center; margin:auto"
|-
! MCR (MHz) !! RFDC Converter Rate (GHz)
|-
| 125.0 || 1.0
|-
| 128.0 || 1.024
|-
| 133.12 || 1.06496
|-
| 150.0 || 1.2
|-
| 153.6 || 1.2288
|-
| 160.0 || 1.28
|-
| 163.84 || 1.31072
|-
| 184.32 || 1.47456
|-
| 199.68 || 1.59744
|-
| 200.0 || 1.6
|-
| 204.8 || 1.6384
|-
| 240.0 || 1.92
|-
| 245.76 || 1.96608
|-
| 250.0 || 2.0, 1.0
|-
| 256.0 || 2.048, 1.024
|-
| 266.24 || 2.12992, 1.06496
|-
| 300.0 || 2.4, 1.2
|-
| 307.2 || 2.4576, 1.2288
|-
| 320.0 || 2.56, 1.28
|-
| 327.68 || 2.62144, 1.31072
|-
| 360.0 || 2.88, 1.44
|-
| 368.64 || 1.47456, 2.94912
|-
| 375.0 || 3.0, 1.5
|-
| 384.0 || 1.536, 3.072
|-
| 399.36 || 3.19488, 1.59744
|-
| 400.0 || 3.2, 1.6
|-
| 409.6 || 3.2768, 1.6384
|-
| 450.0 || 1.8, 3.6
|-
| 460.8 || 1.8432, 3.6864
|-
| 480.0 || 3.84, 1.92
|-
| 491.52 || 3.93216, 1.96608
|-
| 500.0 || 4.0, 2.0, 1.0
|-
| 512.0 || 1.024, 2.048, 4.096
|-
| 532.48 || 1.06496, 2.12992
|-
| 552.96 || 2.21184, 1.10592
|-
| 599.04 || 1.19808, 2.39616
|-
| 600.0 || 1.2, 2.4
|-
| 614.4 || 1.2288, 2.4576
|-
| 625.0 || 1.25, 2.5
|-
| 640.0 || 2.56, 1.28
|-
| 655.36 || 1.31072, 2.62144
|-
| 665.6 || 1.3312, 2.6624
|-
| 720.0 || 1.44, 2.88
|-
| 737.28 || 1.47456, 2.94912
|-
| 750.0 || 1.5, 3.0
|-
| 768.0 || 1.536, 3.072
|-
| 798.72 || 3.19488, 1.59744
|-
| 800.0 || 1.6, 3.2
|-
| 819.2 || 3.2768, 1.6384
|-
| 840.0 || 1.68, 3.36
|-
| 860.16 || 3.44064, 1.72032
|-
| 875.0 || 3.5, 1.75
|-
| 896.0 || 3.584, 1.792
|-
| 900.0 || 1.8, 3.6
|-
| 921.6 || 1.8432, 3.6864
|-
| 931.84 || 1.86368, 3.72736
|-
| 960.0 || 3.84, 1.92
|-
| 983.04 || 1.96608, 3.93216
|-
| 998.4 || 3.9936, 1.9968
|-
| 1000.0 || 4.0, 2.0
|-
| 1024.0 || 4.096, 2.048
|-
| 1050.0 || 2.1
|-
| 1064.96 || 2.12992
|-
| 1075.2 || 2.1504
|-
| 1080.0 || 2.16
|-
| 1105.92 || 2.21184
|-
| 1120.0 || 2.24
|-
| 1125.0 || 2.25
|-
| 1146.88 || 2.29376
|-
| 1152.0 || 2.304
|-
| 1198.08 || 2.39616
|-
| 1200.0 || 2.4
|-
| 1228.8 || 2.4576
|-
| 1280.0 || 2.56
|-
| 1290.24 || 2.58048
|-
| 1310.72 || 2.62144
|-
| 1331.2 || 2.6624
|-
| 1350.0 || 2.7
|-
| 1382.4 || 2.7648
|-
| 1397.76 || 2.79552
|-
| 1400.0 || 2.8
|-
| 1433.6 || 2.8672
|-
| 1440.0 || 2.88
|-
| 1474.56 || 2.94912
|-
| 1500.0 || 3.0
|-
| 1536.0 || 3.072
|-
| 1600.0 || 3.2
|-
| 1625.0 || 3.25
|-
| 1638.4 || 3.2768
|-
| 1650.0 || 3.3
|-
| 1658.88 || 3.31776
|-
| 1664.0 || 3.328
|-
| 1680.0 || 3.36
|-
| 1689.6 || 3.3792
|-
| 1720.32 || 3.44064
|-
| 1730.56 || 3.46112
|-
| 1750.0 || 3.5
|-
| 1760.0 || 3.52
|-
| 1792.0 || 3.584
|-
| 1797.12 || 3.59424
|-
| 1800.0 || 3.6
|-
| 1802.24 || 3.60448
|-
| 1843.2 || 3.6864
|-
| 1863.68 || 3.72736
|-
| 1875.0 || 3.75
|-
| 1920.0 || 3.84
|-
| 1950.0 || 3.9
|-
| 1966.08 || 3.93216
|-
| 1996.8 || 3.9936
|-
| 2000.0 || 4.0
|-
| 2027.52 || 4.05504
|-
| 2048.0 || 4.096
|}


== X440 Supported Master Clock Rate combinations (Dual Rate) ==
Important: For the best RF performance it is required to configure the master clock rate that is connected to the higher RF-ADC/DAC converter rate on the first radio and the MCR connected to the lower converter rate second. Not all master clock rate combinations listed in this table will comply to this requirement by themselves. Specifying the converter_rate argument or swapping the master clock rates will help resolving issues. The selected FPGA bitfile may further limit the maximum supported master clock rate.
{| class="wikitable" style="text-align: center; margin:auto"
|-
| MCR0 (MHz) || MCR1 (MHz)
|-
| 125.0 || 250.0, 375.0, 500.0, 750.0, 875.0, 1000.0, 1125.0, 1625.0, 1750.0, 1875.0, 2000.0
|-
| 128.0 || 384.0, 512.0, 768.0, 1152.0
|-
| 133.12 || 266.24, 399.36, 532.48, 665.6, 798.72, 931.84, 1064.96, 1198.08, 1331.2, 1730.56, 1863.68, 1996.8
|-
| 150.0 || 300.0, 450.0, 600.0, 750.0, 900.0, 1050.0, 1350.0, 1500.0, 1650.0, 1800.0, 1950.0
|-
| 153.6 || 307.2, 614.4, 1228.8
|-
| 160.0 || 320.0, 640.0, 800.0, 1120.0, 1280.0, 1600.0, 1760.0
|-
| 163.84 || 327.68, 655.36, 1146.88, 1310.72, 1474.56, 1802.24
|-
| 184.32 || 368.64, 552.96, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2, 2027.52
|-
| 199.68 || 399.36, 599.04, 798.72, 998.4, 1198.08, 1397.76, 1797.12, 1996.8
|-
| 200.0 || 400.0, 800.0, 1200.0, 1400.0, 1600.0
|-
| 204.8 || 409.6, 819.2, 1433.6, 1638.4
|-
| 240.0 || 360.0, 480.0, 600.0, 720.0, 840.0, 960.0, 1440.0, 1680.0, 1800.0, 1920.0
|-
| 245.76 || 491.52, 860.16, 983.04, 1720.32, 1966.08
|-
| 250.0 || 125.0, 375.0, 500.0, 750.0, 875.0, 1000.0, 1500.0, 1625.0, 1750.0, 1875.0, 2000.0
|-
| 256.0 || 640.0, 896.0, 1024.0, 1280.0, 1664.0, 1792.0, 2048.0
|-
| 266.24 || 133.12, 399.36, 532.48, 665.6, 798.72, 931.84, 1064.96, 1331.2, 1730.56, 1863.68, 1996.8
|-
| 300.0 || 150.0, 450.0, 600.0, 750.0, 900.0, 1050.0, 1500.0, 1650.0, 1800.0, 1950.0
|-
| 307.2 || 153.6, 614.4, 1228.8
|-
| 320.0 || 160.0, 640.0, 800.0, 1120.0, 1280.0, 1600.0, 1760.0
|-
| 327.68 || 163.84, 655.36, 1146.88, 1310.72, 1802.24
|-
| 360.0 || 240.0, 600.0, 720.0, 1080.0, 1800.0
|-
| 368.64 || 184.32, 552.96, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2, 2027.52
|-
| 375.0 || 125.0, 250.0, 750.0, 1125.0, 1500.0, 1875.0
|-
| 384.0 || 128.0, 768.0, 1152.0, 1536.0
|-
| 399.36 || 133.12, 199.68, 266.24, 599.04, 665.6, 798.72, 998.4, 1198.08, 1331.2, 1397.76, 1797.12, 1996.8
|-
| 400.0 || 200.0, 800.0, 1200.0, 1400.0, 1600.0
|-
| 409.6 || 204.8, 819.2, 1433.6, 1638.4
|-
| 450.0 || 150.0, 300.0, 600.0, 750.0, 900.0, 1350.0, 1500.0, 1800.0
|-
| 460.8 || 768.0, 921.6, 1075.2, 1382.4, 1536.0
|-
| 480.0 || 240.0, 720.0, 840.0, 960.0, 1440.0, 1680.0, 1920.0
|-
| 491.52 || 245.76, 860.16, 983.04, 1720.32, 1966.08
|-
| 500.0 || 125.0, 250.0, 750.0, 875.0, 1000.0, 1500.0, 1750.0, 2000.0
|-
| 512.0 || 128.0, 768.0, 1536.0
|-
| 532.48 || 133.12, 266.24, 798.72, 931.84, 1064.96, 1331.2, 1863.68
|-
| 552.96 || 184.32, 368.64, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2
|-
| 599.04 || 199.68, 399.36, 798.72, 998.4, 1198.08, 1397.76, 1797.12, 1996.8
|-
| 600.0 || 150.0, 240.0, 300.0, 360.0, 450.0, 720.0, 900.0, 1000.0, 1050.0, 1500.0, 1800.0, 2000.0
|-
| 614.4 || 153.6, 307.2, 1228.8
|-
| 640.0 || 160.0, 256.0, 320.0, 800.0, 1120.0, 1280.0, 1600.0
|-
| 655.36 || 163.84, 327.68, 1146.88, 1310.72
|-
| 665.6 || 133.12, 266.24, 399.36, 798.72, 1331.2, 1996.8
|-
| 720.0 || 240.0, 360.0, 480.0, 600.0, 960.0, 1440.0, 1680.0, 1800.0, 1920.0
|-
| 737.28 || 184.32, 368.64, 552.96, 1105.92, 1290.24, 1474.56, 1843.2
|-
| 750.0 || 125.0, 150.0, 250.0, 300.0, 375.0, 450.0, 500.0, 900.0, 1000.0, 1125.0, 1500.0, 1750.0, 1875.0, 2000.0
|-
| 768.0 || 128.0, 384.0, 460.8, 512.0, 921.6, 1152.0, 1536.0
|-
| 798.72 || 133.12, 199.68, 266.24, 399.36, 532.48, 599.04, 665.6, 998.4, 1064.96, 1198.08, 1331.2, 1397.76, 1863.68, 1996.8
|-
| 800.0 || 160.0, 200.0, 320.0, 400.0, 640.0, 1200.0, 1400.0, 1600.0
|-
| 819.2 || 204.8, 409.6, 1433.6, 1638.4
|-
| 840.0 || 240.0, 480.0, 1680.0
|-
| 860.16 || 245.76, 491.52, 1720.32
|-
| 875.0 || 125.0, 250.0, 500.0, 1750.0
|-
| 896.0 || 256.0, 1792.0
|-
| 900.0 || 150.0, 300.0, 450.0, 600.0, 750.0, 1500.0, 1800.0
|-
| 921.6 || 460.8, 768.0, 1536.0
|-
| 931.84 || 133.12, 266.24, 532.48, 1863.68
|-
| 960.0 || 240.0, 480.0, 720.0, 1440.0, 1920.0
|-
| 983.04 || 245.76, 491.52, 1966.08
|-
| 998.4 || 199.68, 399.36, 599.04, 798.72, 1198.08, 1996.8
|-
| 1000.0 || 125.0, 250.0, 500.0, 600.0, 750.0, 1500.0, 2000.0
|-
| 1024.0 || 256.0, 1280.0, 2048.0
|-
| 1050.0 || 150.0, 300.0, 600.0
|-
| 1064.96 || 133.12, 266.24, 532.48, 798.72, 1331.2
|-
| 1075.2 || 460.8
|-
| 1080.0 || 360.0
|-
| 1105.92 || 184.32, 368.64, 552.96, 737.28, 1474.56, 1658.88, 1843.2
|-
| 1120.0 || 160.0, 320.0, 640.0
|-
| 1125.0 || 125.0, 375.0, 750.0, 1500.0, 1875.0
|-
| 1146.88 || 163.84, 327.68, 655.36
|-
| 1152.0 || 128.0, 384.0, 768.0, 1536.0
|-
| 1198.08 || 133.12, 199.68, 399.36, 599.04, 798.72, 998.4, 1797.12, 1996.8
|-
| 1200.0 || 200.0, 400.0, 800.0, 1600.0
|-
| 1228.8 || 153.6, 307.2, 614.4
|-
| 1280.0 || 160.0, 256.0, 320.0, 640.0, 1024.0, 1600.0
|-
| 1290.24 || 184.32, 368.64, 552.96, 737.28
|-
| 1310.72 || 163.84, 327.68, 655.36
|-
| 1331.2 || 133.12, 266.24, 399.36, 532.48, 665.6, 798.72, 1064.96, 1996.8
|-
| 1350.0 || 150.0, 450.0
|-
| 1382.4 || 460.8
|-
| 1397.76 || 199.68, 399.36, 599.04, 798.72
|-
| 1400.0 || 200.0, 400.0, 800.0
|-
| 1433.6 || 204.8, 409.6, 819.2
|-
| 1440.0 || 240.0, 480.0, 720.0, 960.0, 1920.0
|-
| 1474.56 || 163.84, 184.32, 368.64, 552.96, 737.28, 1105.92
|-
| 1500.0 || 150.0, 250.0, 300.0, 375.0, 450.0, 500.0, 600.0, 750.0, 900.0, 1000.0, 1125.0, 2000.0
|-
| 1536.0 || 384.0, 460.8, 512.0, 768.0, 921.6, 1152.0
|-
| 1600.0 || 160.0, 200.0, 320.0, 400.0, 640.0, 800.0, 1200.0, 1280.0
|-
| 1625.0 || 125.0, 250.0
|-
| 1638.4 || 204.8, 409.6, 819.2
|-
| 1650.0 || 150.0, 300.0
|-
| 1658.88 || 184.32, 368.64, 552.96, 1105.92
|-
| 1664.0 || 256.0
|-
| 1680.0 || 240.0, 480.0, 720.0, 840.0
|-
| 1720.32 || 245.76, 491.52, 860.16
|-
| 1730.56 || 133.12, 266.24
|-
| 1750.0 || 125.0, 250.0, 500.0, 750.0, 875.0
|-
| 1760.0 || 160.0, 320.0
|-
| 1792.0 || 256.0, 896.0
|-
| 1797.12 || 199.68, 399.36, 599.04, 1198.08
|-
| 1800.0 || 150.0, 240.0, 300.0, 360.0, 450.0, 600.0, 720.0, 900.0
|-
| 1802.24 || 163.84, 327.68
|-
| 1843.2 || 184.32, 368.64, 552.96, 737.28, 1105.92
|-
| 1863.68 || 133.12, 266.24, 532.48, 798.72, 931.84
|-
| 1875.0 || 125.0, 250.0, 375.0, 750.0, 1125.0
|-
| 1920.0 || 240.0, 480.0, 720.0, 960.0, 1440.0
|-
| 1950.0 || 150.0, 300.0
|-
| 1966.08 || 245.76, 491.52, 983.04
|-
| 1996.8 || 133.12, 199.68, 266.24, 399.36, 599.04, 665.6, 798.72, 998.4, 1198.08, 1331.2
|-
| 2000.0 || 125.0, 250.0, 500.0, 600.0, 750.0, 1000.0, 1500.0
|-
| 2027.52 || 184.32, 368.64
|-
| 2048.0 || 256.0, 1024.0
|}


== References and Related Documentation ==
* [https://www.ni.com/en/solutions/aerospace-defense/radar-electronic-warfare-sigint/advantages-of-direct-rf-sampling-architectures.html Advantages of Direct RF Sampling Architectures]
* [https://docs.xilinx.com/r/en-US/pg269-rf-data-converter Zynq UltraScale+ RFSoC RF Data Converter v2.6 Gen 1/2/3/DFE LogiCORE IP Product Guide (PG269)]
* [https://events.gnuradio.org/event/21/contributions/392/attachments/123/285/Lo%20and%20behold,%20no%20LO.pdf GRcon 23 - Lo and behold, no LO!]
* [https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Electrical-Characteristics Zynq UltraScale+ RFSoC Data Sheet: DC and AC Switching Characteristics (DS926)]

= Footnotes =
<references />

About Sampling Rates and Master Clock Rates for the USRP X440

2024-01-05T13:36:05Z

MartinAnderseck: Spelling...

== Application Note Number and Authors ==

'''AN-055''' by Marian Koop and Martin Anderseck



= Overview =
This application note guides users through the selection process of Master Clock Rates (MCR) for the [https://kb.ettus.com/X440#X440 USRP X440]. It will highlight possible implications and side effects as well as design specific differences to other USRPs (like the X410).


= USRP X440 Configuration Considerations =
The USRP X440 is a [https://uhd.readthedocs.io/en/latest/page_fbx.html#fbx_too balun-coupled transceiver] without built-in RF signal conditioning. Compared to other RF architectures this enables the USRP X440 to access the full RF bandwidth available to the ADC/DAC, but also requires additional frequency planning. To achieve this, the USRP X440 utilizes its ADC/DAC in direct sampling mode and is susceptible to various effects that may distort the signal of interest. These can be separated into distortions from both signal processing and from the ADC/DAC design.


== Relationship between RF-ADC/DAC Converter Rate, USRP Master Clock Rate (MCR), Data IQ rate ==
Except for the 200 MHz variant, the default USRP X440 FPGA images do not contain a configurable DDC<ref>Digital Down Conversion</ref>/DUC<ref>Digital Up Conversion</ref> block. This means that the IQ sample rate (FIQ) is the same as the Master Clock Rate (MCR) that goes into the RFNoC Radio block. However, unlike most other USRPs the USRP X440 supports a highly variable MCR. The RF Data Converter sampling rate (FS) is chosen by UHD based on the MCR and the available resampling factors of 2, 4, or 8, and defaults to the highest achievable values with these factors. This can be overridden if the desired MCR can be achieved with multiple converter rates (see device argument [https://uhd.readthedocs.io/en/latest/page_usrp_x4xx.html#x4xx_usage_args converter_rate]). The inverse calculation - divide the converter rate by 8, 4 or 2 - has to be done to derive the master clock rate if a specific converter rate shall be used. Figure 1 depicts the simplified signal path block diagram for the USRP X440.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 1. Simplified USRP X440 Signal Path
|-
| style="border-style: none;" | [[File:ANxxx-X440_signal_path.jpg|450px|center]]
|}


== Aliases and Nyquist Zones ==
By itself the USRP X440 can sample input signals at frequencies above the Nyquist frequency<ref>[https://en.wikipedia.org/wiki/Nyquist_frequency Nyquist frequency]</ref>, which is half of the ADC converter sampling rate (FS). However, this method introduces aliasing effects, which cause unwanted signals to appear as mirror images around multiples of the Nyquist frequency (FS/2) in the output spectrum. The first Nyquist zone (N1) is the frequency range from 0 to FS/2, and the second Nyquist zone (N2) goes from FS/2 to FS. Other Nyquist zones are numbered in ascending order, each spanning FS/2. The digital passband in each Nyquist zone can be calculated as 0.4 * FS (see also <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/RF-ADC-Decimation-Filters-Gen-1/Gen-2 Xilinx RF-ADC Decimation Filters (Gen-1)]</ref>). The following figure depicts the Nyquist zones for the minimum and maximum RF-ADC converter rates supported by the USRP X440. Note that the illustrations do not show the effects of external, analog filters on the achievable passband within a Nyquist zone. A typical expectation is, that the unusable frequency range around each Nyquist zone boundary (also often referred to as a guard band) increases with ascending Nyquist zone order and results in decreasing, lopsided achievable passbands.
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 2. Nyquist Zones
|-
| style="border-style: none;" | [[File:ANxxx-X440_nyquist_zones.jpg|450px|center]]
|}

Knowledge of signal aliases can both be exploited and create uncertainties. Applications could utilize intentional under sampling (also referred as "bandpass sampling") to receive signals at greater than FS/2. The same effect may on the other hand lead to garbled or distorted signal detection if the signal of interest spans multiple Nyquist zones or interferer signals are aliased into the observed spectrum. Both effects are depicted in figure 3.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 3. Aliases - Wanted and unwanted
|-
| style="border-style: none;" | [[File:ANxxx-wanted_and_unwanted_aliases.jpg|450px|center]]
|}

Applications should therefore prefer converter rates that can contain the desired signal spectrum in a single Nyquist zone, or split the signal spectrum among multiple channels and devices. While the USRP X440 does not limit the utilized Nyquist zone, performance degrades in higher orders zones and application should focus on operating in Nyquist zones 1 and 2 (For RX, zone 3 is possible, but zones 4 and higher result into significant performance degradation).


== RF-ADC Spurs to consider and how to predict them ==
Another kind of distortion originates from the ADC/DAC itself. The USRP X440 uses the Xilinx RFDC, which is a design that combines multiple converters to
achieve high RF-ADC rates. An RF-ADC in this design has 8 sub-ADCs that are interleaved together. The resulting offset spurs are minimized by the integrated self-calibration (see also <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/Key-CAL-Features-and-Guidance-Summary Key CAL Features and Guidance Summary]</ref>) executed by UHD but may still be detectable in the signal spectrum.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 4. RF-ADC Spurs with MCR = 500 MHz
|-
| style="border-style: none;" | [[File:ANxxx-adc_distortions.jpg|450px|center]]
|}

Even with the best calibration the RF-ADC spurs may still be detectable in the captured spectrum. Knowledge of the location of the spurs, in particular the RF-ADC offset spur may be used during frequency planning to select an MCR (and converter rate) that exclude the offset spur frequencies from the capture spectrum. RF-ADC input spurs on the other hand will be more difficult to avoid, but as rule of thumb for modulated input signals carrier frequencies that fall on an RF-ADC offset spur frequency should be avoided (because offset and input spurs would superimpose each other).

=== How to predict offset spurs ===
Any residual DC offset not corrected appears as a spur at k*FS/N, where FS is the composite converter rate of the RF-ADC, N is the number of sub-RF-ADCs interleaved together (8 for X4xx devices), and k = 0, 1, 2, … N.
For more information on expected spurs levels, refer to OIS at <ref>[https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Performance-Characteristics RF-ADC Performance Characteristics]</ref>.

=== How to predict input spurs ===
Any residual difference from gain and time skew correction results in spurious signals at +/-fin + (k/N)*FS, where FS is the converter rate of the RF-ADC, N is the number of sub-RF-ADCs (8 for X4xx devices), and fin is the frequency of the input signal.
For more information on expected spurs levels, refer to GTIS at <ref>[https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Performance-Characteristics RF-ADC Performance Characteristics]</ref>.


== RF-DAC Distortions ==
Like the RF-ADC, the RF-DAC is also not an ideal circuitry and suffers from zero-order hold reconstruction. To counter this undesired attenuation in all but the first Nyquist zone, the Xilinx RF-DAC offers a Mix-Mode, which improves the power response in the second Nyquist zone and is utilized by the USRP X440. This, together with an inverse sinc filter to counter residual distortion limits the practical use of the RF-DAC to the first two Nyquist zones. For more information on the RF-DAC mix-mode and inverse sinc filter characteristics, refer to <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/RF-DAC-Nyquist-Zone-Operation RF-DAC Nyquist Zone Operation]</ref>.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 5 <ref>[https://docs.xilinx.com/viewer/attachment/wIPPkVrh~0jtjy6aqWeihQ/q5kXcl5Z7lFon2v535oW0w Xilinx: Ideal DAC Output Response, Normalised to Fsample]</ref>. RF-DAC Mix-Mode and normal, ideal roll-off sinc response.
|-
| style="border-style: none;" | [[File:ANxxx-dac_roll-off_sinc_response.png|350px|center]]
|}




== Dual Rate ==
Unlike previous USRPs, the USRP X440 supports the operation at two different master clock rates simultaneously. All channels on the first daughterboard will run on the first master clock rate / sampling rate and all channels on the second daughterboard will run on the second configured master clock rate / sampling rate. The main motivation for having two different master clock rates is the direct sampling architecture of the USRP X440 without signal conditioning and filtering. While [[#dsp-distortions|Aliases and Nyquist Zones]] describes the challenges of that, with dual rate this feature can be used to capture an RF spectrum that exceeds the bandwidth abilities of the single rate operation. Using a second rate, one can close the Nyquist gap of the other and monitor a wider spectrum for further processing.
As the clocks of both radios are derived from a common clocking chip, not all combinations are possible. Refer to [[#X440-supported-dual-rates|X440 Supported Dual Rates]] for possible RF Data Converter sampling rate combinations. The section about the [[#converter_rate-mcr-iq_rate|Relationship between RFADC/DAC Converter Rate, USRP Master Clock Rate (MCR) and Data IQ rate]] explains how to derive valid master clock rates from the RF Data converter sampling rates.

Note: When using different MCRs for both daughterboards, the device will skip the multi-tile synchronization. That means that the phase relationship between channels may not be preserved over retunes and reboots for channels of the same daughterboard and no defined phase relationship will be preserved between channels of different daughterboards.



= Use cases =
== Scan Spectrum within single Nyquist zone ==
=== Spectrum Capture between 1.7 and 1.9 GHz. ===
* Min Bandwidth: 200 MHz
* Minimum IQ Rate: 250 MSps
==== Option 1: MCR = 250 MHz, RF-ADC converter rate = 2 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_250e6_2000e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest is very close to a Nyquist zone boundary.

==== Option 2: MCR = 300 MHz, RF-ADC converter rate = 2.4 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_300e6_2400e6.jpg|450px|center]]
|}
This option is better, the spectrum of interest is well within a Nyquist zone. Within the bandwidth of interest falls one of the ADC offset spurs. If the input signal is relatively strong, the impact from this small spur is negligible. If on the other hand the input signal strength is on the low end (for the X440), then maybe a different MCR should be considered.

==== Option 3: MCR = 320 MHz, RF-ADC converter rate = 2.56 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_320e6_2560e6.jpg|450px|center]]
|}
This option avoids a potential impact of an ADC offset spur in the observed spectrum. The only drawback to option 2 is the slightly higher data rate during host post-processing.

=== Spectrum Capture between 500 MHz and 1.5 GHz. ===
The USRP X440 ships with multiple [https://uhd.readthedocs.io/en/latest/page_usrp_x4xx.html#x4xx_updating_fpga_types FPGA image flavors]. These either support 400 MHz or 1600 MHz RF bandwidth per channel. To address this use case, users have the option of using a bit file with 1600 MHz RF bandwidth to capture a contiguous spectrum, or use a 400 MHz bit file and create a stitched spectrum during host side post-processing.
==== Using 1600 MHz image ====
* Min Bandwidth: 1000 MHz
* Minimum IQ Rate: 1250 MSps
===== Option 1: MCR = 1280 MHz, RF-ADC converter rate = 2.56 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1250e6_2560e6.jpg|450px|center]]
|}
Bad option, because desired spectrum spans multiple Nyquist zones.

===== Option 2: MCR = 1600 MHz, RF-ADC converter rate = 3.2 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1600e6_3200e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest is very close to a Nyquist zone boundary.

===== Option 3: MCR = 1689.6 MHz, RF-ADC converter rate = 3.3792 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1689e6_3379e6.jpg|450px|center]]
|}
This option would work. If the input signal strength is low, using an even higher MCR would reduce the number of potential ADC offset spurs. This needs to be traded off against a higher data rate during host post-processing.

==== Using 400 MHz image ====
Due to the smaller bandwidth addressing the use case will require the use of multiple channels. The captured spectra than needs to be stitched (combined) together.
* Max Bandwidth: 400 MHz
===== Option 1: MCR 400 MHz, RF-ADC converter rate = 3.2 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_400e6_3200e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest boundary is very close to a Nyquist zone boundary.

===== Option 2: MCR 450 MHz, RF-ADC converter rate = 3.6 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_450e6_3600e6.jpg|450px|center]]
|}
This option would work. Since the spectrum of interest is larger than the per channel bandwidth the captured spectrum may contain potential ADC offset spurs. For the spectrum of interest the 3 channels would nicely use tune frequencies (680, 1000, 1320 MHz) that do not match ADC offset spur frequencies.

===== Option 3: MCR 512 MHz, RF-ADC converter rate = 4.096 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_512e6_4096e6.jpg|450px|center]]
|}
This option would work as well. Like in option 2, the spectrum of interest may contain one potential ADC offset spur (compared to 2 in option 2). The drawback to option 2 is of course again the higher data rate during host post-processing that may be offset by only having to stitch less spectra (2 vs 3) together.



== Scan Spectrum with dual master clock rate ==
=== Spectrum capture between 1.0 and 2.4 GHz (L-band) ===
* Combination of two RF-ADC converter rates: 4096 MHz and 2560 MHz
* Derived master clock rates: 1024 MHz (resampling factor 4) and 1280 MHz (resampling factor 2). The resampling factors are chosen to produce master clock rates which allow capturing a sufficient bandwidth to not have any gaps.
* Center frequencies: 1.23 GHz and 2.0 GHz respectively
* 1600 MHz FPGA image required due to the bandwidth requirements
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:AN055-L-band-dual-rate.jpg|800px|center]]
|}
In the picture you can see a light-green band between 1.0 GHz and 2.4 GHz which can be covered using two different rates: Radio0 operates at MCR=1024 MHz in its first Nyquist zone and radio1 operates at 1280 MHz in its second Nyquist zone. The coverage is shown as light-blue boxes in both frequency charts. Starting with UHD 4.6, the X440_L_band_capture.py example demonstrates this use case and by default uses center frequencies of 0.9 GHz and 2 GHz respectively. These were choosen to conveniently display the two individual spectra next to each other in a continuous spectra view without any overlap. Practical applications on the other hand need to take into account that the well usable bandwidth of each channel is only about 0.8 * MCR. For the chosen MCRs this means that the first radio has a usable bandwidth of 819.2 MHz and the second one of 1024 MHz. Taking into account that a typical RF passband in the first Nyquist zone has a passband of up to 0.4 * FS and the need for some overlap of the two spectra, the center frequency of radio0 should be set to 1.230 GHz (usable bandwidth spans from ~820 MHz to ~1640 MHz). Radio1 will be used in its second Nyquist zone, so the center frequency should be 2.0 GHz (usable bandwidth from ~1.5 GHz to ~2.5 GHz).


= Appendix =

== X440 Supported Master Clock Rates (MCR) ==
Note: The selected FPGA bitfile may further limit the maximum supported master clock rate.
{| class="wikitable" style="text-align: center; margin:auto"
|-
! MCR (MHz) !! RFDC Converter Rate (GHz)
|-
| 125.0 || 1.0
|-
| 128.0 || 1.024
|-
| 133.12 || 1.06496
|-
| 150.0 || 1.2
|-
| 153.6 || 1.2288
|-
| 160.0 || 1.28
|-
| 163.84 || 1.31072
|-
| 184.32 || 1.47456
|-
| 199.68 || 1.59744
|-
| 200.0 || 1.6
|-
| 204.8 || 1.6384
|-
| 240.0 || 1.92
|-
| 245.76 || 1.96608
|-
| 250.0 || 2.0, 1.0
|-
| 256.0 || 2.048, 1.024
|-
| 266.24 || 2.12992, 1.06496
|-
| 300.0 || 2.4, 1.2
|-
| 307.2 || 2.4576, 1.2288
|-
| 320.0 || 2.56, 1.28
|-
| 327.68 || 2.62144, 1.31072
|-
| 360.0 || 2.88, 1.44
|-
| 368.64 || 1.47456, 2.94912
|-
| 375.0 || 3.0, 1.5
|-
| 384.0 || 1.536, 3.072
|-
| 399.36 || 3.19488, 1.59744
|-
| 400.0 || 3.2, 1.6
|-
| 409.6 || 3.2768, 1.6384
|-
| 450.0 || 1.8, 3.6
|-
| 460.8 || 1.8432, 3.6864
|-
| 480.0 || 3.84, 1.92
|-
| 491.52 || 3.93216, 1.96608
|-
| 500.0 || 4.0, 2.0, 1.0
|-
| 512.0 || 1.024, 2.048, 4.096
|-
| 532.48 || 1.06496, 2.12992
|-
| 552.96 || 2.21184, 1.10592
|-
| 599.04 || 1.19808, 2.39616
|-
| 600.0 || 1.2, 2.4
|-
| 614.4 || 1.2288, 2.4576
|-
| 625.0 || 1.25, 2.5
|-
| 640.0 || 2.56, 1.28
|-
| 655.36 || 1.31072, 2.62144
|-
| 665.6 || 1.3312, 2.6624
|-
| 720.0 || 1.44, 2.88
|-
| 737.28 || 1.47456, 2.94912
|-
| 750.0 || 1.5, 3.0
|-
| 768.0 || 1.536, 3.072
|-
| 798.72 || 3.19488, 1.59744
|-
| 800.0 || 1.6, 3.2
|-
| 819.2 || 3.2768, 1.6384
|-
| 840.0 || 1.68, 3.36
|-
| 860.16 || 3.44064, 1.72032
|-
| 875.0 || 3.5, 1.75
|-
| 896.0 || 3.584, 1.792
|-
| 900.0 || 1.8, 3.6
|-
| 921.6 || 1.8432, 3.6864
|-
| 931.84 || 1.86368, 3.72736
|-
| 960.0 || 3.84, 1.92
|-
| 983.04 || 1.96608, 3.93216
|-
| 998.4 || 3.9936, 1.9968
|-
| 1000.0 || 4.0, 2.0
|-
| 1024.0 || 4.096, 2.048
|-
| 1050.0 || 2.1
|-
| 1064.96 || 2.12992
|-
| 1075.2 || 2.1504
|-
| 1080.0 || 2.16
|-
| 1105.92 || 2.21184
|-
| 1120.0 || 2.24
|-
| 1125.0 || 2.25
|-
| 1146.88 || 2.29376
|-
| 1152.0 || 2.304
|-
| 1198.08 || 2.39616
|-
| 1200.0 || 2.4
|-
| 1228.8 || 2.4576
|-
| 1280.0 || 2.56
|-
| 1290.24 || 2.58048
|-
| 1310.72 || 2.62144
|-
| 1331.2 || 2.6624
|-
| 1350.0 || 2.7
|-
| 1382.4 || 2.7648
|-
| 1397.76 || 2.79552
|-
| 1400.0 || 2.8
|-
| 1433.6 || 2.8672
|-
| 1440.0 || 2.88
|-
| 1474.56 || 2.94912
|-
| 1500.0 || 3.0
|-
| 1536.0 || 3.072
|-
| 1600.0 || 3.2
|-
| 1625.0 || 3.25
|-
| 1638.4 || 3.2768
|-
| 1650.0 || 3.3
|-
| 1658.88 || 3.31776
|-
| 1664.0 || 3.328
|-
| 1680.0 || 3.36
|-
| 1689.6 || 3.3792
|-
| 1720.32 || 3.44064
|-
| 1730.56 || 3.46112
|-
| 1750.0 || 3.5
|-
| 1760.0 || 3.52
|-
| 1792.0 || 3.584
|-
| 1797.12 || 3.59424
|-
| 1800.0 || 3.6
|-
| 1802.24 || 3.60448
|-
| 1843.2 || 3.6864
|-
| 1863.68 || 3.72736
|-
| 1875.0 || 3.75
|-
| 1920.0 || 3.84
|-
| 1950.0 || 3.9
|-
| 1966.08 || 3.93216
|-
| 1996.8 || 3.9936
|-
| 2000.0 || 4.0
|-
| 2027.52 || 4.05504
|-
| 2048.0 || 4.096
|}


== X440 Supported Master Clock Rate combinations (Dual Rate) ==
Important: For the best RF performance it is required to configure the master clock rate that is connected to the higher RF-ADC/DAC converter rate on the first radio and the MCR connected to the lower converter rate second. Not all master clock rate combinations listed in this table will comply to this requirement by themselves. Specifying the converter_rate argument or swapping the master clock rates will help resolving issues. The selected FPGA bitfile may further limit the maximum supported master clock rate.
{| class="wikitable" style="text-align: center; margin:auto"
|-
| MCR0 (MHz) || MCR1 (MHz)
|-
| 125.0 || 250.0, 375.0, 500.0, 750.0, 875.0, 1000.0, 1125.0, 1625.0, 1750.0, 1875.0, 2000.0
|-
| 128.0 || 384.0, 512.0, 768.0, 1152.0
|-
| 133.12 || 266.24, 399.36, 532.48, 665.6, 798.72, 931.84, 1064.96, 1198.08, 1331.2, 1730.56, 1863.68, 1996.8
|-
| 150.0 || 300.0, 450.0, 600.0, 750.0, 900.0, 1050.0, 1350.0, 1500.0, 1650.0, 1800.0, 1950.0
|-
| 153.6 || 307.2, 614.4, 1228.8
|-
| 160.0 || 320.0, 640.0, 800.0, 1120.0, 1280.0, 1600.0, 1760.0
|-
| 163.84 || 327.68, 655.36, 1146.88, 1310.72, 1474.56, 1802.24
|-
| 184.32 || 368.64, 552.96, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2, 2027.52
|-
| 199.68 || 399.36, 599.04, 798.72, 998.4, 1198.08, 1397.76, 1797.12, 1996.8
|-
| 200.0 || 400.0, 800.0, 1200.0, 1400.0, 1600.0
|-
| 204.8 || 409.6, 819.2, 1433.6, 1638.4
|-
| 240.0 || 360.0, 480.0, 600.0, 720.0, 840.0, 960.0, 1440.0, 1680.0, 1800.0, 1920.0
|-
| 245.76 || 491.52, 860.16, 983.04, 1720.32, 1966.08
|-
| 250.0 || 125.0, 375.0, 500.0, 750.0, 875.0, 1000.0, 1500.0, 1625.0, 1750.0, 1875.0, 2000.0
|-
| 256.0 || 640.0, 896.0, 1024.0, 1280.0, 1664.0, 1792.0, 2048.0
|-
| 266.24 || 133.12, 399.36, 532.48, 665.6, 798.72, 931.84, 1064.96, 1331.2, 1730.56, 1863.68, 1996.8
|-
| 300.0 || 150.0, 450.0, 600.0, 750.0, 900.0, 1050.0, 1500.0, 1650.0, 1800.0, 1950.0
|-
| 307.2 || 153.6, 614.4, 1228.8
|-
| 320.0 || 160.0, 640.0, 800.0, 1120.0, 1280.0, 1600.0, 1760.0
|-
| 327.68 || 163.84, 655.36, 1146.88, 1310.72, 1802.24
|-
| 360.0 || 240.0, 600.0, 720.0, 1080.0, 1800.0
|-
| 368.64 || 184.32, 552.96, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2, 2027.52
|-
| 375.0 || 125.0, 250.0, 750.0, 1125.0, 1500.0, 1875.0
|-
| 384.0 || 128.0, 768.0, 1152.0, 1536.0
|-
| 399.36 || 133.12, 199.68, 266.24, 599.04, 665.6, 798.72, 998.4, 1198.08, 1331.2, 1397.76, 1797.12, 1996.8
|-
| 400.0 || 200.0, 800.0, 1200.0, 1400.0, 1600.0
|-
| 409.6 || 204.8, 819.2, 1433.6, 1638.4
|-
| 450.0 || 150.0, 300.0, 600.0, 750.0, 900.0, 1350.0, 1500.0, 1800.0
|-
| 460.8 || 768.0, 921.6, 1075.2, 1382.4, 1536.0
|-
| 480.0 || 240.0, 720.0, 840.0, 960.0, 1440.0, 1680.0, 1920.0
|-
| 491.52 || 245.76, 860.16, 983.04, 1720.32, 1966.08
|-
| 500.0 || 125.0, 250.0, 750.0, 875.0, 1000.0, 1500.0, 1750.0, 2000.0
|-
| 512.0 || 128.0, 768.0, 1536.0
|-
| 532.48 || 133.12, 266.24, 798.72, 931.84, 1064.96, 1331.2, 1863.68
|-
| 552.96 || 184.32, 368.64, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2
|-
| 599.04 || 199.68, 399.36, 798.72, 998.4, 1198.08, 1397.76, 1797.12, 1996.8
|-
| 600.0 || 150.0, 240.0, 300.0, 360.0, 450.0, 720.0, 900.0, 1000.0, 1050.0, 1500.0, 1800.0, 2000.0
|-
| 614.4 || 153.6, 307.2, 1228.8
|-
| 640.0 || 160.0, 256.0, 320.0, 800.0, 1120.0, 1280.0, 1600.0
|-
| 655.36 || 163.84, 327.68, 1146.88, 1310.72
|-
| 665.6 || 133.12, 266.24, 399.36, 798.72, 1331.2, 1996.8
|-
| 720.0 || 240.0, 360.0, 480.0, 600.0, 960.0, 1440.0, 1680.0, 1800.0, 1920.0
|-
| 737.28 || 184.32, 368.64, 552.96, 1105.92, 1290.24, 1474.56, 1843.2
|-
| 750.0 || 125.0, 150.0, 250.0, 300.0, 375.0, 450.0, 500.0, 900.0, 1000.0, 1125.0, 1500.0, 1750.0, 1875.0, 2000.0
|-
| 768.0 || 128.0, 384.0, 460.8, 512.0, 921.6, 1152.0, 1536.0
|-
| 798.72 || 133.12, 199.68, 266.24, 399.36, 532.48, 599.04, 665.6, 998.4, 1064.96, 1198.08, 1331.2, 1397.76, 1863.68, 1996.8
|-
| 800.0 || 160.0, 200.0, 320.0, 400.0, 640.0, 1200.0, 1400.0, 1600.0
|-
| 819.2 || 204.8, 409.6, 1433.6, 1638.4
|-
| 840.0 || 240.0, 480.0, 1680.0
|-
| 860.16 || 245.76, 491.52, 1720.32
|-
| 875.0 || 125.0, 250.0, 500.0, 1750.0
|-
| 896.0 || 256.0, 1792.0
|-
| 900.0 || 150.0, 300.0, 450.0, 600.0, 750.0, 1500.0, 1800.0
|-
| 921.6 || 460.8, 768.0, 1536.0
|-
| 931.84 || 133.12, 266.24, 532.48, 1863.68
|-
| 960.0 || 240.0, 480.0, 720.0, 1440.0, 1920.0
|-
| 983.04 || 245.76, 491.52, 1966.08
|-
| 998.4 || 199.68, 399.36, 599.04, 798.72, 1198.08, 1996.8
|-
| 1000.0 || 125.0, 250.0, 500.0, 600.0, 750.0, 1500.0, 2000.0
|-
| 1024.0 || 256.0, 1280.0, 2048.0
|-
| 1050.0 || 150.0, 300.0, 600.0
|-
| 1064.96 || 133.12, 266.24, 532.48, 798.72, 1331.2
|-
| 1075.2 || 460.8
|-
| 1080.0 || 360.0
|-
| 1105.92 || 184.32, 368.64, 552.96, 737.28, 1474.56, 1658.88, 1843.2
|-
| 1120.0 || 160.0, 320.0, 640.0
|-
| 1125.0 || 125.0, 375.0, 750.0, 1500.0, 1875.0
|-
| 1146.88 || 163.84, 327.68, 655.36
|-
| 1152.0 || 128.0, 384.0, 768.0, 1536.0
|-
| 1198.08 || 133.12, 199.68, 399.36, 599.04, 798.72, 998.4, 1797.12, 1996.8
|-
| 1200.0 || 200.0, 400.0, 800.0, 1600.0
|-
| 1228.8 || 153.6, 307.2, 614.4
|-
| 1280.0 || 160.0, 256.0, 320.0, 640.0, 1024.0, 1600.0
|-
| 1290.24 || 184.32, 368.64, 552.96, 737.28
|-
| 1310.72 || 163.84, 327.68, 655.36
|-
| 1331.2 || 133.12, 266.24, 399.36, 532.48, 665.6, 798.72, 1064.96, 1996.8
|-
| 1350.0 || 150.0, 450.0
|-
| 1382.4 || 460.8
|-
| 1397.76 || 199.68, 399.36, 599.04, 798.72
|-
| 1400.0 || 200.0, 400.0, 800.0
|-
| 1433.6 || 204.8, 409.6, 819.2
|-
| 1440.0 || 240.0, 480.0, 720.0, 960.0, 1920.0
|-
| 1474.56 || 163.84, 184.32, 368.64, 552.96, 737.28, 1105.92
|-
| 1500.0 || 150.0, 250.0, 300.0, 375.0, 450.0, 500.0, 600.0, 750.0, 900.0, 1000.0, 1125.0, 2000.0
|-
| 1536.0 || 384.0, 460.8, 512.0, 768.0, 921.6, 1152.0
|-
| 1600.0 || 160.0, 200.0, 320.0, 400.0, 640.0, 800.0, 1200.0, 1280.0
|-
| 1625.0 || 125.0, 250.0
|-
| 1638.4 || 204.8, 409.6, 819.2
|-
| 1650.0 || 150.0, 300.0
|-
| 1658.88 || 184.32, 368.64, 552.96, 1105.92
|-
| 1664.0 || 256.0
|-
| 1680.0 || 240.0, 480.0, 720.0, 840.0
|-
| 1720.32 || 245.76, 491.52, 860.16
|-
| 1730.56 || 133.12, 266.24
|-
| 1750.0 || 125.0, 250.0, 500.0, 750.0, 875.0
|-
| 1760.0 || 160.0, 320.0
|-
| 1792.0 || 256.0, 896.0
|-
| 1797.12 || 199.68, 399.36, 599.04, 1198.08
|-
| 1800.0 || 150.0, 240.0, 300.0, 360.0, 450.0, 600.0, 720.0, 900.0
|-
| 1802.24 || 163.84, 327.68
|-
| 1843.2 || 184.32, 368.64, 552.96, 737.28, 1105.92
|-
| 1863.68 || 133.12, 266.24, 532.48, 798.72, 931.84
|-
| 1875.0 || 125.0, 250.0, 375.0, 750.0, 1125.0
|-
| 1920.0 || 240.0, 480.0, 720.0, 960.0, 1440.0
|-
| 1950.0 || 150.0, 300.0
|-
| 1966.08 || 245.76, 491.52, 983.04
|-
| 1996.8 || 133.12, 199.68, 266.24, 399.36, 599.04, 665.6, 798.72, 998.4, 1198.08, 1331.2
|-
| 2000.0 || 125.0, 250.0, 500.0, 600.0, 750.0, 1000.0, 1500.0
|-
| 2027.52 || 184.32, 368.64
|-
| 2048.0 || 256.0, 1024.0
|}


== References and Related Documentation ==
* [https://www.ni.com/en/solutions/aerospace-defense/radar-electronic-warfare-sigint/advantages-of-direct-rf-sampling-architectures.html Advantages of Direct RF Sampling Architectures]
* [https://docs.xilinx.com/r/en-US/pg269-rf-data-converter Zynq UltraScale+ RFSoC RF Data Converter v2.6 Gen 1/2/3/DFE LogiCORE IP Product Guide (PG269)]
* [https://events.gnuradio.org/event/21/contributions/392/attachments/123/285/Lo%20and%20behold,%20no%20LO.pdf GRcon 23 - Lo and behold, no LO!]
* [https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Electrical-Characteristics Zynq UltraScale+ RFSoC Data Sheet: DC and AC Switching Characteristics (DS926)]

= Footnotes =
<references />

About Sampling Rates and Master Clock Rates for the USRP X440

2024-01-05T09:42:58Z

MartinAnderseck: Added note about phase coherence in dual rate case.

== Application Note Number and Authors ==

'''AN-055''' by Marian Koop and Martin Anderseck



= Overview =
This application note guides users through the selection process of Master Clock Rates (MCR) for the [https://kb.ettus.com/X440#X440 USRP X440]. It will highlight possible implications and side effects as well as design specific differences to other USRPs (like the X410).


= USRP X440 Configuration Considerations =
The USRP X440 is a [https://uhd.readthedocs.io/en/latest/page_fbx.html#fbx_too balun-coupled transceiver] without built-in RF signal conditioning. Compared to other RF architectures this enables the USRP X440 to access the full RF bandwidth available to the ADC/DAC, but also requires additional frequency planning. To achieve this, the USRP X440 utilizes its ADC/DAC in direct sampling mode and is susceptible to various effects that may distort the signal of interest. These can be separated into distortions from both signal processing and from the ADC/DAC design.


== Relationship between RF-ADC/DAC Converter Rate, USRP Master Clock Rate (MCR), Data IQ rate ==
Except for the 200 MHz variant, the default USRP X440 FPGA images do not contain a configurable DDC<ref>Digital Down Conversion</ref>/DUC<ref>Digital Up Conversion</ref> block. This means that the IQ sample rate (FIQ) is the same as the Master Clock Rate (MCR) that goes into the RFNoC Radio block. However, unlike most other USRPs the USRP X440 supports a highly variable MCR. The RF Data Converter sampling rate (FS) is chosen by UHD based on the MCR and the available resampling factors of 2, 4, or 8, and defaults to the highest achievable values with these factors. This can be overridden if the desired MCR can be achieved with multiple converter rates (see device argument [https://uhd.readthedocs.io/en/latest/page_usrp_x4xx.html#x4xx_usage_args converter_rate]). The inverse calculation - divide the converter rate by 8, 4 or 2 - has to be done to derive the master clock rate if a specific converter rate shall be used. Figure 1 depicts the simplified signal path block diagram for the USRP X440.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 1. Simplified USRP X440 Signal Path
|-
| style="border-style: none;" | [[File:ANxxx-X440_signal_path.jpg|450px|center]]
|}


== Aliases and Nyquist Zones ==
By itself the USRP X440 can sample input signals at frequencies above the Nyquist frequency<ref>[https://en.wikipedia.org/wiki/Nyquist_frequency Nyquist frequency]</ref>, which is half of the ADC converter sampling rate (FS). However, this method introduces aliasing effects, which cause unwanted signals to appear as mirror images around multiples of the Nyquist frequency (FS/2) in the output spectrum. The first Nyquist zone (N1) is the frequency range from 0 to FS/2, and the second Nyquist zone (N2) goes from FS/2 to FS. Other Nyquist zones are numbered in ascending order, each spanning FS/2. The digital passband in each Nyquist zone can be calculated as 0.4 * FS (see also <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/RF-ADC-Decimation-Filters-Gen-1/Gen-2 Xilinx RF-ADC Decimation Filters (Gen-1)]</ref>). The following figure depicts the Nyquist zones for the minimum and maximum RF-ADC converter rates supported by the USRP X440. Note that the illustrations do not show the effects of external, analog filters on the achievable passband within a Nyquist zone. A typical expectation is, that the unusable frequency range around each Nyquist zone boundary (also often referred to as a guard band) increases with ascending Nyquist zone order and results in decreasing, lopsided achievable passbands.
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 2. Nyquist Zones
|-
| style="border-style: none;" | [[File:ANxxx-X440_nyquist_zones.jpg|450px|center]]
|}

Knowledge of signal aliases can both be exploited and create uncertainties. Applications could utilize intentional under sampling (also referred as "bandpass sampling") to receive signals at greater than FS/2. The same effect may on the other hand lead to garbled or distorted signal detection if the signal of interest spans multiple Nyquist zones or interferer signals are aliased into the observed spectrum. Both effects are depicted in figure 3.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 3. Aliases - Wanted and unwanted
|-
| style="border-style: none;" | [[File:ANxxx-wanted_and_unwanted_aliases.jpg|450px|center]]
|}

Applications should therefore prefer converter rates that can contain the desired signal spectrum in a single Nyquist zone, or split the signal spectrum among multiple channels and devices. While the USRP X440 does not limit the utilized Nyquist zone, performance degrades in higher orders zones and application should focus on operating in Nyquist zones 1 and 2 (For RX, zone 3 is possible, but zones 4 and higher result into significant performance degradation).


== RF-ADC Spurs to consider and how to predict them ==
Another kind of distortion originates from the ADC/DAC itself. The USRP X440 uses the Xilinx RFDC, which is a design that combines multiple converters to
achieve high RF-ADC rates. An RF-ADC in this design has 8 sub-ADCs that are interleaved together. The resulting offset spurs are minimized by the integrated self-calibration (see also <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/Key-CAL-Features-and-Guidance-Summary Key CAL Features and Guidance Summary]</ref>) executed by UHD but may still be detectable in the signal spectrum.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 4. RF-ADC Spurs with MCR = 500 MHz
|-
| style="border-style: none;" | [[File:ANxxx-adc_distortions.jpg|450px|center]]
|}

Even with the best calibration the RF-ADC spurs may still be detectable in the captured spectrum. Knowledge of the location of the spurs, in particular the RF-ADC offset spur may be used during frequency planning to select an MCR (and converter rate) that exclude the offset spur frequencies from the capture spectrum. RF-ADC input spurs on the other hand will be more difficult to avoid, but as rule of thumb for modulated input signals carrier frequencies that fall on an RF-ADC offset spur frequency should be avoided (because offset and input spurs would superimpose each other).

=== How to predict offset spurs ===
Any residual DC offset not corrected appears as a spur at k*FS/N, where FS is the composite converter rate of the RF-ADC, N is the number of sub-RF-ADCs interleaved together (8 for X4xx devices), and k = 0, 1, 2, … N.
For more information on expected spurs levels, refer to OIS at <ref>[https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Performance-Characteristics RF-ADC Performance Characteristics]</ref>.

=== How to predict input spurs ===
Any residual difference from gain and time skew correction results in spurious signals at +/-fin + (k/N)*FS, where FS is the converter rate of the RF-ADC, N is the number of sub-RF-ADCs (8 for X4xx devices), and fin is the frequency of the input signal.
For more information on expected spurs levels, refer to GTIS at <ref>[https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Performance-Characteristics RF-ADC Performance Characteristics]</ref>.


== RF-DAC Distortions ==
Like the RF-ADC, the RF-DAC is also not an ideal circuitry and suffers from zero-order hold reconstruction. To counter this undesired attenuation in all but the first Nyquist zone, the Xilinx RF-DAC offers a Mix-Mode, which improves the power response in the second Nyquist zone and is utilized by the USRP X440. This, together with an inverse sinc filter to counter residual distortion limits the practical use of the RF-DAC to the first two Nyquist zones. For more information on the RF-DAC mix-mode and inverse sinc filter characteristics, refer to <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/RF-DAC-Nyquist-Zone-Operation RF-DAC Nyquist Zone Operation]</ref>.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 5 <ref>[https://docs.xilinx.com/viewer/attachment/wIPPkVrh~0jtjy6aqWeihQ/q5kXcl5Z7lFon2v535oW0w Xilinx: Ideal DAC Output Response, Normalised to Fsample]</ref>. RF-DAC Mix-Mode and normal, ideal roll-off sinc response.
|-
| style="border-style: none;" | [[File:ANxxx-dac_roll-off_sinc_response.png|350px|center]]
|}




== Dual Rate ==
Unlike previous USRPs, the USRP X440 supports the operation at two different master clock rates simultaneously. All channels on the first daughterboard will run on the first master clock rate / sampling rate and all channels on the second daughterboard will run on the second configured master clock rate / sampling rate. The main motivation for having two different master clock rates is the direct sampling architecture of the USRP X440 without signal conditioning and filtering. While [[#dsp-distortions|Aliases and Nyquist Zones]] describes the challenges of that, with dual rate this feature can be used to capture an RF spectrum that exceeds the bandwidth abilities of the single rate operation. Using a second rate, one can close the Nyquist gap of the other and monitor a wider spectrum for further processing.
As the clocks of both radios are derived from a common clocking chip, not all combinations are possible. Refer to [[#X440-supported-dual-rates|X440 Supported Dual Rates]] for possible RF Data Converter sampling rate combinations. The section about the [[#converter_rate-mcr-iq_rate|Relationship between RFADC/DAC Converter Rate, USRP Master Clock Rate (MCR) and Data IQ rate]] explains how to derive valid master clock rates from the RF Data converter sampling rates.

Note: When using different MCRs for both daughterboards, the device will skip the multi-tile synchronization. That means that the phase relationship between channels may not be preserved over retunes and reboots for channels of the same daughterboard and no defined phase relationship will be preserved between channels of different daughtherboards.



= Use cases =
== Scan Spectrum within single Nyquist zone ==
=== Spectrum Capture between 1.7 and 1.9 GHz. ===
* Min Bandwidth: 200 MHz
* Minimum IQ Rate: 250 MSps
==== Option 1: MCR = 250 MHz, RF-ADC converter rate = 2 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_250e6_2000e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest is very close to a Nyquist zone boundary.

==== Option 2: MCR = 300 MHz, RF-ADC converter rate = 2.4 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_300e6_2400e6.jpg|450px|center]]
|}
This option is better, the spectrum of interest is well within a Nyquist zone. Within the bandwidth of interest falls one of the ADC offset spurs. If the input signal is relatively strong, the impact from this small spur is negligible. If on the other hand the input signal strength is on the low end (for the X440), then maybe a different MCR should be considered.

==== Option 3: MCR = 320 MHz, RF-ADC converter rate = 2.56 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_320e6_2560e6.jpg|450px|center]]
|}
This option avoids a potential impact of an ADC offset spur in the observed spectrum. The only drawback to option 2 is the slightly higher data rate during host post-processing.

=== Spectrum Capture between 500 MHz and 1.5 GHz. ===
The USRP X440 ships with multiple [https://uhd.readthedocs.io/en/latest/page_usrp_x4xx.html#x4xx_updating_fpga_types FPGA image flavors]. These either support 400 MHz or 1600 MHz RF bandwidth per channel. To address this use case, users have the option of using a bit file with 1600 MHz RF bandwidth to capture a contiguous spectrum, or use a 400 MHz bit file and create a stitched spectrum during host side post-processing.
==== Using 1600 MHz image ====
* Min Bandwidth: 1000 MHz
* Minimum IQ Rate: 1250 MSps
===== Option 1: MCR = 1280 MHz, RF-ADC converter rate = 2.56 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1250e6_2560e6.jpg|450px|center]]
|}
Bad option, because desired spectrum spans multiple Nyquist zones.

===== Option 2: MCR = 1600 MHz, RF-ADC converter rate = 3.2 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1600e6_3200e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest is very close to a Nyquist zone boundary.

===== Option 3: MCR = 1689.6 MHz, RF-ADC converter rate = 3.3792 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1689e6_3379e6.jpg|450px|center]]
|}
This option would work. If the input signal strength is low, using an even higher MCR would reduce the number of potential ADC offset spurs. This needs to be traded off against a higher data rate during host post-processing.

==== Using 400 MHz image ====
Due to the smaller bandwidth addressing the use case will require the use of multiple channels. The captured spectra than needs to be stitched (combined) together.
* Max Bandwidth: 400 MHz
===== Option 1: MCR 400 MHz, RF-ADC converter rate = 3.2 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_400e6_3200e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest boundary is very close to a Nyquist zone boundary.

===== Option 2: MCR 450 MHz, RF-ADC converter rate = 3.6 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_450e6_3600e6.jpg|450px|center]]
|}
This option would work. Since the spectrum of interest is larger than the per channel bandwidth the captured spectrum may contain potential ADC offset spurs. For the spectrum of interest the 3 channels would nicely use tune frequencies (680, 1000, 1320 MHz) that do not match ADC offset spur frequencies.

===== Option 3: MCR 512 MHz, RF-ADC converter rate = 4.096 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_512e6_4096e6.jpg|450px|center]]
|}
This option would work as well. Like in option 2, the spectrum of interest may contain one potential ADC offset spur (compared to 2 in option 2). The drawback to option 2 is of course again the higher data rate during host post-processing that may be offset by only having to stitch less spectra (2 vs 3) together.



== Scan Spectrum with dual master clock rate ==
=== Spectrum capture between 1.0 and 2.4 GHz (L-band) ===
* Combination of two RF-ADC converter rates: 4096 MHz and 2560 MHz
* Derived master clock rates: 1024 MHz (resampling factor 4) and 1280 MHz (resampling factor 2). The resampling factors are chosen to produce master clock rates which allow capturing a sufficient bandwidth to not have any gaps.
* Center frequencies: 1.23 GHz and 2.0 GHz respectively
* 1600 MHz FPGA image required due to the bandwidth requirements
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:AN055-L-band-dual-rate.jpg|800px|center]]
|}
In the picture you can see a light-green band between 1.0 GHz and 2.4 GHz which can be covered using two different rates: Radio0 operates at MCR=1024 MHz in its first Nyquist zone and radio1 operates at 1280 MHz in its second Nyquist zone. The coverage is shown as light-blue boxes in both frequency charts. Starting with UHD 4.6, the X440_L_band_capture.py example demonstrates this use case and by default uses center frequencies of 0.9 GHz and 2 GHz respectively. These were choosen to conveniently display the two individual spectra next to each other in a continuous spectra view without any overlap. Practical applications on the other hand need to take into account that the well usable bandwidth of each channel is only about 0.8 * MCR. For the chosen MCRs this means that the first radio has a usable bandwidth of 819.2 MHz and the second one of 1024 MHz. Taking into account that a typical RF passband in the first Nyquist zone has a passband of up to 0.4 * FS and the need for some overlap of the two spectra, the center frequency of radio0 should be set to 1.230 GHz (usable bandwidth spans from ~820 MHz to ~1640 MHz). Radio1 will be used in its second Nyquist zone, so the center frequency should be 2.0 GHz (usable bandwidth from ~1.5 GHz to ~2.5 GHz).


= Appendix =

== X440 Supported Master Clock Rates (MCR) ==
Note: The selected FPGA bitfile may further limit the maximum supported master clock rate.
{| class="wikitable" style="text-align: center; margin:auto"
|-
! MCR (MHz) !! RFDC Converter Rate (GHz)
|-
| 125.0 || 1.0
|-
| 128.0 || 1.024
|-
| 133.12 || 1.06496
|-
| 150.0 || 1.2
|-
| 153.6 || 1.2288
|-
| 160.0 || 1.28
|-
| 163.84 || 1.31072
|-
| 184.32 || 1.47456
|-
| 199.68 || 1.59744
|-
| 200.0 || 1.6
|-
| 204.8 || 1.6384
|-
| 240.0 || 1.92
|-
| 245.76 || 1.96608
|-
| 250.0 || 2.0, 1.0
|-
| 256.0 || 2.048, 1.024
|-
| 266.24 || 2.12992, 1.06496
|-
| 300.0 || 2.4, 1.2
|-
| 307.2 || 2.4576, 1.2288
|-
| 320.0 || 2.56, 1.28
|-
| 327.68 || 2.62144, 1.31072
|-
| 360.0 || 2.88, 1.44
|-
| 368.64 || 1.47456, 2.94912
|-
| 375.0 || 3.0, 1.5
|-
| 384.0 || 1.536, 3.072
|-
| 399.36 || 3.19488, 1.59744
|-
| 400.0 || 3.2, 1.6
|-
| 409.6 || 3.2768, 1.6384
|-
| 450.0 || 1.8, 3.6
|-
| 460.8 || 1.8432, 3.6864
|-
| 480.0 || 3.84, 1.92
|-
| 491.52 || 3.93216, 1.96608
|-
| 500.0 || 4.0, 2.0, 1.0
|-
| 512.0 || 1.024, 2.048, 4.096
|-
| 532.48 || 1.06496, 2.12992
|-
| 552.96 || 2.21184, 1.10592
|-
| 599.04 || 1.19808, 2.39616
|-
| 600.0 || 1.2, 2.4
|-
| 614.4 || 1.2288, 2.4576
|-
| 625.0 || 1.25, 2.5
|-
| 640.0 || 2.56, 1.28
|-
| 655.36 || 1.31072, 2.62144
|-
| 665.6 || 1.3312, 2.6624
|-
| 720.0 || 1.44, 2.88
|-
| 737.28 || 1.47456, 2.94912
|-
| 750.0 || 1.5, 3.0
|-
| 768.0 || 1.536, 3.072
|-
| 798.72 || 3.19488, 1.59744
|-
| 800.0 || 1.6, 3.2
|-
| 819.2 || 3.2768, 1.6384
|-
| 840.0 || 1.68, 3.36
|-
| 860.16 || 3.44064, 1.72032
|-
| 875.0 || 3.5, 1.75
|-
| 896.0 || 3.584, 1.792
|-
| 900.0 || 1.8, 3.6
|-
| 921.6 || 1.8432, 3.6864
|-
| 931.84 || 1.86368, 3.72736
|-
| 960.0 || 3.84, 1.92
|-
| 983.04 || 1.96608, 3.93216
|-
| 998.4 || 3.9936, 1.9968
|-
| 1000.0 || 4.0, 2.0
|-
| 1024.0 || 4.096, 2.048
|-
| 1050.0 || 2.1
|-
| 1064.96 || 2.12992
|-
| 1075.2 || 2.1504
|-
| 1080.0 || 2.16
|-
| 1105.92 || 2.21184
|-
| 1120.0 || 2.24
|-
| 1125.0 || 2.25
|-
| 1146.88 || 2.29376
|-
| 1152.0 || 2.304
|-
| 1198.08 || 2.39616
|-
| 1200.0 || 2.4
|-
| 1228.8 || 2.4576
|-
| 1280.0 || 2.56
|-
| 1290.24 || 2.58048
|-
| 1310.72 || 2.62144
|-
| 1331.2 || 2.6624
|-
| 1350.0 || 2.7
|-
| 1382.4 || 2.7648
|-
| 1397.76 || 2.79552
|-
| 1400.0 || 2.8
|-
| 1433.6 || 2.8672
|-
| 1440.0 || 2.88
|-
| 1474.56 || 2.94912
|-
| 1500.0 || 3.0
|-
| 1536.0 || 3.072
|-
| 1600.0 || 3.2
|-
| 1625.0 || 3.25
|-
| 1638.4 || 3.2768
|-
| 1650.0 || 3.3
|-
| 1658.88 || 3.31776
|-
| 1664.0 || 3.328
|-
| 1680.0 || 3.36
|-
| 1689.6 || 3.3792
|-
| 1720.32 || 3.44064
|-
| 1730.56 || 3.46112
|-
| 1750.0 || 3.5
|-
| 1760.0 || 3.52
|-
| 1792.0 || 3.584
|-
| 1797.12 || 3.59424
|-
| 1800.0 || 3.6
|-
| 1802.24 || 3.60448
|-
| 1843.2 || 3.6864
|-
| 1863.68 || 3.72736
|-
| 1875.0 || 3.75
|-
| 1920.0 || 3.84
|-
| 1950.0 || 3.9
|-
| 1966.08 || 3.93216
|-
| 1996.8 || 3.9936
|-
| 2000.0 || 4.0
|-
| 2027.52 || 4.05504
|-
| 2048.0 || 4.096
|}


== X440 Supported Master Clock Rate combinations (Dual Rate) ==
Important: For the best RF performance it is required to configure the master clock rate that is connected to the higher RF-ADC/DAC converter rate on the first radio and the MCR connected to the lower converter rate second. Not all master clock rate combinations listed in this table will comply to this requirement by themselves. Specifying the converter_rate argument or swapping the master clock rates will help resolving issues. The selected FPGA bitfile may further limit the maximum supported master clock rate.
{| class="wikitable" style="text-align: center; margin:auto"
|-
| MCR0 (MHz) || MCR1 (MHz)
|-
| 125.0 || 250.0, 375.0, 500.0, 750.0, 875.0, 1000.0, 1125.0, 1625.0, 1750.0, 1875.0, 2000.0
|-
| 128.0 || 384.0, 512.0, 768.0, 1152.0
|-
| 133.12 || 266.24, 399.36, 532.48, 665.6, 798.72, 931.84, 1064.96, 1198.08, 1331.2, 1730.56, 1863.68, 1996.8
|-
| 150.0 || 300.0, 450.0, 600.0, 750.0, 900.0, 1050.0, 1350.0, 1500.0, 1650.0, 1800.0, 1950.0
|-
| 153.6 || 307.2, 614.4, 1228.8
|-
| 160.0 || 320.0, 640.0, 800.0, 1120.0, 1280.0, 1600.0, 1760.0
|-
| 163.84 || 327.68, 655.36, 1146.88, 1310.72, 1474.56, 1802.24
|-
| 184.32 || 368.64, 552.96, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2, 2027.52
|-
| 199.68 || 399.36, 599.04, 798.72, 998.4, 1198.08, 1397.76, 1797.12, 1996.8
|-
| 200.0 || 400.0, 800.0, 1200.0, 1400.0, 1600.0
|-
| 204.8 || 409.6, 819.2, 1433.6, 1638.4
|-
| 240.0 || 360.0, 480.0, 600.0, 720.0, 840.0, 960.0, 1440.0, 1680.0, 1800.0, 1920.0
|-
| 245.76 || 491.52, 860.16, 983.04, 1720.32, 1966.08
|-
| 250.0 || 125.0, 375.0, 500.0, 750.0, 875.0, 1000.0, 1500.0, 1625.0, 1750.0, 1875.0, 2000.0
|-
| 256.0 || 640.0, 896.0, 1024.0, 1280.0, 1664.0, 1792.0, 2048.0
|-
| 266.24 || 133.12, 399.36, 532.48, 665.6, 798.72, 931.84, 1064.96, 1331.2, 1730.56, 1863.68, 1996.8
|-
| 300.0 || 150.0, 450.0, 600.0, 750.0, 900.0, 1050.0, 1500.0, 1650.0, 1800.0, 1950.0
|-
| 307.2 || 153.6, 614.4, 1228.8
|-
| 320.0 || 160.0, 640.0, 800.0, 1120.0, 1280.0, 1600.0, 1760.0
|-
| 327.68 || 163.84, 655.36, 1146.88, 1310.72, 1802.24
|-
| 360.0 || 240.0, 600.0, 720.0, 1080.0, 1800.0
|-
| 368.64 || 184.32, 552.96, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2, 2027.52
|-
| 375.0 || 125.0, 250.0, 750.0, 1125.0, 1500.0, 1875.0
|-
| 384.0 || 128.0, 768.0, 1152.0, 1536.0
|-
| 399.36 || 133.12, 199.68, 266.24, 599.04, 665.6, 798.72, 998.4, 1198.08, 1331.2, 1397.76, 1797.12, 1996.8
|-
| 400.0 || 200.0, 800.0, 1200.0, 1400.0, 1600.0
|-
| 409.6 || 204.8, 819.2, 1433.6, 1638.4
|-
| 450.0 || 150.0, 300.0, 600.0, 750.0, 900.0, 1350.0, 1500.0, 1800.0
|-
| 460.8 || 768.0, 921.6, 1075.2, 1382.4, 1536.0
|-
| 480.0 || 240.0, 720.0, 840.0, 960.0, 1440.0, 1680.0, 1920.0
|-
| 491.52 || 245.76, 860.16, 983.04, 1720.32, 1966.08
|-
| 500.0 || 125.0, 250.0, 750.0, 875.0, 1000.0, 1500.0, 1750.0, 2000.0
|-
| 512.0 || 128.0, 768.0, 1536.0
|-
| 532.48 || 133.12, 266.24, 798.72, 931.84, 1064.96, 1331.2, 1863.68
|-
| 552.96 || 184.32, 368.64, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2
|-
| 599.04 || 199.68, 399.36, 798.72, 998.4, 1198.08, 1397.76, 1797.12, 1996.8
|-
| 600.0 || 150.0, 240.0, 300.0, 360.0, 450.0, 720.0, 900.0, 1000.0, 1050.0, 1500.0, 1800.0, 2000.0
|-
| 614.4 || 153.6, 307.2, 1228.8
|-
| 640.0 || 160.0, 256.0, 320.0, 800.0, 1120.0, 1280.0, 1600.0
|-
| 655.36 || 163.84, 327.68, 1146.88, 1310.72
|-
| 665.6 || 133.12, 266.24, 399.36, 798.72, 1331.2, 1996.8
|-
| 720.0 || 240.0, 360.0, 480.0, 600.0, 960.0, 1440.0, 1680.0, 1800.0, 1920.0
|-
| 737.28 || 184.32, 368.64, 552.96, 1105.92, 1290.24, 1474.56, 1843.2
|-
| 750.0 || 125.0, 150.0, 250.0, 300.0, 375.0, 450.0, 500.0, 900.0, 1000.0, 1125.0, 1500.0, 1750.0, 1875.0, 2000.0
|-
| 768.0 || 128.0, 384.0, 460.8, 512.0, 921.6, 1152.0, 1536.0
|-
| 798.72 || 133.12, 199.68, 266.24, 399.36, 532.48, 599.04, 665.6, 998.4, 1064.96, 1198.08, 1331.2, 1397.76, 1863.68, 1996.8
|-
| 800.0 || 160.0, 200.0, 320.0, 400.0, 640.0, 1200.0, 1400.0, 1600.0
|-
| 819.2 || 204.8, 409.6, 1433.6, 1638.4
|-
| 840.0 || 240.0, 480.0, 1680.0
|-
| 860.16 || 245.76, 491.52, 1720.32
|-
| 875.0 || 125.0, 250.0, 500.0, 1750.0
|-
| 896.0 || 256.0, 1792.0
|-
| 900.0 || 150.0, 300.0, 450.0, 600.0, 750.0, 1500.0, 1800.0
|-
| 921.6 || 460.8, 768.0, 1536.0
|-
| 931.84 || 133.12, 266.24, 532.48, 1863.68
|-
| 960.0 || 240.0, 480.0, 720.0, 1440.0, 1920.0
|-
| 983.04 || 245.76, 491.52, 1966.08
|-
| 998.4 || 199.68, 399.36, 599.04, 798.72, 1198.08, 1996.8
|-
| 1000.0 || 125.0, 250.0, 500.0, 600.0, 750.0, 1500.0, 2000.0
|-
| 1024.0 || 256.0, 1280.0, 2048.0
|-
| 1050.0 || 150.0, 300.0, 600.0
|-
| 1064.96 || 133.12, 266.24, 532.48, 798.72, 1331.2
|-
| 1075.2 || 460.8
|-
| 1080.0 || 360.0
|-
| 1105.92 || 184.32, 368.64, 552.96, 737.28, 1474.56, 1658.88, 1843.2
|-
| 1120.0 || 160.0, 320.0, 640.0
|-
| 1125.0 || 125.0, 375.0, 750.0, 1500.0, 1875.0
|-
| 1146.88 || 163.84, 327.68, 655.36
|-
| 1152.0 || 128.0, 384.0, 768.0, 1536.0
|-
| 1198.08 || 133.12, 199.68, 399.36, 599.04, 798.72, 998.4, 1797.12, 1996.8
|-
| 1200.0 || 200.0, 400.0, 800.0, 1600.0
|-
| 1228.8 || 153.6, 307.2, 614.4
|-
| 1280.0 || 160.0, 256.0, 320.0, 640.0, 1024.0, 1600.0
|-
| 1290.24 || 184.32, 368.64, 552.96, 737.28
|-
| 1310.72 || 163.84, 327.68, 655.36
|-
| 1331.2 || 133.12, 266.24, 399.36, 532.48, 665.6, 798.72, 1064.96, 1996.8
|-
| 1350.0 || 150.0, 450.0
|-
| 1382.4 || 460.8
|-
| 1397.76 || 199.68, 399.36, 599.04, 798.72
|-
| 1400.0 || 200.0, 400.0, 800.0
|-
| 1433.6 || 204.8, 409.6, 819.2
|-
| 1440.0 || 240.0, 480.0, 720.0, 960.0, 1920.0
|-
| 1474.56 || 163.84, 184.32, 368.64, 552.96, 737.28, 1105.92
|-
| 1500.0 || 150.0, 250.0, 300.0, 375.0, 450.0, 500.0, 600.0, 750.0, 900.0, 1000.0, 1125.0, 2000.0
|-
| 1536.0 || 384.0, 460.8, 512.0, 768.0, 921.6, 1152.0
|-
| 1600.0 || 160.0, 200.0, 320.0, 400.0, 640.0, 800.0, 1200.0, 1280.0
|-
| 1625.0 || 125.0, 250.0
|-
| 1638.4 || 204.8, 409.6, 819.2
|-
| 1650.0 || 150.0, 300.0
|-
| 1658.88 || 184.32, 368.64, 552.96, 1105.92
|-
| 1664.0 || 256.0
|-
| 1680.0 || 240.0, 480.0, 720.0, 840.0
|-
| 1720.32 || 245.76, 491.52, 860.16
|-
| 1730.56 || 133.12, 266.24
|-
| 1750.0 || 125.0, 250.0, 500.0, 750.0, 875.0
|-
| 1760.0 || 160.0, 320.0
|-
| 1792.0 || 256.0, 896.0
|-
| 1797.12 || 199.68, 399.36, 599.04, 1198.08
|-
| 1800.0 || 150.0, 240.0, 300.0, 360.0, 450.0, 600.0, 720.0, 900.0
|-
| 1802.24 || 163.84, 327.68
|-
| 1843.2 || 184.32, 368.64, 552.96, 737.28, 1105.92
|-
| 1863.68 || 133.12, 266.24, 532.48, 798.72, 931.84
|-
| 1875.0 || 125.0, 250.0, 375.0, 750.0, 1125.0
|-
| 1920.0 || 240.0, 480.0, 720.0, 960.0, 1440.0
|-
| 1950.0 || 150.0, 300.0
|-
| 1966.08 || 245.76, 491.52, 983.04
|-
| 1996.8 || 133.12, 199.68, 266.24, 399.36, 599.04, 665.6, 798.72, 998.4, 1198.08, 1331.2
|-
| 2000.0 || 125.0, 250.0, 500.0, 600.0, 750.0, 1000.0, 1500.0
|-
| 2027.52 || 184.32, 368.64
|-
| 2048.0 || 256.0, 1024.0
|}


== References and Related Documentation ==
* [https://www.ni.com/en/solutions/aerospace-defense/radar-electronic-warfare-sigint/advantages-of-direct-rf-sampling-architectures.html Advantages of Direct RF Sampling Architectures]
* [https://docs.xilinx.com/r/en-US/pg269-rf-data-converter Zynq UltraScale+ RFSoC RF Data Converter v2.6 Gen 1/2/3/DFE LogiCORE IP Product Guide (PG269)]
* [https://events.gnuradio.org/event/21/contributions/392/attachments/123/285/Lo%20and%20behold,%20no%20LO.pdf GRcon 23 - Lo and behold, no LO!]
* [https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Electrical-Characteristics Zynq UltraScale+ RFSoC Data Sheet: DC and AC Switching Characteristics (DS926)]

= Footnotes =
<references />

About Sampling Rates and Master Clock Rates for the USRP X440

2023-11-20T10:30:52Z

MartinAnderseck:

== Application Note Number and Authors ==

'''AN-055''' by Marian Koop and Martin Anderseck



= Overview =
This application note guides users through the selection process of Master Clock Rates (MCR) for the [https://kb.ettus.com/X440#X440 USRP X440]. It will highlight possible implications and side effects as well as design specific differences to other USRPs (like the X410).


= USRP X440 Configuration Considerations =
The USRP X440 is a [https://uhd.readthedocs.io/en/latest/page_fbx.html#fbx_too balun-coupled transceiver] without built-in RF signal conditioning. Compared to other RF architectures this enables the USRP X440 to access the full RF bandwidth available to the ADC/DAC, but also requires additional frequency planning. To achieve this, the USRP X440 utilizes its ADC/DAC in direct sampling mode and is susceptible to various effects that may distort the signal of interest. These can be separated into distortions from both signal processing and from the ADC/DAC design.


== Relationship between RF-ADC/DAC Converter Rate, USRP Master Clock Rate (MCR), Data IQ rate ==
Except for the 200 MHz variant, the default USRP X440 FPGA images do not contain a configurable DDC<ref>Digital Down Conversion</ref>/DUC<ref>Digital Up Conversion</ref> block. This means that the IQ sample rate (FIQ) is the same as the Master Clock Rate (MCR) that goes into the RFNoC Radio block. However, unlike most other USRPs the USRP X440 supports a highly variable MCR. The RF Data Converter sampling rate (FS) is chosen by UHD based on the MCR and the available resampling factors of 2, 4, or 8, and defaults to the highest achievable values with these factors. This can be overridden if the desired MCR can be achieved with multiple converter rates (see device argument [https://uhd.readthedocs.io/en/latest/page_usrp_x4xx.html#x4xx_usage_args converter_rate]). The inverse calculation - divide the converter rate by 8, 4 or 2 - has to be done to derive the master clock rate if a specific converter rate shall be used. Figure 1 depicts the simplified signal path block diagram for the USRP X440.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 1. Simplified USRP X440 Signal Path
|-
| style="border-style: none;" | [[File:ANxxx-X440_signal_path.jpg|450px|center]]
|}


== Aliases and Nyquist Zones ==
By itself the USRP X440 can sample input signals at frequencies above the Nyquist frequency<ref>[https://en.wikipedia.org/wiki/Nyquist_frequency Nyquist frequency]</ref>, which is half of the ADC converter sampling rate (FS). However, this method introduces aliasing effects, which cause unwanted signals to appear as mirror images around multiples of the Nyquist frequency (FS/2) in the output spectrum. The first Nyquist zone (N1) is the frequency range from 0 to FS/2, and the second Nyquist zone (N2) goes from FS/2 to FS. Other Nyquist zones are numbered in ascending order, each spanning FS/2. The digital passband in each Nyquist zone can be calculated as 0.4 * FS (see also <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/RF-ADC-Decimation-Filters-Gen-1/Gen-2 Xilinx RF-ADC Decimation Filters (Gen-1)]</ref>). The following figure depicts the Nyquist zones for the minimum and maximum RF-ADC converter rates supported by the USRP X440. Note that the illustrations do not show the effects of external, analog filters on the achievable passband within a Nyquist zone. A typical expectation is, that the unusable frequency range around each Nyquist zone boundary (also often referred to as a guard band) increases with ascending Nyquist zone order and results in decreasing, lopsided achievable passbands.
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 2. Nyquist Zones
|-
| style="border-style: none;" | [[File:ANxxx-X440_nyquist_zones.jpg|450px|center]]
|}

Knowledge of signal aliases can both be exploited and create uncertainties. Applications could utilize intentional under sampling (also referred as "bandpass sampling") to receive signals at greater than FS/2. The same effect may on the other hand lead to garbled or distorted signal detection if the signal of interest spans multiple Nyquist zones or interferer signals are aliased into the observed spectrum. Both effects are depicted in figure 3.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 3. Aliases - Wanted and unwanted
|-
| style="border-style: none;" | [[File:ANxxx-wanted_and_unwanted_aliases.jpg|450px|center]]
|}

Applications should therefore prefer converter rates that can contain the desired signal spectrum in a single Nyquist zone, or split the signal spectrum among multiple channels and devices. While the USRP X440 does not limit the utilized Nyquist zone, performance degrades in higher orders zones and application should focus on operating in Nyquist zones 1 and 2 (For RX, zone 3 is possible, but zones 4 and higher result into significant performance degradation).


== RF-ADC Spurs to consider and how to predict them ==
Another kind of distortion originates from the ADC/DAC itself. The USRP X440 uses the Xilinx RFDC, which is a design that combines multiple converters to
achieve high RF-ADC rates. An RF-ADC in this design has 8 sub-ADCs that are interleaved together. The resulting offset spurs are minimized by the integrated self-calibration (see also <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/Key-CAL-Features-and-Guidance-Summary Key CAL Features and Guidance Summary]</ref>) executed by UHD but may still be detectable in the signal spectrum.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 4. RF-ADC Spurs with MCR = 500 MHz
|-
| style="border-style: none;" | [[File:ANxxx-adc_distortions.jpg|450px|center]]
|}

Even with the best calibration the RF-ADC spurs may still be detectable in the captured spectrum. Knowledge of the location of the spurs, in particular the RF-ADC offset spur may be used during frequency planning to select an MCR (and converter rate) that exclude the offset spur frequencies from the capture spectrum. RF-ADC input spurs on the other hand will be more difficult to avoid, but as rule of thumb for modulated input signals carrier frequencies that fall on an RF-ADC offset spur frequency should be avoided (because offset and input spurs would superimpose each other).

=== How to predict offset spurs ===
Any residual DC offset not corrected appears as a spur at k*FS/N, where FS is the composite converter rate of the RF-ADC, N is the number of sub-RF-ADCs interleaved together (8 for X4xx devices), and k = 0, 1, 2, … N.
For more information on expected spurs levels, refer to OIS at <ref>[https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Performance-Characteristics RF-ADC Performance Characteristics]</ref>.

=== How to predict input spurs ===
Any residual difference from gain and time skew correction results in spurious signals at +/-fin + (k/N)*FS, where FS is the converter rate of the RF-ADC, N is the number of sub-RF-ADCs (8 for X4xx devices), and fin is the frequency of the input signal.
For more information on expected spurs levels, refer to GTIS at <ref>[https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Performance-Characteristics RF-ADC Performance Characteristics]</ref>.


== RF-DAC Distortions ==
Like the RF-ADC, the RF-DAC is also not an ideal circuitry and suffers from zero-order hold reconstruction. To counter this undesired attenuation in all but the first Nyquist zone, the Xilinx RF-DAC offers a Mix-Mode, which improves the power response in the second Nyquist zone and is utilized by the USRP X440. This, together with an inverse sinc filter to counter residual distortion limits the practical use of the RF-DAC to the first two Nyquist zones. For more information on the RF-DAC mix-mode and inverse sinc filter characteristics, refer to <ref>[https://docs.xilinx.com/r/en-US/pg269-rf-data-converter/RF-DAC-Nyquist-Zone-Operation RF-DAC Nyquist Zone Operation]</ref>.

{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|+ Figure 5 <ref>[https://docs.xilinx.com/viewer/attachment/wIPPkVrh~0jtjy6aqWeihQ/q5kXcl5Z7lFon2v535oW0w Xilinx: Ideal DAC Output Response, Normalised to Fsample]</ref>. RF-DAC Mix-Mode and normal, ideal roll-off sinc response.
|-
| style="border-style: none;" | [[File:ANxxx-dac_roll-off_sinc_response.png|350px|center]]
|}




== Dual Rate ==
Unlike previous USRPs, the USRP X440 supports the operation at two different master clock rates simultaneously. All channels on the first daughterboard will run on the first master clock rate / sampling rate and all channels on the second daughterboard will run on the second configured master clock rate / sampling rate. The main motivation for having two different master clock rates is the direct sampling architecture of the USRP X440 without signal conditioning and filtering. While [[#dsp-distortions|Aliases and Nyquist Zones]] describes the challenges of that, with dual rate this feature can be used to capture an RF spectrum that exceeds the bandwidth abilities of the single rate operation. Using a second rate, one can close the Nyquist gap of the other and monitor a wider spectrum for further processing.
As the clocks of both radios are derived from a common clocking chip, not all combinations are possible. Refer to [[#X440-supported-dual-rates|X440 Supported Dual Rates]] for possible RF Data Converter sampling rate combinations. The section about the [[#converter_rate-mcr-iq_rate|Relationship between RFADC/DAC Converter Rate, USRP Master Clock Rate (MCR) and Data IQ rate]] explains how to derive valid master clock rates from the RF Data converter sampling rates.


= Use cases =
== Scan Spectrum within single Nyquist zone ==
=== Spectrum Capture between 1.7 and 1.9 GHz. ===
* Min Bandwidth: 200 MHz
* Minimum IQ Rate: 250 MSps
==== Option 1: MCR = 250 MHz, RF-ADC converter rate = 2 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_250e6_2000e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest is very close to a Nyquist zone boundary.

==== Option 2: MCR = 300 MHz, RF-ADC converter rate = 2.4 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_300e6_2400e6.jpg|450px|center]]
|}
This option is better, the spectrum of interest is well within a Nyquist zone. Within the bandwidth of interest falls one of the ADC offset spurs. If the input signal is relatively strong, the impact from this small spur is negligible. If on the other hand the input signal strength is on the low end (for the X440), then maybe a different MCR should be considered.

==== Option 3: MCR = 320 MHz, RF-ADC converter rate = 2.56 GHz ====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-1700-1800_320e6_2560e6.jpg|450px|center]]
|}
This option avoids a potential impact of an ADC offset spur in the observed spectrum. The only drawback to option 2 is the slightly higher data rate during host post-processing.

=== Spectrum Capture between 500 MHz and 1.5 GHz. ===
The USRP X440 ships with multiple [https://uhd.readthedocs.io/en/latest/page_usrp_x4xx.html#x4xx_updating_fpga_types FPGA image flavors]. These either support 400 MHz or 1600 MHz RF bandwidth per channel. To address this use case, users have the option of using a bit file with 1600 MHz RF bandwidth to capture a contiguous spectrum, or use a 400 MHz bit file and create a stitched spectrum during host side post-processing.
==== Using 1600 MHz image ====
* Min Bandwidth: 1000 MHz
* Minimum IQ Rate: 1250 MSps
===== Option 1: MCR = 1280 MHz, RF-ADC converter rate = 2.56 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1250e6_2560e6.jpg|450px|center]]
|}
Bad option, because desired spectrum spans multiple Nyquist zones.

===== Option 2: MCR = 1600 MHz, RF-ADC converter rate = 3.2 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1600e6_3200e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest is very close to a Nyquist zone boundary.

===== Option 3: MCR = 1689.6 MHz, RF-ADC converter rate = 3.3792 GHz =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_1689e6_3379e6.jpg|450px|center]]
|}
This option would work. If the input signal strength is low, using an even higher MCR would reduce the number of potential ADC offset spurs. This needs to be traded off against a higher data rate during host post-processing.

==== Using 400 MHz image ====
Due to the smaller bandwidth addressing the use case will require the use of multiple channels. The captured spectra than needs to be stitched (combined) together.
* Max Bandwidth: 400 MHz
===== Option 1: MCR 400 MHz, RF-ADC converter rate = 3.2 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_400e6_3200e6.jpg|450px|center]]
|}
This is not the best option because our spectrum of interest boundary is very close to a Nyquist zone boundary.

===== Option 2: MCR 450 MHz, RF-ADC converter rate = 3.6 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_450e6_3600e6.jpg|450px|center]]
|}
This option would work. Since the spectrum of interest is larger than the per channel bandwidth the captured spectrum may contain potential ADC offset spurs. For the spectrum of interest the 3 channels would nicely use tune frequencies (680, 1000, 1320 MHz) that do not match ADC offset spur frequencies.

===== Option 3: MCR 512 MHz, RF-ADC converter rate = 4.096 GHz, 3 channels =====
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:ANxxx-500-1500_512e6_4096e6.jpg|450px|center]]
|}
This option would work as well. Like in option 2, the spectrum of interest may contain one potential ADC offset spur (compared to 2 in option 2). The drawback to option 2 is of course again the higher data rate during host post-processing that may be offset by only having to stitch less spectra (2 vs 3) together.



== Scan Spectrum with dual master clock rate ==
=== Spectrum capture between 1.0 and 2.4 GHz (L-band) ===
* Combination of two RF-ADC converter rates: 4096 MHz and 2560 MHz
* Derived master clock rates: 1024 MHz (resampling factor 4) and 1280 MHz (resampling factor 2). The resampling factors are chosen to produce master clock rates which allow capturing a sufficient bandwidth to not have any gaps.
* Center frequencies: 1.23 GHz and 2.0 GHz respectively
* 1600 MHz FPGA image required due to the bandwidth requirements
{| class="wikitable" style="text-align: center; border-style: none; background-color:#ffffff;"
|-
| style="border-style: none;" | [[File:AN055-L-band-dual-rate.jpg|800px|center]]
|}
In the picture you can see a light-green band between 1.0 GHz and 2.4 GHz which can be covered using two different rates: Radio0 operates at MCR=1024 MHz in its first Nyquist zone and radio1 operates at 1280 MHz in its second Nyquist zone. The coverage is shown as light-blue boxes in both frequency charts. Starting with UHD 4.6, the X440_L_band_capture.py example demonstrates this use case and by default uses center frequencies of 0.9 GHz and 2 GHz respectively. These were choosen to conveniently display the two individual spectra next to each other in a continuous spectra view without any overlap. Practical applications on the other hand need to take into account that the well usable bandwidth of each channel is only about 0.8 * MCR. For the chosen MCRs this means that the first radio has a usable bandwidth of 819.2 MHz and the second one of 1024 MHz. Taking into account that a typical RF passband in the first Nyquist zone has a passband of up to 0.4 * FS and the need for some overlap of the two spectra, the center frequency of radio0 should be set to 1.230 GHz (usable bandwidth spans from ~820 MHz to ~1640 MHz). Radio1 will be used in its second Nyquist zone, so the center frequency should be 2.0 GHz (usable bandwidth from ~1.5 GHz to ~2.5 GHz).


= Appendix =

== X440 Supported Master Clock Rates (MCR) ==
Note: The selected FPGA bitfile may further limit the maximum supported master clock rate.
{| class="wikitable" style="text-align: center; margin:auto"
|-
! MCR (MHz) !! RFDC Converter Rate (GHz)
|-
| 125.0 || 1.0
|-
| 128.0 || 1.024
|-
| 133.12 || 1.06496
|-
| 150.0 || 1.2
|-
| 153.6 || 1.2288
|-
| 160.0 || 1.28
|-
| 163.84 || 1.31072
|-
| 184.32 || 1.47456
|-
| 199.68 || 1.59744
|-
| 200.0 || 1.6
|-
| 204.8 || 1.6384
|-
| 240.0 || 1.92
|-
| 245.76 || 1.96608
|-
| 250.0 || 2.0, 1.0
|-
| 256.0 || 2.048, 1.024
|-
| 266.24 || 2.12992, 1.06496
|-
| 300.0 || 2.4, 1.2
|-
| 307.2 || 2.4576, 1.2288
|-
| 320.0 || 2.56, 1.28
|-
| 327.68 || 2.62144, 1.31072
|-
| 360.0 || 2.88, 1.44
|-
| 368.64 || 1.47456, 2.94912
|-
| 375.0 || 3.0, 1.5
|-
| 384.0 || 1.536, 3.072
|-
| 399.36 || 3.19488, 1.59744
|-
| 400.0 || 3.2, 1.6
|-
| 409.6 || 3.2768, 1.6384
|-
| 450.0 || 1.8, 3.6
|-
| 460.8 || 1.8432, 3.6864
|-
| 480.0 || 3.84, 1.92
|-
| 491.52 || 3.93216, 1.96608
|-
| 500.0 || 4.0, 2.0, 1.0
|-
| 512.0 || 1.024, 2.048, 4.096
|-
| 532.48 || 1.06496, 2.12992
|-
| 552.96 || 2.21184, 1.10592
|-
| 599.04 || 1.19808, 2.39616
|-
| 600.0 || 1.2, 2.4
|-
| 614.4 || 1.2288, 2.4576
|-
| 625.0 || 1.25, 2.5
|-
| 640.0 || 2.56, 1.28
|-
| 655.36 || 1.31072, 2.62144
|-
| 665.6 || 1.3312, 2.6624
|-
| 720.0 || 1.44, 2.88
|-
| 737.28 || 1.47456, 2.94912
|-
| 750.0 || 1.5, 3.0
|-
| 768.0 || 1.536, 3.072
|-
| 798.72 || 3.19488, 1.59744
|-
| 800.0 || 1.6, 3.2
|-
| 819.2 || 3.2768, 1.6384
|-
| 840.0 || 1.68, 3.36
|-
| 860.16 || 3.44064, 1.72032
|-
| 875.0 || 3.5, 1.75
|-
| 896.0 || 3.584, 1.792
|-
| 900.0 || 1.8, 3.6
|-
| 921.6 || 1.8432, 3.6864
|-
| 931.84 || 1.86368, 3.72736
|-
| 960.0 || 3.84, 1.92
|-
| 983.04 || 1.96608, 3.93216
|-
| 998.4 || 3.9936, 1.9968
|-
| 1000.0 || 4.0, 2.0
|-
| 1024.0 || 4.096, 2.048
|-
| 1050.0 || 2.1
|-
| 1064.96 || 2.12992
|-
| 1075.2 || 2.1504
|-
| 1080.0 || 2.16
|-
| 1105.92 || 2.21184
|-
| 1120.0 || 2.24
|-
| 1125.0 || 2.25
|-
| 1146.88 || 2.29376
|-
| 1152.0 || 2.304
|-
| 1198.08 || 2.39616
|-
| 1200.0 || 2.4
|-
| 1228.8 || 2.4576
|-
| 1280.0 || 2.56
|-
| 1290.24 || 2.58048
|-
| 1310.72 || 2.62144
|-
| 1331.2 || 2.6624
|-
| 1350.0 || 2.7
|-
| 1382.4 || 2.7648
|-
| 1397.76 || 2.79552
|-
| 1400.0 || 2.8
|-
| 1433.6 || 2.8672
|-
| 1440.0 || 2.88
|-
| 1474.56 || 2.94912
|-
| 1500.0 || 3.0
|-
| 1536.0 || 3.072
|-
| 1600.0 || 3.2
|-
| 1625.0 || 3.25
|-
| 1638.4 || 3.2768
|-
| 1650.0 || 3.3
|-
| 1658.88 || 3.31776
|-
| 1664.0 || 3.328
|-
| 1680.0 || 3.36
|-
| 1689.6 || 3.3792
|-
| 1720.32 || 3.44064
|-
| 1730.56 || 3.46112
|-
| 1750.0 || 3.5
|-
| 1760.0 || 3.52
|-
| 1792.0 || 3.584
|-
| 1797.12 || 3.59424
|-
| 1800.0 || 3.6
|-
| 1802.24 || 3.60448
|-
| 1843.2 || 3.6864
|-
| 1863.68 || 3.72736
|-
| 1875.0 || 3.75
|-
| 1920.0 || 3.84
|-
| 1950.0 || 3.9
|-
| 1966.08 || 3.93216
|-
| 1996.8 || 3.9936
|-
| 2000.0 || 4.0
|-
| 2027.52 || 4.05504
|-
| 2048.0 || 4.096
|}


== X440 Supported Master Clock Rate combinations (Dual Rate) ==
Important: For the best RF performance it is required to configure the master clock rate that is connected to the higher RF-ADC/DAC converter rate on the first radio and the MCR connected to the lower converter rate second. Not all master clock rate combinations listed in this table will comply to this requirement by themselves. Specifying the converter_rate argument or swapping the master clock rates will help resolving issues. The selected FPGA bitfile may further limit the maximum supported master clock rate.
{| class="wikitable" style="text-align: center; margin:auto"
|-
| MCR0 (MHz) || MCR1 (MHz)
|-
| 125.0 || 250.0, 375.0, 500.0, 750.0, 875.0, 1000.0, 1125.0, 1625.0, 1750.0, 1875.0, 2000.0
|-
| 128.0 || 384.0, 512.0, 768.0, 1152.0
|-
| 133.12 || 266.24, 399.36, 532.48, 665.6, 798.72, 931.84, 1064.96, 1198.08, 1331.2, 1730.56, 1863.68, 1996.8
|-
| 150.0 || 300.0, 450.0, 600.0, 750.0, 900.0, 1050.0, 1350.0, 1500.0, 1650.0, 1800.0, 1950.0
|-
| 153.6 || 307.2, 614.4, 1228.8
|-
| 160.0 || 320.0, 640.0, 800.0, 1120.0, 1280.0, 1600.0, 1760.0
|-
| 163.84 || 327.68, 655.36, 1146.88, 1310.72, 1474.56, 1802.24
|-
| 184.32 || 368.64, 552.96, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2, 2027.52
|-
| 199.68 || 399.36, 599.04, 798.72, 998.4, 1198.08, 1397.76, 1797.12, 1996.8
|-
| 200.0 || 400.0, 800.0, 1200.0, 1400.0, 1600.0
|-
| 204.8 || 409.6, 819.2, 1433.6, 1638.4
|-
| 240.0 || 360.0, 480.0, 600.0, 720.0, 840.0, 960.0, 1440.0, 1680.0, 1800.0, 1920.0
|-
| 245.76 || 491.52, 860.16, 983.04, 1720.32, 1966.08
|-
| 250.0 || 125.0, 375.0, 500.0, 750.0, 875.0, 1000.0, 1500.0, 1625.0, 1750.0, 1875.0, 2000.0
|-
| 256.0 || 640.0, 896.0, 1024.0, 1280.0, 1664.0, 1792.0, 2048.0
|-
| 266.24 || 133.12, 399.36, 532.48, 665.6, 798.72, 931.84, 1064.96, 1331.2, 1730.56, 1863.68, 1996.8
|-
| 300.0 || 150.0, 450.0, 600.0, 750.0, 900.0, 1050.0, 1500.0, 1650.0, 1800.0, 1950.0
|-
| 307.2 || 153.6, 614.4, 1228.8
|-
| 320.0 || 160.0, 640.0, 800.0, 1120.0, 1280.0, 1600.0, 1760.0
|-
| 327.68 || 163.84, 655.36, 1146.88, 1310.72, 1802.24
|-
| 360.0 || 240.0, 600.0, 720.0, 1080.0, 1800.0
|-
| 368.64 || 184.32, 552.96, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2, 2027.52
|-
| 375.0 || 125.0, 250.0, 750.0, 1125.0, 1500.0, 1875.0
|-
| 384.0 || 128.0, 768.0, 1152.0, 1536.0
|-
| 399.36 || 133.12, 199.68, 266.24, 599.04, 665.6, 798.72, 998.4, 1198.08, 1331.2, 1397.76, 1797.12, 1996.8
|-
| 400.0 || 200.0, 800.0, 1200.0, 1400.0, 1600.0
|-
| 409.6 || 204.8, 819.2, 1433.6, 1638.4
|-
| 450.0 || 150.0, 300.0, 600.0, 750.0, 900.0, 1350.0, 1500.0, 1800.0
|-
| 460.8 || 768.0, 921.6, 1075.2, 1382.4, 1536.0
|-
| 480.0 || 240.0, 720.0, 840.0, 960.0, 1440.0, 1680.0, 1920.0
|-
| 491.52 || 245.76, 860.16, 983.04, 1720.32, 1966.08
|-
| 500.0 || 125.0, 250.0, 750.0, 875.0, 1000.0, 1500.0, 1750.0, 2000.0
|-
| 512.0 || 128.0, 768.0, 1536.0
|-
| 532.48 || 133.12, 266.24, 798.72, 931.84, 1064.96, 1331.2, 1863.68
|-
| 552.96 || 184.32, 368.64, 737.28, 1105.92, 1290.24, 1474.56, 1658.88, 1843.2
|-
| 599.04 || 199.68, 399.36, 798.72, 998.4, 1198.08, 1397.76, 1797.12, 1996.8
|-
| 600.0 || 150.0, 240.0, 300.0, 360.0, 450.0, 720.0, 900.0, 1000.0, 1050.0, 1500.0, 1800.0, 2000.0
|-
| 614.4 || 153.6, 307.2, 1228.8
|-
| 640.0 || 160.0, 256.0, 320.0, 800.0, 1120.0, 1280.0, 1600.0
|-
| 655.36 || 163.84, 327.68, 1146.88, 1310.72
|-
| 665.6 || 133.12, 266.24, 399.36, 798.72, 1331.2, 1996.8
|-
| 720.0 || 240.0, 360.0, 480.0, 600.0, 960.0, 1440.0, 1680.0, 1800.0, 1920.0
|-
| 737.28 || 184.32, 368.64, 552.96, 1105.92, 1290.24, 1474.56, 1843.2
|-
| 750.0 || 125.0, 150.0, 250.0, 300.0, 375.0, 450.0, 500.0, 900.0, 1000.0, 1125.0, 1500.0, 1750.0, 1875.0, 2000.0
|-
| 768.0 || 128.0, 384.0, 460.8, 512.0, 921.6, 1152.0, 1536.0
|-
| 798.72 || 133.12, 199.68, 266.24, 399.36, 532.48, 599.04, 665.6, 998.4, 1064.96, 1198.08, 1331.2, 1397.76, 1863.68, 1996.8
|-
| 800.0 || 160.0, 200.0, 320.0, 400.0, 640.0, 1200.0, 1400.0, 1600.0
|-
| 819.2 || 204.8, 409.6, 1433.6, 1638.4
|-
| 840.0 || 240.0, 480.0, 1680.0
|-
| 860.16 || 245.76, 491.52, 1720.32
|-
| 875.0 || 125.0, 250.0, 500.0, 1750.0
|-
| 896.0 || 256.0, 1792.0
|-
| 900.0 || 150.0, 300.0, 450.0, 600.0, 750.0, 1500.0, 1800.0
|-
| 921.6 || 460.8, 768.0, 1536.0
|-
| 931.84 || 133.12, 266.24, 532.48, 1863.68
|-
| 960.0 || 240.0, 480.0, 720.0, 1440.0, 1920.0
|-
| 983.04 || 245.76, 491.52, 1966.08
|-
| 998.4 || 199.68, 399.36, 599.04, 798.72, 1198.08, 1996.8
|-
| 1000.0 || 125.0, 250.0, 500.0, 600.0, 750.0, 1500.0, 2000.0
|-
| 1024.0 || 256.0, 1280.0, 2048.0
|-
| 1050.0 || 150.0, 300.0, 600.0
|-
| 1064.96 || 133.12, 266.24, 532.48, 798.72, 1331.2
|-
| 1075.2 || 460.8
|-
| 1080.0 || 360.0
|-
| 1105.92 || 184.32, 368.64, 552.96, 737.28, 1474.56, 1658.88, 1843.2
|-
| 1120.0 || 160.0, 320.0, 640.0
|-
| 1125.0 || 125.0, 375.0, 750.0, 1500.0, 1875.0
|-
| 1146.88 || 163.84, 327.68, 655.36
|-
| 1152.0 || 128.0, 384.0, 768.0, 1536.0
|-
| 1198.08 || 133.12, 199.68, 399.36, 599.04, 798.72, 998.4, 1797.12, 1996.8
|-
| 1200.0 || 200.0, 400.0, 800.0, 1600.0
|-
| 1228.8 || 153.6, 307.2, 614.4
|-
| 1280.0 || 160.0, 256.0, 320.0, 640.0, 1024.0, 1600.0
|-
| 1290.24 || 184.32, 368.64, 552.96, 737.28
|-
| 1310.72 || 163.84, 327.68, 655.36
|-
| 1331.2 || 133.12, 266.24, 399.36, 532.48, 665.6, 798.72, 1064.96, 1996.8
|-
| 1350.0 || 150.0, 450.0
|-
| 1382.4 || 460.8
|-
| 1397.76 || 199.68, 399.36, 599.04, 798.72
|-
| 1400.0 || 200.0, 400.0, 800.0
|-
| 1433.6 || 204.8, 409.6, 819.2
|-
| 1440.0 || 240.0, 480.0, 720.0, 960.0, 1920.0
|-
| 1474.56 || 163.84, 184.32, 368.64, 552.96, 737.28, 1105.92
|-
| 1500.0 || 150.0, 250.0, 300.0, 375.0, 450.0, 500.0, 600.0, 750.0, 900.0, 1000.0, 1125.0, 2000.0
|-
| 1536.0 || 384.0, 460.8, 512.0, 768.0, 921.6, 1152.0
|-
| 1600.0 || 160.0, 200.0, 320.0, 400.0, 640.0, 800.0, 1200.0, 1280.0
|-
| 1625.0 || 125.0, 250.0
|-
| 1638.4 || 204.8, 409.6, 819.2
|-
| 1650.0 || 150.0, 300.0
|-
| 1658.88 || 184.32, 368.64, 552.96, 1105.92
|-
| 1664.0 || 256.0
|-
| 1680.0 || 240.0, 480.0, 720.0, 840.0
|-
| 1720.32 || 245.76, 491.52, 860.16
|-
| 1730.56 || 133.12, 266.24
|-
| 1750.0 || 125.0, 250.0, 500.0, 750.0, 875.0
|-
| 1760.0 || 160.0, 320.0
|-
| 1792.0 || 256.0, 896.0
|-
| 1797.12 || 199.68, 399.36, 599.04, 1198.08
|-
| 1800.0 || 150.0, 240.0, 300.0, 360.0, 450.0, 600.0, 720.0, 900.0
|-
| 1802.24 || 163.84, 327.68
|-
| 1843.2 || 184.32, 368.64, 552.96, 737.28, 1105.92
|-
| 1863.68 || 133.12, 266.24, 532.48, 798.72, 931.84
|-
| 1875.0 || 125.0, 250.0, 375.0, 750.0, 1125.0
|-
| 1920.0 || 240.0, 480.0, 720.0, 960.0, 1440.0
|-
| 1950.0 || 150.0, 300.0
|-
| 1966.08 || 245.76, 491.52, 983.04
|-
| 1996.8 || 133.12, 199.68, 266.24, 399.36, 599.04, 665.6, 798.72, 998.4, 1198.08, 1331.2
|-
| 2000.0 || 125.0, 250.0, 500.0, 600.0, 750.0, 1000.0, 1500.0
|-
| 2027.52 || 184.32, 368.64
|-
| 2048.0 || 256.0, 1024.0
|}


== References and Related Documentation ==
* [https://www.ni.com/en/solutions/aerospace-defense/radar-electronic-warfare-sigint/advantages-of-direct-rf-sampling-architectures.html Advantages of Direct RF Sampling Architectures]
* [https://docs.xilinx.com/r/en-US/pg269-rf-data-converter Zynq UltraScale+ RFSoC RF Data Converter v2.6 Gen 1/2/3/DFE LogiCORE IP Product Guide (PG269)]
* [https://events.gnuradio.org/event/21/contributions/392/attachments/123/285/Lo%20and%20behold,%20no%20LO.pdf GRcon 23 - Lo and behold, no LO!]
* [https://docs.xilinx.com/r/en-US/ds926-zynq-ultrascale-plus-rfsoc/RF-ADC-Electrical-Characteristics Zynq UltraScale+ RFSoC Data Sheet: DC and AC Switching Characteristics (DS926)]

= Footnotes =
<references />

File:ANxxx-X440 signal path.jpg

2023-11-18T08:43:54Z

MartinAnderseck: MartinAnderseck uploaded a new version of File:ANxxx-X440 signal path.jpg

File:AN055-L-band-dual-rate.jpg

2023-11-16T12:25:04Z

MartinAnderseck: Graph that shows how the L-band spectrum can be captured by using two different master clock rates (and with this two ADC/DAC converter rates) on a USRP X440.

Graph that shows how the L-band spectrum can be captured by using two different master clock rates (and with this two ADC/DAC converter rates) on a USRP X440.

USRP N300/N310/N320/N321 Getting Started Guide

2022-03-14T07:12:17Z

MartinAnderseck: Updated the Mender image update procedure.

==Kit Contents==
===N300===
{|
|style="vertical-align:top"|
* USRP N300
* DC Power Supply (12V, 7A)
* 1 RJ45 – SFP+ Adapter
* 1 Gigabit Ethernet Cat-5e Cable (3m)
* USB-A to Micro USB-B Cable (1m)
* Getting Started Guide
* Ettus Research Sticker
||[[File:n300 kit.png|450px|center]]
|}
===N310===

{|
|style="vertical-align:top"|
* USRP N310
* DC Power Supply (12V, 7A)
* 1 RJ45 – SFP+ Adapter
* 1 Gigabit Ethernet Cat-5e Cable (3m)
* USB-A to Micro USB-B Cable (1m)
* Getting Started Guide
* Ettus Research Sticker
||[[File:n310 kit.png|500px|center]]
|}

===N320===

{|
|style="vertical-align:top"|
* USRP N320
* DC Power Supply (12V, 7A)
* 1 RJ45 – SFP+ Adapter
* 1 Gigabit Ethernet Cat-5e Cable (3m)
* USB-A to Micro USB-B Cable (1m)
* Getting Started Guide
* Ettus Research Sticker
|[[File:n320 kit.png|500px|center]]
|}

===N321===

{|
|style="vertical-align:top"|
* USRP N321
* DC Power Supply (12V, 7A)
* 1 RJ45 – SFP+ Adapter
* 1 Gigabit Ethernet Cat-5e Cable (3m)
* USB-A to Micro USB-B Cable (1m)
* Getting Started Guide
* Ettus Research Sticker
||[[File:n321 kit.png|500px|center]]
|}
==Verify the Contents of Your Kit==
Ensure that your kit contains all the items listed above. If any items are missing, please contact sales@ettus.com immediately.

==You Will Need==
* microSD Card Writer

* For Network Mode: A host computer with an available 1 or 10 Gigabit Ethernet interface for sample streaming. In addition to the Ethernet interface used for sampling streaming, your host computer will require a separate 1 Gigabit Ethernet interface for command and control streaming.

* For Stand-Alone Embedded Mode: A host computer with an available 1 Gigabit Ethernet port or a USB 2.0 port to remotely access the embedded Linux operating system running on ARM CPU.

==Proper Care and Handling==
All Ettus Research products are individually tested before shipment. The USRP is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP can cause the device to become non-functional. Take the following precautions to prevent damage to the unit.

* Never allow metal objects to touch the circuit board while powered.
* Always properly terminate the transmit port with an antenna or 50Ω load.
* Always handle the board with proper anti-static methods.
* Never allow the board to directly or indirectly come into contact with any voltage spikes.
* Never allow any water or condensing moisture to come into contact with the device.
* Always use caution with FPGA, firmware, or software modifications.

{|
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Never apply more than -15 dBm of power into any RF input.
|-
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |[[File:Caution.png|24px|center]]
|style="padding-left:10px; padding-right:10px; padding-bottom:10px;" |Always use at least 30dB attenuation if operating in loopback configuration
|-
|}

==Install and Setup the Software Tools on Your Host Computer==
In order to use your Universal Software Radio Peripheral (USRP™), you must have the software tools correctly installed and configured on your host computer. A step-by-step guide for doing this is available at the Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on [[Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on Linux|Linux]], [[Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on OS X|OS X]] and [[Building and Installing the USRP Open Source Toolchain (UHD and GNU Radio) on Windows|Windows]] Application Notes.

To find the latest release of UHD, see the UHD repository at https://github.com/EttusResearch/uhd.

The USRP N310 requires UHD version 3.11.0.0 or later.

The USRP N300 requires UHD version 3.12.0.0 or later.

The USRP N320/N321 requires UHD version 3.14.0.0 or later.

White Rabbit Ethernet-Based Synchronization of the N3xx USRP requires UHD version 3.12.0.0 or later. For additional details on White Rabbit Ethernet-Based Synchronization, please see the application note, [[Using Ethernet-Based Synchronization on the USRP™ N3xx Devices]].

'''When you receive a brand-new device, it is strongly recommended that you download the most recent filesystem image from the Ettus Research website and write it to the SD card that comes with the unit. It is not recommended that you use the SD card from the factory as-is. Instructions on downloading the latest filesystem image and writing it to the SD card are listed below.'''

'''Note that if you are operating the device in Network Mode, the version of UHD running on the host computer and the USRP N3xx must match.'''

==Connecting the Device==
===Interfaces Overview===
Listed below are the interfaces to connect to the USRP N3xx. Each interface has specific functionality, limitations and purpose.

'''Serial Console'''

The Serial Console provides a low level interface to the device typically used for debugging.

'''1 Gigabit RJ45 Connection'''

The 1 Gigabit RJ45 Connection interfaces with the on-board ARM CPU. When operated in "Network mode", this interface can optionally be used for UHD management traffic. Regardless of the operation mode (Network vs Embedded) this interface can be used to connect to the ARM via SSH. By default, the 1Gb RJ45 connection is configured to use a DHCP assigned IP address.

'''Dual SFP+ Connections'''

The Dual SFP+ Connections support multiple configurations for streaming high-speed, low-latency data, depending upon the FPGA image which is loaded.

'''QSFP+ Connection (N320/ N321 Only)'''

The QSFP+ Connection supports 2 x 10Gb lanes for streaming high-speed, low-latency data, while the onboard SFP0 connection is used for White Rabbit Ethernet-Based Synchronization.

===Setting up a Serial Console Connection===
It is possible to gain shell access to the device using a serial terminal emulator via the Serial Console port. Most Linux, OSX, or other Unix based operating systems have a tool called <code>screen</code> which can be used for this purpose.

If you do not have <code>screen</code> installed, it can be installed via your package manager. For Ubuntu/Debian based operating systems it can be installed with <code>apt</code> such as:

sudo apt install screen

The default Baud Rate for the Serial Console is: <code>115200</code>

The exact device node you should attach to depends on your operating system's driver and other USB devices that might already be connected. Modern Linux systems offer alternatives to simply trying device nodes; instead, the OS might have a directory of symlinks under <code>/dev/serial/by-id</code>:

$ ls /dev/serial/by-id
usb-Digilent_Digilent_USB_Device_25163511FE00-if00-port0
usb-Digilent_Digilent_USB_Device_25163511FE00-if01-port0
usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6CB5-if00-port0
usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6CB5-if01-port0

NOTE: Exact names depend on the host operating system version and may differ.

Every N3XX series device connected to USB will by default show up as four different devices. The devices labeled <code>"USB_to_UART_Bridge_Controller"</code> are the devices that offer a serial prompt. The first (with the <code>if00</code> suffix) connects to the <code>ARM CPU</code>, whereas the second connects to the <code>STM32 Microcontroller</code>.

If you have multiple N3xx Serial Consoles connected to a single host, you may have to empirically test nodes.

Connecting to the ARM CPU can be performed with the command:

$ sudo screen /dev/serial/by-id/usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6CB5-if00-port0 115200

Upon starting the USRP N3xx, boot messages will appear and rapidly update. Once the boot process successfully completes, a login prompt like the following should appear:

OpenEmbedded test ni-n3xx-313ABDA ttyPS0

ni-n3xx-313ABDA login:

Enter the username: <code>root</code>

By default, the <code>root</code> user's password is left blank. Press the <code>Enter</code> key when prompted for a password.

You should now be presented with a shell prompt similar to the following:

root@ni-n3xx-<motherboard serial #>:~#

Using the default configuration, the serial console will show all kernel log messages (which are not available when using SSH), and give access to the boot loader (U-boot prompt). This can be used to debug kernel or boot-loader issues more efficiently than when logged in via SSH.

====Connecting to the microcontroller====

Using the Serial Console interface, it is possible to connect to the STM32 microcontroller with the command below. The STM32 controls the power sequencing and several other low level device operations.

$ sudo screen /dev/serial/by-id/usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6CB5-if01-port0 115200

The STM32 interface provides a very simple prompt. The command <code>help</code> will list all available commands. A direct connection to the microcontroller can be used to hard-reset the device without physically accessing it (i.e., emulating a power button press) and other low-level diagnostics.

===Connecting to the ARM via SSH===
By default, the RJ45 1Gb management interface is configured to be assigned a DHCP IP address.

If you have access to a network which provides a DHCP server (such as a common router's LAN), attach the RJ45 1Gb port to this network. Details vary by vendor, however, most router management interfaces will provide a list of attached devices to the LAN including their IP address.

Without access to a router management interface, you can identify the IP address by connecting to the ARM CPU via Serial Console as detailed in the section above and running the command <code>ip a</code>:

Example Output:

<pre>
# ip a
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
valid_lft forever preferred_lft forever
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast qlen 1000
link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
inet 192.168.1.151/24 brd 192.168.1.255 scope global dynamic eth0
valid_lft 42865sec preferred_lft 42865sec
3: sfp0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 9000 qdisc pfifo_fast qlen 1000
link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
inet 192.168.10.2/24 brd 192.168.10.255 scope global sfp0
valid_lft forever preferred_lft forever
4: sfp1: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 9000 qdisc pfifo_fast qlen 1000
link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
</pre>

If you do not have access to a network with a DHCP server, you can create one using the Linux utility <code>dnsmasq</code>:

$ sudo dnsmasq -i <ETHERNET_ADAPTER_NAME> --dhcp-range=192.168.1.151,192.168.1.254 --except-interface=lo --bind-dynamic --no-daemon

NOTE: Modify the value <code><ETHERNET_ADAPTER_NAME></code> to match the interface you would like to create a DHCP server on.

After the device has obtained an IP address, you can remotely log into it from a Linux or macOS system with SSH, as shown below:

$ ssh root@192.168.1.151

NOTE: The IP address may vary depending on your network setup.

NOTE: The <code>root</code> password default password is empty/blank.

On Microsoft Windows, the SSH connection can be established using the third-party program Putty.

After logging in, you should be presented with a shell like the following:

root@ni-n3xx-<motherboard serial #>:~#

==Updating the Linux File System==
Before operating the device, it is strongly recommended to update to the latest version of the Embedded Linux file system. If you are operating the device in Network Mode, the version of UHD running on the host machine and N3xx USRP must match.

There is two ways to update the file system for the N3xx USRP:

1. Mender

2. Physically remove microSD card from device and write a new file system to the microSD card.

===File System Partition Layout===
The SD Card is divided into four partitions. There is two root file system partitions, a boot partition and a data partition.

Any data you would like to preserve through Mender updates should be saved to the <code>data</code> partition, which is mounted at <code>/data</code>.

===Updating the file system with Mender===
Mender is third-party software that enables remote updating of the root file system without physically accessing the device (see also the Mender website https://mender.io). Mender can be executed locally on the device, or a Mender server can be set up which can be used to remotely update an arbitrary number of USRP devices. Users can host their own local Mender server, or use servers hosted by Mender as a paid service; contact Mender for more information.

====Mender Update Process====
When updating the file system using Mender, the tool will overwrite the root file system partition that is not currently mounted. Any data stored in the root partitions will be permanently lost with a Mender update.

After updating a partition with Mender, it will reboot into the newly updated partition. Only if the update is confirmed by the user, the update will be made permanent. This means that if an update fails, the device will be always able to reboot into the partition from which the update was originally launched, which presumably is in a working state. Another update can be launched now to correct the previous, failed update, until it works.

To obtain the file system Mender image (these are files with a <code>.mender</code> suffix), run the following command on the host computer with Internet access:

$ sudo uhd_images_downloader -t mender -t n3xx --yes

Example Output:
[INFO] Images destination: /usr/local/share/uhd/images
451639 kB / 451639 kB (100%) n3xx_common_mender_default-v3.14.0.0.zip
[INFO] Images download complete.

NOTE: In the output of the command, the folder destination where the images are saved is printed out.

Next, you will need to copy this Mender file system image to the USRP N3xx. This can be done with the Linux utility <code>scp</code>.

$ scp /usr/local/share/uhd/images/usrp_n3xx_fs.mender root@192.168.1.51:~/.

Note: The path and IP may different for your configuration, the command above assumes you're using the default installation path of <code>/usr/local</code> and that the N3xx's IP is <code>192.168.1.51</code>.

After copying the Mender file system image to the N3xx, connect to the N3xx using either the Serial Console, or via SSH to gain shell access.

On the N3xx, run <code>mender install /path/to/latest.mender</code> to update the file system:

$ mender install /home/root/usrp_n3xx_fs.mender

The artifact can also be stored on a remote server:
$ mender install <nowiki>http://server.name/path/to/latest.mender</nowiki>

This procedure will take a few minutes to complete. After mender has logged a successful update, reboot the device:
$ reboot

If the reboot worked, and the device seems functional, commit the changes so that the boot loader knows to permanently boot into this partition:
$ mender -commit

To identify the currently installed Mender artifact from the command line, the following file can be queried on the N3xx:
$ cat /etc/mender/artifact_info

If you are using a Mender server, the updates can be initiated from a web dashboard. From there, you can start the updates without having to log into the device, and you can update groups of USRPs with a few clicks in a web GUI. The dashboard can also be used to inspect the state of USRPs. This is a simple way to update groups of rack-mounted USRPs with custom file systems.

For more information on updating the file-system, refer to the UHD Manual at https://uhd.ettus.com.

===Updating the files system by writing the disk image===
Please see the separate application note, [[Writing the USRP File System Disk Image to a SD Card]], for step-by-step instructions on writing the file system image to the SD card.

==Updating the Network Configurations==
The USRP N3xx systemd network configuration files are located either at: <code>/etc/systemd/network/</code>

# ls /etc/systemd/network/
eth0.network sfp0.network sfp1.network

or for newer version of the file system: <code>/data/network/</code>

# ls /data/network/
eth0.network int0.network sfp0.network sfp1.network

For details on configuration please refer to the [https://www.freedesktop.org/software/systemd/man/systemd.network.html systemd-networkd manual pages].

The factory settings are as follows:
<pre>
eth0 (DHCP):

[Match]
Name=eth0

[Network]
DHCP=ipv4

[DHCP]
UseHostname=false

sfp0 (static):

[Match]
Name=sfp0

[Network]
Address=192.168.10.2/24

[Link]
MTUBytes=9000

sfp1 (static):

[Match]
Name=sfp1

[Network]
Address=192.168.20.2/24

[Link]
MTUBytes=9000
</pre>

Additional notes on networking:

* Care needs to be taken when editing these files on the device, since <code>vi</code> / <code>vim</code> sometimes generates undo files (e.g. <code>/etc/systemd/network/sfp0.network~</code>), that <code>systemd-networkd</code> might accidentally pick up.
* Temporarily setting the IP addresses or MTU sizes via <code>ifconfig</code> or other command line tools will only change the value until the next reboot or reload of the FPGA image.
* If the MTU of the device and host computers differ, streaming issues can occur.
* Streaming via SFP0 at 1 Gb rates requires a MTU of <code>1500</code>
* Streaming via SFP0 at 10 Gb rates requires a MTU of <code>9000</code>

For addition details on network configuration here: https://files.ettus.com/manual/page_usrp_n3xx.html#n3xx_network_configuration

==Updating the FPGA Image==

===Network Mode FPGA Image Update===
The FPGA image should match the version of UHD installed on the host computer, when operated in Network mode. Connect the device to the host computer using either the RJ45 or SFP+ port, refer to the section above for detailed instructions.

To obtain all the FPGA images for a specific version of UHD, run the following command on the host computer with internet access:

$ sudo uhd_images_downloader

Example Output:

$ sudo uhd_images_downloader
[INFO] Images destination: /usr/local/share/uhd/images
00006 kB / 00006 kB (100%) usrp1_b100_fw_default-g6bea23d.zip
19810 kB / 19810 kB (100%) x3xx_x310_fpga_default-gf1ba32fe.zip
02757 kB / 02757 kB (100%) usrp2_n210_fpga_default-g6bea23d.zip
02123 kB / 02123 kB (100%) n230_n230_fpga_default-ge57dfe0.zip
00522 kB / 00522 kB (100%) usrp1_b100_fpga_default-g6bea23d.zip
00491 kB / 00491 kB (100%) b2xx_b200_fpga_default-ge57dfe0.zip
02415 kB / 02415 kB (100%) usrp2_n200_fpga_default-g6bea23d.zip
08988 kB / 08988 kB (100%) e3xx_e320_fpga_default-g3de8954a.zip
23045 kB / 23045 kB (100%) n3xx_n310_fpga_default-g3de8954a.zip
00523 kB / 00523 kB (100%) b2xx_b205mini_fpga_default-ge57dfe0.zip
18937 kB / 18937 kB (100%) x3xx_x300_fpga_default-gf1ba32fe.zip
00017 kB / 00017 kB (100%) octoclock_octoclock_fw_default-g14000041.zip
00007 kB / 00007 kB (100%) usrp2_usrp2_fw_default-g6bea23d.zip
00009 kB / 00009 kB (100%) usrp2_n200_fw_default-g6bea23d.zip
00450 kB / 00450 kB (100%) usrp2_usrp2_fpga_default-g6bea23d.zip
00144 kB / 00144 kB (100%) b2xx_common_fw_default-ga69ab0c.zip
25107 kB / 25107 kB (100%) n3xx_n320_fpga_default-g3de8954a.zip
00464 kB / 00464 kB (100%) b2xx_b200mini_fpga_default-ge57dfe0.zip
00319 kB / 00319 kB (100%) usrp1_usrp1_fpga_default-g6bea23d.zip
04839 kB / 04839 kB (100%) usb_common_windrv_default-g14000041.zip
00009 kB / 00009 kB (100%) usrp2_n210_fw_default-g6bea23d.zip
16065 kB / 16065 kB (100%) n3xx_n300_fpga_default-g3de8954a.zip
05578 kB / 05578 kB (100%) e3xx_e310_fpga_default-g4bc2c6f.zip
00885 kB / 00885 kB (100%) b2xx_b210_fpga_default-ge57dfe0.zip
[INFO] Images download complete.

NOTE: In the above example output, the Images Destination folder is printed:

[INFO] Images destination: /usr/local/share/uhd/images

To list the N3xx FPGA images with a full path, run the command:

$ ls -w 1 /usr/local/share/uhd/images/usrp_n3*.bit

/usr/local/share/uhd/images/usrp_n300_fpga_AA.bit
/usr/local/share/uhd/images/usrp_n300_fpga_HG.bit
/usr/local/share/uhd/images/usrp_n300_fpga_WX.bit
/usr/local/share/uhd/images/usrp_n300_fpga_XG.bit
/usr/local/share/uhd/images/usrp_n310_fpga_AA.bit
/usr/local/share/uhd/images/usrp_n310_fpga_HG.bit
/usr/local/share/uhd/images/usrp_n310_fpga_WX.bit
/usr/local/share/uhd/images/usrp_n310_fpga_XG.bit
/usr/local/share/uhd/images/usrp_n320_fpga_AQ.bit
/usr/local/share/uhd/images/usrp_n320_fpga_HG.bit
/usr/local/share/uhd/images/usrp_n320_fpga_WX.bit
/usr/local/share/uhd/images/usrp_n320_fpga_XG.bit
/usr/local/share/uhd/images/usrp_n320_fpga_XQ.bit

To update the default <code>HG</code> variant of FPGA image, run the command:

$ uhd_image_loader --args "type=n3xx,addr=<N3xx_IP_ADDR>,fpga=HG"

Example Output:

uhd_image_loader --args "type=n3xx,addr=192.168.1.151,fpga=HG"
[INFO] [UHD] linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_3.11.1.HEAD-0-gad6b0935
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.1.151,type=n3xx,product=n310,serial=313ABDA,claimed=False,skip_init=1
[INFO] [MPM.main] Launching USRP/MPM, version: 3.11.1.0-gunknown
[INFO] [MPM.main] Spawning RPC process...
[INFO] [MPM.PeriphManager] Device serial number: 313ABDA
[INFO] [MPM.PeriphManager] Found 2 daughterboard(s).
[INFO] [MPM.PeriphManager.UDP] No CHDR interfaces found!
[INFO] [MPM.PeriphManager.UDP] No CHDR interfaces found!
[INFO] [MPM.RPCServer] RPC server ready!
[INFO] [MPM.RPCServer] Spawning watchdog task...
[INFO] [MPM.PeriphManager.UDP] No CHDR interfaces found!
[INFO] [MPMD] Claimed device without full initialization.
[INFO] [MPMD IMAGE LOADER] Starting update. This may take a while.
[INFO] [MPM.PeriphManager] Updating component `fpga'
[INFO] [MPM.PeriphManager] Updating component `dts'
[INFO] [MPM.RPCServer] Resetting peripheral manager.
[INFO] [MPM.PeriphManager] Device serial number: 313ABDA
[INFO] [MPM.PeriphManager] Found 2 daughterboard(s).
[INFO] [MPMD IMAGE LOADER] Update component function succeeded.

To load a different default FPGA image (i.e. <code>XG</code>, <code>WG</code>), modify the device argument <code>fpga=</code> to a value of <code>fpga=XG</code> or <code>fpga=WG</code>.

To specify the path to a custom FPGA image, use the <code>--fpga-path</code> argument.

$ uhd_image_loader --args "type=n3xx,addr=<N3xx_IP_ADDR>" --fpga-path=/path/to/custom/fpga.bit

The Verilog code for the FPGA in the USRP N3xx is open-source, and users are free to modify and customize it for their needs. However, certain modifications may result in either bricking the device, or even in physical damage to the unit. Please note that modifications to the FPGA are made at the risk of the user, and may not be covered by the warranty of the device.

===Embedded Mode FPGA Image Update===

It is possible to update the FPGA image when operated in Embedded mode. Connect to the ARM CPU via Serial Console or SSH as detailed in the section above.

Updating the FPGA image from the ARM CPU is the same as detailed above for a Network mode update, except it is not required to provide an <code>addr</code> device argument.

uhd_image_loader --args "type=n3xx,fpga=HG"

<pre>
root@ni-n3xx-313ABDA:~# uhd_image_loader --args "type=n3xx,fpga=HG"
[INFO] [UHD] linux; GNU C++ version 7.2.0; Boost_106400; UHD_3.11.1.0-0-unknown
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=127.0.0.1,type=n3xx,product=n310,serial=313ABDA,claimed=False,skip_init=1
[INFO] [MPMD] Claimed device without full initialization.
[INFO] [MPMD IMAGE LOADER] Starting update. This may take a while.
[INFO] [MPM.PeriphManager] Updating component `fpga'
[INFO] [MPM.PeriphManager] Updating component `dts'
[INFO] [MPM.RPCServer] Resetting peripheral manager.
[INFO] [MPM.PeriphManager] Device serial number: 313ABDA
[INFO] [MPM.PeriphManager] Found 2 daughterboard(s).
[INFO] [MPMD IMAGE LOADER] Update component function succeeded.
</pre>

For more information on updating the FPGA image, refer to the UHD Manual at http://uhd.ettus.com .

==Setting Up a Streaming Connection==
The device supports multiple, high-speed, low-latency interfaces on the SFP+ ports for streaming samples to the host computer.

===1Gb Streaming SFP Port 0===
Complete the steps below to set up a streaming connection over the 1 Gigabit Ethernet interface on <code>SFP Port 0</code>.

When streaming via SFP Port 0 at 1 Gb speeds, it is important that the connection is direct between the Host and USRP. Placing a switch or other network gear between the Host and USRP can reduce throughput of the transport link. It is also generally recommended to avoid using USB to Ethernet Adapters for the high speed streaming interface, as they may limit performance or cause periodic flow control errors.

NOTE: The <code>HG</code> FPGA image must be loaded for <code>SFP Port 0</code> to operate at 1Gb speeds. If the <code>XG</code> image is loaded, the port will be unresponsive at 1Gb speeds.

1. Configure your Host's Ethernet adapter as shown below. This interface should be separate from the 1Gb NIC/network which is connected to the 1Gb RJ45 management interface.

IP Address: 192.168.10.1
Subnet Mask: 255.255.255.0
Gateway: 0.0.0.0
MTU: 1500

NOTE: When operating <code>SFP Port 0</code> at 1Gb speeds, it is important to set a MTU of <code>1500</code> and not a value of <code>automatic</code>.

2. Insert the RJ45 – SFP+ adapter into <code>SFP Port 0</code> .

3. Connect the adapter to a host computer using the Ethernet cable to SFP0.

The Green LED above <code>SFP Port 0</code> should illuminate.

4. To test the connection, <code>ping</code> the device at address <code>192.168.10.2</code> from the host, as shown
below:

$ ping 192.168.10.2
PING 192.168.10.2 (192.168.10.2) 56(84) bytes of data.
64 bytes from 192.168.10.2: icmp_seq=1 ttl=64 time=1.06 ms
^C
--- 192.168.10.2 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 1.065/1.065/1.065/0.000 ms

Press <code>CTRL+C</code> to stop the ping program.

Proceed to the next section "Verifying Device Operation".

===10Gb Streaming SFP Port 1===
Complete the steps below to set up a streaming connection over the 10 Gigabit Ethernet interface on <code>SFP Port 1</code>.

NOTE: Both the <code>HG</code> and <code>XG</code> FPGA images support 10Gb speeds over SFP Port 1.

1. Configure your Host's 10Gb Ethernet adapter as shown below.

IP Address: 192.168.20.1
Subnet Mask: 255.255.255.0
Gateway: 0.0.0.0
MTU: 9000

NOTE: When operating at 10Gb speeds, it is important to set a MTU of <code>9000</code> and not a value of <code>automatic</code>.

2. Connect the USRP to a host computer using either a 10Gb SFP or Fiber cable to <code>SFP Port 1</code>.

The Green LED above <code>SFP Port 1</code> should illuminate.

3. To test the connection, <code>ping</code> the device at address <code>192.168.20.2</code> from the host, as shown
below:

$ ping 192.168.20.2

Press <code>CTRL+C</code> to stop the ping program.

Proceed to the next section "Verifying Device Operation".

===Dual 10Gb Streaming SFP Ports 0/1===
Complete the steps below to set up a streaming connections over the Dual 10 Gigabit Ethernet interface on <code>SFP Ports 0/1</code>.

NOTE: The <code>XG</code> FPGA image must be loaded for <code>SFP Port 0</code> to operate at 10 Gb speeds. If the <code>HG</code> image is loaded, the port will be unresponsive at 10 Gb speeds.

1. Configure your Host's #1 10Gb Ethernet adapter as shown below.

IP Address: 192.168.10.1
Subnet Mask: 255.255.255.0
Gateway: 0.0.0.0
MTU: 9000

2. Configure your Host's #2 10Gb Ethernet adapter as shown below.

IP Address: 192.168.20.1
Subnet Mask: 255.255.255.0
Gateway: 0.0.0.0
MTU: 9000

NOTE: When operating at 10Gb speeds, it is important to set a MTU of <code>9000</code> and not a value of <code>automatic</code>.

3. Connect the USRP to a host computer using either a 10Gb SFP or Fiber cables to <code>SFP Ports 0/1</code>.

The Green LEDs above <code>SFP Ports 0/1</code> should illuminate.

4. To test the <code>SFP Port 0</code> connection, <code>ping</code> the device at address <code>192.168.10.2</code> from the host, as shown below:

$ ping 192.168.10.2

Press <code>CTRL+C</code> to stop the ping program.

5. To test the <code>SFP Port 1</code> connection, <code>ping</code> the device at address <code>192.168.20.2</code> from the host, as shown below:

$ ping 192.168.20.2

Press <code>CTRL+C</code> to stop the ping program.

Proceed to the next section "Verifying Device Operation".

For more details on Network Setup and Configuration, please see the “Interfaces and Connectivity” section on the [[N300/N310]] or [[N320/N321]] hardware resources pages.

==Verifying Device Operation==
Once you have successfully setup a management interface and streaming interface, you can now verify the devices operation using the included UHD utilities.

===Subdevice Specification Mapping===
====N300====
The USRP N300 contains 2 channels, each represented on the front panel as <code>RF0-1</code>. Below is the <code>subdev</code> mapping of RF Ports.

* RF0 = A:0
* RF1 = A:1

====N310====
The USRP N310 contains 4 channels, each represented on the front panel as <code>RF0-3</code>. Below is the <code>subdev</code> mapping of RF Ports.

=====UHD 3.11.x.x - 3.12.x.x=====
* RF0 = A:0
* RF1 = B:0
* RF2 = C:0
* RF3 = D:0

=====UHD 3.13.x.x+=====
* RF0 = A:0
* RF1 = A:1
* RF2 = B:0
* RF3 = B:1

====N320====
The USRP N320 contains 2 channels, each represented on the front panel as <code>RF0-1</code>. Below is the <code>subdev</code> mapping of RF Ports.

* RF0 = A:0
* RF1 = B:0

====N321====
The USRP N321 contains 2 channels, each represented on the front panel as <code>RF0-1</code>. Below is the <code>subdev</code> mapping of RF Ports.

* RF0 = A:0
* RF1 = B:0

Additional details of UHD Subdevice Specifications can be found here in the UHD Manual: http://files.ettus.com/manual/page_configuration.html#config_subdev

===Supported Sample Rates===

The USRP N300/N310 supports the three fixed Master Clock Rates listed below.

* 122.88 MHz
* 125.00 MHz
* 153.60 MHz

The USRP N320/N321 supports the three fixed Master Clock Rates listed below.

* 200.00 MHz
* 245.76 MHz
* 250.00 MHz

Sample rates as delivered to/from the host computer for USRP devices are constrained to follow several important rules.

It is important to understand that strictly-integer decimation and interpolation are used within USRP hardware to meet the requested sample rate requirements of the application at hand. That means that the desired sample rate must meet the requirement that master-clock-rate/desired-sample-rate be an integer ratio. Further, it is strongly desirable for that ratio to be even. This ratio is the decimation (down-conversion) or interpolation (up-conversion) factor. The decimation or interpolation factor may be between 1 and 1024. There are further constraints on the decimation or interpolation factor. If the decimation or interpolation factor exceeds 128, then it must be evenly divisible by 2. If the decimation or interpolation factor exceeds 256, then it must be evenly divisible by 4.

====Example Sample Rates====
Listed below are common sample rates for the given master clock rates. This is not a complete listing of the supported sample rates.

{| class="wikitable"
!Master Clock Rate
!colspan="20"|Decimation / Interpolation Rate Host Sample Rate [Msps]
|-

|style="text-align:center;"| 1
|style="text-align:center;"| 2
|style="text-align:center;"| 4
|style="text-align:center;"| 6
|style="text-align:center;"| 8
|style="text-align:center;"| 10
|style="text-align:center;"| 12
|style="text-align:center;"| 14
|style="text-align:center;"| 16
|style="text-align:center;"| 18
|style="text-align:center;"| 20
|style="text-align:center;"| 30
|style="text-align:center;"| 32
|style="text-align:center;"| 64
|style="text-align:center;"| 100
|style="text-align:center;"| 128
|style="text-align:center;"| 200
|style="text-align:center;"| 256
|style="text-align:center;"| 512
|style="text-align:center;"| 1024
|-

|style="text-align:center;"| 122.88e6
|style="text-align:center;"| 61.44e6
|style="text-align:center;"| 30.72e6
|style="text-align:center;"| 20.48e6
|style="text-align:center;"| 15.36e6
|style="text-align:center;"| 12.288e6
|style="text-align:center;"| 10.24e6
|style="text-align:center;"| 8.7771e6
|style="text-align:center;"| 7.68e6
|style="text-align:center;"| 6.8267e6
|style="text-align:center;"| 6.144e6
|style="text-align:center;"| 4.096e6
|style="text-align:center;"| 3.84e6
|style="text-align:center;"| 1.92e6
|style="text-align:center;"| 1.2288e6
|style="text-align:center;"| 960e3
|style="text-align:center;"| 614.4e3
|style="text-align:center;"| 480e3
|style="text-align:center;"| 240e3
|style="text-align:center;"| 120e3
|-

|style="text-align:center;"| 125e6
|style="text-align:center;"| 62.5e6
|style="text-align:center;"| 31.25e6
|style="text-align:center;"| 20.833e6
|style="text-align:center;"| 15.625e6
|style="text-align:center;"| 12.5e6
|style="text-align:center;"| 10.417e6
|style="text-align:center;"| 8.9286e6
|style="text-align:center;"| 7.8125e6
|style="text-align:center;"| 6.9444e6
|style="text-align:center;"| 6.25e6
|style="text-align:center;"| 4.1667e6
|style="text-align:center;"| 3.90625e6
|style="text-align:center;"| 1.953125e6
|style="text-align:center;"| 1.25e6
|style="text-align:center;"| 976.5625e3
|style="text-align:center;"| 625e3
|style="text-align:center;"| 488.28125e3
|style="text-align:center;"| 244.14e3
|style="text-align:center;"| 122.07e3

|-

|style="text-align:center;"| 153.6e6
|style="text-align:center;"| 76.8e6
|style="text-align:center;"| 38.4e6
|style="text-align:center;"| 25.6e6
|style="text-align:center;"| 19.2e6
|style="text-align:center;"| 15.36e6
|style="text-align:center;"| 12.8e6
|style="text-align:center;"| 10.971e6
|style="text-align:center;"| 9.6e6
|style="text-align:center;"| 8.5333e6
|style="text-align:center;"| 7.68e6
|style="text-align:center;"| 5.12e6
|style="text-align:center;"| 4.8e6
|style="text-align:center;"| 2.4e6
|style="text-align:center;"| 1.536e6
|style="text-align:center;"| 1.2e6
|style="text-align:center;"| 768e3
|style="text-align:center;"| 600e3
|style="text-align:center;"| 300e3
|style="text-align:center;"| 150e3

|-

|}

====N320/N321 Example Sample Rates====
Listed below are common sample rates for the given master clock rates. This is not a complete listing of the supported sample rates.

{| class="wikitable"
!Master Clock Rate
!colspan="20"|Decimation / Interpolation Rate Host Sample Rate [Msps]
|-

|style="text-align:center;"| 1
|style="text-align:center;"| 2
|style="text-align:center;"| 4
|style="text-align:center;"| 6
|style="text-align:center;"| 8
|style="text-align:center;"| 10
|style="text-align:center;"| 12
|style="text-align:center;"| 14
|style="text-align:center;"| 16
|style="text-align:center;"| 18
|style="text-align:center;"| 20
|style="text-align:center;"| 30
|style="text-align:center;"| 32
|style="text-align:center;"| 64
|style="text-align:center;"| 100
|style="text-align:center;"| 128
|style="text-align:center;"| 200
|style="text-align:center;"| 256
|style="text-align:center;"| 512
|style="text-align:center;"| 1024
|-

|style="text-align:center;"| 200e6
|style="text-align:center;"| 100e6
|style="text-align:center;"| 50e6
|style="text-align:center;"| 33.33e6
|style="text-align:center;"| 25e6
|style="text-align:center;"| 20e6
|style="text-align:center;"| 16.66e6
|style="text-align:center;"| 14.2857e6
|style="text-align:center;"| 12.5e6
|style="text-align:center;"| 11.11e6
|style="text-align:center;"| 10e6
|style="text-align:center;"| 6.667e6
|style="text-align:center;"| 6.25e6
|style="text-align:center;"| 3.125e6
|style="text-align:center;"| 2e6
|style="text-align:center;"| 1.5625e6
|style="text-align:center;"| 1e6
|style="text-align:center;"| 781.25e3
|style="text-align:center;"| 390.625e3
|style="text-align:center;"| 195.3125e3

|-

|style="text-align:center;"| 245.76e6
|style="text-align:center;"| 122.88e6
|style="text-align:center;"| 61.44e6
|style="text-align:center;"| 30.72e6
|style="text-align:center;"| 20.48e6
|style="text-align:center;"| 15.36e6
|style="text-align:center;"| 12.288e6
|style="text-align:center;"| 10.24e6
|style="text-align:center;"| 8.7771e6
|style="text-align:center;"| 7.68e6
|style="text-align:center;"| 6.8267e6
|style="text-align:center;"| 6.144e6
|style="text-align:center;"| 4.096e6
|style="text-align:center;"| 3.84e6
|style="text-align:center;"| 1.92e6
|style="text-align:center;"| 1.2288e6
|style="text-align:center;"| 960e3
|style="text-align:center;"| 614.4e3
|style="text-align:center;"| 480e3
|style="text-align:center;"| 240e3
|-

|style="text-align:center;"| 250e6
|style="text-align:center;"| 125e6
|style="text-align:center;"| 62.5e6
|style="text-align:center;"| 31.25e6
|style="text-align:center;"| 20.833e6
|style="text-align:center;"| 15.625e6
|style="text-align:center;"| 12.5e6
|style="text-align:center;"| 10.417e6
|style="text-align:center;"| 8.9286e6
|style="text-align:center;"| 7.8125e6
|style="text-align:center;"| 6.9444e6
|style="text-align:center;"| 6.25e6
|style="text-align:center;"| 4.1667e6
|style="text-align:center;"| 3.90625e6
|style="text-align:center;"| 1.953125e6
|style="text-align:center;"| 1.25e6
|style="text-align:center;"| 976.5625e3
|style="text-align:center;"| 625e3
|style="text-align:center;"| 488.28125e3
|style="text-align:center;"| 244.14e3

|-

|}

Additional information on Sample Rates can be found here in the UHD Manual: http://files.ettus.com/manual/page_general.html#general_sampleratenotes

===Probe the USRP===

====N300/N310====
The UHD utility <code>uhd_usrp_probe</code> provides detailed information of the USRP device.

From your host computer, run the command <code>uhd_usrp_probe</code>:

<pre>
$ uhd_usrp_probe
[INFO] [UHD] linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_3.13.1.HEAD-0-ga0a71d10
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.10.2,type=n3xx,product=n310,serial=313ABDA,claimed=False,addr=192.168.10.2
[INFO] [MPM.main] Launching USRP/MPM, version: 3.13.1.0-gd3b7e90a
[INFO] [MPM.main] Spawning RPC process...
[INFO] [MPM.PeriphManager] Device serial number: 313ABDA
[INFO] [MPM.PeriphManager] Initialized 2 daughterboard(s).
[INFO] [MPM.PeriphManager] init() called with device args `time_source=internal,clock_source=internal'.
[INFO] [MPM.RPCServer] RPC server ready!
[INFO] [MPM.RPCServer] Spawning watchdog task...
[INFO] [0/DmaFIFO_0] Initializing block control (NOC ID: 0xF1F0D00000000004)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1355 MB/s)
[INFO] [MPM.PeriphManager] init() called with device args `mgmt_addr=192.168.10.2,clock_source=internal,time_source=internal,product=n310'.
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1358 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1355 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1345 MB/s)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000011312)
[INFO] [0/Radio_1] Initializing block control (NOC ID: 0x12AD100000011312)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000000)
[INFO] [0/DDC_1] Initializing block control (NOC ID: 0xDDC0000000000000)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000002)
[INFO] [0/DUC_1] Initializing block control (NOC ID: 0xD0C0000000000002)
_____________________________________________________
/
| Device: N300-Series Device
| _____________________________________________________
| /
| | Mboard: ni-n3xx-313ABDA
| | eeprom_version: 1
| | mpm_version: 3.13.1.0-gd3b7e90a
| | pid: 16962
| | product: n310
| | rev: 3
| | rpc_connection: remote
| | serial: 313ABDA
| | type: n3xx
| | MPM Version: 1.2
| | FPGA Version: 5.2
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, gpsdo, sfp0
| | Clock sources: external, internal, gpsdo
| | Sensors: gps_tpv, ref_locked, gps_time, gps_locked, temp, gps_sky, fan
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Magnesium
| | | | Antennas: TX/RX, RX2, CAL, LOCAL
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 75.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 1
| | | | Name: Magnesium
| | | | Antennas: TX/RX, RX2, CAL, LOCAL
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 75.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: AD9371 Dual ADC
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RX Dboard: B
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Magnesium
| | | | Antennas: TX/RX, RX2, CAL, LOCAL
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 75.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 1
| | | | Name: Magnesium
| | | | Antennas: TX/RX, RX2, CAL, LOCAL
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 75.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: B
| | | | Name: AD9371 Dual ADC
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Magnesium
| | | | Antennas: TX/RX
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 65.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 1
| | | | Name: Magnesium
| | | | Antennas: TX/RX
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 65.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: AD9371 Dual DAC
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: B
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Magnesium
| | | | Antennas: TX/RX
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 65.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 1
| | | | Name: Magnesium
| | | | Antennas: TX/RX
| | | | Sensors: lo_locked, ad9371_lo_locked, lowband_lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 65.0 step 0.5 dB
| | | | Gain range rfic: 0.0 to 0.0 step 0.0 dB
| | | | Gain range dsa: 0.0 to 0.0 step 0.0 dB
| | | | Gain range amp: 0.0 to 0.0 step 0.0 dB
| | | | Bandwidth range: 20000000.0 to 100000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: B
| | | | Name: AD9371 Dual DAC
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * DmaFIFO_0
| | | * Radio_0
| | | * Radio_1
| | | * DDC_0
| | | * DDC_1
| | | * DUC_0
| | | * DUC_1

</pre>

====N320====

<pre>

$ uhd_usrp_probe
[INFO] [UHD] linux; GNU C++ version 7.3.0; Boost_106600; UHD_3.14.0.0-0-g6875d061
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=127.0.0.1,type=n3xx,product=n320,serial=3181FFA,claimed=False
[INFO] [MPM.main] Launching USRP/MPM, version: 3.14.0.0-g6875d061
[INFO] [MPM.main] Spawning RPC process...
[INFO] [MPM.PeriphManager] Device serial number: 3181FFA
[INFO] [MPM.Rhodium-0] Successfully loaded all peripherals!
[INFO] [MPM.Rhodium-1] Successfully loaded all peripherals!
[INFO] [MPM.PeriphManager] Initialized 2 daughterboard(s).
[INFO] [MPM.PeriphManager] No QSFP board detected: Assuming it is disabled in the device tree overlay (e.g., HG, XG images).
[INFO] [MPM.PeriphManager] init() called with device args `time_source=internal,clock_source=internal'.
[INFO] [MPM.Rhodium-0] init() called with args `time_source=internal,clock_source=internal'
[INFO] [MPM.Rhodium-1] init() called with args `time_source=internal,clock_source=internal'
[INFO] [MPM.Rhodium-0.init.LMK04828] LMK initialized and locked!
[INFO] [MPM.Rhodium-1.init.LMK04828] LMK initialized and locked!
[INFO] [MPM.Rhodium-1.DAC37J82] DAC PLL Locked!
[INFO] [MPM.Rhodium-1.AD9695] ADC PLL Locked!
[INFO] [MPM.Rhodium-1.init] JESD204B Link Initialization & Training Complete
[INFO] [MPM.Rhodium-0.DAC37J82] DAC PLL Locked!
[INFO] [MPM.Rhodium-0.AD9695] ADC PLL Locked!
[INFO] [MPM.Rhodium-0.init] JESD204B Link Initialization & Training Complete
[INFO] [MPM.RPCServer] RPC server ready!
[INFO] [MPM.RPCServer] Spawning watchdog task...
[INFO] [MPM.PeriphManager] init() called with device args `mgmt_addr=127.0.0.1,clock_source=internal,time_source=internal,product=n320'.
[INFO] [MPM.Rhodium-0] init() called with args `mgmt_addr=127.0.0.1,clock_source=internal,time_source=internal,product=n320'
[INFO] [MPM.Rhodium-1] init() called with args `mgmt_addr=127.0.0.1,clock_source=internal,time_source=internal,product=n320'
[INFO] [0/Replay_0] Initializing block control (NOC ID: 0x4E91A00000000004)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000000320)
[INFO] [0/Radio_1] Initializing block control (NOC ID: 0x12AD100000000320)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DDC_1] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/DUC_1] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/FIFO_0] Initializing block control (NOC ID: 0xF1F0000000000000)
[INFO] [0/FIFO_1] Initializing block control (NOC ID: 0xF1F0000000000000)
_____________________________________________________
/
| Device: N300-Series Device
| _____________________________________________________
| /
| | Mboard: ni-n3xx-3181FFA
| | eeprom_version: 2
| | mpm_version: 3.14.0.0-g6875d061
| | pid: 16962
| | product: n320
| | rev: 6
| | rpc_connection: local
| | serial: 3181FFA
| | type: n3xx
| | MPM Version: 1.2
| | FPGA Version: 5.3
| | FPGA git hash: 3de8954.clean
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, gpsdo, sfp0
| | Clock sources: external, internal, gpsdo
| | Sensors: gps_tpv, temp, gps_sky, fan, gps_time, gps_locked, ref_locked, gps_gpgga
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: Unknown (0x0152)
| | | Serial: 3175A79
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, RX2, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: ad9695-625
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RX Dboard: B
| | | ID: Unknown (0x0152)
| | | Serial: 3175A67
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, RX2, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: B
| | | | Name: ad9695-625
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: Unknown (0x0152)
| | | Serial: 3175A79
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: dac37j82
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: B
| | | ID: Unknown (0x0152)
| | | Serial: 3175A67
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: B
| | | | Name: dac37j82
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * Replay_0
| | | * Radio_0
| | | * Radio_1
| | | * DDC_0
| | | * DDC_1
| | | * DUC_0
| | | * DUC_1
| | | * FIFO_0
| | | * FIFO_1

</pre>

====N321====

<pre>
$ uhd_usrp_probe
[INFO] [UHD] linux; GNU C++ version 7.3.1 20180712 (Red Hat 7.3.1-6); Boost_106400; UHD_3.14.0.0-0-g6875d061
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.20.2,type=n3xx,product=n320,serial=3166646,claimed=False,addr=192.168.20.2
[INFO] [MPM.PeriphManager] init() called with device args `time_source=internal,clock_source=internal,product=n320,mgmt_addr=192.168.20.2'.
[INFO] [MPM.Rhodium-0] init() called with args `time_source=internal,clock_source=internal,product=n320,mgmt_addr=192.168.20.2'
[INFO] [MPM.Rhodium-1] init() called with args `time_source=internal,clock_source=internal,product=n320,mgmt_addr=192.168.20.2'
[INFO] [0/Replay_0] Initializing block control (NOC ID: 0x4E91A00000000004)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000000320)
[INFO] [0/Radio_1] Initializing block control (NOC ID: 0x12AD100000000320)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DDC_1] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/DUC_1] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/FIFO_0] Initializing block control (NOC ID: 0xF1F0000000000000)
[INFO] [0/FIFO_1] Initializing block control (NOC ID: 0xF1F0000000000000)
_____________________________________________________
/
| Device: N300-Series Device
| _____________________________________________________
| /
| | Mboard: ni-n3xx-3166646
| | eeprom_version: 2
| | mpm_version: 3.14.0.0-g6875d061
| | pid: 16962
| | product: n320
| | rev: 6
| | rpc_connection: remote
| | serial: 3166646
| | type: n3xx
| | MPM Version: 1.2
| | FPGA Version: 5.3
| | FPGA git hash: 3de8954.clean
| | RFNoC capable: Yes
| |
| | Time sources: internal, external, gpsdo, sfp0
| | Clock sources: external, internal, gpsdo
| | Sensors: gps_sky, gps_time, gps_gpgga, gps_locked, fan, gps_tpv, ref_locked, temp
| | _____________________________________________________
| | /
| | | RX Dboard: B
| | | ID: Unknown (0x0152)
| | | Serial: 316D814
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, RX2, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: B
| | | | Name: ad9695-625
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | ID: Unknown (0x0152)
| | | Serial: 316D810
| | | _____________________________________________________
| | | /
| | | | RX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, RX2, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: ad9695-625
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: B
| | | ID: Unknown (0x0152)
| | | Serial: 316D814
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: B
| | | | Name: dac37j82
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | ID: Unknown (0x0152)
| | | Serial: 316D810
| | | _____________________________________________________
| | | /
| | | | TX Frontend: 0
| | | | Name: Rhodium
| | | | Antennas: TX/RX, CAL, TERM
| | | | Sensors: lo_locked
| | | | Freq range: 1.000 to 6000.000 MHz
| | | | Gain range all: 0.0 to 60.0 step 1.0 dB
| | | | Bandwidth range: 250000000.0 to 250000000.0 step 0.0 Hz
| | | | Connection Type:
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: dac37j82
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | RFNoC blocks on this device:
| | |
| | | * Replay_0
| | | * Radio_0
| | | * Radio_1
| | | * DDC_0
| | | * DDC_1
| | | * DUC_0
| | | * DUC_1
| | | * FIFO_0
| | | * FIFO_1

</pre>

If you see warnings such as:

[WARNING] [UDP] The recv buffer could not be resized sufficiently.

You need to resize the socket buffers for your network interface card:

sudo sysctl -w net.core.rmem_max=288000
sudo sysctl -w net.core.wmem_max=288000
sudo sysctl -w net.core.rmem_max=33554432

===ASCII Art Example===
The UHD driver includes several example programs, which may serve as test programs or the basis for your application program. The source code can be obtained from the UHD repository on github at: https://github.com/EttusResearch/uhd/tree/master/host/examples

You can quickly verify the operation of your USRP N3xx by running the <code>rx_ascii_art_dft</code> UHD example program.

The <code>rx_ascii_art_dft</code> utility is a simple console based, real-time FFT display tool. It is not graphical in nature, so it can be easily run over an SSH connection within a terminal window, and does not need any graphical capability, such as X Windows, to be installed. It can also be run over a serial console connection, although this is not recommended, as the formatting may not render correctly.

You can run a simple test of the N3xx USRP by connecting an antenna and observing the spectrum of a commercial FM radio station in real-time, following the steps below:

1. Attach an antenna to the <code>Ch0/RX2</code> antenna port of the N3xx.

2. From your host computer, run the command:

'''N300/N310'''
<pre>
$ /usr/local/lib/uhd/examples/rx_ascii_art_dft --args "master_clock_rate=125e6,mgmt_addr=192.168.1.151,addr=192.168.10.2" --freq 98.5e6 --rate 2.5e6 --gain 50 --ref-lvl="-50" --dyn-rng 90 --ant "RX2" --subdev "A:0"
</pre>

'''N320/N321'''
<pre>
$ /usr/local/lib/uhd/examples/rx_ascii_art_dft --args "master_clock_rate=250e6,mgmt_addr=192.168.1.151,addr=192.168.10.2" --freq 98.5e6 --rate 2.5e6 --gain 50 --ref-lvl="-50" --dyn-rng 90 --ant "RX2" --subdev "A:0"
</pre>

NOTE: Modify the command line argument <code>freq</code> above to specify a tuning frequency for a strong local FM radio station. You will also need to update the IP Address to match your device IP.

3. You should see a real-time FFT display of 2.5 MHz of spectrum, centered at the specified tuning frequency.

4. Type "<code>Q</code>" or <code>Ctrl-C</code> to stop the program and to return to the Linux command line.

5. You can run with the <code>--help</code> argument to see a description of all available command-line options.

Example Output:

<pre>
$ /usr/local/lib/uhd/examples/rx_ascii_art_dft --args "master_clock_rate=125e6,mgmt_addr=192.168.1.151,addr=192.168.10.2" --freq 98.5e6 --rate 2.5e6 --gain 50 --ref-lvl="-50" --dyn-rng 90 --ant "RX2" --subdev "A:0"

Creating the usrp device with: master_clock_rate=125e6,mgmt_addr=192.168.1.151,addr=192.168.10.2...
[INFO] [UHD] linux; GNU C++ version 5.4.0 20160609; Boost_105800; UHD_3.11.1.HEAD-0-gad6b0935
[INFO] [MPMD] Initializing 1 device(s) in parallel with args: mgmt_addr=192.168.1.151,type=n3xx,product=n310,serial=313ABDA,claimed=False,master_clock_rate=125e6,addr=192.168.10.2
[INFO] [MPM.main] Launching USRP/MPM, version: 3.11.1.0-gunknown
[INFO] [MPM.main] Spawning RPC process...
[INFO] [MPM.PeriphManager] Device serial number: 313ABDA
[INFO] [MPM.PeriphManager] Found 2 daughterboard(s).
[INFO] [MPM.RPCServer] RPC server ready!
[INFO] [MPM.RPCServer] Spawning watchdog task...
[INFO] [MPM.PeriphManager] init() called with device args `mgmt_addr=192.168.1.151,product=n310,master_clock_rate=125e6'.
[INFO] [0/DmaFIFO_0] Initializing block control (NOC ID: 0xF1F0D00000000004)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1336 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1338 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1346 MB/s)
[INFO] [0/DmaFIFO_0] BIST passed (Throughput: 1350 MB/s)
[INFO] [0/Radio_0] Initializing block control (NOC ID: 0x12AD100000000310)
[INFO] [0/Radio_1] Initializing block control (NOC ID: 0x12AD100000000310)
[INFO] [0/Radio_2] Initializing block control (NOC ID: 0x12AD100000000310)
[INFO] [0/Radio_3] Initializing block control (NOC ID: 0x12AD100000000310)
[INFO] [0/DDC_0] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DDC_1] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DDC_2] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DDC_3] Initializing block control (NOC ID: 0xDDC0000000000001)
[INFO] [0/DUC_0] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/DUC_1] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/DUC_2] Initializing block control (NOC ID: 0xD0C0000000000000)
[INFO] [0/DUC_3] Initializing block control (NOC ID: 0xD0C0000000000000)
Using Device: Single USRP:
Device: N300-Series Device
Mboard 0: ni-n3xx-313ABDA
RX Channel: 0
RX DSP: 0
RX Dboard: A
RX Subdev: Magnesium
TX Channel: 0
TX DSP: 0
TX Dboard: A
TX Subdev: Magnesium
TX Channel: 1
TX DSP: 0
TX Dboard: B
TX Subdev: Magnesium
TX Channel: 2
TX DSP: 0
TX Dboard: C
TX Subdev: Magnesium
TX Channel: 3
TX DSP: 0
TX Dboard: D
TX Subdev: Magnesium

Setting RX Rate: 2.500000 Msps...
Actual RX Rate: 2.500000 Msps...

Setting RX Freq: 98.500000 MHz...
Actual RX Freq: 98.500000 MHz...

Setting RX Gain: 50.000000 dB...
Actual RX Gain: 50.000000 dB...

Checking RX: all_los: locked ...

Done!
</pre>

===Benchmarking your system===
Included with the UHD driver example programs is a utility, <code>benchmark_rate</code> to benchmark the transport link of the system.

A system's maximum performance is dependent upon many factors. <code>benchmark_rate</code> will exercise the transport link and CPU of the system.

====1 Gb Interface====
NOTE: This example requires the <code>HG</code> FPGA image to be loaded.

'''N300/N310'''

This example will test one full-duplex stream using "RF0/A:0", at a rate of 3.84 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.10.2,master_clock_rate=122.88e6" \
--duration 60 \
--channels "0" \
--rx_rate 3.84e6 \
--rx_subdev "A:0" \
--tx_rate 3.84e6 \
--tx_subdev "A:0"

'''N310'''

This example will test four full-duplex streams at 1.25 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.10.2,master_clock_rate=125e6" \
--duration 60 \
--channels "0,1,2,3" \
--rx_rate 1.25e6 \
--rx_subdev "A:0 A:1 B:0 B:1" \
--tx_rate 1.25e6 \
--tx_subdev "A:0 A:1 B:0 B:1"

'''N320/N321'''

This example will test one full-duplex stream using "RF0/A:0", at a rate of 3.84 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.10.2,master_clock_rate=245.76e6" \
--duration 60 \
--channels "0" \
--rx_rate 3.84e6 \
--rx_subdev "A:0" \
--tx_rate 3.84e6 \
--tx_subdev "A:0"

When streaming samples over a 1 Gb transport link, the maximum accumulative rate for all channels is 25 MS/s with a <code>sc16</code> OTW format. To achieve higher streaming rates, it is recommended to use the 10 Gb interfaces.

====10 Gb Interface SFP 1====
NOTE: This example will work with either the <code>HG</code> or <code>XG</code> FPGA image.

'''N300/N310'''

This example will test one full-duplex stream using "RF0/A:0", at a rate of 31.25 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.20.2,master_clock_rate=125e6" \
--duration 60 \
--channels "0" \
--rx_rate 31.25e6 \
--rx_subdev "A:0" \
--tx_rate 31.25e6 \
--tx_subdev "A:0"

'''N320/N321'''

This example will test one full-duplex stream using "RF0/A:0", at a rate of 31.25 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.20.2,master_clock_rate=250e6" \
--duration 60 \
--channels "0" \
--rx_rate 31.25e6 \
--rx_subdev "A:0" \
--tx_rate 31.25e6 \
--tx_subdev "A:0"

'''N310'''

This example will test four full-duplex streams at 30.72 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.20.2,master_clock_rate=122.88e6" \
--duration 60 \
--channels "0,1,2,3" \
--rx_rate 30.72e6 \
--rx_subdev "A:0 A:1 B:0 B:1" \
--tx_rate 30.72e6 \
--tx_subdev "A:0 A:1 B:0 B:1"

'''N320/N321'''

This example will test two full-duplex streams at 30.72 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.20.2,master_clock_rate=245.76e6" \
--duration 60 \
--channels "0,1,2,3" \
--rx_rate 30.72e6 \
--rx_subdev "A:0 B:0" \
--tx_rate 30.72e6 \
--tx_subdev "A:0 B:0"

====Dual 10 Gb Interface====
NOTE: This example requires the <code>XG</code> FPGA image to be loaded.

'''N310'''

This example will test four full-duplex streams at 62.5 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.10.2,second_addr=192.168.20.2,master_clock_rate=125e6" \
--duration 60 \
--channels "0,1,2,3" \
--rx_rate 62.5e6 \
--rx_subdev "A:0 A:1 B:0 B:1" \
--tx_rate 62.5e6 \
--tx_subdev "A:0 A:1 B:0 B:1"

'''N320/N321'''

This example will test two full-duplex streams at 62.5 MS/s, for 60 seconds:

/usr/local/lib/uhd/examples/benchmark_rate \
--args "type=n3xx,mgmt_addr=192.168.1.151,addr=192.168.10.2,second_addr=192.168.20.2,master_clock_rate=250e6" \
--duration 60 \
--channels "0,1,2,3" \
--rx_rate 62.5e6 \
--rx_subdev "A:0 B:0" \
--tx_rate 62.5e6 \
--tx_subdev "A:0 B:0"

==USRP N3xx Device Specific Operations==

===White Rabbit Ethernet-Based Synchronization===
* [[Using Ethernet-Based Synchronization on the USRP™ N3xx Devices]]

===N320/N321===
* [[USRP N320/N321 LO Distribution]]
* [[5G NR EVM Measurements with the USRP N320/N321]]

===Turning the Device Off/On===
To avoid damaging the file system and causing any corruption, do not turn the device off with the power button without first shutting down the system. Use this command to cleanly and properly shut the system down:

shutdown -h now

===Enable Auto Booting===
Auto booting of the N3xx when power is applied can be configured by enabling the flag on the device's EEPROM with the following command:

eeprom-set-flags 0x1

===Default Password===
The default user is <code>root</code> and the password is empty (no password).

It is recommended to update the <code>root</code> password, which can be done with the command <code>passwd</code>:

Example Output:

root@ni-n3xx-serial:~# passwd
Changing password for root
New password:
Re-enter new password:
passwd: password changed.

==Technical Support and Community Knowledge Base==
Technical support for USRP hardware is available through email only. If the product arrived in a nonfunctional state or you require technical assistance, please contact [mailto:support@ettus.com support@ettus.com]. Please allow 24 to 48 hours for response by email, depending on holidays and weekends, although we are often able to reply more quickly than that.

We also recommend that you subscribe to the community mailing lists. The mailing lists have a responsive and knowledgeable community of hundreds of developers and technical users who are located around the world. When you join the community, you will be connected to this group of people who can help you learn about SDR and respond to your technical and specific questions. Often your question can be answered quickly on the mailing lists. Each mailing list also provides an archive of all past conversations and discussions going back many years. Your question or problem may have already been addressed before, and a relevant or helpful solution may already exist in the archive.

Discussions involving the USRP hardware and the UHD software itself are best addressed through the '''usrp-users''' mailing list at [http://usrp-users.ettus.com http://usrp-users.ettus.com].

Discussions involving the use of [http://gnuradio.org/ GNU Radio] with USRP hardware and UHD software are best addressed through the '''discuss-gnuradio''' mailing list at [https://lists.gnu.org/mailman/listinfo/discussgnuradio https://lists.gnu.org/mailman/listinfo/discussgnuradio].

Discussions involving the use of [http://openbts.org/ OpenBTS®] with USRP hardware and UHD software are best addressed through the '''openbts-discuss''' mailing list at [https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss https://lists.sourceforge.net/lists/listinfo/openbtsdiscuss].

The support page on our website is located at [https://www.ettus.com/support https://www.ettus.com/support]. The Knowledge Base is located at [https://kb.ettus.com https://kb.ettus.com].

==Legal Considerations==
Every country has laws governing the transmission and reception of radio signals. Users are solely responsible for insuring they use their USRP system in compliance with all applicable laws and regulations. Before attempting to transmit and/or receive on any frequency, we recommend that you determine what licenses may be required and what restrictions may apply.

*NOTE: This USRP product is a piece of test equipment.

==Sales and Ordering Support==
If you have any non-technical questions related to your order, then please contact us by email at [mailto:orders@ettus.com orders@ettus.com], or by phone at +14086106399 (Monday-Friday, 8 AM - 5 PM, Pacific Time). Please be sure to include your order number and the serial number of your USRP.

==Terms and Conditions of Sale==
Terms and conditions of sale can be accessed online at the following link: http://www.ettus.com/legal/terms-and-conditions-of-sale

[[Category:Getting Started Guides]]
[[Category:N300]]
[[Category:N310]]

[[Category:N320]]

[[Category:N321]]

Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on Linux

2022-02-04T14:33:49Z

MartinAnderseck: Removed the revision history from the page itself. The history can be checked much better in the wiki history functionality.

==Application Note Number==
'''AN-445'''

==Abstract==
This Application Note provides a comprehensive guide for building, installing, and maintaining the open-source toolchain for the USRP (UHD and GNU Radio) from source code on the Linux platform. The Ubuntu and Fedora distributions are specifically discussed. Several other alternate installation methods are also discussed.

http://files.ettus.com/manual/page_build_guide.html#build_instructions_unix

==UHD on Linux==

UHD is fully supported on Linux, using the GCC compiler, and should work on most major Linux distributions.

==Devices==
This document applies only to the USRP X300, X310, B200, B210, B200mini, N200, N210 devices. The E310 and E312 devices are embedded devices, and are fundamentally different from the other non-embedded USRP devices, and are not addressed by this document.

==Install Linux==

If you already have a recent version of Linux installed, then you may be able to skip this section. If you are starting from scratch, or simply want to start with a fresh new installation of Linux, then please follow the instructions and recommendations in this section.

We suggest that you use either Ubuntu 16.04.5, Ubuntu 18.04, Ubuntu 18.10, Fedora 27, 28, 29, and that you use a 64-bit architecture, not a 32-bit architecture. There are several re-spins of Ubuntu, such as Xubuntu, Lubuntu, Kubuntu, Linux Mint, all of which should also work. For the purposes of this document, these re-spins can be considered equivalent. Both Ubuntu and Fedora are known to work well with UHD and GNU Radio.

Download and install Ubuntu, Xubuntu, Linux Mint, or Fedora from the links below. Download the appropriate ISO image, and write it to a USB flash drive. Be sure to verify that the ISO file was not corrupted during the download process by checking the MD5 and/or SHA1 hash.

* [http://www.ubuntu.com/download/desktop Ubuntu download page]
* [http://www.xubuntu.org/getxubuntu/ Xubuntu download page]
* [https://www.linuxmint.com/download.php Linux Mint download page]
* [https://getfedora.org/en/workstation/download/ Fedora download page]

You can learn more about Ubuntu, Xubuntu, Linux Mint, and Fedora at the links below.

* [https://en.wikipedia.org/wiki/Ubuntu_%28operating_system%29 Wikipedia article on Ubuntu]
* [https://en.wikipedia.org/wiki/Xubuntu Wikipedia article on Xubuntu]
* [https://en.wikipedia.org/wiki/Linux_Mint Wikipedia article on Linux Mint]
* [https://en.wikipedia.org/wiki/Fedora_%28operating_system%29 Wikipedia article on Fedora]

There are many tools for writing an ISO image to a USB flash drive. In Linux, you can use the "dd" utility, or the UNetbootin utility. On Ubuntu systems, there is also the Startup Disk Creator utility as well.

* [http://unetbootin.sourceforge.net/ UNetbootin homepage]
* [http://en.wikipedia.org/wiki/UNetbootin Wikipedia article on UNetbootin]

* [https://launchpad.net/usb-creator Startup Disk Creator homepage]
* [https://en.wikipedia.org/wiki/Startup_Disk_Creator Wikipedia article on Startup Disk Creator]
* [http://www.ubuntu.com/download/desktop/create-a-usb-stick-on-ubuntu Article about Startup Disk Creator]

Be sure to use a USB flash drive with at least 8 GB capacity, and use a USB 3.0 flash drive, not a USB 2.0 flash drive. If you use a slower USB 2.0 flash drive, then the install process will take significantly longer.

==Update and Install dependencies==

Before building UHD and GNU Radio, you need to make sure that all the dependencies are first installed.

However, before installing any dependencies, you should first make sure that all the packages that are already installed on your system are up-to-date. You can do this from a GUI, or from the command-line, as shown below.

On Ubuntu systems, run:

sudo apt-get update

On Fedora 21 systems, run:

sudo yum update

On Fedora 22, 23, 24 and 25 systems, run:

sudo dnf update

Once the system has been updated, then install the required dependencies for UHD and GNU Radio.

On Ubuntu 20.04 systems, run:

sudo apt-get -y install autoconf automake build-essential ccache cmake cpufrequtils doxygen ethtool fort77 g++ gir1.2-gtk-3.0 git gobject-introspection gpsd gpsd-clients inetutils-tools libasound2-dev libboost-all-dev libcomedi-dev libcppunit-dev libfftw3-bin libfftw3-dev libfftw3-doc libfontconfig1-dev libgmp-dev libgps-dev libgsl-dev liblog4cpp5-dev libncurses5 libncurses5-dev libpulse-dev libqt5opengl5-dev libqwt-qt5-dev libsdl1.2-dev libtool libudev-dev libusb-1.0-0 libusb-1.0-0-dev libusb-dev libxi-dev libxrender-dev libzmq3-dev libzmq5 ncurses-bin python3-cheetah python3-click python3-click-plugins python3-click-threading python3-dev python3-docutils python3-gi python3-gi-cairo python3-gps python3-lxml python3-mako python3-numpy python3-numpy-dbg python3-opengl python3-pyqt5 python3-requests python3-scipy python3-setuptools python3-six python3-sphinx python3-yaml python3-zmq python3-ruamel.yaml swig wget

On Ubuntu 18.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.14-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses6-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwtplot3d-qt5-dev pyqt4-dev-tools python-qwt5-qt4 cmake git wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq libqwt-dev libqwt6abi1 python-six libgps-dev libgps23 gpsd gpsd-clients python-gps python-setuptools

On Ubuntu 18.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.14-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwtplot3d-qt5-dev pyqt4-dev-tools python-qwt5-qt4 cmake git wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq libqwt-dev libqwt6abi1 python-six libgps-dev libgps23 gpsd gpsd-clients python-gps python-setuptools

On Ubuntu 17.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0v5 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git-core libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq python-setuptools

On Ubuntu 16.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0v5 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git-core libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq-dev libzmq1 python-requests python-sphinx libcomedi-dev python-zmq python-setuptools

On Ubuntu 15.04 and 15.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-1.13-0v5 libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk2.8 git-core libqt4-dev python-numpy ccache python-opengl libgsl0-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq-dev libzmq1 python-requests python-sphinx libcomedi-dev python-zmq python-setuptools

On Ubuntu 14.04 and 14.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk2.8 git-core libqt4-dev python-numpy ccache python-opengl libgsl0-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq1 libzmq-dev python-requests python-sphinx libcomedi-dev python-setuptools

On Fedora 21 systems, run:

sudo yum -y groupinstall "Engineering and Scientific" "Development Tools" "Software Development Tools" "C Development Tools and Libraries"

sudo yum -y install fftw-devel cppunit-devel wxPython-devel boost-devel alsa-lib-devel numpy gsl-devel python-devel pygsl python-cheetah python-mako python-lxml PyOpenGL qt-devel qt qt4 qt4-devel PyQt4-devel qwt-devel qwtplot3d-qt4-devel libusbx-devel cmake git wget python-docutils cppzmq-devel PyQwt PyQwt-devel qwt-devel gtk2-engines xmlrpc-c-"*" tkinter orc orc-devel python-sphinx SDL-devel swig zeromq2-devel python-zmq comedilib comedilib-devel thrift-devel python-thrift scipy zeromq zeromq-devel

On Fedora 22, 23, 24 and 25 systems, run:

sudo dnf -y groupinstall "Engineering and Scientific" "Development Tools" "C Development Tools and Libraries"

sudo dnf -y install fftw-devel cppunit-devel wxPython-devel boost-devel alsa-lib-devel numpy gsl-devel python-devel pygsl python-cheetah python-mako python-lxml PyOpenGL qt-devel PyQt4-devel qwt-devel qwtplot3d-qt4-devel libusbx-devel cmake python-docutils PyQwt PyQwt-devel gtk2-engines xmlrpc-c-"*" tkinter orc-devel python-sphinx SDL-devel swig perl-ZMQ-LibZMQ2 perl-ZMQ-LibZMQ2 zeromq zeromq-devel python-requests gcc-c++ doxygen zeromq-ada-devel cppzmq-devel perl-ZeroMQ amavisd-new-zeromq amavisd-new-snmp-zeromq php-zmq python-zmq czmq uwsgi-logger-zeromq comedilib comedilib-devel pygtk2 ncurses-"*" thrift-devel python-thrift scipy

After installing the dependencies, you should reboot the system.

If the installation of the dependencies completes without any errors, then you can proceed to build and install UHD and GNU Radio.

==Building and installing UHD from source code==

UHD is open-source, and is hosted on GitHub. You can browse the code online at the link below, which points to version 3.14.0.0, which is the the latest release at the time of this writing.

* [https://github.com/EttusResearch/uhd/tree/v3.14.0.0 UHD repository on GitHub]

There are several good reasons to build GNU Radio from source code, especially for doing development and prototyping. It it enables an easy way to customize the location of the installation, and to install multiple UHD versions in parallel, and switch between them. It also provides much more flexibility in upgrading and downgrading versions, and allows the user to modify the code and create customized versions, which could possibly include a patch or other bug-fix.

To build UHD from source code, clone the GitHub repository, check out a branch or tagged release of the repository, and build and install. Please follow the steps below. Make sure that no USRP device is connected to the system at this point.

First, make a folder to hold the repository.

cd $HOME
mkdir workarea
cd workarea

Next, clone the repository and change into the cloned directory.

git clone <nowiki>https://github.com/EttusResearch/uhd</nowiki>
cd uhd

Next, checkout the desired UHD version. You can get a full listing of tagged releases by running the command:

git tag -l

''Example truncated output of <code>git tag -l</code>:''

<pre>
$ git tag -l
...
release_003_009_004
release_003_009_005
release_003_010_000_000
...
</pre>

'''Note''': As of UHD Version 3.10.0.0, the versioning scheme has changed to be a quadruplet format. Each element and version will follow the format of: '''Major.API.ABI.Patch'''. Additional details on this versioning change can be found [https://files.ettus.com/manual/page_semver.html here].

After identifying the version and corresponding release tag you need, check it out:

# Example: For UHD 3.9.5:
git checkout release_003_009_005

# Example: For UHD 3.14.0.0
git checkout v3.14.0.0

Next, create a build folder within the repository.

cd host
mkdir build
cd build

Next, invoke CMake.

cmake ..

'''Note''': if the shell <code>PATH</code> is set such that <code>/bin</code> comes before <code>/usr/bin</code>, then this step is likely to fail because cmake will set the <code>FIND_ROOT_PATH</code> to <code>/</code> and this setting will fail as a prefix for Boost headers or libraries. The cmake output will include messages such as

-- Boost include directories: /include
-- Boost library directories: /lib/x86_64-linux-gnu

and

CMake Error in lib/CMakeLists.txt:
Imported target "Boost::chrono" includes non-existent path
"/include"
in its INTERFACE_INCLUDE_DIRECTORIES. Possible reasons include:
* The path was deleted, renamed, or moved to another location.
* An install or uninstall procedure did not complete successfully.
* The installation package was faulty and references files it does not provide.

One of the following 3 options should fix this situation:

1. <code>/usr/bin/cmake ..</code>
2. <code>PATH=/usr/bin:$PATH cmake ..</code>
3. <code>cmake -DCMAKE_FIND_ROOT_PATH=/usr ..</code>

Once the cmake command succeeds without errors, build UHD.

make

Next, you can optionally run some basic tests to verify that the build process completed properly.

make test

Next, install UHD, using the default install prefix, which will install UHD under the /usr/local/lib folder. You need to run this as root due to the permissions on that folder.

sudo make install

Next, update the system's shared library cache.

sudo ldconfig

Finally, make sure that the <code>LD_LIBRARY_PATH</code> environment variable is defined and includes the folder under which UHD was installed. Most commonly, you can add the line below to the end of your <code>$HOME/.bashrc</code> file:

export LD_LIBRARY_PATH=/usr/local/lib

On Fedora 22/23/24/25 you will need to set the <code>LD_LIBRARY_PATH</code> to <code>/usr/local/lib64</code>.

export LD_LIBRARY_PATH=/usr/local/lib64

If the <code>LD_LIBRARY_PATH</code> environment variable is already defined with other folders in your <code>$HOME/.bashrc</code> file, then add the line below to the end of your <code>$HOME/.bashrc</code> file to preserve the current settings.

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

For Fedora 21/22/23/24/25

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib64

For this change to take effect, you will need to close the current terminal window, and open a new terminal.

At this point, UHD should be installed and ready to use. You can quickly test this, with no USRP device attached, by running <code>uhd_find_devices</code>. You should see something similar to the following.

<pre>
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

No UHD Devices Found
</pre>

===Downloading the UHD FPGA Images===
You can now download the UHD FPGA Images for this installation. This can be done by running the command <code>uhd_images_downloader</code>.

$ sudo uhd_images_downloader

Note: Since this installation is being installed to a system level directory (e.g. <code>/usr/local</code>), the <code>uhd_images_downloader</code> command requires <code>sudo</code> privileges.

Example ouput for UHD 3.13.3.0:

<pre>
$ sudo uhd_images_downloader
Images destination: /usr/local/share/uhd/images
Downloading images from: http://files.ettus.com/binaries/images/uhd-images_003.010.003.000-release.zip
Downloading images to: /tmp/tmpm46JDg/uhd-images_003.010.003.000-release.zip
57009 kB / 57009 kB (100%)

Images successfully installed to: /usr/local/share/uhd/images
</pre>

Example output for UHD 3.13:

<pre>
$ sudo uhd_images_downloader
[INFO] Images destination: /usr/local/share/uhd/images
[INFO] No inventory file found at /usr/local/share/uhd/images/inventory.json. Creating an empty one.
00006 kB / 00006 kB (100%) usrp1_b100_fw_default-g6bea23d.zip
19484 kB / 19484 kB (100%) x3xx_x310_fpga_default-g494ae8bb.zip
02757 kB / 02757 kB (100%) usrp2_n210_fpga_default-g6bea23d.zip
02109 kB / 02109 kB (100%) n230_n230_fpga_default-g494ae8bb.zip
00522 kB / 00522 kB (100%) usrp1_b100_fpga_default-g6bea23d.zip
00474 kB / 00474 kB (100%) b2xx_b200_fpga_default-g494ae8bb.zip
02415 kB / 02415 kB (100%) usrp2_n200_fpga_default-g6bea23d.zip
05920 kB / 05920 kB (100%) e3xx_e320_fpga_default-g494ae8bb.zip
15883 kB / 15883 kB (100%) n3xx_n310_fpga_default-g494ae8bb.zip
00506 kB / 00506 kB (100%) b2xx_b205mini_fpga_default-g494ae8bb.zip
18676 kB / 18676 kB (100%) x3xx_x300_fpga_default-g494ae8bb.zip
00017 kB / 00017 kB (100%) octoclock_octoclock_fw_default-g14000041.zip
04839 kB / 04839 kB (100%) usb_common_windrv_default-g14000041.zip
00007 kB / 00007 kB (100%) usrp2_usrp2_fw_default-g6bea23d.zip
00009 kB / 00009 kB (100%) usrp2_n200_fw_default-g6bea23d.zip
00450 kB / 00450 kB (100%) usrp2_usrp2_fpga_default-g6bea23d.zip
00142 kB / 00142 kB (100%) b2xx_common_fw_default-g3ff4186b.zip
00460 kB / 00460 kB (100%) b2xx_b200mini_fpga_default-g494ae8bb.zip
00319 kB / 00319 kB (100%) usrp1_usrp1_fpga_default-g6bea23d.zip
00009 kB / 00009 kB (100%) usrp2_n210_fw_default-g6bea23d.zip
11537 kB / 11537 kB (100%) n3xx_n300_fpga_default-g494ae8bb.zip
05349 kB / 05349 kB (100%) e3xx_e310_fpga_default-g494ae8bb.zip
00866 kB / 00866 kB (100%) b2xx_b210_fpga_default-g494ae8bb.zip
[INFO] Images download complete.

</pre>

==Building and installing GNU Radio from source code==

As with UHD, GNU Radio is open-source and is hosted on GitHub. You can browse the code online at the link below, which points to version <code>v3.7.13.4</code>, which is the the latest release at the time of this writing.

* [https://github.com/gnuradio/gnuradio/tree/v3.7.13.4 GNU Radio repository on GitHub]

Note: GNU Radio is currently transitioning from major branches of 3.7.x.x to 3.8.x.x. It is generally recommend at this time to use either the <code>v3.7.13.4</code> or <code>maint-3.7</code> branch of GNU Radio. The <code>master</code> branch includes many major changes such as converting to use Python 3 and may be unstable.

As with UHD, there are several good reasons to build GNU Radio from source code, especially for doing development and prototyping. It it enables an easy way to customize the location of the installation, and to install multiple GNU Radio versions in parallel, and switch between them. It also provides much more flexibility in upgrading and downgrading versions, and allows the user to modify the code and create customized versions, which could possibly include a patch or other bug-fix.

Similar to the process for UHD, to build GNU Radio from source code, clone the GitHub repository, check out a branch or tagged release of the repository, and build and install. Please follow the steps below. Make sure that no USRP device is connected to the system at this point.

First, make a folder to hold the repository.

cd $HOME
cd workarea

Next, clone the repository.

git clone --recursive <nowiki>https://github.com/gnuradio/gnuradio</nowiki>

Next, go into the repository and check out the desired GNU Radio version.

cd gnuradio

To checkout the <code>v3.7.13.4</code> branch:

git checkout v3.7.13.4

Or to checkout the <code>maint-3.7</code> branch:

git checkout maint-3.7

Next, update the submodules:

git submodule update --init --recursive

Next, create a build folder within the repository, invoke CMake, and build GNU Radio:

mkdir build
cd build
cmake ../
make

Next, you can optionally run some basic tests to verify that the build process completed properly.

make test

Next, install GNU Radio, using the default install prefix, which will install GNU Radio under the /usr/local/lib folder. You need to run this as root due to the permissions on that folder.

sudo make install

Finally, update the system's shared library cache.

sudo ldconfig

At this point, GNU Radio should be installed and ready to use. You can quickly test this, with no USRP device attached, by running the following quick tests.

gnuradio-config-info --version
gnuradio-config-info --prefix
gnuradio-config-info --enabled-components

There is a simple flowgraph that you can run that does not require any USRP hardware. It's called the dialtone test, and it produces a PSTN dial tone on the computer's speakers. Running it verifies that all the libraries can be found, and that the GNU Radio run-time is working.

python $HOME/workarea/gnuradio/gr-audio/examples/python/dial_tone.py

You can try launching the GNU Radio Companion (GRC) tool, a visual tool for building and running GNU Radio flowgraphs.

gnuradio-companion

If "gnuradio-companion" does not start and complains about the <code>PYTHONPATH</code> environment variable, then you may have to set this in your <code>$HOME/.bashrc</code> file, as shown below.

export PYTHONPATH=/usr/local/lib/python2.7/dist-packages

On Fedora 21/22/23/24, the <code>PYTHONPATH</code> environment variable will need to be set to:

export PYTHONPATH=/usr/lib/python2.7/site-packages:/usr/local/lib64/python2.7/site-packages/

==Configuring USB==

On Linux, udev handles USB plug and unplug events. The following commands install a udev rule so that non-root users may access the device. This step is only necessary for devices that use USB to connect to the host computer, such as the B200, B210, and B200mini. This setting should take effect immediately and does not require a reboot or logout/login. Be sure that no USRP device is connected via USB when running these commands.

cd $HOME/workarea/uhd/host/utils
sudo cp uhd-usrp.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

==Configuring Ethernet==

For USRP devices that use Ethernet to connect to the host computer, such as the N200, N210, X300, X310, set a static IP address for your system of 192.168.10.1, with a netmask of 255.255.255.0. The default IP address of the USRP is 192.168.10.2, with a netmask of 255.255.255.0. You should probably set the IP address using the graphical Network Manager. If you set the IP address from the command line with <code>ifconfig</code>, Network Manager will probably overwrite these settings.

==Connect the USRP==

The installation of UHD and GNU Radio should now be complete. At this point, connect the USRP to the host computer.

If the interface is Ethernet, then open a terminal window, and try to ping the USRP with "ping 192.168.10.2". The USRP should respond to the ping requests.

If the interface is USB, then open a terminal window, and run "<code>lsusb</code>". You should see the USRP listed on the USB bus with a VID of <code>2500</code> and PID of <code>0020</code>, <code>0021</code>, <code>0022</code>, for B200, B210, B200mini, respectively.

Also try running "<code>uhd_find_devices</code>" and "<code>uhd_usrp_probe</code>".

==Thread priority scheduling==

When UHD 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.

<pre>
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
</pre>

To address this issue, non-privileged (non-root) users need to be given special permission to change the scheduling priority. This can be enabled by creating a group <code>usrp</code>, adding your user to it, and then appending the line <code>@usrp - rtprio 99</code> to the file <code>/etc/security/limits.conf</code>.

sudo groupadd usrp
sudo usermod -aG usrp $USER

Then add the line below to end of the file <code>/etc/security/limits.conf</code>:

@usrp - rtprio 99

You must 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 <code>/etc/group</code> file.

There is further documentation about this in the User Manual at the link below.

* [http://files.ettus.com/manual/page_general.html#general_threading_prio Threading Notes section of the User Manual]

[[Category:Application Notes]]

RFNoC 4 Migration Guide

2021-11-19T10:06:38Z

MartinAnderseck: /* GNU Radio 3.8 */ Added link to official GNU Radio build instructions

=Abstract=

The UHD 4.0 release includes a major upgrade to the RFNoC framework called RFNoC 4. This article is a guide to aid users in migrating their existing RFNoC blocks from RFNoC 3 to RFNoC 4. The RFNoC Block Development Environment section provides guidance on how to setup an environment for developing out-of-tree RFNoC blocks in RFNoC 4. The UHD, FPGA, GNU Radio Migration sections provide general information on topics that most users will encounter when migrating their blocks. Finally, an equivalent RFNoC 3 and RFNoC 4 implementation of a digital gain RFNoC Block has been provided as a reference.

=Prerequisites=

===Dependencies (Ubuntu 20.04)===
sudo apt-get install autoconf automake build-essential ccache cmake cpufrequtils doxygen ethtool \
g++ git inetutils-tools libboost-all-dev libncurses5 libncurses5-dev libusb-1.0-0 libusb-1.0-0-dev \
libusb-dev python3-dev python3-mako python3-numpy python3-requests python3-scipy python3-setuptools \
python3-ruamel.yaml libtinfo5 libncurses5

===Vivado 2019.1 Design Edition===

Please reference to Xilinx (xilinx.com) for installation instructions.

''Note: The dependencies step above included installing libtinfo5 libncurses5, which is a workaround for getting Vivado 2019.1 to run on Ubuntu 20.04''

===UHD 4.0===
git clone --branch UHD-4.0 https://github.com/ettusresearch/uhd.git uhd
mkdir uhd/host/build; cd uhd/host/build
cmake ..
make
sudo make install

===GNU Radio 3.8===
'' Note: If your design does not use GNU Radio, then installing GNU Radio and gr-ettus is not required ''

git clone --branch maint-3.8 --recursive https://github.com/gnuradio/gnuradio.git gnuradio
mkdir gnuradio/build; cd gnuradio/build;
cmake ..
make
sudo make install

Please refer to the [https://wiki.gnuradio.org/index.php/UbuntuInstall GNU Radio Build Instructions] for dependencies and a more detailed description.

===gr-ettus===
git clone --branch maint-3.8-uhd4.0 https://github.com/ettusresearch/gr-ettus.git gr-ettus
mkdir gr-ettus/build; cd gr-ettus/build;
cmake -DENABLE_QT=True ..
make
sudo make install

=RFNoC Block Development Environment=

Two options exist for developing RFNoC blocks depending on whether the your RFNoC block integrates with GNU Radio in an out-of-tree module or if it only uses UHD’s C++ API in a standalone application. The sections below outline how to setup the development environment for each scenario.

===Migrating a GNU Radio Out-of-Tree Module===

The tool rfnocmodtool automates the process of creating GNU Radio out-of-tree (OOT) modules that also have support for RFNoC blocks. This tool is part of gr-ettus and it has been ported to RFNoC 4.

Due to changes in almost every source file, it is recommended to use rfnocmodtool to generate a new RFNoC block from scratch and then update the generated “skeleton” files.

====Creating a RFNoC Block with rfnocmodtool====

The following steps show how to create an OOT module called ''example'' and RFNoC block called ''gain'' using rfnocmodtool. The naming is only for example purposes.

rfnocmodtool newmod
Name of the new module: '''example'''

cd rfnoc-tutorial
rfnocmodtool add
Enter name of block/code (without module name prefix): '''gain'''
Enter valid argument list, including default arguments: ''(leave blank)''
Add Python QA code? [y/N] '''N'''
Add C++ QA code? [y/N] '''N'''
Block NoC ID (Hexadecimal): ''(Enter Noc ID of your block)''
Skip Block Controllers Generation? [UHD block ctrl files] [y/N] '''N'''
Skip Block interface files Generation? [GRC block ctrl files] [y/N] '''N'''

''Note: Noc IDs have been reduced from 64-bits in RFNoC 3 to 32-bits in RFNoC 4''

The following are the relevant files that need to be updated when migrating your RFNoC Block.

rfnoc-example/
grc/
example_gain.block.yml – RFNoC Block GNU Radio Companion YAML file
examples/
gain.grc – Example flowgraph using gain RFNoC Block
include/tutorial/
gain.h – GNU Radio block C++ header
gain_block_ctrl.hpp – RFNoC Block Controller C++ header
lib/
gain_impl.cc – GNU Radio block C++ source
gain_impl.h – GNU Radio block C++ header
gain_block_ctrl_impl.cpp – RFNoC Block Controller C++ source
rfnoc/blocks/
gain.yml – RFNoC Block Description YAML file
rfnoc/fpga/rfnoc_block_gain
noc_shell_gain.v – RFNoC Block Noc Shell Verilog Source
rfnoc_block_gain.v – RFNoC Block Verilog Source
rfnoc_block_gain_tb.v – RFNoC Block Testbench
rfnoc/icores
gain_x310_rfnoc_image_core.yml – Image Core YAML file with gain block

====Building OOT module====

cd rfnoc-tutorial
mkdir build; cd build
cmake -DUHD_FPGA_DIR=''(path to uhd/fpga directory)'' ..
make
sudo make install

====Running a testbench====
CMake automatically creates makefile targets to run the generated testbench code for each added RFNoC block. For example, here is how to run the gain block testbench:

cd rfnoc-tutorial/build
make rfnoc_block_gain_tb

====Building a FPGA image====
CMake automatically creates makefile targets to build FPGA images using the generated image core yaml files found in rfnoc/icore. Every RFNoC block created by rfnocmodtool automatically has an image core yaml file generated in that directory. For example, here is how to build an FPGA image using the image core yaml file generated for the gain block:

cd rfnoc-tutorial/build
make gain_x310_rfnoc_image_core

===Migrating a Standalone UHD C++ Application===

For applications that only use the UHD API, an example out-of-tree (UHD source tree) RFNoC block exists called rfnoc-example. It is located in the UHD source at uhd/host/examples/rfnoc-example. This directory can be copied outside of the UHD source tree and used a starting point to migrate your RFNoC block.

The following are the relevant files that need to be updated when migrating your RFNoC Block.

rfnoc-example/
apps/
init_gain_block.cpp – Example C++ application testing gain block
blocks/
gain.yml – RFNoC Block Description YAML file
fpga/rfnoc_block_gain
noc_shell_gain.v – RFNoC Block Noc Shell Verilog Source
rfnoc_block_gain.v – RFNoC Block Verilog Source
rfnoc_block_gain_tb.v – RFNoC Block Testbench
icores/
x310_rfnoc_image_core.yml – Example Image Core YAML file
include/rfnoc/example
gain_block_control.hpp – RFNoC Block Controller C++ header
lib/
gain_block_control.cpp – RFNoC Block Controller C++ source

====Building rfnoc-example====

cd rfnoc-example
mkdir build; cd build
cmake ..
make
sudo make install

====Running a testbench====
CMake automatically creates makefile targets to run RFNoC Block testbench simulations. For every RFNoC block subdirectory listed in the CMakeLists.txt file in the rfnoc-example/fpga directory, a target with the RFNoC block name appended with “_tb” is added as a makefile target. For example, here is how to run the gain RFNoC block testbench:

cd rfnoc-example/build
make rfnoc_block_gain_tb

====Building a FPGA image====
CMake automatically creates makefile targets to build a FPGA image for each image core yaml file listed in the CMakeLists.txt file in the rfnoc-example/icore directory. Each image core yaml file must be listed in the CMakeLists.txt. For example, here is how to build an FPGA image using the image core yaml file generated for the gain block:

cd rfnoc-tutorial/build
make gain_x310_rfnoc_image_core

=Example RFNoC 3 to RFNoC 4 Block Migration=

This ZIP archive, [[File:migration_example.zip]], contains equivalent RFNoC 3 and RFNoC 4 versions of a digital gain RFNoC Block. The following sections will refer to files in this archive to show how the file structure changes when migrating from RFNoC 3 to RFNoC 4.

=UHD Software Migration=

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| Block Description || rfnoc/blocks/gain.xml || lib/gain_block_ctrl_impl.cpp include/example/gain_block_ctrl.hpp
|-
| Block Controller || rfnoc/blocks/gain.yml || lib/gain_block_ctrl_impl.cpp include/example/gain_block_ctrl.hpp
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===Noc Script XML Replaced by Block Description YAML===

RFNoC 3 used Noc Script XML, a domain specific language, to describe the configuration of a RFNoC block: the Noc ID, register names and addresses, args for writing to the registers, and the input/output ports.

RFNoC 4 replaces the Noc Script XML file with an easier to read and edit Block Description YAML file format. From a high level, the Block Description YAML file serves a similar function as the Noc Script XML file, with some similarities and key differences outlined in table below:

{| class="wikitable"
! Item || Noc Script XML || Block Descript YAML || RFNoC 4 Notes
|-
| Block Name
||
<name>gain</name>
||
module_name: gain
||
|-
| Noc ID
||
<id>B160000000000000</id>
||
noc_id: 0xB16
||
Noc ID are limited to 32-bits
|-
| Registers
||
<registers>
<setreg>
<name>GAIN</name>
<address>128</address>
</setreg>
</registers>
||
N/A
||
Registers must be defined in the Block Controller
|-
| Arguments
||
<args>
<arg>
<name>gain</name>
<type>int</type>
...
</arg>
</args>
||
N/A
||
Args are implemented with properties in the Block Controller
|-
| Data Ports
||
<ports>
<sink>
<name>in</name>
</sink>
<source>
<name>out</name>
</source>
</ports>
||
data:
fpga_iface: axis_pyld_ctxt
clk_domain: rfnoc_chdr
inputs:
in:
...
outputs:
out:
...
||
|-
| Control Ports
||
N/A
||
control:
sw_iface: nocscript
fpga_iface: ctrlport
interface_direction: slave
...
||
|-
| Clocking
||
N/A
||
clocks:
- name: rfnoc_chdr
freq: "[]"
- name: rfnoc_ctrl
freq: "[]"
||
|}

''Note: For a more detailed description of the RFNoC 4 Block Description YAML syntax and the various options, see the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].''

===RFNoC API Changes===

Much of the user facing RFNoC software API has not changed or remains very similar between RFNoC 3 and RFNoC 4. The table below outlines some of the notable differences:

{| class="wikitable"
! RFNoC 3 || RFNoC 4 || RFNoC 4 Notes
|-
|
usrp = uhd::device3::make(...)
||
graph = uhd::rfnoc::rfnoc_graph::make()
||
No longer need to create a device3 object
|-
|
usrp->get_block_ctrl(...)
||
graph->get_block(...)
||
Rename
|-
|
N/A
||
graph->enumerate_static_connections()
||
Used to check static connections, usually for detecting hwen a DDC or DUC is statically connected to the radio and requires setting the sample
|-
|
usrp->get_tx_streamer(...)
||
graph->create_tx_streamer(...)
||
Rename
|-
|
usrp->get_rx_streamer(...)
||
graph->create_rx_streamer(...)
||
Rename
|-
|
N/A
||
graph->commit()
||
Commit graph and run initial checks
|-
|
sr_write(...)
||
regs().poke32(...)
||
Address increments by 4
|-
|
sr_read32(...)
||
regs().peek32(...)
||
Address increments by 4
|-
|
sr_read64(...)
||
regs().poke64(...)
||
Address increments by 8
|-
|
set_arg(...)
||
set_property(...)
||
Block args replaced with block properties concept
|-
|
get_arg(...)
||
get_property(...)
||
Block args replaced with block properties concept
|}

===Block Properties===

In RFNoC 3, RFNoC blocks can have arguments (also known as args) that are used to write user registers. This is implemented in the Noc Script XML in the <args> section.

RFNoC 4 expands and generalizes this concept with block properties: a high-level representation of the state of the block. Zero or more properties can be defined by the user in their RFNoC Block’s Block Controller C++ class. When read or written to, they can trigger a call back to a user defined resolver function. The [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification] provides more details on properties in the “Block Properties” section.

The following shows an example of how to migrate a RFNoC 3 Noc Script XML “arg” based register write to a RFNoC 4 property based implementation in the Block Controller:

====RFNoC 3 Noc Script XML snippet====
<registers>
<setreg>
<name>GAIN</name>
<address>128</address>
</setreg>
</registers>

<args>
<arg>
<name>gain</name>
<type>int</type>
<value>1</value>
<check>GE($gain, 0) AND LE($gain, 32767)</check>
<check_message>Gain must be in the range [0, 32767]</check_message>
<action>SR_WRITE("GAIN", $gain)</action>
</arg>
</args>

====RFNoC 4 Block Controller Class====

// <registers>
// <setreg>
// <name>GAIN</name>
// <address>128</address>
// </setreg>
// </registers>
// Note: In RFNoC 4, register addresses can start at address 0 instead of address 128 as in RFNoC 3.
const uint32_t gain_block_ctrl::REG_GAIN_ADDR = 128;
const uint32_t gain_block_ctrl::REG_GAIN_DEFAULT = 1;

class gain_block_ctrl_impl : public gain_block_ctrl
{
public:
RFNOC_BLOCK_CONSTRUCTOR(gain_block_ctrl)
{
_register_props();
}
private:
void _register_props()
{
register_property(&_user_reg, [this]() {
int user_reg = this->_user_reg.get();
// <check>GE($gain, 0) AND LE($gain, 32767)</check>
// <check_message>Gain must be in the range [0, 32767]</check_message>
if (user_reg < 0 || user_reg > 32767) {
throw uhd::value_error("Size value must be in [0,32767]");
}
// <action>SR_WRITE("GAIN", $gain)</action>
this->regs().poke32(REG_USER_ADDR, user_reg);
});
}

// <name>gain</name>
// <type>int</type>
// <value>1</value>
property_t<int> _user_reg{"gain", REG_USER_DEFAULT, {res_source_info::USER}};
}

As the above shows, writing to a register can be replicated with a property and a resolver function. Of course, the resolver function can also be made much more sophisticated. For additional examples, see the in-tree block controllers in uhd/host/lib/rfnoc.

=FPGA Migration=

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| Block Verilog Code || rfnoc/fpga-src/noc_block_gain.v || rfnoc/fpga/rfnoc_block_gain/rfnoc_block_gain.v
|-
| Block Noc Shell || N/A || rfnoc/fpga/rfnoc_block_gain/noc_shell_gain.v
|-
| Block Testbnech || rfnoc/testbench/noc_block_gain/noc_block_gain_tb.sv || rfnoc/fpga/rfnoc_block_gain/rfnoc_block_gain_tb.sv
|-
| Image Core || N/A || rfnoc/icores/gain_x310_rfnoc_image_core.yml
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===Noc Shell Changes===

RFNoC 4 replaces the highly parameterized RFNoC 3 Noc Shell with a per-block customized Noc Shell generated from the block’s Block Description YAML file. The Noc Shell generated via rfnocmodtool or the existing one in rfnoc-example is acceptable for most blocks that require one input and output data port.

====Generating a Custom Noc Shell====

Some blocks may need multiple data ports or other modifications. This requires editing the Block Description YAML file and then using the Python script rfnoc_create_verilog.py (found in uhd/host/utils/rfnoc_blocktool) to generate a new Noc Shell instance.

The argument “-c” is used to provide the YAML file location. “-d” provides the output destination directory.

''Note: It is suggested to not set the destination directory to your existing RFNoC block code, as the script will automatically overwrite the existing code!''

Example usage:
rfnoc_create_verilog.py -c ./rfnoc-example/rfnoc/blocks/gain.yml -d ./output/

====Changing Noc ID without using rfnoc_create_verilog====

In the generated Noc Shell Verilog code, a block’s Noc ID can be changed by updating the NOC_ID parameter on the ''backend_iface'' module. Make sure this matches the Noc ID in both the Block Description YAML file and Block Controller C++ code.

====Goodbye AXI Wrapper====

The RFNoC 3 version of Noc Shell outputs / accepts CHDR data packets consisting of a header, optional timestamp, and payload on a 64-bit AXI stream bus. Most designs then used a module called AXI Wrapper to handle the conversion between CHDR data packets and sample streams on a 32-bit AXI stream bus. AXI Wrapper also supported SIMPLE_MODE which for some use cases could transparently handle the header portion of the CHDR data packet. Otherwise, the user would need to set the header via m_axis_data_tuser.

In RFNoC 4, Noc Shell has absorbed AXI Wrapper’s functionality. Noc Shell outputs two AXI stream buses per input / output port: a payload and context bus. The payload bus is in most cases identical to AXI Wrapper’s output: a 32-bit stream of samples on an AXI Stream bus with packets delimited by tlast. The context AXI stream bus carries the header, optional timestamp, and optional metadata. If your block used AXI Wrapper’s SIMPLE_MODE, then you can loop the context bus back into Noc Shell. If not, you will need to modify the context bus data. Refer to the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification] for the format and timing diagram of the context bus.

''Important Note: If your block used the AXI Rate Change module, Noc Shell has another data port mode to support this use case called '''axis_data''' that can be set in the Block Descriptor YAML file (see the fpga_iface entry). This mode causes the Noc Shell data ports to look more like AXI Wrapper’s and therefore makes them compatible with AXI Rate Change. See the DDC, DUC, or Keep One in N RFNoC Blocks for an example.''

===Settings Bus replaced by CtrlPort===

CtrlPort replaces the Settings Bus in RFNoC 4. The CtrlPort bus is similar to the Settings Bus with a few key differences. The table below compares the signaling between the two bus formats and provides notes on any differences. Timing diagrams and additional information on the CtrlPort bus is also available in the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].

{| class="wikitable"
! Settings Bus (RFNoC 3) || CtrlPort (RFNoC 4) || RFNoC 4 Notes
|-
| set_stb || ctrlport_reg_wr || Write strobe
|-
| set_addr || ctrlport_req_addr || 20-bits instead of 8-bits, increments by 4 instead of by 1, no reserved addresses (versus addresses 0-127 for Settings Bus)
|-
| set_data || ctrlport_req_data || Write data
|-
| N/A || ctrlport_req_rd || Read strobe equivalent of ctrlport_req_wr
|-
| rb_addr || N/A || CtrlPort uses ctrlport_req_addr for both '''read and write''' addresses
|-
| rb_data || ctrlport_resp_data || Read data, 32-bits instead of 64-bits
|-
| rb_stb || N/A || CtrlPort requires ack strobe for '''reads and writes'''
|}

One additional difference when using CtrlPort is that there is not an equivalent Settings Register module. The bus is simple enough to setup a clocked process to handle reading from and writing to registers. See the Verilog example below:

// Note: Register addresses increment by 4
localparam REG_USER_ADDR = 0; // Address for example user register
localparam REG_USER_DEFAULT = 0; // Default value for user register

reg [31:0] reg_user = REG_USER_DEFAULT;

always @(posedge ctrlport_clk) begin
if (ctrlport_rst) begin
reg_user = REG_USER_DEFAULT;
end else begin
// Default assignment
m_ctrlport_resp_ack <= 0;

// Read user register
if (m_ctrlport_req_rd) begin // Read request
case (m_ctrlport_req_addr)
REG_USER_ADDR: begin
m_ctrlport_resp_ack <= 1;
m_ctrlport_resp_data <= reg_user;
end
endcase
end

// Write user register
if (m_ctrlport_req_wr) begin // Write requst
case (m_ctrlport_req_addr)
REG_USER_ADDR: begin
m_ctrlport_resp_ack <= 1;
reg_user <= m_ctrlport_req_data[31:0];
end
endcase
end
end
end

''Important Note: For blocks that make heavy use of the Settings Bus and/or Settings Registers, there is a CtrlPort to Settings Bus bridge available called '''ctrlport_to_settings_bus'''. See the Keep One In N RFNoC Block for example code on how to interface with it.''

===Testbench Infrastructure===

While RFNoC 4 does overhaul the RFNoC 3 testbench infrastructure API, most of the high level concepts remain the same. The table below outlines some of the commonly used RFNoC 3 functions / code and the RFNoC 4 equivalent.

{| class="wikitable"
! Operation || RFNoC 3 || RFNoC 4
|-
| Setup RFNoC
||
`RFNOC_SIM_INIT(...)
`RFNOC_ADD_BLOCK(...)
`RFNOC_CONNECT(...)
||
RfnocBlockCtrlBfm #(...) blk_ctrl = new(...);
blk_ctrl.connect_master_data_port(...)
blk_ctrl.connect_slave_data_port(...)
''Note: Instantiate one Block Controller BFM per RFNoC Block''
|-
| Setup Test Cases
||
`TEST_CASE_START(...)
`TEST_CASE_DONE(...)
||
test.start_test(...)
test.end_test()
|-
| Register Read
||
tb_streamer.read_reg(...)
||
blk_ctrl.reg_read(...)
|-
| Register Write
||
tb_streamer.write_reg(...)
||
blk_ctrl.reg_write(...)
|-
| Send Data / Samples
||
tb_streamer.send(...)
||
blk_ctrl.send_items(...)
|-
| Receive Data / Samples
||
tb_streamer.recv(...)
||
blk_ctrl.recv_items(...)
|}

===Building FPGA images using Image Core YAML Files===

RFNoC 4 replaces uhd_image_builder, the RFNoC 3 FPGA image building tool, with a new tool called rfnoc_image_builder. This tool produces a FPGA bitstream based on an Image Core YAML file that describes the device configuration (e.g. X310 with dual 10GigE) and included RFNoC blocks along with their connections (both static and dynamic), clocking, and I/O.

Both rfnocmodtool and the UHD in-tree example called rfnoc-example automatically setup make targets to handle running rfnoc_image_builder. If you want to use rfnoc_image_builder directly, more details can be found in the [https://kb.ettus.com/Getting_Started_with_RFNoC_in_UHD_4.0 Getting Started with RFNoC in UHD 4.0].

=GNU Radio Software Migration=

RFNoC 4 supports GNU Radio 3.8 only. Most of your RFNoC Block’s GNU Radio related changes will be due to API differences between GNU Radio 3.7 to 3.8. These changes are outside of the scope of this article. Instead, refer to [https://wiki.gnuradio.org/index.php/GNU_Radio_3.8_OOT_Module_Porting_Guide GNU Radio 3.8 Migration Guide] and [https://wiki.gnuradio.org/index.php/YAML_GRC GNU Radio Companion YAML] sites for more information.

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| GNU Radio Block || lib/gain_impl.cc lib/gain_impl.h include/example/gain.h || lib/gain_impl.cc lib/gain_impl.h include/example/gain.h
|-
| GRC Block Description || grc/gain.xml || grc/gain.yml
|-
| Example GRC Flowgraph || examples/gain.grc || examples/gain.grc
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===RX & TX Streamer Blocks===

When transition between a RFNoC block and a GNU Radio block or vice versa, you must insert either a RX stream or TX streamer block respectively. This differs from RFNoC 3, where a RFNoC block could be directly connected to a GNU Radio block.

[[File:rx_tx_streamer.png|border]]

===Setting RFNoC Block Properties Directly in GNU Radio===

The base class for RFNoC Block’s in GNU Radio have a set of functions that provide a shortcut to getting and setting properties without writing custom class methods. The table below lists the functions.

{| class="wikitable"
! Property Type || Set Property || Get Property
|-
| Integer || set_int_property(...) || get_int_property(...)
|-
| Double || set_double_property(...) || get_double_property(...)
|-
| Bool || set_bool_property(...) || get_bool_property(...)
|-
| String || set_string_property(...) || get_string_property(...)
|-
|}

'''Example code for GNU Radio Companion YAML Block Description file'''
templates:
imports: |-
import example
make: |-
example.gain(
self.rfnoc_graph,
uhd.device_addr(${block_args}),
${device_select},
${instance_select})
self.${id}.set_int_property('gain', ${gain})
callbacks:
- set_int_property('gain', ${gain})

RFNoC 4 Migration Guide

2021-11-19T10:00:16Z

MartinAnderseck: /* Dependencies (Ubuntu 20.04) */ Bringing back libtinfo5 libncurses5, removal was way too quick.

=Abstract=

The UHD 4.0 release includes a major upgrade to the RFNoC framework called RFNoC 4. This article is a guide to aid users in migrating their existing RFNoC blocks from RFNoC 3 to RFNoC 4. The RFNoC Block Development Environment section provides guidance on how to setup an environment for developing out-of-tree RFNoC blocks in RFNoC 4. The UHD, FPGA, GNU Radio Migration sections provide general information on topics that most users will encounter when migrating their blocks. Finally, an equivalent RFNoC 3 and RFNoC 4 implementation of a digital gain RFNoC Block has been provided as a reference.

=Prerequisites=

===Dependencies (Ubuntu 20.04)===
sudo apt-get install autoconf automake build-essential ccache cmake cpufrequtils doxygen ethtool \
g++ git inetutils-tools libboost-all-dev libncurses5 libncurses5-dev libusb-1.0-0 libusb-1.0-0-dev \
libusb-dev python3-dev python3-mako python3-numpy python3-requests python3-scipy python3-setuptools \
python3-ruamel.yaml libtinfo5 libncurses5

===Vivado 2019.1 Design Edition===

Please reference to Xilinx (xilinx.com) for installation instructions.

''Note: The dependencies step above included installing libtinfo5 libncurses5, which is a workaround for getting Vivado 2019.1 to run on Ubuntu 20.04''

===UHD 4.0===
git clone --branch UHD-4.0 https://github.com/ettusresearch/uhd.git uhd
mkdir uhd/host/build; cd uhd/host/build
cmake ..
make
sudo make install

===GNU Radio 3.8===
'' Note: If your design does not use GNU Radio, then installing GNU Radio and gr-ettus is not required ''

git clone --branch maint-3.8 --recursive https://github.com/gnuradio/gnuradio.git gnuradio
mkdir gnuradio/build; cd gnuradio/build;
cmake ..
make
sudo make install

===gr-ettus===
git clone --branch maint-3.8-uhd4.0 https://github.com/ettusresearch/gr-ettus.git gr-ettus
mkdir gr-ettus/build; cd gr-ettus/build;
cmake -DENABLE_QT=True ..
make
sudo make install

=RFNoC Block Development Environment=

Two options exist for developing RFNoC blocks depending on whether the your RFNoC block integrates with GNU Radio in an out-of-tree module or if it only uses UHD’s C++ API in a standalone application. The sections below outline how to setup the development environment for each scenario.

===Migrating a GNU Radio Out-of-Tree Module===

The tool rfnocmodtool automates the process of creating GNU Radio out-of-tree (OOT) modules that also have support for RFNoC blocks. This tool is part of gr-ettus and it has been ported to RFNoC 4.

Due to changes in almost every source file, it is recommended to use rfnocmodtool to generate a new RFNoC block from scratch and then update the generated “skeleton” files.

====Creating a RFNoC Block with rfnocmodtool====

The following steps show how to create an OOT module called ''example'' and RFNoC block called ''gain'' using rfnocmodtool. The naming is only for example purposes.

rfnocmodtool newmod
Name of the new module: '''example'''

cd rfnoc-tutorial
rfnocmodtool add
Enter name of block/code (without module name prefix): '''gain'''
Enter valid argument list, including default arguments: ''(leave blank)''
Add Python QA code? [y/N] '''N'''
Add C++ QA code? [y/N] '''N'''
Block NoC ID (Hexadecimal): ''(Enter Noc ID of your block)''
Skip Block Controllers Generation? [UHD block ctrl files] [y/N] '''N'''
Skip Block interface files Generation? [GRC block ctrl files] [y/N] '''N'''

''Note: Noc IDs have been reduced from 64-bits in RFNoC 3 to 32-bits in RFNoC 4''

The following are the relevant files that need to be updated when migrating your RFNoC Block.

rfnoc-example/
grc/
example_gain.block.yml – RFNoC Block GNU Radio Companion YAML file
examples/
gain.grc – Example flowgraph using gain RFNoC Block
include/tutorial/
gain.h – GNU Radio block C++ header
gain_block_ctrl.hpp – RFNoC Block Controller C++ header
lib/
gain_impl.cc – GNU Radio block C++ source
gain_impl.h – GNU Radio block C++ header
gain_block_ctrl_impl.cpp – RFNoC Block Controller C++ source
rfnoc/blocks/
gain.yml – RFNoC Block Description YAML file
rfnoc/fpga/rfnoc_block_gain
noc_shell_gain.v – RFNoC Block Noc Shell Verilog Source
rfnoc_block_gain.v – RFNoC Block Verilog Source
rfnoc_block_gain_tb.v – RFNoC Block Testbench
rfnoc/icores
gain_x310_rfnoc_image_core.yml – Image Core YAML file with gain block

====Building OOT module====

cd rfnoc-tutorial
mkdir build; cd build
cmake -DUHD_FPGA_DIR=''(path to uhd/fpga directory)'' ..
make
sudo make install

====Running a testbench====
CMake automatically creates makefile targets to run the generated testbench code for each added RFNoC block. For example, here is how to run the gain block testbench:

cd rfnoc-tutorial/build
make rfnoc_block_gain_tb

====Building a FPGA image====
CMake automatically creates makefile targets to build FPGA images using the generated image core yaml files found in rfnoc/icore. Every RFNoC block created by rfnocmodtool automatically has an image core yaml file generated in that directory. For example, here is how to build an FPGA image using the image core yaml file generated for the gain block:

cd rfnoc-tutorial/build
make gain_x310_rfnoc_image_core

===Migrating a Standalone UHD C++ Application===

For applications that only use the UHD API, an example out-of-tree (UHD source tree) RFNoC block exists called rfnoc-example. It is located in the UHD source at uhd/host/examples/rfnoc-example. This directory can be copied outside of the UHD source tree and used a starting point to migrate your RFNoC block.

The following are the relevant files that need to be updated when migrating your RFNoC Block.

rfnoc-example/
apps/
init_gain_block.cpp – Example C++ application testing gain block
blocks/
gain.yml – RFNoC Block Description YAML file
fpga/rfnoc_block_gain
noc_shell_gain.v – RFNoC Block Noc Shell Verilog Source
rfnoc_block_gain.v – RFNoC Block Verilog Source
rfnoc_block_gain_tb.v – RFNoC Block Testbench
icores/
x310_rfnoc_image_core.yml – Example Image Core YAML file
include/rfnoc/example
gain_block_control.hpp – RFNoC Block Controller C++ header
lib/
gain_block_control.cpp – RFNoC Block Controller C++ source

====Building rfnoc-example====

cd rfnoc-example
mkdir build; cd build
cmake ..
make
sudo make install

====Running a testbench====
CMake automatically creates makefile targets to run RFNoC Block testbench simulations. For every RFNoC block subdirectory listed in the CMakeLists.txt file in the rfnoc-example/fpga directory, a target with the RFNoC block name appended with “_tb” is added as a makefile target. For example, here is how to run the gain RFNoC block testbench:

cd rfnoc-example/build
make rfnoc_block_gain_tb

====Building a FPGA image====
CMake automatically creates makefile targets to build a FPGA image for each image core yaml file listed in the CMakeLists.txt file in the rfnoc-example/icore directory. Each image core yaml file must be listed in the CMakeLists.txt. For example, here is how to build an FPGA image using the image core yaml file generated for the gain block:

cd rfnoc-tutorial/build
make gain_x310_rfnoc_image_core

=Example RFNoC 3 to RFNoC 4 Block Migration=

This ZIP archive, [[File:migration_example.zip]], contains equivalent RFNoC 3 and RFNoC 4 versions of a digital gain RFNoC Block. The following sections will refer to files in this archive to show how the file structure changes when migrating from RFNoC 3 to RFNoC 4.

=UHD Software Migration=

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| Block Description || rfnoc/blocks/gain.xml || lib/gain_block_ctrl_impl.cpp include/example/gain_block_ctrl.hpp
|-
| Block Controller || rfnoc/blocks/gain.yml || lib/gain_block_ctrl_impl.cpp include/example/gain_block_ctrl.hpp
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===Noc Script XML Replaced by Block Description YAML===

RFNoC 3 used Noc Script XML, a domain specific language, to describe the configuration of a RFNoC block: the Noc ID, register names and addresses, args for writing to the registers, and the input/output ports.

RFNoC 4 replaces the Noc Script XML file with an easier to read and edit Block Description YAML file format. From a high level, the Block Description YAML file serves a similar function as the Noc Script XML file, with some similarities and key differences outlined in table below:

{| class="wikitable"
! Item || Noc Script XML || Block Descript YAML || RFNoC 4 Notes
|-
| Block Name
||
<name>gain</name>
||
module_name: gain
||
|-
| Noc ID
||
<id>B160000000000000</id>
||
noc_id: 0xB16
||
Noc ID are limited to 32-bits
|-
| Registers
||
<registers>
<setreg>
<name>GAIN</name>
<address>128</address>
</setreg>
</registers>
||
N/A
||
Registers must be defined in the Block Controller
|-
| Arguments
||
<args>
<arg>
<name>gain</name>
<type>int</type>
...
</arg>
</args>
||
N/A
||
Args are implemented with properties in the Block Controller
|-
| Data Ports
||
<ports>
<sink>
<name>in</name>
</sink>
<source>
<name>out</name>
</source>
</ports>
||
data:
fpga_iface: axis_pyld_ctxt
clk_domain: rfnoc_chdr
inputs:
in:
...
outputs:
out:
...
||
|-
| Control Ports
||
N/A
||
control:
sw_iface: nocscript
fpga_iface: ctrlport
interface_direction: slave
...
||
|-
| Clocking
||
N/A
||
clocks:
- name: rfnoc_chdr
freq: "[]"
- name: rfnoc_ctrl
freq: "[]"
||
|}

''Note: For a more detailed description of the RFNoC 4 Block Description YAML syntax and the various options, see the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].''

===RFNoC API Changes===

Much of the user facing RFNoC software API has not changed or remains very similar between RFNoC 3 and RFNoC 4. The table below outlines some of the notable differences:

{| class="wikitable"
! RFNoC 3 || RFNoC 4 || RFNoC 4 Notes
|-
|
usrp = uhd::device3::make(...)
||
graph = uhd::rfnoc::rfnoc_graph::make()
||
No longer need to create a device3 object
|-
|
usrp->get_block_ctrl(...)
||
graph->get_block(...)
||
Rename
|-
|
N/A
||
graph->enumerate_static_connections()
||
Used to check static connections, usually for detecting hwen a DDC or DUC is statically connected to the radio and requires setting the sample
|-
|
usrp->get_tx_streamer(...)
||
graph->create_tx_streamer(...)
||
Rename
|-
|
usrp->get_rx_streamer(...)
||
graph->create_rx_streamer(...)
||
Rename
|-
|
N/A
||
graph->commit()
||
Commit graph and run initial checks
|-
|
sr_write(...)
||
regs().poke32(...)
||
Address increments by 4
|-
|
sr_read32(...)
||
regs().peek32(...)
||
Address increments by 4
|-
|
sr_read64(...)
||
regs().poke64(...)
||
Address increments by 8
|-
|
set_arg(...)
||
set_property(...)
||
Block args replaced with block properties concept
|-
|
get_arg(...)
||
get_property(...)
||
Block args replaced with block properties concept
|}

===Block Properties===

In RFNoC 3, RFNoC blocks can have arguments (also known as args) that are used to write user registers. This is implemented in the Noc Script XML in the <args> section.

RFNoC 4 expands and generalizes this concept with block properties: a high-level representation of the state of the block. Zero or more properties can be defined by the user in their RFNoC Block’s Block Controller C++ class. When read or written to, they can trigger a call back to a user defined resolver function. The [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification] provides more details on properties in the “Block Properties” section.

The following shows an example of how to migrate a RFNoC 3 Noc Script XML “arg” based register write to a RFNoC 4 property based implementation in the Block Controller:

====RFNoC 3 Noc Script XML snippet====
<registers>
<setreg>
<name>GAIN</name>
<address>128</address>
</setreg>
</registers>

<args>
<arg>
<name>gain</name>
<type>int</type>
<value>1</value>
<check>GE($gain, 0) AND LE($gain, 32767)</check>
<check_message>Gain must be in the range [0, 32767]</check_message>
<action>SR_WRITE("GAIN", $gain)</action>
</arg>
</args>

====RFNoC 4 Block Controller Class====

// <registers>
// <setreg>
// <name>GAIN</name>
// <address>128</address>
// </setreg>
// </registers>
// Note: In RFNoC 4, register addresses can start at address 0 instead of address 128 as in RFNoC 3.
const uint32_t gain_block_ctrl::REG_GAIN_ADDR = 128;
const uint32_t gain_block_ctrl::REG_GAIN_DEFAULT = 1;

class gain_block_ctrl_impl : public gain_block_ctrl
{
public:
RFNOC_BLOCK_CONSTRUCTOR(gain_block_ctrl)
{
_register_props();
}
private:
void _register_props()
{
register_property(&_user_reg, [this]() {
int user_reg = this->_user_reg.get();
// <check>GE($gain, 0) AND LE($gain, 32767)</check>
// <check_message>Gain must be in the range [0, 32767]</check_message>
if (user_reg < 0 || user_reg > 32767) {
throw uhd::value_error("Size value must be in [0,32767]");
}
// <action>SR_WRITE("GAIN", $gain)</action>
this->regs().poke32(REG_USER_ADDR, user_reg);
});
}

// <name>gain</name>
// <type>int</type>
// <value>1</value>
property_t<int> _user_reg{"gain", REG_USER_DEFAULT, {res_source_info::USER}};
}

As the above shows, writing to a register can be replicated with a property and a resolver function. Of course, the resolver function can also be made much more sophisticated. For additional examples, see the in-tree block controllers in uhd/host/lib/rfnoc.

=FPGA Migration=

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| Block Verilog Code || rfnoc/fpga-src/noc_block_gain.v || rfnoc/fpga/rfnoc_block_gain/rfnoc_block_gain.v
|-
| Block Noc Shell || N/A || rfnoc/fpga/rfnoc_block_gain/noc_shell_gain.v
|-
| Block Testbnech || rfnoc/testbench/noc_block_gain/noc_block_gain_tb.sv || rfnoc/fpga/rfnoc_block_gain/rfnoc_block_gain_tb.sv
|-
| Image Core || N/A || rfnoc/icores/gain_x310_rfnoc_image_core.yml
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===Noc Shell Changes===

RFNoC 4 replaces the highly parameterized RFNoC 3 Noc Shell with a per-block customized Noc Shell generated from the block’s Block Description YAML file. The Noc Shell generated via rfnocmodtool or the existing one in rfnoc-example is acceptable for most blocks that require one input and output data port.

====Generating a Custom Noc Shell====

Some blocks may need multiple data ports or other modifications. This requires editing the Block Description YAML file and then using the Python script rfnoc_create_verilog.py (found in uhd/host/utils/rfnoc_blocktool) to generate a new Noc Shell instance.

The argument “-c” is used to provide the YAML file location. “-d” provides the output destination directory.

''Note: It is suggested to not set the destination directory to your existing RFNoC block code, as the script will automatically overwrite the existing code!''

Example usage:
rfnoc_create_verilog.py -c ./rfnoc-example/rfnoc/blocks/gain.yml -d ./output/

====Changing Noc ID without using rfnoc_create_verilog====

In the generated Noc Shell Verilog code, a block’s Noc ID can be changed by updating the NOC_ID parameter on the ''backend_iface'' module. Make sure this matches the Noc ID in both the Block Description YAML file and Block Controller C++ code.

====Goodbye AXI Wrapper====

The RFNoC 3 version of Noc Shell outputs / accepts CHDR data packets consisting of a header, optional timestamp, and payload on a 64-bit AXI stream bus. Most designs then used a module called AXI Wrapper to handle the conversion between CHDR data packets and sample streams on a 32-bit AXI stream bus. AXI Wrapper also supported SIMPLE_MODE which for some use cases could transparently handle the header portion of the CHDR data packet. Otherwise, the user would need to set the header via m_axis_data_tuser.

In RFNoC 4, Noc Shell has absorbed AXI Wrapper’s functionality. Noc Shell outputs two AXI stream buses per input / output port: a payload and context bus. The payload bus is in most cases identical to AXI Wrapper’s output: a 32-bit stream of samples on an AXI Stream bus with packets delimited by tlast. The context AXI stream bus carries the header, optional timestamp, and optional metadata. If your block used AXI Wrapper’s SIMPLE_MODE, then you can loop the context bus back into Noc Shell. If not, you will need to modify the context bus data. Refer to the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification] for the format and timing diagram of the context bus.

''Important Note: If your block used the AXI Rate Change module, Noc Shell has another data port mode to support this use case called '''axis_data''' that can be set in the Block Descriptor YAML file (see the fpga_iface entry). This mode causes the Noc Shell data ports to look more like AXI Wrapper’s and therefore makes them compatible with AXI Rate Change. See the DDC, DUC, or Keep One in N RFNoC Blocks for an example.''

===Settings Bus replaced by CtrlPort===

CtrlPort replaces the Settings Bus in RFNoC 4. The CtrlPort bus is similar to the Settings Bus with a few key differences. The table below compares the signaling between the two bus formats and provides notes on any differences. Timing diagrams and additional information on the CtrlPort bus is also available in the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].

{| class="wikitable"
! Settings Bus (RFNoC 3) || CtrlPort (RFNoC 4) || RFNoC 4 Notes
|-
| set_stb || ctrlport_reg_wr || Write strobe
|-
| set_addr || ctrlport_req_addr || 20-bits instead of 8-bits, increments by 4 instead of by 1, no reserved addresses (versus addresses 0-127 for Settings Bus)
|-
| set_data || ctrlport_req_data || Write data
|-
| N/A || ctrlport_req_rd || Read strobe equivalent of ctrlport_req_wr
|-
| rb_addr || N/A || CtrlPort uses ctrlport_req_addr for both '''read and write''' addresses
|-
| rb_data || ctrlport_resp_data || Read data, 32-bits instead of 64-bits
|-
| rb_stb || N/A || CtrlPort requires ack strobe for '''reads and writes'''
|}

One additional difference when using CtrlPort is that there is not an equivalent Settings Register module. The bus is simple enough to setup a clocked process to handle reading from and writing to registers. See the Verilog example below:

// Note: Register addresses increment by 4
localparam REG_USER_ADDR = 0; // Address for example user register
localparam REG_USER_DEFAULT = 0; // Default value for user register

reg [31:0] reg_user = REG_USER_DEFAULT;

always @(posedge ctrlport_clk) begin
if (ctrlport_rst) begin
reg_user = REG_USER_DEFAULT;
end else begin
// Default assignment
m_ctrlport_resp_ack <= 0;

// Read user register
if (m_ctrlport_req_rd) begin // Read request
case (m_ctrlport_req_addr)
REG_USER_ADDR: begin
m_ctrlport_resp_ack <= 1;
m_ctrlport_resp_data <= reg_user;
end
endcase
end

// Write user register
if (m_ctrlport_req_wr) begin // Write requst
case (m_ctrlport_req_addr)
REG_USER_ADDR: begin
m_ctrlport_resp_ack <= 1;
reg_user <= m_ctrlport_req_data[31:0];
end
endcase
end
end
end

''Important Note: For blocks that make heavy use of the Settings Bus and/or Settings Registers, there is a CtrlPort to Settings Bus bridge available called '''ctrlport_to_settings_bus'''. See the Keep One In N RFNoC Block for example code on how to interface with it.''

===Testbench Infrastructure===

While RFNoC 4 does overhaul the RFNoC 3 testbench infrastructure API, most of the high level concepts remain the same. The table below outlines some of the commonly used RFNoC 3 functions / code and the RFNoC 4 equivalent.

{| class="wikitable"
! Operation || RFNoC 3 || RFNoC 4
|-
| Setup RFNoC
||
`RFNOC_SIM_INIT(...)
`RFNOC_ADD_BLOCK(...)
`RFNOC_CONNECT(...)
||
RfnocBlockCtrlBfm #(...) blk_ctrl = new(...);
blk_ctrl.connect_master_data_port(...)
blk_ctrl.connect_slave_data_port(...)
''Note: Instantiate one Block Controller BFM per RFNoC Block''
|-
| Setup Test Cases
||
`TEST_CASE_START(...)
`TEST_CASE_DONE(...)
||
test.start_test(...)
test.end_test()
|-
| Register Read
||
tb_streamer.read_reg(...)
||
blk_ctrl.reg_read(...)
|-
| Register Write
||
tb_streamer.write_reg(...)
||
blk_ctrl.reg_write(...)
|-
| Send Data / Samples
||
tb_streamer.send(...)
||
blk_ctrl.send_items(...)
|-
| Receive Data / Samples
||
tb_streamer.recv(...)
||
blk_ctrl.recv_items(...)
|}

===Building FPGA images using Image Core YAML Files===

RFNoC 4 replaces uhd_image_builder, the RFNoC 3 FPGA image building tool, with a new tool called rfnoc_image_builder. This tool produces a FPGA bitstream based on an Image Core YAML file that describes the device configuration (e.g. X310 with dual 10GigE) and included RFNoC blocks along with their connections (both static and dynamic), clocking, and I/O.

Both rfnocmodtool and the UHD in-tree example called rfnoc-example automatically setup make targets to handle running rfnoc_image_builder. If you want to use rfnoc_image_builder directly, more details can be found in the [https://kb.ettus.com/Getting_Started_with_RFNoC_in_UHD_4.0 Getting Started with RFNoC in UHD 4.0].

=GNU Radio Software Migration=

RFNoC 4 supports GNU Radio 3.8 only. Most of your RFNoC Block’s GNU Radio related changes will be due to API differences between GNU Radio 3.7 to 3.8. These changes are outside of the scope of this article. Instead, refer to [https://wiki.gnuradio.org/index.php/GNU_Radio_3.8_OOT_Module_Porting_Guide GNU Radio 3.8 Migration Guide] and [https://wiki.gnuradio.org/index.php/YAML_GRC GNU Radio Companion YAML] sites for more information.

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| GNU Radio Block || lib/gain_impl.cc lib/gain_impl.h include/example/gain.h || lib/gain_impl.cc lib/gain_impl.h include/example/gain.h
|-
| GRC Block Description || grc/gain.xml || grc/gain.yml
|-
| Example GRC Flowgraph || examples/gain.grc || examples/gain.grc
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===RX & TX Streamer Blocks===

When transition between a RFNoC block and a GNU Radio block or vice versa, you must insert either a RX stream or TX streamer block respectively. This differs from RFNoC 3, where a RFNoC block could be directly connected to a GNU Radio block.

[[File:rx_tx_streamer.png|border]]

===Setting RFNoC Block Properties Directly in GNU Radio===

The base class for RFNoC Block’s in GNU Radio have a set of functions that provide a shortcut to getting and setting properties without writing custom class methods. The table below lists the functions.

{| class="wikitable"
! Property Type || Set Property || Get Property
|-
| Integer || set_int_property(...) || get_int_property(...)
|-
| Double || set_double_property(...) || get_double_property(...)
|-
| Bool || set_bool_property(...) || get_bool_property(...)
|-
| String || set_string_property(...) || get_string_property(...)
|-
|}

'''Example code for GNU Radio Companion YAML Block Description file'''
templates:
imports: |-
import example
make: |-
example.gain(
self.rfnoc_graph,
uhd.device_addr(${block_args}),
${device_select},
${instance_select})
self.${id}.set_int_property('gain', ${gain})
callbacks:
- set_int_property('gain', ${gain})

RFNoC 4 Migration Guide

2021-11-01T10:54:41Z

MartinAnderseck: /* Dependencies (Ubuntu 20.04) */ Remove GNU Radio dependencies (not required for UHD only)

=Abstract=

The UHD 4.0 release includes a major upgrade to the RFNoC framework called RFNoC 4. This article is a guide to aid users in migrating their existing RFNoC blocks from RFNoC 3 to RFNoC 4. The RFNoC Block Development Environment section provides guidance on how to setup an environment for developing out-of-tree RFNoC blocks in RFNoC 4. The UHD, FPGA, GNU Radio Migration sections provide general information on topics that most users will encounter when migrating their blocks. Finally, an equivalent RFNoC 3 and RFNoC 4 implementation of a digital gain RFNoC Block has been provided as a reference.

=Prerequisites=

===Dependencies (Ubuntu 20.04)===
sudo apt-get install autoconf automake build-essential ccache cmake cpufrequtils doxygen ethtool \
g++ git inetutils-tools libboost-all-dev libncurses5 libncurses5-dev libusb-1.0-0 libusb-1.0-0-dev \
libusb-dev python3-dev python3-mako python3-numpy python3-requests python3-scipy python3-setuptools \
python3-ruamel.yaml

===Vivado 2019.1 Design Edition===

Please reference to Xilinx (xilinx.com) for installation instructions.

''Note: The dependencies step above included installing libtinfo5 libncurses5, which is a workaround for getting Vivado 2019.1 to run on Ubuntu 20.04''

===UHD 4.0===
git clone --branch UHD-4.0 https://github.com/ettusresearch/uhd.git uhd
mkdir uhd/host/build; cd uhd/host/build
cmake ..
make
sudo make install

===GNU Radio 3.8===
'' Note: If your design does not use GNU Radio, then installing GNU Radio and gr-ettus is not required ''

git clone --branch maint-3.8 --recursive https://github.com/gnuradio/gnuradio.git gnuradio
mkdir gnuradio/build; cd gnuradio/build;
cmake ..
make
sudo make install

===gr-ettus===
git clone --branch maint-3.8-uhd4.0 https://github.com/ettusresearch/gr-ettus.git gr-ettus
mkdir gr-ettus/build; cd gr-ettus/build;
cmake -DENABLE_QT=True ..
make
sudo make install

=RFNoC Block Development Environment=

Two options exist for developing RFNoC blocks depending on whether the your RFNoC block integrates with GNU Radio in an out-of-tree module or if it only uses UHD’s C++ API in a standalone application. The sections below outline how to setup the development environment for each scenario.

===Migrating a GNU Radio Out-of-Tree Module===

The tool rfnocmodtool automates the process of creating GNU Radio out-of-tree (OOT) modules that also have support for RFNoC blocks. This tool is part of gr-ettus and it has been ported to RFNoC 4.

Due to changes in almost every source file, it is recommended to use rfnocmodtool to generate a new RFNoC block from scratch and then update the generated “skeleton” files.

====Creating a RFNoC Block with rfnocmodtool====

The following steps show how to create an OOT module called ''example'' and RFNoC block called ''gain'' using rfnocmodtool. The naming is only for example purposes.

rfnocmodtool newmod
Name of the new module: '''example'''

cd rfnoc-tutorial
rfnocmodtool add
Enter name of block/code (without module name prefix): '''gain'''
Enter valid argument list, including default arguments: ''(leave blank)''
Add Python QA code? [y/N] '''N'''
Add C++ QA code? [y/N] '''N'''
Block NoC ID (Hexadecimal): ''(Enter Noc ID of your block)''
Skip Block Controllers Generation? [UHD block ctrl files] [y/N] '''N'''
Skip Block interface files Generation? [GRC block ctrl files] [y/N] '''N'''

''Note: Noc IDs have been reduced from 64-bits in RFNoC 3 to 32-bits in RFNoC 4''

The following are the relevant files that need to be updated when migrating your RFNoC Block.

rfnoc-example/
grc/
example_gain.block.yml – RFNoC Block GNU Radio Companion YAML file
examples/
gain.grc – Example flowgraph using gain RFNoC Block
include/tutorial/
gain.h – GNU Radio block C++ header
gain_block_ctrl.hpp – RFNoC Block Controller C++ header
lib/
gain_impl.cc – GNU Radio block C++ source
gain_impl.h – GNU Radio block C++ header
gain_block_ctrl_impl.cpp – RFNoC Block Controller C++ source
rfnoc/blocks/
gain.yml – RFNoC Block Description YAML file
rfnoc/fpga/rfnoc_block_gain
noc_shell_gain.v – RFNoC Block Noc Shell Verilog Source
rfnoc_block_gain.v – RFNoC Block Verilog Source
rfnoc_block_gain_tb.v – RFNoC Block Testbench
rfnoc/icores
gain_x310_rfnoc_image_core.yml – Image Core YAML file with gain block

====Building OOT module====

cd rfnoc-tutorial
mkdir build; cd build
cmake -DUHD_FPGA_DIR=''(path to uhd/fpga directory)'' ..
make
sudo make install

====Running a testbench====
CMake automatically creates makefile targets to run the generated testbench code for each added RFNoC block. For example, here is how to run the gain block testbench:

cd rfnoc-tutorial/build
make rfnoc_block_gain_tb

====Building a FPGA image====
CMake automatically creates makefile targets to build FPGA images using the generated image core yaml files found in rfnoc/icore. Every RFNoC block created by rfnocmodtool automatically has an image core yaml file generated in that directory. For example, here is how to build an FPGA image using the image core yaml file generated for the gain block:

cd rfnoc-tutorial/build
make gain_x310_rfnoc_image_core

===Migrating a Standalone UHD C++ Application===

For applications that only use the UHD API, an example out-of-tree (UHD source tree) RFNoC block exists called rfnoc-example. It is located in the UHD source at uhd/host/examples/rfnoc-example. This directory can be copied outside of the UHD source tree and used a starting point to migrate your RFNoC block.

The following are the relevant files that need to be updated when migrating your RFNoC Block.

rfnoc-example/
apps/
init_gain_block.cpp – Example C++ application testing gain block
blocks/
gain.yml – RFNoC Block Description YAML file
fpga/rfnoc_block_gain
noc_shell_gain.v – RFNoC Block Noc Shell Verilog Source
rfnoc_block_gain.v – RFNoC Block Verilog Source
rfnoc_block_gain_tb.v – RFNoC Block Testbench
icores/
x310_rfnoc_image_core.yml – Example Image Core YAML file
include/rfnoc/example
gain_block_control.hpp – RFNoC Block Controller C++ header
lib/
gain_block_control.cpp – RFNoC Block Controller C++ source

====Building rfnoc-example====

cd rfnoc-example
mkdir build; cd build
cmake ..
make
sudo make install

====Running a testbench====
CMake automatically creates makefile targets to run RFNoC Block testbench simulations. For every RFNoC block subdirectory listed in the CMakeLists.txt file in the rfnoc-example/fpga directory, a target with the RFNoC block name appended with “_tb” is added as a makefile target. For example, here is how to run the gain RFNoC block testbench:

cd rfnoc-example/build
make rfnoc_block_gain_tb

====Building a FPGA image====
CMake automatically creates makefile targets to build a FPGA image for each image core yaml file listed in the CMakeLists.txt file in the rfnoc-example/icore directory. Each image core yaml file must be listed in the CMakeLists.txt. For example, here is how to build an FPGA image using the image core yaml file generated for the gain block:

cd rfnoc-tutorial/build
make gain_x310_rfnoc_image_core

=Example RFNoC 3 to RFNoC 4 Block Migration=

This ZIP archive, [[File:migration_example.zip]], contains equivalent RFNoC 3 and RFNoC 4 versions of a digital gain RFNoC Block. The following sections will refer to files in this archive to show how the file structure changes when migrating from RFNoC 3 to RFNoC 4.

=UHD Software Migration=

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| Block Description || rfnoc/blocks/gain.xml || lib/gain_block_ctrl_impl.cpp include/example/gain_block_ctrl.hpp
|-
| Block Controller || rfnoc/blocks/gain.yml || lib/gain_block_ctrl_impl.cpp include/example/gain_block_ctrl.hpp
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===Noc Script XML Replaced by Block Description YAML===

RFNoC 3 used Noc Script XML, a domain specific language, to describe the configuration of a RFNoC block: the Noc ID, register names and addresses, args for writing to the registers, and the input/output ports.

RFNoC 4 replaces the Noc Script XML file with an easier to read and edit Block Description YAML file format. From a high level, the Block Description YAML file serves a similar function as the Noc Script XML file, with some similarities and key differences outlined in table below:

{| class="wikitable"
! Item || Noc Script XML || Block Descript YAML || RFNoC 4 Notes
|-
| Block Name
||
<name>gain</name>
||
module_name: gain
||
|-
| Noc ID
||
<id>B160000000000000</id>
||
noc_id: 0xB16
||
Noc ID are limited to 32-bits
|-
| Registers
||
<registers>
<setreg>
<name>GAIN</name>
<address>128</address>
</setreg>
</registers>
||
N/A
||
Registers must be defined in the Block Controller
|-
| Arguments
||
<args>
<arg>
<name>gain</name>
<type>int</type>
...
</arg>
</args>
||
N/A
||
Args are implemented with properties in the Block Controller
|-
| Data Ports
||
<ports>
<sink>
<name>in</name>
</sink>
<source>
<name>out</name>
</source>
</ports>
||
data:
fpga_iface: axis_pyld_ctxt
clk_domain: rfnoc_chdr
inputs:
in:
...
outputs:
out:
...
||
|-
| Control Ports
||
N/A
||
control:
sw_iface: nocscript
fpga_iface: ctrlport
interface_direction: slave
...
||
|-
| Clocking
||
N/A
||
clocks:
- name: rfnoc_chdr
freq: "[]"
- name: rfnoc_ctrl
freq: "[]"
||
|}

''Note: For a more detailed description of the RFNoC 4 Block Description YAML syntax and the various options, see the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].''

===RFNoC API Changes===

Much of the user facing RFNoC software API has not changed or remains very similar between RFNoC 3 and RFNoC 4. The table below outlines some of the notable differences:

{| class="wikitable"
! RFNoC 3 || RFNoC 4 || RFNoC 4 Notes
|-
|
usrp = uhd::device3::make(...)
||
graph = uhd::rfnoc::rfnoc_graph::make()
||
No longer need to create a device3 object
|-
|
usrp->get_block_ctrl(...)
||
graph->get_block(...)
||
Rename
|-
|
N/A
||
graph->enumerate_static_connections()
||
Used to check static connections, usually for detecting hwen a DDC or DUC is statically connected to the radio and requires setting the sample
|-
|
usrp->get_tx_streamer(...)
||
graph->create_tx_streamer(...)
||
Rename
|-
|
usrp->get_rx_streamer(...)
||
graph->create_rx_streamer(...)
||
Rename
|-
|
N/A
||
graph->commit()
||
Commit graph and run initial checks
|-
|
sr_write(...)
||
regs().poke32(...)
||
Address increments by 4
|-
|
sr_read32(...)
||
regs().peek32(...)
||
Address increments by 4
|-
|
sr_read64(...)
||
regs().poke64(...)
||
Address increments by 8
|-
|
set_arg(...)
||
set_property(...)
||
Block args replaced with block properties concept
|-
|
get_arg(...)
||
get_property(...)
||
Block args replaced with block properties concept
|}

===Block Properties===

In RFNoC 3, RFNoC blocks can have arguments (also known as args) that are used to write user registers. This is implemented in the Noc Script XML in the <args> section.

RFNoC 4 expands and generalizes this concept with block properties: a high-level representation of the state of the block. Zero or more properties can be defined by the user in their RFNoC Block’s Block Controller C++ class. When read or written to, they can trigger a call back to a user defined resolver function. The [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification] provides more details on properties in the “Block Properties” section.

The following shows an example of how to migrate a RFNoC 3 Noc Script XML “arg” based register write to a RFNoC 4 property based implementation in the Block Controller:

====RFNoC 3 Noc Script XML snippet====
<registers>
<setreg>
<name>GAIN</name>
<address>128</address>
</setreg>
</registers>

<args>
<arg>
<name>gain</name>
<type>int</type>
<value>1</value>
<check>GE($gain, 0) AND LE($gain, 32767)</check>
<check_message>Gain must be in the range [0, 32767]</check_message>
<action>SR_WRITE("GAIN", $gain)</action>
</arg>
</args>

====RFNoC 4 Block Controller Class====

// <registers>
// <setreg>
// <name>GAIN</name>
// <address>128</address>
// </setreg>
// </registers>
// Note: In RFNoC 4, register addresses can start at address 0 instead of address 128 as in RFNoC 3.
const uint32_t gain_block_ctrl::REG_GAIN_ADDR = 128;
const uint32_t gain_block_ctrl::REG_GAIN_DEFAULT = 1;

class gain_block_ctrl_impl : public gain_block_ctrl
{
public:
RFNOC_BLOCK_CONSTRUCTOR(gain_block_ctrl)
{
_register_props();
}
private:
void _register_props()
{
register_property(&_user_reg, [this]() {
int user_reg = this->_user_reg.get();
// <check>GE($gain, 0) AND LE($gain, 32767)</check>
// <check_message>Gain must be in the range [0, 32767]</check_message>
if (user_reg < 0 || user_reg > 32767) {
throw uhd::value_error("Size value must be in [0,32767]");
}
// <action>SR_WRITE("GAIN", $gain)</action>
this->regs().poke32(REG_USER_ADDR, user_reg);
});
}

// <name>gain</name>
// <type>int</type>
// <value>1</value>
property_t<int> _user_reg{"gain", REG_USER_DEFAULT, {res_source_info::USER}};
}

As the above shows, writing to a register can be replicated with a property and a resolver function. Of course, the resolver function can also be made much more sophisticated. For additional examples, see the in-tree block controllers in uhd/host/lib/rfnoc.

=FPGA Migration=

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| Block Verilog Code || rfnoc/fpga-src/noc_block_gain.v || rfnoc/fpga/rfnoc_block_gain/rfnoc_block_gain.v
|-
| Block Noc Shell || N/A || rfnoc/fpga/rfnoc_block_gain/noc_shell_gain.v
|-
| Block Testbnech || rfnoc/testbench/noc_block_gain/noc_block_gain_tb.sv || rfnoc/fpga/rfnoc_block_gain/rfnoc_block_gain_tb.sv
|-
| Image Core || N/A || rfnoc/icores/gain_x310_rfnoc_image_core.yml
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===Noc Shell Changes===

RFNoC 4 replaces the highly parameterized RFNoC 3 Noc Shell with a per-block customized Noc Shell generated from the block’s Block Description YAML file. The Noc Shell generated via rfnocmodtool or the existing one in rfnoc-example is acceptable for most blocks that require one input and output data port.

====Generating a Custom Noc Shell====

Some blocks may need multiple data ports or other modifications. This requires editing the Block Description YAML file and then using the Python script rfnoc_create_verilog.py (found in uhd/host/utils/rfnoc_blocktool) to generate a new Noc Shell instance.

The argument “-c” is used to provide the YAML file location. “-d” provides the output destination directory.

''Note: It is suggested to not set the destination directory to your existing RFNoC block code, as the script will automatically overwrite the existing code!''

Example usage:
rfnoc_create_verilog.py -c ./rfnoc-example/rfnoc/blocks/gain.yml -d ./output/

====Changing Noc ID without using rfnoc_create_verilog====

In the generated Noc Shell Verilog code, a block’s Noc ID can be changed by updating the NOC_ID parameter on the ''backend_iface'' module. Make sure this matches the Noc ID in both the Block Description YAML file and Block Controller C++ code.

====Goodbye AXI Wrapper====

The RFNoC 3 version of Noc Shell outputs / accepts CHDR data packets consisting of a header, optional timestamp, and payload on a 64-bit AXI stream bus. Most designs then used a module called AXI Wrapper to handle the conversion between CHDR data packets and sample streams on a 32-bit AXI stream bus. AXI Wrapper also supported SIMPLE_MODE which for some use cases could transparently handle the header portion of the CHDR data packet. Otherwise, the user would need to set the header via m_axis_data_tuser.

In RFNoC 4, Noc Shell has absorbed AXI Wrapper’s functionality. Noc Shell outputs two AXI stream buses per input / output port: a payload and context bus. The payload bus is in most cases identical to AXI Wrapper’s output: a 32-bit stream of samples on an AXI Stream bus with packets delimited by tlast. The context AXI stream bus carries the header, optional timestamp, and optional metadata. If your block used AXI Wrapper’s SIMPLE_MODE, then you can loop the context bus back into Noc Shell. If not, you will need to modify the context bus data. Refer to the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification] for the format and timing diagram of the context bus.

''Important Note: If your block used the AXI Rate Change module, Noc Shell has another data port mode to support this use case called '''axis_data''' that can be set in the Block Descriptor YAML file (see the fpga_iface entry). This mode causes the Noc Shell data ports to look more like AXI Wrapper’s and therefore makes them compatible with AXI Rate Change. See the DDC, DUC, or Keep One in N RFNoC Blocks for an example.''

===Settings Bus replaced by CtrlPort===

CtrlPort replaces the Settings Bus in RFNoC 4. The CtrlPort bus is similar to the Settings Bus with a few key differences. The table below compares the signaling between the two bus formats and provides notes on any differences. Timing diagrams and additional information on the CtrlPort bus is also available in the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].

{| class="wikitable"
! Settings Bus (RFNoC 3) || CtrlPort (RFNoC 4) || RFNoC 4 Notes
|-
| set_stb || ctrlport_reg_wr || Write strobe
|-
| set_addr || ctrlport_req_addr || 20-bits instead of 8-bits, increments by 4 instead of by 1, no reserved addresses (versus addresses 0-127 for Settings Bus)
|-
| set_data || ctrlport_req_data || Write data
|-
| N/A || ctrlport_req_rd || Read strobe equivalent of ctrlport_req_wr
|-
| rb_addr || N/A || CtrlPort uses ctrlport_req_addr for both '''read and write''' addresses
|-
| rb_data || ctrlport_resp_data || Read data, 32-bits instead of 64-bits
|-
| rb_stb || N/A || CtrlPort requires ack strobe for '''reads and writes'''
|}

One additional difference when using CtrlPort is that there is not an equivalent Settings Register module. The bus is simple enough to setup a clocked process to handle reading from and writing to registers. See the Verilog example below:

// Note: Register addresses increment by 4
localparam REG_USER_ADDR = 0; // Address for example user register
localparam REG_USER_DEFAULT = 0; // Default value for user register

reg [31:0] reg_user = REG_USER_DEFAULT;

always @(posedge ctrlport_clk) begin
if (ctrlport_rst) begin
reg_user = REG_USER_DEFAULT;
end else begin
// Default assignment
m_ctrlport_resp_ack <= 0;

// Read user register
if (m_ctrlport_req_rd) begin // Read request
case (m_ctrlport_req_addr)
REG_USER_ADDR: begin
m_ctrlport_resp_ack <= 1;
m_ctrlport_resp_data <= reg_user;
end
endcase
end

// Write user register
if (m_ctrlport_req_wr) begin // Write requst
case (m_ctrlport_req_addr)
REG_USER_ADDR: begin
m_ctrlport_resp_ack <= 1;
reg_user <= m_ctrlport_req_data[31:0];
end
endcase
end
end
end

''Important Note: For blocks that make heavy use of the Settings Bus and/or Settings Registers, there is a CtrlPort to Settings Bus bridge available called '''ctrlport_to_settings_bus'''. See the Keep One In N RFNoC Block for example code on how to interface with it.''

===Testbench Infrastructure===

While RFNoC 4 does overhaul the RFNoC 3 testbench infrastructure API, most of the high level concepts remain the same. The table below outlines some of the commonly used RFNoC 3 functions / code and the RFNoC 4 equivalent.

{| class="wikitable"
! Operation || RFNoC 3 || RFNoC 4
|-
| Setup RFNoC
||
`RFNOC_SIM_INIT(...)
`RFNOC_ADD_BLOCK(...)
`RFNOC_CONNECT(...)
||
RfnocBlockCtrlBfm #(...) blk_ctrl = new(...);
blk_ctrl.connect_master_data_port(...)
blk_ctrl.connect_slave_data_port(...)
''Note: Instantiate one Block Controller BFM per RFNoC Block''
|-
| Setup Test Cases
||
`TEST_CASE_START(...)
`TEST_CASE_DONE(...)
||
test.start_test(...)
test.end_test()
|-
| Register Read
||
tb_streamer.read_reg(...)
||
blk_ctrl.reg_read(...)
|-
| Register Write
||
tb_streamer.write_reg(...)
||
blk_ctrl.reg_write(...)
|-
| Send Data / Samples
||
tb_streamer.send(...)
||
blk_ctrl.send_items(...)
|-
| Receive Data / Samples
||
tb_streamer.recv(...)
||
blk_ctrl.recv_items(...)
|}

===Building FPGA images using Image Core YAML Files===

RFNoC 4 replaces uhd_image_builder, the RFNoC 3 FPGA image building tool, with a new tool called rfnoc_image_builder. This tool produces a FPGA bitstream based on an Image Core YAML file that describes the device configuration (e.g. X310 with dual 10GigE) and included RFNoC blocks along with their connections (both static and dynamic), clocking, and I/O.

Both rfnocmodtool and the UHD in-tree example called rfnoc-example automatically setup make targets to handle running rfnoc_image_builder. If you want to use rfnoc_image_builder directly, more details can be found in the [https://kb.ettus.com/Getting_Started_with_RFNoC_in_UHD_4.0 Getting Started with RFNoC in UHD 4.0].

=GNU Radio Software Migration=

RFNoC 4 supports GNU Radio 3.8 only. Most of your RFNoC Block’s GNU Radio related changes will be due to API differences between GNU Radio 3.7 to 3.8. These changes are outside of the scope of this article. Instead, refer to [https://wiki.gnuradio.org/index.php/GNU_Radio_3.8_OOT_Module_Porting_Guide GNU Radio 3.8 Migration Guide] and [https://wiki.gnuradio.org/index.php/YAML_GRC GNU Radio Companion YAML] sites for more information.

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| GNU Radio Block || lib/gain_impl.cc lib/gain_impl.h include/example/gain.h || lib/gain_impl.cc lib/gain_impl.h include/example/gain.h
|-
| GRC Block Description || grc/gain.xml || grc/gain.yml
|-
| Example GRC Flowgraph || examples/gain.grc || examples/gain.grc
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===RX & TX Streamer Blocks===

When transition between a RFNoC block and a GNU Radio block or vice versa, you must insert either a RX stream or TX streamer block respectively. This differs from RFNoC 3, where a RFNoC block could be directly connected to a GNU Radio block.

[[File:rx_tx_streamer.png|border]]

===Setting RFNoC Block Properties Directly in GNU Radio===

The base class for RFNoC Block’s in GNU Radio have a set of functions that provide a shortcut to getting and setting properties without writing custom class methods. The table below lists the functions.

{| class="wikitable"
! Property Type || Set Property || Get Property
|-
| Integer || set_int_property(...) || get_int_property(...)
|-
| Double || set_double_property(...) || get_double_property(...)
|-
| Bool || set_bool_property(...) || get_bool_property(...)
|-
| String || set_string_property(...) || get_string_property(...)
|-
|}

'''Example code for GNU Radio Companion YAML Block Description file'''
templates:
imports: |-
import example
make: |-
example.gain(
self.rfnoc_graph,
uhd.device_addr(${block_args}),
${device_select},
${instance_select})
self.${id}.set_int_property('gain', ${gain})
callbacks:
- set_int_property('gain', ${gain})

RFNoC 4 Migration Guide

2021-11-01T10:53:44Z

MartinAnderseck: /* Vivado 2019.1 Design Edition */ Fix typo in Ubuntu

=Abstract=

The UHD 4.0 release includes a major upgrade to the RFNoC framework called RFNoC 4. This article is a guide to aid users in migrating their existing RFNoC blocks from RFNoC 3 to RFNoC 4. The RFNoC Block Development Environment section provides guidance on how to setup an environment for developing out-of-tree RFNoC blocks in RFNoC 4. The UHD, FPGA, GNU Radio Migration sections provide general information on topics that most users will encounter when migrating their blocks. Finally, an equivalent RFNoC 3 and RFNoC 4 implementation of a digital gain RFNoC Block has been provided as a reference.

=Prerequisites=

===Dependencies (Ubuntu 20.04)===
sudo apt-get -y install autoconf automake build-essential ccache cmake cpufrequtils \
doxygen ethtool fort77 g++ gir1.2-gtk-3.0 git gobject-introspection gpsd gpsd-clients \
inetutils-tools libasound2-dev libboost-all-dev libcomedi-dev libcppunit-dev libfftw3-bin \
libfftw3-dev libfftw3-doc libfontconfig1-dev libgmp-dev libgps-dev libgsl-dev liblog4cpp5-dev \
libncurses5 libncurses5-dev libpulse-dev libqt5opengl5-dev libqwt-qt5-dev libsdl1.2-dev libtool \
libudev-dev libusb-1.0-0 libusb-1.0-0-dev libusb-dev libxi-dev libxrender-dev libzmq3-dev \
libzmq5 ncurses-bin python3-cheetah python3-click python3-click-plugins python3-click-threading \
python3-dev python3-docutils python3-gi python3-gi-cairo python3-gps python3-lxml python3-mako \
python3-numpy python3-numpy-dbg python3-opengl python3-pyqt5 python3-requests python3-scipy \
python3-setuptools python3-six python3-sphinx python3-yaml python3-zmq python3-ruamel.yaml swig wget

===Vivado 2019.1 Design Edition===

Please reference to Xilinx (xilinx.com) for installation instructions.

''Note: The dependencies step above included installing libtinfo5 libncurses5, which is a workaround for getting Vivado 2019.1 to run on Ubuntu 20.04''

===UHD 4.0===
git clone --branch UHD-4.0 https://github.com/ettusresearch/uhd.git uhd
mkdir uhd/host/build; cd uhd/host/build
cmake ..
make
sudo make install

===GNU Radio 3.8===
'' Note: If your design does not use GNU Radio, then installing GNU Radio and gr-ettus is not required ''

git clone --branch maint-3.8 --recursive https://github.com/gnuradio/gnuradio.git gnuradio
mkdir gnuradio/build; cd gnuradio/build;
cmake ..
make
sudo make install

===gr-ettus===
git clone --branch maint-3.8-uhd4.0 https://github.com/ettusresearch/gr-ettus.git gr-ettus
mkdir gr-ettus/build; cd gr-ettus/build;
cmake -DENABLE_QT=True ..
make
sudo make install

=RFNoC Block Development Environment=

Two options exist for developing RFNoC blocks depending on whether the your RFNoC block integrates with GNU Radio in an out-of-tree module or if it only uses UHD’s C++ API in a standalone application. The sections below outline how to setup the development environment for each scenario.

===Migrating a GNU Radio Out-of-Tree Module===

The tool rfnocmodtool automates the process of creating GNU Radio out-of-tree (OOT) modules that also have support for RFNoC blocks. This tool is part of gr-ettus and it has been ported to RFNoC 4.

Due to changes in almost every source file, it is recommended to use rfnocmodtool to generate a new RFNoC block from scratch and then update the generated “skeleton” files.

====Creating a RFNoC Block with rfnocmodtool====

The following steps show how to create an OOT module called ''example'' and RFNoC block called ''gain'' using rfnocmodtool. The naming is only for example purposes.

rfnocmodtool newmod
Name of the new module: '''example'''

cd rfnoc-tutorial
rfnocmodtool add
Enter name of block/code (without module name prefix): '''gain'''
Enter valid argument list, including default arguments: ''(leave blank)''
Add Python QA code? [y/N] '''N'''
Add C++ QA code? [y/N] '''N'''
Block NoC ID (Hexadecimal): ''(Enter Noc ID of your block)''
Skip Block Controllers Generation? [UHD block ctrl files] [y/N] '''N'''
Skip Block interface files Generation? [GRC block ctrl files] [y/N] '''N'''

''Note: Noc IDs have been reduced from 64-bits in RFNoC 3 to 32-bits in RFNoC 4''

The following are the relevant files that need to be updated when migrating your RFNoC Block.

rfnoc-example/
grc/
example_gain.block.yml – RFNoC Block GNU Radio Companion YAML file
examples/
gain.grc – Example flowgraph using gain RFNoC Block
include/tutorial/
gain.h – GNU Radio block C++ header
gain_block_ctrl.hpp – RFNoC Block Controller C++ header
lib/
gain_impl.cc – GNU Radio block C++ source
gain_impl.h – GNU Radio block C++ header
gain_block_ctrl_impl.cpp – RFNoC Block Controller C++ source
rfnoc/blocks/
gain.yml – RFNoC Block Description YAML file
rfnoc/fpga/rfnoc_block_gain
noc_shell_gain.v – RFNoC Block Noc Shell Verilog Source
rfnoc_block_gain.v – RFNoC Block Verilog Source
rfnoc_block_gain_tb.v – RFNoC Block Testbench
rfnoc/icores
gain_x310_rfnoc_image_core.yml – Image Core YAML file with gain block

====Building OOT module====

cd rfnoc-tutorial
mkdir build; cd build
cmake -DUHD_FPGA_DIR=''(path to uhd/fpga directory)'' ..
make
sudo make install

====Running a testbench====
CMake automatically creates makefile targets to run the generated testbench code for each added RFNoC block. For example, here is how to run the gain block testbench:

cd rfnoc-tutorial/build
make rfnoc_block_gain_tb

====Building a FPGA image====
CMake automatically creates makefile targets to build FPGA images using the generated image core yaml files found in rfnoc/icore. Every RFNoC block created by rfnocmodtool automatically has an image core yaml file generated in that directory. For example, here is how to build an FPGA image using the image core yaml file generated for the gain block:

cd rfnoc-tutorial/build
make gain_x310_rfnoc_image_core

===Migrating a Standalone UHD C++ Application===

For applications that only use the UHD API, an example out-of-tree (UHD source tree) RFNoC block exists called rfnoc-example. It is located in the UHD source at uhd/host/examples/rfnoc-example. This directory can be copied outside of the UHD source tree and used a starting point to migrate your RFNoC block.

The following are the relevant files that need to be updated when migrating your RFNoC Block.

rfnoc-example/
apps/
init_gain_block.cpp – Example C++ application testing gain block
blocks/
gain.yml – RFNoC Block Description YAML file
fpga/rfnoc_block_gain
noc_shell_gain.v – RFNoC Block Noc Shell Verilog Source
rfnoc_block_gain.v – RFNoC Block Verilog Source
rfnoc_block_gain_tb.v – RFNoC Block Testbench
icores/
x310_rfnoc_image_core.yml – Example Image Core YAML file
include/rfnoc/example
gain_block_control.hpp – RFNoC Block Controller C++ header
lib/
gain_block_control.cpp – RFNoC Block Controller C++ source

====Building rfnoc-example====

cd rfnoc-example
mkdir build; cd build
cmake ..
make
sudo make install

====Running a testbench====
CMake automatically creates makefile targets to run RFNoC Block testbench simulations. For every RFNoC block subdirectory listed in the CMakeLists.txt file in the rfnoc-example/fpga directory, a target with the RFNoC block name appended with “_tb” is added as a makefile target. For example, here is how to run the gain RFNoC block testbench:

cd rfnoc-example/build
make rfnoc_block_gain_tb

====Building a FPGA image====
CMake automatically creates makefile targets to build a FPGA image for each image core yaml file listed in the CMakeLists.txt file in the rfnoc-example/icore directory. Each image core yaml file must be listed in the CMakeLists.txt. For example, here is how to build an FPGA image using the image core yaml file generated for the gain block:

cd rfnoc-tutorial/build
make gain_x310_rfnoc_image_core

=Example RFNoC 3 to RFNoC 4 Block Migration=

This ZIP archive, [[File:migration_example.zip]], contains equivalent RFNoC 3 and RFNoC 4 versions of a digital gain RFNoC Block. The following sections will refer to files in this archive to show how the file structure changes when migrating from RFNoC 3 to RFNoC 4.

=UHD Software Migration=

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| Block Description || rfnoc/blocks/gain.xml || lib/gain_block_ctrl_impl.cpp include/example/gain_block_ctrl.hpp
|-
| Block Controller || rfnoc/blocks/gain.yml || lib/gain_block_ctrl_impl.cpp include/example/gain_block_ctrl.hpp
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===Noc Script XML Replaced by Block Description YAML===

RFNoC 3 used Noc Script XML, a domain specific language, to describe the configuration of a RFNoC block: the Noc ID, register names and addresses, args for writing to the registers, and the input/output ports.

RFNoC 4 replaces the Noc Script XML file with an easier to read and edit Block Description YAML file format. From a high level, the Block Description YAML file serves a similar function as the Noc Script XML file, with some similarities and key differences outlined in table below:

{| class="wikitable"
! Item || Noc Script XML || Block Descript YAML || RFNoC 4 Notes
|-
| Block Name
||
<name>gain</name>
||
module_name: gain
||
|-
| Noc ID
||
<id>B160000000000000</id>
||
noc_id: 0xB16
||
Noc ID are limited to 32-bits
|-
| Registers
||
<registers>
<setreg>
<name>GAIN</name>
<address>128</address>
</setreg>
</registers>
||
N/A
||
Registers must be defined in the Block Controller
|-
| Arguments
||
<args>
<arg>
<name>gain</name>
<type>int</type>
...
</arg>
</args>
||
N/A
||
Args are implemented with properties in the Block Controller
|-
| Data Ports
||
<ports>
<sink>
<name>in</name>
</sink>
<source>
<name>out</name>
</source>
</ports>
||
data:
fpga_iface: axis_pyld_ctxt
clk_domain: rfnoc_chdr
inputs:
in:
...
outputs:
out:
...
||
|-
| Control Ports
||
N/A
||
control:
sw_iface: nocscript
fpga_iface: ctrlport
interface_direction: slave
...
||
|-
| Clocking
||
N/A
||
clocks:
- name: rfnoc_chdr
freq: "[]"
- name: rfnoc_ctrl
freq: "[]"
||
|}

''Note: For a more detailed description of the RFNoC 4 Block Description YAML syntax and the various options, see the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].''

===RFNoC API Changes===

Much of the user facing RFNoC software API has not changed or remains very similar between RFNoC 3 and RFNoC 4. The table below outlines some of the notable differences:

{| class="wikitable"
! RFNoC 3 || RFNoC 4 || RFNoC 4 Notes
|-
|
usrp = uhd::device3::make(...)
||
graph = uhd::rfnoc::rfnoc_graph::make()
||
No longer need to create a device3 object
|-
|
usrp->get_block_ctrl(...)
||
graph->get_block(...)
||
Rename
|-
|
N/A
||
graph->enumerate_static_connections()
||
Used to check static connections, usually for detecting hwen a DDC or DUC is statically connected to the radio and requires setting the sample
|-
|
usrp->get_tx_streamer(...)
||
graph->create_tx_streamer(...)
||
Rename
|-
|
usrp->get_rx_streamer(...)
||
graph->create_rx_streamer(...)
||
Rename
|-
|
N/A
||
graph->commit()
||
Commit graph and run initial checks
|-
|
sr_write(...)
||
regs().poke32(...)
||
Address increments by 4
|-
|
sr_read32(...)
||
regs().peek32(...)
||
Address increments by 4
|-
|
sr_read64(...)
||
regs().poke64(...)
||
Address increments by 8
|-
|
set_arg(...)
||
set_property(...)
||
Block args replaced with block properties concept
|-
|
get_arg(...)
||
get_property(...)
||
Block args replaced with block properties concept
|}

===Block Properties===

In RFNoC 3, RFNoC blocks can have arguments (also known as args) that are used to write user registers. This is implemented in the Noc Script XML in the <args> section.

RFNoC 4 expands and generalizes this concept with block properties: a high-level representation of the state of the block. Zero or more properties can be defined by the user in their RFNoC Block’s Block Controller C++ class. When read or written to, they can trigger a call back to a user defined resolver function. The [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification] provides more details on properties in the “Block Properties” section.

The following shows an example of how to migrate a RFNoC 3 Noc Script XML “arg” based register write to a RFNoC 4 property based implementation in the Block Controller:

====RFNoC 3 Noc Script XML snippet====
<registers>
<setreg>
<name>GAIN</name>
<address>128</address>
</setreg>
</registers>

<args>
<arg>
<name>gain</name>
<type>int</type>
<value>1</value>
<check>GE($gain, 0) AND LE($gain, 32767)</check>
<check_message>Gain must be in the range [0, 32767]</check_message>
<action>SR_WRITE("GAIN", $gain)</action>
</arg>
</args>

====RFNoC 4 Block Controller Class====

// <registers>
// <setreg>
// <name>GAIN</name>
// <address>128</address>
// </setreg>
// </registers>
// Note: In RFNoC 4, register addresses can start at address 0 instead of address 128 as in RFNoC 3.
const uint32_t gain_block_ctrl::REG_GAIN_ADDR = 128;
const uint32_t gain_block_ctrl::REG_GAIN_DEFAULT = 1;

class gain_block_ctrl_impl : public gain_block_ctrl
{
public:
RFNOC_BLOCK_CONSTRUCTOR(gain_block_ctrl)
{
_register_props();
}
private:
void _register_props()
{
register_property(&_user_reg, [this]() {
int user_reg = this->_user_reg.get();
// <check>GE($gain, 0) AND LE($gain, 32767)</check>
// <check_message>Gain must be in the range [0, 32767]</check_message>
if (user_reg < 0 || user_reg > 32767) {
throw uhd::value_error("Size value must be in [0,32767]");
}
// <action>SR_WRITE("GAIN", $gain)</action>
this->regs().poke32(REG_USER_ADDR, user_reg);
});
}

// <name>gain</name>
// <type>int</type>
// <value>1</value>
property_t<int> _user_reg{"gain", REG_USER_DEFAULT, {res_source_info::USER}};
}

As the above shows, writing to a register can be replicated with a property and a resolver function. Of course, the resolver function can also be made much more sophisticated. For additional examples, see the in-tree block controllers in uhd/host/lib/rfnoc.

=FPGA Migration=

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| Block Verilog Code || rfnoc/fpga-src/noc_block_gain.v || rfnoc/fpga/rfnoc_block_gain/rfnoc_block_gain.v
|-
| Block Noc Shell || N/A || rfnoc/fpga/rfnoc_block_gain/noc_shell_gain.v
|-
| Block Testbnech || rfnoc/testbench/noc_block_gain/noc_block_gain_tb.sv || rfnoc/fpga/rfnoc_block_gain/rfnoc_block_gain_tb.sv
|-
| Image Core || N/A || rfnoc/icores/gain_x310_rfnoc_image_core.yml
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===Noc Shell Changes===

RFNoC 4 replaces the highly parameterized RFNoC 3 Noc Shell with a per-block customized Noc Shell generated from the block’s Block Description YAML file. The Noc Shell generated via rfnocmodtool or the existing one in rfnoc-example is acceptable for most blocks that require one input and output data port.

====Generating a Custom Noc Shell====

Some blocks may need multiple data ports or other modifications. This requires editing the Block Description YAML file and then using the Python script rfnoc_create_verilog.py (found in uhd/host/utils/rfnoc_blocktool) to generate a new Noc Shell instance.

The argument “-c” is used to provide the YAML file location. “-d” provides the output destination directory.

''Note: It is suggested to not set the destination directory to your existing RFNoC block code, as the script will automatically overwrite the existing code!''

Example usage:
rfnoc_create_verilog.py -c ./rfnoc-example/rfnoc/blocks/gain.yml -d ./output/

====Changing Noc ID without using rfnoc_create_verilog====

In the generated Noc Shell Verilog code, a block’s Noc ID can be changed by updating the NOC_ID parameter on the ''backend_iface'' module. Make sure this matches the Noc ID in both the Block Description YAML file and Block Controller C++ code.

====Goodbye AXI Wrapper====

The RFNoC 3 version of Noc Shell outputs / accepts CHDR data packets consisting of a header, optional timestamp, and payload on a 64-bit AXI stream bus. Most designs then used a module called AXI Wrapper to handle the conversion between CHDR data packets and sample streams on a 32-bit AXI stream bus. AXI Wrapper also supported SIMPLE_MODE which for some use cases could transparently handle the header portion of the CHDR data packet. Otherwise, the user would need to set the header via m_axis_data_tuser.

In RFNoC 4, Noc Shell has absorbed AXI Wrapper’s functionality. Noc Shell outputs two AXI stream buses per input / output port: a payload and context bus. The payload bus is in most cases identical to AXI Wrapper’s output: a 32-bit stream of samples on an AXI Stream bus with packets delimited by tlast. The context AXI stream bus carries the header, optional timestamp, and optional metadata. If your block used AXI Wrapper’s SIMPLE_MODE, then you can loop the context bus back into Noc Shell. If not, you will need to modify the context bus data. Refer to the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification] for the format and timing diagram of the context bus.

''Important Note: If your block used the AXI Rate Change module, Noc Shell has another data port mode to support this use case called '''axis_data''' that can be set in the Block Descriptor YAML file (see the fpga_iface entry). This mode causes the Noc Shell data ports to look more like AXI Wrapper’s and therefore makes them compatible with AXI Rate Change. See the DDC, DUC, or Keep One in N RFNoC Blocks for an example.''

===Settings Bus replaced by CtrlPort===

CtrlPort replaces the Settings Bus in RFNoC 4. The CtrlPort bus is similar to the Settings Bus with a few key differences. The table below compares the signaling between the two bus formats and provides notes on any differences. Timing diagrams and additional information on the CtrlPort bus is also available in the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].

{| class="wikitable"
! Settings Bus (RFNoC 3) || CtrlPort (RFNoC 4) || RFNoC 4 Notes
|-
| set_stb || ctrlport_reg_wr || Write strobe
|-
| set_addr || ctrlport_req_addr || 20-bits instead of 8-bits, increments by 4 instead of by 1, no reserved addresses (versus addresses 0-127 for Settings Bus)
|-
| set_data || ctrlport_req_data || Write data
|-
| N/A || ctrlport_req_rd || Read strobe equivalent of ctrlport_req_wr
|-
| rb_addr || N/A || CtrlPort uses ctrlport_req_addr for both '''read and write''' addresses
|-
| rb_data || ctrlport_resp_data || Read data, 32-bits instead of 64-bits
|-
| rb_stb || N/A || CtrlPort requires ack strobe for '''reads and writes'''
|}

One additional difference when using CtrlPort is that there is not an equivalent Settings Register module. The bus is simple enough to setup a clocked process to handle reading from and writing to registers. See the Verilog example below:

// Note: Register addresses increment by 4
localparam REG_USER_ADDR = 0; // Address for example user register
localparam REG_USER_DEFAULT = 0; // Default value for user register

reg [31:0] reg_user = REG_USER_DEFAULT;

always @(posedge ctrlport_clk) begin
if (ctrlport_rst) begin
reg_user = REG_USER_DEFAULT;
end else begin
// Default assignment
m_ctrlport_resp_ack <= 0;

// Read user register
if (m_ctrlport_req_rd) begin // Read request
case (m_ctrlport_req_addr)
REG_USER_ADDR: begin
m_ctrlport_resp_ack <= 1;
m_ctrlport_resp_data <= reg_user;
end
endcase
end

// Write user register
if (m_ctrlport_req_wr) begin // Write requst
case (m_ctrlport_req_addr)
REG_USER_ADDR: begin
m_ctrlport_resp_ack <= 1;
reg_user <= m_ctrlport_req_data[31:0];
end
endcase
end
end
end

''Important Note: For blocks that make heavy use of the Settings Bus and/or Settings Registers, there is a CtrlPort to Settings Bus bridge available called '''ctrlport_to_settings_bus'''. See the Keep One In N RFNoC Block for example code on how to interface with it.''

===Testbench Infrastructure===

While RFNoC 4 does overhaul the RFNoC 3 testbench infrastructure API, most of the high level concepts remain the same. The table below outlines some of the commonly used RFNoC 3 functions / code and the RFNoC 4 equivalent.

{| class="wikitable"
! Operation || RFNoC 3 || RFNoC 4
|-
| Setup RFNoC
||
`RFNOC_SIM_INIT(...)
`RFNOC_ADD_BLOCK(...)
`RFNOC_CONNECT(...)
||
RfnocBlockCtrlBfm #(...) blk_ctrl = new(...);
blk_ctrl.connect_master_data_port(...)
blk_ctrl.connect_slave_data_port(...)
''Note: Instantiate one Block Controller BFM per RFNoC Block''
|-
| Setup Test Cases
||
`TEST_CASE_START(...)
`TEST_CASE_DONE(...)
||
test.start_test(...)
test.end_test()
|-
| Register Read
||
tb_streamer.read_reg(...)
||
blk_ctrl.reg_read(...)
|-
| Register Write
||
tb_streamer.write_reg(...)
||
blk_ctrl.reg_write(...)
|-
| Send Data / Samples
||
tb_streamer.send(...)
||
blk_ctrl.send_items(...)
|-
| Receive Data / Samples
||
tb_streamer.recv(...)
||
blk_ctrl.recv_items(...)
|}

===Building FPGA images using Image Core YAML Files===

RFNoC 4 replaces uhd_image_builder, the RFNoC 3 FPGA image building tool, with a new tool called rfnoc_image_builder. This tool produces a FPGA bitstream based on an Image Core YAML file that describes the device configuration (e.g. X310 with dual 10GigE) and included RFNoC blocks along with their connections (both static and dynamic), clocking, and I/O.

Both rfnocmodtool and the UHD in-tree example called rfnoc-example automatically setup make targets to handle running rfnoc_image_builder. If you want to use rfnoc_image_builder directly, more details can be found in the [https://kb.ettus.com/Getting_Started_with_RFNoC_in_UHD_4.0 Getting Started with RFNoC in UHD 4.0].

=GNU Radio Software Migration=

RFNoC 4 supports GNU Radio 3.8 only. Most of your RFNoC Block’s GNU Radio related changes will be due to API differences between GNU Radio 3.7 to 3.8. These changes are outside of the scope of this article. Instead, refer to [https://wiki.gnuradio.org/index.php/GNU_Radio_3.8_OOT_Module_Porting_Guide GNU Radio 3.8 Migration Guide] and [https://wiki.gnuradio.org/index.php/YAML_GRC GNU Radio Companion YAML] sites for more information.

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| GNU Radio Block || lib/gain_impl.cc lib/gain_impl.h include/example/gain.h || lib/gain_impl.cc lib/gain_impl.h include/example/gain.h
|-
| GRC Block Description || grc/gain.xml || grc/gain.yml
|-
| Example GRC Flowgraph || examples/gain.grc || examples/gain.grc
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===RX & TX Streamer Blocks===

When transition between a RFNoC block and a GNU Radio block or vice versa, you must insert either a RX stream or TX streamer block respectively. This differs from RFNoC 3, where a RFNoC block could be directly connected to a GNU Radio block.

[[File:rx_tx_streamer.png|border]]

===Setting RFNoC Block Properties Directly in GNU Radio===

The base class for RFNoC Block’s in GNU Radio have a set of functions that provide a shortcut to getting and setting properties without writing custom class methods. The table below lists the functions.

{| class="wikitable"
! Property Type || Set Property || Get Property
|-
| Integer || set_int_property(...) || get_int_property(...)
|-
| Double || set_double_property(...) || get_double_property(...)
|-
| Bool || set_bool_property(...) || get_bool_property(...)
|-
| String || set_string_property(...) || get_string_property(...)
|-
|}

'''Example code for GNU Radio Companion YAML Block Description file'''
templates:
imports: |-
import example
make: |-
example.gain(
self.rfnoc_graph,
uhd.device_addr(${block_args}),
${device_select},
${instance_select})
self.${id}.set_int_property('gain', ${gain})
callbacks:
- set_int_property('gain', ${gain})

RFNoC 4 Migration Guide

2021-10-29T10:04:54Z

MartinAnderseck: /* Dependencies (Ubuntu 20.04) */ Adding full dependencies list to align with other sources

=Abstract=

The UHD 4.0 release includes a major upgrade to the RFNoC framework called RFNoC 4. This article is a guide to aid users in migrating their existing RFNoC blocks from RFNoC 3 to RFNoC 4. The RFNoC Block Development Environment section provides guidance on how to setup an environment for developing out-of-tree RFNoC blocks in RFNoC 4. The UHD, FPGA, GNU Radio Migration sections provide general information on topics that most users will encounter when migrating their blocks. Finally, an equivalent RFNoC 3 and RFNoC 4 implementation of a digital gain RFNoC Block has been provided as a reference.

=Prerequisites=

===Dependencies (Ubuntu 20.04)===
sudo apt-get -y install autoconf automake build-essential ccache cmake cpufrequtils \
doxygen ethtool fort77 g++ gir1.2-gtk-3.0 git gobject-introspection gpsd gpsd-clients \
inetutils-tools libasound2-dev libboost-all-dev libcomedi-dev libcppunit-dev libfftw3-bin \
libfftw3-dev libfftw3-doc libfontconfig1-dev libgmp-dev libgps-dev libgsl-dev liblog4cpp5-dev \
libncurses5 libncurses5-dev libpulse-dev libqt5opengl5-dev libqwt-qt5-dev libsdl1.2-dev libtool \
libudev-dev libusb-1.0-0 libusb-1.0-0-dev libusb-dev libxi-dev libxrender-dev libzmq3-dev \
libzmq5 ncurses-bin python3-cheetah python3-click python3-click-plugins python3-click-threading \
python3-dev python3-docutils python3-gi python3-gi-cairo python3-gps python3-lxml python3-mako \
python3-numpy python3-numpy-dbg python3-opengl python3-pyqt5 python3-requests python3-scipy \
python3-setuptools python3-six python3-sphinx python3-yaml python3-zmq python3-ruamel.yaml swig wget

===Vivado 2019.1 Design Edition===

Please reference to Xilinx (xilinx.com) for installation instructions.

''Note: The dependencies step above included installing libtinfo5 libncurses5, which is a workaround for getting Vivado 2019.1 to run on Ubunbtu 20.04''

===UHD 4.0===
git clone --branch UHD-4.0 https://github.com/ettusresearch/uhd.git uhd
mkdir uhd/host/build; cd uhd/host/build
cmake ..
make
sudo make install

===GNU Radio 3.8===
'' Note: If your design does not use GNU Radio, then installing GNU Radio and gr-ettus is not required ''

git clone --branch maint-3.8 --recursive https://github.com/gnuradio/gnuradio.git gnuradio
mkdir gnuradio/build; cd gnuradio/build;
cmake ..
make
sudo make install

===gr-ettus===
git clone --branch maint-3.8-uhd4.0 https://github.com/ettusresearch/gr-ettus.git gr-ettus
mkdir gr-ettus/build; cd gr-ettus/build;
cmake -DENABLE_QT=True ..
make
sudo make install

=RFNoC Block Development Environment=

Two options exist for developing RFNoC blocks depending on whether the your RFNoC block integrates with GNU Radio in an out-of-tree module or if it only uses UHD’s C++ API in a standalone application. The sections below outline how to setup the development environment for each scenario.

===Migrating a GNU Radio Out-of-Tree Module===

The tool rfnocmodtool automates the process of creating GNU Radio out-of-tree (OOT) modules that also have support for RFNoC blocks. This tool is part of gr-ettus and it has been ported to RFNoC 4.

Due to changes in almost every source file, it is recommended to use rfnocmodtool to generate a new RFNoC block from scratch and then update the generated “skeleton” files.

====Creating a RFNoC Block with rfnocmodtool====

The following steps show how to create an OOT module called ''example'' and RFNoC block called ''gain'' using rfnocmodtool. The naming is only for example purposes.

rfnocmodtool newmod
Name of the new module: '''example'''

cd rfnoc-tutorial
rfnocmodtool add
Enter name of block/code (without module name prefix): '''gain'''
Enter valid argument list, including default arguments: ''(leave blank)''
Add Python QA code? [y/N] '''N'''
Add C++ QA code? [y/N] '''N'''
Block NoC ID (Hexadecimal): ''(Enter Noc ID of your block)''
Skip Block Controllers Generation? [UHD block ctrl files] [y/N] '''N'''
Skip Block interface files Generation? [GRC block ctrl files] [y/N] '''N'''

''Note: Noc IDs have been reduced from 64-bits in RFNoC 3 to 32-bits in RFNoC 4''

The following are the relevant files that need to be updated when migrating your RFNoC Block.

rfnoc-example/
grc/
example_gain.block.yml – RFNoC Block GNU Radio Companion YAML file
examples/
gain.grc – Example flowgraph using gain RFNoC Block
include/tutorial/
gain.h – GNU Radio block C++ header
gain_block_ctrl.hpp – RFNoC Block Controller C++ header
lib/
gain_impl.cc – GNU Radio block C++ source
gain_impl.h – GNU Radio block C++ header
gain_block_ctrl_impl.cpp – RFNoC Block Controller C++ source
rfnoc/blocks/
gain.yml – RFNoC Block Description YAML file
rfnoc/fpga/rfnoc_block_gain
noc_shell_gain.v – RFNoC Block Noc Shell Verilog Source
rfnoc_block_gain.v – RFNoC Block Verilog Source
rfnoc_block_gain_tb.v – RFNoC Block Testbench
rfnoc/icores
gain_x310_rfnoc_image_core.yml – Image Core YAML file with gain block

====Building OOT module====

cd rfnoc-tutorial
mkdir build; cd build
cmake -DUHD_FPGA_DIR=''(path to uhd/fpga directory)'' ..
make
sudo make install

====Running a testbench====
CMake automatically creates makefile targets to run the generated testbench code for each added RFNoC block. For example, here is how to run the gain block testbench:

cd rfnoc-tutorial/build
make rfnoc_block_gain_tb

====Building a FPGA image====
CMake automatically creates makefile targets to build FPGA images using the generated image core yaml files found in rfnoc/icore. Every RFNoC block created by rfnocmodtool automatically has an image core yaml file generated in that directory. For example, here is how to build an FPGA image using the image core yaml file generated for the gain block:

cd rfnoc-tutorial/build
make gain_x310_rfnoc_image_core

===Migrating a Standalone UHD C++ Application===

For applications that only use the UHD API, an example out-of-tree (UHD source tree) RFNoC block exists called rfnoc-example. It is located in the UHD source at uhd/host/examples/rfnoc-example. This directory can be copied outside of the UHD source tree and used a starting point to migrate your RFNoC block.

The following are the relevant files that need to be updated when migrating your RFNoC Block.

rfnoc-example/
apps/
init_gain_block.cpp – Example C++ application testing gain block
blocks/
gain.yml – RFNoC Block Description YAML file
fpga/rfnoc_block_gain
noc_shell_gain.v – RFNoC Block Noc Shell Verilog Source
rfnoc_block_gain.v – RFNoC Block Verilog Source
rfnoc_block_gain_tb.v – RFNoC Block Testbench
icores/
x310_rfnoc_image_core.yml – Example Image Core YAML file
include/rfnoc/example
gain_block_control.hpp – RFNoC Block Controller C++ header
lib/
gain_block_control.cpp – RFNoC Block Controller C++ source

====Building rfnoc-example====

cd rfnoc-example
mkdir build; cd build
cmake ..
make
sudo make install

====Running a testbench====
CMake automatically creates makefile targets to run RFNoC Block testbench simulations. For every RFNoC block subdirectory listed in the CMakeLists.txt file in the rfnoc-example/fpga directory, a target with the RFNoC block name appended with “_tb” is added as a makefile target. For example, here is how to run the gain RFNoC block testbench:

cd rfnoc-example/build
make rfnoc_block_gain_tb

====Building a FPGA image====
CMake automatically creates makefile targets to build a FPGA image for each image core yaml file listed in the CMakeLists.txt file in the rfnoc-example/icore directory. Each image core yaml file must be listed in the CMakeLists.txt. For example, here is how to build an FPGA image using the image core yaml file generated for the gain block:

cd rfnoc-tutorial/build
make gain_x310_rfnoc_image_core

=Example RFNoC 3 to RFNoC 4 Block Migration=

This ZIP archive, [[File:migration_example.zip]], contains equivalent RFNoC 3 and RFNoC 4 versions of a digital gain RFNoC Block. The following sections will refer to files in this archive to show how the file structure changes when migrating from RFNoC 3 to RFNoC 4.

=UHD Software Migration=

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| Block Description || rfnoc/blocks/gain.xml || lib/gain_block_ctrl_impl.cpp include/example/gain_block_ctrl.hpp
|-
| Block Controller || rfnoc/blocks/gain.yml || lib/gain_block_ctrl_impl.cpp include/example/gain_block_ctrl.hpp
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===Noc Script XML Replaced by Block Description YAML===

RFNoC 3 used Noc Script XML, a domain specific language, to describe the configuration of a RFNoC block: the Noc ID, register names and addresses, args for writing to the registers, and the input/output ports.

RFNoC 4 replaces the Noc Script XML file with an easier to read and edit Block Description YAML file format. From a high level, the Block Description YAML file serves a similar function as the Noc Script XML file, with some similarities and key differences outlined in table below:

{| class="wikitable"
! Item || Noc Script XML || Block Descript YAML || RFNoC 4 Notes
|-
| Block Name
||
<name>gain</name>
||
module_name: gain
||
|-
| Noc ID
||
<id>B160000000000000</id>
||
noc_id: 0xB16
||
Noc ID are limited to 32-bits
|-
| Registers
||
<registers>
<setreg>
<name>GAIN</name>
<address>128</address>
</setreg>
</registers>
||
N/A
||
Registers must be defined in the Block Controller
|-
| Arguments
||
<args>
<arg>
<name>gain</name>
<type>int</type>
...
</arg>
</args>
||
N/A
||
Args are implemented with properties in the Block Controller
|-
| Data Ports
||
<ports>
<sink>
<name>in</name>
</sink>
<source>
<name>out</name>
</source>
</ports>
||
data:
fpga_iface: axis_pyld_ctxt
clk_domain: rfnoc_chdr
inputs:
in:
...
outputs:
out:
...
||
|-
| Control Ports
||
N/A
||
control:
sw_iface: nocscript
fpga_iface: ctrlport
interface_direction: slave
...
||
|-
| Clocking
||
N/A
||
clocks:
- name: rfnoc_chdr
freq: "[]"
- name: rfnoc_ctrl
freq: "[]"
||
|}

''Note: For a more detailed description of the RFNoC 4 Block Description YAML syntax and the various options, see the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].''

===RFNoC API Changes===

Much of the user facing RFNoC software API has not changed or remains very similar between RFNoC 3 and RFNoC 4. The table below outlines some of the notable differences:

{| class="wikitable"
! RFNoC 3 || RFNoC 4 || RFNoC 4 Notes
|-
|
usrp = uhd::device3::make(...)
||
graph = uhd::rfnoc::rfnoc_graph::make()
||
No longer need to create a device3 object
|-
|
usrp->get_block_ctrl(...)
||
graph->get_block(...)
||
Rename
|-
|
N/A
||
graph->enumerate_static_connections()
||
Used to check static connections, usually for detecting hwen a DDC or DUC is statically connected to the radio and requires setting the sample
|-
|
usrp->get_tx_streamer(...)
||
graph->create_tx_streamer(...)
||
Rename
|-
|
usrp->get_rx_streamer(...)
||
graph->create_rx_streamer(...)
||
Rename
|-
|
N/A
||
graph->commit()
||
Commit graph and run initial checks
|-
|
sr_write(...)
||
regs().poke32(...)
||
Address increments by 4
|-
|
sr_read32(...)
||
regs().peek32(...)
||
Address increments by 4
|-
|
sr_read64(...)
||
regs().poke64(...)
||
Address increments by 8
|-
|
set_arg(...)
||
set_property(...)
||
Block args replaced with block properties concept
|-
|
get_arg(...)
||
get_property(...)
||
Block args replaced with block properties concept
|}

===Block Properties===

In RFNoC 3, RFNoC blocks can have arguments (also known as args) that are used to write user registers. This is implemented in the Noc Script XML in the <args> section.

RFNoC 4 expands and generalizes this concept with block properties: a high-level representation of the state of the block. Zero or more properties can be defined by the user in their RFNoC Block’s Block Controller C++ class. When read or written to, they can trigger a call back to a user defined resolver function. The [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification] provides more details on properties in the “Block Properties” section.

The following shows an example of how to migrate a RFNoC 3 Noc Script XML “arg” based register write to a RFNoC 4 property based implementation in the Block Controller:

====RFNoC 3 Noc Script XML snippet====
<registers>
<setreg>
<name>GAIN</name>
<address>128</address>
</setreg>
</registers>

<args>
<arg>
<name>gain</name>
<type>int</type>
<value>1</value>
<check>GE($gain, 0) AND LE($gain, 32767)</check>
<check_message>Gain must be in the range [0, 32767]</check_message>
<action>SR_WRITE("GAIN", $gain)</action>
</arg>
</args>

====RFNoC 4 Block Controller Class====

// <registers>
// <setreg>
// <name>GAIN</name>
// <address>128</address>
// </setreg>
// </registers>
// Note: In RFNoC 4, register addresses can start at address 0 instead of address 128 as in RFNoC 3.
const uint32_t gain_block_ctrl::REG_GAIN_ADDR = 128;
const uint32_t gain_block_ctrl::REG_GAIN_DEFAULT = 1;

class gain_block_ctrl_impl : public gain_block_ctrl
{
public:
RFNOC_BLOCK_CONSTRUCTOR(gain_block_ctrl)
{
_register_props();
}
private:
void _register_props()
{
register_property(&_user_reg, [this]() {
int user_reg = this->_user_reg.get();
// <check>GE($gain, 0) AND LE($gain, 32767)</check>
// <check_message>Gain must be in the range [0, 32767]</check_message>
if (user_reg < 0 || user_reg > 32767) {
throw uhd::value_error("Size value must be in [0,32767]");
}
// <action>SR_WRITE("GAIN", $gain)</action>
this->regs().poke32(REG_USER_ADDR, user_reg);
});
}

// <name>gain</name>
// <type>int</type>
// <value>1</value>
property_t<int> _user_reg{"gain", REG_USER_DEFAULT, {res_source_info::USER}};
}

As the above shows, writing to a register can be replicated with a property and a resolver function. Of course, the resolver function can also be made much more sophisticated. For additional examples, see the in-tree block controllers in uhd/host/lib/rfnoc.

=FPGA Migration=

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| Block Verilog Code || rfnoc/fpga-src/noc_block_gain.v || rfnoc/fpga/rfnoc_block_gain/rfnoc_block_gain.v
|-
| Block Noc Shell || N/A || rfnoc/fpga/rfnoc_block_gain/noc_shell_gain.v
|-
| Block Testbnech || rfnoc/testbench/noc_block_gain/noc_block_gain_tb.sv || rfnoc/fpga/rfnoc_block_gain/rfnoc_block_gain_tb.sv
|-
| Image Core || N/A || rfnoc/icores/gain_x310_rfnoc_image_core.yml
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===Noc Shell Changes===

RFNoC 4 replaces the highly parameterized RFNoC 3 Noc Shell with a per-block customized Noc Shell generated from the block’s Block Description YAML file. The Noc Shell generated via rfnocmodtool or the existing one in rfnoc-example is acceptable for most blocks that require one input and output data port.

====Generating a Custom Noc Shell====

Some blocks may need multiple data ports or other modifications. This requires editing the Block Description YAML file and then using the Python script rfnoc_create_verilog.py (found in uhd/host/utils/rfnoc_blocktool) to generate a new Noc Shell instance.

The argument “-c” is used to provide the YAML file location. “-d” provides the output destination directory.

''Note: It is suggested to not set the destination directory to your existing RFNoC block code, as the script will automatically overwrite the existing code!''

Example usage:
rfnoc_create_verilog.py -c ./rfnoc-example/rfnoc/blocks/gain.yml -d ./output/

====Changing Noc ID without using rfnoc_create_verilog====

In the generated Noc Shell Verilog code, a block’s Noc ID can be changed by updating the NOC_ID parameter on the ''backend_iface'' module. Make sure this matches the Noc ID in both the Block Description YAML file and Block Controller C++ code.

====Goodbye AXI Wrapper====

The RFNoC 3 version of Noc Shell outputs / accepts CHDR data packets consisting of a header, optional timestamp, and payload on a 64-bit AXI stream bus. Most designs then used a module called AXI Wrapper to handle the conversion between CHDR data packets and sample streams on a 32-bit AXI stream bus. AXI Wrapper also supported SIMPLE_MODE which for some use cases could transparently handle the header portion of the CHDR data packet. Otherwise, the user would need to set the header via m_axis_data_tuser.

In RFNoC 4, Noc Shell has absorbed AXI Wrapper’s functionality. Noc Shell outputs two AXI stream buses per input / output port: a payload and context bus. The payload bus is in most cases identical to AXI Wrapper’s output: a 32-bit stream of samples on an AXI Stream bus with packets delimited by tlast. The context AXI stream bus carries the header, optional timestamp, and optional metadata. If your block used AXI Wrapper’s SIMPLE_MODE, then you can loop the context bus back into Noc Shell. If not, you will need to modify the context bus data. Refer to the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification] for the format and timing diagram of the context bus.

''Important Note: If your block used the AXI Rate Change module, Noc Shell has another data port mode to support this use case called '''axis_data''' that can be set in the Block Descriptor YAML file (see the fpga_iface entry). This mode causes the Noc Shell data ports to look more like AXI Wrapper’s and therefore makes them compatible with AXI Rate Change. See the DDC, DUC, or Keep One in N RFNoC Blocks for an example.''

===Settings Bus replaced by CtrlPort===

CtrlPort replaces the Settings Bus in RFNoC 4. The CtrlPort bus is similar to the Settings Bus with a few key differences. The table below compares the signaling between the two bus formats and provides notes on any differences. Timing diagrams and additional information on the CtrlPort bus is also available in the [https://files.ettus.com/app_notes/RFNoC_Specification.pdf RFNoC Specification].

{| class="wikitable"
! Settings Bus (RFNoC 3) || CtrlPort (RFNoC 4) || RFNoC 4 Notes
|-
| set_stb || ctrlport_reg_wr || Write strobe
|-
| set_addr || ctrlport_req_addr || 20-bits instead of 8-bits, increments by 4 instead of by 1, no reserved addresses (versus addresses 0-127 for Settings Bus)
|-
| set_data || ctrlport_req_data || Write data
|-
| N/A || ctrlport_req_rd || Read strobe equivalent of ctrlport_req_wr
|-
| rb_addr || N/A || CtrlPort uses ctrlport_req_addr for both '''read and write''' addresses
|-
| rb_data || ctrlport_resp_data || Read data, 32-bits instead of 64-bits
|-
| rb_stb || N/A || CtrlPort requires ack strobe for '''reads and writes'''
|}

One additional difference when using CtrlPort is that there is not an equivalent Settings Register module. The bus is simple enough to setup a clocked process to handle reading from and writing to registers. See the Verilog example below:

// Note: Register addresses increment by 4
localparam REG_USER_ADDR = 0; // Address for example user register
localparam REG_USER_DEFAULT = 0; // Default value for user register

reg [31:0] reg_user = REG_USER_DEFAULT;

always @(posedge ctrlport_clk) begin
if (ctrlport_rst) begin
reg_user = REG_USER_DEFAULT;
end else begin
// Default assignment
m_ctrlport_resp_ack <= 0;

// Read user register
if (m_ctrlport_req_rd) begin // Read request
case (m_ctrlport_req_addr)
REG_USER_ADDR: begin
m_ctrlport_resp_ack <= 1;
m_ctrlport_resp_data <= reg_user;
end
endcase
end

// Write user register
if (m_ctrlport_req_wr) begin // Write requst
case (m_ctrlport_req_addr)
REG_USER_ADDR: begin
m_ctrlport_resp_ack <= 1;
reg_user <= m_ctrlport_req_data[31:0];
end
endcase
end
end
end

''Important Note: For blocks that make heavy use of the Settings Bus and/or Settings Registers, there is a CtrlPort to Settings Bus bridge available called '''ctrlport_to_settings_bus'''. See the Keep One In N RFNoC Block for example code on how to interface with it.''

===Testbench Infrastructure===

While RFNoC 4 does overhaul the RFNoC 3 testbench infrastructure API, most of the high level concepts remain the same. The table below outlines some of the commonly used RFNoC 3 functions / code and the RFNoC 4 equivalent.

{| class="wikitable"
! Operation || RFNoC 3 || RFNoC 4
|-
| Setup RFNoC
||
`RFNOC_SIM_INIT(...)
`RFNOC_ADD_BLOCK(...)
`RFNOC_CONNECT(...)
||
RfnocBlockCtrlBfm #(...) blk_ctrl = new(...);
blk_ctrl.connect_master_data_port(...)
blk_ctrl.connect_slave_data_port(...)
''Note: Instantiate one Block Controller BFM per RFNoC Block''
|-
| Setup Test Cases
||
`TEST_CASE_START(...)
`TEST_CASE_DONE(...)
||
test.start_test(...)
test.end_test()
|-
| Register Read
||
tb_streamer.read_reg(...)
||
blk_ctrl.reg_read(...)
|-
| Register Write
||
tb_streamer.write_reg(...)
||
blk_ctrl.reg_write(...)
|-
| Send Data / Samples
||
tb_streamer.send(...)
||
blk_ctrl.send_items(...)
|-
| Receive Data / Samples
||
tb_streamer.recv(...)
||
blk_ctrl.recv_items(...)
|}

===Building FPGA images using Image Core YAML Files===

RFNoC 4 replaces uhd_image_builder, the RFNoC 3 FPGA image building tool, with a new tool called rfnoc_image_builder. This tool produces a FPGA bitstream based on an Image Core YAML file that describes the device configuration (e.g. X310 with dual 10GigE) and included RFNoC blocks along with their connections (both static and dynamic), clocking, and I/O.

Both rfnocmodtool and the UHD in-tree example called rfnoc-example automatically setup make targets to handle running rfnoc_image_builder. If you want to use rfnoc_image_builder directly, more details can be found in the [https://kb.ettus.com/Getting_Started_with_RFNoC_in_UHD_4.0 Getting Started with RFNoC in UHD 4.0].

=GNU Radio Software Migration=

RFNoC 4 supports GNU Radio 3.8 only. Most of your RFNoC Block’s GNU Radio related changes will be due to API differences between GNU Radio 3.7 to 3.8. These changes are outside of the scope of this article. Instead, refer to [https://wiki.gnuradio.org/index.php/GNU_Radio_3.8_OOT_Module_Porting_Guide GNU Radio 3.8 Migration Guide] and [https://wiki.gnuradio.org/index.php/YAML_GRC GNU Radio Companion YAML] sites for more information.

Migration reference files for this section from Gain RFNoC Block example:

{| class="wikitable"
! Description || RFNoC 3 Files || RFNoC 4 Files
|-
| GNU Radio Block || lib/gain_impl.cc lib/gain_impl.h include/example/gain.h || lib/gain_impl.cc lib/gain_impl.h include/example/gain.h
|-
| GRC Block Description || grc/gain.xml || grc/gain.yml
|-
| Example GRC Flowgraph || examples/gain.grc || examples/gain.grc
|}

''Note: Files are relative to the rfnoc-example directory in the respective rfnoc3 and rfnoc4 directories''

===RX & TX Streamer Blocks===

When transition between a RFNoC block and a GNU Radio block or vice versa, you must insert either a RX stream or TX streamer block respectively. This differs from RFNoC 3, where a RFNoC block could be directly connected to a GNU Radio block.

[[File:rx_tx_streamer.png|border]]

===Setting RFNoC Block Properties Directly in GNU Radio===

The base class for RFNoC Block’s in GNU Radio have a set of functions that provide a shortcut to getting and setting properties without writing custom class methods. The table below lists the functions.

{| class="wikitable"
! Property Type || Set Property || Get Property
|-
| Integer || set_int_property(...) || get_int_property(...)
|-
| Double || set_double_property(...) || get_double_property(...)
|-
| Bool || set_bool_property(...) || get_bool_property(...)
|-
| String || set_string_property(...) || get_string_property(...)
|-
|}

'''Example code for GNU Radio Companion YAML Block Description file'''
templates:
imports: |-
import example
make: |-
example.gain(
self.rfnoc_graph,
uhd.device_addr(${block_args}),
${device_select},
${instance_select})
self.${id}.set_int_property('gain', ${gain})
callbacks:
- set_int_property('gain', ${gain})

Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on Linux

2021-10-29T09:58:26Z

MartinAnderseck: Added python3-ruamel.yaml to Ubuntu 20.04 dependencies to align with other sources.

==Application Note Number==
'''AN-445'''

==Revision History==
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2016-05-01
|style="text-align:center;"| Neel Pandeya
|style="text-align:center;"| Initial creation
|}

==Abstract==
This Application Note provides a comprehensive guide for building, installing, and maintaining the open-source toolchain for the USRP (UHD and GNU Radio) from source code on the Linux platform. The Ubuntu and Fedora distributions are specifically discussed. Several other alternate installation methods are also discussed.

http://files.ettus.com/manual/page_build_guide.html#build_instructions_unix

==UHD on Linux==

UHD is fully supported on Linux, using the GCC compiler, and should work on most major Linux distributions.

==Devices==
This document applies only to the USRP X300, X310, B200, B210, B200mini, N200, N210 devices. The E310 and E312 devices are embedded devices, and are fundamentally different from the other non-embedded USRP devices, and are not addressed by this document.

==Install Linux==

If you already have a recent version of Linux installed, then you may be able to skip this section. If you are starting from scratch, or simply want to start with a fresh new installation of Linux, then please follow the instructions and recommendations in this section.

We suggest that you use either Ubuntu 16.04.5, Ubuntu 18.04, Ubuntu 18.10, Fedora 27, 28, 29, and that you use a 64-bit architecture, not a 32-bit architecture. There are several re-spins of Ubuntu, such as Xubuntu, Lubuntu, Kubuntu, Linux Mint, all of which should also work. For the purposes of this document, these re-spins can be considered equivalent. Both Ubuntu and Fedora are known to work well with UHD and GNU Radio.

Download and install Ubuntu, Xubuntu, Linux Mint, or Fedora from the links below. Download the appropriate ISO image, and write it to a USB flash drive. Be sure to verify that the ISO file was not corrupted during the download process by checking the MD5 and/or SHA1 hash.

* [http://www.ubuntu.com/download/desktop Ubuntu download page]
* [http://www.xubuntu.org/getxubuntu/ Xubuntu download page]
* [https://www.linuxmint.com/download.php Linux Mint download page]
* [https://getfedora.org/en/workstation/download/ Fedora download page]

You can learn more about Ubuntu, Xubuntu, Linux Mint, and Fedora at the links below.

* [https://en.wikipedia.org/wiki/Ubuntu_%28operating_system%29 Wikipedia article on Ubuntu]
* [https://en.wikipedia.org/wiki/Xubuntu Wikipedia article on Xubuntu]
* [https://en.wikipedia.org/wiki/Linux_Mint Wikipedia article on Linux Mint]
* [https://en.wikipedia.org/wiki/Fedora_%28operating_system%29 Wikipedia article on Fedora]

There are many tools for writing an ISO image to a USB flash drive. In Linux, you can use the "dd" utility, or the UNetbootin utility. On Ubuntu systems, there is also the Startup Disk Creator utility as well.

* [http://unetbootin.sourceforge.net/ UNetbootin homepage]
* [http://en.wikipedia.org/wiki/UNetbootin Wikipedia article on UNetbootin]

* [https://launchpad.net/usb-creator Startup Disk Creator homepage]
* [https://en.wikipedia.org/wiki/Startup_Disk_Creator Wikipedia article on Startup Disk Creator]
* [http://www.ubuntu.com/download/desktop/create-a-usb-stick-on-ubuntu Article about Startup Disk Creator]

Be sure to use a USB flash drive with at least 8 GB capacity, and use a USB 3.0 flash drive, not a USB 2.0 flash drive. If you use a slower USB 2.0 flash drive, then the install process will take significantly longer.

==Update and Install dependencies==

Before building UHD and GNU Radio, you need to make sure that all the dependencies are first installed.

However, before installing any dependencies, you should first make sure that all the packages that are already installed on your system are up-to-date. You can do this from a GUI, or from the command-line, as shown below.

On Ubuntu systems, run:

sudo apt-get update

On Fedora 21 systems, run:

sudo yum update

On Fedora 22, 23, 24 and 25 systems, run:

sudo dnf update

Once the system has been updated, then install the required dependencies for UHD and GNU Radio.

On Ubuntu 20.04 systems, run:

sudo apt-get -y install autoconf automake build-essential ccache cmake cpufrequtils doxygen ethtool fort77 g++ gir1.2-gtk-3.0 git gobject-introspection gpsd gpsd-clients inetutils-tools libasound2-dev libboost-all-dev libcomedi-dev libcppunit-dev libfftw3-bin libfftw3-dev libfftw3-doc libfontconfig1-dev libgmp-dev libgps-dev libgsl-dev liblog4cpp5-dev libncurses5 libncurses5-dev libpulse-dev libqt5opengl5-dev libqwt-qt5-dev libsdl1.2-dev libtool libudev-dev libusb-1.0-0 libusb-1.0-0-dev libusb-dev libxi-dev libxrender-dev libzmq3-dev libzmq5 ncurses-bin python3-cheetah python3-click python3-click-plugins python3-click-threading python3-dev python3-docutils python3-gi python3-gi-cairo python3-gps python3-lxml python3-mako python3-numpy python3-numpy-dbg python3-opengl python3-pyqt5 python3-requests python3-scipy python3-setuptools python3-six python3-sphinx python3-yaml python3-zmq python3-ruamel.yaml swig wget

On Ubuntu 18.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.14-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses6-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwtplot3d-qt5-dev pyqt4-dev-tools python-qwt5-qt4 cmake git wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq libqwt-dev libqwt6abi1 python-six libgps-dev libgps23 gpsd gpsd-clients python-gps python-setuptools

On Ubuntu 18.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.14-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwtplot3d-qt5-dev pyqt4-dev-tools python-qwt5-qt4 cmake git wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq libqwt-dev libqwt6abi1 python-six libgps-dev libgps23 gpsd gpsd-clients python-gps python-setuptools

On Ubuntu 17.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0v5 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git-core libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq3-dev libzmq5 python-requests python-sphinx libcomedi-dev python-zmq python-setuptools

On Ubuntu 16.04 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0v5 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6abi1 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk3.0 git-core libqt4-dev python-numpy ccache python-opengl libgsl-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq-dev libzmq1 python-requests python-sphinx libcomedi-dev python-zmq python-setuptools

On Ubuntu 15.04 and 15.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libqwt6 libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-1.13-0v5 libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk2.8 git-core libqt4-dev python-numpy ccache python-opengl libgsl0-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq-dev libzmq1 python-requests python-sphinx libcomedi-dev python-zmq python-setuptools

On Ubuntu 14.04 and 14.10 systems, run:

sudo apt-get -y install git swig cmake doxygen build-essential libboost-all-dev libtool libusb-1.0-0 libusb-1.0-0-dev libudev-dev libncurses5-dev libfftw3-bin libfftw3-dev libfftw3-doc libcppunit-1.13-0 libcppunit-dev libcppunit-doc ncurses-bin cpufrequtils python-numpy python-numpy-doc python-numpy-dbg python-scipy python-docutils qt4-bin-dbg qt4-default qt4-doc libqt4-dev libqt4-dev-bin python-qt4 python-qt4-dbg python-qt4-dev python-qt4-doc python-qt4-doc libfftw3-bin libfftw3-dev libfftw3-doc ncurses-bin libncurses5 libncurses5-dev libncurses5-dbg libfontconfig1-dev libxrender-dev libpulse-dev swig g++ automake autoconf libtool python-dev libfftw3-dev libcppunit-dev libboost-all-dev libusb-dev libusb-1.0-0-dev fort77 libsdl1.2-dev python-wxgtk2.8 git-core libqt4-dev python-numpy ccache python-opengl libgsl0-dev python-cheetah python-mako python-lxml doxygen qt4-default qt4-dev-tools libusb-1.0-0-dev libqwt5-qt4-dev libqwtplot3d-qt4-dev pyqt4-dev-tools python-qwt5-qt4 cmake git-core wget libxi-dev gtk2-engines-pixbuf r-base-dev python-tk liborc-0.4-0 liborc-0.4-dev libasound2-dev python-gtk2 libzmq1 libzmq-dev python-requests python-sphinx libcomedi-dev python-setuptools

On Fedora 21 systems, run:

sudo yum -y groupinstall "Engineering and Scientific" "Development Tools" "Software Development Tools" "C Development Tools and Libraries"

sudo yum -y install fftw-devel cppunit-devel wxPython-devel boost-devel alsa-lib-devel numpy gsl-devel python-devel pygsl python-cheetah python-mako python-lxml PyOpenGL qt-devel qt qt4 qt4-devel PyQt4-devel qwt-devel qwtplot3d-qt4-devel libusbx-devel cmake git wget python-docutils cppzmq-devel PyQwt PyQwt-devel qwt-devel gtk2-engines xmlrpc-c-"*" tkinter orc orc-devel python-sphinx SDL-devel swig zeromq2-devel python-zmq comedilib comedilib-devel thrift-devel python-thrift scipy zeromq zeromq-devel

On Fedora 22, 23, 24 and 25 systems, run:

sudo dnf -y groupinstall "Engineering and Scientific" "Development Tools" "C Development Tools and Libraries"

sudo dnf -y install fftw-devel cppunit-devel wxPython-devel boost-devel alsa-lib-devel numpy gsl-devel python-devel pygsl python-cheetah python-mako python-lxml PyOpenGL qt-devel PyQt4-devel qwt-devel qwtplot3d-qt4-devel libusbx-devel cmake python-docutils PyQwt PyQwt-devel gtk2-engines xmlrpc-c-"*" tkinter orc-devel python-sphinx SDL-devel swig perl-ZMQ-LibZMQ2 perl-ZMQ-LibZMQ2 zeromq zeromq-devel python-requests gcc-c++ doxygen zeromq-ada-devel cppzmq-devel perl-ZeroMQ amavisd-new-zeromq amavisd-new-snmp-zeromq php-zmq python-zmq czmq uwsgi-logger-zeromq comedilib comedilib-devel pygtk2 ncurses-"*" thrift-devel python-thrift scipy

After installing the dependencies, you should reboot the system.

If the installation of the dependencies completes without any errors, then you can proceed to build and install UHD and GNU Radio.

==Building and installing UHD from source code==

UHD is open-source, and is hosted on GitHub. You can browse the code online at the link below, which points to version 3.14.0.0, which is the the latest release at the time of this writing.

* [https://github.com/EttusResearch/uhd/tree/v3.14.0.0 UHD repository on GitHub]

There are several good reasons to build GNU Radio from source code, especially for doing development and prototyping. It it enables an easy way to customize the location of the installation, and to install multiple UHD versions in parallel, and switch between them. It also provides much more flexibility in upgrading and downgrading versions, and allows the user to modify the code and create customized versions, which could possibly include a patch or other bug-fix.

To build UHD from source code, clone the GitHub repository, check out a branch or tagged release of the repository, and build and install. Please follow the steps below. Make sure that no USRP device is connected to the system at this point.

First, make a folder to hold the repository.

cd $HOME
mkdir workarea
cd workarea

Next, clone the repository and change into the cloned directory.

git clone <nowiki>https://github.com/EttusResearch/uhd</nowiki>
cd uhd

Next, checkout the desired UHD version. You can get a full listing of tagged releases by running the command:

git tag -l

''Example truncated output of <code>git tag -l</code>:''

<pre>
$ git tag -l
...
release_003_009_004
release_003_009_005
release_003_010_000_000
...
</pre>

'''Note''': As of UHD Version 3.10.0.0, the versioning scheme has changed to be a quadruplet format. Each element and version will follow the format of: '''Major.API.ABI.Patch'''. Additional details on this versioning change can be found [https://files.ettus.com/manual/page_semver.html here].

After identifying the version and corresponding release tag you need, check it out:

# Example: For UHD 3.9.5:
git checkout release_003_009_005

# Example: For UHD 3.14.0.0
git checkout v3.14.0.0

Next, create a build folder within the repository.

cd host
mkdir build
cd build

Next, invoke CMake.

cmake ..

'''Note''': if the shell <code>PATH</code> is set such that <code>/bin</code> comes before <code>/usr/bin</code>, then this step is likely to fail because cmake will set the <code>FIND_ROOT_PATH</code> to <code>/</code> and this setting will fail as a prefix for Boost headers or libraries. The cmake output will include messages such as

-- Boost include directories: /include
-- Boost library directories: /lib/x86_64-linux-gnu

and

CMake Error in lib/CMakeLists.txt:
Imported target "Boost::chrono" includes non-existent path
"/include"
in its INTERFACE_INCLUDE_DIRECTORIES. Possible reasons include:
* The path was deleted, renamed, or moved to another location.
* An install or uninstall procedure did not complete successfully.
* The installation package was faulty and references files it does not provide.

One of the following 3 options should fix this situation:

1. <code>/usr/bin/cmake ..</code>
2. <code>PATH=/usr/bin:$PATH cmake ..</code>
3. <code>cmake -DCMAKE_FIND_ROOT_PATH=/usr ..</code>

Once the cmake command succeeds without errors, build UHD.

make

Next, you can optionally run some basic tests to verify that the build process completed properly.

make test

Next, install UHD, using the default install prefix, which will install UHD under the /usr/local/lib folder. You need to run this as root due to the permissions on that folder.

sudo make install

Next, update the system's shared library cache.

sudo ldconfig

Finally, make sure that the <code>LD_LIBRARY_PATH</code> environment variable is defined and includes the folder under which UHD was installed. Most commonly, you can add the line below to the end of your <code>$HOME/.bashrc</code> file:

export LD_LIBRARY_PATH=/usr/local/lib

On Fedora 22/23/24/25 you will need to set the <code>LD_LIBRARY_PATH</code> to <code>/usr/local/lib64</code>.

export LD_LIBRARY_PATH=/usr/local/lib64

If the <code>LD_LIBRARY_PATH</code> environment variable is already defined with other folders in your <code>$HOME/.bashrc</code> file, then add the line below to the end of your <code>$HOME/.bashrc</code> file to preserve the current settings.

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

For Fedora 21/22/23/24/25

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib64

For this change to take effect, you will need to close the current terminal window, and open a new terminal.

At this point, UHD should be installed and ready to use. You can quickly test this, with no USRP device attached, by running <code>uhd_find_devices</code>. You should see something similar to the following.

<pre>
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.000.HEAD-0-g6e1ac3fc

No UHD Devices Found
</pre>

===Downloading the UHD FPGA Images===
You can now download the UHD FPGA Images for this installation. This can be done by running the command <code>uhd_images_downloader</code>.

$ sudo uhd_images_downloader

Note: Since this installation is being installed to a system level directory (e.g. <code>/usr/local</code>), the <code>uhd_images_downloader</code> command requires <code>sudo</code> privileges.

Example ouput for UHD 3.13.3.0:

<pre>
$ sudo uhd_images_downloader
Images destination: /usr/local/share/uhd/images
Downloading images from: http://files.ettus.com/binaries/images/uhd-images_003.010.003.000-release.zip
Downloading images to: /tmp/tmpm46JDg/uhd-images_003.010.003.000-release.zip
57009 kB / 57009 kB (100%)

Images successfully installed to: /usr/local/share/uhd/images
</pre>

Example output for UHD 3.13:

<pre>
$ sudo uhd_images_downloader
[INFO] Images destination: /usr/local/share/uhd/images
[INFO] No inventory file found at /usr/local/share/uhd/images/inventory.json. Creating an empty one.
00006 kB / 00006 kB (100%) usrp1_b100_fw_default-g6bea23d.zip
19484 kB / 19484 kB (100%) x3xx_x310_fpga_default-g494ae8bb.zip
02757 kB / 02757 kB (100%) usrp2_n210_fpga_default-g6bea23d.zip
02109 kB / 02109 kB (100%) n230_n230_fpga_default-g494ae8bb.zip
00522 kB / 00522 kB (100%) usrp1_b100_fpga_default-g6bea23d.zip
00474 kB / 00474 kB (100%) b2xx_b200_fpga_default-g494ae8bb.zip
02415 kB / 02415 kB (100%) usrp2_n200_fpga_default-g6bea23d.zip
05920 kB / 05920 kB (100%) e3xx_e320_fpga_default-g494ae8bb.zip
15883 kB / 15883 kB (100%) n3xx_n310_fpga_default-g494ae8bb.zip
00506 kB / 00506 kB (100%) b2xx_b205mini_fpga_default-g494ae8bb.zip
18676 kB / 18676 kB (100%) x3xx_x300_fpga_default-g494ae8bb.zip
00017 kB / 00017 kB (100%) octoclock_octoclock_fw_default-g14000041.zip
04839 kB / 04839 kB (100%) usb_common_windrv_default-g14000041.zip
00007 kB / 00007 kB (100%) usrp2_usrp2_fw_default-g6bea23d.zip
00009 kB / 00009 kB (100%) usrp2_n200_fw_default-g6bea23d.zip
00450 kB / 00450 kB (100%) usrp2_usrp2_fpga_default-g6bea23d.zip
00142 kB / 00142 kB (100%) b2xx_common_fw_default-g3ff4186b.zip
00460 kB / 00460 kB (100%) b2xx_b200mini_fpga_default-g494ae8bb.zip
00319 kB / 00319 kB (100%) usrp1_usrp1_fpga_default-g6bea23d.zip
00009 kB / 00009 kB (100%) usrp2_n210_fw_default-g6bea23d.zip
11537 kB / 11537 kB (100%) n3xx_n300_fpga_default-g494ae8bb.zip
05349 kB / 05349 kB (100%) e3xx_e310_fpga_default-g494ae8bb.zip
00866 kB / 00866 kB (100%) b2xx_b210_fpga_default-g494ae8bb.zip
[INFO] Images download complete.

</pre>

==Building and installing GNU Radio from source code==

As with UHD, GNU Radio is open-source and is hosted on GitHub. You can browse the code online at the link below, which points to version <code>v3.7.13.4</code>, which is the the latest release at the time of this writing.

* [https://github.com/gnuradio/gnuradio/tree/v3.7.13.4 GNU Radio repository on GitHub]

Note: GNU Radio is currently transitioning from major branches of 3.7.x.x to 3.8.x.x. It is generally recommend at this time to use either the <code>v3.7.13.4</code> or <code>maint-3.7</code> branch of GNU Radio. The <code>master</code> branch includes many major changes such as converting to use Python 3 and may be unstable.

As with UHD, there are several good reasons to build GNU Radio from source code, especially for doing development and prototyping. It it enables an easy way to customize the location of the installation, and to install multiple GNU Radio versions in parallel, and switch between them. It also provides much more flexibility in upgrading and downgrading versions, and allows the user to modify the code and create customized versions, which could possibly include a patch or other bug-fix.

Similar to the process for UHD, to build GNU Radio from source code, clone the GitHub repository, check out a branch or tagged release of the repository, and build and install. Please follow the steps below. Make sure that no USRP device is connected to the system at this point.

First, make a folder to hold the repository.

cd $HOME
cd workarea

Next, clone the repository.

git clone --recursive <nowiki>https://github.com/gnuradio/gnuradio</nowiki>

Next, go into the repository and check out the desired GNU Radio version.

cd gnuradio

To checkout the <code>v3.7.13.4</code> branch:

git checkout v3.7.13.4

Or to checkout the <code>maint-3.7</code> branch:

git checkout maint-3.7

Next, update the submodules:

git submodule update --init --recursive

Next, create a build folder within the repository, invoke CMake, and build GNU Radio:

mkdir build
cd build
cmake ../
make

Next, you can optionally run some basic tests to verify that the build process completed properly.

make test

Next, install GNU Radio, using the default install prefix, which will install GNU Radio under the /usr/local/lib folder. You need to run this as root due to the permissions on that folder.

sudo make install

Finally, update the system's shared library cache.

sudo ldconfig

At this point, GNU Radio should be installed and ready to use. You can quickly test this, with no USRP device attached, by running the following quick tests.

gnuradio-config-info --version
gnuradio-config-info --prefix
gnuradio-config-info --enabled-components

There is a simple flowgraph that you can run that does not require any USRP hardware. It's called the dialtone test, and it produces a PSTN dial tone on the computer's speakers. Running it verifies that all the libraries can be found, and that the GNU Radio run-time is working.

python $HOME/workarea/gnuradio/gr-audio/examples/python/dial_tone.py

You can try launching the GNU Radio Companion (GRC) tool, a visual tool for building and running GNU Radio flowgraphs.

gnuradio-companion

If "gnuradio-companion" does not start and complains about the <code>PYTHONPATH</code> environment variable, then you may have to set this in your <code>$HOME/.bashrc</code> file, as shown below.

export PYTHONPATH=/usr/local/lib/python2.7/dist-packages

On Fedora 21/22/23/24, the <code>PYTHONPATH</code> environment variable will need to be set to:

export PYTHONPATH=/usr/lib/python2.7/site-packages:/usr/local/lib64/python2.7/site-packages/

==Configuring USB==

On Linux, udev handles USB plug and unplug events. The following commands install a udev rule so that non-root users may access the device. This step is only necessary for devices that use USB to connect to the host computer, such as the B200, B210, and B200mini. This setting should take effect immediately and does not require a reboot or logout/login. Be sure that no USRP device is connected via USB when running these commands.

cd $HOME/workarea/uhd/host/utils
sudo cp uhd-usrp.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

==Configuring Ethernet==

For USRP devices that use Ethernet to connect to the host computer, such as the N200, N210, X300, X310, set a static IP address for your system of 192.168.10.1, with a netmask of 255.255.255.0. The default IP address of the USRP is 192.168.10.2, with a netmask of 255.255.255.0. You should probably set the IP address using the graphical Network Manager. If you set the IP address from the command line with <code>ifconfig</code>, Network Manager will probably overwrite these settings.

==Connect the USRP==

The installation of UHD and GNU Radio should now be complete. At this point, connect the USRP to the host computer.

If the interface is Ethernet, then open a terminal window, and try to ping the USRP with "ping 192.168.10.2". The USRP should respond to the ping requests.

If the interface is USB, then open a terminal window, and run "<code>lsusb</code>". You should see the USRP listed on the USB bus with a VID of <code>2500</code> and PID of <code>0020</code>, <code>0021</code>, <code>0022</code>, for B200, B210, B200mini, respectively.

Also try running "<code>uhd_find_devices</code>" and "<code>uhd_usrp_probe</code>".

==Thread priority scheduling==

When UHD 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.

<pre>
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
</pre>

To address this issue, non-privileged (non-root) users need to be given special permission to change the scheduling priority. This can be enabled by creating a group <code>usrp</code>, adding your user to it, and then appending the line <code>@usrp - rtprio 99</code> to the file <code>/etc/security/limits.conf</code>.

sudo groupadd usrp
sudo usermod -aG usrp $USER

Then add the line below to end of the file <code>/etc/security/limits.conf</code>:

@usrp - rtprio 99

You must 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 <code>/etc/group</code> file.

There is further documentation about this in the User Manual at the link below.

* [http://files.ettus.com/manual/page_general.html#general_threading_prio Threading Notes section of the User Manual]

[[Category:Application Notes]]

UHD Python API

2021-09-09T11:54:36Z

MartinAnderseck: Removed invalid link to old mailinglist post and instead added link to manual which covers some typical issues on Windows systems.

== What's the UHD Python API? ==

As the name suggests, it exposes the UHD API into Python. We use <code>Boost.Python</code>
to generate a Python module which exposes most of the C++ API, and some extra
features. The Python API is currently part of master branch.

The USRP Hardware Driver and USRP Manual covers most information about the UHD Python API and can be found here: https://files.ettus.com/manual/page_python.html

== How can I use it? ==

In order to test the Python API, check out the <code>master</code> branch and build it like always. When running CMake, make sure that the Python API was enabled (<code>-DENABLE_PYTHON_API=ON</code>).

The output from CMake should look something like this:

<pre>
-- ######################################################
-- # UHD enabled components
-- ######################################################
-- * LibUHD
-- * LibUHD - C API
-- * LibUHD - Python API
-- * Examples
-- * Utils
-- * Tests
-- * USB
-- * B100
-- * B200
-- * USRP1
-- * USRP2
-- * X300
-- * N230
-- * OctoClock
-- * Manual
-- * API/Doxygen
-- * Man Pages
--
-- ######################################################
-- # UHD disabled components
-- ######################################################
-- * GPSD
-- * E100
-- * E300
</pre>

Please refer to the [https://files.ettus.com/manual/page_python.html USRP Manual] for extended instructions especially when installing on Windows.
Once it's built and installed, you'll be able to import the <code>uhd</code> Python
module.

<syntaxhighlight lang="python">
>>> import uhd
>>> my_usrp = uhd.usrp.MultiUSRP("type=b200")
>>> my_usrp.set_rx_gain(70)
</syntaxhighlight>

We have some examples in <code>[https://github.com/EttusResearch/uhd/tree/master/host/examples/python host/examples/python]</code>. The examples are very
simple, but concise.

==Example: pyuhd_rx_to_file.py==
This Python example is based on the C++ example <code>uhd/host/examples/rx_samples_to_file.cpp</code>.

<syntaxhighlight lang="python">
import uhd
import numpy as np
import argparse

def parse_args():
parser = argparse.ArgumentParser()
parser.add_argument("-a", "--args", default="", type=str)
parser.add_argument("-o", "--output-file", type=str, required=True)
parser.add_argument("-f", "--freq", type=float, required=True)
parser.add_argument("-r", "--rate", default=1e6, type=float)
parser.add_argument("-d", "--duration", default=5.0, type=float)
parser.add_argument("-c", "--channels", default=0, nargs="+", type=int)
parser.add_argument("-g", "--gain", type=int, default=10)
return parser.parse_args()

def main():
args = parse_args()
usrp = uhd.usrp.MultiUSRP(args.args)
num_samps = int(np.ceil(args.duration*args.rate))
if not isinstance(args.channels, list):
args.channels = [args.channels]
samps = usrp.recv_num_samps(num_samps, args.freq, args.rate, args.channels, args.gain)
with open(args.output_file, 'wb') as f:
np.save(f, samps, allow_pickle=False, fix_imports=False)

if __name__ == "__main__":
main()
</syntaxhighlight>

== What about documentation? ==

Documentation is currently pretty sparse. The best we can do right now is to ask
users to infer the documentation from the C++ API. For example, the Python has
an object called <code>MultiUSRP</code> which is an equivalent of the C++ <code>multi_usrp</code> API.
The methods on both classes are the same, and take the same arguments.

==FAQ==
'''Does it support Python 2 and 3?'''

Yes.

'''Does it require GNU Radio?'''

No.

'''Does it use SWIG?'''

No, it uses <code>Boost.Python</code>. We didn't want to add another dependency to UHD (i.e., SWIG) and Boost was already a dependency of UHD. It also doesn't require the C API.

'''How does this relate to the Python API in gr-uhd?'''

It serves an entirely different purpose. This Python API is for people writing standalone applications for USRPs that *don't* use GNU Radio. <code>gr-uhd</code> is staying the way it is, and is going nowhere. If you're using GNU Radio, you probably don't care about this.

'''Are the UHD Python API and the gr-uhd Python API compatible?'''

Short answer: No. Long answer: There are very few cases where it makes sense to mix these APIs, so no. However, this means that a <code>TimeSpec</code> from the <code>Boost.Python</code> API is not convertible into a <code>time_spec_t</code> from the <code>gr-uhd</code> API.

'''When will it be released?'''

It is currently on <code>master</code> branch, and will become part of the next major release.

'''Does it support RFNoC API?'''

Not yet, but it's in the pipeline. We wanted to get the basics (i.e. <code>multi_usrp</code> API) right first.

'''What's the streaming performance?'''

Worse than straight C++, but not a lot, thanks to NumPy. You can run <code>host/examples/benchmark_rate.py</code> if you want to see for yourself.
Overall, <code>recv()</code> calls are pretty efficient if you've preallocated a NumPy array, because we can cast that to a straight pointer (and also skip any type checking!) and then it's not that different from a <code>recv()</code> call in a C++ app. However, consuming the data is limited by how fast you can handle that in Python.

Building and Installing the USRP Open Source Toolchain (UHD and GNU Radio) on Windows

2021-08-25T09:11:55Z

MartinAnderseck: Updated version number of current libUSB release.

==Application Note Number==
'''AN-611'''


==Abstract==
This Application Note provides a step-by-step guide for building, installing, and updating the open-source toolchain, specifically UHD and GNU Radio, for the USRP from source code on Windows.

==UHD on Windows==

UHD is fully supported on Windows 7, 8, 8.1, and 10 and can be compiled using Visual Studio 2013, 2015, or 2017. The future target is to support the latest three OS and Visual Studio releases.

==Setup the Environment==

The following dependencies are required for a regular build.

* Microsoft Windows (7, 8, 8.1, 10)
* Microsoft Visual Studio (2013, 2015, 2017)
* CMake (2.8.0 or later)
* Boost (1.53 or later)
* LibUSB (1.0 or later)
* Python (2.7.x)
* Mako (0.5.0 or later)
* Doxygen (1.8 or later, optional)
* NSIS (2.50 or later, optional)

Optional Tools:

* 7zip (http://www.7-zip.org/download.html)
* msysGit (https://gitforwindows.org/)

==Installing the dependencies==

===Microsoft Visual Studio===

The free version of Visual Studio is sufficient for building UHD. This guide was tested using Windows 10 x64 and Microsoft Visual Studio Community 2017 (v15.9).

Users will need to install the "Desktop Development for C++" Workload for Visual Studio. This can be found in:

Tools >> Get Tools and Features... >> Workloads

https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads

https://www.visualstudio.com/downloads/

===CMake===

CMake is a cross-platform build system used to configure and generate the files necessary to compile and test UHD for a particular computer environment.

Made sure to download the ".msi" file, not the ".zip" file. During installation select the option to "Add CMake to the system PATH for the current user" or for "all users", depending on which is more applicable for your Windows usage.

CMake 3.13.2 (win64-x64) was used for the guide. UHD has been tested to work through CMake 3.17.2.

https://cmake.org/download/

===Boost===

Boost is a set of C++ libraries providing useful algorithms and data structures.

UHD builds with Boost through 1.72.0. From the link below, select the version of Boost you wish to build against. At the bottom of the directory listing will be a file "DEPENDENCY_VERSIONS.txt". Review this file to determine the correct version of the Boost installer to download for your specific MSVC version. The Boost binary installer must be selected to match the version of MSVC being used to compile UHD and architecture of Windows being run -- 32 or 64 bit. Watch out as Microsoft has done the version numbering of MSVC such that the year and version number do not match. Here are the recent entries in the noted file:

Microsoft Visual Studio 2013 - msvc-12.0 - Update 5
Microsoft Visual Studio 2015 - msvc-14.0 - Update 3
Microsoft Visual Studio 2017 - msvc-14.1 - VS 15.9.17
Microsoft Visual Studio 2019 - msvc-14.2 - VS 16.3.6

Note that VS2019 support (MSVC Toolset 14.2) starts unofficially with Boost 1.70.0, and then officially with 1.71.0.

After the Boost installer executable is downloaded, find it in the Windows File Explorer, right click on it and "Run as administrator". During the install, select the destination location of "C:\Program Files\Boost\" for the install; the installer will append the Boost directory and version info, such that the full destination will actually be, for example, "C:\Program Files\Boost\boost_1_68_0".

VS2017 uses the MSVC Toolset 14.1 so boost_1_68_0-msvc-14.1-64 was selected for this tutorial, and installed as "C:\Program Files\Boost\boost_1_68_0".

https://sourceforge.net/projects/boost/files/boost-binaries/

===LibUSB===

LibUSB is a cross-platform library providing access to USB devices. UHD is compatible through LibUSB 1.0.24 (the current release as of this update).

LibUSB releases are distributed as 7zip or tar.bz2 archives. There are plenty of free "unzip" programs available that can extract the files in either archive type; Windows does not provide this capability, so you'll need to download one of these programs. We are using the "7Zip" program as linked in the “Setting Up the Environment” Section. After installing 7zip the LibUSB release archive can be extracted by right clicking on the downloaded file and selecting <tt>7zip >> Extract files</tt>.

LibUSB 1.0.22 was used for the guide and extracted to <syntaxhighlight lang="irc" enclose="none">C:\Users\username\libusb-1.0.22</syntaxhighlight>.

https://sourceforge.net/projects/libusb/files/libusb-1.0/

'''Note''': The directory to which you extract libusb must not contain spaces. This is to say that <syntaxhighlight lang="irc" enclose="none">C:\Users\user name\libusb-1.0.22</syntaxhighlight> will cause compile issues moving forward.

===Python===

Python is a widely-used general-purpose, high-level programming language. UHD includes several utilities written in Python and has several scripts which are part of the build process. UHD is compatible with Python 2.7, and 3.5 through 3.8. The default Python install will be 32 bit. To get the 64-bit install, you have to select it specifically -- "Download Windows x86-64 executable installer" for Python 3.0+ or "Download Windows x86-64 MSI installer" for Python 2.7 (any version). When installing Python make sure to add to the PATH so that "python.exe" is available from the commandline.

The Python 2.7.15 was used for this tutorial.

https://www.python.org/downloads/windows/

For building the LibUHD Python API the Python libraries NumPy and ruamel.yaml are required. NumPy adds support for large matrices and arrays and mathematical functions around them. ruamel.yaml is used for parsing/emitting YAML.
To install them open a command line (Ctrl-X, select Run, type <syntaxhighlight lang="python" enclose="none">cmd.exe</syntaxhighlight> and click OK)

cd C:\Python27\Scripts
pip.exe install numpy
pip.exe install ruamel.yaml

===Mako===

Mako is a python template library used to generate source files and is
distributed using a Python package management system.

Open a command line (Ctrl-X, select Run, type <syntaxhighlight lang="python" enclose="none">cmd.exe</syntaxhighlight> and click OK)

cd C:\Python27\Scripts
pip.exe install mako

This installed version 1.0.7 at the time of writing this guide.

===Doxygen===

Doxygen is a documentation generator which creates the HTML manual from text in the source code. It optional for building UHD.

Version 1.8.14 was used for this guide.

https://sourceforge.net/projects/doxygen/files/rel-1.8.14/

===NSIS===

NSIS is a toolkit for creating Windows installers. NSIS is used for creating binary packages of UHD enabling easy distribution and installation of UHD, associated utilities, and examples.

Version 3.03 was used for this guide.

https://sourceforge.net/projects/nsis/files/NSIS%203/

==Obtain the UHD source code==

The UHD source code is stored in a GIT repository: https://www.github.com/EttusResearch/uhd . From this link, one can download an archive of the UHD source code for any release, the current public codebase itself, and the code state for some branches or tags. Which one you download is up to your needs. We generally recommend the latest release, which can be downloaded from our Github repository or from our website as noted below.

For the purposes of this guide, the archive was [https://files.ettus.com/binaries/uhd/uhd_003.015.000.000-release/uhd_3.15.0.0-release.tar.xz downloaded from our website], and extracted as <syntaxhighlight lang="irc" enclose="none">C:\Users\username\uhd-release\</syntaxhighlight>. Please note that most UHD archives will extract to a directory name that corresponds to the UHD version; for example the one noted extracts to "uhd_3.15.0.0-release". After extraction, we change the directory name to that as noted ("uhd-release") and move it into the directory as noted. You can install the UHD source wherever you want to, of course; for this article we choose this location and use it later as such.

===From a release source archive===

Archives of the source code for each stable release can be downloaded from the Ettus website.

http://files.ettus.com/binaries/uhd/

7zip can be used to extract the <tt>tar.gz</tt> archive to a location of your choosing.

This guide used the Git repository to obtain the newest release of UHD, read on for details.

===From the Git repository===

The latest development code, as well as tagged releases, is available from the git repository hosted on GitHub

https://www.github.com/EttusResearch/uhd

For step-by-step instructions using a git client, see section [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux#Building_and_installing_UHD_from_source_code Building and installing UHD from source code] in the UHD Linux Installation Guide. Return to this document after you have successfully checked out your desired release of UHD, and note that some directory names moving forward may differ slightly.

==Building==

All prerequisites have now been installed and downloaded. You are encouraged to restart your machine before continuing.

===Configuring the Building===

* Open the Cmake GUI
* Select source code directory
*: <syntaxhighlight lang="irc" enclose="none">C:\Users\username\uhd-release\host\</syntaxhighlight>
* Select binary build directory (this may require creating the folder \build\)
*: <syntaxhighlight lang="irc" enclose="none">C:\Users\username\uhd-release\host\build\</syntaxhighlight>
* Check the Advanced checkbox
* Click Configure
** Set Visual Studio 15 2017 Win64 as the compiler
** Click “Finish” and allow CMake to Generate
* Change or add the following entries
*; '''Boost_INCLUDE_DIR''' : <syntaxhighlight lang="irc" enclose="none">C:\Program Files\Boost\boost_1_68_0\</syntaxhighlight>
* Add the following entries with type PATH
*; '''Boost_LIBRARY_DIRS''' : <syntaxhighlight lang="irc" enclose="none">C:\Program Files\Boost\boost_1_68_0\lib64-msvc-14.1\</syntaxhighlight>
*; '''LIBUSB_INCLUDE_DIRS''' : <syntaxhighlight lang="irc" enclose="none">C:\Users\username\libusb-1.0.22\include\libusb-1.0\</syntaxhighlight>
* Add the following entry with type FILEPATH
*; '''LIBUSB_LIBRARIES''' : <syntaxhighlight lang="irc" enclose="none">C:\Users\username\libusb-1.0.22\MS64/dll\libusb-1.0.lib</syntaxhighlight>
* Click Generate

===Compiling UHD===

Open Visual Studio 2017 and open the UHD project file generated by CMake.
; <tt>File > Open Project</tt> : <syntaxhighlight lang="irc" enclose="none">C:\Users\username\uhd-release\host\build\UHD.sln</syntaxhighlight>

Change the build type from Debug to Release. The '''ALL_BUILD''' project should be selected in the Solution Explorer, select it if this is not the case. Run the build, <tt>Build > Build '''ALL_BUILD'''</tt>.

==Installing UHD==

Select the '''INSTALL''' project in the Solution Explorer and run the build, <tt>Build > Build '''INSTALL'''</tt>.

Visual Studio must be run as Administrator for this to succeed as it needs write permission for the <syntaxhighlight lang="python" enclose="none">C:\Program Files</syntaxhighlight> directory.

===Compiling a binary installer===

Building the '''PACKAGE''' project will produce a binary installer if NSIS is installed. This installer with be for either 64 bit or 32 bit as chosen during the CMake step. Select the '''PACKAGE''' project in the Solution Explorer and run the build, <tt> Build > '''Package'''</tt>.

==Running UHD==

Running programs using UHD requires the Visual Studio C++ Runtime Redistributable to be installed. The version of the C++ Runtime Redistributable must match the version of Visual Studio used to compile the program.

* [https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads Visual Studio 2017]
* [https://www.microsoft.com/en-us/download/details.aspx?id=48145 Visual Studio 2015]
* [https://support.microsoft.com/en-us/kb/2977003 Visual Studio 2012 and 2013]

==Installing the USB driver==

If a USB connected USRP is used then the USB drivers must be installed. The drivers are located at http://files.ettus.com/binaries/misc/erllc_uhd_winusb_driver.zip.

There is a known issue with Windows 10 where an error message is shown at the end of driver installation. However resetting or power cycling the USRP enables full functionality.

==Note on Dependencies for Current and Previous Versions==

It should be noted that this guide is intended to serve as an example; the software versions and dependencies listed above are not the only possible combinations. Be sure to review the [http://files.ettus.com/manual/page_build_guide.html Build Dependencies] in the [http://files.ettus.com/manual/index.html USRP Hardware Driver and USRP Manual] for information regarding the minimum required driver versions for your build of UHD. To preserve the software stack from the previous iteration of this Application Note, here is an example driver stack for Windows 7 + VS 2013:

* Microsoft Windows 7 x64
* Microsoft Visual Studio 2013
* CMake 3.4.1 win32-x86
* Boost 1.58.0 msvc-12.0 x64
* LibUSB 1.0.20
* Python 2.7.11
* Mako 1.0.3
* Doxygen 1.8
* NSIS 2.50

==GNU Radio and UHD==
Building GNU Radio from source on Windows is still an involved process due to the large number of dependencies. A set of scripts have been developed to automate the process by Geof Nieboer. The links below will detail the process to building GNU Radio + UHD.

'''Note:''' The linked instructions below will build GNU Radio along with UHD, which is separate from the instructions above within this Application Note. The scripts linked below are not maintained by Ettus Research, and are considered third-party binary packages, and are not directly supported by Ettus Research.

https://github.com/gnieboer/gnuradio_windows_build_scripts
http://www.gcndevelopment.com/gnuradio/

[[Category:Application Notes]]

Building and Installing the USRP Open Source Toolchain (UHD and GNU Radio) on Windows

2021-08-24T14:56:49Z

MartinAnderseck: Added information about dependencies NumPy and ruamel.yaml required for building the Python API for UHD.

==Application Note Number==
'''AN-611'''


==Abstract==
This Application Note provides a step-by-step guide for building, installing, and updating the open-source toolchain, specifically UHD and GNU Radio, for the USRP from source code on Windows.

==UHD on Windows==

UHD is fully supported on Windows 7, 8, 8.1, and 10 and can be compiled using Visual Studio 2013, 2015, or 2017. The future target is to support the latest three OS and Visual Studio releases.

==Setup the Environment==

The following dependencies are required for a regular build.

* Microsoft Windows (7, 8, 8.1, 10)
* Microsoft Visual Studio (2013, 2015, 2017)
* CMake (2.8.0 or later)
* Boost (1.53 or later)
* LibUSB (1.0 or later)
* Python (2.7.x)
* Mako (0.5.0 or later)
* Doxygen (1.8 or later, optional)
* NSIS (2.50 or later, optional)

Optional Tools:

* 7zip (http://www.7-zip.org/download.html)
* msysGit (https://gitforwindows.org/)

==Installing the dependencies==

===Microsoft Visual Studio===

The free version of Visual Studio is sufficient for building UHD. This guide was tested using Windows 10 x64 and Microsoft Visual Studio Community 2017 (v15.9).

Users will need to install the "Desktop Development for C++" Workload for Visual Studio. This can be found in:

Tools >> Get Tools and Features... >> Workloads

https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads

https://www.visualstudio.com/downloads/

===CMake===

CMake is a cross-platform build system used to configure and generate the files necessary to compile and test UHD for a particular computer environment.

Made sure to download the ".msi" file, not the ".zip" file. During installation select the option to "Add CMake to the system PATH for the current user" or for "all users", depending on which is more applicable for your Windows usage.

CMake 3.13.2 (win64-x64) was used for the guide. UHD has been tested to work through CMake 3.17.2.

https://cmake.org/download/

===Boost===

Boost is a set of C++ libraries providing useful algorithms and data structures.

UHD builds with Boost through 1.72.0. From the link below, select the version of Boost you wish to build against. At the bottom of the directory listing will be a file "DEPENDENCY_VERSIONS.txt". Review this file to determine the correct version of the Boost installer to download for your specific MSVC version. The Boost binary installer must be selected to match the version of MSVC being used to compile UHD and architecture of Windows being run -- 32 or 64 bit. Watch out as Microsoft has done the version numbering of MSVC such that the year and version number do not match. Here are the recent entries in the noted file:

Microsoft Visual Studio 2013 - msvc-12.0 - Update 5
Microsoft Visual Studio 2015 - msvc-14.0 - Update 3
Microsoft Visual Studio 2017 - msvc-14.1 - VS 15.9.17
Microsoft Visual Studio 2019 - msvc-14.2 - VS 16.3.6

Note that VS2019 support (MSVC Toolset 14.2) starts unofficially with Boost 1.70.0, and then officially with 1.71.0.

After the Boost installer executable is downloaded, find it in the Windows File Explorer, right click on it and "Run as administrator". During the install, select the destination location of "C:\Program Files\Boost\" for the install; the installer will append the Boost directory and version info, such that the full destination will actually be, for example, "C:\Program Files\Boost\boost_1_68_0".

VS2017 uses the MSVC Toolset 14.1 so boost_1_68_0-msvc-14.1-64 was selected for this tutorial, and installed as "C:\Program Files\Boost\boost_1_68_0".

https://sourceforge.net/projects/boost/files/boost-binaries/

===LibUSB===

LibUSB is a cross-platform library providing access to USB devices. UHD is compatible through LibUSB 1.0.23 (the current release as of this update).

LibUSB releases are distributed as 7zip or tar.bz2 archives. There are plenty of free "unzip" programs available that can extract the files in either archive type; Windows does not provide this capability, so you'll need to download one of these programs. We are using the "7Zip" program as linked in the “Setting Up the Environment” Section. After installing 7zip the LibUSB release archive can be extracted by right clicking on the downloaded file and selecting <tt>7zip >> Extract files</tt>.

LibUSB 1.0.22 was used for the guide and extracted to <syntaxhighlight lang="irc" enclose="none">C:\Users\username\libusb-1.0.22</syntaxhighlight>.

https://sourceforge.net/projects/libusb/files/libusb-1.0/

'''Note''': The directory to which you extract libusb must not contain spaces. This is to say that <syntaxhighlight lang="irc" enclose="none">C:\Users\user name\libusb-1.0.22</syntaxhighlight> will cause compile issues moving forward.

===Python===

Python is a widely-used general-purpose, high-level programming language. UHD includes several utilities written in Python and has several scripts which are part of the build process. UHD is compatible with Python 2.7, and 3.5 through 3.8. The default Python install will be 32 bit. To get the 64-bit install, you have to select it specifically -- "Download Windows x86-64 executable installer" for Python 3.0+ or "Download Windows x86-64 MSI installer" for Python 2.7 (any version). When installing Python make sure to add to the PATH so that "python.exe" is available from the commandline.

The Python 2.7.15 was used for this tutorial.

https://www.python.org/downloads/windows/

For building the LibUHD Python API the Python libraries NumPy and ruamel.yaml are required. NumPy adds support for large matrices and arrays and mathematical functions around them. ruamel.yaml is used for parsing/emitting YAML.
To install them open a command line (Ctrl-X, select Run, type <syntaxhighlight lang="python" enclose="none">cmd.exe</syntaxhighlight> and click OK)

cd C:\Python27\Scripts
pip.exe install numpy
pip.exe install ruamel.yaml

===Mako===

Mako is a python template library used to generate source files and is
distributed using a Python package management system.

Open a command line (Ctrl-X, select Run, type <syntaxhighlight lang="python" enclose="none">cmd.exe</syntaxhighlight> and click OK)

cd C:\Python27\Scripts
pip.exe install mako

This installed version 1.0.7 at the time of writing this guide.

===Doxygen===

Doxygen is a documentation generator which creates the HTML manual from text in the source code. It optional for building UHD.

Version 1.8.14 was used for this guide.

https://sourceforge.net/projects/doxygen/files/rel-1.8.14/

===NSIS===

NSIS is a toolkit for creating Windows installers. NSIS is used for creating binary packages of UHD enabling easy distribution and installation of UHD, associated utilities, and examples.

Version 3.03 was used for this guide.

https://sourceforge.net/projects/nsis/files/NSIS%203/

==Obtain the UHD source code==

The UHD source code is stored in a GIT repository: https://www.github.com/EttusResearch/uhd . From this link, one can download an archive of the UHD source code for any release, the current public codebase itself, and the code state for some branches or tags. Which one you download is up to your needs. We generally recommend the latest release, which can be downloaded from our Github repository or from our website as noted below.

For the purposes of this guide, the archive was [https://files.ettus.com/binaries/uhd/uhd_003.015.000.000-release/uhd_3.15.0.0-release.tar.xz downloaded from our website], and extracted as <syntaxhighlight lang="irc" enclose="none">C:\Users\username\uhd-release\</syntaxhighlight>. Please note that most UHD archives will extract to a directory name that corresponds to the UHD version; for example the one noted extracts to "uhd_3.15.0.0-release". After extraction, we change the directory name to that as noted ("uhd-release") and move it into the directory as noted. You can install the UHD source wherever you want to, of course; for this article we choose this location and use it later as such.

===From a release source archive===

Archives of the source code for each stable release can be downloaded from the Ettus website.

http://files.ettus.com/binaries/uhd/

7zip can be used to extract the <tt>tar.gz</tt> archive to a location of your choosing.

This guide used the Git repository to obtain the newest release of UHD, read on for details.

===From the Git repository===

The latest development code, as well as tagged releases, is available from the git repository hosted on GitHub

https://www.github.com/EttusResearch/uhd

For step-by-step instructions using a git client, see section [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux#Building_and_installing_UHD_from_source_code Building and installing UHD from source code] in the UHD Linux Installation Guide. Return to this document after you have successfully checked out your desired release of UHD, and note that some directory names moving forward may differ slightly.

==Building==

All prerequisites have now been installed and downloaded. You are encouraged to restart your machine before continuing.

===Configuring the Building===

* Open the Cmake GUI
* Select source code directory
*: <syntaxhighlight lang="irc" enclose="none">C:\Users\username\uhd-release\host\</syntaxhighlight>
* Select binary build directory (this may require creating the folder \build\)
*: <syntaxhighlight lang="irc" enclose="none">C:\Users\username\uhd-release\host\build\</syntaxhighlight>
* Check the Advanced checkbox
* Click Configure
** Set Visual Studio 15 2017 Win64 as the compiler
** Click “Finish” and allow CMake to Generate
* Change or add the following entries
*; '''Boost_INCLUDE_DIR''' : <syntaxhighlight lang="irc" enclose="none">C:\Program Files\Boost\boost_1_68_0\</syntaxhighlight>
* Add the following entries with type PATH
*; '''Boost_LIBRARY_DIRS''' : <syntaxhighlight lang="irc" enclose="none">C:\Program Files\Boost\boost_1_68_0\lib64-msvc-14.1\</syntaxhighlight>
*; '''LIBUSB_INCLUDE_DIRS''' : <syntaxhighlight lang="irc" enclose="none">C:\Users\username\libusb-1.0.22\include\libusb-1.0\</syntaxhighlight>
* Add the following entry with type FILEPATH
*; '''LIBUSB_LIBRARIES''' : <syntaxhighlight lang="irc" enclose="none">C:\Users\username\libusb-1.0.22\MS64/dll\libusb-1.0.lib</syntaxhighlight>
* Click Generate

===Compiling UHD===

Open Visual Studio 2017 and open the UHD project file generated by CMake.
; <tt>File > Open Project</tt> : <syntaxhighlight lang="irc" enclose="none">C:\Users\username\uhd-release\host\build\UHD.sln</syntaxhighlight>

Change the build type from Debug to Release. The '''ALL_BUILD''' project should be selected in the Solution Explorer, select it if this is not the case. Run the build, <tt>Build > Build '''ALL_BUILD'''</tt>.

==Installing UHD==

Select the '''INSTALL''' project in the Solution Explorer and run the build, <tt>Build > Build '''INSTALL'''</tt>.

Visual Studio must be run as Administrator for this to succeed as it needs write permission for the <syntaxhighlight lang="python" enclose="none">C:\Program Files</syntaxhighlight> directory.

===Compiling a binary installer===

Building the '''PACKAGE''' project will produce a binary installer if NSIS is installed. This installer with be for either 64 bit or 32 bit as chosen during the CMake step. Select the '''PACKAGE''' project in the Solution Explorer and run the build, <tt> Build > '''Package'''</tt>.

==Running UHD==

Running programs using UHD requires the Visual Studio C++ Runtime Redistributable to be installed. The version of the C++ Runtime Redistributable must match the version of Visual Studio used to compile the program.

* [https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads Visual Studio 2017]
* [https://www.microsoft.com/en-us/download/details.aspx?id=48145 Visual Studio 2015]
* [https://support.microsoft.com/en-us/kb/2977003 Visual Studio 2012 and 2013]

==Installing the USB driver==

If a USB connected USRP is used then the USB drivers must be installed. The drivers are located at http://files.ettus.com/binaries/misc/erllc_uhd_winusb_driver.zip.

There is a known issue with Windows 10 where an error message is shown at the end of driver installation. However resetting or power cycling the USRP enables full functionality.

==Note on Dependencies for Current and Previous Versions==

It should be noted that this guide is intended to serve as an example; the software versions and dependencies listed above are not the only possible combinations. Be sure to review the [http://files.ettus.com/manual/page_build_guide.html Build Dependencies] in the [http://files.ettus.com/manual/index.html USRP Hardware Driver and USRP Manual] for information regarding the minimum required driver versions for your build of UHD. To preserve the software stack from the previous iteration of this Application Note, here is an example driver stack for Windows 7 + VS 2013:

* Microsoft Windows 7 x64
* Microsoft Visual Studio 2013
* CMake 3.4.1 win32-x86
* Boost 1.58.0 msvc-12.0 x64
* LibUSB 1.0.20
* Python 2.7.11
* Mako 1.0.3
* Doxygen 1.8
* NSIS 2.50

==GNU Radio and UHD==
Building GNU Radio from source on Windows is still an involved process due to the large number of dependencies. A set of scripts have been developed to automate the process by Geof Nieboer. The links below will detail the process to building GNU Radio + UHD.

'''Note:''' The linked instructions below will build GNU Radio along with UHD, which is separate from the instructions above within this Application Note. The scripts linked below are not maintained by Ettus Research, and are considered third-party binary packages, and are not directly supported by Ettus Research.

https://github.com/gnieboer/gnuradio_windows_build_scripts
http://www.gcndevelopment.com/gnuradio/

[[Category:Application Notes]]