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

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

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

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"
}