NAV Navbar
shell

Introduction

Please note: The Regulus and Devices API's are deprecated. For new use cases, please consider the V2 API.

Welcome to the API documentation for the Sustainder Brokerage Layer.

The URL of the Sustainder Brokerage Layer API is https://httpapi.sustainder.com/.

Authentication

Authentication is done by using Basic Access Authentication over HTTPS or by using JSON Web Tokens (JWT). Both these methods require a username and password, which will be provided to you by Sustainder.

We've implemented a welcome command that is only accessible when you are authenticated. The below sections will walk you through testing your connection.

Basic Access Authentication

To access the welcome command:

curl https://httpapi.sustainder.com/light/regulus
  -X POST -u username:password -d '<welcome/>'

Make sure to replace username and password with your credentials.

While simple to implement, this method requires you to send both the username and password on every request. This means it is not suitable for use on devices that you do not control (such as mobile devices of users).

JSON Web Tokens

To retrieve your JWT token:

curl https://httpapi.sustainder.com/auth/jwt
  -X POST -d '{"username": "{username}", "password": "{password}"}'

Make sure to replace username and password with your credentials.

Example response:

{
    "name": "username",
    "token": "MyJWTToken",
    "auth-header": "JWT MyJWTToken"
}

To access the welcome command using your newly generated token:

curl https://httpapi.sustainder.com/light/regulus
  -X POST -H "Authorization: JWT MyJWTToken" -d '<welcome/>'

JSON Web Tokens allow you to generate a token that can be used for a certain period to perform requests with. This does not require you to store and send the password for every request, and as such is more suitable for use where basic authentication is not secure enough.

We’ve implemented an endpoint to request a JWT. An example to request such a JWT token can be found on the right.

For subsequent requests, this token should be prefixed with “JWT” and should be sent as value of the Authorization header. For example:

Authorization: JWT MyJWTToken

Sustainder Devices API

This section details the functionality of the Device API. This API allows a user to retrieve information on the devices active in the brokerage layer, to retrieve information on configuration options, and to do basic configuration of devices.

The base URL of this API is https://httpapi.sustainder.com/devices.

This API communicates in JSON.

Device locations

Example response:

[
    {
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [
                53.214483,
                6.555677
            ]
        },
        "properties": {
            "device_name": "LCM1",
            "status": "online",
            "model": "anne",
            "device_id": "160524000001",
            "gateway_id": "352267077368016",
            "type": "streetlight"
        }
    },
    {
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [
                53.214656,
                6.556385
            ]
        },
        "properties": {
            "device_name": "LCM2",
            "status": "online",
            "model": "anne",
            "device_id": "171224000196",
            "gateway_id": "352267077368016",
            "type": "streetlight"
        }
    },
    {
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [
                53.215710,
                6.556578
            ]
        },
        "properties": {
            "device_name": null,
            "status": "online",
            "model": "anne",
            "device_id": "171224000148",
            "gateway_id": "352267077368016",
            "type": "streetlight"
        }
    }
]

Retrieve all devices, with their location data, that your application has access to.

HTTP Request

GET https://httpapi.sustainder.com/devices/locations

Device details

Example response:

{
    "type": "streetlight",
    "model": "anne",
    "device_status": "offline",
    "gateway_identifier": "352267077368016",
    "device_identifier": "160524000001",
    "longitude": "6.555677",
    "latitude": "53.214483",
    "lighting_mode": "DIRECT_CONTROL",
    "dimming_scheme_name": "Default",
    "direct_control_light_level_c1": "0",
    "direct_control_light_level_c2": "0",
    "direct_control_light_level_c3": "0",
    "direct_control_light_level_c4": "0",
    "default_light_level_c1": "0",
    "default_light_level_c3": "0",
    "default_light_level_c2": "0",
    "default_light_level_c4": "0"
}

Retrieve details and configuration of a specific device.

HTTP Request

GET https://httpapi.sustainder.com/devices/{deviceId}

List dimming schemes

Example response:

{
    "dimming_schemes": [
        {
            "dimming_graph": "Default",
            "name": "Default",
            "rules": []
        },
        {
            "dimming_graph": "A 100-70-100",
            "name": "A 100-70-100",
            "rules": []
        },
        {
            "dimming_graph": "E 100-70-50-70-100",
            "name": "E 100-70-50-70-100",
            "rules": []
        }
    ],
    "dimming_graphs": [
        {
            "name": "E 100-70-50-70-100",
            "steps": [
                {
                    "light-level": 100,
                    "time": "12:00"
                },
                {
                    "light-level": 70,
                    "time": "22:00"
                },
                {
                    "light-level": 50,
                    "time": "00:00"
                },
                {
                    "light-level": 70,
                    "time": "05:00"
                },
                {
                    "light-level": 100,
                    "time": "06:00"
                }
            ]
        },
        {
            "name": "A 100-70-100",
            "steps": [
                {
                    "light-level": 100,
                    "time": "12:00"
                },
                {
                    "light-level": 70,
                    "time": "00:00"
                },
                {
                    "light-level": 100,
                    "time": "06:00"
                }
            ]
        },
        {
            "name": "Default",
            "steps": [
                {
                    "light-level": 100,
                    "time": "12:00"
                }
            ]
        }
    ]
}

Retrieve all available dimming schemes.

Dimming schemes have a name and a graph. The details of the graph can be found in the same response, under the key "dimming_graphs".

Dimming graphs consist of one or more steps. Every step defines a light level for a certain time. The light module will dim to the specified level at the specified time.

The name of each dimming scheme and graph is unique. To set the dimming scheme, you will need the name of the dimming scheme.

HTTP Request

GET https://httpapi.sustainder.com/devices/dimmingschemes

Light settings - light levels and dimming schemes

Example request: Configure light levels:

[{
    "device_id": "160524000001",
    "gateway_id": "352267077368016",
    "light_levels": [100,100,100,100]
}, {
    "device_id": "171224000196",
    "gateway_id": "352267077368016",
    "light_levels": [20,100,20,100]
}, {
    "device_id": "171224000148",
    "gateway_id": "352267077368016",
    "light_levels": [80,0,0,0]
}]

Example request: Set dimmming schemes

[{
    "device_id": "160524000001",
    "gateway_id": "352267077368016",
    "dimming_scheme": "Default"
}, {
    "device_id": "171224000196",
    "gateway_id": "352267077368016",
    "dimming_scheme": "Default"
}, {
    "device_id": "171224000148",
    "gateway_id": "352267077368016",
    "dimming_scheme": "A 100-70-100"
}]

Configure the basic settings of a lighting node: Light levels and dimming scheme.

It is possible to set the dimming scheme and light levels at the same time in the same request.

HTTP Request

POST https://httpapi.sustainder.com/devices/settings

Regulus Light Control API

The Sustainder Brokerage Layer has multiple API’s for various domains. This section details the functionality of Regulus Light Control API. This API corresponds almost completely with the existing Regulus XML API, albeit with a few minor changes (most notably regarding authentication).

With this API, it is possible to perform direct control commands to the luminaires of Sustainder, and it also allows for various configuration settings, such as the setting of dim schemes.

The basic URL of this API is https://httpapi.sustainder.com/light/regulus/{imei}, where “imei” is the IMEI value of the luminaire the request applies to.

The API only supports POST commands. The body of all POST commands is expected to be XML. The response body will, if there is a body, also be XML.

Responses: Synchronous vs asynchronous

In the Regulus light API, communication mainly happens asynchronously. On your requests, you will always receive a synchronous response, but this usually just indicates whether the command was parsed and received successfully. The real reply is sent by a POST message to an endpoint you choose. This push-mechanism supports basic authentication.

The format for synchronous responses will be documented here. The asynchronous responses will be documented with the corresponding requests.

Commands

For “get” commands, the general command format is as follows:

<commands>
    <get id="{deviceId}" ctrlId="{gatewayId}" meaning="{meaning}" />
</commands>

For “set” commands, the format is as follows:

<commands>
    <set id="{deviceId}" ctrlId="{gatewayId}" meaning="{meaning}">{value}</set>
</commands>

Specific examples for various requests can be found below.

Commands are direct control messages, to directly control the luminaires. Commands are subdivided into two operations, namely “get” and “set”.

The ctrlId field corresponds to the IMEI of the gateway, and the meaning value identifies the type of the command.

Command meanings

An overview of all command meanings can be found below. The most important meanings will be discussed in their own section.

Meaning Type Description
Current Get Request status
LampLevel Get Request status
LampCommandLevel Set Set lamp level
LampFailure Get Request status
LampSwitch Get Request status
LostCommunication Get Request status
NodeFailure Get Request status
NodeFailureMessage Get Request status
UnknowIdentifier Get Request status
LampCommandMode Get and set Get or set the lamp command mode

LampCommandLevel

Set all channels of the specified device to 50:

<commands>
    <set id="{deviceId}" ctrlId="{gatewayId}" meaning="LampCommandLevel">50</set>
</commands>

Set every channel individually:

<commands>
    <set id="{deviceId}" ctrlId="{gatewayId}" meaning="LampCommandLevel">50;70;30;100</set>
</commands>

The LampCommandLevel command directly sets the light level of the luminaire. The light level is an integer from 0 to 100.

The value can always be a single value, which sets the level of the entire luminaire. It can also be either two or four values, separated by a semicolon (;).

In case of two values, the channels opposite each other are set to the same value. In case of four values, all channels are set with their own value.

LampCommandMode

Set lamp to default configuration

<commands>
    <set id="{deviceId}" ctrlId="{gatewayId}" meaning="LampCommandMode">1</set>
</commands>

The LampCommandMode command sets the mode of the luminaire. This is usually used to return the lamp to its default configuration (in which it will follow the configured dimming scheme), after some direct control override was performed.

To return a lamp to its default configuration, the value should be “1”.

Command responses (synchronous)

Example response: Succesful request

<responses>
    <response>
        <status>QUEUED</status>
        <date>2017-10-30 16:30:18</date>
        <value></value>
        <error></error>
    </response>
</responses>

Example response: Gateway offline

<responses>
    <response>
        <status>ERROR</status>
        <date>2015-07-10 16:30:18</date>
        <value></value>
        <error>Gateway is offline</error>
    </response>
</responses>

In case of a bad request response (status 400), no body will be provided. When multiple requests are done at once, multiple response blocks will be returned.

The response date field is always filled, with a datetime value formatted as follows: “2017-10-30 16:30:18”.

If a command was successful, the response status will be QUEUED, indicating that the command has been queued for sending to the luminaires. If the command was not successful, it will be ERROR, with the response error field filled with a description of the error.

Configuration

Configuration template

<configuration>
    <devices mode="{overwrite_mode}">
        <device id="{device_id}" ctrlId="{controller_imei}" type="{device_type}">
            <params>
                <param key="{key}">{value}</param>
            </params>
        </device>
    </devices>
    <schedulers mode="{overwrite_mode}">
        <controlPrograms>
        </controlPrograms>
        <calendars>
        </calendars>
    </schedulers>
</configuration>

Commission gateways and lightpoints

<configuration>
    <devices mode="COMPLETE">
        <device id="controllerdevice" ctrlId="{controller_imei}" type="CONTROLLER">
            <params>
                <param key="lat">53.214510</param>
                <param key="lng">6.555723</param>
                <param key="TimeZoneId">Europe/Amsterdam</param>
                <param key="reportTime">01:00</param>
                <param key="reportFrequency">1</param>
            </params>
        </device>
        <device id="{device_id}" ctrlId="{controller_imei}" type="LIGHTPOINT">
            <params>
                <param key="lat">53.214510</param>
                <param key="lng">6.555723</param>
                <param key="DimmingGroupName">{group_name}</param>
                <param key="controllerStrId">{controller_imei}</param>
                <param key="idOnController">{device_id}</param>
            </params>
        </device>
    </devices>
</configuration>

Set dim scheme

<configuration>
    <schedulers mode="COMPLETE">
        <controlPrograms>
            <controlProgram id="15">
                <command time="15:08">82</command>
                <command time="03:44">68</command>
                <command time="23:34">83</command>
                <command time="21:00">77</command>
                <command time="18:30">90</command>
                <command time="10:46">0</command>
            </controlProgram>
        </controlPrograms>
        <calendars>
            <calendar id="{group_name}">
                <rule profile="daybased">
                    <controlProgram>15</controlProgram>
                    <day>T</day>
                    <priority>1</priority>
                </rule>
                <rule profile="daybased">
                    <controlProgram>15</controlProgram>
                    <day>M</day>
                    <priority>2</priority>
                </rule>
                <rule profile="daybased">
                    <controlProgram>15</controlProgram>
                    <day>W</day>
                    <priority>3</priority>
                </rule>
                <rule profile="daybased">
                    <controlProgram>15</controlProgram>
                    <day>SU</day>
                    <priority>4</priority>
                </rule>
                <rule profile="daybased">
                    <controlProgram>15</controlProgram>
                    <day>TH</day>
                    <priority>5</priority>
                </rule>
                <rule profile="daybased">
                    <controlProgram>15</controlProgram>
                    <day>F</day>
                    <priority>6</priority>
                </rule>
                <rule profile="daybased">
                    <controlProgram>15</controlProgram>
                    <day>S</day>
                    <priority>7</priority>
                </rule>
            </calendar>
        </calendars>
    </schedulers>
</configuration>

Configuration messages serve to configure the luminaires. A configuration message can exist out of two parts. The first part, devices, configures settings on the devices. The second part, schedulers, sets dimming schemes on the devices. Both parts do not need to be present.

The general template can be found on the right. The variables in the template are detailed below. For more details, see the sections below on the specific parts.

Variable Description Possible values
overwrite_mode How to handle existing data
  • COMPLETE: All previous data will be overwritten with the new data.
  • COMPLETE_NO_VERIFY: Special mode for setting dimschemes without checking they have been set on the nodes correctly. This can be used to rapidly distribute new settings before setting them again with verification.
  • COMPLETE_BUT_CONTROLLER: Only node data is updated, not the controller.
  • CONTROLLER_ONLY: Only the controller is updated, not the nodes.
device_id The device identifier
controller_imei The gateway identifier
device_type The device type
  • LIGHTPOINT: A Mira node.
  • CONTROLLER: An Antares controller.

Devices

The following key and value pairs are supported for devices with type LIGHTPOINT:

Key Description Value type
controllerStrId The ID of the Antares associated with this node. Integer
MacAddress
idOnController The current node ID on the Antares.
DimmingGroupName The name of the group the node is in. String
defaultLighState The default lightlevel for the node. Integer
CanGoOutOfSync A flag indicating if the LCM should continue to run the current dimscheme if it loses contact with the Gateway for >1:15 Boolean

The following key and value pairs are supported for devices with type CONTROLLER:

Key Description Value type
lat The latitude of the controller. Float
lng The longitude of the controller. Float
TimeZoneId The timezone of the controller String, in format “Europe/Amsterdam”
networkOperationalKey This is used to calculate the network key for Antares-Mira communication.
reportFrequency The amount of times per day the node status & dim change log is requested.
reportTime The timestamp of the time the node status & dim change log is requested.

Schedulers

Schedulers template

<configuration>
    <schedulers mode="{overwrite_mode}">
        <controlPrograms>
            <controlProgram id=”{control_program_id}”>
                <command time=”{command_time}”>
                    {command_lightlevel}          
                </command>
            </controlProgram>
        </controlPrograms>
        <calendars>
            <calendar id=”{group_name}”>
                <rule profile="daybased">
                    <controlProgram>{control_program_id}</controlProgram>
                    <priority>{priority}</priority>
                    <day>{day}</day>
                </rule>
            </calendar>
        </calendars>
    </schedulers>
</configuration>

The schedulers subsection consists of two parts, namely controlPrograms and calendars. A single message can contain multiple control programs and multiple calendars.

A control program describes a dimming scheme, with a number of command steps corresponding to the light level and times. A calendar contains one or more rules that link control programs to groups.

The variables in the template are detailed below.

Variable Description Possible values
control_program_id The ID of the control program. In the calendar section, it is used to reference to control programs defined above. String
command_time The time for the command step. See below: Dimschemes.
command_lightlevel The lightlevel for the command step. Integer
group_name The group that will be affected. Must be set earlier with the DimmingGroupName in Devices. String
day This indicates that the control program should execute on this day. "M", "T", "W", "TH", "F", "S" and "SU". Note that "M" means the night of Monday to Tuesday, meaning that it will run from Monday 12:00 (noon) until Tuesday 11:59.

Dimschemes / control programs

Dimschemes are defined by controlProgram elements. A number of “command” elements are provided, that each provide a time and a lightlevel. All dimschemes run from 12:00 (noon) until 11:59 the next day. It will sequentially step through the steps, starting with the 12:00 step, followed by all Sunset steps ordered by offset time. After the Sunset steps the Exact steps are all handled. Last are the Sunrise steps, ordered by offset time.

There are three types of time that can be provided in a command step:

Additionally, a step for 12:00 will be added if it is not already in the scheme and there is at least one step in the scheme. As lightlevel it will use the last step. The 12:00 step will be calculated by the last step in the scheme, e.g. if the last step is a sunrise step at 80% a 12:00 @ 80% step is added.

Diagnostics and administration

Template

<test>
    <{type} />
</test>

A number of diagnostics and administration commands are available, to trigger diagnostics operations on the luminaires. Take care to always provide the IMEI in the URL, to specify the device the command applies to.

The “type” field can be filled by one of the following values:

Type Description Asynchronous message
checknow Request the status of the lighting control module.
cancelcommand Cancel the current command operation, which halts the process of sending the command to all lighting control module.
reset Reset the Antares gateway.
bootload Update one or more nodes, or the entire network.

Bootload

Bootload example

<test>
    <bootload>
        <upgrade target="{network_or_node_id}" version="{version}" devicetype="{devicetype}" key="{download_key}" force="{force}" continue="{continue" />
    </bootload>
</test>

The bootload command requires additional parameters. These parameters are defined as follows.

Parameter Description Value type
Target The network or node ID the command applies to. Either “network” or the node ID as integer
Version The version the target should be updated to. Integer: 0 to 255
Devicetype The device type to update to. Integer: 0 to 255
Key The download key for node update. String of 32 characters
Force Whether the upgrade should be forced or not. A string of value “true”
Continue A string of value “true”

Errors

The Sustainder Brokerage Layer API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your username and password are incorrect, or your token is expired.
403 Forbidden -- You are not allowed to perform this request. Contact Sustainder for more information.
404 Not Found -- The specified gateway does not exist.
405 Method Not Allowed -- You tried to access a resource with a method that was not supported.
429 Too Many Requests -- You're performing too many requests in a short period of time. Please slow down.
500 Internal Server Error -- We had a problem with our server. Try again later. If the problem persists, please contact us.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Sensor Push API

This section details the functionality of the Sensor Push API. This API pushes sensor data to your application.

Communication

This Push API pushes data to one of your endpoints. Only a single endpoint is currently supported. Your endpoint should be provided to us during the onboarding process.

We will push data in the JSON format, and we will always provide the application/json Content-Type.

Sensor data message format

Example measurement

{
    "timestamp": "2018-08-17T08:43:40Z",
    "gateway_id": "3851577230355",
    "device_id": "8193651206395",
    "sensors": [{
        "name": "ambient_light",
        "available": true,
        "data": [{
            "value": 50
        }]
    }, {
        "name": "temperature_internal",
        "available": true,
        "data": [{
            "value": 32
        }]
    }, {
        "name": "gps",
        "available": true,
        "data": [{
            "name": "latitude",
            "available": true,
            "data": [{
                "value": 53.219575
            }]
        }, {
            "name": "longitude",
            "available": true,
            "data": [{
                "value": 6.568790
            }]
        }]
    }]
}

Sensor data is pushed using the JSON message format. It consists of a nested structure, with in the root the timestamp of the measurement, the device ID of the device that made the measurement, and the gateway ID of the gateway that reported the measurement to the platform.

In the “data” field, a list of data points is provided. Every data point has a name and a value. For some data points, the value is simply a number or a string. For others, it can be an object or a list of data points.

shell