Overview

DragonRadio consists of a C++ core that is exposed to Python using the excellent pybind11 library—the dragonradio binary embeds a Python interpreter. The radio is initialized and configured in Python, a process driven by a Python script.

Capabilities and Security

DragonRadio requires the CAP_SYS_NICE and CAP_NET_ADMIN capabilities to configure the USRP and network. Strictly speaking, only the CAP_NET_ADMIN capability is necessary; without the CAP_SYS_NICE capability, the radio will run, but UHD will complain about not being able to change thread priorities.

There are several ways to provide these capabilities:

  1. Run the dragonradio binary as root or another privileged user.

  2. Set the setuid bit on the dragonradio binary and chown it to a privileged user (like root).

  3. Use setcap to set file capabilities on the dragonradio binary, e.g.,

    setcap cap_sys_nice,cap_net_admin+p dragonradio

On startup, dragonradio drops all capabilties, keeping only CAP_SYS_NICE and CAP_NET_ADMIN in its permitted set. These capabilities are temporarily raised when needed. If dragonradio is invoked with the setuid bit set, it will set its effective uid to the uid of the user who invoked it after dropping capabilities.

Networking

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

Logging

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. node_id: The numeric radio node identifier.

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

  4. version: The version of the radio.

A HDF5 log contains the following tables:

  1. arq_event: ARQ events.

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

  3. recv: Received packets.

  4. selftx: Self-transmissions.

  5. send: Sent packets.

  6. slots: IQ data received by MAC.

  7. snapshots: Snapshotted IQ data.