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 sysmsg_example_launcher_rev_info_report.json

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>

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