[Tinyos-2-commits]
CVS: tinyos-2.x/doc/html/tutorial index.html, 1.7,
1.8 lesson1.html, 1.7, 1.8 lesson10.html, 1.3,
1.4 lesson11.html, 1.14, 1.15 lesson12.html, 1.4,
1.5 lesson13.html, 1.3, 1.4 lesson15.html, 1.9,
1.10 lesson16.html, 1.2, 1.3 lesson2.html, 1.4,
1.5 lesson3.html, 1.3, 1.4 lesson4.html, 1.5, 1.6 lesson5.html,
1.5, 1.6 lesson6.html, 1.4, 1.5 lesson7.html, 1.5,
1.6 lesson8.html, 1.7, 1.8
Kevin Klues
klueska at users.sourceforge.net
Sun Jan 27 22:00:05 PST 2008
Update of /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv18117/tutorial
Modified Files:
index.html lesson1.html lesson10.html lesson11.html
lesson12.html lesson13.html lesson15.html lesson16.html
lesson2.html lesson3.html lesson4.html lesson5.html
lesson6.html lesson7.html lesson8.html
Log Message:
Update to tutorials to redirect them to the wiki now instead of directly being modified here anymore
Index: index.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/index.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** index.html 3 Sep 2007 22:38:41 -0000 1.7
--- index.html 28 Jan 2008 05:59:55 -0000 1.8
***************
*** 1,148 ****
! <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
! <html>
<head>
! <title>TinyOS Tutorial</title>
! <link href="../../stylesheets/tutorial.css" rel="stylesheet" type="text/css">
</head>
!
<body>
!
! <div class="title">TinyOS 2.0 Tutorials </div>
! <div class="subtitle">Last updated 30 Aug 2007</div>
!
! <p>
! These brief tutorials are intended to get you started with TinyOS. They show
! you the basics of writing, compiling, and installing TinyOS applications.
! They introduce the basic TinyOS abstractions: computation, communication,
! sensing, and storage. The later tutorials go a little deeper into some of
! the more advanced areas of TinyOS, such as handling interrupts,
! power management, and how platforms are organized.
! </p>
!
! <h1><a href="lesson1.html">Lesson 1: TinyOS</a></h1>
!
! <dd>Lesson 1 introduces the major concepts of TinyOS: components, modules,
! configurations and interfaces. It shows you how to compile and install
! a TinyOS program on a mote.
! </dd>
!
! <h1><a href="lesson2.html">Lesson 2: Modules and the TinyOS Execution Model</a></h1>
!
! <dd>Lesson 2 explains the TinyOS execution model, looking more closely
! at modules. It explains events, commands and their relationships to
! interfaces in greater depth, introducing split-phase operations.
! It explains tasks, the basic mechanism in TinyOS for components to
! cooperatively share the processor.
! </dd>
!
! <h1><a href="lesson3.html">Lesson 3: Mote-mote radio communication</a></h1>
!
! <dd> Lesson 3 introduces the TinyOS communication model. There is an exercise that
! illustrates sending and receiving messages.
! </dd>
!
! <h1><a href="lesson4.html">Lesson 4: Mote-PC serial communication and SerialForwarder</a></h1>
!
! <dd> Lesson 4 introduces the the TinyOS toolchain for PCs
! and laptops to communicate with motes. It describes the
! concept of a packet source, the <code>mig</code> tool,
! and SerialForwarder.
! </dd>
!
! <h1><a href="lesson5.html">Lesson 5: Sensing</a></h1>
!
! <dd>Lesson 5 explains how to sample sensors in TinyOS. There is an exercise that
! periodically samples a sensor and displays the value on the leds.
! </dd>
!
! <h1><a href="lesson6.html">Lesson 6: Boot Sequence</a></h1>
!
! <dd>Lesson 6 details the boot sequence and, in doing so, answers the question, "But where is main()?".
! </dd>
!
! <h1><a href="lesson7.html">Lesson 7: Storage</a></h1>
!
! <dd> Lesson 7 introduces the TinyOS storage model. Sample
! applications illustrate the use of the Mount, ConfigStorage,
! LogRead and LogWrite interfaces.
! </dd>
!
! <h1><a href="lesson8.html">Lesson 8: Resource Arbitration and Power Management</a></h1>
!
! <dd> Lesson 8 introduces the TinyOS resource arbitration and power management model. There are two
! exercises in this tutorial. The first one illustrates how to gain access to predefined shared resources.
! The second one illustrates how to create your own shared resource. In both tutorials, the process for controlling
! the power states of the resource is presented.
! </dd>
!
! <h1>Lesson 9: Concurrency</h1>
!
! <dd> Lesson 9 introduces the TinyOS concurrency model. Tasks are revisited and async code is introduced.
! This tutorial is currently unfinished.
! </dd>
!
! <h1><a href="lesson10.html">Lesson 10: Platforms</a></h1>
!
! <dd> Lesson 10 provides a better understanding of the difference between "make
! micaz" and "make telosb," including how these commands map into underlying
! files, directories, and definitions. It is not necessary for most TinyOS
! developers, but is included as a starter's guide for people who wish to
! understand the make system better or wish to design a new platform.
! </dd>
!
! <h1><a href="lesson11.html">Lesson 11: TOSSIM</a></h1>
!
! <dd> Lesson 11 introduces TOSSIM, a TinyOS simulator. TOSSIM allows
! you to compile your TinyOS applications into a simulation
! framework, where you can perform reproducible tests and debug
! your code with standard development tools.
! </dd>
!
! <h1><a href="lesson12.html">Lesson 12: Network Protocols</a></h1>
!
! <dd> Lesson 12 introduces two basic multihop protocols,
! Dissemination and Collection. Dissemination reliably
! delivers small data items to every node in a network,
! while collection delivers small data items from every node
! in a network to designated collection roots.
! </dd>
!
! <h1><a href="lesson13.html">Lesson 13: TinyOS Toolchain</a></h1>
!
! <dd> Lesson 13 describes the details of the TinyOS toolchain, including
! the build system, how to create your own Makefile, and how to find out
! more information on the various tools included with TinyOS.
! </dd>
!
! <h1>Lesson 14: Building a simple but full-featured application</h1>
!
! <dd> Lesson 14 goes through the process of building a simple anti-theft
! application using many of the features and services of TinyOS 2. Lesson 14
! is found in the tinyos-2.x/apps/AntiTheft directory. The powerpoint slides
! found there (also available in pdf form) go over the basic principles of
! TinyOS, and show how to build the accompanying AntiTheft application. Please
! start by reading the README.txt file in the AntiTheft directory.
!
! <p>To run the AntiTheft demo you will need mica2 or micaz motes, and
! some mts310 sensor boards (you can also use mts300 boards, though you
! will lose the movement detection functionality). If you do not have this
! hardware, the slides and AntiTheft code should still provide a good
! overview of TinyOS 2.
! </dd>
! <h1><a href="lesson15.html">Lesson 15: The TinyOS printf Library</a></h1>
!
! <dd> Lesson 15 describes the details of using the TinyOS <code>printf</code> library to
! print debug messages to your PC from a TinyOS application running on a mote.
! </dd>
!
! <h1><a href="lesson16.html">Lesson 16: Writing Low Power Sensing Applications</a></h1>
! <dd>
! This lesson demonstrates how to write low power sensing applications in TinyOS. At
! any given moment, the power consumption of a wireless sensor node is a function of its
! microcontroller power state, whether the radio, flash, and sensor peripherals are on,
! and what operations active peripherals are performing. This tutorial shows you
! how to best utilize the features provided by TinyOS to keep the power consumption
! of applications that use these devices to a minumum.
! </dd>
</body>
! </html>
--- 1,14 ----
! <!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>klueska.com</title>
</head>
! <frameset>
! <frame src="http://docs.tinyos.net/index.php/TinyOS_Tutorials" name="redir_frame" />
! <noframes>
<body>
! <p>Sorry, your browser does not support frames. Please <a href="http://docs.tinyos.net/index.php/TinyOS_Tutorials" target="_top">go here</a>.</p>
</body>
! </noframes>
! </frameset>
! </html>
\ No newline at end of file
Index: lesson1.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/lesson1.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** lesson1.html 31 Jul 2007 07:15:44 -0000 1.7
--- lesson1.html 28 Jan 2008 05:59:55 -0000 1.8
***************
*** 1,907 ****
! <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
! <html>
<head>
! <title>TinyOS Tutorial Lesson 1: TinyOS Component Model</title>
! <link href="../../stylesheets/tutorial.css" rel="stylesheet" type="text/css">
</head>
!
<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>
!
</body>
! </html>
--- 1,14 ----
! <!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>klueska.com</title>
</head>
! <frameset>
! <frame src="http://docs.tinyos.net/index.php/Getting_Started_with_TinyOS" name="redir_frame" />
! <noframes>
<body>
! <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>
! </noframes>
! </frameset>
! </html>
\ No newline at end of file
Index: lesson10.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/lesson10.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** lesson10.html 12 Dec 2006 18:22:53 -0000 1.3
--- lesson10.html 28 Jan 2008 05:59:55 -0000 1.4
***************
*** 1,560 ****
! <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
! <html>
<head>
! <title>TinyOS Tutorial Lesson 10: Platforms</title>
! <link href="../../stylesheets/tutorial.css" rel="stylesheet" type="text/css">
</head>
!
<body>
!
! <div class="title">Lesson 10: Platforms</div>
! <div class="subtitle">Last updated October 23 2006</div>
!
! <h1>Introduction</h1>
!
! <p>Many different hardware platforms (e.g micaZ, telos, eyesIFX) can be
! used with TinyOS. This lesson shows you what a platform port consists
! of, and how TinyOS reuses as much code as possible between different
! platforms.
! The lesson will proceed by showing how to do the port for an imaginary
! mote called "yamp", which has a MSP430 microcontroller and a CC2420
! radio transceiver.
!
! <p>
! The <b>target audience</b> of this lesson consists of those people that want
! to better understand what the difference between e.g "make micaz" and "make
! telosb" is, and how these differences concretely map into the underlying
! files, definitions, etc.
!
! <p> Note that the material covered in this tutorial is <b>not</b>
! strictly necessary for regular tinyos developpers, and you can safely skip
! it if you have no intention of working down to the lowest level or
! developping new platforms.
!
! </p>
!
! <h1>Chips vs Platforms</h1>
!
! <p>
! Two key building blocks for any mote are the microcontroller and
! radio transceiver.
! Of course, both a microcontroller and a radio can be used on
! more than one platform. This is indeed the case for the MSP430 and CC2420
! that our yamp mote uses (telos, eyes, and tinynode use the MSP430; telos
! and micaz use the CC2420).
! </p>
!
! <p>
! Given this multiplicity of platforms, it would be vasly redundant if each
! platform developper had to rewrite the software support for each chip
! from scratch. While a chip may be physically wired in a different way on
! different platforms (e.g., a radio is connected to a different digital
! pins on the microcontroller), by far the largest part of the logic to
! deal with a chip is platform-independent.
! </p>
!
! <p>
! Thus, platform-independent code to support a chip is placed in a
! chip-specific directory. Writing a platform port for a platform is then
! (essentially) a matter of <b>pulling in the code for each of the
! platform's chips, and "gluing" things together</b>.
! For example, the modules and components that support the CC2420 are in
! tos/chips/cc2420. This radio is used on both the telos and micaZ motes; the
! "gluing" is done by the modules in the tos/platforms/telosa/chips/cc2420 and
! tos/platforms/micaz/chips/cc2420/ directories.
! </p>
!
! <p>
! Note that in general there may
! be more to a platform port than pulling in existing code for different
! chips, in particular when a new platform uses a chip that is not yet
! supported. Developping drivers for a new chip can be a non-trivial
! undertaking (especially for radios and microcontrollers); these aspects
! are not covered here.
! </p>
!
! <h1>Initial platform bring-up</h1>
!
! <p>
! As a first step to bring up the platform, we will stick to the bare minimum in
! order to compile and install the Null application on our yamp mote.
! </p>
!
! <p>
! All platform-specific code goes in tos/platforms/<platformname>.
! For example, we have tos/platforms/micaz or tos/platforms/tinynode.
! Our first step is to create a directory for the yamp platform:
! <pre>
! $ cd tinyos-2.x/tos/platforms
! $ mkdir yamp
! </pre>
! </p>
!
! <h2>The .platform file</h2>
!
! Each platform directory (such as tos/platforms/yamp) should contain a
! file named ".platform", that contains basic compiler parameters
! information for each platform. So, create the file
! "tos/platforms/yamp/.platform" (note the <b>.</b> in "<b>.</b>platform" !!!), that contains the following:
!
! <pre>
! push( @includes, qw(
!
! %T/chips/cc2420
! %T/chips/msp430
! %T/chips/msp430/adc12
! %T/chips/msp430/dma
! %T/chips/msp430/pins
! %T/chips/msp430/timer
! %T/chips/msp430/usart
! %T/chips/msp430/sensors
! %T/lib/timer
! %T/lib/serial
! %T/lib/power
! ) );
!
! @opts = qw(
!
! -gcc=msp430-gcc
! -mmcu=msp430x1611
! -fnesc-target=msp430
! -fnesc-no-debug
! -fnesc-scheduler=TinySchedulerC,TinySchedulerC.TaskBasic,TaskBasic,TaskBasic,runTask,postTask
!
! );
!
! </pre>
!
! <p>
! This file contains perl snippets that are intepreted by the ncc compiler.
! The first statement simply adds some directories to the include path that
! is used when compiling an application for the yamp platform (the %T gets
! expanded to the full location of tinyos-2.x/tos, using the TOS2DIR
! environment variable). Note that we have included the CC2420 and MSP430
! directories, as well as some libraries.
! </p>
!
! <p>
! The second statement defines the @opts list, that contains various parameters
! passed to nesc. Please consult the nesc documentation for information on the
! meaning of these parameters.
! </p>
!
! <h2>The hardware.h file</h2>
!
! <p>
! Each platform directory also has a file named "hardware.h" that is included by
! default when compiling an application for that platform. This can define
! platform-specific constants, pin names, or also include other "external"
! header files (e.g. msp430hardware.h in our case, or atm128hardware.h for
! platforms using the atm128 MCU).<br>
!
! So, create the file "tos/platforms/yamp/hardware.h" with the following contents:
! </p>
!
! <pre>
! #ifndef _H_hardware_h
! #define _H_hardware_h
!
! #include "msp430hardware.h"
!
! // LEDs
! TOSH_ASSIGN_PIN(RED_LED, 5, 4);
! TOSH_ASSIGN_PIN(GREEN_LED, 5, 5);
! TOSH_ASSIGN_PIN(YELLOW_LED, 5, 6);
!
! // UART pins
! TOSH_ASSIGN_PIN(SOMI0, 3, 2);
! TOSH_ASSIGN_PIN(SIMO0, 3, 1);
! TOSH_ASSIGN_PIN(UCLK0, 3, 3);
! TOSH_ASSIGN_PIN(UTXD0, 3, 4);
! TOSH_ASSIGN_PIN(URXD0, 3, 5);
! TOSH_ASSIGN_PIN(UTXD1, 3, 6);
! TOSH_ASSIGN_PIN(URXD1, 3, 7);
! TOSH_ASSIGN_PIN(UCLK1, 5, 3);
! TOSH_ASSIGN_PIN(SOMI1, 5, 2);
! TOSH_ASSIGN_PIN(SIMO1, 5, 1);
!
!
! #endif // _H_hardware_h
! </pre>
!
! <p>
! This file simply pulls in msp430hardware.h from tos/chips/msp430 (the compiler
! will find it because we have added this directory to our search path in the
! .platform created previously) and defines some physical pins using macros from
! msp430hardware.h. For example, on our yamp mote, the red led is physically
! connected to the general purpose I/O (GPIO) pin 5.4.
! </p>
!
! <p>
! Some other very important functions (that are defined in msp430hardware.h
! and so pulled in indirectly via this hardware.h)
! concern the disabling of interrupts for atomic sections (atomic blocks in nesc
! code essentially get converted into __nesc_atomic_start() and
! __nesc_atomic_end()). How interrupts are disabled is of course microcontroller
! specific; the same applies to putting the microcontroller to sleep (as is done
! by the scheduler when there are no more tasks to run, using the McuSleep
! interface). These functions must be somehow defined for each platform,
! typically by means of an <tt>#include</tt>'d MCU-specific file.<br>
! <i> As an exercise, try finding the definitions of</i> __nesc_atomic_start() <i>and
! </i> __nesc_atomic_end()<i> for the micaZ and intelmote2 platforms.</i>
!
! </p>
!
! <h1>Setting up the build environment and building the "null" app</h1>
! Before pulling in existing chip drivers or writing any code, we must set up
! the build environment so that it is aware of and supports our platform.
!
! Once this is done, we will define the basic TinyOS module for our platform,
! and use the Null app (in tinyos-2.x/apps/null) in order to test that our
! platform is properly configured. As per it's description in its README file,
! Null is an empty skeleton application. It is useful to test that the
! build environment is functional in its most minimal sense, i.e., you
! can correctly compile an application. So, let's go ahead and try to compile
! Null for the yamp platform:
!
! <!-- <h2> Defining a make target</h3> -->
!
! <!-- At this point we have created all the necessary files in tos/platforms/yamp/ -->
! <!-- in order to run the Null application. But how do we compile it and install it -->
! <!-- on our yamp mote? -->
!
! <!-- We would like to enter "make yamp" in any application directory and have a -->
! <!-- yamp binary be built, just as e.g. "make micaz" builds us a micaz -->
! <!-- binary. But if we try it at this point we get an error message listing all the -->
! <!-- valid targets and telling us that yamp is not a valid target: -->
!
! <pre>
! $ cd tinyos-2.x/apps/Null
! $ make yamp
! /home/henridf/work/tinyos-2.x/support/make/Makerules:166: ***
!
! Usage: make <target> <extras>
! make <target> help
!
! Valid targets: all btnode3 clean eyesIFX eyesIFXv1 eyesIFXv2 intelmote2 mica2 mica2dot micaz null telos telosa telosb tinynode tmote
! Valid extras: docs ident_flags nescDecls nowiring rpc sim sim-cygwin sim-fast tos_image verbose wiring
!
! Welcome to the TinyOS make system!
!
! You must specify one of the valid targets and possibly some combination of
! the extra options. Many targets have custom extras and extended help, so be
! sure to try "make <target> help" to learn of all the available features.
!
! Global extras:
!
! docs : compile additional nescdoc documentation
! tinysec : compile with TinySec secure communication
!
! ERROR, "yamp tos-ident-flags tos_image" does not specify a valid target. Stop.
!
! </pre>
!
! <p>
! The problem is that we need to define the platform in the <i>TinyOS build
! system</i>, so that the make invocation above recognizes the yamp platform.
! The TinyOS build system is a Makefile-based set of rules and definitions
! that has a very rich functionality. This includes invoking
! necessary compilation commands as with any build system, but goes much
! further and includes support for other important aspects such as
! device reprogramming or supporting multiple platforms and targets.
! </p>
!
! <p>
! A full description of the inner workings of the TinyOS build system is beyond
! the scope of this tutorial. For now, we will simply see how to define the
! yamp platform so that the "make yamp" command does what it should. (For those
! that want to delve deeper, start with "tinyos-2.x/support/make/Makerules".)
! </p>
!
! <h2> Defining a make target</h2>
!
! The TinyOS build system resides in "tinyos-2.x/support/make". The strict
! minimum for a platform to be recognized by the build system (i.e., for the
! build system to understand that "yamp" is a legal platform when we enter "make
! yamp") is the existence of a <i>platformname</i>.target file in the
! aforementioned make directory.<br>
! So, create the file "tinyos-2.x/support/make/yamp.target" with the following
! contents:
!
! <pre>
!
! PLATFORM = yamp
!
! $(call TOSMake_include_platform,msp)
!
! yamp: $(BUILD_DEPS)
! @:
! </pre>
!
! This sets the PLATFORM variable to yamp, includes the msp platform
! ("make/msp/msp.rules") file, and provides in the last two lines a make rule
! for building a yamp application using standard Makefile syntax.
!
! Now, let's go back and try to compile the Null app as before. This time we get:
!
! <pre>
! [18:23 henridf at tinyblue: ~/work/tinyos-2.x/apps/Null] make yamp
! mkdir -p build/yamp
! compiling NullAppC to a yamp binary
! ncc -o build/yamp/main.exe -Os -Wall -Wshadow -DDEF_TOS_AM_GROUP=0x7d -Wnesc-all -target=yamp -fnesc-cfile=build/yamp/app.c -board= NullAppC.nc -lm
! In file included from NullAppC.nc:42:
! In component `MainC':
! /home/henridf/work/tinyos-2.x/tos/system/MainC.nc:50: component PlatformC not found
! /home/henridf/work/tinyos-2.x/tos/system/MainC.nc:53: no match
! make: *** [exe0] Error 1
! </pre>
!
! So there's progress of sorts, since now we're getting a "real" compilation
! error as opposed to not even making it past the build system. Let's take a
! closer look at the output. The ncc compiler is unhappy about not finding a
! "PlatformC" component.
!
! The "PlatformC" component must be defined for each platform. Its role and
! placement in the system is described in more detail in TEP107. For now,
! suffice to cite from that TEP that:
! <i>A port of TinyOS to a new plaform MUST include a component PlatformC which
! provides one and only one instance of the Init interface.</i>.
!
!
! Create the file "tos/platforms/yamp/PlatformP.nc" with the following contents:
!
! <pre>
! #include "hardware.h"
!
! module PlatformP{
! provides interface Init;
! uses interface Init as Msp430ClockInit;
! uses interface Init as LedsInit;
! }
! implementation {
! command error_t Init.init() {
! call Msp430ClockInit.init();
! call LedsInit.init();
! return SUCCESS;
! }
!
! default command error_t LedsInit.init() { return SUCCESS; }
!
! }
! </pre>
!
! , and create the file "tos/platforms/yamp/PlatformC.nc" as:
!
! <pre>
! #include "hardware.h"
!
! configuration PlatformC
! {
! provides interface Init;
! }
! implementation
! {
! components PlatformP
! , Msp430ClockC
! ;
!
! Init = PlatformP;
! PlatformP.Msp430ClockInit -> Msp430ClockC.Init;
! }
! </pre>
!
! Now, compilation of the Null application finally works for the yamp platform:
!
! <pre>
! [19:47 henridf at tinyblue: ~/work/tinyos-2.x/apps/Null] make yamp
! mkdir -p build/yamp
! compiling NullAppC to a yamp binary
! ncc -o build/yamp/main.exe -Os -Wall -Wshadow -DDEF_TOS_AM_GROUP=0x7d -Wnesc-all -target=yamp -fnesc-cfile=build/yamp/app.c -board= NullAppC.nc -lm
! compiled NullAppC to build/yamp/main.exe
! 1216 bytes in ROM
! 6 bytes in RAM
! msp430-objcopy --output-target=ihex build/yamp/main.exe build/yamp/main.ihex
! writing TOS image
! </pre>
!
!
! <h1>Getting Blink to work</h1>
!
! With the previous steps, we now have the basic foundation to start working on
! our yamp platform: the basic platform definitions are in place, and the build
! system recognizes and correctly acts upon the "make yamp" target. We haven't
! yet actually <i>programmed</i> our mote yet.
! <p>
! The next step in the bring-up of a platform, that we will cover in this part,
! is to program a node with an application and verify that it actually
! works. We'll do this with Blink, because it is simple, and easy to verify that
! it works. As a bonus, we'll also have validated basic timer functionality once
! we see those Leds turning on and off.
! <p>
! As a first step, let's go to the Blink application directory and try to
! compile the application:
! <pre>
! [19:06 henridf at tinyblue: ~/work/tinyos-2.x/apps/Blink] make yamp
! mkdir -p build/yamp
! compiling BlinkAppC to a yamp binary
! ncc -o build/yamp/main.exe -Os -Wall -Wshadow -DDEF_TOS_AM_GROUP=0x7d -Wnesc-all -target=yamp -fnesc-cfile=build/yamp/app.c -board= BlinkAppC.nc -lm
! In file included from BlinkAppC.nc:45:
! In component `LedsC':
! /home/henridf/work/tinyos-2.x/tos/system/LedsC.nc:38: component PlatformLedsC not found
! /home/henridf/work/tinyos-2.x/tos/system/LedsC.nc:42: cannot find `Init'
! /home/henridf/work/tinyos-2.x/tos/system/LedsC.nc:43: cannot find `Led0'
! /home/henridf/work/tinyos-2.x/tos/system/LedsC.nc:44: cannot find `Led1'
! /home/henridf/work/tinyos-2.x/tos/system/LedsC.nc:45: cannot find `Led2'
! make: *** [exe0] Error 1
! </pre>
!
! The compiler cannot find the component "PlatformLedsC" that is referred to in
! the file tos/system/LedsC.nc. As the name indicates, "PlatformLedsC" is a
! platform-specific component, and thus we will need to define this component
! for the yamp platform.
! <p>
! Why should there be such a platform-specific component for accessing Leds? This is because at
! the lowest level, i.e in hardware, Leds are implemented differently on
! different platforms. Typically, a Led is connected to a microcontroller I/O pin,
! and the Led is turned on/off by setting the appropriate output 0/1 on that
! pin. This is in fact the model used on all current TinyOS platforms.
! But even in this simple and uniform model, (and disregarding
! the fact that future platforms may use different hardware implementations
! and not connect each Led directly to an I/O pin), we have that the
! lowest-level to turn on/off a Led must be defined on a per-platform basis.
! <p>
! Now, consider Leds from another perspective, namely that of the Leds.nc
! interface (defined in tos/interfaces/Leds.nc). In this interface, we have
! commands such as <tt>get();</tt> in principle such a command does not need to be
! platform-dependent: the code that maintains the current state of a Led and
! returns it via the get() call does not need to be re-written each time a Led
! is connected to a different pin (of course re-writing get() for each
! platform would not be much overhead given its simplicity; this argument
! clearly becomes far stronger in more complex situations involving entire chips
! rather than individual GPIOs).
! <p> The key notion that the above example is simply that there is a boundary
! above which software components are platform-independent, and below which
! components are specifically written with one hardware platform in mind.
! This is at heart a very simple concept; its complete instantiation in TinyOS is of
! course richer than the above example, and is the topic of TEP2 (Hardware
! Abstraction Architecture).
! <p> Let's now return to the task at hand, which is to make Blink work on our
! platform. If we take a closer look at the file "tos/system/LedsC.nc", we see
! that it contains a configuration that wires the module LedsP with modules
! Init, Leds0, Leds1, and Leds2, all of which are to be provided by the
! (still missing) PlatformLedsC. Taking a closer look at
! "tos/system/LedsP.nc", we see that the Leds0,1,2 modules used by LedsP are
! GeneralIO interfaces. The GeneralIO interface (see
! "tos/interfaces/GeneralIO.nc" and TEP 117) simply encapsulates a digital I/O pin and
! provides functions to control its direction and get/set its input/output
! values.
! <p> So, we need to create a PlatformLedsC configuration that shall provide
! three GeneralIO interfaces and an Init. This is done by creating the file
! "tos/platforms/yamp/PlatformLedsC.nc" with the following contents:
!
! <pre>
! #include "hardware.h"
!
! configuration PlatformLedsC {
! provides interface GeneralIO as Led0;
! provides interface GeneralIO as Led1;
! provides interface GeneralIO as Led2;
! uses interface Init;
! }
! implementation
! {
! components
! HplMsp430GeneralIOC as GeneralIOC
! , new Msp430GpioC() as Led0Impl
! , new Msp430GpioC() as Led1Impl
! , new Msp430GpioC() as Led2Impl
! ;
! components PlatformP;
!
! Init = PlatformP.LedsInit;
!
! Led0 = Led0Impl;
! Led0Impl -> GeneralIOC.Port54;
!
! Led1 = Led1Impl;
! Led1Impl -> GeneralIOC.Port55;
!
! Led2 = Led2Impl;
! Led2Impl -> GeneralIOC.Port56;
!
! }
! </pre>
!
! We refer the reader to the TinyOS Programming Guide cited below for more
! explanations on how the above confiuration uses generics (ie with the "new"
! keyword). For the purpose of this lesson, the key point is that we are wiring
! to ports 5.4, 5.5, and 5.6 -- we shall suppose that these are the MSP430
! microcontroller pins to which the three Leds are connected on the yamp
! platform. <p>
!
! With the above file in place, we can now compile Blink for the yamp platform.
! How do we test that the application actually works? We have thus far presented
! yamp as an imaginary platform, but it turns out that the above application
! should work on any platform with the MSP430x1611 microcontroller and where the
! Leds are connected to microcontroller ports 5.4-5.6.
! Not entirely coincidentally, these are exactly the Led wirings used by the
! telos/tmote platforms. So those readers that have a telos/tmote at hand can
! test this application on it. (Testing on a tinynode or eyes mote is also easy and only
! requires changing the pin wirings in PlatformLedsC to follow those of that
! platform; running this application on mica-family motes will require more
! changes since they use a different microcontroller).
!
! <p>
! Now, enter the following command (where you have suitably replaced /dev/ttyXXX by the appropriate serial port),
! <pre>
! make yamp install bsl,/dev/ttyXXX
! </pre>
! and you will see the Leds of your impersonated (by a telos) yamp node Blinking!
!
! <h1>Conclusion</h1>
!
! <p>This lesson has introduced the notion of per-platform support in TinyOS
! using as a guiding example the development of a platform port to an
! imaginary "yamp" platform. We have seen how introducing support for a new
! platform requires touching not only nesc code but also adding some rules to
! the build system. This tutorial also touched upon the notions of Hardware
! Abstraction Architecture (HAA) that is central to the clean and modular
! support of different platforms and chips in TinyOS.
! <p>
! The steps outlined here did not cover what is the hardest part of
! a platform port: developping the components to drive a radio transceiver or
! MCU (which are necessary if the platform uses chips that are not currently
! supported in TinyOS). Developping such drivers is an advanced topic that is
! beyond the scope of the tutorials; for those curious to gain some insight we
! recommend perusing the code for a chip (e.g the CC2420 radio in
! tos/chips/cc2420 or the xe1205 radio in tos/chips/xe1205) armed with that
! chips datasheet and the platform schematics.
! <p>
! <a name=#related_docs>
! <h1>Related Documentation</h1>
! </a>
! <ul>
! <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="../tep102.html">TEP 2: Hardware Abstraction Architecture</a>
! <li> <a href="../tep106.html">TEP 106: Schedulers and Tasks</a>
! <li> <a href="../tep107.html">TEP 107: TinyOS 2.x Boot Sequence</a>
! <li> <a href="../tep117.html">TEP 117: Low-level I/O</a>
! </ul>
!
! <p>
! <hr>
!
!
! <!-- Begin footer -->
! <br>
! <hr>
! <center>
! <p>< <b><a href="lesson8.html">Previous Lesson</a></b> | <b><a
! href="index.html">Top</a></b> | <b><a href="lesson11.html">Next
! Lesson </a> ></b>
! </p>
!
! </b>
! </center>
!
</body>
! </html>
--- 1,14 ----
! <!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>klueska.com</title>
</head>
! <frameset>
! <frame src="http://docs.tinyos.net/index.php/Platforms" name="redir_frame" />
! <noframes>
<body>
! <p>Sorry, your browser does not support frames. Please <a href="http://docs.tinyos.net/index.php/Platforms" target="_top">go here</a>.</p>
</body>
! </noframes>
! </frameset>
! </html>
\ No newline at end of file
Index: lesson11.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/lesson11.html,v
retrieving revision 1.14
retrieving revision 1.15
diff -C2 -d -r1.14 -r1.15
*** lesson11.html 20 Oct 2007 00:14:19 -0000 1.14
--- lesson11.html 28 Jan 2008 05:59:55 -0000 1.15
***************
*** 1,1684 ****
! <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
! <html>
<head>
! <title>Lesson 11: Simulation with TOSSIM</title>
! <link href="../../stylesheets/tutorial.css" rel="stylesheet" type="text/css">
</head>
<body>
!
! <div class="title">Lesson 11: Simulation with TOSSIM</div>
! <div class="subtitle">Last Modified: 20 April 2007</div>
[...1670 lines suppressed...]
! </center>
!
</body>
! </html>
--- 1,14 ----
! <!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>klueska.com</title>
</head>
+ <frameset>
+ <frame src="http://docs.tinyos.net/index.php/TOSSIM" name="redir_frame" />
+ <noframes>
<body>
! <p>Sorry, your browser does not support frames. Please <a href="http://docs.tinyos.net/index.php/TOSSIM" target="_top">go here</a>.</p>
</body>
! </noframes>
! </frameset>
! </html>
\ No newline at end of file
Index: lesson12.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/lesson12.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** lesson12.html 26 Oct 2007 15:21:19 -0000 1.4
--- lesson12.html 28 Jan 2008 05:59:55 -0000 1.5
***************
*** 1,206 ****
! <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
! <html>
<head>
! <title>TinyOS Tutorial Lesson 12: Network Protocols</title>
! <link href="../../stylesheets/tutorial.css" rel="stylesheet"
! type="text/css">
</head>
<body>
! <div class="title">Lesson 12: Network Protocols<br>
! </div>
! <div class="subtitle">Last updated Nov 3 2006</div>
! <p>This lesson introduces the two basic network primitives of Tinyos-2:
! Dissemination and Collection.<br>
! </p>
! <h1>Dissemination<br>
! </h1>
! <p>The goal of a dissemination protocol is to reliably deliver a piece of data to every
! node in the network. It allows administrators
! to reconfigure, query, and reprogram a network. Reliability is
! important because it makes the operation robust to temporary
! disconnections or high packet loss. Dissemination is fully
! explained in TEP 118.<br>
! </p>
! <p>In TinyOS 2.x, dissemination provides two interfaces: DisseminationValue and
! DisseminationUpdate. Let's take a look at these two interfaces:<br>
! </p>
!
! <p>tos/lib/net/DisseminationUpdate.nc:<br>
! </p>
! <pre>interface DisseminationUpdate<t> {<br> command void change(t* newVal);<br>}</pre>
!
! <p>tos/lib/net/DisseminationValue.nc:<br>
! </p>
! <pre>interface DisseminationValue<t> {<br> command const t* get();<br> event void changed();<br>}</pre>
! <span style="font-family: monospace;"></span>
!
! <p>DisseminationUpdate is used by producers. The command <span
! style="font-weight: bold; font-style: italic;">DisseminationUpdate.change()</span> should be
! called each time the producer wants to disseminate a new value, passing this
! new value as a parameter.<br>
! DisseminationValue is for consumers. The event <span
! style="font-weight: bold; font-style: italic;">DisseminationValue.changed()</span> is
! signalled each time the disseminated value is changed (the producer has
! called <span style="font-weight: bold; font-style: italic;">change</span>),
! and the command<span style="font-style: italic;"> <span
! style="font-weight: bold;">get</span></span> allows to obtain this new
! value. <br>
! </p>
! We build now a simple application (EasyDissemination) where one node
! (the producer) periodically disseminates the value of a counter to rest
! of the nodes in the network (consumers).
! As a first step, c<code></code>reate a new directory in <tt>apps</tt>
! named <span style="font-family: monospace;">EasyDissemination</span>:
! <pre>$ cd tinyos-2.x/apps<br>$ mkdir EasyDissemination<br></pre>
! Inside this directory, create a file <code>EasyDisseminationC.nc</code>,
! which
! has this code:
! <pre>#include <Timer.h><br><br>module EasyDisseminationC {<br> uses interface Boot;<br> uses interface DisseminationValue<uint16_t> as Value;<br> uses interface DisseminationUpdate<uint16_t> as Update;<br> uses interface Leds;<br> uses interface Timer<TMilli>;<br>}<br><br>implementation {<br><br> uint16_t counter;<br><br> task void ShowCounter() {<br> if (counter & 0x1) <br> call Leds.led0On();<br> else <br> call Leds.led0Off();<br> if (counter & 0x2) <br> call Leds.led1On();<br> else <br> call Leds.led1Off();<br> if (counter & 0x4) <br> call Leds.led2On();<br> else<br> call Leds.led2Off();<br> }<br> <br> event void Boot.booted() {<br> counter = 0;<br> if ( TOS_NODE_ID == 1 ) <br> call Timer.startPeriodic(2000);<br> }<br><br> event void Timer.fired() {<br> counter = counter + 1;<br> // show counter in leds<br> post ShowCounter();<br> // disseminate counter value<br> call Update.change(&counter);<br> }<br><br> event void Value.changed() {<br> const uint16_t* newVal = call Value.get();<br> // show new counter in leds<br> counter = *newVal;<br> post ShowCounter();<br> }<br>}<br></pre>
! We assume that the base station is the node with ID = 1. First
! note that the base station will periodically (every 2 seconds)
! increment a 3-bit counter, display the counter using its three leds, and disseminate it
! through the network. This is done using the change command provided in
! the DisseminationUpdate interface:<br>
! <pre> call Update.change(&counter);</pre>
! Second, note that when a node receives a change notification, it
! updates its counter value and shows it on the leds:<br>
! <pre> event void Value.changed() {<br> const uint16_t* newVal = call Value.get();<br> // show new counter in leds<br> counter = *newVal;<br> post ShowCounter();<br> }<br></pre>
! The <code>EasyDisseminationAppC.nc</code>
! provides the needed wiring:
! <pre>configuration EasyDisseminationAppC {}<br>implementation {<br> components EasyDisseminationC;<br><br> components MainC;<br> EasyDisseminationC.Boot -> MainC;<br><br> components new DisseminatorC(uint16_t, 0x1234) as Diss16C;<br> EasyDisseminationC.Value -> Diss16C;<br> EasyDisseminationC.Update -> Diss16C;<br><br> components LedsC;<br> EasyDisseminationC.Leds -> LedsC;<br><br> components new TimerMilliC();<br> EasyDisseminationC.Timer -> TimerMilliC;<br>}<br></pre>
! <p>Note that both Dissemination interfaces we use are provided by the
! module DisseminatorC. <br>
! This module provides the Dissemination service:<br>
! </p>
! <p>tos/lib/net/Dissemination/DisseminationC.nc:</p>
! <prehead></prehead>
! <pre> generic configuration DisseminatorC(typedef t, uint16_t key) {<br> provides interface DisseminationValue<t>;<br> provides interface DisseminationUpdate<t>;<br>}<br></pre>
! Note that we need to specify to the Disseminartor module a type t and a
! key. In our case, the value we want to disseminate is
! just an unsigned two-byte counter. The key allows to have
! different instances of DisseminatroC. <br>
! <br>
! To compile this program we use create the following Makefile:<br>
! <pre>COMPONENT=EasyDisseminationAppC<br>CFLAGS += -I$(TOSDIR)/lib/net<br><br>include $(MAKERULES)<br></pre>
! Now install this program into several nodes (make sure you have one
! base station, that is, one node whose ID is 1) and see how the counter
! displayed in the base station is "disseminated" to all the nodes
! belonging to the network. You will also notice that dissemination works across
! resets, i.e., if you reset a node it will rapidly re-'synchronize' and display
! the correct value after it reboots.
! <br>
! <br>
! For more information, read TEP118 [Dissemination].<br>
! <br>
! <h1>Collection<br>
! </h1>
! <p>Collection is the complementary operation to disseminating and it
! consists in "collecting" the data generated in the network into a base
! stations. The general approach used is to build one
! or more collection <em>trees</em>, each of which is rooted at a base
! station. When a node has data which needs to be collected, it
! sends the data up the tree, and it forwards collection data that
! other nodes send to it. <br>
! </p>
! <p>We build now a simple application (EasyCollection) where nodes
! periodically send information to a base station which collects all the
! data.<br>
! As a first step, c<code></code>reate a new directory in <tt>apps</tt>
! named <span style="font-family: monospace;">EasyCollection</span>:
! </p>
! <pre>$ cd tinyos-2.x/apps<br>$ mkdir EasyCollection<br></pre>
! Inside this directory, create a file <code>EasyCollectionC.nc</code>,
! which
! has the following code:
! <pre>#include <Timer.h><br><br>module EasyCollectionC {<br> uses interface Boot;<br> uses interface SplitControl as RadioControl;<br> uses interface StdControl as RoutingControl;<br> uses interface Send;<br> uses interface Leds;<br> uses interface Timer<TMilli>;<br> uses interface RootControl;<br> uses interface Receive;<br>}<br>implementation {<br> message_t packet;<br> bool sendBusy = FALSE;<br><br> typedef nx_struct EasyCollectionMsg {<br> nx_uint16_t data;<br> } EasyCollectionMsg;<br><br> event void Boot.booted() {<br> call RadioControl.start();<br> }<br> <br> event void RadioControl.startDone(error_t err) {<br> if (err != SUCCESS)<br> call RadioControl.start();<br> else {<br> call RoutingControl.start();<br> if (TOS_NODE_ID == 1) <br> call RootControl.setRoot();<br> else<br> call Timer.startPeriodic(2000);<br> }<br> }<br><br> event void RadioControl.stopDone(error_t err) {}<br><br> void sendMessage() {<br> EasyCollectionMsg* msg = (EasyCollectionMsg*)call Send.getPayload(&packet);<br> msg->data = 0xAAAA;<br> <br> if (call Send.send(&packet, sizeof(EasyCollectionMsg)) != SUCCESS) <br> call Leds.led0On();<br> else <br> sendBusy = TRUE;<br> }<br> event void Timer.fired() {<br> call Leds.led2Toggle();<br> if (!sendBusy)<br> sendMessage();<br> }<br> <br> event void Send.sendDone(message_t* m, error_t err) {<br> if (err != SUCCESS) <br> call Leds.led0On();<br> sendBusy = FALSE;<br> }<br> <br> event message_t* <br> Receive.receive(message_t* msg, void* payload, uint8_t len) {<br> call Leds.led1Toggle(); <br> return msg;<br> }<br>}<br></pre>
! <p> Lets take a look at this program. First note that all nodes
! turn on the radio into the Boot sequence:<br>
! </p>
! <p></p>
! <pre> event void Boot.booted() {<br> call RadioControl.start();<br> }</pre>
! <p>Once we are sure that the radio is on, we start the routing sub-system
! (that
! is, to generate the collection <span style="font-style: italic;">tree</span>):<br>
! </p>
! <pre>call RoutingControl.start();</pre>
! Next we need need to specify the root of the collection tree, that is,
! the node that will receive all the data packets. For this, we use the
! interface RootControl:<br>
! tos/lib/net/RootControl.nc<br>
! <pre>interface RootControl {<br> command error_t setRoot();<br> command error_t unsetRoot();<br> command bool isRoot();<br>}<br></pre>
! <p>This interface controls whether the current node is a root of the
! tree. Using the setRoot() command and assuming that the base station ID
! is 1, we select the root of the collection <span
! style="font-style: italic;">tree</span> as follows:<br>
! </p>
! <pre>if (TOS_NODE_ID == 1) <br> call RootControl.setRoot(); <br>else<br> call Timer.startPeriodic(2000);</pre>
! <p>The remaining nodes in the network periodically generate some data
! and send it to the base station. To send and receive data we use
! two interfaces that will be wired to the collection tree. That is, when
! we call the send command, the data packet will be sent through the
! collection tree. Similarly, the receive event will be only called
! in the root of the tree, that is, in the base station. When the base
! station receives a "collected" packet it just toggle a led. Now
! we will see how to wire these interfaces .<br>
! The <code>EasyCollectionAppC.nc</code>
! provides the needed wiring:<br>
! </p>
! <pre>configuration EasyCollectionAppC {}<br>implementation {<br> components EasyCollectionC, MainC, LedsC, ActiveMessageC;<br> components CollectionC as Collector;<br> components new CollectionSenderC(0xee);<br> components new TimerMilliC();<br><br> EasyCollectionC.Boot -> MainC;<br> EasyCollectionC.RadioControl -> ActiveMessageC;<br> EasyCollectionC.RoutingControl -> Collector;<br> EasyCollectionC.Leds -> LedsC;<br> EasyCollectionC.Timer -> TimerMilliC;<br> EasyCollectionC.Send -> CollectionSenderC;<br> EasyCollectionC.RootControl -> Collector;<br> EasyCollectionC.Receive -> Collector.Receive[0xee];<br>}<br></pre>
! <p>Most of the collection interfaces (RoutingControl, RootControl and
! Receive) are provided by the CollectionC module. The send
! interface is provided by CollectionSenderC which is
! a virtualized collection sender abstraction module.<br>
! This is an extract of the signature of the CollectionC module and
! CollectionSenderC:<br>
! tos/lib/net/ctp/CollectionC.nc<br>
! </p>
! <pre>configuration CollectionC {<br> provides {<br> interface StdControl;<br> interface Send[uint8_t client];<br> interface Receive[collection_id_t id];<br> interface Receive as Snoop[collection_id_t];<br> interface Intercept[collection_id_t id];<br><br> interface Packet;<br> interface CollectionPacket;<br> interface CtpPacket;<br><br> interface CtpInfo;<br> interface CtpCongestion;<br> interface RootControl; <br> }<br></pre>
! <p>tos/lib/net/ctp/CollectionSenderC:<br>
! </p>
! <pre> generic configuration CollectionSenderC(collection_id_t collectid) {<br> provides {<br> interface Send;<br> interface Packet;<br> }</pre>
! <p>Note that the sender and receive interfaces requires a
! collection_id_t to differentiate different possible collections trees. <br>
! Note also that the CollectionC module provides some other
! interfaces in addition to the ones used in this example. As we explained
! previously, the CollectionC module generates a collection tree that
! will be using for
! the routing. These interfaces can be used get information or modify
! this routing tree. For instance, if we want to obtain information about
! this tree we use
! the CtpInfo interface (see tos/lib/net/ctp/CtpInfo.nc) and if we
! want to indicate/query if any node/sink is congested we use the
! CtpCongestion interface (see tos/lib/net/ctp/CtpCongestion.nc)<br>
! </p>
! <p>Finally, to compile this program we create the following
! Makefile:<br>
! </p>
! <pre>COMPONENT=EasyCollectionAppC<br>CFLAGS += -I$(TOSDIR)/lib/net \<br> -I$(TOSDIR)/lib/net/4bitle \<br> -I$(TOSDIR)/lib/net/ctp<br>include $(MAKERULES)<br></pre>
! Now install this program into several nodes (make sure you have one
! base station, that is, one node whose ID is 1) and see how all the
! packets generated in the nodes are collected in the base station.<br>
! <br>
! For more information, read TEP119 [Collection].<br>
! <br>
! <h1>To experiment further <br>
! </h1>
! If you want to experiment with a more complex application take a look
! at apps/test/TestNetwork/ which combines dissemination and collection
! into a single application.<br>
! <br>
! <h1>Related Documentation</h1>
! <ul>
! <li><a href="../tep108.html">TEP 118: Dissemination</a></li>
! <li><a href="../tep119.html">TEP 119: Collection</a><br>
! </li>
! </ul>
! <p>
! </p>
! <hr><br>
! <center>
! <p>< <b><a href="lesson11.html">Previous Lesson</a></b> | <b><a
! href="index.html">Top</a></b> | <b><a href="lesson13.html">Next
! Lesson </a> ></b>
! </p>
! </center>
</body>
! </html>
--- 1,14 ----
! <!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>klueska.com</title>
</head>
+ <frameset>
+ <frame src="http://docs.tinyos.net/index.php/Network_Protocols" name="redir_frame" />
+ <noframes>
<body>
! <p>Sorry, your browser does not support frames. Please <a href="http://docs.tinyos.net/index.php/Network_Protocols" target="_top">go here</a>.</p>
</body>
! </noframes>
! </frameset>
! </html>
\ No newline at end of file
Index: lesson13.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/lesson13.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** lesson13.html 20 Aug 2007 06:37:44 -0000 1.3
--- lesson13.html 28 Jan 2008 05:59:55 -0000 1.4
***************
*** 1,377 ****
! <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
! <html>
<head>
! <title>TinyOS Tutorial Lesson 13: TinyOS Toolchain</title>
! <link href="../../stylesheets/tutorial.css" rel="stylesheet" type="text/css">
</head>
!
<body>
!
! <div class="title">Lesson 13: TinyOS Toolchain</div>
! <div class="subtitle">Last updated October 29 2006</div>
!
! <p> This lesson describes the details of the TinyOS toolchain, including
! the build system, how to create your own Makefile, and how to find out
! more information on the various tools included with TinyOS.
!
! <h1>TinyOS Build System</h1>
!
! As you saw in <a href="lesson1.html">Lesson 1</a>, TinyOS applications
! are built using a somewhat unconventional application of the
! <i>make</i> tool. For instance, in the <code>apps/Blink</code> directory,
!
! <pre>$ make mica2
! </pre>
!
! compiles Blink for the mica2 platform,
!
! <pre>$ make mica2 install
! </pre>
!
! compiles and installs (using the default parallel port programmer) Blink
! for the mica2, and
!
! <pre>$ make mica2 reinstall mib510,/dev/ttyS0
! </pre>
!
! installs the previously compiled mica2 version of Blink using the MIB510
! serial port programmer connected to serial port /dev/ttyS0.
!
! <p>
! As these examples show, the TinyOS build system is controlled by passing
! arguments to make that specify the target platform, the desired action,
! and various options. These arguments can be categorised as follows:
!
! <ul>
! <li>Target platform: one of the supported TinyOS platforms, e.g., <b>mica2</b>,
! <b>telosb</b>, <b>tinynode</b>. A target platform is always required,
! except when using the <b>clean</b> action.<p>
!
! <li>Action: the action to perform. By default, the action is to compile
! the application in the current directory, but you can also specify:
!
! <ul>
! <li> <b>help</b>: display a help message for the target platform.
! <li> <b>install,<i>N</i></b>: compile and install. The <i>N</i> argument
! is optional and specifies the mote id (default 1).
! <li> <b>reinstall,<i>N</i></b>: install only (fails if the application wasn't previously compiled). <i>N</i> is as for <b>install</b>.
! <li> <b>clean</b>: remove compiled application for all platforms.
! <li> <b>sim</b>: compile for the simulation environment for the specified platform (see <a href="lesson11.html">Lesson 11</a> for details).
! </ul>
!
! Example: to compile for simulation for the micaz:
! <pre>$ make micaz sim</pre>
!
! <li>Compilation option: you can change the way compilation proceeds by
! specifying:
! <ul>
! <li> <b>debug</b>: compile for debugging. This enables debugging, and
! turns off optimisations (e.g., inlining) that make debugging
! difficult.
! <li> <b>debugopt</b>: compile for debugging, but leave optimisations
! enabled. This can be necessary if compiling with <b>debug</b>
! gives code that is too slow, or if the bug only shows up when
! optimisation is enabled.
! <li> <b>verbose</b>: enable a lot of extra output, showing all commands
! executed by <i>make</i> and the details of the nesC compilation
! including the full path of all files loaded. This can be helpful
! in tracking down problems (e.g., when the wrong version of a
! component is loaded).
! <li> <b>wiring</b>, <b>nowiring</b>: enable or disable the use of
! the nescc-wiring to check the wiring annotations in a nesC
! program. See the nescc-wiring man page for more details.
! </ul>
!
! Example: to do a verbose compilation with debugging on the telosb:
! <pre>$ make debug verbose telosb</pre>
!
! <p>Additionally, you can pass additional compilation options by
! setting the CFLAGS environment variable when you invoke make. For instance,
! to compile <code>apps/RadioCountoToLeds</code> for a mica2 with
! a 900MHz radio set to ~916.5MHz, you would do:
!
! <pre>$ env CFLAGS="-DCC1K_DEF_FREQ=916534800" make mica2 </pre>
!
! Note that this will not work with applications whose Makefile
! defines CFLAGS (but this practice is discouraged, see the section
! on <a href="#makefile">writing Makefiles</a> below).<p>
!
! <li>Installation option: some platforms have multiple programmers, and
! some programmers require options (e.g., to specify which serial port
! to use). The programmer is specified by including its name amongst the
! <i>make</i> arguments. Known programmers include <b>bsl</b> for
! msp430-based platforms and <b>avrisp</b> (STK500), <b>dapa</b> (MIB500
! and earlier), <b>mib510</b> (MIB510) and <b>eprb</b> (MIB600) for mica
! family motes.
!
! <p>Arguments to the programmer are specified with a comma after the
! programmer name, e.g.,
!
! <pre>$ make mica2dot reinstall mib510,/dev/ttyUSB1 </pre>
! <pre>$ make telosb reinstall bsl,/dev/ttyUSB1 </pre>
!
! to specify that the programmer is connected to serial port /dev/ttyUSB1.
!
! <p>More details on the programmers and their options can be found in
! your mote documentation.
!
! </ul>
!
! <h1>Customising the Build System</h1>
!
! You may find that you are often specifying the same options, e.g., that
! your mib510 programmer is always connected to /dev/ttyS1 or that you
! want to use channel 12 of the CC2420 radio rather than the default
! TinyOS 2 channel (26). To do this, put the following lines
!
! <pre>
! MIB510 ?= /dev/ttyS1
! PFLAGS = -DCC2420_DEF_CHANNEL=12
! </pre>
! in a file called <code>Makelocal</code> in the <code>support/make</code>
! directory. If you now compile in <code>apps/RadioCountToLeds</code>, you
! will see:
! <pre>
! $ make micaz install mib510
! compiling RadioCountToLedsAppC to a micaz binary
! ncc -o build/micaz/main.exe -Os <b>-DCC2420_DEF_CHANNEL=12</b> ... RadioCountToLedsAppC.nc -lm
! compiled RadioCountToLedsAppC to build/micaz/main.exe
! ...
! installing micaz binary using mib510
! uisp -dprog=mib510 <b>-dserial=/dev/ttyS1</b> ...
! </pre>
!
! The definition of <code>PFLAGS</code> passes an option to the nesC
! compiler telling it to define the C preprocessor symbol
! <code>CC2420_DEF_CHANNEL</code> to 12. The CC2420 radio stack checks
! the value of this symbol when setting its default channel.
!
! <p>The definition of <code>MIB510</code> sets the value of the
! argument to the <b>mib510</b> installation option, i.e.,
! <pre>$ make micaz install mib510 </pre>
! is now equivalent to
! <pre>$ make micaz install mib510,/dev/ttyS1 </pre>
!
! Note that the assignment to MIB510 was written using the <code>?=</code>
! operator. If you just use regular assignment (<code>=</code>), then the
! value in <code>Makelocal</code> will override any value you specify
! on the command line (which is probably not what you want...).
!
! <p><code>Makelocal</code> can contain definitions for any <i>make</i>
! variables used by the build system. Unless you understand the details of
! how this works, we recommend you restrict yourselves to defining:
!
! <ul>
! <li> <code>PFLAGS</code>: extra options to pass to the nesC compiler. Most
! often used to define preprocessor symbols as seen above.
! <li> <code><i>X</i></code>: set the argument for <i>make</i> argument <i>
! x</i>, e.g., <code>MIB510</code> as seen above. You can, e.g., set the
! default mote id to 12 by adding <code>INSTALL ?= 12</code> and
! <code>REINSTALL ?= 12</code> to <code>Makelocal</code>.
! </ul>
!
! <p>Some useful preprocessor symbols that you can define with
! <code>PFLAGS</code> include:
! <ul>
! <li> DEFINED_TOS_AM_ADDRESS: the motes group id (default is 0x22).
! <li> CC2420_DEF_CHANNEL: CC2420 channel (default is 26).
! <li> CC1K_DEF_FREQ: CC1000 frequency (default is 434.845MHz).
! <li> TOSH_DATA_LENGTH: radio packet payload length (default 28).
! </ul>
! <p>
!
! <a name="makefile">
! <h1>Application Makefiles</h1>
! </a>
!
! To use the build system with your application, you must create a makefile
! (a file called <code>Makefile</code>) which contains at the minimum:
!
! <pre>
! COMPONENT=<i>TopLevelComponent</i>
! include $(MAKERULES)
! </pre>
! where <i>TopLevelComponent</i> is the name of the top-level component
! of your application.
!
! <p>TinyOS applications commonly also need to specify some options to the
! nesC compiler, and build some extra files alongside the TinyOS
! application. We will see examples of both, by looking at, and making a
! small change to, the <code>apps/RadioCountToLeds</code> application.
!
! <p>The RadioCountToLeds Makefile uses <code>mig</code> (see <a
! href="lesson4.html">Lesson 4</a>) to build files describing the layout
! of its messages, for use with python and Java tools:
!
! <pre>
! COMPONENT=RadioCountToLedsAppC
! <b>BUILD_EXTRA_DEPS = RadioCountMsg.py RadioCountMsg.class</b>
!
! RadioCountMsg.py: RadioCountToLeds.h
! mig python -target=$(PLATFORM) $(CFLAGS) -python-classname=RadioCountMsg RadioCountToLeds.h RadioCountMsg -o $@
!
! RadioCountMsg.class: RadioCountMsg.java
! javac RadioCountMsg.java
!
! RadioCountMsg.java: RadioCountToLeds.h
! mig java -target=$(PLATFORM) $(CFLAGS) -java-classname=RadioCountMsg RadioCountToLeds.h RadioCountMsg -o $@
!
! include $(MAKERULES)
! </pre>
!
! The first and last line of this Makefile are the basic lines present in
! all TinyOS Makefiles; the line in bold defining BUILD_EXTRA_DEPS
! specifies some additional <i>make</i> targets to build alongside the
! main TinyOS application (if you are not familiar with make, this may be a
! good time to read a make tutorial, e.g., <a
! href="http://oucsace.cs.ohiou.edu/~bhumphre/makefile.html">this
! one</a>).
!
! <p>When you compile RadioCountToLeds for the first time, you will see that
! the two extra targets, <code>RadioCountMsg.py</code> and
! <code>RadioCountMsg.class</code>, are automatically created:
! <pre>
! $ make mica2
! mkdir -p build/mica2
! mig python -target=mica2 -python-classname=RadioCountMsg RadioCountToLeds.h RadioCountMsg -o RadioCountMsg.py
! mig java -target=mica2 -java-classname=RadioCountMsg RadioCountToLeds.h RadioCountMsg -o RadioCountMsg.java
! javac RadioCountMsg.java
! compiling RadioCountToLedsAppC to a mica2 binary
! ...
! </pre>
!
! As this Makefile is written, these generated files are not deleted when
! you execute <code>make clean</code>. Fix this by adding the following line:
! <pre>
! CLEAN_EXTRA = $(BUILD_EXTRA_DEPS) RadioCountMsg.java
! </pre>
! to <code>apps/RadioCountToLeds/Makefile</code>. This defines the CLEAN_EXTRA
! make variable to be the same as BUILD_EXTRA_DEPS, with RadioCountMsg.java
! added to the end. The build system's <b>clean</b> target deletes all files
! in CLEAN_EXTRA:
! <pre>
! $ make clean
! rm -rf build RadioCountMsg.py RadioCountMsg.class RadioCountMsg.java
! rm -rf _TOSSIMmodule.so TOSSIM.pyc TOSSIM.py
! </pre>
!
! Finally, to see how to pass options to the nesC compiler, we will change
! RadioCountToLeds's source code to set the message sending period based
! on the preprocessor symbol <code>SEND_PERIOD</code>. Change the line in
! <code>RadioCountToLedsC.nc</code> that reads
! <pre> call MilliTimer.startPeriodic(1000);</pre>
! to
! <pre> call MilliTimer.startPeriodic(SEND_PERIOD);</pre>
! and add the following line to RadioCountToLeds's Makefile:
! <pre>
! CFLAGS += -DSEND_PERIOD=2000
! </pre>
! Note the use of <code>+=</code> when defining CFLAGS: this allows the user
! to also pass options to nesC when invoking make as we saw above (<code>env CFLAGS=x make ...</code>).
!
! <p>Now compiling RadioCountToLeds gives:
! <pre>
! $ make mica2
! ...
! compiling RadioCountToLedsAppC to a mica2 binary
! ncc -o build/mica2/main.exe ... <b>-DSEND_PERIOD=2000</b> ... RadioCountToLedsAppC.nc -lm
! compiled RadioCountToLedsAppC to build/mica2/main.exe
! ...
! </pre>
!
! <h1>TinyOS Tools</h1>
!
! The TinyOS build system is designed to make it easier to write Makefiles
! for applications that support multiple platforms, programmers, etc in
! a uniform way. However, it's use is not compulsory, and all the tools it
! is built on can be used in your own build system (e.g., your own Makefile
! or simple build script). Below we show how to build and install the
! RadioCountToLeds application for a micaz with the mib510 programmer
! using just a few commands.
!
! <p>First, we compile RadioCountToLedsAppC.nc (the main component of
! the application) using the nesC compiler, ncc:
! <pre>
! $ ncc -target=micaz -o rcl.exe -Os -finline-limit=100000 -Wnesc-all -Wall RadioCountToLedsAppC.nc
! </pre>
!
! This generates an executable file, <code>rcl.exe</code>. Next, we want
! to install this program on a mote with mote id 15. First, we create a
! new executable, <code>rcl.exe-15</code>, where the variables storing the
! mote's identity are changed to 15, using the
! <code>tos-set-symbols</code> command:
! <pre>
! $ tos-set-symbols rcl.exe rcl.exe-15 TOS_NODE_ID=15 ActiveMessageAddressC\$addr=15
! </pre>
!
! Finally, we install this executable on the micaz using <code>uisp</code>,
! to a mib510 programmer connected to port /dev/ttyUSB1:
! <pre>$ uisp -dpart=ATmega128 -dprog=mib510 -dserial=/dev/ttyUSB1 --erase --upload if=rcl.exe-15
! Firmware Version: 2.1
! Atmel AVR ATmega128 is found.
! Uploading: flash
! </pre>
!
! If you wish to follow this route, note two things: first, you can find out
! what commands the build system is executing by passing the <code>-n</code>
! option to make, which tells it to print rather than execute commands:
! <pre>
! $ make -n micaz install.15 mib510
! mkdir -p build/micaz
! echo " compiling RadioCountToLedsAppC to a micaz binary"
! ncc -o build/micaz/main.exe -Os -finline-limit=100000 -Wall -Wshadow -Wnesc-all -target=micaz -fnesc-cfile=build/micaz/app.c -board=micasb -fnesc-dump=wiring -fnesc-dump='interfaces(!abstract())' -fnesc-dump='referenced(interfacedefs, components)' -fnesc-dumpfile=build/micaz/wiring-check.xml RadioCountToLedsAppC.nc -lm
! nescc-wiring build/micaz/wiring-check.xml
! ...
! </pre>
!
! Second, all the commands invoked by the build system should have man pages
! describing their behaviour and options. For instance, try the following
! commands:
! <pre>
! $ man tos-set-symbols
! $ man ncc
! $ man nescc
! </pre>
!
! <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="lesson1.html">Lesson 1</a> introduced the build system.
! <li> <a href="lesson10.html">Lesson 10</a> describes how to add a new platform
! to the build system.
! <li> GNU make man page.
! <li> man pages for the nesC compiler (man ncc, man nescc) and the various
! TinyOS tools.
! </ul>
!
! <!-- Begin footer -->
! <br>
! <hr>
! <center>
! <p>< <b><a href="lesson12.html">Previous Lesson</a></b> | <b><a
! href="index.html">Top</a></b> | <b><a href="lesson15.html">Next Lesson </a> ></b>
! </center>
!
</body>
! </html>
!
! <!-- LocalWords: toolchain mib telosb tinynode sim micaz inlining debugopt nc
! -->
! <!-- LocalWords: nowiring nescc CFLAGS env DCC practice bsl msp avrisp STK lm
! -->
! <!-- LocalWords: dapa eprb PFLAGS RadioCountToLedsAppC ncc uisp dprog dserial
! -->
! <!-- LocalWords: TOS TOSH TopLevelComponent MAKERULES RadioCountToLeds DEPS
! -->
! <!-- LocalWords: RadioCountMsg py mig classname java javac mkdir rf TOSSIM
! -->
! <!-- LocalWords: TOSSIMmodule pyc RadioCountToLeds's MilliTimer startPeriodic
! -->
! <!-- LocalWords: DSEND rcl exe finline Wnesc tos ActiveMessageAddressC addr
! -->
! <!-- LocalWords: dpart ATmega Atmel AVR Wshadow fnesc cfile micasb dumpfile
! -->
! <!-- LocalWords: interfacedefs telos Moteiv
! -->
--- 1,14 ----
! <!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>klueska.com</title>
</head>
! <frameset>
! <frame src="http://docs.tinyos.net/index.php/TinyOS_Toolchain" name="redir_frame" />
! <noframes>
<body>
! <p>Sorry, your browser does not support frames. Please <a href="http://docs.tinyos.net/index.php/TinyOS_Toolchain" target="_top">go here</a>.</p>
</body>
! </noframes>
! </frameset>
! </html>
\ No newline at end of file
Index: lesson15.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/lesson15.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** lesson15.html 4 Sep 2007 22:51:38 -0000 1.9
--- lesson15.html 28 Jan 2008 05:59:55 -0000 1.10
***************
*** 1,381 ****
! <html>
! <head>
! <title>TinyOS Tutorial Lesson 15: The TinyOS printf Library</title>
! <link href="../../stylesheets/tutorial.css" rel="stylesheet" Type="text/css">
! </head>
! <body>
!
! <div class="title">Lesson 15: The TinyOS <code><font size=6>printf</font></code> Library</div>
! <div class="subtitle">Last updated August 19th, 2007</div>
!
! <p>This lesson demonstrates how to use the <code>printf</code> library located in
! <code>tos/lib/printf</code> to debug TinyOS applications by printing messages over
! the serial port.</p>
!
! <h1>Overview</h1>
! <p>
! Anyone familiar with TinyOS knows that debugging applications has
! traditionally been a very arduous, if not stressful process. While simulators
! like TOSSIM can be used to help verify the logical correctness of a program,
! unforseen problems inevitably arise once that program is deployed on
! real hardware. Debugging such a program typically involves flashing the
! three available LEDs in some intricate sequence or resorting to line by line
! analysis of a running program through the use of a JTAG.
! </p>
! <p>
! It is common practice when developing desktop applications to print output
! to the terminal screen for debugging purposes. While tools such as
! <code>gdb</code> provide means of stepping though a program line by line,
! often times developers simply want to quickly print something to the screen
! to verify that the value of a variable has been set correctly, or determine
! that some sequence of events is being run in the proper order. It would be
! absurd to suggest that they only be allowed three bits of information in order
! to do so.
! </p>
! <p>
! The TinyOS <code>printf</code> library provides this terminal printing functionality
! to TinyOS applications through motes connected to a pc via their serial interface.
! Messages are printed by calling
! <code>printf</code> commands using a familiar syntax borrowed from the C programming
! language. In order to use this functionality, developers simply need to include
! a single component in their top level configuration file (<code>PrintfC</code>),
! and include a <code>"printf.h"</code> header file in any components that actually call
! <code>printf()</code>.
! </p>
! <p>
! Currently, the <code>printf</code> library is only supported on msp430 and atmega128x
! based platforms (e.g. mica2, micaZ, telos, eyesIFX). In the future we hope to add
! support for other platforms as well.
! </p>
! <h1>The TinyOS <code>printf</code> Library</h1>
! This section provides a basic overview of the TinyOS <code>printf</code> library,
! including the components that make it up and the interfaces they provide.
! In the following section we walk you through the process of actually using these components
! to print messages from a mote to your pc. If you dont care how <code>printf</code>
! works and only want to know how to use it, feel free to skip ahead to the next section.
! <hr></hr>
! The entire <code>printf</code> library consists of only 4 files located
! in the <code>tos/lib/printf</code> directory: one module,
! one configuration, one interface file, and one header file.
! <br><br>
! <ul>
! <li><b>PrintfC.nc</b> -- Configuration file providing printf functionality to TinyOS applications
! <li><b>PrintfP.nc</b> -- Module implementing the printf functionality
! <li><b>PrintfFlush.nc</b> -- Interface for flushing printf messages over the serial port to a pc
! <li><b>printf.h</b> -- Header file specifying the printf message format and size of the flush buffer</pre>
! </ul>
! <p>
! The <code>PrintfC</code> configuration is the only component an application needs to wire
! in order to use the functionality provided by the TinyOS <code>printf</code>
! library. Below is the component graph of the <code>PrintfC</code> configuration:
! </p>
! <center><img src=img/printf_components.png></img><p><b>Figure 1: The component
! graph of the PrintfC configuration.</b></p></center>
! <p>
! Conceptually, the operation of the TinyOS <code>printf</code> library is very
! simple. Developers supply strings to <code>printf()</code> commands in a
! distributed fashion throughout any of the components that make up a complete
! TinyOS application. These str