MQTT Broker API

Getting Started

This document will guide you through the initial steps in connecting your device to WolkAbout IoT Platform.

Terminology

Before you start, you should get 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).

Device

Device represents a physical device which is connected to the Platform through the 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.

Semantic Group

Semantic groups gives semantics to the measurements we are collecting (For example you can name the semantic group by location - Room 15, Living Room, Basement and collect measurement - Temperature). Each device, that is created on the Platform, has an automatically assigned semantic group.

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 a 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. Since the actuator can be controlled (actuated) from the Platform, its state may be READY, BUSY or ERROR. BUSY state indicates 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. This can be illustrated by an example. Imagine a device with a light switch that can have values ON and OFF. Initially, its value is OFF. Now the user makes a request, from the Platform, to turn the switch to ON. The device will a receive request and change state from READY to BUSY (keeping the value OFF). When the device finishes the action, the state will be READY and the value ON. In case some error occurs, the state will be ERROR and the 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 the device management module. This combination is required when your device connects to WolkAbout IoT Platform to ensure the authenticity of the data.

Reference

The key concept in the manifest is a REFERENCE which uniquely identifies device’s 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 the additional value/usage of the references, which is keeping message payload minimal - appropriate for the edge devices with limited resources.

MQTT API

MQTT Support

WolkAbout IoT Platform uses MQTT protocol to exchange the data (i.e. MQTT messages) with the devices. MQTT is a lightweight, subscription-based protocol used as a de facto standard for the IoT communication between the server and the clients. More info about MQTT can 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 the access to specific topics. In order to connect an 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 the 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:

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 (see support concepts) : reference as defined in the device manifest : 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

- Universal Time Coordinated timestamp in seconds

- 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 (JSONSINGLE)

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).

Channel

Payload

Multiple sensors per message (JSONMULTI)

Use when you want to publish readings from multiple sensors.

Channel

Payload

Actuation Messages

Messages sent to the device to either:

SET the value of the actuator
Request STATUS of the actuator from device

Channel

(Device subscribes, Platform posts messages here)

Channel for Platform->Device command messages:

Payload

The device sends the status of the actuator and its current value.

Channel

(Platform subscribes, Device posts messages here)

Channel for Device->Platform status updates:

Payload

Alarm Messages

These are system events, sent by the device, which can be alert, critical or error messages.

Channel

Payload