-<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
-<html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" ^M "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
- <title>TinyOS Tutorial Lesson 1: TinyOS Component Model</title>
- <link href="../../stylesheets/tutorial.css" rel="stylesheet" type="text/css">
+<title>klueska.com</title>
</head>
-
+<frameset>
+<frame src="http://docs.tinyos.net/index.php/Getting_Started_with_TinyOS" name="redir_frame" />
+<noframes>
<body>
-
-<div class="title">Lesson 1: Getting Started with TinyOS and nesC</div>
-<div class="subtitle">Last updated April 8 2007</div>
-
- <h1>Introduction</h1>
-
- <p>This lesson shows you how to compile a TinyOS program and
- install it on a mote, introduces the basic concepts and syntax of
- the TinyOS component model, and shows you how to generate
- and navigate TinyOS's source code documentation.</p>
-
- <h1>Compiling and Installing</h1>
-
- <p>As a first exercise, you'll compile and install a very simple
- TinyOS application called Blink. If you don't have mote
- hardware, you can compile it for TOSSIM, the TinyOS simulator.</p>
-
- <p>You compile TinyOS applications with the program
- <tt>make</tt>. TinyOS uses a powerful and extensible make
- system that allows you to easily add new platforms and
- compilation options. The makefile system definitions are
- located in tinyos-2.x/support/make.</p>
-
- <p>The first step is to check that your environment is set up
- correctly. Run the <code>tos-check-env</code> command:</p>
-
-<pre>
-$ tos-check-env
-</pre>
-
- <p>This script checks pretty much everything that the TinyOS
- environment needs. Most of the warnings should be somewhat
- self-explanatory, if you are at all accustomed to a UNIX
- environment. If you are having trouble with warnings, your
- best bet is to join and ask questions on the
- <A HREF="https://mail.millennium.berkeley.edu/mailman/listinfo/tinyos-help">tinyos-help</A> email list. It's almost always the
- case that if you've run into a problem, someone else has too.
- Searching the <A HREF="http://mail.millennium.berkeley.edu/pipermail/tinyos/">help archives</A> can therefore be
- useful.</p>
-
- <p>If your system says some command is not available, then
- chances are you need to install the TinyOS tools (tos-*) RPM.
- Please refer to your installation instructions. If you have
- installed the RPM, then look in /usr/bin and /usr/local/bin
- for tos-check-env. If you have downloaded from CVS rather than
- used RPMs, then you need to compile and build the tools.
- Go to <code>tinyos-2.x/tools/tinyos</code> and type:</p>
-
-<pre>
-$ configure
-$ make
-$ make install
-</pre>
-
- <p>On Linux systems, you will either need superuser abilities or
- access to <code>sudo</code> for the last command.</p>
-
-
- <p>The second thing to check is that you have the TinyOS build system
- enabled. This involves the MAKERULES environment variable. In a shell,
- type</p>
-
- <pre>
- printenv MAKERULES
- </pre>
-
- <p>You should see <tt>/opt/tinyos-2.x/support/make/Makerules</tt>. If
- your TinyOS tree is installed somewhere besides the standard place,
- you might not see <tt>/opt</tt>, but rather a different initial path.
- If MAKERULES is not set (printenv prints nothing), you need to set it.
- Depending on your shell, this involves using either <tt>export</tt> (bash)
- or <tt>setenv</tt> (csh, tcsh). If you don't know about shell environment
- variables, this
- <A HREF="http://www.ee.surrey.ac.uk/Teaching/Unix/unix8.html">tutorial</A>
- should help.</p>
-
- <p>The make command to compile a TinyOS application is
- <code>make</code> <i>[platform]</i>, executed from the
- application's directory. To compile Blink, go the <code>apps/Blink</code>
- directory and depending on which hardware you have, type <tt>make micaz</tt>,
- <tt>make mica2</tt>, <tt>make telosb</tt>, or, for simulation, type
- <tt>make micaz sim</tt>.</p> You should see output such as this:
-
- <pre>
-dark /root/src/tinyos-2.x/apps/Blink -4-> make telosb
-mkdir -p build/telosb
- compiling BlinkAppC to a telosb binary
-ncc -o build/telosb/main.exe -Os -O -mdisable-hwmul -Wall -Wshadow
--DDEF_TOS_AM_GROUP=0x7d -Wnesc-all -target=telosb -fnesc-cfile=build/telosb/app.c
--board= BlinkAppC.nc -lm
- compiled BlinkAppC to build/telosb/main.exe
- 2782 bytes in ROM
- 61 bytes in RAM
-msp430-objcopy --output-target=ihex build/telosb/main.exe build/telosb/main.ihex
- writing TOS image
- </pre>
-
- <p>If you compile for TOSSIM, you will see a much longer message,
- as building TOSSIM requires several steps, such as building shared
- libraries and scripting support.</p>
-
- <p>If you are running Cygwin and see the error message "The procedure entry point basename could not be located in the dynamic link library cygwin1.dll" then you need to install the other Cygwin nesC RPM (step 4 of the <A HREF="../install-tinyos.html">install instructions</A> or step 2 of the <A HREF="../upgrade-tinyos.html">upgrade instructions</A>)</p>
-
- <h2>Making sure you're invoking the right version of the nesC compiler</h2>
-
- <p>If you see an error message along the lines of this:</p>
-
-<pre>
-BlinkAppC.nc:46: syntax error before `new'
-make: *** [exe0] Error 1
-</pre>
-
- <p>Then you are invoking an older version of the nesc compiler.
- Check by typing <tt>ncc --version</tt>. You should see:</p>
-
-<pre>
-ncc: 1.2.1
-nescc: 1.2.6
-</pre>
-
-
- <p>Followed by some information on what version of the C compiler
- is being used. If you see different versions than those above,
- your compilation problems are most probably due to the fact that
- make is invoking the wrong version. This can easily happen if
- you are upgrading from TinyOS 1.x. You might have passed the
- tos-check-env because you have the right compiler on your system,
- but for some reason make is invoking the wrong one.</p>
-
- <p><tt>ncc</tt> is a script that invokes the full compiler,
- <tt>nescc</tt>. It lives in <tt>tinyos-2.x/tools/tinyos/ncc</tt>.
- If you've installed from an RPM, then the RPM put the new
- version of <tt>ncc</tt> in <tt>/usr/bin</tt>. You can see which
- version make is invoking by typing <tt>which ncc</tt>:
-
-<pre>
-$ which ncc
-/usr/local/bin/ncc
-$ /usr/local/bin/ncc --version
-Unknown target mica
-Known targets for TinyOS directory /opt/tinyos-2.x/tos
-and the specified include directories are:
-none.
-</pre>
-
- <p>In this case, the version of ncc is so old that it doesn't even
- respond to the <tt>--version</tt> flag. In contrast,</p>
-
-<pre>
-$ /usr/bin/ncc --version
-ncc: 1.2.1
-nescc: 1.2.5
-</pre>
-
- <p>The best solution to this problem is to move the old ncc to
- a different name (keep in around in case you need to go back
- to your old setup):</p>
-
-<pre>
-$ mv /usr/local/bin/ncc /usr/local/bin/ncc.old
-$ which ncc
-/usr/bin/ncc
-</pre>
-
- <p>You can apply the same process for <tt>nescc</tt>:</p>
-
-<pre>
-$ nescc --version
-ncc: 1.1.2
-$ which nescc
-/usr/local/bin/nescc
-$ /usr/bin/nescc --version
-nescc: 1.2.5
-$ mv /usr/local/bin/nescc /usr/local/bin/nescc.old
-$ which nescc
-/usr/bin/nescc
-</pre>
-
- <p>Now that we've compiled the application it's time to program the
- mote and run it. The next step depends on what family of mote you
- are programming.</p>
-
- <ul>
- <li><A HREF="#mica">Installing on a mica-family mote</A></li>
- <li><A HREF="#telos">Installing on a telos-family mote</A></li>
- <li><A HREF="#tinynode">Installing on a tinynode mote</A></li>
- <li><A HREF="#eyes">Installing on an eyesIFX-family mote</A></li>
- <li><A HREF="#intel">Installing on an IntelMote2</A></li>
- </ul>
-
- <h2><A NAME="mica">Installing on a mica-family mote (micaz, mica2, mica2dot)</A></h2>
-
- <p>This example uses a Mica2 mote and the
- serial-based programming board (<span
- style="font-family: monospace;">mib510</span>). Instructions on how to
- use other programming boards are <a href="programmers.html">here</a>.
- 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 or 5 volt supply to the connector on the
- programming board or power the node directly. The green LED (labeled PWR)
- 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). The ON/OFF switch on the
- mib510 board should normally be left in the OFF position. Only switch it
- to ON if you have problems programming the mote and when you are done
- programming, switch it back to OFF (when the switch is ON the mote
- cannot send data to the PC). </p>
-
- <p>Plug the 9-pin connector into the serial port of a computer
- configured with the TinyOS tools, using a pass-through (not null-modem!)
- DB9 serial cable. If your computer does not have a serial port, you can
- easily obtain DB9-serial-to-USB cables. </p>
-
- <center>
- <table border="0" cellspacing="2" cellpadding="3" hspace="4">
- <tbody>
- <tr>
- <td><img src="img/mica-offboard.jpg" height="240" width="320"></td>
- <td><img src="img/mica-onboard.jpg" height="240" width="320"></td>
- </tr>
- <tr>
- <td><i>Mica2 mote next to the programming board</i></td>
- <td><i>Mica2 mote connected to the programming board</i></td>
- </tr>
- </tbody>
- </table>
- </center>
-
-<p>Type:
-<pre>make mica2 reinstall mib510,<i>serialport</i></pre>
-where <i>serialport</i> is the serial port device name. Under Windows, if
-your serial port is <tt>COM<i>n</i>:</tt>, you must use
-<tt>/dev/ttyS<i>n-1</i></tt> as the device name. On Linux, the device name
-is typically <tt>/dev/ttyS</tt><i>n</i> for a regular serial port and
-<tt>/dev/ttyUSB<i>n</i></tt> or <tt>/dev/usb/tts/<i>n</i></tt> for a
-USB-serial cable (the name depends on the Linux distribution). Additionally,
-on Linux, you will typically need to make this serial port world writeable.
-As superuser, execute the following command:
-<pre>chmod 666 <i>serialport</i></pre>
-<p>
-If the installation is successful you should see something like the
-following (if you don't, try repeating the <tt>make</tt> command): </p>
-
- <pre>
-cp build/mica2/main.srec build/mica2/main.srec.out
- installing mica2 binary using mib510
-uisp -dprog=mib510 -dserial=/dev/ttyUSB1 --wr_fuse_h=0xd9 -dpart=ATmega128
- --wr_fuse_e=ff --erase --upload if=build/mica2/main.srec.out
-Firmware Version: 2.1
-Atmel AVR ATmega128 is found.
-Uploading: flash
-
-Fuse High Byte set to 0xd9
-
-Fuse Extended Byte set to 0xff
-rm -f build/mica2/main.exe.out build/mica2/main.srec.out
- </pre>
-
-
- <A name="#telos"><h2>Installing on telos-family mote (telosa, telosb)</h2></A>
-<p>Telos motes are USB devices, and can be plugged into any USB port:
- <center>
- <table border="0" cellspacing="2" cellpadding="3" hspace="4">
- <tbody>
- <tr>
- <td><img src="img/telos.jpg" height="240" width="320"></td>
- <td><img src="img/telos2.jpg" height="240" width="320"></td>
- </tr>
- <tr>
- <td><i>Telos mote</i></td>
- <td><i>Telos mote plugged into a USB port</i></td>
- </tr>
- </tbody>
- </table>
- </center>
-
- <p>Because Telos motes are USB devices, they register with
- your OS when you plug them in. Typing <code>motelist</code>
- will display which nodes are currently plugged in:</p>
-<pre>
-$ motelist
-Reference CommPort Description
----------- ---------- ----------------------------------------
-UCC89MXV COM4 Telos (Rev B 2004-09-27)
-</pre>
-
-<p><i>motelist</i> tells you which ports have motes attached. Under
-Windows, it displays the mote's COM port (in this case 4), under Linux it
-displays just the USB serial port number (e.g., 2). Confusingly, the
-Windows version of the code installer (<tt>tos-bsl</tt>) takes the COM port
-number - 1 as it's argument (in this case 3); under Linux it takes the USB
-device name (e.g., /dev/ttyUSB2 or /dev/tts/usb/2 if motelist reports that
-the mote is device 2). On Linux, as with the mica programmers, you will
-typically need to make the USB serial port world writeable. As superuser,
-execute the following command:
-<pre>chmod 666 <i>usb-device-name</i></pre>
-
-Now you can install the application using one of:</p>
-
-<pre>
- make telosb reinstall bsl,3 # Windows example
- make telosb reinstall bsl,/dev/ttyUSB2 # Linux example
-</pre>
-
-<p>This would compile an image suitable for the telosb platform and install
-it with a mote ID of 2 on a mote connected to COM4 on Windows or
-/dev/ttyUSB2 on Linux. If you have a single mote installed, you can skip
-the bsl and device name/number arguments. Again, see the Getting Started
-Guide for your chosen platform for the exact make parameters.</p>
-
-<p>You should see something like this scroll by:</p>
-
-<pre>
- installing telosb binary using bsl
-tos-bsl --telosb -c 16 -r -e -I -p build/telosb/main.ihex.out
-MSP430 Bootstrap Loader Version: 1.39-telos-8
-Mass Erase...
-Transmit default password ...
-Invoking BSL...
-Transmit default password ...
-Current bootstrap loader version: 1.61 (Device ID: f16c)
-Changing baudrate to 38400 ...
-Program ...
-2782 bytes programmed.
-Reset device ...
-rm -f build/telosb/main.exe.out-2 build/telosb/main.ihex.out
-</pre>
-
-
-<A name="tinynode"><h2>Installing on a TinyNode mote</h2></A>
-<p>There are different ways to program a TinyNode mote depending on how
-it is connected to your computer. The most common case is to connect
-it to a serial port using either the standard extension board (SEB) or
-the MamaBoard. <i>(The other possible methods are to use a Mamaboard with a Digi
-Connect ethernet adaptor and program a node over the network, or to
-use a JTAG adaptor. These are not covered in this tutorial; please
-refer to the Tinynode documentation for further details.)</i>
-
-<p>To install an application on a TinyNode mote using the
-serial port, enter the following command, taking care to
-replace <tt>/dev/ttyXXX</tt> with the file device corresponding to the
-serial port that the tinynode is plugged into.</p>
-
-<pre>
- make tinynode reinstall bsl,/dev/XXX
-</pre>
-
-As with the telos and eyesIFX platforms, this command will reprogram your
-mote using the <tt>tos-bsl</tt> utility, and you will see similar
-output on your screen as given above for telos.
-
-<A NAME="eyes"><h2>Installing on an eyesIFX-family mote</h2></A>
-
-<p>The eyesIFX motes have a mini-B USB connector, allowing easy
-programming and data exchange over the USB. The on-board serial-to-USB
-chip exports two separate serial devices: a lower-numbered one used
-exclusively for serial data communication, and a higher-numbered one
-used for programming of the microcontroller.</p>
-
- <center>
- <table border="0" cellspacing="2" cellpadding="3" hspace="4">
- <tbody>
- <tr>
- <td><img src="img/eyesIFX.jpg" height="140" width="320"></td>
- <td><img src="img/eyesIFX_usb.jpg" height="240" width="320"></td>
- </tr>
- <tr>
- <td><i>eyesIFXv2 mote</i></td>
- <td><i>eyesIFXv2 mote attached to a USB cable</i></td>
- </tr>
- </tbody>
- </table>
- </center>
-
-
-
-<p>The actual programming is performed by the <i>msp430-bsl</i> script,
-conveniently invoked using the same <i>make</i> rules as for the telos
-motes. In the most basic form:</p>
-
-<pre>
- make eyesIFX install bsl
-</pre>
-
-<p>the install script defaults to programming using the /dev/ttyUSB1
-device on Linux and COM1 on Windows, giving output similar to this:</p>
-
-<pre>
- installing eyesIFXv2 binary using bsl
-msp430-bsl --invert-test --invert-reset --f1x -c /dev/ttyUSB1 -r -e -I -p build/eyesIFXv2/main.ihex.out
-MSP430 Bootstrap Loader Version: 2.0
-Mass Erase...
-Transmit default password ...
-Invoking BSL...
-Transmit default password ...
-Current bootstrap loader version: 1.61 (Device ID: f16c)
-Program ...
-2720 bytes programmed.
-Reset device ...
-rm -f build/eyesIFXv2/main.exe.out build/eyesIFXv2/main.ihex.out
-</pre>
-
-<p> The programming device can also be explicitly set as a parameter
-of the <i>bsl</i> command using shorthand or full notation:</p>
-
-<pre>
- make eyesIFX install bsl,USB3
- make eyesIFX install bsl,/dev/ttyUSB3
-</pre>
-
-<p>The eyesIFX motes can be programmed over the provided JTAG interface
-with the help of the msp430-jtag script:</p>
-
-<pre>
- make eyesIFX install jtag
-</pre>
-
-<p>producing output as in the following:</p>
-
-<pre>
- installing eyesIFXv2 binary using the parallel port jtag adapter
-msp430-jtag -Iepr build/eyesIFXv2/main.ihex.out
-MSP430 parallel JTAG programmer Version: 2.0
-Mass Erase...
-Program...
-2720 bytes programmed.
-Reset device...
-Reset and release device...
-</pre>
-
-
-<A NAME="intel"><h2>Installing on an IntelMote2</h2></A>
-
-
-<h1>Installation options</h1>
-
-<p>You can now test the program by unplugging the mote from the
-programming board and turning on the power switch (if it's not already
-on). With any luck the three LEDs should be displaying a counter
-incrementing at 4Hz.</p>
-
-<p>The <tt>reinstall</tt> command told the make system to
-install the currently compiled binary: it skips the
-compilation process. Type <tt>make clean</tt> to clean up all
-of the compiled binary files, then type, e.g., <tt>make telosb install</tt>
-This will recompile Blink and install it on one action.</p>
-
-<p>Networking almost always requires motes to have unique identifiers.
-When you compile a TinyOS application, it has a default unique
-identifier of 1. To give a node a different identifier, you can specify
-it at installation. For example, if you type <tt>make telosb install.5</tt>
-or <tt>make telosb reinstall.5</tt>, you will install the application
-on a node and give it 5 as its identifier.</b></p>
-
-<p>For more information on the build system, please see <a
-href="lesson13.html">Lesson 13</a>.
-
-<h1>Components and Interfaces</h1>
-
- <p>Now that you've installed Blink, let's look at how
- it works. Blink, like all TinyOS code, is written
- in nesC, which is C with some additional language
- features for components and concurrency.</p>
-
- <p>A nesC application consists of one or more <i>components</i>
- assembled, or <i>wired</i>, to form an application executable.
- Components define two scopes: one for their specification which
- contains the names of their <i>interfaces</i>, and a second scope for their
- implementation. A component <i>provides</i> and <i>uses</i>
- interfaces. The provided interfaces are intended to represent
- the functionality that the component provides to its user in its
- specification; the used interfaces represent the functionality the
- component needs to perform its job in its implementation.</p>
-
- <p>Interfaces are bidirectional: they specify a set of
- <i>commands</i>, which are functions to be implemented by the
- interface's provider, and a set of <i>events</i>, which are functions
- to be implemented by the interface's user. For a component to call the
- commands in an interface, it must implement the events of that
- interface. A single component may use or provide multiple interfaces
- and multiple instances of the same interface.</p>
-
- <p>The set of interfaces which a component provides together with the
- set of interfaces that a component uses is considered that component's
- <i>signature</i>.</p>
-
- <h2>Configurations and Modules</h2>
-
- <p>There are two types of components in nesC: <i>modules</i> and
- <i>configurations</i>. Modules provide the implementations of one or more
- interfaces. Configurations are used to assemble other components
- together, connecting interfaces used by components to interfaces
- provided by others. Every nesC
- application is described by a top-level configuration that wires
- together the components inside.</p>
-
- <h1>Blink: An Example Application</h1>
-
- <p>Let's look at a concrete example:
- <tt><a href="../../../apps/Blink">Blink</a></tt> in the TinyOS
- tree. As you saw, this application displays a counter on the
- three mote LEDs. In actuality, it simply causes the LED0 to to turn on and off at
- .25Hz, LED1 to turn on and off at .5Hz, and LED2 to turn on and off at
- 1Hz. The effect is as if the three
- LEDs were displaying a binary count of one to seven every two
- seconds. </p>
-
-<p>Blink is composed of two <b>components</b>: a <b>module</b>, called
-"<tt>BlinkC.nc</tt>", and a <b>configuration</b>, called
-"<tt>BlinkAppC.nc</tt>". Remember that all applications require a
-top-level configuration file, which is typically named after the
-application itself. In this case <tt>BlinkAppC.nc</tt> is the
-configuration for the Blink application and the source file that the
-nesC compiler uses to generate an executable file. <tt>BlinkC.nc</tt>,
-on the other hand, actually provides the <i>implementation</i> of the
-Blink application. As you might guess, <tt>BlinkAppC.nc</tt> is used
-to wire the <tt>BlinkC.nc</tt> module to other components that the
-Blink application requires. </p>
-
-<p>The reason for the distinction between modules and configurations
-is to allow a system designer to build applications out of existing
-implementations. 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. </p>
-
-<p>Sometimes (as is the case with <tt>BlinkAppC</tt> and
-<tt>BlinkC</tt>) 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:</p>
-
-
-<CENTER>
-<table border="1" cellspacing="1" cellpadding="1">
-<tbody>
-
-<tr>
-<td>File Name </td>
-<td>File Type </td>
-</tr>
-
-<tr>
-<td><tt>Foo.nc</tt></td>
-<td>Interface </td>
-</tr>
-
-<tr>
-<td><tt>Foo.h</tt></td>
-<td>Header File</td>
-</tr>
-
-<tr>
-<td><tt>FooC.nc </tt></td>
-<td>Public Module</td>
-</tr>
-
-<tr>
-<td><tt>FooP.nc</tt></td>
-<td>Private Module</td>
-</tr>
-
-
-</tbody>
-</table>
-</CENTER>
-
-<p>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
-conventions used in TinyOS;
-<a href="../tep3.html">TEP 3</a>
-specifies the coding standards and best current practices.
-
-<h1>The BlinkAppC.nc Configuration</h1>
-
-<p>The nesC compiler 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.
-
-<p>Let's look at <tt>BlinkAppC.nc</tt>, the configuration for this
-application first:
-
-<pre></pre>
-<prehead>apps/Blink/BlinkAppC.nc:</prehead>
-<pre>
-configuration BlinkAppC {
-}
-implementation {
- components MainC, BlinkC, LedsC;
- components new TimerMilliC() as Timer0;
- components new TimerMilliC() as Timer1;
- components new TimerMilliC() as Timer2;
-
- BlinkC -> MainC.Boot;
- BlinkC.Timer0 -> Timer0;
- BlinkC.Timer1 -> Timer1;
- BlinkC.Timer2 -> Timer2;
- BlinkC.Leds -> LedsC;
-}
-</pre>
-
-<p>The first thing to notice is the key word <tt>configuration</tt>,
-which indicates that this is a configuration file. The first two
-lines,
-
-<pre></pre>
-<prehead>apps/Blink/BlinkAppC.nc:</prehead>
-<pre>
-configuration BlinkAppC {
-}
-</pre>
-
-simply state that this is a configuration called <tt>BlinkAppC</tt>.
-Within the empty braces here it is possible to specify <tt>uses</tt>
-and <tt>provides</tt> clauses, as with a module. This is important to
-keep in mind: a configuration can use and provide interfaces. Said
-another way, not all configurations are top-level applications.
-
-<p>The actual configuration is implemented within the pair of curly
-brackets following the key word <tt>implementation </tt>. The
-<tt>components</tt> lines specify the set of components that this
-configuration references. In this case those components are
-<tt>Main</tt>, <tt>BlinkC</tt>,
-<tt>LedsC</tt>, and three instances of a timer component called
-<tt>TimerMilliC</tt> which will be referenced as Timer0, Timer1,
-and Timer2<a href="#timermillic_footnote">(1)</a>. This is accomplished
-via the <i>as</i> keyword which is simply an alias<a href="#hint10">(2)</a>.
-
-<p>As we continue reviewing the BlinkAppC application, keep in mind that the
-BlinkAppC component is not the same as the BlinkC component. Rather,
-the BlinkAppC component is composed of the BlinkC component along with
-MainC, LedsC and the three timers.
-
-<p>The remainder of the BlinkAppC configuration consists of connecting
-interfaces used by components to interfaces provided by others. The
-<tt>MainC.Boot</tt> and <tt>MainC.SoftwareInit</tt> interfaces are
-part of TinyOS's boot sequence and will be covered in detail in Lesson
-3. Suffice it to say that these wirings enable the LEDs and Timers to
-be initialized.
-
-<p>The last four lines wire interfaces that the BlinkC component
-<i>uses</i> to interfaces that the TimerMilliC and LedsC
-components <i>provide</i>. To fully understand the semantics of these
-wirings, it is helpful to look at the BlinkC module's definition and
-implementation.
-
-<h1>The BlinkC.nc Module</h1>
-
-<pre></pre>
-<prehead>apps/Blink/BlinkC.nc:</prehead>
-<pre>
-module BlinkC {
- uses interface Timer<TMilli> as Timer0;
- uses interface Timer<TMilli> as Timer1;
- uses interface Timer<TMilli> as Timer2;
- uses interface Leds;
- uses interface Boot;
-}
-implementation
-{
- // implementation code omitted
-}
-</pre>
-
-<p>The first part of the module code states that this is a module
-called <tt>BlinkC</tt>and declares the interfaces it provides and
-uses. The <tt>BlinkC</tt> module <b>uses</b> three
-instances of the interface <tt>Timer<TMilli></tt> using the
-names Timer0, Timer1 and Timer2 (the <tt><TMilli></tt> syntax
-simply supplies the generic Timer interface with the required timer
-precision). Lastly, the <tt>BlinkC</tt>
-module also uses the Leds and Boot interfaces. This means that BlinkC
-may call any command declared in the interfaces it uses and must also
-implement any events declared in those interfaces.
-
-<p>After reviewing the interfaces used by the <tt>BlinkC</tt>
-component, the semantics of the last four lines in
-<tt>BlinkAppC.nc</tt> should become clearer. The line
-<tt>BlinkC.Timer0 -> Timer0</tt> wires the three
-<tt>Timer<TMilli></tt> interface used by <tt>BlinkC</tt> to the
-<tt>Timer<TMilli></tt> interface provided the three
-<tt>TimerMilliC</tt> component. The <tt>BlinkC.Leds ->
-LedsC</tt> line wires the <tt>Leds</tt> interface used by the
-<tt>BlinkC</tt> component to the <tt>Leds</tt> interface provided by
-the <tt>LedsC</tt> component.
-
-<p>nesC uses arrows to bind interfaces to one another. The right arrow
-(<tt>A->B</tt>) as "A wires to B". The left side of the arrow (A)
-is a user of the interface, while the right side of the arrow (B) is
-the provider. A full wiring is <tt>A.a->B.b</tt>, which means
-"interface a of component A wires to interface b of component B."
-Naming the interface is important when a component uses or provides multiple
-instances of the same interface. For example, BlinkC uses three instances of
-Timer: Timer0, Timer1 and Timer2.
-
-When a component only has one instance
-of an interface, you can elide the interface name. For example, returning
-to BlinkAppC:
-
-<pre></pre>
-<prehead>apps/Blink/BlinkAppC.nc:</prehead>
-<pre>
-configuration BlinkAppC {
-}
-implementation {
- components MainC, BlinkC, LedsC;
- components new TimerMilliC() as Timer0;
- components new TimerMilliC() as Timer1;
- components new TimerMilliC() as Timer2;
-
- BlinkC -> MainC.Boot;
- BlinkC.Timer0 -> Timer0;
- BlinkC.Timer1 -> Timer1;
- BlinkC.Timer2 -> Timer2;
- BlinkC.Leds -> LedsC;
-}
-</pre>
-
-<p>The interface name Leds does not have to be included in LedsC:</p>
-
-<pre>
- BlinkC.Leds -> LedsC; // Same as BlinkC.Leds -> LedsC.Leds
-</pre>
-
-<p>Because BlinkC only uses one instance of the Leds interface, this
-line would also work:</p>
-
-<pre>
- BlinkC -> LedsC.Leds; // Same as BlinkC.Leds -> LedsC.Leds
-</pre>
-
-<p>As the TimerMilliC components each provide a single instance of Timer,
-it does not have to be included in the wirings:</p>
-
-<pre>
- BlinkC.Timer0 -> Timer0;
- BlinkC.Timer1 -> Timer1;
- BlinkC.Timer2 -> Timer2;
-</pre>
-
-<p>However, as BlinkC has three instances of Timer, eliding the name
-on the user side would be a compile-time error, as the compiler would
-not know which instance of Timer was being wired:</p>
-
-<pre>
- BlinkC -> Timer0.Timer; // Compile error!
-</pre
-
-<p>The direction of a wiring arrow is always from a user to a
-provider. If the provider is on the left side, you can also
-use a left arrow:</p>
-
-<pre>
- Timer0 <- BlinkC.Timer0; // Same as BlinkC.Timer0 -> Timer0;
-</pre>
-
-<p>For ease of reading, however, most wirings are left-to-right.</p>
-
-<h1>Visualizing a Component Graph</h1>
-
-<p>Carefully engineered TinyOS systems often have many layers of configurations,
-each of which refines the abstraction in simple way, building something robust
-with very little executable code. Getting to the modules underneath
--- or just navigating the layers -- with a text editor can be laborious.
-To aid in this process, TinyOS and nesC have a documentation feature called
-nesdoc, which generates documentation automatically from source code. In
-addition to comments, nesdoc displays the structure and composition of
-configurations.</p>
-
-<p>To generate documentation for an application, type</p>
-
-<pre>
- make <i>platform</i> docs
-</pre>
-
-<p>You should see a long list of interfaces and components stream by. If you
-see the error message</p>
-
-<pre>sh: dot: command not found</pre>
-
-<p>then you need to <A HREF="http://www.graphviz.org/Download..php">install
-graphviz</A>, which is the program that draws the component graphs.</p>
-
-<p>Once you've generated the documentation, go to <tt>tinyos-2.x/doc/nesdoc</tt>. You
-should see a directory for your platform: open its <tt>index.html</tt>, and
-you'll see a list of the components and interfaces for which you've
-generated documentation. For example, if you generated documentation
-for Blink on the telosb platform, you'll see documentation for interfaces
-such as Boot, Leds, and Timer, as well as some from the underlying hardware
-implementations, such as Msp430TimerEvent and HplMsp430GeneralIO.</p>
-
-<p>In the navigation panel on the left, components are below interfaces.
-Click on BlinkAppC, and you should a figure like this: </p>
-
-<CENTER>
- <IMG SRC="img/BlinkAppC.gif">
-</CENTER>
-
-<p>In nesdoc diagrams, a single box is a module and a double box is a
-configuration. Dashed border lines denote that a component is a generic:</p>
-<CENTER>
-<TABLE CELLPADDING=6 BORDER=1>
- <TR>
- <td></td>
- <td><b>Singleton</b></td>
- <td><b>Generic</b></td>
- </TR>
- <TR>
- <td>Module</td>
- <td><IMG SRC="img/singleton-module.gif"></td>
- <td><IMG SRC="img/generic-module.gif"></td>
- </TR>
- <TR>
- <td>Configuration</td>
- <td><IMG SRC="img/singleton-configuration.gif"></td>
- <td><IMG SRC="img/generic-configuration.gif"></td>
- </TR>
-</TABLE>
-</CENTER>
-<p>Lines denote wirings, and shaded ovals denote interfaces
-that a component provides or uses. You can click on the components
-in the graph to examine their internals. Click on MainC, which shows
-the wirings for the boot sequence:</p>
-
-<CENTER>
- <IMG SRC="img/tos.system.MainC.gif">
-</CENTER>
-
-<p>Shaded ovals denote wireable interfaces.
-Because MainC provides the Boot interface and uses the Init (as
-SoftwareInit) interface, it has two shaded ovals. Note the direction
-of the arrows: because it uses SoftwareInit, the wire goes out from
-RealMainP to SoftwareInit, while because it provides Boot, the wire
-goes from Boot into RealMainP. The details of MainC aren't too important
-here, and we'll be looking at it in greater depth in
-<A HREF="lesson3.html">lesson 3</A>
-(you can also read <A HREF="../tep107.html">TEP 107</A> for details),
-but looking at the components you can get a sense of what it does: it
-controls the scheduler, initializes the hardware platform, and
-initializes software components.</p>
-
-<h1>Conclusion</h1>
-
-<p>This lesson has introduced the concepts of the TinyOS component
-model: configurations, modules, interfaces and wiring. It showed
-how applications are built by wiring components together. The next
-lesson continues with Blink, looking more closely at modules,
-including the TinyOS concurrency model and executable code.
-
-<p>
-<a name=#related_docs>
-<h1>Related Documentation</h1>
-</a>
-<ul>
-<li> mica mote Getting Started Guide at <a href="http://www.xbow.com">Crossbow</a>
-<li> telos mote Getting Started Guide for <a href="http://www.moteiv.com">Moteiv</a>
-<li> <a href="https://sourceforge.net/projects/nescc">nesc at sourceforge</a>
-<li> <a href="http://nescc.sourceforge.net/papers/nesc-ref.pdf">nesC reference manual</a>
-<li> <a href="http://csl.stanford.edu/~pal/pubs/tinyos-programming-1-0.pdf">TinyOS Programming Guide</a>
-<li> <a href="../tep3.html">TEP 3: TinyOS Coding Conventions</a>
-<li> <a href="../tep102.html">TEP 102: Timers</a>
-<li> <a href="../tep106.html">TEP 106: Schedulers and Tasks</a>
-<li> <a href="../tep107.html">TEP 106: TinyOS 2.x Boot Sequence</a>
-</ul>
-
-<p>
-<hr>
-
-<p><a name="timermillic_footnote">(1)</a> The TimerMilliC component is a
-<i>generic component</i> which means that, unlike non-generic components,
-it can be instantiated more than once. Generic components can take types
-and constants as arguments, though in this case TimerMilliC takes
-none. There are also <i>generic interafces</i>, which take type arguments
-only. The Timer interface provided by TimerMilliC is a generic interface;
-its type argument defines the timer's required precision (this prevents
-programmer from wiring, e.g., microsecond timer users to millisecond timer
-providers). A full explanation of generic components is outside this
-document's scope, but you can read about them in <!-- TODO: Need to update
-this link to a real file><a href="../../nesc/user/generics-1.2.txt"> -->the
-nesc generic component documentation</a>.
-
-<p><a name="hint10">(2)</a>
-<b>Programming Hint 10:</b> Use the <i>as</i> keyword liberally. From
-<a href="http://csl.stanford.edu/~pal/pubs/tinyos-programming-1-0.pdf"><i>TinyOS Programming</i></a>
-
-
-<!-- Begin footer -->
-<br>
-<hr>
-<center>
-<p>< <b><a href="index.html">Top</a></b>
- | <b><a href="lesson2.html">Next Lesson </a> ></b>
-</center>
-
+<p>Sorry, your browser does not support frames. Please <a href="http://docs.tinyos.net/index.php/Getting_Started_with_TinyOS" target="_top">go here</a>.</p>
</body>
-</html>
+</noframes>
+</frameset>
+</html>
\ No newline at end of file
projects / tinyos-2.x.git / blobdiff