Last updated 23 September 2003

To goal of this lesson is to integrate the sensor network with a PC, allowing us to display sensor readings on the PC as well as to communicate from the PC back to the motes. First, we'll introduce the basic tools used to read sensor network data on a desktop over the serial port. Next we'll demonstrate a Java application that displays sensor readings graphically. Finally, we'll close the communication loop by showing how to send data back to the motes.
 

The Oscilloscope application

The mote application we use in this lesson is found in apps/Oscilloscope. It consists of a single module that reads data from the photo sensor. For each 10 sensor readings, the module sends a packet to the serial port containing those readings. The mote only sends the packets over the serial port.  (To see how the data can be sent over the radio see apps/OscilloscopeRF.)

Compile and install the Oscilloscope application on a mote. You will need to connect a sensor board to the mote to get the light readings. Remember to set the SENSORBOARD option in apps/Oscilloscope/Makefile to either micasb or basicsb depending on the type of sensor board you have.

This application requires that the mote with the sensor be connected to the serial port on the programming board. Note that the size of the current Mica sensor board prevents you from plugging the mote and board into the programming board directly. One workaround is to use a short cable to connect the programming board to the sensor board connector.

When the Oscilloscope application is running, the red LED lights when the sensor reading is over some threshold (set to 0x0300) by default in the code - you might want to change this to a higher value if it never seems to go off in the dark). The yellow LED is toggled whenever a packet is sent to the serial port.
 

The 'listen' tool: displaying raw packet data

The first step to establishing communication between the PC and the mote is to connect up your serial port cable to the programming board, and to make sure that you have Java and the javax.comm package installed. After programming your mote with the Oscilloscope code, cd to the tools/java directory, and type

  make

  export MOTECOM=serial@serialport:baudrate

  export MOTECOM=serial@COM1:19200 # mica baud rate
  export MOTECOM=serial@COM1:mica  # mica baud rate, again
  export MOTECOM=serial@COM2:mica2 # the mica2 baud rate, on a different serial port
  export MOTECOM=serial@COM3:57600 # explicit mica2 baud rate

  java net.tinyos.tools.Listen

% java net.tinyos.tools.Listen

serial@COM1:19200: resynchronising
7e 00 0a 7d 1a 01 00 0a 00 01 00 46 03 8e 03 96 03 96 03 96 03 97 03 97 03 97 03 97 03 97 03
7e 00 0a 7d 1a 01 00 14 00 01 00 96 03 97 03 97 03 98 03 97 03 96 03 97 03 96 03 96 03 96 03
7e 00 0a 7d 1a 01 00 1e 00 01 00 98 03 98 03 96 03 97 03 97 03 98 03 96 03 97 03 97 03 97 03

Before continuning, execute unset MOTECOM to avoid forcing all java applications to use the serial port to get packets.

If you don't have the javax.comm package installed properly, then the program will complain that it can't find the serial port. If you do not see that data lines on the screen, you may have chosen the wrong COM port or the mote may not be correctly connected to the computer.
 

Now what are you seeing?

The application that you are running is simply printing out the packets that are coming from the mote. Each data packet that comes out of the mote contains several fields of data. Some of these fields are generic Active Message fields, and are defined in tos/types/AM.h. The data payload of the message, which is defined by the application, is defined in apps/Oscilloscope/OscopeMsg.h. The overall message format for the Oscilloscope application is as follows:

• Destination address (2 bytes)
• Active Message handler ID (1 byte)
• Group ID (1 byte)
• Message length (1 byte)
• Payload (up to 29 bytes):
  • source mote ID (2 bytes)
  • sample counter (2 bytes)
  • ADC channel (2 bytes)
  • ADC data readings (10 readings of 2 bytes each)

Note that the data is sent by the mote in little-endian format; so, for example, the two bytes 96 03 represent a single sensor reading with most-significant-byte 0x03 and least-significant-byte 0x96. That is, 0x0396 or 918 decimal.

Here is an excerpt from OscilloscopeM.nc showing the data being written to the packet:

   async event result_t ADC.dataReady(uint16_t data) {
    struct OscopeMsg *pack;

    atomic {
      pack = (struct OscopeMsg *)msg[currentMsg].data;

      // add the new sensor reading to the packet 
      // and update the number of bytes in this packet 
      pack->data[packetReadingNumber++] = data;

      readingNumber++; // increment total number of bytes

      dbg(DBG_USR1, "data_event\n");

      // if the packet is full, send the packet out 
      if (packetReadingNumber == BUFFER_SIZE) {
        post dataTask();
      }
    }

    if (data > 0x0300)
      call Leds.redOn();
    else
      call Leds.redOff();

    return SUCCESS;
  }

  task void dataTask() {
    struct OscopeMsg *pack;
    atomic {
      pack = (struct OscopeMsg *)msg[currentMsg].data;
      packetReadingNumber = 0;
      pack->lastSampleNumber = readingNumber;
    }

    pack->channel = 1;
    pack->sourceMoteID = TOS_LOCAL_ADDRESS;
   
    /* Try to send the packet. Note that this will return
     * failure immediately if the packet could not be queued for
     * transmission.
     */
    if (call DataMsg.send(TOS_UART_ADDR, sizeof(struct OscopeMsg),
                              &msg[currentMsg]))
      {
        atomic {
          currentMsg ^= 0x1; // flip-flop between two message buffers
        }
        call Leds.yellowToggle();
      }
  }

The Listen program is the most basic way of communicating with the mote; it directly opens the serial port and just dumps packets to the screen. Obviously it is not easy to visualize the sensor data using this program. What we'd really like is a better way of retrieving and observing data coming from the sensor network.

The SerialForwarder program is used to read packet data from a serial port and forward it over an Internet connection, so that other programs can be written to communicate with the sensor network over the Internet. To run the serial forwarder, cd to tools/java and run the program

  java net.tinyos.sf.SerialForwarder -comm serial@COM1:<baud rate>

The -comm argument tells SerialForwarder to communicate over serial port COM1. The-comm argument specifies where the packets SerialForwarder should forward come from, using the same syntax as the MOTECOM environment variable you saw above (you can run 'java net.tinyos.packet.BuildSource' to get a list of valid sources). Unlike most other programs, SerialForwarder does not pay attention to the MOTECOM environment variable; you must use the -comm argument to specify the packet source (The rationale is that you would typically set MOTECOM to specify a serial forwarder, and that serial forwader should talk to, e.g., a serial port. You wouldn't want the SerialForwarder to talk to itself...).

The <baud rate> argument tells SerialForwarder to communicate at specified baud rate.

SerialForwarder does not display the packet data itself, but rather updates the packet counters in the lower-right hand corner of the window. Once running, the serial forwarder listens for network client connections on a given TCP port (9001 is the default), and simply forwards TinyOS messages from the serial port to the network client connection, and vice versa. Note that multiple applications can connect to the serial forwarder at once, and all of them will receive a copy of the messages from the sensor network.

More information is available on SerialForwarder and packet sources is found in the SerialForwarder Documentation
 

Starting the Oscilloscope GUI

It is now time to graphically display the data coming from the motes. Leaving the serial forwarder running, execute the command

  java net.tinyos.oscope.oscilloscope

The x-axis of the graph is the packet counter number and the y-axis is the sensor light reading. If the mote has been running for a while, its packet counter might be quite large, so the readings might not appear on the graph; just power-cycle the mote to reset its packet counter to 0. If you don't see any light readings on the display, be sure that you have not zoomed in on the display.
 

Using MIG to communicate with motes

MIG (Message Interface Generator) is a tool that is used to automatically generate Java classes that correspond to Active Message types that you use in your mote applications. MIG reads in the nesC struct definitions for message types in your mote application and generates a Java class for each message type that takes care of the gritty details of packing and unpacking fields in the message's byte format. Using MIG saves you from the trouble of parsing message formats in your Java application.

MIG is used in conjunction with the net.tinyos.message package, which provides a number of routines for sending and receiving messages through the MIG-generated message classes. NCG(nesC Constant Generator) is a tool to extract constants from nesC files for use with other applications and is typically used in conjunction with MIG.

Let's look at the code from tools/java/net/tinyos/oscope/GraphPanel.java (part of the oscilloscope program) that communicates with the serial forwarder. First, the program connects to the serial forwarder and registers a handler to be invoked when a packet arrives. All of this is done through the net.tinyos.message.MoteIF interface:

        // OK, connect to the serial forwarder and start receiving data
        mote = new MoteIF(PrintStreamMessenger.err, oscilloscope.group_id);
        mote.registerListener(new OscopeMsg(), this);

MoteIF represents a Java interface for sending and receiving messages to and from motes. The host and port number of the serial forwarder are obtained from the environment variable MOTECOM. You initialize MoteIF with  PrintStreamMessenger which indicates where to send status messages (System.err), as well as an (optional) Active Message group ID. This group ID must correspond to the group ID used by your motes.

We register a message listener (this) for the message type OscopeMsg.OscopeMsg is automatically generated by MIG from the nesC definition for struct OscopeMsg, which we saw earlier in OscopeMsg.h. Look at tools/java/net/tinyos/oscope/Makefile for an example of how this class is generated. You will see:

  OscopeMsg.java:
        $(MIG) -java-classname=$(PACKAGE).OscopeMsg $(APP)/OscopeMsg.h OscopeMsg -o $@

GraphPanel implements the MessageListener interface, which defines the interface for receiving messages from the serial forwarder. Each time a message of the appropriate type is received, the messageReceived() method is invoked in GraphPanel. It looks like this:

  public void messageReceived(int dest_addr, Message msg) {
    if (msg instanceof OscopeMsg) {
      oscopeReceived( dest_addr, (OscopeMsg)msg);
    } else {
      throw new RuntimeException("messageReceived: Got bad message type: "+msg);
    }
  }

  public void oscopeReceived(int dest_addr, OscopeMsg omsg) {
    boolean foundPlot = false;
    int moteID, packetNum, channelID, channel = -1, i;

    moteID = omsg.get_sourceMoteID();
    channelID = omsg.get_channel();
    packetNum = omsg.get_lastSampleNumber();
    
    /* ... */

messageReceived() is called with two arguments: the destination address of the packet, and the message itself (net.tinyos.message.Message).Message is just the base class for the application-defined message types; in this case we want to cast it to OscopeMsg which represents the actual message format we are using here.

Once we have the OscopeMsg we can extract fields from it using the handy get_sourceMoteID(), get_lastSampleNumber(), and get_channel() methods. If we look at struct OscopeMsg in OscopeMsg.h we'll see that each of these methods corresponds to a field in the message type:

struct OscopeMsg
{
    uint16_t sourceMoteID;
    uint16_t lastSampleNumber;
    uint16_t channel;
    uint16_t data[BUFFER_SIZE];
};

Each field in a MIG-generated class has at least eight methods associated with it:

• isSigned_fieldname - Indicates whether or not this field is a signed quantity.
• isArray_fieldname - Indicates whether or not this field is an array.
• get_fieldname - Return the value of this field.
• set_fieldname - Set the value of this field.
• offset_fieldname - Return the offset (in bytes) for this field.
• offsetBits_fieldname - Return the offset (in bits) for this field.
• size_fieldname - Return the length (in bytes) of this field.
• sizeBits_fieldname - Return the length (in bits) of this field.

The remainder of messageReceived() pulls the sensor readings out of the message and places them on the graph.

Sending a message through MIG

It is also possible to send a message to the motes using MIG. The Oscilloscope application sends messages of type AM_OSCOPERESETMSG, which causes the mote to reset its packet counter. Looking at clear_data() in GraphPanel.java, we see how messages are sent to the motes:

          try {
            mote.send(MoteIF.TOS_BCAST_ADDR, new OscopeResetMsg());
          } catch (IOException ioe) {
            System.err.println("Warning: Got IOException sending reset message: "+ioe);
            ioe.printStackTrace();
          }

All we need to do is invoke MoteIF.send() with the destination address and the message that we wish to send. Here, MoteIF.TOS_BCAST_ADDR is used to represent the broadcast destination address, which is identical to TOS_BCAST_ADDR used in the nesC code.
 

Exercises

Transmit the light sensor readings over the radio to another mote that sends them over the serial port!

The apps/Oscilloscope mote application is written to use the serial port and the light sensor. Instead, look at apps/OscillosopeRF, which transmits the sensor readings over the radio. In order to use this application, you need to use one mote as a gateway that receives data packets over the radio and transmits them over the serial port. apps/TOSBase is an application that does this; it simply forwards packets between the radio and the UART (in both directions).

Extra Credit: Can you figure out how to display sensor readings on the oscilloscope GUI from two motes simultaneously? (Note that the oscillosope GUI is already capable of displaying sensor readings from multiple motes. You have to ensure that those readings are correctly transmitted and received over the network.) This setup would look like the following diagram.

Last updated 25 August  2003

TOSSIM, the TinyOS simulator, compiles directly from TinyOS code. Built with make pc, the simulation runs natively on a desktop or laptop. TOSSIM can simulate thousands of nodes simultaneously. Every mote in a simulation runs the same TinyOS program.

TOSSIM provides run-time configurable debugging output, allowing a user to examine the execution of an application from different perspectives without needing to recompile. TinyViz is a Java-based GUI that allows you to visualize and control the simulation as it runs, inspecting debug messages, radio and UART packets, and so forth. The simulation provides several mechanisms for interacting with the network; packet traffic can be monitored, packets can be statically or dynamically injected into the network. In this lesson, we won't be dealing with packet injection, which is discussed in Lesson 7 .
 

Building and Running an Application

TOSSIM is compiled by typing make pc in an application directory. In addition to the expected TinyOS components, a few simulator-specific files are compiled; these files provide functionality such as support for network monitoring over TCP sockets.

Enter the apps/CntToLedsAndRfm directory. This application runs a 4Hz counter. It assumes a Mica mote which has 3 LEDs. On each counter tick, the application displays the least significant three bits of the counter on the three mote LEDs and sends the entire 16-bit value in a packet. Build and install the application on a Mica mote as in Lesson 4. You should see the LEDs blink.

Build a TOSSIM version of the application with make pc. The TOSSIM executable is build/pc/main.exe. Type build/pc/main.exe --help to see a brief summary of its command-line usage. TOSSIM has a single required parameter, the number of nodes to simulate. Type build/pc/main.exe 1 to run a simulation of a single node. You should see a long stream of output fly by, most of which refer to radio bit events. Hit control-C to stop the simulation.

By default, TOSSIM prints out all debugging information. As radio bit events are fired at 20 or 40 KHz, these are the most frequent events in the simulator, they comprise most of the output in CntToLedsAndRfm. Given the application, we're more concerned with the packet output and mote LEDs than individual radio bits. TOSSIM output can be configured by setting the DBG environment variable in a shell. Type export DBG=am,led in your shell; this makes only LED and AM (active messages) packet output enabled. Run the one-mote simulation again. You should see output similar to this:
 

0: LEDS: Yellow off.
0: LEDS: Green off.
0: LEDS: Red off.
0: Sending message: ffff, 4
    ff ff 04 7d 08 20 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 3b f3 00 00 01 00 00 00
0: LEDS: Yellow off.
0: LEDS: Green off.
0: LEDS: Red on.
0: Sending message: ffff, 4
    ff ff 04 7d 08 21 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 ac e6 00 00 01 00 00 00
              

The sixth byte of the packet contains the least significant byte of the two byte counter; in this example the first packet is hex 0x20 (32), in the second, it's hex 0x21 (33). As the LEDs show the bottom three bits of the counter, they are all off for the first packet and bit one is on for the second.

Almost every message is preceded by a 0:; this means that the message pertains to the execution of mote 0. Run a simulation of two motes (build/pc/main.exe 2); after it runs for a few seconds, stop the simulation with control-C. You should see messages for both mote 0 and mote 1.

Set DBG to crc. Run two mote simulation of CntToLedsAndRfm. You should see output indicating that both nodes are successfully receiving packets from each-other.

The full set of DBG modes can be seen by typing build/pc/main.exe --help; they are listed at the bottom of the output.
 

Adding Debugging Statements

Four DBG modes are reserved for application components and debugging use: usr1, usr2, usr3, and temp. In TinyOS code, debug message commands have this syntax:
 

dbg(<mode>, const char* format, ...);

The mode parameter specifies which under which DBG modes this message will be printed. The full set of modes can be found in tos/types/dbg_modes.h. The format and following parameters specify the string to output and have printf() semantics. For example, open tos/lib/Counters/Counter.ncin your editor. In Timer.fired(), add this line just before the return statement:
 

dbg(DBG_TEMP, "Counter: Value is %i\n", (int)state);

Set DBG to be temp and run a single mote simulation. You'll see the counter increment. In general, the DBG mode name in TinyOS code is the name used when you run the simulator, with DBG_prepended. For example, am is DBG_AM, packet is DBG_PACKET and boot is DBG_BOOT.

Just as you can enable multiple modes when running the simulator, a single debug message can be activated on multiple modes. Each mode is a bit in a large bitmask; one can use all of the standard logical operators (e.g. |, ~) . For example, change the debug message you just added to:
 

dbg(DBG_TEMP|DBG_USR1, "Counter: Value is %i\n", (int)state);

It will now be printed if either temp or usr1 is enabled. Run the application to see this is the case.
 

Using gdb with TOSSIM

One significant advantage of TOSSIM is that, because it runs natively on a PC, you can use traditional debugging tools such as gdb. However, because TOSSIM is a discrete event simulation for large numbers of motes, traditional step-through debugging techniques only work on an event basis, and not cross-events.

Unfortunately, gdb is generally designed for C and not nesC; the component model of nesC means that a single command can have multiple providers; referring to a specific command requires specifying the component, interface, and command. For example, to break on entry to the redOff command of the Leds interface of LedsC, one must type:
 

 gdb build/pc/main.exe  // start gdb

(gdb) break *LedsC$Leds$redOff
Breakpoint 1 at 0x804c644: file tos/system/LedsC.td, line 97.

run 1                   // run CntToLedsAndRfm with one mote

The leading * is necessary so gdb can parse the function name correctly; otherwise, it looks for the function LedsC.

Variables are similarly named. For example, to print the ledsOn variable of LedsC (which keeps track of on/off for the toggle commands), one types:
 

(gdb) print LedsC$ledsOn
$3 = '\0' <repeats 999 times>

Actually, this isn't quite correct, as the output above shows; in TOSSIM, ledsOn isn't a single uint8_t, but an array of 1000 of them. This is how TOSSIM handles the state of many motes; it compiles fields to be arrays of n elements, where n is the maximum simulation size. Whenever a mote accesses a component's state, it indexes into the array based on its node ID. Therefore, to refer to a specific mote's state, one needs to index into the array properly:
 

(gdb) print LedsC$ledsOn[tos_state.current_node]
$2 = 0 '\0'

We've supplied a simple gdb macro named VAR that handles this for you. Copy tos/platform/pc/.gdbinit to your home directory (if there's already a .gdbinit there, just append this file).  Type quit and start gdb it again. Break in LedsC$Leds$redOff as before. Now, instead of the above command line, you can type:
 

(gdb) VAR LedsC$ledsOn
$3 = 0 '\0'

TinyViz provides an extensible graphical user interface for debugging, visualizing, and interacting with TOSSIM simulations of TinyOS applications. Using TinyViz, you can easily trace the execution of TinyOS apps, set breakpoints when interesting events occur, visualize radio messages, and manipulate the virtual position and radio connectivity of motes. In addition, TinyViz supports a simple "plugin" API that allows you to write your own TinyViz modules to visualize data in an application-specific way, or interact with the running simulation.
 

Getting Started

To get started, look at the apps/TestTinyViz application, which causes motes to periodically send a message to a random neighbor. There isn't anything interesting about the application itself, but it will allow us to demonstrate the basic features of TinyViz. Go ahead and build the app with make pc.

To compile TinyViz, cd to the tools/java/net/tinyos/sim directory and type make. This will build the TinyOS program as tinyviz.jar, a stand-alone Java JAR file that you can run with the tinyviz script, found in this directory. Place this script on your PATH and you will be able to run tinyviz directly from the command line.

Start up TinyViz, running the TestTinyViz app, as follows:

export DBG=usr1
tinyviz -run build/pc/main.exe 30

You will see a window looking something like the following:

On the left is the graphical display of the sensor network. On the right is the control panel where you can interact with a series of plugins that control how TinyViz works.

In the mote window, you can select motes by clicking on them, or select a group of motes by dragging a rectangle around the group. You can move motes around by dragging them around. Selecting motes is meaningful for certain plugins, and other operations, such as toggling the power state of the motes.

The "pause/play" button pauses or resumes the simulation. The "grid button" toggles grid-lines on the display. The "clear" button clears out the display state. The "stop" button kills the simulation. The "delay" slider introduces a delay between the handling of each TOSSIM event, which will slow down the display -- useful in cases where you have a small number of motes and want to watch the simulation operating in "real time". The "On/off" button toggles the power state of the selected motes.

Plugins

A TinyViz plugin is a software module that watches for events coming from the simulation -- such as debug messages, radio messages, and so forth -- and reacts by drawing information on the display, setting simulation parameters, or actuating the simulation itself, for example, by setting the sensor values that simulated motes will read. TinyViz comes with a suite of built-in plugins, in the tools/java/net/tinyos/sim/plugins directory, and you can write your own. Not all plugins are used for all applications -- for example, the Calamari plugin is used mainly for testing the Calamari localization service -- but many of them are generally useful.

Plugins can be selectively enabled or disabled, depending on what information you are interested in seeing during the simulation. You select plugins from the Plugins menu. When a plugin is enabled, its corresponding tab in the right-hand control panel window is active, which may have additional information and controls provided by that plugin. Plugins are designed to be independent of each other so you can enable or disable any group of plugins you like.

The main plugins you are likely to use are:

• Debug messages: Shows a window with all of the debug messages generated by the simulation. You can select debug messages just from the selected group of motes, and also highlight messages that match a certain pattern. Note that the set of debug messages you see are controlled by the value of the DBG environment variable, just as they are when running TOSSIM in a stand-alone setting. So, if you only want to see debug messages of type DBG_USR1 and DBG_AM, start up TinyViz with:

  DBG=usr1,am tinyviz -run build/pc/main.exe 30

• Set breakpoint: Allows you to set a breakpoint, which will pause the simulation when some condition is met. Right now, the possible conditions are (a) a substring match on a debug message, or (b) a match on the contents of a sent radio message. Multiple breakpoints can be set and they can be enabled or disabled by selecting them in the breakpoints list.
• ADC readings: Shows the most recent value of each ADC channel next to each mote.
• Sent radio packets: Shows a window with all sent radio packets, much like the Debug messages plugin. Note that the Debug messages plugin also shows this information.
• Radio links: Graphically displays radio message activity. When a mote broadcasts a message, a blue circle will be drawn around it. When a mote sends a message to another mote, a directed arrow will be drawn between the two motes. Note that this shows all message transmissions, regardless of whether they are successful; if a mote attempts to send a message but it is corrupted or lost, the arrow will still be drawn.
• Set location: Makes the virtual location of each mote available to that mote through the Location interface, found in apps/TestTinyViz/Location.nc. This is accomplished by setting the value of three "fake" ADC channels (one each for X, Y, and Z coordinates) on each mote, which the FakeLocation component reads to determine the mote's virtual location. This is meant to act as a stand-in for a real localization service when simulating TinyOS apps.
• Radio model: Sets the bit error rate between motes according to their location and various models of radio connectivity. Enabling this plugin allows you to use realistic connectivity models in your simulations. There are two built-in models: "Empirical" (based on an outdoor trace of packet connectivity with the RFM1000 radios) and "Fixed radius" (all motes within a given fixed distance of each other have perfect connectivity, and no connectivity to other motes). Setting the "scaling factor" in the control panel simply scales the distance parameter of the model. Increasing the scaling factor will decrease the connectivity range of the chosen model. By selecting a mote in the display you can see its connectivity to other motes -- the number shown next to each edge is the probability of a packet getting through. Changing the scaling factor and clicking "update model" will update the model parameters, as will moving motes around in the display.

Layout of the motes is controlled by the Layout menu, which gives you several options including random, grid-based, or a "grid+random" (grid-based but with a random perturbation) layout. You can also save and load layouts from a file. The location of the motes on the display is used in two ways. First, it is used to determine radio connectivity, when the RadioModelPlugin is enabled. Second, it is used to set the virtual location of the motes, when using the LocationPlugin.

Trying it out

OK, now we're ready to try out the various features.

1. Startup TinyViz with DBG=usr1, tinyviz -run build/pc/main.exe 30 if it is not already running.
2. Select the Debug messages, Radio links, and Set breakpoint plugins from the Plugins menu, and resume the simulation by clicking the pause/play button.
3. Clicking on the Debug messages tab in the control panel will show you all of the debug messages generated by the simulation. Click on a given mote (say, mote 3) then click "Selected motes only" to restrict the display to just that mote.
4. Type a phrase (for example, "Received") in the box at the bottom of the control panel, then click "Highlight". This will highlight all messages matching the chosen string - very useful for visually scanning for "interesting" messages.
5. Pause the simulation, then click on the "Set breakpoint" tab. Pull down the bar at the top of the control panel (which says "Current breakpoints") and choose "Add debug message breakpoint". In the "Message contains" box, type "Received message", then click "Enable breakpoint". This will add a new breakpoint that pauses the simulation whenever a matching debug message is printed. Click on the pause/play button to resume the simulation. Very soon afterwards, the simulation will pause and the control panel at the bottom of the screen will print something like

   Breakpoint 0 fired: Debug message: [24] DebugMsgEvent [24: TestTinyVizM: Received message from 13]

   which simply means that this debug message triggered the breakpoint. Clicking the play button again will resume the simulation, causing the breakpoint to be hit again.
6. Select "Current breakpoints" from the bar at the top of the control panel. Disable the breakpoint by clicking on it in the breakpoints list, then click "Disable breakpoint".
7. Select the Radio model plugin from the Plugins menu and click on the "Radio model" tab in the control panel, then pick "Fixed radius (100.0)" from the list of radio models. Drag the mouse across the mote display to select all motes; you will see a very densely-connected mesh, indicating that nearly every mote has connectivity with all others, due to the large radius of the radio model. Type "4" in the "Distance scaling factor" box, then click "Update model". The radio model will be updated -- which may take some time -- and the resulting connectivity mesh will be much more sparse.
    

    

   Note that once you restart the simulation, nodes that can no longer communicate (due to no connectivity) will still be sending messages to each other; this is because the TestTinyViz application accumulates a list of nodes to send messages to, but changing the underlying connectivity model does not modify this list. However, if you watch the debug messages from each node, you will notice that nodes are only receiving messages from those nodes they are connected to, as you would expect.

The TinyViz AutoRun feature allows you to "script" the configuration and execution of a TinyOS simulation, by setting parameters in a file that controls TinyViz. This allows you to automatically enable plugins, set breakpoints, run multiple simulations, log data to files, and execute commands both before and after each simulation runs. This is useful when you are using TinyViz as an analysis tool.

Look at the file apps/TestTinyViz/sample.autorun in the TestTinyViz directory. The autorun file specifies one or more simulations to run; a simulation stops either when a specified number of simulated seconds have elapsed (the "numsec" option), when a substring match on a debug message occurs (the "stopstring" option), or when the simulation exits itself (e.g., a crash or deliberate call to exit()). The parameters for each simulation are separated by a blank line. When a parameter is set in the file for one simulation, it will carry forward for subsequent simulations in the file, saving you from having to re-specify parameters for each run.

Here is the sample file:

# This is a sample TinyViz autorun file. To use it, run
#   tinyviz -autorun sample.autorun
# Set the layout
layout gridrandom
# Enable some plugins
plugin DebugMsgPlugin
plugin RadioLinkPlugin
plugin RadioModelPlugin
# Total number of simulated seconds to run
numsec 20
# Name of the executable file
executable build/pc/main.exe
# DBG messages to include
dbg usr1
# The radio model and scaling factor to use
radiomodel disc100
radioscaling 5
# Number of motes
nummotes 10
# Command to run before starting
precmd echo "This is a command that will run before the simulation"
# File to log all DBG messages to
logfile logfile-20.txt

# The blank line above indicates that we are starting another simulation
# This time run with a different number of motes
nummotes 30
logfile logfile-30.txt

The AutoRun file specifies two simulations, one with 20 motes and another with 30. All debug messages are logged to two different logfiles. We enable a few different plugins (specified by the Java class names as they are found in tools/java/net/tinyos/sim/plugins.

To run the simulations with this autorun file, just type:

tinyviz -autorun sample.autorun

TinyViz starts up, enables and configures the appropriate plugins, and automatically runs each simulation for 10 simulated seconds, then exits. You can set up AutoRun to run a series of simulations and then go to lunch -- the data will be waiting for you in your logfiles when you get back.

AutoRun supports a number of features not shown here -- just look at the arConfig class in the tools/java/net/tinyos/sim/AutoRun.javasource file. Note that all options specified in the file that aren't used by AutoRun itself, however they made available to plugins. So, for example, the radiomodel option is interpreted by the RadioModelPlugin to configure the radio model. You can write your own plugins that are configured through AutoRun in this way.

Writing TinyViz plugins

By far the most useful feature of TinyViz is the ability to write your own plugins to interact with the simulation. Writing plugins is beyond the scope of this document, but we wanted to give you a couple of pointers on where to start. Look at tools/java/net/tinyos/sim/plugins/RadioLinkPlugin.javafor a simple, well-documented plugin implementation. Essentially, plugins must provide a method that receives events from the TOSSIM simulation and the TinyViz framework. Plugins react to events by changing internal state, updating the display, or possibly sending commands back into the simulation. TinyViz delivers events to plugins for initialization, debug messages, radio messages, a change in the location of a mote (e.g., when the user moves it), and when new motes join the simulation. Plugins provide additional methods that are called when the plugin is enabled or disabled, as well as when the mote window is redrawn.

Using RadioLinkPlugin.java as an example, it is straightforward to write your own plugins. Currently, all plugins must be located in the plugins subdirectory of the TinyViz directory. (In the future we will add support for a "plugin path"). Note that when you modify a plugin you need to recompile the tinyviz.jar file by typing make in the main TinyViz directory (tools/java/net/tinyos/sim); just typing make in the plugins directory is not adequate.
 

Further Use

This tutorial only covers some of the functionality and usefulness of TOSSIM; for example, as TOSSIM simulates the TinyOS networking stack at bit granularity, radio models can simulate some of the difficult issues that arise. Similarly, one can test and debug low-level protocols (such as start symbol detection) in addition to application components and routing protocols. The TOSSIM System Description goes into greater details on these capabilities and presents some information on TOSSIM's implementation.
 

Last updated 31 July 2003

This lesson introduces two concepts: hierarchical decomposition of component graphs, and using radio communication. The applications that we will consider are CntToLedsAndRfm and RfmToLeds. CntToLedsAndRfm is a variant of Blink that outputs the current counter value to multiple output interfaces: both the LEDs, and the radio communication stack. RfmToLeds receives data from the radio and displays it on the LEDs. Programming one mote with CntToLedsAndRfm will cause it to transmit its counter value over the radio; programming another with RfmToLeds causes it to display the received counter on its LEDs - your first distributed application!

If you're using mica2 or mica2dot motes, you will need to ensure that you've selected a radio frequency compatible with your motes (433MHz vs 916MHz motes). If your motes are unlabeled, see "How to determine the operating frequency range of a MICA2 or MICA2DOT mote" for information on recognizing which kind of mote you have. To tell the compiler which frequency you are using, edit the Makelocal file in the apps directory, defining either CC1K_DEF_PRESET (see tinyos-1.x/tos/platform/mica2/CC1000Const.h for preset values), or CC1K_DEF_FREQ with an explicit frequency (see example in Makelocal).

The CntToRfmAndLeds Application

Look at CntToRfmAndLeds.nc. Note that this application only consists of a configuration; all of the component modules are located in libraries!

configuration CntToLedsAndRfm {
}
implementation {
  components Main, Counter, IntToLeds, IntToRfm, TimerC;

  Main.StdControl -> Counter.StdControl;
  Main.StdControl -> IntToLeds.StdControl;
  Main.StdControl -> IntToRfm.StdControl;
  Main.StdControl -> TimerC.StdControl;
  Counter.Timer -> TimerC.Timer[unique("Timer")];
  IntToLeds <- Counter.IntOutput;
  Counter.IntOutput -> IntToRfm;
}

The first thing to note is that a single interface requirement (such as Main.StdControl or Counter.IntOutput) can be fanned out to multiple implementations. Here we wire Main.StdControl to the Counter, IntToLeds, IntToRfm, and TimerCcomponents. (All of these components can be found in the tos/lib/Counters directory.) The names of the various components tell you what they do: Counter receives Timer.fired() events to maintain a counter. IntToLeds and IntToRfm provide the IntOutput interface, that has one command, output(), which is called with a 16-bit value, and one event, outputComplete(), which is called with result_t . IntToLeds displays the lower three bits of its value on the LEDs, and IntToRfm broadcasts the 16-bit value over the radio.

So we're wiring the Counter.Timer interface to TimerC.Timer, and Counter.IntOutput to both IntToLeds and IntToRfm. The NesC compiler generates code so that all invocations of the Counter.IntOutput.output() command will invoke the command in both IntToLeds and IntToRfm. Also note that the wiring arrow can go in either direction: the arrow always points from a used interface to a provided implementation.

Assuming you are using a Mica mote, try building and installing this application with make mica install; you should see a 3-bit binary counter on the mote's LEDs. Of course the mote is also transmitting the value over the radio, which we describe next.
 

IntToRfm: Sending a message

IntToRfm is a simple component that receives an output value (through the IntOutput interface) and broadcasts it over the radio. Radio communication in TinyOS follows the Active Message (AM) model, in which each packet on the network specifies a handler ID that will be invoked on recipient nodes. Think of the handler ID as an integer or "port number" that is carried in the header of the message. When a message is received, the receive event associated with that handler ID is signaled. Different motes can associate different receive events with the same handler ID.

In any messaging layer, there are 5 aspects involved in successful communication:

1. Specifying the message data to send;
2. Specifying which node is to receive the message;
3. Determining when the memory associated with the outgoing message can be reused;
4. Buffering the incoming message; and,
5. Processing the message on reception

Let's look at IntToRfm.nc:

configuration IntToRfm
{
  provides interface IntOutput;
  provides interface StdControl;
}
implementation
{
  components IntToRfmM, GenericComm as Comm;

  IntOutput = IntToRfmM;
  StdControl = IntToRfmM;

  IntToRfmM.Send -> Comm.SendMsg[AM_INTMSG];
  IntToRfmM.StdControl -> Comm;
}

This component provides the IntOutput and StdControl interfaces. This is the first time that we have seen a configuration provide an interface. In the previous lessons we have always used configurations just to wire other components together; in this case, the IntToRfm configuration is itself a component that another configuration can wire to. Got it?

In the implementation section, we see:

  components IntToRfmM, GenericComm as Comm;

We also see some new syntax here in the lines:

  IntOutput = IntToRfmM;
  StdControl = IntToRfmM;

The last two lines of the configuration are:

  IntToRfmM.Send -> Comm.SendMsg[AM_INTMSG];
  IntToRfmM.StdControl -> Comm;

The GenericComm component declares:

  provides {

    ...
    interface SendMsg[uint8_t id];

    ...
  }

  command result_t SendMsg.send[uint8_t id]( ... ) { ... };

Now we know how IntToRfm is wired up, but we don't know how message communication is implemented. Take a look at the IntOutput.output() command in IntToRfmM.nc:

  bool pending;
  struct TOS_Msg data;

  /* ... */ 

  command result_t IntOutput.output(uint16_t value) {
    IntMsg *message = (IntMsg *)data.data;

    if (!pending) {
      pending = TRUE;

      message->val = value;
      atomic {
      message->src = TOS_LOCAL_ADDRESS;
      }

      if (call Send.send(TOS_BCAST_ADDR, sizeof(IntMsg), &data))
        return SUCCESS;

      pending = FALSE;
    }  
    return FAIL;
  }

The command is using a message structure called IntMsg, declared in tos/lib/Counters/IntMsg.h. It is a simple struct with val and src fields; the first being the data value and the second being the message's source address. We assign these two fields (using the global constant TOS_LOCAL_ADDRESS for the local source address) and call Send.send() with the destination address (TOS_BCAST_ADDR is the radio broadcast address), the message size, and the message data.

The "raw" message data structure used by SendMsg.send() is struct TOS_Msg, declared in tos/system/AM.h. It contains fields for the destination address, message type (the AM handler ID), length, payload, etc. The maximum payload size is TOSH_DATA_LENGTH and is set to 29 by default; you are welcome to experiment with larger data packets but some nontrivial hacking of the code may be required :-) Here we are encapsulating an IntMsg within the data payload field of the TOS_Msg structure.

The SendMsg.send() command is split-phase; it signals the SendMsg.sendDone() event when the message transmission has completed. If send() succeeds, the message is queued for transmission, and if it fails, the messaging component was unable to accept the message.

TinyOS Active Message buffers follow a strict alternating ownership protocol to avoid expensive memory management, while still allowing concurrent operation. If the message layer accepts the send() command, it owns the send buffer and the requesting component should not modify the buffer until the send is complete (as indicated by the sendDone() event).

IntToRfmM uses a pending flag to keep track of the status of the buffer. If the previous message is still being sent, we cannot modify the buffer, so we drop the output() operation and return FAIL. If the send buffer is available, we can fill in the buffer and send a message.
 

The GenericComm Network Stack

Recall that IntToRfm's SendMsg interface is wired to GenericComm, a "generic" TinyOS network stack implementation (found in tos/system/GenericComm.nc). If you look at the GenricComm.nc, you'll see that it makes use of a number of low-level interfaces to implement communication: AMStandard to implement Active Message sending and reception, UARTNoCRCPacket to communicate over the mote's serial port, RadioCRCPacket to communicate over the radio, and so forth. You don't need to understand all of the details of these modules but you should be able to follow the GenericComm.nc wiring configuration by now.

If you're really curious, check out AMStandard.nc for some details on how the ActiveMessage layer is built. For example, it implements SendMsg.send() by posting a task to take the message buffer and send it over the serial port (if the destination address is TOS_UART_ADDR or the radio radio (if the destination is anything else). You can dig down through the various layers of code until you see the mechanism that actually transmits a byte over the radio or UART.

Receiving Messages with RfmToLeds

The RfmToLeds application is defined by a simple configuration that uses the RfmToInt component to receive a message, and the IntToLeds component to display the received value on the LEDs. Like IntToRfm, the RfmToInt component uses GenericComm to receive messages. Most of RfmToInt.nc should be familiar to you by now, but look at the line:

  RfmToIntM.ReceiveIntMsg -> GenericComm.ReceiveMsg[AM_INTMSG];

Memory management for incoming messages is inherently dynamic. A message arrives and fills a buffer, and the Active Message layer decodes the handler type and dispatches it. The buffer is handed to the application component (through the ReceiveMsg.receive() event), but, critically, the application component must return a pointer to a buffer upon completion.

For example, looking at RfmToIntM.nc,

  /* ... */
  event TOS_MsgPtr ReceiveIntMsg.receive(TOS_MsgPtr m) {
    IntMsg *message = (IntMsg *)m->data;
    call IntOutput.output(message->val);

    return m;
  }

Note that the last line returns the original message buffer, since the application is done with it. If your component needs to save the message contents for later use, it needs to copy the message to a new buffer, or return a new (free) message buffer for use by the network stack.

Underlying Details

TinyOS messages contain a "group ID" in the header, which allows multiple distinct groups of motes to share the same radio channel. If you have multiple groups of motes in your lab, you should set the group ID to a unique 8-bit value to avoid receiving messages for other groups. The default group ID is 0x7D. You can set the group ID by defining the preprocessor symbol DEFAULT_LOCAL_GROUP.

  DEFAULT_LOCAL_GROUP = 0x42    # for example...

Use the Makelocal file to set the group ID for all your applications.

In addition, the message header carries a 16-bit destination node address. Each communicating node within a group is given a unique address assigned at compile time.  Two common reserved destination addresses we've introduced thus far are TOS_BCAST_ADDR (0xfff) to broadcast to all nodes or TOS_UART_ADDR (0x007e) to send to the serial port.

The node address may be any value EXCEPT the two reserved values described above.  To specify the local address of your mote, use the following install syntax:

  make mica install.<addr>

  make mica install.38

1. Question: What would happen if you built multiple CntToLedsAndRfm nodes and turned them on?
2. Program one mote with CntToLedsAndRfm and another with RfmToLeds. When you turn on CntToLedsAndRfm, you should see the count displayed on the RfmToLeds device. Congratulations - you are doing wireless networking. Can you change this to implement a wireless sensor? (Hint: Check out apps/SenseToRfm.)

Last updated 9 September  2003

This lesson demonstrates a simple sensor application that takes light intensity readings (from the sensor board's photo sensor) and displays those readings on the LEDs. This is based on the Sense application, found in apps/Sense. This is a very simple application that reads a value from the light sensor and displays the lower 3 bits of the value on the LEDs. The application configuration is found in Sense.nc and the implementation module in SenseM.nc.

The SenseM.nc component

Let's first look at the top portion of SenseM.nc:

module SenseM {
  provides {
    interface StdControl;
  }
  uses {
    interface Timer;
    interface ADC;
    interface StdControl as ADCControl;
    interface Leds;
  }
}
// Implementation not shown ...

Like BlinkM, this component provides the StdControl interface and uses Timer and Leds. It also uses two more interfaces: ADC, which is used to access data from the analogue-to-digital converter, and StdControl, which is used to initialize the ADC component.

This application uses a new component, TimerC, in place of SingleTimer. The reason is that TimerC allows multiple instance of timers, while SingleTimer only provides a single one that only one component can use. We'll discuss more on Timer a bit later.

Note the line

  interface StdControl as ADCControl;

  interface StdControl as ADCControl;
  interface StdControl as SounderControl;

One related note: if you don't provide an interface instance name then the instance is named the same as the interface. That is, the line

  interface ADC;

  interface ADC as ADC;

Open the file apps/Sense/SenseM.nc.  You'll see the code simply calls ADC.getData() each time Timer.fired() is signaled. Likewise, when ADC.dataReady() is signaled, the internal function display() is invoked, which sets the LEDs to the low-order bits of the ADC value.

Notice the use of the function rcombine() in the implementation of StdControl.init().

  return rcombine(call ADCControl.init(), call Leds.init());

At this point you should be wondering, "how does the Sense application know that the ADC channel should access the light sensor?" This is exactly what the Sense.nc configuration wires up for us.

configuration Sense {
  // this module does not provide any interface
}
implementation
{
  components Main, SenseM, LedsC, TimerC, Photo;

  Main.StdControl -> SenseM;
  Main.StdControl -> TimerC;

  SenseM.ADC -> Photo;
  SenseM.ADCControl -> Photo;
  SenseM.Leds -> LedsC;
  SenseM.Timer -> TimerC.Timer[unique("Timer")];
}

Most of this should be familiar from Blink. We're wiring up the Main.StdControl to SenseM.StdControl, as before. The Leds wirings is also similar to Blink, and we'll discuss Timer in a minute. The wiring for the ADC is:

  SenseM.ADC -> Photo;
  SenseM.ADCControl -> Photo;

Remember that

  SenseM.ADC -> Photo;

  SenseM.ADC -> Photo.ADC;

  SenseM.ADControl -> Photo;

  SenseM.ADC -> Photo.ADCControl;

  SenseM.ADControl -> Photo;

  SenseM.ADControl -> Photo.StdControl;

Let's look at the line

  SenseM.Timer -> TimerC.Timer[unique("Timer")];

A parameterized interface allows a component to provide multiple instances of an interface that are parameterized by a runtime or compile-time value. Recall that it's possible for a component to provide multiple instances of an interface and to give them different names, e.g.,

  provides {
    interface StdControl as fooControl;
    interface StdControl as barControl;
  }

  provides interface Timer[uint8_t id];

In this case, we want TinyOS applications to create and use multiple timers, each of which can be managed independently. For example, an application component might need one timer to fire at a certain rate (say, once per second) to gather sensor readings, while another component might need the a timer to fire at a different rate to manage radio transmission. By wiring the Timer interface in each of these components to a separate instance of the Timer interface provided by TimerC, each component can effectively get its own "private" timer.

When we say TimerC.Timer[someval], we are specifying that BlinkM.Timer should be wired to the instance of the Timer interface specified by the value (someval) in the square brackets. This can be any 8-bit positive number. If we were to specify a particular value here, such as 38 or 42, we might accidentally conflict with the timer being used by another component (if that component used the same value in the brackets). So, we use the compile-time constant function unique(), which generates a unique 8-bit identifier from the string given as an argument. Here,

  unique("Timer")

  uniqueCount("Timer")

will count the number of uses of unique("Timer").
 

Running the Sense application

As before, just do a make mica install in the Sense directory to compile and install the application on your mote. You'll need a sensor board attached to the mote with a photo sensor. The Mica sensor board, for example, snaps into place via the 51 pin connector. The type of sensorboard is selected by the -board command line option to ncc. On the Mica mote, the default sensor board type is micasb. However, if you have an older ("basic") sensor board, you might need to pass in the -board basicsb option to ncc. To do this, edit the Makefile in the Sense directory and add the line SENSORBOARD=basicsb before the line that includes Makerules. The sensor boards supported by TinyOS are represented by the directory names in tos/sensorboards .

The operation of the photo sensor is a bit unusual. The ADC yields a 10-bit digitized sample of the photo sensor. What we would like is for the LEDs to be off when the node is in the light, and on when the node is in the dark. Here, we are looking at the upper three bits of this data coming from the ADC, and inverting the value. Note the line:

  display(7 - ((data >> 7) & 0x7));

Note that when running the application you may really have to cover up the photo sensor pretty well to get it to respond - we'll admit that this is not the best application to really see the photo sensor at work!
 

Exercises

Extend the capability of the application by chirping the sensor board's sounder when it is dark! The TinyOS component for the Sounder is located in tos/sensorboards/micasb/Sounder.nc and provides the StdControl interface. Modify SenseM.nc to add a StdControl as SounderControl, wiring it as appropriate in Sense.nc.  Remember to call init() to initialize the Sounder component. To make the sounder turn on from SenseM.nc, call SounderControl.start(). To turn off the sounder, call SounderControl.stop(). Be sure to test this new application many times to annoy everyone sitting around you.

Last updated 15 August 2003

This lesson introduces the TinyOS notion of tasks, which can be used to perform general-purpose "background" processing in an application. This lesson makes use of the SenseTask application, which is a revision of the Sense application from the previous lesson.

Task creation and scheduling

TinyOS provides a two-level scheduling hierarchy consisting of tasks and hardware event handlers. Remember that the keyword async declares a command or event that can be executed by a hardware event handler. This means it could be executed at any time (preempting other code), so async commands and events should do small amounts of work and complete quickly. Additionally, you should pay attention to the possibility of data races on all shared data accessed by an async command or event. Tasks are used to perform longer processing operations, such as background data processing, and can be preempted by hardware event handler.

A task is declared in your implementation module using the syntax

  task void taskname() { ... }

To dispatch a task for (later) execution, use the syntax

  post taskname();

The post operation places the task on an internal task queue which is processed in FIFO order. When a task is executed, it runs to completion before the next task is run; therefore, a task should not spin or block for long periods of time. Tasks do not preempt each other, but a task can be preempted by a hardware event handler. If you need to run a series of long operations, you should dispatch a separate task for each operation, rather than using one big task.
 

The SenseTask Application

To illustrate tasks, we have modified the Sense application from Lesson 2, which is found in apps/SenseTask. The SenseTaskM component maintains a circular data buffer, rdata, that contains recent photo sensor samples; the putdata() function is used to insert a new sample into the buffer. The dataReady() event simply deposits data into the buffer and posts a task, called processData(), for processing.
 

  // ADC data ready event handler
  async event result_t ADC.dataReady(uint16_t data) {
    putdata(data);
    post processData();
    return SUCCESS;
  }

Some time after the async event completes (there may be other tasks pending for execution), the processData() task will run. It computes the sum of the recent ADC samples and displays the upper three bits of the sum on the LEDs.

  task void processData() {
    int16_t i, sum=0;

    atomic {
    for (i=0; i < size; i++)
      sum += (rdata[i] >> 7);
    } 
    display(sum >> log2size);
  }

The keyword atomic in the task processData() illustrates the use of nesC atomic statements. This means the code section within the atomic curly braces will execute without preemption. In this example, access to the shared buffer rdata is being protected. Where else should this be used ?

Atomic statements delay interrupt handling which makes the system less responsive. To minimize this effect, atomic statements in nesC should avoid calling commands or signaling events when possible (the execution time of an external command or event will depend on what the component is wired to).
 

Exercises

Try to break up the processData() task so that each invocation of the task only adds one element of the rdata array to sum. processData() should then post itself to continue processing the complete sum, and display the LEDs when the final element of the array has been processed. Be careful of concurrency issues - since processData() is also posted from ADC.dataReady(), you might want to add a flag to prevent a new instance of the task from being started before the previous sum has been computed!

Last updated 9 September 2003

This lesson introduces the basic concepts of TinyOS and the nesC language in which the system is written. It includes a quick overview of the nesC language concepts and syntax to help you get started with programming in this environment.

Introduction

The TinyOS system, libraries, and applications are written in nesC, a new language for programming structured component-based applications. The nesC language is primarily intended for embedded systems such as sensor networks. nesC has a C-like syntax, but supports the TinyOS concurrency model, as well as mechanisms for structuring, naming, and linking together software components into robust network embedded systems.（不只是一个简单的语言编译器，还包含了一种基于组件和并发的OS模型在里面，直接生成一个含OS的完整系统，有必要对NesC进行进一步的分析了解）

   The principal goal is to allow application designers to build components that can be easily composed into complete, concurrent systems, and yet perform extensive checking at compile time.

TinyOS defines a number of important concepts that are expressed in nesC：

• First, nesC applications are built out of components with well-defined, bidirectional interfaces. 
• Second, nesC defines a concurrency model, based on tasks and hardware event handlers, and detects data races at compile time.（NesC定义了一个基于Task和硬件事件处理的并发模型）

Components

  Specification
  一个nesC应用包含一个或多个components，它们连接在一起构成一个可执行的应用.

  一个component 提供和使用接口. 这些接口是双向的，是访问component的唯一访问点.

  interface声明称为commands的interface提供者必须实现的函数集合，同时声明另一个称为events的函数集，该接口的使用者必须实现这些事件处理函数.当一个component调用接口中的commands时，它必须实现该接口的events. 单个component可以use或provide多个interfaces和同一接口的多个实例.

  Implementation

  nesC中包含两类components:

• modules：提供应用代码，实现一个或多个interface.
• configurations：用来组装其他components到一起, 连接这些components使用的interfaces到其他组件提供的interfaces. 这也称为wiring(连线，类似VHDL中的结构模型). 每个nesC应用通过把内部组建连接起来的top-level configuration进行描述.

   nesC对所有源文件使用".nc"扩展名 -- interfaces, modules, and configurations. Please see TinyOS Coding and Naming Conventions for more information on naming conventions.

Concurrency Model

   TinyOS仅执行一个程序，包含运行应用所需的系统组件和定制组件(用户定义编制的). 存在两条执行threads:

• tasks：任务就是函数，其执行是预留的（defered），一旦调度，它们就被执行，直至完成，无法被剥夺.
• hardware event handlers：硬件中断响应程序，同样运行到完成，但是可以剥夺task和其他hardware event handler的执行。作为硬件事件处理程序的一部分执行的Commands和events必须用async关键字声明.

    因为任务和硬件事件处理程序可以被其他异步(asynchronous)代码占先执行，nesC程序可能会出现某种竞争条件(race conditions). 这可以通过访问任务间互斥的共享数据来避免，也可以通过在atomic语句内完成所有对共享数据的访问. nesC编译器可以在编译时报告潜在的data races，存在误报的可能，这种情况可以使用norace关键字来声明相关变量，但是该关键字的使用要非常慎重.

   Please see the nesC Language Reference Manual for more information on programming in nesC.
 

An example application: Blink

   So far this is all fairly abstract - let's look at a concrete example: the simple test program "Blink" found in apps/Blink in the TinyOS tree. This application simply causes the red LED on the mote to turn on and off at 1Hz.

   Blink application is composed of two components:

• a module："BlinkM.nc"
• a configuration："Blink.nc". 

The reason for the distinction between modules and configurations is to allow a system designer to quickly "snap together" applications. For example, a designer could provide a configuration that simply wires together one or more modules, none of which she actually designed. Likewise, another developer can provide a new set of "library" modules that can be used in a range of applications.

Sometimes (as is the case with Blink and BlinkM) you will have a configuration and a module that go together. When this is the case, the convention used in the TinyOS source tree is that Foo.nc represents a configuration and FooM.nc represents the corresponding module. While you could name an application's implementation module and associated top-level configuration anything, to keep things simple we suggest that you adopt this convention in your own code. There are several other naming conventions used in TinyOS code; a summary is provided

The Blink.nc configuration

The nesC compiler, ncc, compiles a nesC application when given the file containing the top-level configuration. Typical TinyOS applications come with a standard Makefile that allows platform selection and invokes ncc with appropriate options on the application's top-level configuration.

Let's look at Blink.nc, the configuration for this application first:

configuration Blink {
  //其中可以说明uses和provides语句，配置可以使用和提供接口
}
implementation { //配置的具体实现
  components Main, BlinkM, SingleTimer, LedsC;//本配置涉及到的组件

  //下面是连线，类似VHDL语言中的结构模型中信号的连接
  //左边的接口(use)绑定到右边的接口实现(provide)
  Main.StdControl -> BlinkM.StdControl;
  Main.StdControl -> SingleTimer.StdControl;
  BlinkM.Timer -> SingleTimer.Timer;
  BlinkM.Leds -> LedsC;  //相当于BlinkM.Leds -> LedsC.Leds
}

The first thing to notice is the key word configuration, which indicates that this is a configuration file. The first two lines,

  configuration Blink {
  }

The actual configuration is implemented within the pair of curly bracket following key word implementation . The componentsline specifies the set of components that this configuration references, in this case Main, BlinkM, SingleTimer, and LedsC. The remainder of the implementation consists of connecting interfaces used by components to interfaces provided by others.

Main是TinyOS应用第一个执行的组件.更精确的说，Main.StdControl.init()命令是TinyOS执行的第一个命令，紧跟着是Main.StdControl.start()命令. 因此任何TinyOS应用必须在其顶层配置中包含Main组件。StdControl是一个用于初始化和启动TinyOS组件的公共interface. Let us have a look at tos/interfaces/StdControl.nc:

interface StdControl {
  command result_t init(); //组件初始化时被调用，可调用多次但必须在start和stop之前
  command result_t start();//组件启动，即组件实际第一次执行，可调用多次
  command result_t stop(); //停止组件，可调用多次
}

We see that StdControl defines three commands：

• init()：called when a component is first initialized,init() can be called multiple times, but will never be called after either start() or stop are called.
• start()：called when a component is started, that is, actually executed for the first time；
• stop()：called when the component is stopped, for example, in order to power off the device that it is controlling.  

  Main.StdControl -> SingleTimer.StdControl;
  Main.StdControl -> BlinkM.StdControl;

Concerning used interfaces, it is important to note that subcomponent initialization functions must be explicitly called by the using component. For example, the BlinkM module uses the interface Leds, so Leds.init() is called explicitly in BlinkM.init().

nesC uses arrows to determine relationships between interfaces. Think of the right arrow (->) as "binds to". The left side of the arrow binds an interface to an implementation on the right side. In other words, the component that uses an interface is on the left, and the component provides the interface is on the right.

The line

  BlinkM.Timer -> SingleTimer.Timer;

nesC supports multiple implementations of the same interface. The Timer interface is such a example. The SingleTimer component implements a single Timer interface while another component, TimerC, implements multiple timers using timer id as a parameter. Further discussions on timers can be found in Lesson 2.

Wirings can also be implicit. For example,

  BlinkM.Leds -> LedsC;

  BlinkM.Leds -> LedsC.Leds;

Now let's look at the module BlinkM.nc:

module BlinkM {
  provides {
    interface StdControl;
  }
  uses {
    interface Timer;
    interface Leds;
  }
}
// Continued below...

The first part of the code states that this is a module called BlinkMand declares the interfaces it provides and uses.  The BlinkM  module provides the interface StdControl.  This means that BlinkM implements the StdControl interface.  As explained above, this is necessary to get the Blink component initialized and started.  The BlinkM module also uses two interfaces: Leds and Timer. 这意味着BlinkM可以调用它use的接口中声明的任何command，而且必须实现这些接口中声明的任何events.

The Leds interface defines several commands like redOn(),redOff(), and so forth, which turn the different LEDs (red, green, or yellow) on the mote on and off. Because BlinkM uses the Leds interface, it can invoke any of these commands. Keep in mind, however, that Leds is just an interface: the implementation is specified in the Blink.nc configuration file.

Timer.nc is a little more interesting:

interface Timer {
  command result_t start(char type, uint32_t interval);
  command result_t stop();
  event result_t fired();//本接口会触发fired事件，使用者必须实现该事件的响应程序
}

Here we see that Timer interface defines the start() and stop() commands, and the fired() event.

The start() command is used to specify the type of the timer and the interval at which the timer will expire. The unit of the interval argument is millisecond. The valid types are TIMER_REPEAT and TIMER_ONE_SHOT. A one-shot timer ends after the specified interval, while a repeat timer goes on and on until it is stopped by the stop() command.

How does an application know that its timer has expired? The answer is when it receives an event. The Timer interface provides an event:

  event result_t fired();

Let's look at the rest of BlinkM.nc to see how this all fits together:

implementation {

  command result_t StdControl.init() {
    call Leds.init();//显式调用init
    return SUCCESS;
  }

  command result_t StdControl.start() {
    return call Timer.start(TIMER_REPEAT, 1000) ;
  }

  command result_t StdControl.stop() {
    return call Timer.stop();
  }

  event result_t Timer.fired()
  {
    call Leds.redToggle();
    return SUCCESS;
  }
}

This is simple enough. As we see the BlinkM module implements the StdControl.init(), StdControl.start(), and StdControl.stop() commands, since it provides the StdControl interface. It also implements the Timer.fired() event, which is necessary since BlinkM must implement any event from an interface it uses.

The init() command in the implemented StdControl interface simply initializes the Leds subcomponent with the call to Leds.init(). The start() command invokes Timer.start() to create a repeat timer that expires every 1000 ms. stop() terminates the timer. Each time Timer.fired() event is triggered, the Leds.redToggle() toggles the red LED.

You can view a graphical representation of the component relationships within an application. TinyOS source files include metadata within comment blocks that ncc, the nesC compiler, uses to automatically generate html-formatted documentation. To generate the documentation, type make <platform> docs from the application directory. The resulting documentation is located in docs/nesdoc/<platform>.docs/nesdoc/<platform>/index.html is the main index to all documented applications.
 

Compiling the Blink application

TinyOS supports multiple platforms. Each platform has its own directory in the tos/platform directory. In this tutorial, we will use the mica platform as an example. If you are in the TinyOS source tree, compiling the Blink application for the Mica mote is as simple as typing

  make mica

nesC itself is invoked using the ncc command which is based on gcc. For example, you can type

  ncc -o main.exe -target=mica Blink.nc

  avr-objcopy --output-target=srec main.exe main.srec

Now that we've compiled the application it's time to program the mote and run it. This example will use the Mica mote and the parallel-port-based programming board (mib500). Instructions on how to use the other programming boards are here. To download your program onto the mote, place the mote board (or mote and sensor stack) into the bay on the programming board, as shown below. You can either supply a 3 volt supply to the connector on the programming board or power the node directly. The red LED (labeled D2) on the programming board will be on when power is supplied. If you are using batteries to power the mote, be sure the mote is switched on (the power switch should be towards the connector).

Plug the 32-pin connector into the parallel port of a computer configured with the TinyOS tools, using a standard DB32 parallel port cable.

Type: make mica install. If you get the error:

  uisp -dprog=dapa --erase 
  pulse
  An error has occurred during the AVR initialization.
   * Target status:
      Vendor Code = 0xff, Part Family = 0xff, Part Number = 0xff

  Probably the wiring is incorrect or target might be `damaged'.
  make: *** [install] Error 2

If you are using an IBM ThinkPad, it may be necessary to tell the tools to use a different parallel port. You can do this by adding the line

  PROGRAMMER_EXTRA_FLAGS = -dlpt=3

If the installation is successful you should see something like the following:

  compiling Blink to a mica binary
  ncc -board=micasb -o build/mica/main.exe -Os -target=mica  -Wall -Wshadow -DDEF_TOS_AM_GROUP=0x7d -finline-limit=200 -fnesc-cfile=build/mica/app.c  Blink.nc -lm
  avr-objcopy --output-target=srec build/mica/main.exe
  build/mica/main.srec
      compiled Blink to build/mica/main.srec
      installing mica binary
  uisp -dprog=dapa  --erase 
  pulse
  Atmel AVR ATmega128 is found.
  Erasing device ...
  pulse
  Reinitializing device
  Atmel AVR ATmega128 is found.
  sleep 1              
  uisp -dprog=dapa  --upload if=build/mica/main.srec
  pulse
  Atmel AVR ATmega128 is found.
  Uploading: flash
  sleep 1              
  uisp -dprog=dapa  --verify if=build/mica/main.srec
  pulse
  Atmel AVR ATmega128 is found.
  Verifying: flash

Typing make clean in the Blink directory will clean up the compiled binary files.

If you are still having errors, then you need to check your TinyOS installation and check the Mica hardware. See System and Hardware Verification for details.
 

Exercises

To test your new-found TinyOS programming skills, try out the following:

• Modify Blink to display the lower three bits of a counter in the LEDs.

This tutorial has just scratched the surface of nesC's syntax and features. Rather than document everything extensively, we refer the reader to the nesC Project Pages as well as the documentation included with the nesC distribution in nesc/doc. These sources contain more complete documentation on the language.

Hopefully this should be enough of a start to get you going on programming in this fun new language.