MQTT Broker API. This guide will get you started in connecting your devices to WolkAbout IoT Platform.

Transcription

1 MQTT Broker API Getting started This guide will get you started in connecting your devices to WolkAbout IoT Platform. Terminology Before you start, you should make yourself familiar with the common terms used in the documentation and API s Core concepts Device Manifest Device manifest represents a contract between a physical device and WolkAbout IoT Platform. It describes device capabilities to the Platform in order to enable connectivity, data collection and device management. Each manifest defines the following capabilities: Device sensors - like temperature in degrees Celsius and humidity in percents Device actuators - e.g. switch with states ON and OFF Device alarms - possibility for the device to alert the Platform that some alarming situation occurred. For example, a smoke detection device can send an alarm, which signals that smoke is detected. Additional device configuration parameters Manifest also defines a type of protocol used for the message exchange. Currently, supported protocols are JSON (single and multi) and WolkSense (legacy).

2 Device Device represents a physical device which connects to the Platform through Internet via MQTT protocol. It is represented by its device key and is effectively acting as a physical source of the data. Each device must conform to the device manifest in order to successfully communicate with the Platform. Point Point represents a point of measurement. It gives semantics to the measurements we are collecting (For example you can name the point by location - Room 15, Living Room, Basement and collect measurement Temperature). Each device, that is created on the Platform, has an automatically assigned point. Each point has a set of feeds, actuators and alarms. Feed Feed is a representation of a single type of measurement on a single point. Feed describes a specific sensor measurement by defining its type (temperature, humidity ) and unit. Value of a feed is the last reported measurement of a given type on a given point and its recent trend (rising, falling and steady). In that manner, the feed is treated as a real time data stream. Actuator Actuator is a representation of a component of a physical device which is able to receive the command and produce change in the system - for example, an ON/OFF switch that may control light. Each actuator has its state and current value: for instance, value of light switch can be ON and state READY. Because actuator can be controlled (actuated) from the Platform, its state may be READY, BUSY or ERROR. BUSY state represents that the actuation is currently being performed by the device and is still not finished. ERROR state means the actuator could not perform the actuation action. This can be illustrated by an example. Imagine a device with a light switch that can have values ON and OFF. Initially, it s value is OFF.

3 Now the user makes a request, from the Platform, to turn the switch to ON. The device will receive request and change state from READY to BUSY (keeping value OFF). When device finishes the action, the state will be READY and value ON. In case some error occurs, the state will be ERROR and value will stay OFF. Alarm Alarm represents an occurrence of an event detected by the device. For example, smoke detection device will send smoke detected alarm when a certain level of smoke is detected - suggesting the possibility of fire. This means that the device is responsible for detecting such events and signalling it to the Platform. Upon receiving alarming event, the Platform will perform actions, such as sending notifications to users or performing custom business rules. Support concepts Device key / Password Device key uniquely identifies the device on the Platform, and password authenticates it. A unique device key / password combination can be obtained for your devices through device management module. This combination is required when your device connects to WolkAbout IoT Platform to ensure the authenticity of the data. Reference Key concept in the manifest is a REFERENCE which uniquely identifies a device physical sensor, actuator, alarm and configuration parameters. For instance, a device which measures temperature, air pressure and air humidity may have 3 sensors with respective references of T, P, H. The example illustrates additional value/usage of references, which is keeping message payload minimal - which is appropriate for edge devices with limited resources.

4 MQTT API MQTT Support WolkAbout IoT Platform uses MQTT protocol to exchange data (i.e. MQTT messages) with devices. MQTT is a lightweight, subscription-based protocol used as a de facto standard for IoT communication between server and clients. More info about MQTT may be found here. Connecting to MQTT broker WolkAbout IoT Platform MQTT broker is hosted on api-demo.wolkabout.com on port 8883 and accepts SSL/TLS encrypted connections. Username/password authentication is used to identify MQTT clients and grant them access to specific topics. In order to connect IoT device (i.e. MQTT client) to the broker, the device should be first registered on WolkAbout IoT Platform. Device is registered in device management module (demo.wolkabout.com), resulting in credentials for MQTT broker. Credentials consist of username and password, where username maps to device key. Client libraries WolkAbout IoT Platform comes with free, open-source client libraries which can be used for connecting device to the Platform. Besides connectivity, the libraries contain all functionalities necessary for communication between the Platform and the device such as: Sending sensor readings Sending alarms Controlling actuators Updating device firmware Buffering data on the device To connect device to WolkAbout IoT Platform you can use Java, Python, C and C++ libraries available on GitHub. WolkConnect - Java WolkConnect - Python WolkConnect - C

5 WolkConnect - C++ Message format Message format depends on the type of protocol specified in the device manifest. Typically it is JSON with multi and single flavours. WolkAbout IoT Platform also supports WolkSense protocol for connecting devices like WolkSensor and Hexiwear. Common message terminology device_key - device key (see support concepts) REF - reference as defined in the device manifest value - value which should match data type as defined in the device manifest. It could be any of boolean, string or float values. JSON based protocol This is default protocol implementation with two flavours - JSON_SINGLE and JSON_MULTI. JSON message terminology utc - Universal Time Coordinated timestamp in seconds. data - feed value which should match data type as defined in the device manifest. It could be any of boolean, string or float values. Sensor data messages Device sends the sensor readings in following ways: Individual sensors readings (JSON_SINGLE)

6 Device sends one or more readings from one sensor. This format somewhat reduces the payload size and is best used when sending the data of specific sensors when required (such as on significant value change). readings/{device_key}/{ref} [{ utc (optional) : , data : 23.6 }] If utc is not sent current server time is recorded (treat it as live reading). Multiple sensors per message (JSON_MULTI) Use when you want to publish readings from multiple sensors readings/{device_key}/ { } utc (optional) : , REF1 : value1, REF2 : value2, If utc is not sent current server time is recorded (treat it as live reading). Actuation messages

7 Messages sent to the device to either: 1. SET the value of the actuator 2. Request STATUS of the actuator from device (Device subscribes, Platform posts messages here) for Platform->Device command messages: actuators/commands/{device_key}/{ref} { } command : SET STATUS, value (optional) : The device sends the status of the actuator and its current value. (Platform subscribes, Device posts messages here) for Device->Platform status updates: actuators/status/{device_key}/{ref} { } status : READY BUSY ERROR value : Alarm messages These are system events, sent by the device, which can be alert, critical or error messages. events/{device_key}/{ref}

8 { } utc (optional) : , data : E002 If utc is not sent current server time is recorded. WolkSense protocol Sensor data messages Device sends the sensor readings in following ways: sensors/{device_key} Digit = "0" "1" "2" "3" "4" "5" "6" "7" "8" "9" ; Type = Reference from manifest. For example T for Temperature Value = ("+" "-") {Digit} readingslist = "R:" {Digit} {"," Type ":" Value} readingscommand = "READINGS " ReadingsList {" " ReadingsList} ";" Examples READINGS R: ,T:+243,P:+10031,H:+374; Readings for timestamp with values temperature = 24.3 Celsius, pressure mbar, humidity = 37.4%. READINGS R: ,T:+243,P:+10031,H:+374 R: ,T:+233,P:+10021,H:+364;

9 Readings for timestamp with values temperature = 24.3 Celsius, pressure mbar, humidity = 37.4% with readings for timestamp temperature 23.3 Celsius, pressure mbar, humidity 36.4% Actuation messages Messages sent to device to either: 1. SET the value of the actuator 2. Request STATUS of the actuator from device (Device subscribes, Platform posts messages here) for Platform->Device command messages: config/{device_key} Digit = "0" "1" "2" "3" "4" "5" "6" "7" "8" "9" ; Type = Reference from manifest. For example SW for Switch Value = ("+" "-") {Digit} Command = SetCommand StatusCommand SetCommand = "SET {Type}:{Value};" StatusCommand = "STATUS {Type};" Examples SET SW:1; Set switch actuator to ON. SET SW:0; Set switch actuator to OFF. SET SL:+56; Set slider actuator to +56.

10 STATUS SW ; Report status of switch SW. Device sends the status of the actuator and its current value. (Platform subscribes, Device posts messages here) for Device->Platform status updates: sensors/{device_key} Digit = "0" "1" "2" "3" "4" "5" "6" "7" "8" "9" ; Type = Reference from manifest. For example SW for Switch Value = ("+" "-") {Digit} State = "READY" "BUSY" "ERROR" StatusCommand = "STATUS {Type}:{Value}:{State};" Examples STATUS SW:1:READY; Reports switch actuator is ON and its state is READY. State=READY means that actuator can receive and process a new message (when it is BUSY, new messages can not be processed). STATUS SL:+56:READY; Reports slider actuator is +56 and its state is READY. State=READY means that actuator can receive and process a new message (when it is BUSY, new messages can not be processed). Alarm messages These are the system events, sent by the device, which can be alarms, alerts, warnings, error messages or info. sensors/{device_key}

11 Digit = "0" "1" "2" "3" "4" "5" "6" "7" "8" "9" ; Type = Reference from manifest. For example HH for Humidity high alarm Value = ("+" "-") {Digit} readingslist = "R:" {Digit} {"," Type ":" Value} readingscommand = "READINGS " ReadingsList {" " ReadingsList} ";" Examples READINGS R: ,HH:1; Alarm with reference HH (Humidity high) published for timestamp