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 following
Acceptable Use Policy (AUP) regarding wireless interfaces.
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-GR (fedora core 4 with gnuradio
# software and required drivers installed) image to use the USRP
# devices.
tb-set-node-os $gr1 FC4-GR
tb-set-node-os $gr2 FC4-GR
# 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-GR (fedora core 4 with gnuradio
# software and required drivers installed) image to use the USRP
# devices.
tb-set-node-os $nodew1 FC4-GR
tb-set-node-os $nodew2 FC4-GR
tb-set-node-os $nodew3 FC4-GR
# 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/tunnel.py" 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. There are two Emulab specific directives that
you can use; tb-set-lan-setting sets a configuration
parameter for the entire lan. In the example above, we set the
frequency to be used for the lan to 906MHz. Per-node settings can
be specified with the tb-set-node-lan-setting directive.
No per-node lan settings are available at this time for the GNU
Radio network interface, but we will offer some in the near
future (such as "gain" and "carrier sense threshold").
- You currently cannot change the GNU Radio lan settings on the fly
as you can with wifi nodes in Emulab. If you want to change
them, you must modify your experiment and be sure to check the
box to reboot the nodes in order to force the GNU Radio
interfaces to pick up the new settings.
- The GNU Radio interfaces appear as "gr0" in the output of ifconfig.
- You must use the FC4-GR image (or a custom one based on
it) to take advantage of the GNU Radio wireless interfaces.