How to use Skyhook Precision Location SDK on a Raspberry Pi by skyhookwireless.com

Information and credit for this tut goes to skyhookwireless.com
http://www.skyhookwireless.com/devices/raspberry_pi_cartracker_location_tutorial

This tutorial will demonstrate how to use Skyhook location on a Raspberry Pi device running Raspbian Linux.

In this tutorial you will learn how to:

Configure your Raspberry Pi device with Wi-Fi

Install the Skyhook Precision Location SDK on your Raspberry Pi

Find location on the device while connected to the Internet and while disconnected using Skyhook Offline Location

Look up offline location

Build a map of your trip in KML. KML is an XML file format that specifies a set of features (placemarks, images, polygons, 3D models, textual descriptions, etc.) for display in geospatial software.

The tutorial leads you through the process of building a tracking device that:

(i) turns on and off with the power source, and
(ii) connects to the Internet only when in-range of a known, pre-configured Wi-Fi network

The device will continuously record its location whether connected to the Internet or not, and will dynamically detect when it is connected to the Internet so it can reconcile previous locations and build a trip map KML file for each trip the car takes.

What you need:

Raspberry Pi board - this tutorial was developed using a Raspberry Pi Model B which is equipped with 512MB of RAM and a 700MHz Broadcom ARM processor. The Pi Zero work as well.

USB Wi-Fi device - we used one with a Realtek chipset. Most off-the-shelf USB Wi-Fi devices should work. For this tutorial we tried Ralink and Realtek chipsets.

Case - we used a pre-made plastic case for the Raspberry Pi. Optional

Power adapter - a standard USB car power adapter. A cable designed for an Android phone, or any device with a micro-USB connector, should work.

SD Card - we use a 16GB micro-SD card with a standard SD card adapter

Operating System version - For this project we used Raspbian Linux, Wheezy version.

Follow the instructions at http://www.raspberrypi.org/downloads to set up a standard Raspbian installation.

Once you’ve burned the image to your SD card and booted the system, set it up to start up with a command-prompt login - not using the X window GUI. You’ll need to connect a keyboard and a monitor to do this.

Once you’ve booted the machine, you can run the configuration script:

sudo raspi-config

Part 2: Connecting Your Raspberry Pi to Your Network

The easiest way to connect your device to your network is using wired ethernet. If you have a wired ethernet network, just plug your device into your router or switch. Assuming you’re using DHCP your router will automatically assign an IP address to the Raspberry Pi and it will automatically connect. If you would rather connect to your network using Wi-Fi, you will need to modify the /etc/wpa_supplicant/wpa_supplicant.conf file. To generate the text you need to add type the following. Replace “mywifi” with the SSID of your network and “mypw” with your passphrase.

sudo bash
wpa_passphrase mywifi mypw >> /etc/wpa_supplicant/wpa_supplicant.conf

Reboot to bring up the device and have it connect to the network. Once it has booted up you can find out the IP address by typing:

ifconfig wlan0

Note the IP address - we’ll use 10.100.1.5 here as an example. Now you can connect to the Raspberry Pi remotely using the ssh and scp tools. To log in to the Raspberry Pi from a Mac or Linux machine you can type:

ssh [email protected]

The password is “raspberry”. You can also use scp to copy files to the device. At this point you can disconnect the monitor and keyboard if you wish.

Part 3: Installing Skyhook Precision Location

First you will need to get the latest Skyhook Precision SDK from my.skyhookwireless.com. To do this, follow these steps:

Create a My Skyhook account if you don’t already have one by going to my.skyhookwireless.com/register.
Create a new Precision Location project. Note your API key. You can get back to this any time at my.skyhookwireless.com/dashboard.
Download the Raspberry Pi Linux SDK zip file from my.skyhookwireless.com/resources.
Extract the zip file. The important files are libwpsapi.so and wpsapi.h.
From your remote computer copy the libwpsapi.so, wpsapi.h, and demo source files to the Rasberry Pi using scp from a terminal window on your machine.

Use the cd command to change to the directory where you extracted the SDK, like this (on a Linux, Mac, or other Unix machine for example):

cd ~/wpsapi-4.9.1_rasberry_pi

Then copy the files using scp (remember to replace the IP address with your real IP address):

scp include/wpsapi.h [email protected]:/home/pi

scp lib/libwpsapi.so [email protected]:/home/pi

Copy the source files that comprise this demo. They are available here: https://www.dropbox.com/s/fw84l6eqjrclbzz/offline_tracker.zip. Unzip them first then copy them:

scp tracker.cpp [email protected]:/home/pi

scp redeem.cpp [email protected]:/home/pi

scp create_kml.pl [email protected]:/home/pi

scp trackerd [email protected]:/home/pi

The default password is “raspberry”.

Log in to the Rasberry Pi using ssh (or connect directly using the keyboard and monitor) like this (remember to replace the IP address with your real IP address):

ssh [email protected]

As root, copy libwpsapi.so to /usr/lib using this command:

sudo cp libwpsapi.so /usr/lib

You can copy these from a remote machine using scp. First note the IP address.

As root, copy wpsapi.h to /usr/include:

sudo cp wpsapi.h /usr/include

Part 4 - Writing a Continuous Location Log

THE TRACKER C++ APPLICATION

Tracker.cpp (compiled as “tracker”) is a C++ program that demonstrates how to use the Skyhook SDK - also known for historical reasons as the WPS API, or Wi-Fi Positioning System. Tracker.cpp uses the periodic location call to get location every 5 seconds. It writes that location to a file, /var/log/trip_logs/trips_in_progress/trip_log_2014_01_02_09_30_00.txt. The numbers indicate the start time of the trip - year, month, day, etc. - in GMT. See the note about time below. If it cannot reach the Skyhook API server it will request an offline token from the Skyhook SDK and store that. An offline token is an encapsulation of a Wi-Fi scan that can be redeemed at a later time to determine the location.

This cpp (c++ source file) needs to be modified to change the API_KEY value at the top of the file. The API key is available from my.skyhookwireless.com for the project you have defined. You can open the source file using the nano editor:

nano tracker.cpp

Once you have changed the API_KEY you must compile the application using this command:

gcc -o tracker tracker.cpp -lwpsapi

Then copy the tracker file to /usr/bin with this command:

sudo cp tracker /usr/bin

Tracker creates a new folder called /var/log/trip_logs and under that it creates /var/log/trip_logs/trips_in_progress and /var/log/trip_logs/completed_trips. As soon as you start the program it creates a new trip log in the trips_in_progress folder. It also moves any existing trip logs to the completed_trips folder at startup.

Create the logs directories like this:

sudo mkdir -p /var/log/trip_logs/trips_in_progress

sudo mkdir /var/log/trip_logs/completed_trips

sudo mkdir /var/log/trip_logs/trip_maps

You can run tracker by typing this command:

sudo tracker

From another login window, you can then monitor the log as it is generated with this command:

tail -f /var/log/trip_logs/trips_in_progress/trip_log_2014_.log

where the number at the end of the filename is the date and time the log was created.

Each line of the log contains either a location or the path to an offline location token. An offline location token is generated whenever the device tries to get a location and the server is unavailable. The token represents a Wi-Fi scan and is compressed and encoded for later submission to the Skyhook service. In this case the device frequently is not connected to any network since the device has no cell network connection - so most or all the lines in the log will be references to token files. Here’s an example log file:

1392242819: offline token written to /var/log/trip_logs/tokens/1392242819.tok

1392242820: 42.352004,-71.048243 +/-148m 2+0+0

1392242826: 42.352005,-71.048242 +/-148m 2+0+0

The first number at the beginning of the line is a time stamp in standard Unix format - the number of seconds since 12:00 AM, January 1, 1970 GMT. On line 1 you see the path to the offline token. Token files are named with the time stamp and the extension “.tok”. Lines 2 and 3 show the location that was determined while tracker was running, if it was able to get a connection to the Skyhook service. You see in both lines the latitude and longitude followed by the error estimate - what we call the HPE, or horizontal position error. This means that 95% of the time, the device is within a circle centered on the given latitude and longitude with a radius equal to the HPE - 148m in this case. HPE does not indicate the actual error, which is typically much less - usually 30-50m in populated areas.

Tracker runs continuously until the device loses power or an interactive user types control-c.

In part 6 you’ll learn how to make tracker start at boot time so you can have it track each trip you take in your car and have it automatically start as soon as the car starts.

Part 5 - Redeeming Offline Tokens

THE REDEEM C++ APPLICATION

The source code for the redeem program is provided in redeem.cpp. Redeem takes as an argument the path to an offline location token. It submits the token to the Skyhook service and returns a location. You will need to modify redeem.cpp and give it the same API key you used in tracker.cpp. Redeem is called by the create_kml.pl program to generate a KML map that you can view in a tool like Google Earth.

You can compile the redeem program with this command:

gcc -o redeem redeem.cpp -lwpsapi

Then copy the program to the /usr/bin directory so it can be called from the create_kml.pl program:

sudo cp redeem /usr/bin

Part 6 - Building the KML Trace Map - create_kml.pl

KML is an XML file format that describes positions on a map and can be loaded into a tool like Google Earth to easily visualize a trip. Create_kml.pl is a Perl script that goes through each log file in the completed_trips folder and writes out the locations to a KML file. For each line of the log create_kml.pl either parses the given latitude and longitude and writes that out as a point in the KML, or it reads the path to the token file and calls redeem to get a location and then writes that to the KML. If it is unable to get a location from the call to redeem it is assumed that the device is still off-line and the program will wait for 30 seconds before trying again. It will continue to do this in a loop forever. So as soon as you plug in your device to an ethernet network after a car trip the program will successfully generate a KML file within a minute or so.

To install the create_kml.pl file type the following commands:

sudo cp create_kml.pl /usr/bin

sudo chmod +x /usr/bin/create_kml.pl

Part 7 - Making it Start Automatically on Boot

On Raspbian Linux, like all Debian variants, you can make something run at boot time by placing a script to start it into the /etc/init.d folder. You then need to run update-rc.d to update the system. Provided with this example is a short shell script to start and stop the tracker and create_kml programs.

sudo cp trackerd /etc/init.d

sudo update-rc.d trackerd defaults

Part 8 - Retrieving and Viewing the Results

The easiest way to copy completed trip KML files from your device is to use the scp utility. You can copy all the KMLs from the device using a command like this:

scp [email protected]:/var/log/trip_logs/trip_maps/*

As before, the default password for the “pi” user on Raspbian Linux is “raspberry”. You’ll need to change the IP address to be the right one for your machine.

Once you’ve copied your KML to your machine, open it with Google Earth. You will see your trip as a sequence of points connected by yellow lines.

Time may be inaccurate on the Raspberry Pi since it doesn’t have a clock or a battery on the board. Add-on boards are available if keeping accurate time is important in your project.