[Tinyos-2-commits] CVS: tinyos-2.x/doc/html/tutorial index.html,
1.1.2.2, 1.1.2.3 lesson1.html, 1.1.2.7, 1.1.2.8 lesson2.html,
1.1.2.3, 1.1.2.4 lesson3.html, 1.1.2.1, 1.1.2.2 lesson5.html,
1.1.2.2, 1.1.2.3
Phil Levis
scipio at users.sourceforge.net
Mon Jun 5 21:37:01 PDT 2006
Update of /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv3572/html/tutorial
Modified Files:
Tag: tinyos-2_0_devel-BRANCH
index.html lesson1.html lesson2.html lesson3.html lesson5.html
Log Message:
Updates
Index: index.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/Attic/index.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
*** index.html 10 Feb 2006 09:51:21 -0000 1.1.2.2
--- index.html 6 Jun 2006 04:36:58 -0000 1.1.2.3
***************
*** 1,42 ****
! <!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 Tutorial </div>
! <div class="subtitle">Last updated 29 January 2006</div>
!
! <h2><a href="lesson1.html">Lesson 1: TinyOS Component Model</a></h2>
!
! <dd>Lesson 1 introduces the major concepts of the TinyOS Component
! model: components, configurations, interfaces, commands,
! events. The exercise is compiling an existing sample application.
! </dd>
!
! <h2><a href="lesson2.html">Lesson 2: Modules and the Execution Model</a></h2>
!
! <dd>Lesson 2 explains the TinyOS execution model: events
! and commands are revisited in the execution context, tasks are introduced.
! With that knowledge, modules are revisited and fully explained.
! The exercise is modifying the sample application to use a task.
! </dd>
!
! <h2><a href="lesson3.html">Lesson 3: Boot Sequence</a></h2>
!
! <dd>Lesson 3 details the boot sequence and, in doing so, answers the question, "But where is main()?".
! </dd>
!
! <h2><a href="lesson4.html">Lesson 4: Sensing</a></h2>
!
! <h2><a href="lesson5.html">Lesson 5: Communications</a></h2>
!
! <dd> Lesson 5 introduces the TinyOS communication model. A sample
! application illustrates sending and receiving messages.
! </dd>
!
!
!
!
--- 1,77 ----
! <!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 Tutorial </div>
! <div class="subtitle">Last updated 18 May 2006</div>
!
! <h2><a href="lesson1.html">Lesson 1: TinyOS Component Model</a></h2>
!
! <dd>Lesson 1 introduces the major concepts of the TinyOS Component
! model: components, configurations, interfaces, commands,
! events. There is an exercise which shows how to compile an existing sample application.
! </dd>
!
! <h2><a href="lesson2.html">Lesson 2: Modules and the Execution Model</a></h2>
!
! <dd>Lesson 2 explains the TinyOS execution model: events
! and commands are revisited in the execution context, tasks are introduced.
! With that knowledge, modules are revisited and fully explained.
! There is an exercise that modifies the sample application to use a task.
! </dd>
!
! <h2><a href="lesson3.html">Lesson 3: Boot Sequence</a></h2>
!
! <dd>Lesson 3 details the boot sequence and, in doing so, answers the question, "But where is main()?".
! </dd>
!
! <h2><a href="lesson4.html">Lesson 4: Sensing</a></h2>
!
! <dd>Lesson 4 explains how sensors are sampled in TinyOS. There is an exercise that periodically samples
! a sensor and displays the value on the leds.
! </dd>
!
! <h2><a href="lesson5.html">Lesson 5: Communications</a></h2>
!
! <dd> Lesson 5 introduces the TinyOS communication model. There is an exercise that
! illustrates sending and receiving messages.
! </dd>
!
! <h2><a href="lesson6.html">Lesson 6: Storage</a></h2>
!
! <dd> Lesson 6 introduces the TinyOS model model. A sample
! application illustrates storing data.
! </dd>
!
! <h2><a href="lesson7.html">Lesson 7: Power Management</a></h2>
!
! <dd> Lesson 7 introduces the TinyOS power management model. There is an exercise that
! illustrates how to turn components on and off.
! </dd>
!
! <h2><a href="lesson8.html">Lesson 8: Concurrancy</a></h2>
!
! <dd> Lesson 8 introduces the TinyOS concurrancy model. Tasks are revisited and async code is introduced.
! </dd>
!
! <h2><a href="lesson9.html">Lesson 9: Platforms</a></h2>
!
! <dd>
! - chips vs. platforms
! - Telescoping abstractions
! - Sensorboards
! </dd>
!
! <h2><a href="lesson10.html">Lesson 10: TOSSIM</a></h2>
!
! <dd> Lesson 5 introduces the TinyOS communication model. A sample
! application illustrates sending and receiving messages.
! </dd>
!
! </body>
! </html>
\ No newline at end of file
Index: lesson1.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/Attic/lesson1.html,v
retrieving revision 1.1.2.7
retrieving revision 1.1.2.8
diff -C2 -d -r1.1.2.7 -r1.1.2.8
*** lesson1.html 10 Feb 2006 09:51:21 -0000 1.1.2.7
--- lesson1.html 6 Jun 2006 04:36:58 -0000 1.1.2.8
***************
*** 1,339 ****
! <!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 8 January 2005</div>
!
! <p>This lesson introduces the basic concepts of the component model
! used by TinyOS, and the nesC component syntax.
!
! <h1>Introduction</h1>
!
! <p>TinyOS is written in nesC, an extension of the C language designed
! to support the resource-challenged embedded systems space. nesC's
! extensions support an efficient yet robust component model, and a
! concurrency model based on run-to-completion tasks and interrupt
! handlers. This lesson introduces the TinyOS/nesC component model, and
! the next lesson introduces the TinyOS/nesC concurrency model.
!
! <h2>Components and Interfaces</h2>
!
! 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>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>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>.
!
! <h2>Configurations and Modules</h2>
!
! 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. This is called <i>wiring</i>. Every nesC
! application is described by a top-level configuration that wires
! together the components inside.
!
! <h1>Blink: An Example Application</h1>
!
! <p>Let's look at concrete examples using the application Blink found
! in <tt><a href="../../../apps/Blink">apps/Blink</a></tt> in the TinyOS
! tree. This application 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.<a href="#leds_footnote">(1)</a> 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>BlinkApp.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 quickly "snap together"
! applications. For example, a designer could provide a configuration
! that simply wires together one or more modules, none of which she
! actually designed. Likewise, another developer can provide a new set
! of "library" modules that can be used in a range of applications. </p>
!
! <!-- Fill in 2.x convention
! <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 that <tt>Foo.nc</tt> represents a configuration and
! <tt>FooM.nc</tt> represents the corresponding module. While you could
! name an application's implementation module and associated top-level
! configuration anything, to keep things simple we suggest that you
! adopt this convention in your own code. There are several other naming
! conventions used in TinyOS code; a <a href="naming.html">summary</a>
! is provided. -->
!
! <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;
! MainC.SoftwareInit -> LedsC;
! 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="#oskitimermillic_footnote">(2)</a> 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 and LedsC.
!
! <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;
! users 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 component 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>You may have surmised that nesC uses arrows to determine relationships
! between interfaces. Think of the right arrow (<tt>-></tt>) as
! "binds to". The left side of the arrow binds an interface to an
! implementation on the right side. In other words, the component that
! <b>uses</b> an interface is on the left, and the component <b>provides
! </b>the interface is on the right. </p>
!
! It follows, then, that on the line:
!
! <pre></pre>
! <prehead>apps/Blink/BlinkAppC.nc:</prehead>
! <pre>
! BlinkC.Timer -> Timer0;
! </pre>
!
! <tt>BlinkC.Timer</tt> on the left side of the arrow is referring to
! the <i>interface</i> called Timer (<tt>tos/lib/timer/Timer.nc</tt>),
! while <tt>Timer0</tt> on the right side of the arrow is referring to
! the <i>implementation </i>of Timer</tt>. Remember that the arrow
! always binds interfaces (on the left) to implementations (on the
! right).
!
! <p><tt>BlinkAppC</tt> also illustrates that wirings can be
! implicit. For example:
!
! <pre></pre>
! <prehead>apps/Blink/BlinkAppC.nc:</prehead>
! <pre>
! BlinkC.Leds -> LedsC;
! </pre>
!
! is really shorthand for:
!
! <pre>
! BlinkC.Leds -> LedsC.Leds;
! </pre>
!
! If no interface name is given on the right side of the arrow, the nesC
! compiler by default tries to bind to the same interface as on the left
! side of the arrow.
!
! <h1>Exercise</h1>
!
! <p>As a first exercise, simply compile the Blink application for your
! chosen platform. If you don't have hardware, you can compile for the
! <code>pc</code> platform which is simulated code.</p>
!
! <p>The TinyOS makefile structure is tailored to ease
! adding new platforms with widely differing hardware support into TinyOS.
! The makefile system definitions are located in tinyos-2.x/support/make.
!
! <p>The make command to compile a TinyOS application is
! <code>make</code> <i>[platform]</i> and should be executed from the
! application's directory. From the <code>apps/Blink</code> directory
! you could enter the following to compile an image for the telosb platform:
!
! <pre>
! make telosb
! </pre>
!
! <p>The make parameters that you use to upload or <i>install</i> your
! application image onto your mote vary from platform to platform. Please
! check your hardware manufacturer's Getting Started Guide for exact parameters
! (see <a href="#related_docs">Related Documentation</a>). In general,
! however, the make command to install an image onto a mote is
! <code>make</code> <i>[platform]</i> 
! <code>install,</code><i>[moteid]</i>
! <i>[upload port]</i>. From the <code>apps/Blink</code> directory
! you could enter:
!
! <pre>
! make telosb install,2 bsl,3
! </pre>
!
! <p>This would compile an image suitable for the telosb platform and install
! it with a mote ID of 2 using the <code>tos-bsl</code> loader on
! COM port 4 (the bsl argument uses n-1 notation: the COM port is 4 but
! the argument on the make line is 3 (4-1)). Again, see the Getting Started
! Guide for your chosen platform for the exact make parameters.</p>
!
!
! <h1>Conclusion</h1>
!
! <p>This lesson has introduced the concepts of the TinyOS component
! model: configurations, modules, interfaces and wiring. The next
! lesson continues our look at Blink to expand 1) on the nesC/TinyOS concurrency model
! and 2) Module implementations.
!
! <p>
! <a name=#related_docs>
! <h1>Related Documentation</h1>
! </a>
! <ul>
! <li> NesC reference manual: tinyos-2.x/doc/nesc/ref.pdf
! <li> <a href="https://sourceforge.net/projects/nescc">nesc at sourceforge</a>
! <li> Generic component information: tinyos-2.x/doc/nesc/user/generics-1.2.txt
! <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="http://cvs.sourceforge.net/viewcvs.py/tinyos/tinyos-1.x/beta/teps/txt/Attic/tep103.txt?view=markup">TEP 103: TinyOS Coding Conventions</a>
! <li> <a href="http://cvs.sourceforge.net/viewcvs.py/tinyos/tinyos-1.x/beta/teps/txt/Attic/tep106.txt?view=markup">TEP 107: Boot Sequence</a>
! <li> tinyos-2.x/support/make/README
! </ul>
!
! <p>
! <hr>
!
! <p><a name="leds_footnote">(1)</a> Unlike in tinyos-1.x, LEDs in 2.x
! are not labeled by color but instead by number to reflect the fact
! that different platforms have different colored LEDs. In telos, the
! mapping (LED0,LED1,LED2) to (Red,Green,Blue), and in mica motes the
! mapping is (LED0,LED1,LED2) to (Red,Green,Yellow).
!
! <p><a name="timermillic_footnote">(2)</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 typed arguments and in this case, that
! typed argument defines the timer's required precision. A full
! explanation of generic components is outside this document's scope,
! but you can read about them in <a
! href="../../nesc/user/generics-1.2.txt">nesc generic component
! documentation</a>.
!
! <p>
! <b><a href="lesson2.html">Next Lesson ></a></b> | <b><a
! href="index.html">Top</a></b>
! </body>
! </html>
--- 1,450 ----
! <!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 18 May 2005</div>
!
! <p>This lesson introduces the basic concepts of the component model
! used by TinyOS, and the nesC component syntax.
!
! <h1>Introduction</h1>
!
! <p>TinyOS is written in nesC, an extension of the C language designed
! to support the resource-challenged embedded systems space. nesC's
! extensions support an efficient yet robust component model, and a
! concurrency model based on run-to-completion tasks and interrupt
! handlers. This lesson introduces the TinyOS/nesC component model, and
! the next lesson introduces the TinyOS/nesC concurrency model.
!
! <h2>Components and Interfaces</h2>
!
! 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>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>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>.
!
! <h2>Configurations and Modules</h2>
!
! 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. This is called <i>wiring</i>. Every nesC
! application is described by a top-level configuration that wires
! together the components inside.
!
! <h1>Blink: An Example Application</h1>
!
! <p>Let's look at concrete examples using the application Blink found
! in <tt><a href="../../../apps/Blink">apps/Blink</a></tt> in the TinyOS
! tree. This application 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.<a href="#leds_footnote">(1)</a> 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>BlinkApp.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 quickly "snap together"
! applications. For example, a designer could provide a configuration
! that simply wires together one or more modules, none of which she
! actually designed. Likewise, another developer can provide a new set
! of "library" modules that can be used in a range of applications. </p>
!
! <!-- Is this really the T2 convention? -->
! <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>
!
!
! <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>FooC.nc <a href="#hint9">(2)</a></tt></td>
! <td>Public Module</td>
! </tr>
!
! <tr>
! <td><tt>FooP.nc</tt></td>
! <td>Private Module</td>
! </tr>
!
! <tr>
! <td><tt>FooAppC.nc</tt> </td>
! <td>Configuration</td>
! </tr>
!
! </tbody>
! </table>
!
! <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;
! MainC.SoftwareInit -> LedsC;
! 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="#oskitimermillic_footnote">(3)</a>. This is accomplished
! via the <i>as</i> keyword which is simply an alias<a href="#hint10">(4)</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 and LedsC.
!
! <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;
! users 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 component 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>You may have surmised that nesC uses arrows to determine relationships
! between interfaces. Think of the right arrow (<tt>-></tt>) as
! "binds to". The left side of the arrow binds an interface to an
! implementation on the right side. In other words, the component that
! <b>uses</b> an interface is on the left, and the component <b>provides
! </b>the interface is on the right. </p>
!
! It follows, then, that on the line:
!
! <pre></pre>
! <prehead>apps/Blink/BlinkAppC.nc:</prehead>
! <pre>
! BlinkC.Timer -> Timer0;
! </pre>
!
! <tt>BlinkC.Timer</tt> on the left side of the arrow is referring to
! the <i>interface</i> called Timer (<tt>tos/lib/timer/Timer.nc</tt>),
! while <tt>Timer0</tt> on the right side of the arrow is referring to
! the <i>implementation </i>of Timer</tt>. Remember that the arrow
! always binds interfaces (on the left) to implementations (on the
! right).
!
! <p><tt>BlinkAppC</tt> also illustrates that wirings can be
! implicit. For example:
!
! <pre></pre>
! <prehead>apps/Blink/BlinkAppC.nc:</prehead>
! <pre>
! BlinkC.Leds -> LedsC;
! </pre>
!
! is really shorthand for:
!
! <pre>
! BlinkC.Leds -> LedsC.Leds;
! </pre>
!
! If no interface name is given on the right side of the arrow, the nesC
! compiler by default tries to bind to the same interface as on the left
! side of the arrow.
!
! <h1>Exercise</h1>
!
! <p>As a first exercise, simply compile the Blink application for your
! chosen platform. If you don't have hardware, you can compile for the
! <code>pc</code> platform which is simulated code.</p>
!
! <p>The TinyOS makefile structure is tailored to ease
! adding new platforms with widely differing hardware support into TinyOS.
! The makefile system definitions are located in tinyos-2.x/support/make.
!
! <p>The make command to compile a TinyOS application is
! <code>make</code> <i>[platform]</i> and should be executed from the
! application's directory. From the <code>apps/Blink</code> directory
! you could enter the following to compile an image for the telosb platform:
!
! <pre>
! make telosb
! </pre>
!
! <p>The make parameters that you use to upload or <i>install</i> your
! application image onto your mote vary from platform to platform. Please
! check your hardware manufacturer's Getting Started Guide for exact parameters
! (see <a href="#related_docs">Related Documentation</a>). In general,
! however, the make command to install an image onto a mote is
! <code>make</code> <i>[platform]</i> 
! <code>install,</code><i>[moteid]</i>
! <i>[upload port]</i>. From the <code>apps/Blink</code> directory
! you could enter:
!
! <pre>
! $ motelist
! Reference CommPort Description
! ---------- ---------- ----------------------------------------
! UCC89MXV COM4 Telos (Rev B 2004-09-27)
! </pre>
!
! <i>motelist</i> is a command that will tell you which ports have motes attached. In
! this case a TelosB mote is connected to COM port 4. Now you can install the application using:
!
! <pre>
! make telosb install,2 bsl,3
! </pre>
!
! <p>This would compile an image suitable for the telosb platform and install
! it with a mote ID of 2 using the <code>tos-bsl</code> loader on
! COM port 4 (the bsl argument uses n-1 notation: the COM port is 4 but
! the argument on the make line is 3 (4-1)). 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:
!
! <pre>
! 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 BlinkToRadioAppC 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
! tos-set-symbols --objcopy msp430-objcopy --objdump msp430-objdump --target ihex build/telosb/main.ihex build/telosb/main.ihex.out-2 TOS_NODE_ID=2 ActiveMessageAddressC$addr=2
! found mote on COM4 (using bsl,auto)
! installing telosb binary using bsl
! tos-bsl --telosb -c 16 -r -e -I -p build/telosb/main.ihex.out-2
! 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-2
! </pre>
!
! <p>This assumes you're running Windows. Things are slightly different on Linux.
! Instead of COM4 you'll find a numbered "file" in the /dev directory. The actual name of this file
! varies from distribution to distribution and depends on how the motes are physically connected
! (i.e., via serial or USB).
!
! <pre>
! $ motelist
! Reference CommPort Description
! ---------- ---------- ----------------------------------------
! UCC89MXV /dev/ttyUSB3 Telos (Rev B 2004-09-27)
! </pre>
!
! <p>You use the same command to install, except you don't substract 1.
! The ports are already numbered starting at 0.
!
! <pre>
! make telosb install,2 bsl,3
! </pre>
!
! <h1>Conclusion</h1>
!
! <p>This lesson has introduced the concepts of the TinyOS component
! model: configurations, modules, interfaces and wiring. The next
! lesson continues our look at Blink to expand 1) on the nesC/TinyOS concurrency model
! and 2) Module implementations.
!
! <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="../tep107.html">TEP 102: Timers</a>
! <li> <a href="../tep106.html">TEP 106: Schedulers and Tasks</a>
! </ul>
!
! <p>
! <hr>
!
! <p><a name="leds_footnote">(1)</a> Unlike in tinyos-1.x, LEDs in 2.x
! are not labeled by color but instead by number to reflect the fact
! that different platforms have different colored LEDs. In telos, the
! mapping (LED0,LED1,LED2) to (Red,Green,Blue), and in mica motes the
! mapping is (LED0,LED1,LED2) to (Red,Green,Yellow).
!
! <p><a name="hint9">(2)</a>
! <b>Programming Hint 9:</b> If a component is a usable abstraction by itself,
! its name should end with C. If it is intended to be an internal and private
! part of a larger abstraction, its name should end with P. Never wire to
! P components from outside your package (directory). From Phil Levis'
! <a href="http://csl.stanford.edu/~pal/pubs/tinyos-programming-1-0.pdf">
! <i>TinyOS Programming</i></a>
!
! <p><a name="timermillic_footnote">(3)</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 typed arguments and in this case, that
! typed argument defines the timer's required precision. 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">(4)</a>
! <b>Programming Hint 10:</b> Use the <i>as</i> keyword liberally. From Phil Levis'
! <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>
\ No newline at end of file
Index: lesson2.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/Attic/lesson2.html,v
retrieving revision 1.1.2.3
retrieving revision 1.1.2.4
diff -C2 -d -r1.1.2.3 -r1.1.2.4
*** lesson2.html 10 Feb 2006 09:51:21 -0000 1.1.2.3
--- lesson2.html 6 Jun 2006 04:36:58 -0000 1.1.2.4
***************
*** 1,271 ****
! <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
! <html>
! <head>
! <title>TinyOS Tutorial Lesson 2: Modules and the TinyOS Execution Model</title>
! <link href="../../stylesheets/tutorial.css" rel="stylesheet" type="text/css">
! </head>
! <body>
!
! <div class="title">Lesson 2: </div>
! <div class="subtitle">Last updated 18 January 2006</div>
!
! <p>This lesson introduces the TinyOS Execution Model and expands on
! the Component Module.</p>
!
! <h1>Execution Model</h1> <br>
!
! TinyOS executes only one program consisting of selected system
! components and custom components needed for a single application. There is
! no concept of user address space and system address space; there is only
! one address space accessible from all components of the applicatin. </p>
!
! <p>There are two threads of execution: one for <b>tasks</b> and one
! for <b>events</b>. <a href="#event_footnote">(1)</a> A tasks is
! functions whose execution is deferred. Once scheduled, they run to
! completion with respect to other tasks and do not preempt one
! another. Events are executed in response to a hardware interrupt and
! are also run to completion, but may preempt the execution of a task or
! another event.
!
! Recall from lesson 1 that a <b>command</b>, along with events, specify
! a components interface. Commands can be run in either the task context
! or the event context depending upon where the command was called
! from. If the command was called from within an event, it will be run
! in the event handler context. If a command was called from within a
! task, it will be run in the task queue context. <a href="#task_footnote">(2)</a>
!
! <p>Any state belongs to the containing component and is accessed through
! the components interfaces. Blink does not use any state, but if it
! did it would be declared within the <code>implementation</code> blocks.</p>
!
! <p>Now let's revisit the Blink application to see how it uses events
! and commands. Here is the Blink module BlinkC.nc's implementation in
! its entirety:
!
! <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;
! users interface Boot;
! }
! implementation
! {
! event void Boot.booted()
! {
! call Timer0.startPeriodic( 250 );
! call Timer1.startPeriodic( 500 );
! call Timer2.startPeriodic( 1000 );
! }
!
! event void Timer0.fired()
! {
! call Leds.led0Toggle();
! }
!
! event void Timer1.fired()
! {
! call Leds.led1Toggle();
! }
!
! event void Timer2.fired()
! {
! call Leds.led2Toggle();
! }
! }
! </pre>
!
! In lesson 1 we learned that if a Component is to use another component,
! it must implement the events in that component's interface. We also
! saw that the BlinkC component uses the Timer, Leds, and Boot interfaces.
! Let's take a look at those interfaces:
!
! <pre></pre>
! <prehead>tos/interfaces/Boot.nc:</prehead>
! <pre>
! interface Boot {
! event void booted();
! }
! </pre>
!
! <prehead>tos/interfaces/Leds.nc:</prehead>
! <pre>
! interface Leds {
!
! /**
! * Turn LED n on, off, or toggle its present state.
! */
! async command void led0On();
! async command void led0Off();
! async command void led0Toggle();
!
! async command void led1On();
! async command void led1Off();
! async command void led1Toggle();
!
! async command void led2On();
! async command void led2Off();
! async command void led2Toggle();
!
! /**
! * Get/Set the current LED settings as a bitmask. Each bit corresponds to
! * whether an LED is on; bit 0 is LED 0, bit 1 is LED 1, etc.
! */
! async command uint8_t get();
! async command void set(uint8_t val);
!
! }
! </pre>
!
! <prehead>tos/interfaces/Leds.nc:</prehead>
! <pre>
! interface Timer<precision_tag>
! {
! // basic interface
! command void startPeriodic( uint32_t dt );
! command void startOneShot( uint32_t dt );
! command void stop();
! event void fired();
!
! // extended interface omitted (all commands)
! }
! </pre>
!
! Looking over the interfaces for <code>Boot</code>, <code>Leds</code>,
! and
! <code>Timer</code>, we can see that since <code>BlinkC</code> uses
! those interfaces it must implement handlers for the
! <code>Boot.booted()</code> event, and the <code>Timer.fired()</code>
! event. The <code>Leds</code> interface signature does not include any
! events, so BlinkC need not implement any in order to call the Leds
! commands.
! <p>
! Here, again, is BlinkC's implementation of <code>Boot.booted()<code>:
!
! <pre></pre>
! <prehead>apps/Blink/BlinkC.nc:</prehead>
! <pre>
! event void Boot.booted()
! {
! call Timer0.startPeriodic( 250 );
! call Timer1.startPeriodic( 500 );
! call Timer2.startPeriodic( 1000 );
! }
! </pre>
! BlinkC uses 3 instances of the OskiTimerMilliC component and they're
! called Timer0, Timer1, and Timer2. In the Boot.booted() event handler,
! these instances are each started. The parameter to
! <code>startPeriodic()</code> specifies the period in milliseconds after
! which the timer will fire. Because the timer is started using the
! <code>startPeriodic()</code> command, the timer will be reset after
! firing such that the fired() event is triggered every n milliseconds.
!
! <p>Next, we look at the implementation of the <code>Timer.fired()</code>:
!
! <pre></pre>
! <prehead>apps/Blink/BlinkC.nc:</prehead>
! <pre>
! event void Timer0.fired()
! {
! call Leds.led0Toggle();
! }
!
! event void Timer1.fired()
! {
! call Leds.led1Toggle();
! }
!
! event void Timer2.fired()
! {
! call Leds.led2Toggle();
! }
! }
! </pre>
!
! <p>Because there are three Timer instances, the BlinkC component
! must implement three instances of the <code>Timer.fired()</code>
! event. Here, each Timer toggles it's corresponding LED (from on to off or
! from off to on) at every Timer fire by calling the <code>Leds.ledNToggle()</code>
! command exported by the Leds interface. Note that the Leds will be
! toggled within event context because the command is called from
! within an event; this event, in turn, was triggered by a hardware
! interrupt from the platform's timer hardware. Looking back at the
! declaration of the Leds interface, we note that the commands are
! declared with the <code>async</code> keyword so we know that they
! can be called from within event handlers:</p>
!
! <pre></pre>
! <prehead>tos/interfaces/Leds.nc:</prehead>
! <pre>
! interface Leds {
!
! ...
! async command void led0Toggle();
! ...
! async command void led1Toggle();
! ...
! async command void led2Toggle();
! ...
! }
! </pre>
!
! <h1>Exercise</h1>
!
! Blink as written does not use any tasks. Rewrite Blink to
! <ol>
! <li> blink LED0 every 1000 milliseconds
! <li> use a task to change the Leds
! </ol>
!
! Here are a few things you'll
! need to change:
!
! <ol>
! <li> Remove two of the TimerMilliC instances and their corresponding
! events. Remove the lines in the boot() event that start them.
! <li> Create a task that will call the Leds.led0Toggle() command. The
! syntax to define a task goes inside of the modules implementation block
! and looks like this:
! <pre>
! task void myTask()
! {
! // task implementation;
! }
! </pre>
! <li> Change the fired() event to post your new task.
! </ol>
!
! When you're done, you can compare your work with the application
! in <code>apps/tutorial/BlinkTask</code>.
!
! <a name=#related_docs>
! <h1>Related Documentation</h1>
! </a>
! <ul>
! <li> NesC reference manual: tinyos-2.x/doc/nesc/ref.pdf
! <li> <a href="https://sourceforge.net/projects/nescc">nesc at sourceforge</a>
! <li> <a href="http://cvs.sourceforge.net/viewcvs.py/tinyos/tinyos-1.x/beta/teps/txt/Attic/tep106.txt?view=markup">TEP 106: Tasks and Schedulers</a>
! <li> <a href="http://cvs.sourceforge.net/viewcvs.py/tinyos/tinyos-1.x/beta/teps/txt/Attic/tep106.txt?view=markup">TEP 107: Boot Sequence</a>
! </ul>
!
! <p>
! <hr>
!
! <p><a name="event_footnote">(1)</a> Recall that events were introduced
! in lesson 1 in conjunction with the component model and were explained
! in that context to be functions in an interface that a component must
! implement if the component is to use that interface. Lesson 1
! discussed events in terms of the Component Model; here they are
! discussed in terms of the Execution Model.
!
! <p><a name="task_footnote">(2)</a> The task semantics have changed
! significantly from tinyos-2.x. In 1.x, a task could be posted more
! than once and a post could fail if the task queue were full. In 2.x, a
! basic post will only fail if that task has already been posted and has
! not started execution. So a task can always run, but can only have one
! outstanding post at any time. If a component needs to post task
! several times, then the end of the task logic can repost itself as
! need be.
--- 1,296 ----
! <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
! <html>
! <head>
! <title>TinyOS Tutorial Lesson 2: Modules and the TinyOS Execution Model</title>
! <link href="../../stylesheets/tutorial.css" rel="stylesheet" type="text/css">
! </head>
! <body>
!
! <div class="title">Lesson 2: Modules and the TinyOS Execution Model</div>
! <div class="subtitle">Last updated 18 January 2006</div>
!
! <p>This lesson introduces the TinyOS Execution Model and expands on
! the Component Module.</p>
!
! <h1>Execution Model</h1> <br>
!
! TinyOS executes only one program consisting of selected system
! components and custom components needed for a single application. There is
! no concept of user address space and system address space; there is only
! one address space accessible from all components of the applicatin. </p>
!
! <p>There are two threads of execution: one for <b>tasks</b> and one
! for <b>events</b>. <a href="#event_footnote">(1)</a> A tasks is
! functions whose execution is deferred. Once scheduled, they run to
! completion with respect to other tasks and do not preempt one
! another. Events are executed in response to a hardware interrupt and
! are also run to completion, but may preempt the execution of a task or
! another event.
!
! Recall from lesson 1 that a <b>command</b>, along with events, specify
! a components interface. Commands can be run in either the task context
! or the event context depending upon where the command was called
! from. If the command was called from within an event, it will be run
! in the event handler context. If a command was called from within a
! task, it will be run in the task queue context. <a href="#task_footnote">(2)</a>
!
! <p>Any state belongs to the containing component and is accessed through
! the components interfaces. Blink does not use any state <a href="#hint6">(3)</a>
! , but if it did it would be declared within the <code>implementation</code> blocks.</p>
!
! <p>Now let's revisit the Blink application to see how it uses events
! and commands. Here is the Blink module BlinkC.nc's implementation in
! its entirety:
!
! <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;
! users interface Boot;
! }
! implementation
! {
! event void Boot.booted()
! {
! call Timer0.startPeriodic( 250 );
! call Timer1.startPeriodic( 500 );
! call Timer2.startPeriodic( 1000 );
! }
!
! event void Timer0.fired()
! {
! call Leds.led0Toggle();
! }
!
! event void Timer1.fired()
! {
! call Leds.led1Toggle();
! }
!
! event void Timer2.fired()
! {
! call Leds.led2Toggle();
! }
! }
! </pre>
!
! In lesson 1 we learned that if a Component is to use another component,
! it must implement the events in that component's interface. We also
! saw that the BlinkC component uses the Timer, Leds, and Boot interfaces.
! Let's take a look at those interfaces:
!
! <pre></pre>
! <prehead>tos/interfaces/Boot.nc:</prehead>
! <pre>
! interface Boot {
! event void booted();
! }
! </pre>
!
! <prehead>tos/interfaces/Leds.nc:</prehead>
! <pre>
! interface Leds {
!
! /**
! * Turn LED n on, off, or toggle its present state.
! */
! async command void led0On();
! async command void led0Off();
! async command void led0Toggle();
!
! async command void led1On();
! async command void led1Off();
! async command void led1Toggle();
!
! async command void led2On();
! async command void led2Off();
! async command void led2Toggle();
!
! /**
! * Get/Set the current LED settings as a bitmask. Each bit corresponds to
! * whether an LED is on; bit 0 is LED 0, bit 1 is LED 1, etc.
! */
! async command uint8_t get();
! async command void set(uint8_t val);
!
! }
! </pre>
!
! <prehead>tos/interfaces/Leds.nc:</prehead>
! <pre>
! interface Timer<precision_tag>
! {
! // basic interface
! command void startPeriodic( uint32_t dt );
! command void startOneShot( uint32_t dt );
! command void stop();
! event void fired();
!
! // extended interface omitted (all commands)
! }
! </pre>
!
! Looking over the interfaces for <code>Boot</code>, <code>Leds</code>,
! and
! <code>Timer</code>, we can see that since <code>BlinkC</code> uses
! those interfaces it must implement handlers for the
! <code>Boot.booted()</code> event, and the <code>Timer.fired()</code>
! event. The <code>Leds</code> interface signature does not include any
! events, so <code>BlinkC</code> need not implement any in order to call the Leds
! commands.
! <p>
! Here, again, is <code>BlinkC</code>'s implementation of <code>Boot.booted()<code>:
!
! <pre></pre>
! <prehead>apps/Blink/BlinkC.nc:</prehead>
! <pre>
! event void Boot.booted()
! {
! call Timer0.startPeriodic( 250 );
! call Timer1.startPeriodic( 500 );
! call Timer2.startPeriodic( 1000 );
! }
! </pre>
! <code>BlinkC</code> uses 3 instances of the OskiTimerMilliC component and they're
! called <code>Timer0</code>, <code>Timer1</code>, and <code>Timer2</code>.
! In the <code>Boot.booted()</code> event handler, these instances are each started.
! The parameter to <code>startPeriodic()</code> specifies the period in milliseconds after
! which the timer will fire. Because the timer is started using the <code>startPeriodic()</code>
! command, the timer will be reset after firing such that the <code>fired()</code> event is
! triggered every n milliseconds.
!
! <p>Next, we look at the implementation of the <code>Timer.fired()</code>:
!
! <pre></pre>
! <prehead>apps/Blink/BlinkC.nc:</prehead>
! <pre>
! event void Timer0.fired()
! {
! call Leds.led0Toggle();
! }
!
! event void Timer1.fired()
! {
! call Leds.led1Toggle();
! }
!
! event void Timer2.fired()
! {
! call Leds.led2Toggle();
! }
! }
! </pre>
!
! <p>Because there are three Timer instances, the <code>BlinkC</code> component
! must implement three instances of the <code>Timer.fired()</code>
! event. Here, each Timer toggles it's corresponding LED (from on to off or
! from off to on) at every Timer fire by calling the <code>Leds.ledNToggle()</code>
! command exported by the Leds interface. Note that the Leds will be
! toggled within event context because the command is called from
! within an event; this event, in turn, was triggered by a hardware
! interrupt from the platform's timer hardware. Looking back at the
! declaration of the Leds interface, we note that the commands are
! declared with the <code>async</code> keyword <a href="#hint3">(4)</a>
! so we know that they can be called from within event handlers:</p>
!
! <pre></pre>
! <prehead>tos/interfaces/Leds.nc:</prehead>
! <pre>
! interface Leds {
!
! ...
! async command void led0Toggle();
! ...
! async command void led1Toggle();
! ...
! async command void led2Toggle();
! ...
! }
! </pre>
!
! <h1>Exercise</h1>
!
! Blink as written does not use any tasks. Rewrite Blink to
! <ol>
! <li> blink LED0 every 1000 milliseconds
! <li> use a task to change the Leds
! </ol>
!
! Here are a few things you'll need to change:
!
! <ol>
! <li> Remove two of the <code>TimerMilliC</code> instances and their corresponding
! events. Remove the lines in the <code>boot()</code> event that start them.
! <li> Create a task <a href="#hint2">(5)</a> that will call the
! <code>Leds.led0Toggle()</code> command. The syntax to define a
! task goes inside of the modules implementation block and looks like this:
! <pre>
! task void myTask()
! {
! // task implementation;
! }
! </pre>
! <li> Change the <code>fired()</code> event to post your new task.
! </ol>
!
! When you're done, you can compare your work with the application
! in <code>apps/tutorial/BlinkTask</code>.
!
! <a name=#related_docs>
! <h1>Related Documentation</h1>
! </a>
! <ul>
! <li> <a href="../tep107.html">TEP 102: Timers</a>
! <li> <a href="../tep106.html">TEP 106: Schedulers and Tasks</a>
! </ul>
!
! <p>
! <hr>
!
! <p><a name="event_footnote">(1)</a> Recall that events were introduced
! in lesson 1 in conjunction with the component model and were explained
! in that context to be functions in an interface that a component must
! implement if the component is to use that interface. Lesson 1
! discussed events in terms of the Component Model; here they are
! discussed in terms of the Execution Model.
!
! <p><a name="task_footnote">(2)</a> The task semantics have changed
! significantly from tinyos-2.x. In 1.x, a task could be posted more
! than once and a post could fail if the task queue were full. In 2.x, a
! basic post will only fail if that task has already been posted and has
! not started execution. So a task can always run, but can only have one
! outstanding post at any time. If a component needs to post task
! several times, then the end of the task logic can repost itself as
! need be.
!
! <p><a name="hint6">(3)</a><b>Programming Hint 6:</b> Allocate all
! state in components. If your application requirements necessitate a dynamic
! memory pool, encapsulate it in a component and try to limit the set of users.
! From Phil Levis' <a href="http://csl.stanford.edu/~pal/pubs/tinyos-programming-1-0.pdf">
! <i>TinyOS Programming</i></a>
!
! <p><a name="hint3">(4)</a><b>Programming Hint 3:</b> Keep code
! synchronous when you can. Code should be async only if its timing is
! very important or if it might be used by something whose timing is important.
! From Phil Levis' <a href="http://csl.stanford.edu/~pal/pubs/tinyos-programming-1-0.pdf">
! <i>TinyOS Programming</i></a>
!
! <p><a name="hint3">(4)</a><b>Programming Hint 3:</b> Keep tasks short.
! From Phil Levis' <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="lesson1.html">Previous Lesson</a></b> | <b><a
! href="index.html">Top</a></b> | <b><a href="lesson3.html">Next Lesson </a> ></b>
! </center>
!
! </body>
! </html>
\ No newline at end of file
Index: lesson3.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/Attic/lesson3.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -C2 -d -r1.1.2.1 -r1.1.2.2
*** lesson3.html 10 Feb 2006 09:51:21 -0000 1.1.2.1
--- lesson3.html 6 Jun 2006 04:36:58 -0000 1.1.2.2
***************
*** 1,168 ****
!
! <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
! <html>
! <head>
! <title>TinyOS Tutorial Lesson 3: TinyOS Boot and System Initialization</title>
! <link href="../../stylesheets/tutorial.css" rel="stylesheet" type="text/css">
! </head>
! <body>
!
! <div class="title">Lesson 3: Boot Sequence</div>
! <div class="subtitle">Last updated 9 February 2006</div>
!
! One of the frequently asked questions regarding TinyOS is, "Where is
! main()?". In previous lessons, we deferred detailed discussion of the
! TinyOS boot sequence in favor of grasping the general idea. We will
! now revisit the boot sequence indetail. Understanding how TinyOS
! initializes will help solidify understanding of the execution model
! and answer the question "Where is main()?".
!
! The TinyOS boot sequence is comprised of three steps:
! <ul>
! <li> Scheduler initialization
! <li> Component initialization
! <li> Signal that the boot process has completed
! </ul>
!
! <p><b>Scheduler initialization.</b> The scheduler is initialized
! before any components are initialized. If the scheduler were not
! initialized before the components, component initialization
! routines would not be able to post tasks. While not all components
! require tasks to be posted, this gives the flexibility required for those compoenents that do.
!
! <p>The <code>Scheduler</code> interface defines a scheduling
! component's signature in
! <code>tos/interfaces/Scheduler.nc</code>. TinyOS developers can
! define their own scheduler to meet their application's needs.</p> An
! implementation of the
! <code>Scheduler</code> interface is provided in
! <code>tos/system/TinySchedulerC.nc</code>.</p>
!
! <p><b>Component initialization.</b> After the scheduler is initialized,
! components are initialized. The <code>Init</code> interface implements only
! the single command <code>init()</code>. </p>
!
! <pre></pre>
! <prehead>tos/interfaces/Init.nc:</prehead>
! <pre>
!
! interface Init {
! command error_t init();
! }
! </pre>
!
! <p>To provide the initialization flexibility required by sensor
! network components, the TinyOS's boot sequence breaks down the component
! initialization into either a <i>platform
! initialization phase</i> and a <i>software initialization
! phase</i>. This is accomplished by making the TinyOS component that
! executes the boot sequence provide two <code>Init</code interfaces:
! one called
! <code>PlatformInit</code> and one called <code>SoftwareInit</code>.
! The defining difference between the two is that the platform
! initialization phase precedes the software initialization phase and
! component writers can choose to wire their components interfaces to
! the most appropriate <code>Init</code>. Any component that requires
! initialization can implement the <code>Init</code interface and wire
! the implementation to either the <code>PlatformInit</code> or
! <code>PlatformInit</code interface.
!
! <p>To fully conceptualize the two initialization options, it is
! helpful to look at the code that implements the boot sequence. The
! boot sequence is implemented in a system component called
! <code>RealMainP.nc</code.
!
! <pre></pre>
! <prehead>tos/system/RealMainP.nc:</prehead>
! <pre>
! module RealMainP {
! provides interface Boot;
! uses interface Scheduler;
! uses interface Init as PlatformInit;
! uses interface Init as SoftwareInit;
! }
! implementation {
! // implementation covered below
! }
! </pre>
!
! <p>Generally, you'll find <code>PlatformInit</code> implementations in low-level platform-specific code, and <code>
! SoftwareInit</code> implementations layers above the platform-specific code.
!
! <p>And now to answer the question, "Where is main?".
! <code>RealMainP</code> is hooked into TinyOS applications by the wiring in
! the <code>MainC</conde> configuration which is, in turn, required to be wired into <i>every</i> application.
!
! <pre></pre>
! <prehead>tos/system/MainC.nc:</prehead>
! <pre>
! configuration MainC {
! provides interface Boot;
! uses interface Init as SoftwareInit;
! }
! implementation {
! components PlatformC, RealMainP, TinySchedulerC;
!
! RealMainP.Scheduler -> TinySchedulerC;
! RealMainP.PlatformInit -> PlatformC;
!
! // Export the SoftwareInit and Booted for applications
! SoftwareInit = RealMainP.SoftwareInit;
! Boot = RealMainP;
! }
! </pre>
!
! The last piece of the boot sequence story is the actual implementation in
! <code>RealMainP.nc</code>:
!
! <pre></pre>
! <prehead>tos/system/RealMainP.nc:</prehead>
! <pre>
! module RealMainP {
! // signature
! }
! implementation {
! int main() __attribute__ ((C, spontaneous)) {
!
! call Scheduler.init();
!
! call PlatformInit.init();
! while (call Scheduler.runNextTask());
!
! call SoftwareInit.init();
! while (call Scheduler.runNextTask());
! }
!
! /* Enable interrupts now that system is ready. */
! __nesc_enable_interrupt();
!
! signal Boot.booted();
!
! /* Spin in the Scheduler */
! call Scheduler.taskLoop();
!
! ...
! }
!
! </pre>
!
!
! Once the <code>Boot.booted()</code> event is signaled, components are free
! to call <code>start()</code> on any components they are using. Recall
! that in the <code>Blink</code> application, the timers were started from
! the <code>booted()</code> event.
!
! Lastly, note that the task loop is entered. Hopefully you can now
! understand the mechanism by which TinyOS runs its tasks serially with
! respect to each other, but yes the task look can be interrupted by
! event code since interrupts have been enabled.
!
! <p>
! <a name=#related_docs>
! <h1>Related Documentation</h1>
! </a>
! <ul>
! <li> <a href="http://cvs.sourceforge.net/viewcvs.py/tinyos/tinyos-1.x/beta/teps/txt/Attic/tep103.txt?view=markup">TEP 103: TinyOS Coding Conventions</a>
! <li> <a href="http://cvs.sourceforge.net/viewcvs.py/tinyos/tinyos-1.x/beta/teps/txt/Attic/tep106.txt?view=markup">TEP 107: Boot Sequence</a>
! </ul>
!
--- 1,181 ----
! <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
! <html>
! <head>
! <title>TinyOS Tutorial Lesson 3: TinyOS Boot and System Initialization</title>
! <link href="../../stylesheets/tutorial.css" rel="stylesheet" type="text/css">
! </head>
! <body>
!
! <div class="title">Lesson 3: TinyOS Boot and System Initialization</div>
! <div class="subtitle">Last updated 18 May 2006</div>
!
! One of the frequently asked questions regarding TinyOS is, "Where is
! <code>main()</code>?". In previous lessons, we deferred detailed discussion of the
! TinyOS boot sequence in favor of grasping the general idea. We will
! now revisit the boot sequence indetail. Understanding how TinyOS
! initializes will help solidify understanding of the execution model
! and answer the question "Where is <code>main()</code>?".
!
! The TinyOS boot sequence is comprised of three steps:
! <ul>
! <li> Scheduler initialization
! <li> Component initialization
! <li> Signal that the boot process has completed
! </ul>
!
! <p><b>Scheduler initialization.</b> The scheduler is initialized
! before any components are initialized. If the scheduler were not
! initialized before the components, component initialization
! routines would not be able to post tasks. While not all components
! require tasks to be posted, this gives the flexibility required for those compoenents that do.
!
! <p>The <code>Scheduler</code> interface defines a scheduling
! component's signature in
! <code>tos/interfaces/Scheduler.nc</code>. TinyOS developers can
! define their own scheduler to meet their application's needs.</p> An
! implementation of the <code>Scheduler</code> interface is provided in
! <code>tos/system/TinySchedulerC.nc</code>.</p>
!
! <p><b>Component initialization.</b> After the scheduler is initialized,
! components are initialized. The <code>Init</code> interface implements only
! the single command <code>init()</code>. </p>
!
! <pre></pre>
! <prehead>tos/interfaces/Init.nc:</prehead>
! <pre>
!
! interface Init {
! command error_t init();
! }
! </pre>
!
! <p>To provide the initialization flexibility required by sensor
! network components, the TinyOS's boot sequence breaks down the component
! initialization into either a <i>platform initialization phase</i> and a <i>software
! initialization phase</i>. This is accomplished by making the TinyOS component that
! executes the boot sequence provide two <code>Init</code interfaces:
! one called <code>PlatformInit</code> and one called <code>SoftwareInit</code>.
!
! <p>The defining difference between the two is that the platform
! initialization phase precedes the software initialization phase and
! component writers can choose to wire their components interfaces to
! the most appropriate <code>Init</code><a href="#hint8">(1)</a>.
! Any component that requires initialization can implement the <code>Init</code
! interface and wire the implementation to either the <code>PlatformInit</code> or
! <code>PlatformInit</code interface.
!
! <p>To fully conceptualize the two initialization options, it is
! helpful to look at the code that implements the boot sequence. The
! boot sequence is implemented in a system component called
! <code>RealMainP.nc</code.
!
! <pre></pre>
! <prehead>tos/system/RealMainP.nc:</prehead>
! <pre>
! module RealMainP {
! provides interface Boot;
! uses interface Scheduler;
! uses interface Init as PlatformInit;
! uses interface Init as SoftwareInit;
! }
! implementation {
! // implementation covered below
! }
! </pre>
!
! <p>Generally, you'll find <code>PlatformInit</code> implementations in low-level platform-specific code, and <code>
! SoftwareInit</code> implementations layers above the platform-specific code.
!
! <p>And now to answer the question, "Where is main?".
! <code>RealMainP</code> is hooked into TinyOS applications by the wiring in
! the <code>MainC</conde> configuration which is, in turn, required to be wired into <i>every</i> application.
!
! <pre></pre>
! <prehead>tos/system/MainC.nc:</prehead>
! <pre>
! configuration MainC {
! provides interface Boot;
! uses interface Init as SoftwareInit;
! }
! implementation {
! components PlatformC, RealMainP, TinySchedulerC;
!
! RealMainP.Scheduler -> TinySchedulerC;
! RealMainP.PlatformInit -> PlatformC;
!
! // Export the SoftwareInit and Booted for applications
! SoftwareInit = RealMainP.SoftwareInit;
! Boot = RealMainP;
! }
! </pre>
!
! The last piece of the boot sequence story is the actual implementation in
! <code>RealMainP.nc</code>:
!
! <pre></pre>
! <prehead>tos/system/RealMainP.nc:</prehead>
! <pre>
! module RealMainP {
! // signature
! }
! implementation {
! int main() __attribute__ ((C, spontaneous)) {
!
! call Scheduler.init();
!
! call PlatformInit.init();
! while (call Scheduler.runNextTask());
!
! call SoftwareInit.init();
! while (call Scheduler.runNextTask());
! }
!
! /* Enable interrupts now that system is ready. */
! __nesc_enable_interrupt();
!
! signal Boot.booted();
!
! /* Spin in the Scheduler */
! call Scheduler.taskLoop();
!
! ...
! }
!
! </pre>
!
! Once the <code>Boot.booted()</code> event is signaled, components are free
! to call <code>start()</code> on any components they are using. Recall
! that in the <code>Blink</code> application, the timers were started from
! the <code>booted()</code> event.
!
! Lastly, note that the task loop is entered. Hopefully you can now
! understand the mechanism by which TinyOS runs its tasks serially with
! respect to each other, but yes the task look can be interrupted by
! event code since interrupts have been enabled.
!
! <p>
! <a name=#related_docs>
! <h1>Related Documentation</h1>
! </a>
! <ul>
! <li> <a href="../tep106.html">TEP 106: Schedulers and Tasks</a>
! <li> <a href="../tep107.html">TEP 107: Boot Sequence</a>
! </ul>
!
! <p><a name="hint3">(4)</a><b>Programming Hint 8:</b> In the top-level
! configuration of a software abstraction, auto-wire Init to MainC. This removes the
! burden of wiring Init from the programmer, which removes unnecessary work from the
! boot sequence and removes the possibility of bugs from forgetting to wire.
! From Phil Levis' <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="lesson2.html">Previous Lesson</a></b> | <b><a
! href="index.html">Top</a></b> | <b><a href="lesson4.html">Next Lesson </a> ></b>
! </center>
!
! </body>
! </html>
\ No newline at end of file
Index: lesson5.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/Attic/lesson5.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
*** lesson5.html 1 Mar 2006 20:26:58 -0000 1.1.2.2
--- lesson5.html 6 Jun 2006 04:36:58 -0000 1.1.2.3
***************
*** 1,943 ****
! <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
! <html>
! <head>
! <title>Lesson 5: Communications</title>
! <link href="../../stylesheets/tutorial.css" rel="stylesheet" type="text/css">
! </head>
! <body>
!
! $Id$
!
[...1860 lines suppressed...]
! independent types when defining message formats.
! From Phil Levis' <a href="http://csl.stanford.edu/~pal/pubs/tinyos-programming-1-0.pdf">
! <i>TinyOS Programming</i></a>
!
! <p><a name="hint16">(4)</a><b>Programming Hint 16:</b>If you have to perform
! significant computation on a platform independent type or access it many (hundreds or
! more) times, then temporarily copying it to a native type can be a good idea.
! From Phil Levis' <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="lesson4.html">Previous Lesson</a></b> | <b><a
! href="index.html">Top</a></b> | <b><a href="lesson6.html">Next Lesson </a> ></b>
! </center>
!
! </body>
! </html>
More information about the Tinyos-2-commits
mailing list