Commit 84042868 authored by David Johnson's avatar David Johnson

Add some params and dynamic config notes, split into sections as well.

parent f35247a7
<!--
EMULAB-COPYRIGHT
Copyright (c) 2004, 2006 University of Utah and the Flux Group.
Copyright (c) 2004-2007 University of Utah and the Flux Group.
All rights reserved.
-->
<center>
<h2>Emulab Tutorial - Using GNU Radio in Emulab</h2>
</center>
<p>
Several <a href="http://www.gnu.org/software/gnuradio/">GNU Radio </a>
<a
......@@ -20,16 +21,39 @@ 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.
</p>
<p>
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.
</p>
<p>
Before using a GNU Radio USRP interface in an experiment, please read the
<a href="#GnuRadioAUP"><b>Acceptable Use Policy</b> (AUP)</a> regarding
GNU Radio wireless interfaces on Emulab nodes.
</p>
<p>
This document is broken up into the following sections:
<ol>
<li><a href="#GnuRadioAUP">Acceptable Use Policy</a>
<li><a href="#CreateExp">Creating Experiments that include USRP-equipped Nodes</a>
<ol>
<li><a href="#BareMetal">Allocating a "bare metal" USRP</a>
<li><a href="#GRWireless">Using the USRP as a managed wireless network
interface</a>
</ol>
<li><a href="#LinkConfig">GNU Radio Link Configuration Settings</a>
<li><a href="#DynamicLinkConfig">Dynamically Configuring GNU Radio Links</a>
</ol>
</p>
<h3><a name="GnuRadioAUP">Acceptable Use Policy</a></h3>
<p>
Before using a GNU Radio USRP interface in an experiment,
please read the following
<b>Acceptable Use Policy</b> (AUP) regarding wireless interfaces.
By using our GNU Radio USRP nodes, you agree to be bound by this AUP.
</p>
......@@ -51,26 +75,23 @@ By using our GNU Radio USRP nodes, you agree to be bound by this AUP.
</ul>
<font size=+2>Creating Experiments that include USRP-equipped Nodes:</font>
<br>
<br>
<h3><a name="CreateExp">Creating Experiments that include USRP-equipped Nodes</a></h3>
<p>
You can currently use the USRP hardware in Emulab in two ways: As
<a href="#BareMetal">"Bare metal" hardware</a> with nothing setup, and
as a <a href="#GRWireless">wireless network interface</a> with full IP
connectivity over a prototype CMSA/CD layer 2 MAC.
</p>
<h4><a name="BareMetal">Allocating a "bare metal" USRP</a></h4>
<br>
<br>
<a NAME="BareMetal"></a>
<font size=+1>Allocating a "bare metal" USRP:</font><br>
<p>
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:
</p>
<code><pre>
source tb_compat.tcl
set ns [new Simulator]
......@@ -79,11 +100,11 @@ hardware and RFX900 daughterboards:
set gr1 [$ns node]
set gr2 [$ns node]
# Currently you must use the FC4-GR (fedora core 4 with gnuradio
# 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-GR
tb-set-node-os $gr2 FC4-GR
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
......@@ -94,8 +115,9 @@ hardware and RFX900 daughterboards:
# Turn on static routing and run.
$ns rtproto Static
$ns run </code></pre>
</p>
<p>
Some notes on "bare metal" use:
<ul>
......@@ -130,15 +152,15 @@ Some notes on "bare metal" use:
to request specific features that have been attached to
certain nodes. It is not specific to GNU Radio equipped nodes.
</ul>
</p>
<h4><a name="GRWireless">Using the USRP as a managed wireless network interface</a></h4>
<a NAME="GRWireless"></a>
<font size=+1>Using the USRP as a managed wireless network interface:</font>
<p>
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:
</p>
<code><pre>
source tb_compat.tcl
......@@ -163,17 +185,19 @@ small example:
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
# 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-GR
tb-set-node-os $nodew2 FC4-GR
tb-set-node-os $nodew3 FC4-GR
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 </code></pre>
</p>
<p>
Notes on using the GNU Radio USRPs as network interfaces:
<ul>
<li> <tt>lan0</tt> is created with standard <tt>make-lan</tt>
......@@ -186,7 +210,7 @@ Notes on using the GNU Radio USRPs as network interfaces:
<li> After you create the lan, you need to choose the
<em>protocol</em> for the lan with the
<tt>tb-set-lan-protocol</tt> directive. Currently, you can only
set the protocol to <tt>flex900.</tt>. If you fail to set the
set the protocol to <tt>flex900</tt>. If you fail to set the
protocol, the lan will consist of wired links, most likely with
delay nodes inserted!
......@@ -213,24 +237,69 @@ Notes on using the GNU Radio USRPs as network interfaces:
<li> 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; <tt>tb-set-lan-setting</tt> 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 <tt>tb-set-node-lan-setting</tt> 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").
<li> 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.
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 <a href="#LinkConfig">GNU Radio Link Configuration
Settings</a> section of this document.
<li> The GNU Radio interfaces appear as "gr0" in the output of ifconfig.
<li> You must use the <tt>FC4-GR</tt> image (or a custom one based on
<li> You must use the <tt>FC4-WIRELESS</tt> image (or a custom one based on
it) to take advantage of the GNU Radio wireless interfaces.
</ul>
</p>
<h3><a name="LinkConfig">GNU Radio Link Configuration Settings</a></h3>
<p>
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; <tt>tb-set-lan-setting</tt> sets a configuration
parameter for the entire lan. Per-node settings can
be specified with the <tt>tb-set-node-lan-setting</tt> directive.
Here is a guide to what you can currently specify:
</p>
<p>
<ul>
<li> <tt>frequency</tt>: (<b>required</b>) Transmit and receive on this
frequency (i.e., 907M).
<li> <tt>rate</tt>: (<b>required</b>) Transmit and receive at this bitrate.
Values above 250k and 500k typically result in extremely high loss rates
between our nodes.
<li> <tt>carrierthresh</tt>: Set the carrier detection threshold to this value
(specified in decibels, but without unit postfix; i.e., "30").
<li> <tt>rxgain</tt>: Set the receiver gain to this value (specified in
decibels, but without unit postfix).
</ul>
</p>
<h3><a name="DynamicLinkConfig">Dynamically Configuring GNU Radio
Links</a></h3>
<p>
After your experiment is swapped in, you can change the above settings
on the fly, using either the <tt>link_config</tt> script on
<tt>users.emulab.net</tt>, 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
<b>must set both the <tt>frequency</tt> and <tt>rate</tt> parameters</b>!):
<code><pre>
link_config myproj myexp lan0 frequency=916M rate=250k
</code></pre>
Or you can use the <a href=../xmlrpcapi.php3>XMLRPC interface</a> from
your desktop or from <tt>users</tt>:
<code><pre>
sshxmlrpc_client.py link_config proj=myproj exp=myexp
link=lan0 "params={'frequency': '916M', 'rate': '250k'}"
</code></pre>
</p>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment