Note: Due to firmware changes that make RSSI calculations more consistent across radios and hardware models, you will likely notice a reduction in the RSSI values reported when using 6.3 firmware compared to earlier firmware versions. Earlier firmware releases are no longer being actively developed, so it is strongly recommended that you develop and test your presence reporting backend with access points running 6.3 or later firmware.
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. Must be accessible from the internet. |
| 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. Timezone is UTC. |
| last_seen | Timestamp of the last time this client was seen, during the reporting period. Timezone is UTC. |
| associated | Indication of whether the client is associated to the AP specified by node_mac. |
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);
?>
Probe request frequency
Depending on the client device's state, the number of probe requests it sends will vary. If the device is in a power-save mode, it may reduce the number of probe requests to once per minute(or longer). If it's already associated with a WiFi network, it may not send any probe requests again until the user manually brings up the WiFi networks list on the device.
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.