This document will guide you through the initial steps needed to connect your device to WolkAbout IoT Platform.
Before you start, you should get familiar with the common terms used in the documentation and APIs.
Device template is a placeholder for device and it enables you to create a number of identical devices which contain the same type of data. It describes device capabilities to the Platform in order to enable connectivity, data collection and device management. Each template defines the following capabilities:
For example, a smoke detection device can send an alarm, which signals that the smoke is detected.
Template also defines a type of protocol used for the message exchange. Currently, supported protocols are JSON (single and multi), Cayenne and WolkSense (legacy).
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 template in order to successfully communicate with the Platform.
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 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 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 the 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 has 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 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 represents an occurrence of an event detected by 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.
Device key uniquely identifies 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 is the key concept in the template. It uniquely identifies device’s physical sensor, actuator, alarm and configuration parameters. For instance, a device that 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.
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.
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.
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:
To connect device to WolkAbout IoT Platform you can use Arduino, C, C++, Java, MicroPython, Node-RED, Python and Zerynth libraries:
Message format depends on the type of protocol specified in the device template. Typically it is JSON with multi and single flavours. WolkAbout IoT Platform also supports WolkSense protocol for connecting devices like WolkSensor and Hexiwear.
: device key (see support concepts)
: reference as defined in the device template
: value which should match data type as defined in the device template. It could be any of boolean, string or float values
This is default protocol implementation with two flavours - JSON_SINGLE and JSON_MULTI.
- Universal Time Coordinated timestamp in seconds
- feed value which should match data type as defined in the device template. It could be any of boolean, string or float values.
Device sends the sensor readings in following ways:
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
Use when you want to publish readings from multiple sensors.
Channel
Payload
Messages sent to the device to either:
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
These are system events, sent by the device, which can be alert, critical or error messages.
Channel
Payload
Device sends the sensor readings in following ways:
Channel
Payload
Examples
Messages sent to device to either:
Channel
(Device subscribes, Platform posts messages here)
Channel for Platform->Device command messages:
Payload
Examples
Set switch actuator to ON.
Set switch actuator to OFF.
Set slider actuator to +56.
Report status of switch SW. 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
Examples
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).
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).
These are the system events, sent by the device, which can be alarms, alerts, warnings, error messages or info.
Channel
Payload
Examples
Alarm with reference HH (Humidity high) published for timestamp 1508150922.
