[Tinyos-2-commits] CVS: tinyos-2.x/doc/html/tutorial lesson13.html,
NONE, 1.1.2.1 index.html, 1.1.2.11, 1.1.2.12 lesson1.html,
1.1.2.17, 1.1.2.18 lesson11.html, 1.1.2.2, 1.1.2.3
David Gay
idgay at users.sourceforge.net
Sun Oct 29 17:33:28 PST 2006
Update of /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv16912
Modified Files:
Tag: tinyos-2_0_devel-BRANCH
index.html lesson1.html lesson11.html
Added Files:
Tag: tinyos-2_0_devel-BRANCH
lesson13.html
Log Message:
toolchain overview
--- NEW FILE: lesson13.html ---
<!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>
</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
-->
Index: index.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/index.html,v
retrieving revision 1.1.2.11
retrieving revision 1.1.2.12
diff -C2 -d -r1.1.2.11 -r1.1.2.12
*** index.html 27 Oct 2006 22:52:29 -0000 1.1.2.11
--- index.html 30 Oct 2006 01:33:26 -0000 1.1.2.12
***************
*** 106,112 ****
<dd> Lesson 13 describes the details of the TinyOS toolchain, including
! the message interface generator (<tt>mig</tt>), the nesC constant
! generator (<tt>ncg</tt>), and how they can be used through Java,
! Python, or C.
</dd>
--- 106,111 ----
<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>
Index: lesson1.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/lesson1.html,v
retrieving revision 1.1.2.17
retrieving revision 1.1.2.18
diff -C2 -d -r1.1.2.17 -r1.1.2.18
*** lesson1.html 28 Jun 2006 15:27:12 -0000 1.1.2.17
--- lesson1.html 30 Oct 2006 01:33:26 -0000 1.1.2.18
***************
*** 230,234 ****
<p>Type:
! <pre>make mica2 reinstall mib510 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
--- 230,234 ----
<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
***************
*** 454,457 ****
--- 454,460 ----
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>
Index: lesson11.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/lesson11.html,v
retrieving revision 1.1.2.2
retrieving revision 1.1.2.3
diff -C2 -d -r1.1.2.2 -r1.1.2.3
*** lesson11.html 19 Jun 2006 00:20:06 -0000 1.1.2.2
--- lesson11.html 30 Oct 2006 01:33:26 -0000 1.1.2.3
***************
*** 1358,1362 ****
! <p><b><a href="lesson5.html">< Previous Lesson</a></b> | <b><a
href="index.html">Top</a></b>
--- 1358,1365 ----
! <p><b><a href="lesson5.html">< Previous Lesson</a></b>
! |
! <b><a href="lesson13.html">Next Lesson </a> ></b>
! <b><a
href="index.html">Top</a></b>
More information about the Tinyos-2-commits
mailing list