OpenBeacon Tracker API Installation





= Live OpenBeacon Tracker API = You can see the API in action at http://api.openbeacon.net/get/brucon.json - just hit reload to get new data. The data used there loops day 2 of BruCON 2011. The JSON format used there captures the entire state of the installation in a single object - no recursive API calls are needed.

Live Demo Applications

 * Phosphor Tag Tracking (source) by Jeff Katz
 * Realtime Social Network (source) by Milosch Meriac
 * Tags per Reader based on D3.js (source) by Milosch Meriac
 * Tags positions versus Tag Proximity sightings (source) by Milosch Meriac
 * Visitor Avatars Bowtie Animation by Aestetix
 * Visitor Tracking based on D3.js (source) by Rob Zinkov

= Installing the Tracker API under Fedora 17 x64 bit =

Please make sure that your user is in the sudoers file to enable him to run sudo. You can enable sudo in System Settings/User Accounts by pressing the Unlock-button and setting Account type from Standard to Administrator.

"Shortcut: Download a pre-configured VMware Workstation 9.0 image of a Fedora 7 x64 Linux based OpenBeacon API and Tracker + Web Service installation. This image will run under Windows, OS X and Linux using the free VMWare Player 5, Fusion 5 or Workstation 9 and later.

The password for the user openbeacon is sputnik - the root password is openbeacon. ssh access is is disabled in the firewall settings - if you need external access, you need to enable the ssh port in the firewall tool (see Activities-side-bar). On the first run of the VMware image, the ssh key is re-generated out of security reasons.

You need to click on Activities / OpenBeacon Tracker to run the tracker service. Please start the Activities / Chrome - see especially the links Proximity, openbeacon.local in the browser short-cuts-toolbar. By clicking on the network symbol and Network Settings in the top-right tray-area you can see the IP address of the bridged VMware image network interface.

Using Activities / GTKTerm you can configure PoE Easyreaders using a mini USB cable."

Get the latest sources
See git documentation for more information on this topic.

Run the openbeacon-tracker API service
You need to make sure that all OpenBeacon Ethernet EasyReaders point to the IP of your linux machine.

Additionally you need to open your local machines firewall UDP port 2342 to receive tracking packets:
 * go to Activities/Applications/Other/Firewall
 * in Firewall Configuration, Other Ports/Add - enable '''User Defined"
 * enter 2342 in Port / Port Range
 * select Protocol/udp
 * press OK to confirm your changes
 * press Apply to apply your changes
 * Close Firewall Configuration

If everything is correct you will see now a continuous stream of JSON objects on stdout':

In this example you can see two tags with the ID's 192 and 80 detected by reader 1095 - and as both tags are next to each other the proximity function kicks in and detects a sighting (called edge) between both tags with the power level 5.

Connecting OpenBeacon Tracker API to an Apache web server
Please watch the video tutorial on setting up the OpenBeacon PoE Ethernet readers, configuring apache for serving the JSON API and installing the example web visualizations.

The examples below use shortened object results for performance reasons. A the BruCON 2011 page you can find a real world example of a JSON object to clarify the data format. You can nicely see the list of tag positions with the button press indicator, the list of readers and positions plus the current social interaction of visitors in the edges'-area. You can see the live API at http://api.openbeacon.net/get/brucon.json - please hit reload to get new data. The BSON object format in the MongoDB database is the same as on the JSON web API.

If you add the option -l to filter-mongodb, these object will be stored into the MongoDB databes in the collection named log.

Connecting OpenBeacon Tracker API to a MongoDB database
Let's try some offline operations first to get the hang of MongoDB. This example downloads example log files from the BruCON 2011 conference and populate the MongoDB database openbeacon' with the processed data.

You will see a similar output as a result: new tag     115 [key=1] seen new tag     298 [key=1] seen new tag     369 [key=1] seen new tag     186 [key=1] seen new tag     402 [key=1] seen new tag     183 [key=1] seen new tag     231 [key=1] seen new tag     334 [key=1] seen

The openbeacon-tracker software chews through the entire BruCON 2011 logfile as quick as possible and stores all JSON objects into the mongodb tables openbeacon.tag and openbeacon.edge: Multiple filters can be concatenated as stdin/stdout/stderr pipes are used for communication between openbeacon-tracker and possible filters like ./filter-mongodb or ./filter-singular-sighting

running a MongoDB live update from openbeacon-tracker
This example runs ./openbeacon-tracker and pipes the data to ./filter-mongodb where it's stored into the MongoDB database collection openbeaco.live. As you can see in this example, the output of ./filter-mongodb is not redirected to >/dev/null in this example. This allows you to see the current status of the tracking system live in your console window. Please maximize the console window for the best visual experience.

Here you can see how a custom MongoDB Server IP, the database port and a database name are specified:

Default Configuration Settings:

Querying the MongoDB database
Run the interactive MongoDB shell first and connect to the openbeacon collection:

As a response the interactive shell pops up: MongoDB shell version: 2.0.7 connecting to: openbeacon >

Creating database indexes for increased performance
First make sure to create meaningful indexes to speed up querying of your database.

Show time and position of a tag
Show time and position of a tag seen at the venue: Using the command it (for 'iterate') you can iterate through the whole dataset.

Show times when tags were within a range of two pixels near to the coordinate X=808,Y=516

Show times when tag number 382 was 5 pixels near to the coordinate X=808,Y=516

Show all datasets with proximity sightings involving tag number 275
Returns tag ID tuplets of proximity sightings that include tag 275.