Clone the Simulator virtual RF testbed and start hacking today!
Click here and we’ll be in touch with submission instructions!
To summarize the competition’s format, competitors are tasked with transmitting data from one radio node to another within a congested or hostile channel. Competitors control both ends of the link, and may use any physical layer of their liking to transmit and deliver the data. Competitors earn points based on how many sequential data packets they deliver. Radio links must be reliable, and as such any dropped, duplicate, or missing packets submitted to the scoring engine will adversely affect scoring.
The Radio Resilience Competition is an ongoing and evolving contest. Daily Matches are the Competition’s main event, since they enable competitors to get continuous feedback and iterate on their radio performance.
Periodically, the organizers will run events, such as the week-long GNU Radio Conference “CTF” event. These events typically involve a series of Scrimmages leading up to a Final. The Scrimmages are for testing, gathering data, and debugging, and have no bearing on the competition’s outcome. The final is what determines placement in the event. The final may be a single match, or may be comprised of several matches to exercise radio performance under different conditions.
Each match is comprised of one competitor team playing against a simulated environment called the Simulator. The Simulator is a virtual RF testbed comprised of containerized microservices that make up different functions in the spectrum, controlled by docker-compose. Two instances of the competitor’s radio submission will be created (collectively reffered to as Blue Radios). One is designated the “transmitter” (Blue TX) and the other the “receiver” (Blue RX), however the same Docker image is used for each. This naming convention refers to the direction in which scoring traffic flows, and despite their labels, both competitor radio instances are equally capable and allowed to transmit.
Environmental components that are instantiated are a Channel Simulator instance, a Scoring Instance (which is also the traffic source and sink), and one or several Red Radio applications that also occupy the spectrum. These Red Radios make the challenge interesting – they introduce interference, and create conditions that the Blue Radios must overcome. Optional Channel Condition containers create other types of environmental effects that Blue Radios must contend with.
Matches will last between 10 seconds and 3 minutes in duration, where traffic is sourced from the Scoring Instance to the Blue TX instance. The match begins when all container instances come online and pass a health check. At the end of each match, the Channel Simulator is disabled, allowing no additional traffic to be passed between the Blue Radios. The Scoring Instance stops counting packets when match duration elapses.
To allow the Simulator to run on a range of hardware, the Simulator accounts for time in samples rather than against a wall clock. This means the Simulator will not drop samples if run on an old laptop, or if the system running it experiences network latency. The Simulator typically assumes a 1 MHz-wide channel for ease of accounting. A 30-second long match in a 1 MHz virtual channel concludes after the 30 millionth sample is sent.
Because the Simulator runs slower than the wall clock, a Timeout may be instituted during matches to manage resource availability. This timeout is typically 10 or 30 minutes of wall clock time. If the timeout elapses before the match concludes, we will do our best to count the competitor’s score up to that point (but make no guarantee to do so).
Since reliability is an essential attribute of a useful wireless protocol, the scoring algorithm has been designed with this in mind. To summarize scoring, the score a competitor receives within a match is equal to the highest sequence number of consecutive packets delivered, starting from the first packet.
Packets generated by the scoring instance will be comprised of a header, pseudorandom data, and a signature. In order to be scored, packets must be submitted to the Scoring Instance by Blue RX bit-for-bit, exactly as they were delivered to Blue TX by the Scoring Instance. Packets within a match may be of uniform or varying size, though for consistency and fairness all competitors will be given identical packet size demands within each set of matches.
Here are some examples for a hypothetical load of 100 packets: - Blue Radios deliver packets 1 through 100. The competitor’s score is 100. - Blue Radios deliver packets 1 through 33, misses packet 34, and delivers packets 35 through 100. The competitor’s score is 33. - Blue Radios deliver 0 packets. The competitor’s score is 0. - Blue Radios deliver packets 1 through 100, but drops the last octet from packet 3. The competitor’s score is 2.
How to Play
Radio Resiliency Competition takes place on a virtual RF testbed called the Simulator. Simulation lowers the barrier to entry by reducing cost, and increases the rate of iteration for competitors and organizers alike. It also allows competitors to locally test with an exact replica of the software that will run the Competition’s matches.
Competition infrastructure is implemented in a microservice architecture that uses
docker-compose to orchestrate the containers that comprise it. A diagram and description of each microservice follows.
The Channel Simulator microservice simulates the RF spectrum. It runs a GNU Radio flowgraph that takes in IQ ZeroMQ streams from any number of sources, muxes them together, and then emits a single IQ ZeroMQ stream representing the combined spectrum.
Any number of channel profiles or conditions may be simulated. This includes but is not limited to varying the effective link budget between the transmitter and receiver nodes, multipath fading, and dynamic channel conditions.
Blue Radios (Blue TX / Blue RX)
The Blue Radio microservice container is the competitor’s software radio design. During each match, two instances will be created – one serves as the “transmitter” (Blue TX, sometimes called Blue 1), and the other serves as the “receiver” (Blue RX, sometimes called Blue 2). This nomenclature only designates the flow of scoring traffic within a match; both competitor radio nodes are equally capable of transmitting.
Each Blue Radio instance receives the spectrum from the Channel Simulator via an IQ ZeroMQ stream. Both instances can transmit via separate IQ ZeroMQ streams that source IQ to the Channel Simulator. Additionally, Blue Radios can connect to the Scoring Instance via ZeroMQ. The Scoring Instance will serve scoring traffic only to Blue TX, and will only score data packets submitted from Blue RX.
The RRC competition infrastructure comes with a working competitor radio implementation! Competitors are encouraged to build, run, and submit this basic modem to verify their account credentials and get started. (They are encouraged to then build on top of it to be competitive, of course!) While GNU Radio is used throughout the rest of the infrastructure and is what is supported, competitors are welcome to use any signal processing framework of their choosing as long as they are able to adhere to the same I/O convention.
Red Radio applications are microservices that transmit IQ within the RF spectrum. Competitors have no control over these! Red Radios may take the form of other benign radio systems, or they may be hostile and act adversarially. RRC organizers will add more Red Radio designs over time.
The Scoring Instance is the microservice responsible for generating scoring traffic. At the start of the match, the Scoring Instance will begin sending packets over ZeroMQ to Blue TX. The Scoring Instance will also listen for packets originating from Blue RX over ZeroMQ. Packet scoring will stop precisely at the expiration of match duration.
Blue Radio Submission
Competitors submit their entries by tagging and pushing their Blue Radio Docker image to a GitLab container registry. RRC organizers will provide a repository and path when you register.