path: root/host/docs/usrp_n3xx.dox

/*! \page page_usrp_n3xx USRP N3xx Series

\tableofcontents

\section n3xx_feature_list Comparative features list

- Hardware Capabilities:
	- Dual SFP+ Transceivers (can be used with 1 GigE, 10 GigE, and Aurora)
	- External PPS input & output
	- External 10 MHz input & output (20 MHz and 25 MHz inputs also supported)
	- Internal 25 MHz reference clock
	- Internal GPSDO for timing, location, and 20 MHz reference clock + PPS
	- External GPIO Connector with UHD API control
	- External USB Connection for built-in JTAG debugger and serial console
        - Xilinx Zynq SoC with dual-core ARM Cortex A9 and Virtex-7 FPGA

- Software Capabilities:
        - Full Linux system running on the ARM core
        - Runs MPM (see also \ref page_mpm)

- FPGA Capabilities:
	- Timed commands in FPGA
	- Timed sampling in FPGA
        - RFNoC capability

The N3XX series of USRPs is designed as a platform. The following USRPs are
variants of the N3XX series:

\subsection n3xx_feature_list_mg N310 (4-channel transceiver)

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.

- Supported master clock rates: 122.88 MHz, 125 MHz, 153.6 MHz
- Tuning range: 10 MHz to 6 GHz (below 300 MHz, additional LOs and mixer stages
  are required to shift the signal into the frequency range of the AD9371
  transceiver)
- 4 RX DDC chains in FPGA
- 4 TX DUC chain in FPGA


\section n3xx_overview Overview

\subsection n3xx_micro The STM32 microcontroller

tbw

\subsection n3xx_sdcard The SD card

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:

1. Boot partition (contains the bootloader). This partition usually does not
   require touching.
2. A data partition, mounted in /data. This is the only partition that is not
   erased during file system updates.
2. 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:

    $ 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.


\section n3xx_getting_started Getting started

This will run you through the first steps relevant to getting your USRP N3XX
series up and running.

\subsection n3xx_getting_started_assembling Assembling the N3XX

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:
- Connect power and network
- Read security settings
- Connect clocking (if required)
- Connect external LOs (if required)

\subsection n3xx_getting_started_fs_update Updating the file system

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:

1. 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`.

2. Using Mender to update. For more details on this procedure, see Section
   \ref n3xx_rasm_mender . This is possible without removing the SD card.
   Updates will take a bit longer though.


\subsection n3xx_getting_started_serial Serial connection

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.

\subsubsection n3xx_getting_started_serial_micro Connecting to the microcontroller

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.

\subsection n3xx_ssh SSH connection

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
\ref n3xx_getting_started_serial. 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 root@ni-n3xx-311FE00.local

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:~#

\subsection n3xx_getting_started_connectivity Network Connectivity

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
<a href=https://www.freedesktop.org/software/systemd/man/systemd.network.html> systemd-networkd manual pages</a>

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.

\subsection n3xx_getting_started_security Security-related settings

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.

\subsection n3xx_getting_started_fpga_update Updating the FPGA

tbw (using uhd_image_loader)

\section n3xx_usage Using an N3XX USRP from UHD

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:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
auto usrp = uhd::usrp::multi_usrp::make("type=n3xx");
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For a list of which arguments can be passed into make(), see Section
\ref n3xx_usage_device_args.

\subsection n3xx_usage_device_args 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)
 find_all            | When using broadcast, find all devices, even if unreachable via CHDR.        | All N3xx          | find_all=1
 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

\subsection n3xx_usage_sensors The sensor API

\section n3xx_rasm Remote Management

\subsection n3xx_rasm_mender Mender: Remote update capability

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](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. Mender servers can be self-hosted, or
hosted by Mender (see [mender.io](https://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 \ref n3xx_sdcard.

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.

\subsection n3xx_rasm_salt Salt: Remote configuration management and execution

Salt (also known as SaltStack, see [Salt Website](https://saltstack.com)) 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](https://docs.saltstack.com/en/latest/),
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


\section n3xx_theory_of_ops Theory of Operation

The N3xx-series are devices based on the MPM architecture (see
also: \ref page_mpm). 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

\section n3xx_mg N310-specific Features

\subsection n3xx_mg_calibrations RF Calibrations

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 \ref n3xx_usage_device_args). 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)

\subsection n3xx_mg_external_lo External LOs

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:

- Improving phase alignment: The N310 itself has no way of aligning phase
  between channels, and phase will be random between runs.  By applying an
  external LO, the phase ambiguity is reduced to 180 degrees, produced by a
  by-2 divider in the AD9371 transceiver IC.
- Improving phase noise: The quality of the onboard LO depends on the external
  reference clock, among other things. By providing a custom LO signal, it is
  possible to more accurately tune, assuming the externally generated LO signal
  is coming from a high-quality oscillator.


\subsection n3xx_mg_eeprom Storing user data in the EEPROM

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.

*/
// vim:ft=doxygen: