TOSSIM: A Simulator for TinyOS Networks
Philip Levis and Nelson Lee
[email protected]erkeley.edu
September 17, 2003
Version 1.0
June 26, 2003
1
Contents
1 Introduction 2
2 Compiling and Running a Simulation 4
2.1 dbg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Network Monitoring and Packet Injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3 Radio Models 7
3.1 Using LossyBuilder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2 Bit Errors and Packet Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3 Lossy Model Actuation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4 ADC Models 9
5 EEPROM 9
6 TinyViz 10
6.1 TinyViz Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
7 Using gdb 12
8 Concurrency Model 13
8.1 Sample Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
9 Internals 14
9.1 TOSSIM Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
9.2 TOSSIM Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
9.3 RFM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1 Introduction
TOSSIM is a discrete event simulator for TinyOS sensor networks. Instead of compiling a TinyOS application
for a mote, users can compile it into the TOSSIM framework, which runs on a PC. This allows users to debug,
test, and analyze algorithms in a controlled and repeatable environment. As TOSSIM runs on a PC, users can
examine their TinyOS code using debuggers and other development tools. This document briefly describes
the design philosophy of TOSSIM, its capabilities, its structure. It also provides a brief tutorial on how to
use TOSSIM for testing or analysis.
TOSSIM’s primary goal is to provide a high fidelity simulation of TinyOS applications. For this reason,
it focuses on simulating TinyOS and its execution, rather than simulating the real world. While TOSSIM
can be used to understand the causes of behavior observed in the real world, it does not capture all of them,
and should not be used for absolute evaluations.
TOSSIM is not always the right simulation solution; like any simulation, it makes several assumptions,
focusing on making some behaviors accurate while simplying others. One of the most common questions
about TOSSIM is whether it can “simulate X” or whether it “has an accurate X model.” In hope of answering
most of such questions, here is a brief summmary of its characteristics:
• Fidelity: By default, TOSSIM captures TinyOS’ behavior at a very low level. It simulates the network
at the bit level, simulates each individual ADC capture, and every interrupt in the system.
2
• Time: While TOSSIM precisely times interrupts (allowing things like bit-level radio simulation), it
does not model execution time. From TOSSIM’s perspective, a piece of code runs instantaneously.
Time is kept at a 4MHz granularity (the CPU clock rate of the rene and mica platforms). This also
means that spin locks or task spin locks will never exit: as the code runs instantaneously, the e vent
that would allow the spin to stop will not occur until the code com pletes (never).
• Models: TOSSIM itself does not model the real world. Instead, it provides abstractions of certain
real-world phenomena (such as bit error). With tools outside the simulation itself, users c an then
manipulate these abstractions to implement whatever models they want to use. By making complex
models exterior to the simulation, TOSSIM remains flexible to the needs of many users without trying
to establish what is “correct.” Additionally, it keeps the simulation simple and efficient.
– Radio: TOSSIM does not m odel radio propagation; instead, it provides a radio abstraction of
directed independent bit errors between two nodes. An external program can provide a desired
radio model and map it to these bit errors. Having directed bit error rates means that asymmetric
links can be easily modeled. Independent bit errors mean longer packets have a higher probability
of corruption, and each packet’s loss probability is independent.
– Power/Energy: TOSSIM does not model power draw or energy consumption. However, it
is very simple to add annotations to components that consume power to provide information on
when their power states change (e.g., turned on or off). After a simulation is run, a user can apply
a energy or power model to these transitions, calculating overall e nergy consumption. Because
TOSSIM does not model CPU execution time, it cannot easily provide accurate information for
calculating CPU energy consumption.
• Building: TOSSIM builds directly from TinyOS code. To simulate a protocol or system, you must
write a TinyOS implementation of it. On one hand, this is often more difficult than an abstract
simulation; on the other, it means you can then take your implementation and run it on actual motes.
• Imperfections: Although TOSSIM captures TinyOS behavior at a very low level, it makes several
simplifying assumptions. This means that it is very possible that code which runs in a simulation
might not run on a real mote. For example, in TOSSIM interrupts are non-preemptive (a result of
being a discrete event simulator). On a real mote, an interrupt can fire while other code is running. If
pre-emption can put a mote in an unrecoverable state, then simulated motes will run without mishap
while real-world motes may fail. Also, if interrupt handlers run too long, a real-world mote may c rash;
as code in TOSSIM runs instantaneously, no problems will appear in simulation.
• Networking: Currently, TOSSIM simulates the 40Kbit RFM mica networking stack, including the
MAC, encoding, timing, and synchronous acknowledgements. It does not simulate the mica2 ChipCon
CC1000 stack. We are waiting to have a better understanding of the behavior of CC1000 before writing
a simulation implementation.
• Authority: Initial experience from real-world deployments has shown that TinyOS networks have
very complex and highly variable behavior. While TOSSIM is useful to get a sense of how algorithms
perform in comparison to one another, TOSSIM results shouldn’t be considered authoritative. For
example, TOSSIM can tell you that one algorithm behaves better than another under high loss, but
the question remains as to whether the specified loss scenario has any basis in the real world. TOSSIM
should not be considered an end-point of evaluation; instead, it is a system that allows the user to
separate out environmental noise to better understand algortithms.
3
2 Compiling and Running a Simulation
TOSSIM is automatically built when you compile an application. Applications are compiled by entering an
application directory (e.g. /apps/Blink) and typing make. Alternatively, when in an application directory,
you can type make pc, which will only compile a simulation of the application.
There are several compilation options to ncc when compiling for TOSSIM, including the maximum
number of motes that can be simulated. The default options in the TinyOS 1.1 makefile should fit almost
any need; refer to the nesC manual for further information on the options available.
The TOSSIM executable is named main.exe, and resides in build/pc. It has the following usage:
Usage: ./build/pc/main.exe [options] num_nodes
[options] are:
-h, --help Display this message.
-gui pauses simulation waiting for GUI to connect
-a=<model> specifies ADC model (generic is default)
options: generic random
-b=<sec> motes boot over first <sec> seconds (default: 10)
-ef=<file> use <file> for eeprom; otherwise anonymous file is used
-l=<scale> run sim at <scale> times real time (fp constant)
-r=<model> specifies a radio model (simple is default)
options: simple static lossy
-rf=<file> specifies file input for lossy model (lossy.nss is default)
-s=<num> only boot <num> of nodes
-t=<sec> run simulation for <sec> virtual seconds
num_nodes number of nodes to simulate
The -h or --help options prints out the above usage message, and some additional information.
The -a option specifies the ADC model to use. TOSSIM c urrently supports two models: generic and
random. Section 4 describes these models.
The -b option specifies the interval over which motes boot. Their boot times are uniformly distributed
over this interval. The default value is ten seconds.
The -e option is for named EEPROM files. If -e isn’t specified, the logger component stores and reads
data, but this data is not persistent across simulator invocations: it uses an anonymous file. Section 5
describes how the EEPROM in TOSSIM works.
The -l option is for making TOSSIM run at a rate representative of real time. The scale argument
specifies what relative rate should be used. For example, -l=2.0 means twice as fast as real time (two virtual
seconds run in one real second), while -l=0.1 means one tenth of real time (one virtual seconds runs in ten
real seconds.). TOSSIM can only run so fast; sp e cifying it to run faster than it can will cause it to run as
quickly as possible. Using this option imposes a significant performance overhead; it shouldn’t be used when
trying to run simulations quickly.
The -r option specifies the radio model to use. TOSSIM currently supp orts two models: simple and
lossy. Earlier versions also supported a “static” model, but this has been subsumed by the lossy model.
Section 3 describes these models
The -s option tells TOSSIM to only boot a subset of the number of nodes specified. This is useful if you
want some to boot later, in response to user input. If the -s option is specified, TOSSIM boots mote IDs
0-(num - 1).
The -t option tells TOSSIM to run for a specified number of virtual seconds. After sec seconds have
passed, TOSSIM exits cleanly.
4
The num nodes option specifies how many nodes should be simulated. A compile-time upper bound is
specified in /apps/Makerules. The standard TinyOS distribution sets this value to be 1000. By default, all
num nodes boot in the first ten seconds of simulation, with bootup times uniformly distributed.
TOSSIM catches SIGINT (control-C) to exit cleanly. This is useful when profiling code.
2.1 dbg
TOSSIM provides configuration of debugging output at run-time. Much of the TinyOS source contains
debugging statements. Each debugging statement is accompanied by one or more modal flags. When the
simulator starts, it reads in the DBG environment variable to determine which modes should be enabled.
Modes are stored and processed as entries in a bit-mask, so a single output can be enabled for multiple modes,
and a user can specify multiple modes to be displayed. The set of DBG modes recognized by TOSSIM can
be identified by using the -h option; all available modes are printed. The current modes are:
all: Enable all available messages
boot: Simulation boot and StdControl
clock: The hardware clock
task: Task enqueueing/dequeueing/running
sched: The TinyOS scheduler
sensor: Sensor readings
led: Mote leds
crypto: Cryptographic operations (e.g., TinySec)
route: Routing systems
am: Active messages transmission/reception
crc: CRC checks on active messages
packet: Packet-level transmission/reception
encode: Packet encoding/decoding
radio: Low-level radio operations: bits and bytes
logger: Non-volatile storage
adc: The ADC
i2c: The I2C bus
uart: The UART (serial port)
prog: Network reprogramming
sounder: The sounder on the mica sensor board
time: Timers
sim: TOSSIM internals
queue: TOSSIM event queue
simradio: TOSSIM radio mo dels
hardware: TOSSIM hardware abstractions
simmem: TOSSIM memory allocation/deallocation (for finding leaks)
usr1: User output mode 1
usr2: User output mode 2
usr3: User output mode 3
temp: For temporary use
As an example, the statement
dbg(DBG_CRC, "crc check failed: \%x, \%x\n", cr c, mcrc);
will print out the failed CRC check message if the user has e nabled CRC debug messages, while
dbg(DBG_BOOT, "AM Module initialized\n");
will be printed to standard out if boot messages are enabled. DBG flags c an also be combined, as in this
example:
dbg(DBG_ROUTE|DBG_ERROR, "Received control message: lose our network name!.\n");
5
