CloudTrax Presence Reporting API

Follow

Overview

The CloudTrax Presence Reporting API delivers real-time presence data from Open Mesh access points to customers, enabling applications like presence analytics, CRM tools and custom software.

The presence data is gathered from the probe request frames sent out by clients that the APs can see, and is sent to your server based on your configuration in CloudTrax.

This feature is disabled on all networks by default. Only enable it if you wish to use presence data for third-party solutions or your own custom software. Note that this feature will be part of a paid package of services in the future. 

Configuration

To configure the CloudTrax Presence Reporting API, you must have at least one or more access points running firmware version 6.1 or newer.

Navigate to Configuration > Advanced to enable and configure the CloudTrax Presence Reporting API.

You must set the following attributes:

Server Location: Where you would like the presence data to be forwarded. 
Key: 

This is the secret used to generate a SHA256 HMAC signature, over the payload (the JSON message). The signature is then added to a custom HTTP header (“Signature”) in the POST message.

Rate:  How often the data is sent to the server. 

Data Format

The data sent consists of the following elements:

node_mac  MAC address of the Access Point reporting the presence data. 
mac  MAC address of the end client device for which presence data is being reported.
count  Number of times the specific end client device was seen by the AP, within the time period specified by the “First seen” and “Last seen” timestamps.
min_signal Lowest RSSI reading on the AP for the specific client within the time period specified by the “First seen” and “Last seen” timestamps.
max_signal Highest RSSI reading on the AP for the specific client within the time period specified by the “First seen” and “Last seen” timestamps. 
avg_signal  Average RSSI reading on the AP for the specific client within the time period specified by the “First seen” and “Last seen” timestamps. 
last_seen_signal Reported RSSI reading on the AP for when this client was last seen
first_seen Timestamp of the first time this client was seen, during the reporting period
last_seen Timestamp of the last time this client was seen, during the reporting period
associated Indication of whether the client is associated to the AP or not.

The data is sent via a HTTP POST message to the server. No data is stored locally on the APs or on CloudTrax, so if the server specified in the configuration is down or otherwise unreachable, the HTTP POST will fail and cause the data to be lost. The CloudTrax UI will not provide any notification of such failure.

Sample data

{"network_id":221234,"node_mac":"AC:86:74:82:9A:30","version":1,"probe_requests":[{"mac":"00:9a:cd:e3:15:49","count":11,"min_signal":-77,"max_signal":-36,"avg_signal":-55,"last_seen_signal":-77,"first_seen":1475860695,"last_seen":1475860718,"associated":false},{"mac":"5c:dc:96:66:24:e3","count":1,"min_signal":-74,"max_signal":-74,"avg_signal":-74,"last_seen_signal":-74,"first_seen":1475860702,"last_seen":1475860702,"associated":false},{"mac":"70:ec:e4:16:75:71","count":1,"min_signal":-58,"max_signal":-58,"avg_signal":-58,"last_seen_signal":-58,"first_seen":1475860708,"last_seen":1475860708,"associated":false},{"mac":"8c:8b:83:d2:26:a5","count":1,"min_signal":-76,"max_signal":-76,"avg_signal":-76,"last_seen_signal":-76,"first_seen":1475860693,"last_seen":1475860693,"associated":false},{"mac":"98:01:a7:9e:47:7f","count":11,"min_signal":-60,"max_signal":-36,"avg_signal":-42,"last_seen_signal":-38,"first_seen":1475860712,"last_seen":1475860718,"associated":false},{"mac":"98:01:a7:a7:1d:d3","count":2,"min_signal":-84,"max_signal":-80,"avg_signal":-82,"last_seen_signal":-84,"first_seen":1475860689,"last_seen":1475860689,"associated":false},{"mac":"a8:86:dd:af:ac:0f","count":1,"min_signal":-68,"max_signal":-68,"avg_signal":-68,"last_seen_signal":-68,"first_seen":1475860708,"last_seen":1475860708,"associated":false},{"mac":"b0:fa:eb:30:4c:9e","count":10,"min_signal":-72,"max_signal":-62,"avg_signal":-67,"last_seen_signal":-67,"first_seen":1475860689,"last_seen":1475860715,"associated":false},{"mac":"e2:9f:fc:7f:1f:42","count":1,"min_signal":-65,"max_signal":-65,"avg_signal":-65,"last_seen_signal":-65,"first_seen":1475860714,"last_seen":1475860714,"associated":false}]}

Note for PHP users

PHP will not handle raw JSON POST data when processed using the $_POST
variable. To be able to access raw JSON data, you may have to use
"php://input" instead. Here is a sample script that shows you how:


<?php
// The code below uses php://input instead of $_POST as
// the data we are processing is not html form based post,
// but rather raw json that $_POST does not process.
$postdata = file_get_contents("php://input") . "\n\n";
print_r($postdata);
file_put_contents('mydata.txt', serialize($postdata), FILE_APPEND | LOCK_EX);
?> 

Presence reporting partners

The CloudTrax Presence Reporting API is currently being used by a number of Open Mesh partners to deliver analytics, marketing and enterprise reporting solutions. You can find a list of partners here

Have more questions? Submit a request

Comments

  • Avatar
    Marcos Santos

    I've been configuring an own solution to get this information into my server.

    I'm very interested on this, so, it will be available for anyone in the future? I mean, everyone will have access to the paid package services?

  • Avatar
    Bryan Patterson

    Marcos - The Presence Analytics API is currently available to anyone running 6.1 firmware. You'll find the server settings on the Advanced tab in Cloudtrax. The API is currently in beta and we will charge a small fee for it in the future upon final release.

  • Avatar
    Eric

    If anyone is interested, I wrote a PHP app that can collect this info. It is easy for anyone to setup, as there is a Heroku Install Button.
    The data is collected into a MySQL DB, which is also configured for you. The app installs on a free account, but depending on your requirements, you might need to upgrade your database size. You can also reconfigure the app to point to your own DB if you choose, you'd just need to replicate the schema.

    https://github.com/Skeyelab/cloudtrax-presence-php

    There is also a Ruby/MongoDB implementation linked from the URL above.

    Eric Dahl

  • Avatar
    vadique

    Hi guys,

    Any chance you will be expanding presence API with additional keys? It would be very helpful if posts contained a bit more data. For example each probe request could contain:
    : "ssid" - if a client is associated, pass the SSID name in addition to "associated:true"
    : "client_manufacturer" and/or "client_os" - OS is available in Cloudtrax Dashboard

    It would also be helpful if we could add custom data/descriptors to any AP in the dashboard. For example, we would like to add some custom meta data to our APs, and presence post could include that in addition to "network_id" and "node_mac", so that we don't have to do a lookup on our end with every post.

    Thanks!

Powered by Zendesk