Small modifications to lesson 15 and 8, and new checkin of lesson 16

[tinyos-2.x.git] / doc / html / tutorial / lesson15.html

diff --git a/doc/html/tutorial/lesson15.html b/doc/html/tutorial/lesson15.html
index caed1a9d11378c7f9f696b7a839c2060866ac97d..cb9075f77efbb3c6d0809c2a9b29c72b2969bc4f 100644 (file)
--- a/doc/html/tutorial/lesson15.html
+++ b/doc/html/tutorial/lesson15.html
@@ -9,8 +9,8 @@
     <div class="subtitle">Last updated August 19th, 2007</div>
     
     <p>This lesson demonstrates how to use the <code>printf</code> library located in 
-    tos/lib/printf to debug TinyOS applications by printing messages over the serial 
-    port.</p>
+    <code>tos/lib/printf</code> to debug TinyOS applications by printing messages over
+    the serial port.</p>
     
     <h1>Overview</h1>
     <p> 
@@ -94,7 +94,7 @@
     Currently, only a single buffer is used to store the strings supplied to
     calls to <code>printf</code> before flushing them.  This means that while
     the buffer is being flushed, any calls to <code>printf</code> will fail.
-    In the future, we plan to implement a doubled buffer approach so that
+    In the future, we plan to implement a double buffered approach so that
     strings can continue to be buffered at the same time they are being printed.
     </p>
     <p>
@@ -130,6 +130,22 @@ cvs -z3 -d:pserver:anonymous@tinyos.cvs.sourceforge.net:/cvsroot/tinyos co -P -d
     <p>
     Just hit enter when prompted for a CVS password.  You do not need to enter one.
     </p>
+
+    <p>
+    If you are not using cvs, you will also have to apply the patch
+    found <a href=http://sing.stanford.edu/klueska/tinyos-2.0-printf.patch>here</a>
+    in order to allow the <code>printf</code> library to compile correctly for
+    atmega128x based platforms (i.e. mica2, micaz):
+    </p>
+    <pre>
+    cp tinyos-2.0-printf.patch $TOSROOT/..
+    cd $TOSROOT/..
+    patch -p0 < tinyos-2.0-printf.patch</pre>
+    <p>
+    Note that you may have to use 'sudo' when applying the patch if you run into
+    permission problems.
+    </p>
+
     <hr></hr>
 
     <p>
@@ -282,14 +298,15 @@ event void PrintfFlush.flushDone(error_t error) {
 }</pre>
     <p>
     Notice that the last line of output is cut short before being fully printed.
-    If you actually read the line printed above it can see why.  The buffer
-    used to store TinyOS <code>printf</code> messages befor ethey are flushed
-    is limited to a total of 250 bytes.  If you try and print more characters then
+    If you actually read the line printed above it you can see why.  The buffer
+    used to store TinyOS <code>printf</code> messages before they are flushed
+    is by default limited to 250 bytes.  If you try and print more characters than
     this before flushing, then only the first 250 characters will actually be printed.
-    As of now, this buffer size is fixed and can't be changed.  In the future we
-    hope to allow developers to specify custom buffer sizes at the time that
-    they include the PrintfC component in their configuration file.
+    This buffer size is configurable, however, by specifying the proper CFLAGS option
+    in your Makefile.
     </p>
+    <pre>
+CFLAGS += -DPRINTF_BUFFER_SIZE=XXX</pre>
     <p>
     Once the the <code>Printf</code> service has been stopped, the
     <code>PrintfControl.stopDone()</code> event is signaled and Led 2 is turned
@@ -315,17 +332,21 @@ event void PrintfFlush.flushDone(error_t error) {
     use the functionality provided by the <code>printf</code> library.
     </p>
     <ol>
-      <li>The buffer used by the <code>printf</code> library is limited to 250 bytes.
-          Do NOT try and increase this value.  It is unclear why, but at present,
-          larger buffer sizes result in messages being cut short when printed over the
-          serial line.  Tracking down
-          the source of this problem is on our list of things to do.</li>
       <li>In order to use the <code>printf</code> library, the <code>tos/lib/printf</code>
           directory must be in your include path.  The easiest way to include it is
           by adding the following line directly within the Makefile of your top
           level application:
           <pre>
-CFLAGS += -I$(TOSDIR)/lib/printf</pre></li>
+CFLAGS += -I$(TOSDIR)/lib/printf</pre>
+          Remember that changing the <code>printf</code> buffer size is done similarly:
+          <pre>
+CFLAGS += -DPRINTF_BUFFER_SIZE=XXX</pre>
+      </li>
+      <li>You MUST be sure to #include <code>"printf.h"</code> header file in
+          every component in which you would like to call the <code>printf()</code>
+          command.  Failure
+          to do so will result in obscure error messages making it difficult to identify
+          the problem.</li>
     </ol>
 
 <p>