Presence Reporting API

Topic

This article describes the Presence Reporting API, and how to configure the feature using the Datto Networking Portal.

Environment

  • Datto Access Points

Description

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

The presence data derives from probe request frames sent out by clients that access points can see, and will forward to a destination server defined in the Datto Networking Portal.

Navigation

1. In the Navigation menu, click Access Points, then select Advanced from the expanded options.

mceclip0.png
Figure 1: The Navigation menu

2. Enable Presence Reporting using the toggle to activate the feature.

mceclip1.png
Figure 2: Presence Reporting

Configuration

You must set the following attributes:

  • Server Location: Enter the server that will receive the presence data. This must be accessible from the internet.
  • Key: Enter the secret used to generate a SHA256 HMAC signature, within the payload (JSON message). The signature is then added to a custom HTTP header (signature) in the POST message.
  • Rate: Enter how often the data transmits the server in seconds.

Data Format

The data sent to the server location consists of the following elements:

Element Description
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 connected to the access point within the time period specified by the First seen and Last seen timestamps
min_signal Lowest RSSI reading on the access point 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 access point for when this client was last seen
first_seen Timestamp of when the client was first seen, during the reporting period; timezone is UTC
last_seen Timestamp of when the client was last seen, during the reporting period; timezone is UTC
associated Displays the association status between the client and the access point

The server receives the data via an HTTP POST message. Access points and Datto Networking servers do not store this data, so if the server specified in the configuration is down or otherwise unreachable, the HTTP POST will fail, making the data inaccessible. The Datto Networking Portal will not provide any notification of such failure.

Sample data 

{"network_id":221234,"node_mac":"[MAC address]","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}]}

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.