MoteTrack User's Manual v2.1

by Konrad Lorincz
January 5, 2005
(updated July 28, 2006)
Harvard University

 

Table of Contents

  1. Introduction
    1. What is MoteTrack?
    2. About this Document and Release
  2. Software Installation Instruction
    1. Prerequisites
    2. Installation Verification
  3. Deployment
    1. Prerequisites
    2. Hardware placement
    3. Data collection
    4. Normal operation (location tracking)
  4. Miscellaneous
    1. Generating Documentation
    2. Interpreting the Leds
    3. Running Experiments
  5. Support Information
    1. General
    2. Frequently Asked Questions
    3. Copyright Notice

IMPORTANT: If your using a CC1000 radio more (like Mica2), read this.

 

Introduction

What is MoteTrack?

MoteTrack is a robust, decentralized RF-based location tracking system for motes.  The system runs entirely on motes and requires no wired infrastructure.  With just 25 beacon nodes deployed throughout one floor, the system achieves a 50th-percentile and 80th-percentile location-tracking accuracy of 1 meters and 1.7 meters respectively when diversifying the radio signal over 16 frequencies.  In addition, MoteTrack can tolerate the failure of up to 60% of the beacon nodes without severely degrading accuracy, making the system suitable for deployment in highly volatile conditions.

For further information, please visit the MoteTrack website at:
http://www.eecs.harvard.edu/~konrad/projects/motetrack/

About this Document and Release

This document describes how to install, deploy, and use MoteTrack v2.1.

Caveats of version 2.1

  • This release includes only the centralized version.  The difference between the centralized and decentralized versions is that in the centralized version the mobile mote stores the reference signature database and performs the location estimation.  In the decentralized version, the reference signature database is stored at the beacon motes, and the location estimation is performed by the beacon motes.  Furthermore, each beacon mote stores only a subset of the entire reference signature database, making the system highly scalable.
  • Fully supports motes using the CC2420 802.15.4 radios (e.g., Telos, MicaZ).
  • Partial support for Mica2 and Mica2Dot.  The only limitation is that only one (the default) frequency channel can be used.

Telos

MicaZ

Mica2

 
Software Installation Instructions

Prerequisites

  • This manual assumes that you have installed correctly TinyOS and all related tools on your system and know how to program in TinyOS.  If you don't, visit the TinyOS website for the code, installation instructions, and tutorial.  If you've never programmed in TinyOS, I highly recommend you do the TinyOS tutorial!
    • Download and install TinyOS 1.1.10 or higher.  (Actually, you can use an earlier version if the mote that you are programming is supported by the earlier version.  For example, MicaZ requires TinyOS 1.1.7 and TelosB requires TinyOS 1.1.10.)  The code, installation instruction, and tutorial can be found at
      http://www.tinyos.net/
  • Download and unpack MoteTrack v2.1.  The system can be unpacked in any directory.  The code can be obtained from the MoteTrack website
    http://www.eecs.harvard.edu/~konrad/projects/motetrack/
  • Optional:  To exercise the nesC code, you must have one mote.
  • IMPORTANT for CC1000 radio motes like Mica2!!!
    If your CC1000 radio is running at 915MHz, open the file
      "moteTrack/src/centralized/mobileMote/Makefile.common.in"
    and enable the 915MHz flag by uncommenting the line below.  If your CC1000 radio is running at 433MHz or 315MHz, then make sure the line is commented out (default).
       # PFLAGS += -DCC1000FREQ_915
     

Installation Verification

At this point TinyOS should be properly installed and MoteTrack v2.1 unpacked in a directory.  MoteTrack can run in one of 3 modes: (1) simulation mode *without* motes, (2) simulation mode *with* motes, (3) normal mode (on a deployed system only).  If the software is installed correctly, the system should run in the two simulation modes.  I highly recommend that you verify your software installation by running the two simulations.  By default, it will use the data collected in the second floor of Maxwell Dworkin, the computer science and electrical engineering building at Harvard University.
  • Simulation mode *without* motes [most simple to get working]

    Description: This will read from a file the reference signature database and the signatures, simulate the distributed version of estimating  signature locations and display the actual and estimated locations in the MapGUI.
     
    1. Prerequisites
      Include the "moteTrack" package in the java CLASSPATH
      Note: in "moteTrack/tools/java/moteTrack/Makefile", the "moteTrack" package is included in the java CLASSPATH via "..". This should work fine in most cases.
       
    2. MapGUI
      cd to "moteTrack/tools/java/moteTrack" and type
          make clean; make runMapGUI-simNoMotes

     

  • Simulation mode *with* motes

    Description: This uses the mobile mote and the MapGUI for visualization. The "MobileMote" is preloaded with a set of signatures who's locations it estimates periodically. The MobileMote then forwards the estimated location to the UART. The MapGUI with help from the serial receiver receives the location estimates forwarded by the MobileMote and displays them. (Note: since the MapGUI knows the actual locations of the signatures, it also displays the actual location of the signatures).
     
    1. Prerequisites
      Include the "moteTrack" package in the java CLASSPATH
      Note: in "moteTrack/tools/moteTrack/Makefile", the "moteTrack" package is included in the java CLASSPATH via "..". This should work fine in most cases.
       
    2. MobileMote
      Compile and install MobileMote using the simulation Makefile (i.e. Makefile.sim)!
      cd to "moteTrack/src/centralized/mobileMote" and type
         
      make -f Makefile.sim install micaz

      (Important: If your using a CC1000 radio mote like Mica2, read this!)
       
    3. SerialForwarder
      Start the serial forwarder located in
      "tinyos-1.x/tools/java/net/tinyos/sf/SerialForwarder.java".  It should be something like:
         
      java net.tinyos.sf.SerialForwarder -comm serial@COM1:micaz
       
    4. MapGUI
      cd to "moteTrack/tools/java/moteTrack" and type
          make clean; make runMapGUI-simWithMotes
 
Deployment

Prerequisites

  • A number of motes to be used as beacon motes.  You should have at least 10 beacon motes.
    • Optional:  I recommend that the beacon motes when deployed be plugged in to main power supply.  This will prevent the need to replace batteries.
  • One or mote motes to be used as the mobile mote.
  • A map in "jpg" format of the area being deployed.  This is required for collecting reference signatures.
    • The conversion ratio between number of pixels on the map and actual meters.  (This can be measured with a measuring tape and then count the number of pixels on the jpg map.)

Hardware Placement

  1. Decide how many frequencies and transmission powers you want to use
    • Diversifying the beacon messages over multiple frequencies and transmission powers will increase accuracy.  Using more frequencies will only increase accuracy.  Using more transmission powers will generally increase accuracy, however there is a tradeoff between a more diverse signature (which has a positive effect on accuracy) and hearing from less beacon motes when transmitting a low power (which has a negative effect on accuracy).  I recommend that you start with 1 transmission power at full strength and 4 different frequencies.  The table below summarizes the tradeoffs.
       
    Transmitting at multiple: Benefits Drawbacks
    Frequencies
    • increases accuracy (more diverse signature)
    • takes longer to collect a signature
    • signatures are larger and therefore take up more space
    • more message transmissions
    Powers
    • increases accuracy (more diverse signature)
    • takes longer to collect a signature
    • signatures are larger and therefore take up more space
    • more message transmissions
    • may decrease accuracy when combining at very low powers with high powers because at very low power the mobile mote hears from less beacons

     

    Multiple Frequencies
    (from ver. 2.x)
    Multiple Powers
    (from ver. 1.0)

    Used CC2420, 802.15.4 radio (i.e. MicaZ, Telos)

    Used CC1000, 433 MHz radio (i.e. Mica2)


    How it works
    :
    All variables in this section are listed in "moteTrack/src/centralized/common/MoteTrackParams.h"

    At initialization, each beacon mote starts with a random frequency from the specified frequencies (this helps minimize packet collisions).  The beacon mote tunes to the first frequency and then transmits a beacon message at each of the specified transmission powers.  Then, it tunes to the next frequency and again it transmits a beacon message at each transmission power, and so on.  The constant "BEACON_SEND_PERIOD" specifies the interval between beacon messages.  (You may set this to 14 or higher, i.e., do not transmit at more than about 70 Hz!)

    The mobile mote can only listen on one frequency at a time and therefore it will not receive messages sent on a different frequency.  To guarantee that the mobile mote receives a beacon message at its current frequency and every transmission power from each beacon mote, the mobile mote must listen at the current frequency long enough for a beacon mote to cycle through one round of all its frequencies and transmission powers.  More specifically, the mobile mote must listen at the current frequency for:
    "FREQ_LISTEN_PERIOD = NBR_FREQCHANNELS * NBR_TXPOWERS * BEACON_SEND_PERIOD". 
     Next the beacon mote tunes to the next frequency and again listens for "FREQ_LISTEN_PERIOD", and so on.

    Note:  This is a very simple scheme which has the advantage of simplicity but requires a longer time to collect a signature.  To decrease the amount of time required to collect a signature, implement a frequency hopping synchronization scheme between the beacon motes and the mobile mote.
     

  2. Program each of the motes that will act as beacon motes with the beacon mote code.
    • cd to "moteTrack/src/decentralized/beaconMote" and type something like:
         
      make install micaz.10

      Important:  Make sure that each beacon mote has a unique ID!  Unique IDs are necessary to distinguish between beacon motes.  The IDs can be 1 or higher.  DO NOT use 0 because 0 is reserved!

      Optional:  If you're going to reprogram the beacon motes frequently, then I recommend that you look into reprogramming the motes over the radio (see Deluge: TinyOS Network Programming http://www.cs.berkeley.edu/~jwhui/research/projects/deluge/) or set up a testbed that makes it possible to reprogram the motes from a web browser (see MoteLab: http://motelab.eecs.harvard.edu/).
       
  3. Place the beacon motes
    • Place the beacon motes throughout your environment such that they are more or less evenly spread out.  To get good accuracy, you should have enough beacon motes so that at every location the mobile mote can hear from about 6 beacon motes (when transmitting at the default power of 0 dBm).

      Optional:  I recommend that the beacon motes when deployed be plugged in to main power supply.  This will prevent the need to replace batteries.

Data Collection

This section describes how to collect reference signatures and how to program the mobile mote with the collected data.  At this point the beacon motes should be deployed and they should be transmitting beacon messages.
  1. Setup the "jpg" map
    • Obtain a map in "jpg" of the area of deployment.  The map should be fairly large (e.g. 2000x800 pixels).  Name this map "mapNormalScale.jpg" and copy it to "moteTrack/tools/java/moteTrack/resources".
    • Create a smaller version of the map (prefereably about 2 times smaller).  Name this map "mapSmallScale.jpg" and copy it to "moteTrack/tools/java/moteTrack/resources".  (The two map sizes will allow you to zoom in and out when collecting data.)
    • Open "moteTrack/tools/java/moteTrack/dataCollection/DataCollection.java" and locate the array "mapScales".  Leave the first entry as "1.0", but chance the second entry to be the ratio between the normal and smaller maps.  For example if the smaller map is 2 times smaller than the normal sized map, then the second entry should be "1.0/2.0".
    • Open "moteTrack/tools/java/moteTrack/mapGUI/MapGUI.java" and locate the variable "mapScale".  Change the value to be the same as above (i.e. the ratio between the normal and smaller maps).  For example if the smaller map is 2 times smaller than the normal sized map, then set the value to be "1.0/2.0".
    • Open "moteTrack/tools/java/moteTrack/common/MoteTrack.java" and locate the variable "METERS_PER_PIXEL".  Change the value to reflect the ratio between then number of pixels in "mapNormalScale.jpg" that correspond to a meter.
       
  2. Set the data collection period
    • Open "moteTrack/src/centralized/common/MoteTrackParams.h".  You will need to know the values of the variables NBR_FREQCHANNELS, NBR_FREQCHANNELS,  NBR_TXPOWERS, and BEACON_SEND_PERIOD for the formula below.
    • Open "moteTrack/tools/java/moteTrack/dataCollection/DataCollection.java" and locate the variable "DATA_COLLECTION_PERIOD"
    • Decide how many samples you want the mobile mote to receive at each <frequency, txPower, beaconMote>.  I recommend at least 5 samples.
    • Set "DATA_COLLECTION_PERIOD" according to the formula below (also specified in the file)

      DATA_COLLECTION_PERIOD = nbrDesiredSamples * NBR_FREQCHANNELS * NBR_FREQCHANNELS * NBR_TXPOWERS * BEACON_SEND_PERIOD
       
  3. Program the MobileMote for data collection
    • Compile and install MobileMote using the data collection Makefile (i.e. Makefile.dataCollect)!
      cd to "moteTrack/src/centralized/mobileMote" and type
         
      make -f Makefile.dataCollect install micaz

      (Important: If your using a CC1000 radio mote like Mica2, read this!)
       
  4. Setup the laptop for collecting data
    • Attach the mobile mote to the laptop that will be used for collecting data.
    • Start the SerialForwarder on the laptop
      "tinyos-1.x/tools/java/net/tinyos/sf/SerialForwarder.java".  It should be something like:
         
      java net.tinyos.sf.SerialForwarder -comm serial@COM1:micaz
    • Start the java data collection GUI
      cd to "moteTrack/tools/java/moteTrack" and type:
          make clean; make runDataCol
       
  5. Collect Data
    • Using the mouse, click on the map where you want to collect the first reference signature.  For finer adjustments, hold the Ctrl key and press one of the arrow keys.   Notice that the "Coordinates" in the "Data Collection Control" section on the left hand side get updated automatically.  If you want to, change the "Location ID" and the "Output file postfix".  For example if you are in the hall, than choose "-hall.dat".  To zoom in and out of the map, click on "View -> Toggle Map Size".
    • Click the "Start Data Collection" button.  A confirmation window will pop up asking you to confirm the data.  If everything is OK, click "Yes".  (While the data is being collected, every time the mobile mote gets a beacon message, you should see a dot "." appear on the screen.  The collected data will appear in the file "100-hall.dat".  Repeat this procedure for all the reference signatures.
    • Concatenate all the reference signatures into one file by typing something like:
          cat *.dat > trainingData_hall-doorClosed.dat

  6. Generate the database to be loaded onto the mobile mote
    • Copy the reference signatures file (e.g. "trainingData_hall-doorClosed.dat") to "moteTrack/tools/java/moteTrack/resources".
    • Open "moteTrack/tools/java/moteTrack/genRefSignatureDB/GenRefSignatureDB.java" and locate the variables "freqChansToUse", "txPowersToUse" and "nbrRFSignalsInSignature".  Change these variables according to what you want to load into the motes.  I recommed that you use 4 frequency channels, one txPower (set to 0dBm) and set nbrRFSignalsInSignature between  15-20.  Locate "trainingRefSigsFile" and "testingRefSigsFile" and make sure they refer to the files where you collected reference signatures.
    • Generate the header files containing the collected data
      cd to "moteTrack/tools/java/moteTrack" and type:
          make clean; make runGenDB

      Two files "RefSignatureDB.h" and "SignatureDB.h", should have been created and copied to the "moteTrack/src/centralized/common" directory.  The previous files should have been renamed with the "_OLD" postfix.

Normal Operation (location tracking)

At this point you should have (1) the beacon motes deployed and sending beacon messages, (2) collected the reference signature database and (3) generated the RefSignatureDB.h and SignatureDB.h files and placed them in "moteTrack/src/centralized/common".  Next, we will program the mobile mote in MODE_NORMAL with the RefSignatureDB.h.
  1. Obtain the coordinates of the Beacon Motes'
    • Determine the coordinates in pixels of the beacon motes and enter them in the file "moteTrack/tools/java/moteTrack/resources/coordinatesMotes.txt".  Please use the exact same format as the sample file that came with the distribution. The format is "beaconMoteID  (x, y, z)".

      Note:  The MoteTrack protocol does not require the knowledge of the beacon motes' coordinates!  The reason why you must supply them is because the java map GUI shows the closest beacon mote when estimating locations and it's also required for some of the experiments.  If you don't wish to supply the beacon motes' coordinates, you may modify the code to not require this step.
       
  2. Determine how often the mobile mote should estimate it's location
    • Open "moteTrack/src/centralized/common/MoteTrackParams.h" and locate the variable "ESTLOC_PERIOD".  This variable specifies how long the mobile mote should collect beacon messages for a signature.  The mobile mote takes all the beacon messages received in the last "ESTLOC_PERIOD", constructs a signature and estimates the location of the signature.  This variable is used by the mobile mote when it is running in MODE_NORMAL.
    • Decide how many samples you want the mobile mote to receive at each <frequency, txPower, beaconMote>.  I recommend at least 3 samples.
    • Set "ESTLOC_PERIOD" according to the formula below (also specified in the file):

      ESTLOC_PERIOD = nbrDesiredSamples * NBR_FREQCHANNELS * NBR_FREQCHANNELS * NBR_TXPOWERS * BEACON_SEND_PERIOD
       
      Warning: Do not multiply constants because it may cause an overflow!  Calculate the number for ESTLOC_PERIOD and write it with the "L" for long (e.g. ESTLOC_PERIOD = 4800L)
       
  3. Program the MobileMote
    • Compile and install MobileMote using the normal (default) Makefile (i.e. Makefile)!
      cd to "moteTrack/src/centralized/mobileMote" and type
         
      make -f Makefile install micaz
        
      or equivalently
         
      make install micaz
       
  4. Track your location
    • Attach the mobile mote to the laptop that will be used for tracking your location.
    • Start the SerialForwarder on the laptop
      "tinyos-1.x/tools/java/net/tinyos/sf/SerialForwarder.java".  It should be something like:
         
      java net.tinyos.sf.SerialForwarder -comm serial@COM1:micaz
    • Start the java map GUI
      cd to "moteTrack/tools/java/moteTrack" and type:
          make clean; make runMapGUI-normal

You should now see your estimated location on map.  The red dot is the latest estimate while the gray dots are the previous location estimates.

 
Miscellaneous

Generating Documentation

  • For nesC code
    • To generate the documentation for a nesc component, go to the component's directory and type:
          make docs <PLATFORM>
      For example: cd to "moteTrack/src/centralized/beaconMote" and type
          make docs telos

      Note: Depending on where you placed moteTrack, you may have to change the "-topdir" flag in the Makefile!
    • The documentation will be placed in "moteTrack/docs/nescdoc"
       
  • For java code
    • To generate the documentation for all java code, go to "moteTrack/tools/java/moteTrack" and type:
          make doc
    • The documentation will be placed in "moteTrack/docs/javadoc" 

Interpreting the Leds

This section describes how to interpret the leds on the motes.
  • BeaconMote
    • green led blinks:  sent a beacon msg. led-on (trying to send), led-off (send successful)
    • red led:  not used.
    • yellow led blinks:  changed to the next frequency.
       
  • MobileMote
    • green led blinks:   forwarded a msg over the UART.  led-on (trying to send), led-off (send successful)
    • red led toggles:   received a beacon msg.
    • yellow led toggles:  changed to the next frequency.

Running Experiments

This section describes how to run experiments to generate graphs such as error distance, the effect of using multiple frequencies and transmission powers, etc.

Prerequisites

  • You must have "gnuplot" installed, because the java program calls gnuplot to generate the plots!

Instructions

  1. Obtain the coordinates of the Beacon Motes'
    • If you haven't already done this step :
      Determine the coordinates in pixels of the beacon motes and enter them in the file "moteTrack/tools/java/moteTrack/resources/coordinatesMotes.txt".  Please use the exact same format as the sample file that came with the distribution. The format is "beaconMoteID  (x, y, z)".

      Note:  The MoteTrack protocol does not require the knowledge of the beacon motes' coordinates!  The reason why you must supply them is because the java map GUI shows the closest beacon mote when estimating locations and it's also required for some of the experiments.  If you don't wish to supply the beacon motes' coordinates, you may modify the code to not require this step.
       
  2. Edit the experiments file
    • Open the experiments file "moteTrack/tools/java/moteTrack/experiments/Experiments.java" and locate the function "runAllExpMT2()"
    • Uncomment the experiments you want to run, or write your own.
       
  3. Run the experiments
    • cd to "moteTrack/tools/java/moteTrack" and type
          make clean; make runExp

      This will run your experiments and place them in the "moteTrack/tools/java/moteTrack/plots" directory.
 
Support Information

General

Frequently Asked Questions

  • Problem:  I can gather data into a ".dat" file, and the "make runGenDB" command produces no errors, yet my database size is zero or all entries are zeros.  It is properly constructed otherwise, but contains no signatures.
    • Solution:  The problem is most likely due to a mismatch between the FREQCHANNELS[] and TXPOWERS[] in MoteTrackParams.h (which generates the collected ".data" file) and the freqChansToUse[] and txPowersToUse[] set on the java side (GenRefSignatureDB.java).  Make sure that the frequency channels and transmission powers match.  They should also match with your data collected (i.e. your ".data" file).
       
  • Problem:  I am running under cygwin with Windows XP.  When I try to program a mica2 or micaz mote like this
      $ make mica2 install
      $ make mica2 install.10
      $ make mica2 install.10 mib510,COM4

    on COM4, either nothing happens or I get errors.
    • Solution:  Try installing by using Linux convention, (i.e. /dev/ttyS3), where it's your windows COM port number minus 1!
        $ make mica2 install.10 mib510,/dev/ttyS3

Copyright Notice

Copyright (c) 2005
The President and Fellows of Harvard College.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE UNIVERSITY OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.