/
MQTT - Inbound API

MQTT - Inbound API

Apr 06, 2020

 

Interface to/from sensors/gateways

  • receive (values/measurements, events, sysmsgs, images etc...) for processing [publish]

  • send (e.g. actions, jobs, configurations etc.) [subscribe]

Prerequisites

  • name of the organization <orgShortName>

  • serial of the sensor/gateway <serial> (a serial is mapped to a location/site)

  • optional: certificate for encrypted connection (SSL/TLS)

Protocol

  • MQTT V3.1.1

  • we recommend using Paho library components http://www.eclipse.org/paho/

  • The MQTT message payload can be zipped. zipped message should use the topic prefic "/application/gzip" (example: <orgShortName>/events/<serial>/application/gzip)

Topics/Message Types

From Edge Gateway to Cloud (publish)

Historical data

  • synonym for values, measurements, readings...

  •  we recommend to send historical data periodically

Topic: <orgShortName>/hd/<serial>

Example

[{ "processing_level": 0, "sensor_id": "Temperature", "timestamp": "2019-08-06T13:02:59.975Z", "value": 7 },{ "processing_level": 0, "sensor_id": "Temperature", "timestamp": "2019-08-06T13:03:58.478Z", "value": 11 }, { "processing_level": 0, "sensor_id": "Temperature", "timestamp": "2019-08-06T13:04:59.975Z", "value": 56 },{ "processing_level": 0, "sensor_id": "Temperature", "timestamp": "2019-08-06T13:05:58.478Z", "value": 50 }]

Attribute definitions

Attribute name

Data type 

Comments 

sensor_id

String

Unique sensor identifier

processing_level

String

indicates if there was a problem during the processing on the data. the value will be tagged. 0 mean no problem

timestamp

String

ISO 8601 (with Timezone Information)

in case of an empty string would the server would generate a now() timestamp

value

Number, String, Boolean

Measurement taken

Special sensor: device_gps_location

  • can set the gps coordinates of a gateway/location

[ {"timestamp": "", "sensor_id": "device_gps_location", "error_code": 0, "value": "47.3597222222,13.5955555556"} ]

Events

Topic: <orgShortName>/events/<serial>

[{ "output": "eval based on 22", "sensor_id": "Temperature", "state": "HOT", "timestamp": "2016-01-01T19:02:59.975+0100", "severity": 0 }]

 we recommend to send events immediately

 events can contain values as "hd" array element (preferably values that had an influence to the new event)

[{ "hd": [{ "processing_level": 0, "sensor_id": "Temperature", "timestamp": "", "value": -10 }], "output": "eval based on -10", "sensor_id": "Temperature", "state": "COLD", "timestamp": "", "severity": 200 }]

Attribute definitions

Attribute name

Data type 

Comments 

sensor_id

String

 

processing_level

String

 

timestamp

String

 

state

String

 

severity

Number

by default this mapping

0 → OK,

0 < severity < 100 → WARNING,

100<x<200 → CRITICAL (DANGER)

output

String

detailed info describing the state

hd

Array

Historical data, array of historical data elements

Special sensor: cloud_connected

  • this sensor is used to display the gateway status

  • the gateway should try after a successful connect to the MQTT Broker this message. Only by successfully receiving the acknoledgement it can be assured that next messages can be published. (access security might appear)

  • use events with state: "CONNECTED" 

  • on a regular shutdown of the gateway we recommend publishing a state: "OFFLINE" event

  • in order to show a unexpected disconnect we recommend using the MQTT feature lastWillTestament (using an offline payload)

  • the timezone information of the timestamp of the CONNECTED message is used to 

System Messages

Topic: <orgShortName>/sys_msg/<serial>

[{ "timestamp": "", "type": "job_status", "severity": 0, "code": 123, "output_short": "test", "output_long": "Job successfuly started" }]

Attribute definitions

Attribute name

Data type 

Comments 

timestamp

String

 

type

String

 

severity

Number

 

code

Number

 

output_short

String

 

output_long

String

 

references

Object

free list of reference objects

 

Special Message Type "rev_info_report"

  • indicates gateway details

  • example for the SiteController Message 

VSData

  • backup data for a sensor. Sensors can publish here their config or last state object. This can be redeployed via ACP in order to re-initialize

Topic: <orgShortName>/vs_data/<serial>/<sensor_id>

Images

Topic: <orgShortName>/imgdata/<serial>

open

From Cloud to Edge gateway (subscribe)

Actions

  • to trigger any action from the ACP the actions have to be defined first (see templates) 

Topic: cloud/<serial>/exec_action/<actuator_id>

 

Payload
{ "action_id": "SimulatedSensor", "exec_uid": "1bb083fc-8924-4324-8971-db22513ca78c", "origin": "SSCServices", "user_id": 70752, "command_id": "OK" }