IoT Edge Gateway Software API V1
Introduction
The Aretas IoT Edge Gateway Software ships with most Aretas sensor packages and is available through the Aretas Ubuntu PPA as a self-install. Many other documents are available in the knowledge-base to cover installing the software and edge device hardware.
The software offers several key features:
- Visualize Sensor Data in Real-Time
- Export sensor data to CSV
- Process and Send Sensor Data to the Cloud
- Backlog Sensor Data when Internet is unavailable
- Persist Sensor Data
- Complete separation of UI and API
- Autodiscovery via MDNS / Bonjour
Below is a screenshot of the basic software interface:
Radiation monitor data charting
If you are working with an Aretas supplied device or you have installed the Ubuntu package, you can use an AVAHI browser to locate the IP address of the device on your network. A KB Article can be found here describing the process: http://www2.aretas.ca/accessing-your-aretas-edge-device-or-iot-gateway-page/
*Note, you can typically access a test device at http://bridge-test.aretas.ca for interim development testing (API, etc).
Software Configuration
The software has several configuration files. The main configuration files are located in:
/opt/aretas/Bridge/bridge_impl/
The main config file is bridge.ini
The contents of a typical file look like this:
[DEFAULT] username= password= bridge.owner_id= run_as.user=aretas run_as.group=aretas logging.enabled=true local=false serial.port=/dev/ttyS40 sensorapi.url=https://api.aretas.ca/SensorAPI strategies.url=https://api2.aretas.ca/strategies types.url=https://api2.aretas.ca/sensortypes service_controller.enabled=true service_controller.assoc_timeout_ms=3600000 webserver.enabled=true webserver.host = 0.0.0.0 webserver.port = 80 webserver.ui_path = /opt/aretas/Bridge/bridgewebinterface/ redis.host=localhost redis.port=6379 redis.serial_input.db=0 redis.service_controller_db=1 redis.backlog_db=2 redis.report_db=3 redis.type_db=4
Explanation of Configuration Variables
username=[String]
The username is your username assigned to your account, for sending data to the Cloud API
password=[String]
The password is the password assigned to your account. You must provide a valid password if you have provided your username and wish to enable sending data to the Cloud API and receiving Strategies and Control .
bridge.owner_id=[String]
This is a String containing the owner_id provided with your account. You must provide an owner id in addition to a username and password when accessing the cloud API to download strategies and control thresholds.
serial.port=[String]
Default: /dev/ttyUSB0
This is the serial port of the XBee/ZigBEE adapter or UART (for embedded versions)
run_as.user=[String]
A valid system user that the software will run as. This will have been created by the .deb package install script in Ubuntu / Debian. If you are performing a custom installation, you may need to create this user manually.
run_as.group=[String]
A valid system group the software will run as. This will have been created by the .deb package install script in Ubuntu / Debian. If you are performing a custom installation, you may need to create this user manually.
logging.enabled=[true,false]
Set to true to enable logging. Set to false to disable logging. Logs are typically located in /var/log/aretas. Also check logging.conf for additional logging configuration variables.
local=[true,false]
Sets local mode. If local is set to true, no messages will be posted to the sensorapi.url (even if the sensors have been authorized in your account). If local is set to false, messages will be sent to the sensorapi.url using the standard GET method.
sensorapi.url=[String]
Default: https://api.aretas.ca/SensorAPI
The URL used to post Sensor messages. You can change this URL to a custom end point as long as it follows the same GET / REST format as the Aretas API ingest endpoints.
Every time a valid sensor message is received by the gateway, the sensorapi.url is called with the sensor data, type, mac address of the sensor and a timestamp.
strategies.url=[String]
Default: https://api2.aretas.ca/strategies
The URL used by the bridge to query for Control strategies. Control strategies are user defined thresholds for various sensor types and control messages for Thermostats, Demand Ventilation Controllers and other types of equipment. Requires a valid username, password and bridge.owner_id
types.url=[String]
Default: https://api2.aretas.ca/sensortypes
The URL used to query the sensor semantics (label names, colors, codes, etc). Returns a JSON array of Objects. A small sample is below (there are roughly 100+ sensor types returned by the service):
[{"enabled":true,"display":true,"sensorColor":"0x00AA72","gasStatsSupported":false,"sensorGasFormula":"","label":"Control Switch","charCode":"CSW","charting":true,"type":"0x11"},{"enabled":true,"display":true,"sensorColor":"0x00AA72","gasStatsSupported":false,"sensorGasFormula":"","label":"Theta","charCode":"THETA","charting":true,"type":"0x15"}]
Requires a valid username, password and bridge.owner_id
A recent version of the sensortypes json is cached in the distribution and this setting is not entirely necessary, but is useful to stay up to date with the latest sensor semantic information.
service_controller.enabled=[true|false]
Enables / disables the sensor service controller (the software thread / process that dispatches control messages to associated sensors). The service controller, when enabled, will only attempt to dispatch control messages to sensors that have reported within the service_controller.assoc_timeout_ms value. Requires a valid username, password and bridge.owner_id.
service_controller.assoc_timeout_ms=[Number]
Default: 3600000
If the time (in milliseconds) between sensor reports exceeds this time interval, the Sensor will no longer be considered associated with this Edge device and will no longer received control messages.
webserver.enabled=[true|false]
Default: true
Enable / Disable the built in web / REST server.
webserver.host = [String/IP Address]
Default: 0.0.0.0
Select the IP address to bind to. Set to 0.0.0.0 to listen on all interfaces.
webserver.port = [Number]
Default: 80
The port the web server will listen on. Default is 80, however, if you are self-installing on your own device with other services running, you may want to change the port to avoid conflicts.
webserver.ui_path = [String]
Default: /opt/aretas/Bridge/bridgewebinterface/
The folder with the Web UI (html/javascript application). You can use the included application or using the API, write your own and change the webserver.ui_path setting to point to your custom application.
redis.host=[String/IP Address/Hostname]
Default: localhost
The Edge software requires access to a Redis database. The .deb package installs this dependency automatically, however if you are installing from source or would like to have a dedicated Redis instance, you can change this to an external host.
redis.port=[Number]
Default: 6379
The Redis service port. Don’t change this unless Redis is running on a non-standard port.
redis.serial_input.db=[String/Number]
Default: 0
The Redis database for storing the raw serial input from the wireless adapter. Don’t change this unless you know what you’re doing.
redis.service_controller_db=[String/Number]
Default: 1
The Redis database for storing service controller information. Don’t change this unless you know what you’re doing.
redis.backlog_db=[String/Number]
Default: 2
The Redis database for storing backlog sensor messages. Don’t change this unless you know what you’re doing.
redis.report_db=[String/Number]
Default: 3
The Redis database for storing sensor reports. Don’t change this unless you know what you’re doing.
redis.type_db=[String/Number]
Default: 4
The Redis database for storing sensor type information. Don’t change this unless you know what you’re doing.
Additional Serial Configuration File (for Go serial port reader)
If the main serial port changes for any reason, you may also need to edit /opt/aretas/Bridge/bridge_impl/bin/serial_reader.ini
[Serial] serialport=/dev/ttyUSB0 redis_serial_input_db=0
Edge Device v1 REST API
The Edge Device software comes enabled with 2 basic web service endpoints you can use to build your own application.
Get Data Request: /data
Called to get initial chunk of data and /or to get updates
URL
http://<device_ip>/data?from=<timeStart>&to=<timeStop>&mac=<mac>
URL example
http://bridge-test.aretas.ca/data?from=1535091334000&to=1535091934000
*hint, use https://www.epochconverter.com/ to generate some timestamps to use to query the sample URI. Make sure you multiply by 1000 to convert to milliseconds (or just add 000)
Parameters
from – timestamp with milliseconds – start time
to – timestamp with milliseconds – end time
mac – mac address of the device – (optional) if absent, returns data for all macs reporting to the edge device
Return format
JSON
Return codes
200 Everything worked as expected
400 Bad Request – Often missing a required parameter
Return Data
{ "mac" : [{type, color, units, label, series[[timestamp, value],], {{type, color, units, label, series[[timestamp, value]], ], }
Return Data Example
{
"1082900827": [{
"type": "248",
"color": "0x3DA028",
"units": null,
"label": "Relative Humidity",
"series": [
[1467141098550, 57.97],
[1467141218377, 57.83],
[1467141339622, 57.77],
[1467141459860, 57.67],
],
"code": "RH"
}, {
"type": "80",
"color": "0x25D500",
"units": null,
"label": "Nitrogen Dioxide",
"series": [
[1467141097543, 0.0],
[1467141338615, 0.0],
[1467141458853, 0.0],
[1467141579091, 0.0],
[1467141699329, 0.0],
[1467141819566, 0.0],
],
"code": "NO2"
}],
"1082900928": [],
}
Code Example
sg.updateDataByMac = function(){
var now = new Date().getTime();
var timeStart = now - sg.period;
jQuery.ajax({
type: "GET",
url: "http://"+window.location.host+"/data?from="+timeStart+ "&to="+now+"&mac="+sg.mac,
contentType: "application/json",
dataType: 'json',
success: function(data){
$.each(data[sg.mac], function( index, sensor ) {
if (sensor.type == sg.type){
var series = {};
series.data = sensor.series;
series.label = sensor.label;
series.type = sensor.type;
series.color = sensor.color.replace("0x", "#");
sg.data = [series];
sg.updateGraph();
}
});
}
});
}
Web Socket Request /ws
Subscribe to data updates.
Used to create a channel between a client and web server to deliver updates automatically using a web socket mechanism.
Return Format
JSON
Return Data
{'mac': mac, 'type': type, 'timestamp': timestamp, 'data': data}
Return Data Example
{'mac': '1082900827', 'type': '248', 'timestamp': 1467141098550, 'data': 57.97}
Code Example
var ws = new WebSocket("ws://"+window.location.host+"/ws");
ws.onopen = function() {
ws.send("Hello, world");
};
ws.onclose = function(){
console.log('Connection closed');
}
ws.onerror = function(evt) { console.log(evt) };
ws.onmessage = function (evt) {
var point = JSON.parse(evt.data);
if (point["mac"]){
var key = point["mac"]+point["type"].toString();
var graph = graphs[key];
if (graph != null){
graph.addPoint(point.type, point);
}
}
Posting Data Via HTTP / GET to the Edge Device
URL
http://<device_ip>/api/v1/report/?mac=<mac>&stype=<sensortype>&data=<data>
Example URL
http://<device_ip>/api/v1/report?mac=1234567&stype=248&data=35.3
Parameters
stype – sensor type (0-255)
data – the sensor payload data
mac – mac address of the device – (optional) if absent, returns data for all macs reporting to the edge device
Exporting CSV Data
URL
http://<device_ip>/export
Example URL
http://bridge-test.aretas.ca/export?from=1535089587267&to=1535093187267&mac=0
Parameters
from – timestamp with milliseconds – start time
to – timestamp with milliseconds – end time
mac – mac address of the device
Return Format
CSV
0 Comments