[Tinyos-2-commits] CVS: tinyos-2.x/doc/html/tutorial lesson7.html, 1.1.2.1, 1.1.2.2

Sun Nov 5 15:20:20 PST 2006

Update of /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv11326

Modified Files:
      Tag: tinyos-2_0_devel-BRANCH
	lesson7.html 
Log Message:
Release version

Index: lesson7.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial/Attic/lesson7.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
*** lesson7.html	25 Oct 2006 06:38:12 -0000	1.1.2.1
--- lesson7.html	5 Nov 2006 23:20:18 -0000	1.1.2.2
***************
*** 8,12 ****

  <div class="title">Lesson 7: Permanent Data Storage</div>
! <div class="subtitle">Last Modified: October 24 2006</div>

  <p>This lesson introduces permanent (non-volatile) data storage in
--- 8,12 ----

  <div class="title">Lesson 7: Permanent Data Storage</div>
! <div class="subtitle">Last Modified: November 5, 2006</div>

  <p>This lesson introduces permanent (non-volatile) data storage in
***************
*** 27,33 ****
  <li>Store configuration data that survives a power cycle.

! <li>Log sensor readings and radio data packets to flash.

! <li>Store large objects in non-volatile flash.

  </ul>
--- 27,34 ----
  <li>Store configuration data that survives a power cycle.

! <li>Provide a link to example code using the logging abstraction.

! <li>Provide a link to example code use large objects storage in
! non-volatile flash.

  </ul>
***************
*** 159,165 ****
  </pre>

- 
- <p>RESTRICTIONS ON SIZE PARAMETER???</p>
- 
  <p>The volume table for a particular application must be placed in the
  application's directory (where one types 'make') and must be named
--- 160,163 ----
***************
*** 171,195 ****
  abstractions needs a file named <code>volumes-stm25p.xml</code>.

! <p>See Section 4.1 in <a href="#fn1">TEP 103</a> for more details.

  <h1>Storing Configuration Data</h1>

! <p>Recall that in Lesson 3, we implemented a simple application that
! incremented a counter, displayed the counter's three least significant
! bits on the three LEDs, and sent a message with the counter value over
! the radio.  In that application, if the node was power-cycled, the
! counter would be reset and the node would begin counting from zero.
! To illustrate how permanent data storage can be used to persist
! configuration data across power cycles, we will <em>store</em> the
! value of counter every time it is incremented and read its value on
! system initialization.  This will allow the node to keep track of its
! counter across a power cycle and begin counting exactly where it left
! off.

! <h1>Logging Sensor Readings and Radio Packets</h1>

  <h1>Storing Large Objects</h1>

  <h1>Conclusions</h1>
--- 169,355 ----
  abstractions needs a file named <code>volumes-stm25p.xml</code>.

! <p>Note that the size parameter is a multiple of the erase unit for a
! particular flash chip.  See Section 4.1 in <a href="#fn1">TEP 103</a>
! for more details.

  <h1>Storing Configuration Data</h1>

! <p>In <a name="fn2"><a href="lesson3.html">Lesson 3</a></a>, we
! implemented a simple application called BlinkToRadio that used a
! single timer, set to fire at a fixed rate, to toggle the LEDs.

! <p>See <a href="../../../apps/tutorials/BlinkConfig/">
! <code>tinyos-2.x/apps/tutorials/BlinkConfig/</code></a> for the
! accompanying code.
! 
! <p>This lesson shows how parameters, like the timer period, can be
! configured at runtime and persisted across node power cycles.  The
! ability to store configuration data is useful in many applications.
! For example, it may be necessary to store a node's coordinates which
! are only known after the node is deployed.  Let's walk through the
! steps to use the <code>ConfigStorage</code> abstraction:
! 
! <ol>
! 
! <li>Create a <code>volumes-CHIPNAME.xml</code> file, enter the volume
! table in this file, and place the file in the application directory.
! Note that <code>CHIPNAME</code> is the flash chip used on your target
! plaform.  For example, <code>CHIPNAME</code> will be
! <code>stm25p</code> for the Telos platform and <code>at45db</code> for
! the MicaZ platform.  Our file will have the following contents:
! 
! <pre>
! &lt;volume_table&gt;
!   &lt;volume name="LOGTEST" size="262144"/&gt;
!   &lt;volume name="CONFIGTEST" size="131072"/&gt;
! &lt;/volume_table&gt;
! </pre>
! 
! This volume information is used by the toolchain to create an include
! file.  The auto-generated file, however, has to be included manually.
! Place the following line in the configuration file which declares the
! ConfigStorageC component (e.g. <code>BlinkConfigAppC.nc</code>):
! 
! <pre>
! #include "StorageVolumes.h"
! </pre>
! 
! <li>Config storage <em>uses</em> the <code>Mount</code> and
! <code>ConfigStorage</code> interfaces (note that we rename
! <code>ConfigStorage</code> to <code>Config</code>).
! 
! <pre>
! module BlinkConfigC {
!   uses {
!     ...
!     interface Mount;
!     interface ConfigStorage as Config;
!     ...
!   }
! }
! </pre>
! 
! <li>Each interface must be wired to an <em>implementation</em> that
! will provide it:
! 
! <pre>
! configuration BlinkConfigAppC {
! }
! implementation {
!   components BlinkConfigC as App;
!   components new ConfigStorageC(VOLUME_CONFIGTEST); 
!   ...
! 
!   App.Mount      -> ConfigStorageC.Mount;
!   App.Config     -> ConfigStorageC.ConfigStorage;
!   ...
! }
! </pre>
! 
! <li>Before the flash chip can be used, it must be mounted using the
! two-phase mount/mountDone command.  Here we show chaining how this
! might be chained into the boot sequence:
! 
! <pre>
!   event void Boot.booted() {
!     call AMControl.start();
!   }
! 
!   event void AMControl.startDone(error_t error) {
!     if (error != SUCCESS) {
!       call AMControl.start();
!     }
!     if (call Mount.mount() != SUCCESS) {
!       // Handle failure
!     }
!   }
! </pre>
! 
! <li>If the Mount.mount succeeds, then the <code>Mount.mountDone</code>
! event will be signaled.  In this case, we call the
! <code>ConfigStore.mount</code> command from with the event handler:
! 
! <pre>
!   event void Mount.mountDone(error_t error) {
!     if (error != SUCCESS) {
!       // Handle failure
!     }
!     else{
!       call Config.write(CONFIG_ADDR, &period, sizeof(period));
!     }
!   }
! </pre>
! 
! <li>Once mounted, the flash can be written:
! 
! <pre>
!   event void Mount.mountDone(error_t error) {
!     if (error != SUCCESS) {
!       // Handle failure
!     }
!     else{
!       call Config.write(CONFIG_ADDR, &period, sizeof(period));
!     }
!   }
! </pre>

+ <li>Data is not necessarily "written" to flash when
+ <code>ConfigStore.write</code> is called.  To ensure data is persisted
+ to flash, a <code>ConfigStore.commit</code> call is required:
+ 
+ <pre>
+   event void Config.writeDone(storage_addr_t addr, void *buf, 
+     storage_len_t len, error_t result) {
+     // Verify addr and len
+ 
+     if (result == SUCCESS) {
+       // Note success
+     }
+     else {
+       // Handle failure
+     }
+     if (call Config.commit() != SUCCESS) {
+       // Handle failure
+     }
+   }
+ </pre>
+ 
+ <li>Finally, when the commit is complete, data can be read back from
+ the flash:
+ 
+ <pre>
+   event void Config.commitDone(error_t error) {
+     if (call Config.read(CONFIG_ADDR, &period2, sizeof(period2)) != SUCCESS) {
+       // Handle failure
+     }
+   }
+ 
+   event void Config.readDone(storage_addr_t addr, void* buf, 
+     storage_len_t len, error_t result) __attribute__((noinline)) {
+     memcpy(&period2, buf, len);
+ 
+     if (period == period2) {
+       call Leds.led2On();
+     }
+ 
+     if (len == 2 && addr == CONFIG_ADDR) {
+       call Leds.led1On();
+     }
+   }
+ </pre>
+ 
+ </ol>
+ 
+ <h1>Logging Data</h1>
+ 
+ See <a href="../../../apps/tests/storage/Log/">
+ <code>tinyos-2.x/apps/tests/storage/Log/</code></a> for an example of
+ code that uses the Log storage abstraction.

  <h1>Storing Large Objects</h1>

+ See <a href="../../../apps/tests/storage/Block/">
+ <code>tinyos-2.x/apps/tests/storage/Block/</code></a> for an example
+ of code that uses the Block storage abstraction.

  <h1>Conclusions</h1>
***************
*** 202,212 ****
  <ul>
  <li> (1) <a name="fn1"><a href="../tep103.html">TEP 103: Permanent Data Storage</a></a>
! </ul>
! 
! <p><a name="hint15">(3)</a><b>Programming Hint 15:</b>Always use platform
! 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>
! 

  <!-- Begin footer -->
--- 362,368 ----
  <ul>
  <li> (1) <a name="fn1"><a href="../tep103.html">TEP 103: Permanent Data Storage</a></a>
! <li> (2) <a name="fn2"><a href="lesson1.html">Lesson 1: Getting Started with TinyOS and nesC</a></a>
  <i>TinyOS Programming</i></a>
! </ul>

  <!-- Begin footer -->