IoT Edge Gateway Software API V1

You are here:
< Back

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:

  1. Visualize Sensor Data in Real-Time
  2. Export sensor data to CSV
  3. Process and Send Sensor Data to the Cloud
  4. Backlog Sensor Data when Internet is unavailable
  5. Persist Sensor Data
  6. Complete separation of UI and API
  7. 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
Ensure this file also has the correct serial port and redis db.

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

Table of Contents

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.