Skip to content. | Skip to navigation

Personal tools


You are here: Home / Wiki / Gnuradio


Emulab Tutorial - Using GNU Radio in Emulab

Emulab Tutorial - Using GNU Radio in Emulab

Several GNU Radio Universal Software Radio Peripheral (USRP) hardware devices are connected (via USB2) to Emulab nodes scattered around the Merrill Engineering Building on the University of Utah campus. Each of these nodes also contains one or more wifi interfaces, and the physical distribution of these nodes can be seen via the GNU Radio wireless floormaps page. The colored dots on this page indicate where the wireless nodes are located. If you click on dot, you will get more information about the node it represents, including the types of interfaces available.

Each of the deployed USRP devices is currently outfitted with one RFX900 (flex900) 900MHz band transceiver daughterboard. The RFX900s each have a directly attached 900MHz "rubber duck" antenna. Other daughterboard choices will likely be offered in the future.

Before using a GNU Radio USRP interface in an experiment, please read the '''Acceptable Use Policy''' (AUP) regarding GNU Radio wireless interfaces on Emulab nodes.

Acceptable Use Policy

By using our GNU Radio USRP nodes, you agree to be bound by this AUP.

  • Receiving: You may listen to and monitor anything you like. If you happen to observe "private" information, such as passwords, you will not exploit that information, and you will take care not to let it leak out publicly, e.g., in log files.
  • Transmitting: It is your responsibility to comply with all applicable FCC regulations while using Emulab's USRP hardware.
  • Questions and Exceptions: send to Testbed Ops if you're not sure, or want an exception.

Creating Experiments that include USRP-equipped Nodes

You can currently use the USRP hardware in Emulab in two ways: As "Bare metal" hardware with nothing setup, and as a wireless network interface with full IP connectivity over a prototype CMSA/CD layer 2 MAC.

Allocating a "bare metal" USRP

Allocating a node outfitted with a USRP is a simple matter of asking for the "usrp" or "flex900" features in your NS file. Here is a small example showing the allocation of a couple of nodes equipped with USRP hardware and RFX900 daughterboards:

       source tb_compat.tcl
       set ns [new Simulator]

       # First, create the node objects
       set gr1 [$ns node]
       set gr2 [$ns node]

       # Currently you must use the FC4-WIRELESS (fedora core 4 with gnuradio
       # software and required drivers installed) image to use the USRP
       # devices.
       tb-set-node-os $gr1 FC4-WIRELESS
       tb-set-node-os $gr2 FC4-WIRELESS

       # Add a desire for the "usrp" or "flex900" feature.
       # $gr1 add-desire usrp 1.0
       # $gr2 add-desire usrp 1.0
       $gr1 add-desire flex900 1.0
       $gr2 add-desire flex900 1.0

       # Turn on static routing and run.
       $ns rtproto Static
       $ns run

Some notes on "bare metal" use:

  • When allocated as "bare metal" devices, the GNU Radio USRP hardware is provided raw. It is up to you to set it up and use it. The GNU Radio software is available on these nodes, but may be somewhat out of date. We anticipate that people will want to provide their own software in most cases. Emulab has convenient mechanisms for loading software and starting up commands on boot. Be sure to read through the Emulab Tutorial to learn more.
  • The "usrp" feature is less specific than the "flex900" feature. There is currently no distinction, but as soon as other USRP daughterboard choices are made available, the difference will become important. The "usrp" feature asks for a node with USRP hardware attached, regardless of what daughterboards are present on it. The "flex900" feature refers to nodes that also have an RFX900 transceiver daughterboard attached (the presence of a USRP motherboard is implied).
  • In the example above, we let Emulab decide what USRP-equipped nodes to pick. This is not an ideal approach, as Emulab does not currently track the connectivity of nodes, and so might pick a set of nodes (randomly) that cannot communicate with each other. See the section in the wifi tutorial on choosing your nodes for more information on how to overcome this problem.
  • add-desire is a general Emulab mechanism and is utilized to request specific features that have been attached to certain nodes. It is not specific to GNU Radio equipped nodes.

Using the USRP as a managed wireless network interface

To use GNU Radio USRP hardware as interfaces in an Emulab-managed wireless network experiment, you must provide a few Emulab specific NS directives in your NS file, which are illustrated in the following small example:

	source tb_compat.tcl
	set ns [new Simulator]

	# Allocate the nodes.  Their wireless capability is determined later,
	# by the type of networks you request to be set up on them.
	set nodew1 [$ns node]
	set nodew2 [$ns node]
	set nodew3 [$ns node]

	# A wireless lan connecting the three nodes.
        # The lan speed set here (500Kb) is just a placeholder; the rate
        # is actually set below.
	set lan0 [$ns make-lan "$nodew1 $nodew2 $nodew3" 500Kb 0ms]

	# Choose the wireless lan protocol.
	tb-set-lan-protocol $lan0 "flex900"

	# These two wireless lan settings are required for a GNU Radio
        # network lan.
	tb-set-lan-setting $lan0 "frequency" 906M
        tb-set-lan-setting $lan0 "rate" 250k

	# Currently you must use the FC4-WIRELESS (fedora core 4 with gnuradio
        # software and required drivers installed) image to use the USRP
        # devices.
	tb-set-node-os $nodew1 FC4-WIRELESS
	tb-set-node-os $nodew2 FC4-WIRELESS
	tb-set-node-os $nodew3 FC4-WIRELESS

	# Turn on static routing.
	$ns rtproto Static
	$ns run

Notes on using the GNU Radio USRPs as network interfaces:

  • lan0 is created with standard make-lan directive, but the bandwidth parameter is ignored (just put in 500Kb as shown above). Instead you must specify the rate at which the radios will transmit with the tb-set-lan-setting command (as illustrated in the example).
  • After you create the lan, you need to choose the protocol for the lan with the tb-set-lan-protocol directive. Currently, you can only set the protocol to flex900. If you fail to set the protocol, the lan will consist of wired links, most likely with delay nodes inserted!
  • You must specify the frequency and rate for your GNU radio network lan. Failure to set these will result in network setup failure. The example above illustrates how to do this. Suffix the frequency with "M" for megahertz, and suffix the rate with "k" for kilobits/sec or "m" for megabits/sec.
  • You can learn more about the prototype CSMA/CD protocol Emulab uses to setup a GNU Radio wireless lan by checking out the gnuradio-examples cvs module from the GNU Radio project and examining the "python/gmsk2/" program and the README in the same directory. The presntation of the interface is accomplished with the tun/tap driver in conjunction with the above user space program which passes the packets back and forth between the radio and the Linux network stack.
  • As in the "bare metal" example above, we don't explicitly specify which nodes to use in the topology. You will probably want to do this. The section from the wifi tutorial on choosing your nodes has more information.
  • Wireless lans allow a number of configuration parameters to be specified, either for the lan as a whole, or for individual members of a lan. In the example above, we set the frequency to be used for the lan to 906MHz. Read more about supported parameters in the GNU Radio Link Configuration Settings section of this document.
  • The GNU Radio interfaces appear as "gr0" in the output of ifconfig.
  • You must use the FC4-WIRELESS image (or a custom one based on it) to take advantage of the GNU Radio wireless interfaces.

GNU Radio Link Configuration Settings

Wireless LANs allow a number of configuration parameters to be specified, either for the lan as a whole, or for individual members of a lan. There are two Emulab specific directives that you can use; tb-set-lan-setting sets a configuration parameter for the entire lan. Per-node settings can be specified with the tb-set-node-lan-setting directive. Here is a guide to what you can currently specify:

  • frequency: (required) Transmit and receive on this frequency (i.e., 907M).
  • rate: (required) Transmit and receive at this bitrate. Values above 250k and 500k typically result in extremely high loss rates between our nodes.
  • carrierthresh: Set the carrier detection threshold to this value (specified in decibels, but without unit postfix; i.e., "30").
  • rxgain: Set the receiver gain to this value (specified in decibels, but without unit postfix).

After your experiment is swapped in, you can change the above settings on the fly, using either the link_config script on, or with the Emulab XMLRPC interface. For example, if you want to change the frequency at which a LAN of GNU Radio devices is transmitting, you can use link_config (remember, for GNU Radio devices, you must set both the frequency and rate parameters!):

        link_config myproj myexp lan0 frequency=916M rate=250k

Or you can use the [BOSS(xmlrpcapi.php3,XMLRPC interface)]] from your desktop or from users: link_config proj=myproj exp=myexp
                link=lan0 "params={'frequency': '916M', 'rate': '250k'}"