updates

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

diff --git a/doc/html/tutorial/lesson15.html b/doc/html/tutorial/lesson15.html
index 8938d23cb8a44e76982096a802927336c0942e17..5e17b9dbd50afa3d79ef749f991dbb0a3e05126b 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>
@@ -119,17 +119,33 @@
     At present, this application is not included in
     the official TinyOS distribution (<= 2.0.2).  If you are using TinyOS
     from a cvs checkout, you will find it located under
-    <code>apps/tests/TestPrintf</code>.  Otherwise, you can obtain it from
+    <code>apps/tutorials/Printf</code>.  Otherwise, you can obtain it from
     cvs by running the following set of commands from a terminal window:
     </p>
 
     <pre>
-cd $TOSROOT/apps/tests
+cd $TOSROOT/apps/tutorials
 cvs -d:pserver:anonymous@tinyos.cvs.sourceforge.net:/cvsroot/tinyos login
-cvs -z3 -d:pserver:anonymous@tinyos.cvs.sourceforge.net:/cvsroot/tinyos co -P -d TestPrintf tinyos-2.x/apps/tests/TestPrintf</pre>
+cvs -z3 -d:pserver:anonymous@tinyos.cvs.sourceforge.net:/cvsroot/tinyos co -P -d Printf tinyos-2.x/apps/tutorials/Printf</pre>
     <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>
@@ -284,12 +300,13 @@ event void PrintfFlush.flushDone(error_t error) {
     Notice that the last line of output is cut short before being fully printed.
     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 limited to a total of 250 bytes.  If you try and print more characters than
+    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>
@@ -353,9 +374,8 @@ Enjoy!!
 <hr>
 <center>
 <p>&lt;&nbsp;<b><a href="lesson13.html">Previous Lesson</a></b> |&nbsp; <b><a
- href="index.html">Top</a></b> &nbsp;|&nbsp;
+ href="index.html">Top</a></b> &nbsp;|&nbsp; <b><a href="lesson16.html">Next Lesson </a>&nbsp;&gt;</b>
 </center>
 
-
 </body>
 </html>