Robust Localization with Cricket
--------------------------------
David Moore, John Leonard, Daniela Rus, Seth Teller

http://cgr.csail.mit.edu/netloc

Please send any comments, questions, or bug reports to:
David Moore <dcm@csail.mit.edu>


PREREQUISITES

This code requires TinyOS 1.1.6 or greater.  TinyOS can be obtained from
http://www.tinyos.net/.  The latest version is obtained by first
installing TinyOS 1.1.0 and then applying the update to the latest point
release.  As of this writing, the latest version is 1.1.7.

To run the algorithm on real devices, you must obtain Crickets from
either MIT or Crossbow.  They are available for sale at:
http://www.xbow.com/Products/productsdetails.aspx?sid=116

Without physical devices, the algorithm can still be simulated on a
PC.  The 'cricket_pc' TinyOS platform, provided in this package, allows
such simulation.


INSTALLATION

1. Unpack the archive, cricket.tar.gz, using 'tar -xvzf cricket.tar.gz'
2. cd cricket/
3. Create a symlink from your TinyOS directory to the new platforms using:
    ln -s $PWD/tos/tos/platform/cricket $TOSDIR/platform
    ln -s $PWD/tos/tos/platform/cricket_pc $TOSDIR/platform

Installation is now complete!


COMPILING AND RUNNING

The TinyOS application that runs the sensor network localization algorithm
is provided in the tos/apps/CricketRobustLoc/ directory.  Assuming TinyOS
has been installed properly and the installation instructions above have
been followed, the following command, executed from the CricketRobustLoc
directory, will compile the application:
    make cricket
    
Note that some compiler warnings are normal and cannot be avoided.

The resulting executable can be installed onto Cricket hardware with
a MIB510 programming board using the following command:
    make cricket install MIB510=/dev/ttyS0

Replace /dev/ttyS0 with the device file of your serial port.  In order
to compile to the application to a PC target, allowing simulation of
the algorithm, compile with:
    make cricket_pc

This command produces an PC executable as build/cricket_pc/main.exe
in the traditional fashion of the TOSSIM TinyOS simulator.  Please
refer to the TOSSIM documentation at:
    http://www.tinyos.net/tinyos-1.x/doc/nido.pdf

An additional command line argument '-d' is available with the Cricket
TOSSIM executable that allows you to provide a template file that
contains the set of distance measurements to be used by the simulated
Crickets.  The format of this file is not yet documented.

Upon running the application on a Cricket (either a real Cricket or
using TOSSIM), the device will output text to the serial port (standard
output in the case of TOSSIM) that indicates the status and results
of the localization algorithm.  Applications, as described below,
are included in the package to make use of this data.


INCLUDED APPLICATIONS

src/rwser:
    rwser is simple utility to make it easy to read cricket output from
    the serial port.  Compile by typing 'make'.  When run, rwser reads
    from the serial port and dumps any text to standard output.  It can
    be run in interactive mode using 'rwser -i' in which case any text
    typed is also sent to the serial port.  Type 'rwser --help' for
    a complete list of options.

src/robustloc/glcricket:
    glcricket is a graphical utility that renders the output of the
    robust localization on-screen to allow the user to view the
    localization results in real time.  Compile with 'make'.  By default,
    it opens the serial and reads any text from the Crickets.  The
    localization results are displayed on-screen in real time.  It
    can also be run on previously captured data using 'glcricket -i file'
    where file is a text file containing Cricket output.  For example,
    to capture this data run 'rwser -t > file'.

    glcricket requires X-windows and a working installation of the
    OpenGL libraries.