Place Lab Users' Quick Start Guide

Place Lab: A privacy-observant location system

Documentation

Place Lab is software providing low-cost, easy-to-use user positioning for location-enhanced computing applications. Unlike existing positioning systems, Place Lab tries to provide positioning which works worldwide, both indoors and out, and is privacy observant. Place Lab clients can determine their location privately without constant interaction with a central service.

The Place Lab approach is to allow commodity hardware clients like notebooks, PDAs and cell phones to locate themselves by listening for radio beacons such as 802.11 access points, GSM cell phone towers, and fixed Bluetooth devices that already exist in the environment. These beacons all have unique or semi-unique IDs, for example, a MAC address. Clients compute their own location by hearing one or more IDs, looking up the associated beacons' positions in a locally cached map, and estimating their own position referenced to the beacons' positions. To read an overview research publication about Place Lab, refer to the technical report Place Lab: Device Positioning Using Radio Beacons in the Wild.

This sounds great! How do I install Place Lab for my device?

Go to http://www.placelab.org/toolkit/ and download the proper distribution for your device. A hardware compatibility list is available. Each platform-specific distribution includes almost everything needed to run Place Lab including source-code, pre-compiled jar files, and platform-specific executables and scripts. You only need to get a Java run-time if you don't already have one on your system (available from Sun or IBM). If you are installing on Windows XP, make sure you follow the spotter installation instructions in the readme file in the native directory.

I've got Place Lab installed on my device. What should I run to verify my installation and get acquainted with Place Lab's basic features?

Scripts in the run/ directory of your Place Lab installation can be used to check your installation, run some demos, and gain an understanding of Place Lab's basic capabilities.

Verify that your device can scan for 802.11 APs using WiFiSpotterExample and APViewer. APViewer shows nearby access points including their MAC address, name, and signal strength. Until you complete step 2 below, APViewer will provide no position estimate.
For the device to be able to compute its actual location you need to download a snapshot of the radio beacons (APs, GSM towers, fixed Bluetooth devices) for your area using the MapLoaderGUI tool. Unless you happen to be located in an area covered by our Seattle area test database, you should create a wigle.net account and use it with Place Lab. Wigle.net is an online wardriving repository with >7 million 802.11 access points from around the world. (Note that placelab.org used to have an online database, but this was taken down in 2006 as major research on on the project ceased.)
Run APViewer again. Assuming the MapLoaderGUI tool found known beacons in your area, APViewer should now present Place Lab's estimate of your latitude and longitude derived from the radio beacons currently in range.
You can run the SeattleMapDemo sample to see a full featured map tracking visualization using a prerecorded log and map created in the Seattle area. For this demo to work, make sure you first use the MapLoaderGUI to download beacons for the Seattle area (note: it's probably easiest just to retrieve all of Washington State. Note that once you create your own mapwads (discussed in the developer's tutorial), you can use the org.placelab.demo.MapDemo class run internally by the SeattleMapDemo script to show live tracking on maps of your own area.

Help! My area has no beacons in the database! Or, how do I contribute new beacons to the database to increase the accuracy and coverage of Place Lab?

Gathering and submitting trace logs of beacons in your area for the mutual benefit of all Place Lab users is a process called stumbling. Stumbling logs should be submitted to wigle.net. Refer to the Place Lab Laptop Stumbling HOWTO Guide for instructions on using laptop to stumble for WiFi, Bluetooth, and GSM through a slave phone. Refer to the Place Lab Phone Stumbling HOWTO Guide for instructions on using a phone without a laptop to stumble for GSM (followed by the Place Lab Bluetooth Phone to PC Data Transfer HOWTO Guide for general instructions on transferring data such as stumbler logs from the phone to a PC over Bluetooth).

Where does Place Lab store its configuration data? What is in the placelab.ini file?

The placelabdata directory contains all the beacon database snapshots, maps, icons, and other data used by placelab. The directory is located in your home directory (e.g.

C:\Documents and
Settings\myusername\

on Windows XP) by default, although the distribution has a placelabdata directory which is used by the sample scripts in the run/ directory. The placelab.ini file contains many customization settings including Wigle.net login information. Here are the system properties used by Place Lab which may be defined using -D options to the virtual machine or in the placelab.ini file:

placelab.ini=<path> : a file to load all these properties out of. default is ~/placelab.ini
placelab.dir=<path> : location of the placelabdata directory for all the placelab support files. default is ~/placelabdata
placelab.disableapdrawing=true|false : controls the AP overlay in MapDemo
placelab.showrssi=true|false : controls the signal strength coloring of aps in MapDemo
placelab.showconfidence=true|false : controls the confidence circle around the reticle in MapDemo
placelab.demofps=<int> : controls the rate at which log files are polled in MapDemo
placelab.mapwaddir=<path> : controls the directory mapwads will be searched for in if they cannot be found on the current path
placelab.gps_device=<device> : on windows it will be COMx, or on mac/linux it will be /dev/something. If you are trying to stumble, refer to the Place Lab Laptop Stumbling HOWTO Guide
placelab.gps_speed=<int> : default (and NMEA standard) is 4800. If you are trying to stumble, refer to the Place Lab Laptop Stumbling HOWTO Guide
placelab.landmarks.dir=<path> : directory to store landmarks in for the JSR-179 implementation
placelab.mapper=JDBM|HSQL : sets the database to use for the local beacon cache
placelab.wigle_username=<username> : your login at wigle.net
placelab.wigle_password=<password> : your password at wigle.net
placelab.stumbler.newapcmd=<executable path> : Refer to the Place Lab Laptop Stumbling HOWTO Guide
placelab.stumbler.lostgpscmd=<executable path> : Refer to the Place Lab Laptop Stumbling HOWTO Guide
placelab.stumbler.lockedgpscmd=<executable path> : Refer to the Place Lab Laptop Stumbling HOWTO Guide
placelab.StumblerFunnel.timeout=<time in ms> : Refer to the Place Lab Laptop Stumbling HOWTO Guide
placelab.stumbler_bluetooth=true|false : Refer to the Place Lab Laptop Stumbling HOWTO Guide
placelab.cellphone=id:port : Refer to the Place Lab Laptop Stumbling HOWTO Guide

I'm ready to create my own applications using Place Lab! Where can I find information for developers?

Place Lab supports five ways of communicating location information to applications:

Direct Linking. Applications may link against the Place Lab Java library and invoke a single method to start the location tracking service.
Daemon. For lighter-weight interactions, Place Lab can be run in daemon mode and applications can query Place Lab via loopback HTTP. This HTTP interface allows programs written in most languages and styles to use Place Lab.
Web Proxy. Place Lab supports location-enhanced web services by augmenting outgoing HTTP requests with extension headers that denote the user's location. By setting their web browser to use the Place Lab daemon's web proxy (in the same way one uses a corporate firewall's proxy), web services that understand our HTTP headers can provide location-based service to the user.
JSR 0179. To support existing Java location-based applications Place Lab supports the JSR 0179 Java location API.
NMEA 0183. Place Lab provides a virtual serial-port interface that can mimic an external GPS unit by emitting NMEA 0183 navigation sentences in the same format generated by real GPS hardware.

To get started developing with Place Lab, please refer to the more detailed Place Lab Developers' Tutorial for information such as CVS access to the Place Lab code and an explanation of the underlying Place Lab architecture and APIs.