Spectrum Wars – A Dynamic Spectrum Access Game Using Iris

One of the more interesting demo systems we’ve built recently using Iris has been a 4-player game called Spectrum Wars. The game shows how flexible software radios can dynamically change the properties of their wireless signals to avoid interference and efficiently use available spectrum. It also emphasizes the challenges of coordinating a transmitter and receiver to maintain a wireless link in a very dynamic spectrum environment.

Teams of two play the game – one team player controls a radio transmitter and the other controls a receiver. Graphical interfaces are used to manually choose the carrier frequency, bandwidth and gain. The objective of the game is to create a wireless link between the transmitter and receiver and to transfer as much data as possible over that link. At the same time, the opposing team tries to do likewise using the same spectrum band. A team can choose to play nicely by avoiding the signals of the opposing team, or to play aggressively by interfering with the signals of the opposing team and preventing them from creating and maintaining a link.

To make things more difficult a “primary user” (with priority access to the spectrum) also uses the spectrum band and transmits a high-power, narrow-bandwidth signal which sweeps to new randomly-selected carrier frequencies every 5 seconds.

Spectrum Wars was inspired by the spectrum challenge organised by DARPA in the US in 2013. The game was initially demonstrated at the CTVR Telecommunications Showcase in Dublin, in September 2013 (http://ledoyle.wordpress.com/2013/10/09/ctvr-showcase-2013-lighting-up-the-light-house/) and has since been played at FOSDEM 2014 in Brussels (https://fosdem.org/2014) and the Future Internet Assembly in Athens (https://www.fi-athens.eu/). More recently, it was enhanced with the addition of an automated team and demonstrated at IEEE DySPAN 2014 (http://dyspan2014.ieee-dyspan.org/) where it won the award for best demonstration.

In my next post, I’ll describe the Iris radios used to build Spectrum Wars.

New Iris Release – v1.0.1

Release 1.0.1 of the Iris software radio architecture is now available:

– Paul Sutton (paul@softwareradiosystems.com)
– Andre Puschmann (andre.puschmann@tu-ilmenau.de)

Release 1.0.1 features two new stack components – TunTap and AlohaMac.
TunTap provides a connector between Iris and virtual network device drivers TUN/TAP on Linux systems. AlohaMac provides a simple ALOHA medium access control layer. Andre has also written an excellent blog post about the AlohaMac component.
The release also provides performance improvements and bugfixes for the OfdmModulator and OfdmDemodulator phy components.

Find out more:
Iris-discuss mailing list

Iris Controllers – building “smarter” radios

The Iris architecture can be used to build software radios using plugin libraries called components. These components expose parameters which can be changed to control how the component operates. XML configuration files are used to specify the components and parameters of a particular radio and can be used to reconfigure a radio while it is running. Self-configuring software radios can be built using another type of plugin library called a controller.

Controllers have a global view of all engines and components in a radio and can reconfigure the running radio at any time by adjusting component parameters. A simple controller could be used for example to scan frequencies in a wireless receiver.


Here, the radio consists of a Usrp front-end receiver, an OFDM demodulator and a file writer. The controller simply enters a loop, reconfiguring the receive frequency on the Usrp radio front-end and then sleeping for a set amount of time. Of course, with this design there is no mechanism for the radio to lock onto a received signal – it will simply continue scanning forever. Some mechanism is needed to allow a component to notify the controller to stop when a signal is received.

In Iris, this is what component events are used for. Building on the previous example, we could design the OFDM demodulator so that it triggers an event whenever an incoming signal is detected. Controllers can subscribe to events on specific components in order to be notified when that event is triggered. In this way, our controller gets notified when the OFDM demodulator detects an incoming signal and exits the scanning loop, thus locking onto the signal of interest.


Using controllers, events and parameters in this way, we can build “smart” self-configuring radios which adapt to changes in their operating environment to maintain and optimize communications links.

The Iris Architecture

For the first Iris blog post, I thought it would be a good idea to briefly discuss the Iris architecture and the various elements which make it up.

Iris is a program and a set of libraries written in C++ which can be used to build software radios. A software radio is a wireless system in which many of the tasks for generating a signal for transmission, or receiving and extracting data from a transmitted signal are carried out in software, often on general-purpose processors such as those found in PCs or laptops. Here, a radio is any device which sends or receives data wirelessly (this could be anything from a digital TV receiver to an 3GPP LTE modem used in modern mobile phones). One of the major advantages of building a radio in software is the flexibility it provides. In software, it’s very easy to dramatically change the properties of the radio (for example, switching from a garage door opener to an 802.11 wifi access point or vice versa). Iris is designed to support and exploit this flexibility or reconfigurability.

Iris is built using a plugin architecture. Each plugin is a library which does a specific job (e.g. data scrambling, OFDM modulation etc.) and which provides a generic API for the core Iris program to use. These libraries can be dynamically loaded at runtime and used within a software radio design. The main type of Iris plugin is called a component. Components typically process streams of data. They have input and output ports and work by reading data from one or more of their inputs and writing data to one or more outputs. In Iris, components run within an engine. The engine is responsible for loading the component library, initialising the component, providing input data to it, calling it to work on that input data, taking output data from it, destroying it and unloading the library when the radio is shut down. Typically, a component in an Iris radio will run in a loop, repeatedly processing sets of data before it is destroyed and unloaded. Components can expose parameters which control how they operate and these parameters may be used to reconfigure a radio while it is running.

Iris currently has two types of engines (and thus two types of components) – the Phy engine and the Stack engine. Phy components typically operate on a stream of signal data which flows in one direction from input to output and execute only when called by their Phy engine. Examples include modulators and demodulators, channel coders and decoders, data scramblers etc. Stack components on the other hand may support bidirectional data, coming both from above and below. They run their own threads and can generate sets of data at any time, in addition to processing data coming from above and below. Stack component examples include complete MAC layers, network routing layers and data encryption layers.

In order to run a radio in Iris, an XML configuration file is used. This file tells the core Iris program which engines will be used to create the radio, and which components will run within those engines. It also includes the initial parameter settings for each component.

An example XML configuration file for a simple OFDM transmitter is shown below:

<softwareradio name="Radio1">

  <engine name="phyengine1" class="phyengine">

    <component name="filerawreader1" class="filerawreader">
      <parameter name="filename" value="testdata.txt"/>
      <parameter name="blocksize" value="140"/>
      <parameter name="datatype" value="uint8_t"/>
      <port name="output1" class="output"/>

    <component name="ofdmmod1" class="ofdmmodulator">
      <port name="input1" class="input"/>
      <port name="output1" class="output"/>

    <component name="signalscaler1" class="signalscaler">
      <parameter name="maximum" value="0.9"/>
      <port name="input1" class="input"/>
      <port name="output1" class="output"/>

    <component name="usrptx1" class="usrptx">
      <parameter name="frequency" value="5010000000"/>
      <parameter name="rate" value="1000000"/>
      <parameter name="streaming" value="false"/>
      <port name="input1" class="input"/>


  <link source="filerawreader1.output1" sink="ofdmmod1.input1" />
  <link source="ofdmmod1.output1" sink="signalscaler1.input1" />
  <link source="signalscaler1.output1" sink="usrptx1.input1" />


This XML configuration specifies 4 Phy components which will run within a single Phy engine. In this radio, data is read from the file “testdata.txt”, modulated into an OFDM signal, scaled in magnitude and transmitted with a specific carrier frequency and bandwidth by a radio front-end, in this case an Ettus Research Universal Software Radio Peripheral (USRP). The resulting radio looks like this:


You can see that some initial parameter values are provided for some of the components in the radio. If a component has parameters which are not specified in the XML configuration, these are set to default values (as is the case for the OFDM modulator here). An XML configuration file specifies the structure of an Iris radio when it is initially loaded and run. However, it can also be used to reconfigure a radio while it is running. This can be done for example by changing the value of a parameter in the file, saving it and prompting Iris to reload it. Iris will compare the configuration in the file with that of the running radio, find that one of the parameters has changed and reconfigure that parameter as required.

Using the XML configuration file, an Iris user can easily reconfigure a running radio. However, we often need a radio to reconfigure itself instead of relying on user input. This might be the case for example, when we wish to design a receiver which scans a set of channels for signals of interest. We have already discussed the main type of Iris plugin – the component. The second type of plugin which is used in the Iris architecture supports this self-configuring behaviour – the controller. Controllers are libraries which are loaded at runtime, just like components. However, a controller does not run in an engine and typically does not operate on streams of data. Instead, a controller has a global view of a running radio and can reconfigure any component in the radio at any time.

In my next post, I’ll discuss the role that controllers can play in an Iris software radio and show some examples of how controllers can be used to make a “smarter” radio which reconfigures itself as required.