Table of Contents

1. Introduction
2. Installation
3. Command-line options and system properties

Introduction

Installation

Required libraries

• rxtxSerial 2.1-7pre17 (you will find the jar in /placelab/lib and the jnilib in /placelab/native/<your platform=>/rxtx)
• swt 3.0 release (find the jar in /placelab/lib and the jnilib(s) in /placelab/lib/swt/<your platform=>/)
• jface 3.0 release (find the jar in /placelab/lib)
• Additionally to do wifi spotting you will need the placelab wifi spotter library (find in /placelab/native//spotter)
• To do bluetooth stumbling you will need Windows XP SP2 and Bluecove (find BlueCove in /placelab/lib/bluetooth)
• GSM stumbling has all the bluetooth requirements, plus the requirement of a series 60 phone with the placelab-phone distribution installed on it.

OS-specific instructions

Instructions for Linux (thanks to yu-chung)

Permissions. Make sure /var/lock is group writable and your id is also in the same group of the serial device (eg /dev/ttyS0) and /var/lock. In RedHat/Fedora, add "uucp" and "lock" into your group in /etc/groups. Also you have to logout or exit the X window to make the permission change effective. If the permissions aren't set correctly, you might get "lock file denied" messages from rxtx.

USB-Serial port converterIf you are using a usb-serial converter cable for the GPS, you need the usbserial kernel module. Ideally the module will auto load but if not you can use "modprobe usbserial" to install it manually.

• Run "dmesg" to see which device file is associated with the GPS, typically it is "/dev/ttyUSB0"
• For some reason the rxtx library only accepts device file /dev/ttyS* . You can run "ln -s /dev/ttyUSB0 /dev/ttyS100". Later run the stumbler with "placelab.gps_device=/dev/ttyS100"

Scanning mode support.If you run the stumbler but no beacons shows up, this is because some cards may not support scanning mode with default kernel/pcmcia module. For example, the orinoco card. Try "iwlist ethX scan" and see if it works. If not, you can download scanning patch from http://www.ozlabs.org/people/dgibson/dldwd/. On Fedora, you just need to download the tar ball, compile it and replace all related kernel module (ex *.ko) with current modules in /lib/modules. No need to reboot. For prism2 based-card, the host-ap driver support scanning and monitoring. You can find more info by Googling hostap.

Instructions for Mac OS

Hooking up your gps

		using /dev/tty.USA19H1b1P1.1
		Devel Library
		=========================================
		Native lib Version = RXTX-2.1-7pre17
		Java lib Version   = RXTX-2.1-7pre17
		$GPRMC,,V,,,,,,,120704,17.1,E,N*0F
		$GPRMB,V,,,,,,,,,,,,A,N*13
		$GPGGA,,,,,,0,00,,,M,,M,,*66
		$GPGSA,A,1,,,,,,,,,,,,,,,*1E
		$GPGSV,3,1,09,01,72,002,00,04,21,303,00,11,04,200,00,13,31,290,00*7E
		$GPGSV,3,2,09,16,42,108,00,20,73,187,00,24,02,334,00,25,24,053,00*76
		$GPGSV,3,3,09,27,09,233,00*4E
	and so on ...

It is also possible to use bluetooth gps devices. If you have windows xp sp2 set the system property placelab.gps_device=bluetooth and placelab.stumble_bluetooth=true (this can be done either with the -D switch on the command line or by placing it in your placelab.ini). PlacelabStumblerGUI will automatically detect and begin using your gps device. If it fails to connect to your device, try removing the device from your computer in the Bluetooth control panel. PlacelabStumblerGUI will automagically re-pair with the device.

If you don't have windows xp sp2, you'll have to use a bluetooth virtual serial port utility. For mac os, you'll find that at /Applications/Utilities/Bluetooth Serial Utility.app.

Some gps devices must be put into nmea mode before they will work. I just fiddle with them until I find the menu for it, but you may have more luck referring to the documentation for your gps device.

Stumbling for bluetooth beacons (win xp sp2 only)

Stumbling for 802.11, bluetooth, and GSM (win xp sp2 + nokia series 60 phone only)

Note that if you are trying to stumble for GSM alone using only a phone (i.e. no laptop involved), you should read the Place Lab Phone Stumbler HOWTO Guide instead of this guide.

Before doing anything, make sure you pair your phone with the computer you will be running PlacelabStumblerGUI on. To do this, press the menu button on the phone (blue button on the far left) and go to connect->bluetooth and click over to the "Paired Devices" tab. Click options, choose "New Paired Device" and select your computer (entering in the passcode on both the phone and computer if necessary) Once you have the pairing set up, select the computer in the pairing tab on the phone and in the options menu choose "Set as authorised"

Now navigate back to the phone's launcher menu and start the Placelab application (if its not already running) to start the GSM spotter on the phone. Leave that running and go start "GSMBT" (answer yes to both questions it asks).

Once GSMBT starts up it will display some statistics on the number of gsm towers seen and it will also display the bluetooth id and channel the program is listening on. Launch PlacelabStumblerGUI with the system property placelab.cellphone set to that id and channel (it will be of the form xxxxxxxxxxxx:x where the last x is the channel) and gsm stumbling will be enabled.

Transferring the data to a PC for uploading to placelab.org is the last step in GSM stumbling. The LogUploadProxy tool transfers stumbler logs from the phone to the PC ready for uploading to placelab.org. The bytes that are received are in compressed format which the proxy decompresses before uploading. More information on transferring data from the phone can be found in the Phone Bluethooth Transfer HOWTO.

Command line options and system properties

System Properties

• placelab.StumblerFunnel.timeout=time_in_ms This controls how long the stumbler will wait for an update from the gps device before it will go out and collect beacon measurements without gps. I set mine to 3000 because all the gps devices I've used produce usable measurements once every 1 or 2 seconds, and I like to give a little extra time just in case.
• placelab.gps_device=gps_device This must be set to the serial device where the gps is connected. If you don't set it, or set it incorrectly, the stumbler will still work, but you won't get gps readings. An error message will be printed to stdout. With Windows XP sp2, you may also specify bluetooth here (see gps section above).
• placelab.stumble_bluetooth=true|false Default is false. See bluetooth section above.
• placelab.cellphone=phone_id:phone_channel (e.g. 000F6D8368FF:4) Used for gsm stumbling with a paired nokia s60 phone. See GSM section above.
• placelab.gps_speed=baudrate The NMEA specification says that a baud rate of 4800 is to be used to communicate with the gps device. If you don't set this property, this is what I default to. If your gps device can support a higher speed, taking advantage of it may allow you to get more frequent updates from the device.
• placelab.stumbler.newapcmd If you are using the AudioNotifier (see below) this will let you specify a command line to be executed when a new ap is seen.
• placelab.stumbler.lostgpscmd Same as above but for lost gps signal
• placelab.stumbler.lockedgpscmd Same as above but for acquired a gps fix

Command line options

• --log /path/to/log (Text stumbler only, the gui stumbler has a gui save dialog) This will save everything seen to the log file specified. Note that the stumbler will choose a unique name for the log if the one you pass already exists.
• --a (Text stumbler only, the gui stumbler uses --audio) Enables the AudioNotifier which will play sounds when new aps are heard, either using defaults for the os you are using (windows and mac) or by executing the commands corresponding to the placelab.stumbler.* system properties above.
• --audio (gui stumbler only, the text stumbler uses --a)