Running the Radio

DragonRadio is built against UHD 3.9.5, which is the default version on the Colosseum. We provide a patched version of UHD 3.9.5 that compiles under Ubuntu 20.04. If you are running DragonRadio on your own USRP instead of on the Colosseum, make sure it has been flashed with the 3.9.5 firmware.

The build.sh script will create a virtualenv environment in the directory venv containing all required Python modules. You may either activate this virtualenv before invoking the radio, or you may set the VIRTUAL_ENV environment variable to point to it before you invoke dragonradio. You must make sure the dragonradio binary can obtain the CAP_SYS_NICE and CAP_NET_ADMIN capabilities when it runs (see Capabilities and Security).

Invoking the radio

The Stand-alone Radio

Let’s take a look at an example invocation of the stand-alone radio, which uses the scripts/standalone-radio.py to configure the radio:

VIRTUAL_ENV=venv ./dragonradio scripts/standalone-radio.py \
   --auto-soft-tx-gain 100 -G 25 -R 25 \
   --slot-size=0.05 --guard-size=0.001 --superslots --tdma-fdma \
   --fifo --packet-compression \
   -l logs -d \
   -b 10e6

The command-line parameters have the following effects:

1. The digital soft gain is automatically adjusted to 0dB using the first 100 transmitted packets. This is necessary for liquid-dsp-based PHYs.

2. The transmit and received hard gain is set to 25 dB.

3. The TDMA/FDMA MAC is used with a TDMA slot size of 50ms and a guard interval of 1ms. Superslots are enabled.

4. A FIFO network queue is used.

5. Packet header compression is enabled.

6. Logs will be written to the logs directory, and debugging is enabled.

7. The radio bandwidth is set to 10 Mhz.

Note the following defaults:

1. The TDMA/FDMA MAC uses 1 MHz channels. This can be overridden using the --channel-bandwidth option.

2. The radio node ID is derived from the hostname. This can be overridden using the -i option.

3. The radio assumes there are two radio nodes, numbered 1 and 2, in the network. This number is used to configure a MAC schedule. It can be overridden using the -n option.

The next invocation of the stand-alone radio adds the options --config config/features/amc.conf --amc --arq.

VIRTUAL_ENV=venv ./dragonradio scripts/standalone-radio.py \
   --config config/features/amc.conf --amc --arq \
   --auto-soft-tx-gain 100 -G 25 -R 25 \
   --slot-size=0.05 --guard-size=0.001 --superslots --tdma-fdma \
   --fifo --packet-compression \
   -l logs -d \
   -b 10e6

These options have additional effects:

1. Options are loaded from the configuration file config/features/amc.conf.

2. Automatic Modulation and Coding (AMC) is enabled.

3. Automatic Repeat Request (ARQ) is enabled.

The --config option may be specified multiple times. This features loads configuration settings from a libconfig format configuration file, making it easy to specify a large set of options without typing out a long command line. Radio options are managed by the dragonradio.radio.Config class; see its documentation for a description of all available radio options. See the Command-line Argument Reference for a description of all available command-line options. Most, but not all, radio options can be configured on the command line.

The SC2 Radio

Here is an example invocation of the SC2 competition radio:

VIRTUAL_ENV=venv ./dragonradio scripts/sc2-radio.py \
   --config config/srn/radio.conf \
   --colosseum-ini config/srn/colosseum_config.ini
   --collab-server-ip 10.32.143.101 \
   --bootstrap --foreground \
   -b 10e6 \
   -l logs \
   start

These parameters have the following effects:

1. Load the configuration file config/srn/radio.conf.

2. Load the Colosseum INI file config/srn/colosseum_config.ini.

3. Set the IP address of the collaboration server to 10.32.143.101.

4. Boostrap the radio. Without the --bootstrap option, the radio will wait to be told to start transmitting.

5. Run in the foreground. Without this option, the radio will daemonize and run in the background.

6. start the radio. This initializes the radio but does not start transmitting until told to begin unless the --bootstrap option is given.

By default, when run in the background, that radio will write its PID to the file /var/run/dragonradio.pid. It can be invoked with the stop command instead of the start command to terminate the radio. The dragonradio-client script can be used to control the daemonized radio.

Command-line Argument Reference

Run dragonradio.

usage: dragonradio SCRIPT [-h] [--team ID] [-i ID] [-n N] [--interactive] [--config FILE] [-d] [-v] [--verbose-packet-trace]
                          [-l PATH] [--log-iq] [--log-iface IFACE] [--log-invalid-headers] [--log-snapshots] [--log-protobuf]
                          [--compress-iface-logs] [--addr ADDR] [--rx-subdev DEVICE] [--tx-subdev DEVICE] [--rx-antenna ANTENNA]
                          [--tx-antenna ANTENNA] [--rx-max-samps-factor X] [--tx-max-samps-factor X] [--clock-source CLOCK]
                          [--time-source CLOCK] [-f HZ] [-b HZ] [--max-bandwidth HZ] [--rx-bandwidth HZ] [--tx-bandwidth HZ]
                          [--rx-oversample X] [--tx-oversample X] [--channel-bandwidth HZ] [-G DB] [-R DB] [-g DB]
                          [--auto-soft-tx-gain COUNT] [--auto-soft-tx-gain-clip-frac FRACTION]
                          [--phy {flexframe,newflexframe,ofdm}] [--max-channels MAX_CHANNELS] [--tx-upsample] [--no-tx-upsample]
                          [--channelizer {freqdomain,timedomain,overlap}] [--channelizer-enforce-ordering]
                          [--synthesizer {multichannel,freqdomain,timedomain}] [-r CHECK] [-c FEC] [-k FEC] [-m MODULATION]
                          [--soft-header] [--soft-payload] [-M N] [-C N] [-T N] [--subcarriers SUBCARRIERS]
                          [--mac {aloha,tdma,tdma-fdma,fdma}] [--aloha] [--tdma] [--fdma] [--tdma-fdma] [--slot-size SEC]
                          [--guard-size SEC] [--demod-overlap-size SEC] [--superslots] [--accurate-mac-tx-timestamps]
                          [--mac-timed-tx-delay SEC] [--arq] [--no-arq] [--arq-window NPACKETS] [--arq-enforce-ordering]
                          [--max-retransmissions COUNT] [--explicit-nak-window NPACKETS] [--explicit-nak-window-duration SEC]
                          [--selective-ack] [--no-selective-ack] [--amc] [--no-amc] [--short-per-window SEC]
                          [--long-per-window SEC] [--short-stats-window SEC] [--long-stats-window SEC]
                          [--mcsidx-up-per-threshold FRACTION] [--mcsidx-down-per-threshold FRACTION] [--mcsidx-alpha ALPHA]
                          [--mcsidx-prob-floor FRACTION] [--snapshot-frequency SEC] [--snapshot-duration SEC] [--mtu BYTES]
                          [--tap IFACE] [--queue {fifo,lifo,mandate,red}] [--fifo] [--lifo] [--taildrop] [--red]
                          [--packet-compression] [--force-gateway] [--collab-server-ip IP]

Named Arguments

--team

set team ID

Default: 0

-i

set node ID

-n

set number of nodes in network

--interactive

enter interactive shell after radio is started

Default: False

--config

load configuration options from a file

Logging

-d, --debug

print debugging information

-v, --verbose

be verbose

--verbose-packet-trace

show trace of packets written to network

-l

specify directory for log files

--log-iq

log IQ data

--log-iface

log packets received on interface

Default: []

--log-invalid-headers

log packets with invalid headers

Default: False

--log-snapshots

log snapshots

Default: False

--log-protobuf

log protobuf

Default: False

--compress-iface-logs

compress interface logs

Default: False

USRP

--addr

specify device address

Default: “”

--rx-subdev

specify RX subdevice

--tx-subdev

specify TX subdevice

--rx-antenna

set RX antenna

Default: “RX2”

--tx-antenna

set TX antenna

Default: “TX/RX”

--rx-max-samps-factor

set multiplicative factor for rx_max_samps

Default: 8

--tx-max-samps-factor

set multiplicative factor for tx_max_samps

Default: 8

--clock-source

set clock source

--time-source

set time source

Frequency and bandwidth

-f, --frequency

set center frequency (Hz)

Default: 1000000000.0

-b, --bandwidth

set bandwidth (Hz)

Default: 5000000.0

--max-bandwidth

set maximum bandwidth (Hz)

Default: 50000000.0

--rx-bandwidth

set receive bandwidth (Hz)

--tx-bandwidth

set transmit bandwidth (Hz)

--rx-oversample

set RX oversample factor

Default: 1.0

--tx-oversample

set TX oversample factor

Default: 1.0

--channel-bandwidth

set channel bandwidth (Hz)

Default: 1000000.0

Gain

-G, --tx-gain

set UHD TX gain (dB)

Default: 25

-R, --rx-gain

set UHD RX gain (dB)

Default: 25

-g, --soft-tx-gain

set soft TX gain (dB)

Default: -8

--auto-soft-tx-gain

use COUNT packets to calculate soft TX gain to attain 0dBFS

--auto-soft-tx-gain-clip-frac

clip fraction for automatic soft TX gain

Default: 1.0

PHY

--phy

Possible choices: flexframe, newflexframe, ofdm

set PHY

Default: “ofdm”

--max-channels

set maximum number of channels

Default: 10

--tx-upsample

use software upsampler on TX

Default: True

--no-tx-upsample

use USRP’s hardware upsampler on TX

Default: True

--channelizer

Possible choices: freqdomain, timedomain, overlap

set channelization algorithm

Default: “freqdomain”

--channelizer-enforce-ordering

enforce packet order when demodulating in channelizer

Default: False

--synthesizer

Possible choices: multichannel, freqdomain, timedomain

set synthesizer algorithm

Default: “freqdomain”

liquid-dsp

-r, --check

set data validity check: checksum, crc16, crc24, crc32, crc8, none, unknown

Default: crc32

-c, --fec0

set inner FEC: g2412, h128, h74, h84, none, rep3, rep5, rs8, secded2216, secded3932, secded7264, unknown, v27, v27p23, v27p34, v27p45, v27p56, v27p67, v27p78, v29, v29p23, v29p34, v29p45, v29p56, v29p67, v29p78, v39, v615

Default: rs8

-k, --fec1

set outer FEC: g2412, h128, h74, h84, none, rep3, rep5, rs8, secded2216, secded3932, secded7264, unknown, v27, v27p23, v27p34, v27p45, v27p56, v27p67, v27p78, v29, v29p23, v29p34, v29p45, v29p56, v29p67, v29p78, v39, v615

Default: none

-m, --mod

set modulation scheme: V29, apsk128, apsk16, apsk256, apsk32, apsk4, apsk64, apsk8, arb, arb128opt, arb16opt, arb256opt, arb32opt, arb64opt, arb64vt, ask128, ask16, ask2, ask256, ask32, ask4, ask64, ask8, bpsk, dpsk128, dpsk16, dpsk2, dpsk256, dpsk32, dpsk4, dpsk64, dpsk8, ook, psk128, psk16, psk2, psk256, psk32, psk4, psk64, psk8, qam128, qam16, qam256, qam32, qam4, qam64, qam8, qpsk, sqam128, sqam32, unknown

Default: qpsk

--soft-header

use soft decoding for header

Default: True

--soft-payload

use soft decoding for payload

Default: True

OFDM

-M

set number of OFDM subcarriers

Default: 48

-C, --cp

set OFDM cyclic prefix length

Default: 6

-T, --taper

set OFDM taper length

Default: 4

--subcarriers

set OFDM subcarrier allocation (.=null, P=pilot, +=data)

MAC

--mac

Possible choices: aloha, tdma, tdma-fdma, fdma

set MAC

Default: “tdma-fdma”

--aloha

use slotted ALOHA MAC

Default: “tdma-fdma”

--tdma

use pure TDMA MAC

Default: “tdma-fdma”

--fdma

use FDMA MAC

Default: “tdma-fdma”

--tdma-fdma

use TDMA/FDMA MAC

Default: “tdma-fdma”

--slot-size

set MAC slot size (sec)

Default: 0.035

--guard-size

set MAC guard interval (sec)

Default: 0.01

--demod-overlap-size

set demodulation overlap interval (sec)

Default: 0.005

--superslots

use TDMA superslots

Default: False

--accurate-mac-tx-timestamps

provide more accurate TX timestamps at a potential performance cost

Default: False

--mac-timed-tx-delay

delay for timed TX (sec)

Default: 0.0005

ARQ

--arq

enable ARQ

--no-arq

disable ARQ

--arq-window

set ARQ window size

Default: 1024

--arq-enforce-ordering

enforce packet order when performing ARQ

Default: False

--max-retransmissions

set maximum number of retransmission attempts

--explicit-nak-window

set explicit NAK window size

Default: 10

--explicit-nak-window-duration

set explicit NAK window duration (sec)

Default: 0.1

--selective-ack

send selective ACK’s

Default: True

--no-selective-ack

do not send selective ACK’s

Default: True

AMC

--amc

enable AMC

--no-amc

disable AMC

--short-per-window

time window used to calculate short-term PER

Default: 0.1

--long-per-window

time window used to calculate long-term PER

Default: 0.4

--short-stats-window

time window used to calculate short-term statistics, e.g., EVM and RSSI

Default: 0.1

--long-stats-window

time window used to calculate long-term statistics, e.g., EVM and RSSI

Default: 0.4

--mcsidx-up-per-threshold

set PER threshold for increasing modulation level

Default: 0.04

--mcsidx-down-per-threshold

set PER threshold for decreasing modulation level

Default: 0.1

--mcsidx-alpha

set decay factor for learning MCS transition probabilities

Default: 0.5

--mcsidx-prob-floor

set minimum MCS transition probability

Default: 0.1

Snapshots

--snapshot-frequency

set snapshot frequency (sec)

--snapshot-duration

set snapshot duration (sec)

Default: 0.5

Network

--mtu

set Maximum Transmission Unit (bytes)

Default: 1500

--tap

name of tap interface

Default: “tap0”

--queue

Possible choices: fifo, lifo, mandate, red

set network queuing algorithm

Default: “fifo”

--fifo

use FIFO network queue algorithm

Default: “fifo”

--lifo

use LIFO network queue algorithm

Default: “fifo”

--taildrop

use tail drop network queue algorithm

Default: “fifo”

--red

use RED network queue algorithm

Default: “fifo”

--packet-compression

enable network packet compress

Default: False

Collaboration

--force-gateway

force this node to act as a gateway

Default: False

--collab-server-ip

set collaboration server IP address