 |
USRP Hardware Driver and USRP Manual
Version: 3.11.0.HEAD-0-gdca39145
UHD and USRP Manual
|
|
|
USRP Hardware Driver and USRP Manual
Version: 3.11.0.HEAD-0-gdca39145
UHD and USRP Manual
|
|
The N3XX series of USRPs is designed as a platform. The following USRPs are variants of the N3XX series:
The N310 is a 4-channel receiver based on the AD9371 transceiver IC. It has two daughterboards with one AD9371 each; every daughterboard provides two RF channels.
tbw
The N3XX series uses a micro SD card as its main storage. The entire root file system (Linux kernel, libraries) and any user data are stored on this SD card.
The SD card is partitioned into four partitions:
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:
$ mkdir temp $ mount /dev/mmcblk0p3 temp $ 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
The device node in the mount command will likely differ, depending on which partition is currently already mounted.
This will run you through the first steps relevant to getting your USRP N3XX series up and running.
Unlike the X300 or N200 series, there is no assembly of daughterboards required. Members of the N3XX product family, such as the N310, ship with daughterboards pre-installed.
TODO: Sync with getting-started guide
Checklist:
Before doing any major work with a newly acquired USRP N3XX, it is recommended to update the file system to the latest version. By default, the N3xx supports two methods of updating:
Directly writing the latest SD card image. This requires physical access to the device. To do this, remove the SD card from the device, and plug it into another computer with an SD card reader. Download the latest SD card image file (it typically has a .sdimg file ending) and run the following command:
$ sudo dd if=$yourimage.sdimg of=/dev/$yoursdcard bs=1M
The $yoursdcard device node depends on your operating system and which other devices are plugged in. Typical values are sdb or mmcblk0.
It is possible to gain root access to the device using a serial terminal emulator. Most Linux, OSX, or other Unix flavours have a tool called 'screen' which can be used for this purpose, by running the following command:
$ sudo screen /dev/ttyUSB2 115200
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:
$ 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 "USB_to_UART_Bridge_Controller" are the devices that offer a serial prompt. The first (with the if00 suffix) connects to Linux, whereas the second connects to the STM32 microcontroller. If you have multiple N3XX devices connect, you may have to try out multiple devices. In this case, to use this symlink instead of the raw device node address, modify the command above to:
$ sudo screen /dev/usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6CB5-if00-port0 115200
You should be presented with a shell prompt similar to the following:
root@ni-n3xx-311FE00:~#
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.
The STM32 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:
$ sudo screen /dev/usb-Silicon_Labs_CP2105_Dual_USB_to_UART_Bridge_Controller_007F6CB5-if01-port0 115200
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 (i.e., emulating a power button press) and other low-level diagnostics.
The USRP N-Series devices have two network connections: The dual SFP ports, and an RJ-45 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:
$ ssh root@ni-n3xx-311FE00 # Replace with your actual device name!
Depending on your network setup, using a .local domain may work:
$ ssh [email protected]
Of course, you can also connect to the IP address directly if you know it (or set it manually using the serial console).
(TODO: Add the hostname thing here)
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:
root@ni-n3xx-311FE00:~#
The RJ45 port (eth0) comes up with a default configuration of DHCP, that will request a network address from your DHCP server (if available on your network).
The SFP+ (eth1, eth2) ports are configured with static addresses 192.168.10.2/24 and 192.168.20.2/24 respectively.
The configuration for the ethX port is stored in /etc/systemd/networkd/ethX.network.
For configuration please refer to the manual pages systemd-networkd manual pages
The factory settings are as follows:
eth0 (DHCP):
[Match]
Name=eth0
[Network]
DHCP=v4
[DHCPv4]
UseHostname=false
eth1 (static):
[Match]
Name=eth1
[Network]
Address=192.168.10.2/24
[Link]
MTUBytes=9000
eth2 (static):
[Match]
Name=eth2
[Network]
Address=192.168.20.2/24
[Link]
MTUBytes=9000
Note: Care needs to be taken when editing these files on the device, since vi / vim sometimes generates undo files (e.g. /etc/systemd/networkd/eth1.network~), that systemd-networkd might pick up.
Note: Temporarily setting the IP addresses via ifconfig etc will only change the value until the next reboot / reload of the FPGA image.
The N3XX 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
$ passwd
on the device.
tbw (using uhd_image_loader)
Like any other USRP, all N3XX USRPs are controlled by the UHD software. To integrate a USRP N3XX into your C++ application, you would generate a UHD device in the same way you would for any other USRP:
For a list of which arguments can be passed into make(), see Section Device arguments.
| Key | Description | Supported Devices | Example Value |
|---|---|---|---|
| addr | IPv4 address of primary SFP+ port to connect to. | All N3xx | addr=192.168.30.2 |
| second_addr | IPv4 address of secondary SFP+ port to connect to. | All N3xx | second_addr=192.168.40.2 |
| mgmt_addr | IPv4 address or hostname which to connect the RPC client. Defaults to `addr'. | All N3xx | mgmt_addr=ni-sulfur-311FE00 (can also go to RJ45) |
| master_clock_rate | Master Clock Rate in Hz | N310 | master_clock_rate=125e6 |
| identify | Causes front-panel LEDs to blink. The duration is variable. | N310 | identify=5 (will blink for about 5 seconds) |
| serialize_init | Force serial initialization of daughterboards. | All N3xx | serialize_init=1 |
| skip_dram | Ignore DRAM FIFO block. Connect TX streamers straight into DUC or radio. | All N3xx | skip_dram=1 |
| skip_ddc | Ignore DDC block. Connect Rx streamers straight into radio. | All N3xx | skip_ddc=1 |
| skip_duc | Ignore DUC block. Connect Rx streamers or DRAM straight into radio. | All N3xx | skip_duc=1 |
| skip_init | Skip the initialization process for the device. | All N3xx | skip_init=1 |
| ref_clk_freq | Specify the external reference clock frequency, default is 10 MHz. | N310 | ref_clk_freq=20e6 |
| init_cals | Specify the bitmask for initial calibrations of the RFIC. | N310 | init_cals=BASIC |
| init_cals_timeout | Timeout for initial calibrations in milliseconds. | N310 | init_cals_timeout=45000 |
| discovery_port | Override default value for MPM discovery port. | All N3xx | discovery_port=49700 |
| rpc_port | Override default value for MPM RPC port. | All N3xx | rpc_port=49701 |
| tracking_cals | Specify the bitmask for tracking calibrations of the RFIC. | N310 | tracking_cals=ALL |
| rx_lo_source | Initialize the source for the RX LO. | N310 | rx_lo_source=external |
| tx_lo_source | Initialize the source for the TX LO. | N310 | tx_lo_source=external |
Mender is a third-party software that enables remote updating of the root file system without physically accessing the device (see also the 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: every SD card comes with 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. 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. See also Section The SD card.
To initiate an update from the device itself, download a Mender artifact containing the update itself. These are files with a .mender suffix.
Then run mender on the command line:
$ mender -rootfs /path/to/latest.mender
The artifact can also be stored on a remote server:
$ mender -rootfs http://server.name/path/to/latest.mender
This procedure will take a while. After mender has logged a successful update, reboot the device:
$ reboot
If the reboot worked, and the device seems functional, commit the changes so 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:
$ cat /etc/mender/artifact_info
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 simple way to update groups of rack-mounted USRPs with custom file systems.
Salt (also known as SaltStack, see Salt Website) is a Python-based tool for maintaining fleets of remote devices. It can be used to manage USRP N3XX series remotely for all types of settings that are not controlled by UHD. For example, if an operator would like to reset the root password on multiple devices, or install custom software, this tool might be a suitable choice.
Salt is a third-party project with its own documentation, which should be consulted for configuring it. However, the Salt minion is installed by default on every N3XX device. To start it, simply log on to the device and run:
$ systemctl start salt-minion
To permanently enable it at every boot, run (this won't by itself launch the salt-minion):
$ systemctl enable salt-minion
TODO: Add some example
The N3xx-series are devices based on the MPM architecture (see also: The Module Peripheral Manager (MPM) Architecture). Inside the Linux operating system running on the ARM cores, there is hardware daemon which needs to be active in order for the device to function as a USRP (it is enabled to run by default).
A large portion of hardware-specific setup is handled by the daemon.
tbw
The onboard RFIC (AD9371) has built-in calibrations which can be enabled from UHD. A more detailed description of the calibrations can be found in the AD9371 user guide, see chapter "Quadrature Error Correction, Calibration, and ARM configuration".
Not all calibrations available on the AD9371 are applicable to the USRP N310. However, those calibrations that are applicable can be enabled/disabled at initialization time using the tracking_cals and init_cals device args (see also Device arguments). These device can be set to the precise bit mask the chip uses to set those calibrations (e.g., init_cals=0x4DFF,tracking_cals=0xC3) or they can use the following descriptive keys provided by UHD (e.g.init_cals=DEFAULT,tracking_cals=TX_QEC|RX_QEC). The | symbol can be used to combine keys (equivalent to a bitwise OR).
Calibrations can significantly delay the initialization of a session. By only picking relevant calibrations, sessions can be initialized faster.
Key (init_cal) | Function |
|---|---|
| TX_BB_FILTER | Tx baseband filter calibration |
| ADC_TUNER | ADC tuner calibration |
| TIA_3DB_CORNER | Rx TIA filter calibration |
| DC_OFFSET | Rx DC offset calibration |
| TX_ATTENUATION_DELAY | Tx attenuation delay |
| RX_GAIN_DELAY | Rx gain delay calibration |
| FLASH_CAL | ADC flash calibration |
| PATH_DELAY | Path delay calibration |
| TX_LO_LEAKAGE_INTERNAL | Tx LO leakage internal initial calibration |
| TX_LO_LEAKAGE_EXTERNAL | Tx LO leakage external initial calibration (requires external LO) |
| TX_QEC_INIT | Tx QEC initial |
| LOOPBACK_RX_LO_DELAY | Loopback ORx LO delay (ORx not connected by default!) |
| LOOPBACK_RX_RX_QEC_INIT | Loopback Rx QEC initial calibration |
| RX_LO_DELAY | Rx LO delay |
| RX_QEC_INIT | Rx QEC initial calibration |
| BASIC | Preset for minimal calibrations (TX_BB_FILTER, ADC_TUNER, TIA_3DB_CORNER, DC_OFFSET and FLASH_CAL) |
| OFF | Preset for disabling all initial calibrations |
| DEFAULT | Preset for enabling most calibrations (BASIC plus TX_ATTENUATION_DELAY, RX_GAIN_DELAY, PATH_DELAY, RX_QEC_INIT, TX_LO_LEAKAGE_INTERNAL, TX_QEC_INIT, LOOPBACK_RX_LO_DELAY) |
| ALL | Enable all applicable calibrations |
Key (tracking_cal) | Function |
|---|---|
| TRACK_RX1_QEC | Rx1 QEC tracking |
| TRACK_RX2_QEC | Rx2 QEC tracking |
| TRACK_ORX1_QEC | ORx1 QEC tracking |
| TRACK_ORX2_QEC | ORx1 QEC tracking |
| TRACK_TX1_LOL | Tx1 LO leakage tracking |
| TRACK_TX2_LOL | Tx2 LO leakage tracking |
| TRACK_TX1_QEC | Tx1 QEC tracking |
| TRACK_TX2_QEC | Tx2 QEC tracking |
| OFF | Disable all tracking |
| RX_QEC | Enable all RX QEC tracking |
| TX_QEC | Enable all TX QEC tracking |
| TX_LOL | Enable all TX LO leakage tracking |
| DEFAULT | Enable all QEC tracking |
| ALL | Enable all tracking (except ORx) |
The N310 has inputs for external local oscillators. For every daughterboard, there is one input for TX and RX, respectively, resulting in 4 LO inputs total per N310.
Reasons to use an external LO include:
The N310 daughterboard has an EEPROM which is primarily used for storing the serial number, product ID, and other product-specific information. However, it can also be used to store user data, such as calibration information.
Note that EEPROMs have a limited number of write cycles, and storing user data should happen only when necessary. Writes should be kept at a minimum.
Storing data on the EEPROM is done by loading a uhd::eeprom_map_t object into the property tree. On writing this property, the driver code will serialize the map into a binary representation that can be stored on the EEPROM.
1.8.13