MQTT - Inbound API


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...
  • (info) we recommend to send historical data periodically

Topic: <orgShortName>/hd/<serial>

Example

Attribute definitions

Attribute nameData type Comments 

sensor_id

StringUnique sensor identifier

processing_level

Stringindicates 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, BooleanMeasurement taken
Special sensor: device_gps_location
  • can set the gps coordinates of a gateway/location

Events

Topic: <orgShortName>/events/<serial>

(info) we recommend to send events immediately

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

Attribute definitions

Attribute nameData type Comments 

sensor_id

String

processing_level

String

timestamp

String

state

String
severityNumber

by default this mapping

(green star) 0 → OK,

(star) 0 < severity < 100 → WARNING,

(red star) 100<x<200 → CRITICAL (DANGER)

outputStringdetailed info describing the state
hdArrayHistorical 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>

Attribute definitions

Attribute nameData type Comments 

timestamp

String
typeString
severityNumber


codeNumber

output_short

String

output_long

String

references

Objectfree list of reference objects


Special Message Type "rev_info_report"

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>