Running the Radio

The radio is initialized via Python. The dragonradio binary will treat its first argument as the name of a Python script to run to set up the radio, ignoring all further arguments. The Python script will receive all but the zeroth argument (the name of the dragonradio binary) as its arguments. Radio scripts are located in the scripts directory.

The radio must be run with root privileges in order to properly configure the USRP and network. Help removing this restriction is welcome.

The script will create a virtualenv environment containing all needed Python modules. You may either activate this virtualenv before invoking the radio, or you may set the VIRTUAL_ENV environment variable to point to the virtualenv before you invoke dragonradio.

The Stand-alone Radio

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

VIRTUAL_ENV=env ./dragonradio scripts/ \
   --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=env ./dragonradio scripts/ \
   --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 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=env ./dragonradio scripts/ \
   --config config/srn/radio.conf \
   --colosseum-ini config/srn/colosseum_config.ini
   --collab-server-ip \
   --bootstrap --foreground \
   -b 10e6 \
   -l logs \

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

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


After starting up, the radio will create a tap0 device with IP address 10.10.10.NODEID and a netmask of, where NODEID is the node ID. Packets sent to this subnet will in turn be sent over the radio.


The radio provides extensive logging. The low-level C++ radio will create a log in HDF5 format named radio.h5. If the file radio.h5 exists, it will create radio-N.h5 where N is the first number such that radio-N.h5 does not exist; this allows the radio to be restarted if it crashes while guaranteeing it won’t overwrite old logs.

Each HDF5 log has the following attributes:

  1. config: The radio configuration, dumped from the Config object used to configure the radio.

  2. version: The version of the radio.

  3. node_id: The numeric radio node identifier.

  4. start: Start time of logging, in seconds since the epoch.

A HDF5 log contains the following tables:

  1. event: Logged messages, consisting of a time (offset from start of the log) and a string.

  2. recv: Received packets.

  3. selftx: Self-transmissions.

  4. send: Sent packets.

  5. slots: IQ data received by MAC.

  6. snapshots: Snapshotted IQ data.

Command-line Argument Reference

Run dragonradio.

usage: dragonradio SCRIPT [-h] [-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] [--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] [--long-stats-window SEC]
                          [--mcsidx-up-per-threshold FRACTION] [--mcsidx-down-per-threshold FRACTION] [--mcsidx-alpha ALPHA] [--mcsidx-prob-floor FRACTION]
                          [--snapshot-period SEC] [--snapshot-duration SEC] [--mtu BYTES] [--tap IFACE] [--queue {fifo,lifo,mandate}] [--fifo] [--lifo]
                          [--packet-compression] [--force-gateway] [--collab-server-ip IP]

Named Arguments


set node ID


set number of nodes in network


enter interactive shell after radio is started

Default: False


load configuration options from a file


-d, --debug

print debugging information

-v, --verbose

be verbose


show trace of packets written to network


specify directory for log files


log IQ data


log packets received on interface

Default: []


log packets with invalid headers

Default: False


log snapshots

Default: False


log protobuf

Default: False


compress interface logs

Default: False



specify device address

Default: “”


specify RX subdevice


specify TX subdevice


set RX antenna

Default: “RX2”


set TX antenna

Default: “TX/RX”


set multiplicative factor for rx_max_samps

Default: 8


set multiplicative factor for tx_max_samps

Default: 8


set clock source


set time source

Frequency and bandwidth

-f, --frequency

set center frequency (Hz)

Default: 1000000000.0

-b, --bandwidth

set bandwidth (Hz)

Default: 5000000.0


set maximum bandwidth (Hz)

Default: 50000000.0


set receive bandwidth (Hz)


set transmit bandwidth (Hz)


set RX oversample factor

Default: 1.0


set TX oversample factor

Default: 1.0


set channel bandwidth (Hz)

Default: 1000000.0


-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


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


clip fraction for automatic soft TX gain

Default: 1.0



Possible choices: flexframe, newflexframe, ofdm

set PHY

Default: “ofdm”


set maximum number of channels

Default: 10


use software upsampler on TX

Default: True


use USRP’s hardware upsampler on TX

Default: True


Possible choices: freqdomain, timedomain, overlap

set channelization algorithm

Default: “freqdomain”


enforce packet order when demodulating in channelizer

Default: False


Possible choices: multichannel, freqdomain, timedomain

set synthesizer algorithm

Default: “freqdomain”


-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


use soft decoding for header

Default: True


use soft decoding for payload

Default: True



set number of OFDM subcarriers

Default: 48

-C, --cp

set OFDM cyclic prefix length

Default: 6

-T, --taper

set OFDM taper length

Default: 4


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



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

set MAC

Default: “tdma-fdma”


use slotted ALOHA MAC

Default: “tdma-fdma”


use pure TDMA MAC

Default: “tdma-fdma”



Default: “tdma-fdma”



Default: “tdma-fdma”


set MAC slot size (sec)

Default: 0.035


set MAC guard interval (sec)

Default: 0.01


set demodulation overlap interval (sec)

Default: 0.005


use TDMA superslots

Default: False



enable ARQ


disable ARQ


set ARQ window size

Default: 1024


enforce packet order when performing ARQ

Default: False


set maximum number of retransmission attempts


set explicit NAK window size

Default: 10


set explicit NAK window duration (sec)

Default: 0.1


send selective ACK’s

Default: True


do not send selective ACK’s

Default: True



enable AMC


disable AMC


time window used to calculate short-term PER

Default: 0.1


time window used to calculate long-term PER

Default: 0.4


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

Default: 0.4


set PER threshold for increasing modulation level

Default: 0.04


set PER threshold for decreasing modulation level

Default: 0.1


set decay factor for learning MCS transition probabilities

Default: 0.5


set minimum MCS transition probability

Default: 0.1



set snapshot period (sec)


set snapshot duration (sec)

Default: 0.5



set Maximum Transmission Unit (bytes)

Default: 1500


name of tap interface

Default: “tap0”


Possible choices: fifo, lifo, mandate

set network queuing algorithm

Default: “fifo”


use FIFO network queue algorithm

Default: “fifo”


use LIFO network queue algorithm

Default: “fifo”


enable network packet compress

Default: False



force this node to act as a gateway

Default: False


set collaboration server IP address