WolkAbout Developer Guides
MQTT Broker API

Learn the basics of how to connect your networked devices to WolkAbout IoT Platform with MQTT

Scroll

Getting Started

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

Terminology

Before you start, you should get familiar with the common terms used in the documentation and APIs.

Core Concepts

Device Template

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:

  • Device sensors - like temperature in degrees Celsius and humidity in percentages
  • Device actuators - e.g. switch with states ON and OFF
  • Device alarms - possibility for the device to alert the Platform of some alarming situation0

For example, a smoke detection device can send an alarm, which signals that the smoke is detected.

  • Additional device configuration parameters

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

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

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.

Support Concepts

Device Key / Password

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

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.

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 Arduino, C, C++, Java, MicroPython, Node-RED, Python and Zerynth libraries:

Message Format

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.

Common Message Terminology

: 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

JSON Based Protocol

Connection

The device connects to the Platform using a device key and a password as authentication.

The gateway connects to the Platform using a gateway key and a password. When a child device is connected via gateway to the Platform, its device key is used as a reference to that child device. Using a device password is not needed, as all communication related to that child device goes through the gateway.

Channel naming convention

Channel names should comply to the following format:

"{direction}/{message_type}[_{method}]/{path}"

Direction

Device to Platform messages

Device outbound messages channels are prepended with “d2p”.

Platform to device messages

Device inbound messages channels are prepended with “p2d”.

Message type

The identifier which categorises messages by type (Sensor reading, actuation request, etc.)

Method

This specifies how messages are exchanged between the device and the Platform. This part is optional and should be used only when there is an interaction between the gateway and the Platform for some message type. Some possible values are:

request | response | update | confirm | initiate | abort | status | …

Use the request/response pattern if one side acquires some data (request) and the other side should provide it (response).

Use the update/confirm pattern if one side sends some data (update) and the other side should confirm the reception (confirm).

Both request/response and update/confirm patterns require that the initial message is responded or the message should be retried.

Use the initiate/abort/status pattern for the process that is initiated or aborted by one side and the other side should periodically report the status.

The segment "{direction}/{message_type}[_{method}]" maps to a single DTO which flows through the channel.

Path

{path} = "[/g/{gateway_key}] [/d/{device_key}] [/r/{reference}]"

‘/g/{gateway_key}’ - Present if the message is intended for a child device that is bridged via a gateway

"/d/{device_key}" - Present if a specific device is targeted or if the message is intended for the gateway itself, behaving in this context as a regular device

"/r/{reference}" - Accessing per device unique entity (Optional - depending on the message type)

Overview of the Channels Used

Name Direction Path
Last will Device to Platform lastwill/{device_key}
Ping request Device to Platform ping/{device_key}
Ping response Platform to Device pong/{device_key}
Sensor readings Device to Platform d2p/sensor_reading/{path}
Events Device to Platform d2p/events/{path}
Actuator set request Platform to Device p2d/actuator_set/{path}
Actuator status response Device to Platform d2p/actuator_status/{path}
Configuration set request Platform to Device p2d/configuration_set/{path}
Configuration response Device to Platform d2p/configuration_get/{path}
Child device status update Device to Platform d2p/subdevice_status_update/{path}
Child device status confirm Platform to Device p2d/subdevice_status_confirm/{path}
Child device status request Platform to Device p2d/subdevice_status_request/{path}
Child device status response Device to Platform d2p/subdevice_status_response/{path}
Gateway update request Device to Platform d2p/update_gateway_request/{path}
Gateway update response Platform to Device p2d/update_gateway_response/{path}
Child device registration request Device to Platform d2p/register_subdevice_request/{path}
Child device registration response Platform to Device p2d/register_subdevice_response/{path}
Child device deletion request Device to Platform d2p/delete_subdevice_request/{path}
Child device deletion response Platform to Device p2d/delete_subdevice_response/{path}
Firmware install Platform to Device p2d/firmware_update_install/{path}
Firmware update abort Platform to Device p2d/firmware_update_abort/{path}
Firmware update status Device to Platform d2p/firmware_update_status/{path}
Firmware version Device to Platform d2p/firmware_version_update/{path}
File upload initiation Platform to Device p2d/file_upload_initiate/{path}
File upload status Device to Platform d2p/file_upload_status/{path}
File upload abort Platform to Device p2d/file_upload_abort/{path}
File chunk upload Platform to Device p2d/file_binary_response/{path}
File chunk request Device to Platform d2p/file_binary_request/{path}
File url download initiation Platform to Device p2d/file_url_download_initiate/{path}
File url download abort Platform to Device p2d/file_url_download_abort/{path}
File url download status Device to Platform d2p/file_url_download_status/{path}
File delete Platform to Device p2d/file_delete/{path}
File purge Platform to Device p2d/file_purge/{path}
File list request Platform to Device p2d/file_list_request/{path}
File list response Device to Platform d2p/file_list_response/{path}
File list update Device to Platform d2p/file_list_update/{path}
File list confirm Platform to Device p2d/file_list_confirm/{path}

Last Will

To handle the event of ungraceful disconnects, a last will message can be set on the MQTT broker when the device or gateway is establishing a connection to the Platform.
If the Platform receives this message, it will momentarily declare that the device or the gateway and its child devices are offline.
This message is also expected to be sent by the device or the gateway when it makes a controlled disconnect.
Payload for this message is not required, although any kind of content is valid.

Channel:
"lastwill/[{gateway_key}][{device_key}]"
Payload:

None (optional)

Keep Alive Mechanism

In conjunction with Last Will, devices should periodically publish messages that will ensure that the device is in fact connected to the Platform, and update the device’s last report time when the device is not publishing any data at that time.
Publishing these messages is not required and can be omitted, eg. when using battery powered devices or when available bandwidth is limited. Payload for this message is not required, although any kind of content is valid.

Each of these messages will be acknowledged with a response message that will contain the Platform’s current timestamp.

Request

Channel:
"ping/[{gateway_key}][{device_key}]" Payload:

None  (optional)
Response

Channel:
"pong/[{gateway_key}][{device_key}]" Payload:

{
    "value": int, (current Platform UTC timestamp)
    "command": "SET"
}

Sending and Receiving Data

Any device or gateway may have sensor readings, actuators, alarms and configurations. Sensor readings, actuators, alarms and configurations are accessed using per-device unique reference.
References are included in the message channel or in the payload, depending on the message type.

Sensor readings and alarms may be sent by the device at any time.

The Platform may send a command to set a device’s actuator value and the device should respond with actuator status and value. Optionally, the device may send actuator status at any time when the actuator value changes.

The Platform may send a command to set the device’s configuration option values and the device should respond with configuration values.
Optionally, the device may send configuration values at any time when the configuration is updated.
Each configuration message should contain all configuration items supported by the device, not just the ones (to be) updated.

Each device actuator status and value, as well as all the configuration values should be sent by the device to the Platform upon establishing a connection.

The topic includes device and/or gateway key depending on what is targeted.
When the device or gateway is targeted, the topic contains the "d/{device_key}" part.
When a gateway’s child device is targeted, the topic contains the
"g/{gateway_key}/d/{device_key}" part.

Channels
Name Direction Path
Sensor readings Device to Platform d2p/sensor_reading/{path}
Alarms Device to Platform d2p/events/{path}
Actuator set request Platform to Device p2d/actuator_set/{path}
Actuator status response Device to Platform d2p/actuator_status/{path}
Configuration set request Platform to Device p2d/configuration_set/{path}
Configuration response Device to Platform d2p/configuration_get/{path}
Sensor readings

Sensor reading for one sensor

Channel:
"d2p/sensor_reading/[g/{gateway_key}/][d/{device_key}/]r/{reference}"

Payload:

{
    "utc": integer, (optional)
    "data" : string
    (if data size > 1, use comma-separated values as string)
}

or

[
    {
        "utc": integer,(optional)
        "data": string (data)
    },
    {
        "utc": integer,(optional)
        "data": string (data2)
    },  ...
]

Using "utc" is advised if data history is important. If this field is omitted, the Platform will assign a timestamp once it receives the message.
The integer value expected for "utc" is a Unix timestamp in seconds or milliseconds.

Sensor readings for one or more sensors

Channel:
"d2p/sensor_reading/[g/{gateway_key}/][d/{device_key}/]"

Payload:

[
    {
        "utc": integer, (optional)
        "{reference}": string (data),
        "{reference2}": string (data),
        ...
    },
    {
        "utc": integer, (optional)
        "{reference}": string (data),
        ...
    },
    ...
]

Using "utc" is advised if data history is important. If this field is omitted, the Platform will assign a timestamp once it receives the message.
The integer value expected for "utc" is a Unix timestamp in seconds or milliseconds.

Alarms

Alarm event for one alarm

Channel:
"d2p/sensor_reading/[g/{gateway_key}/][d/{device_key}/]"

Payload:

[
    {
        "utc": integer, (optional)
        "{reference}": string (data),
        "{reference2}": string (data),
        ...
    },
    {
        "utc": integer, (optional)
        "{reference}": string (data),
        ...
    },
    ...
]

Alarm event for one or more alarms

Channel:
"d2p/events/[g/{gateway_key}/][d/{device_key}/]"

Payload:

[
    {
        "utc": integer, (optional)
        "{reference}": string (data),
        "{reference2}": string (data),
        ...
    },
    {
        "utc": integer, (optional)
        "{reference}": string (data),
        ...
    },
    ...
]

Alarm active values: "1", "ON", "true", "1.0"
Alarm inactive value: "0", "OFF", "false", "0.0"

Using "utc" is advised if data history is important. If this field is omitted, the Platform will assign a timestamp once it receives the message.
The integer value expected for "utc" is a Unix timestamp in seconds or milliseconds.

Actuators

Actuator set

Request
Channel:
"p2d/actuator_set/[g/{gateway_key}/][d/{device_key}/]r/{reference}"

Payload:

{
    "value": string
}

Response
Note: Can be sent freely by device, eg. not only on request
Channel:
"d2p/actuator_status/[g/{gateway_key}/][d/{device_key}/]r/{reference}"

Payload:

{
    "status": "READY" | "BUSY" | "ERROR",
    "value": string (ignored when status is "ERROR")
}

Configurations

Configuration set

Request
Channel:
"p2d/configuration_set/[g/{gateway_key}/][d/{device_key}/]"

Payload:

{
   "{reference1}": string,
   (if data size > 1, use comma-separated values as string)
   "{reference2}": string,
   ...
   "{referenceN}": string
}

Response
Note: Can be sent freely by device, eg. not only on request.
Contains all configuration fields supported by the device.
Channel:
"d2p/configuration_get/[g/{gateway_key}/][d/{device_key}/]"

Payload:

{
    "values":
        {
            "{reference1}": string,
            "{reference2}": string,
            ...
            "{referenceN}": string
        }
}

Gateway Specific Functionality

Determining control over child devices

Devices that communicate through a gateway (child devices) have to be registered on WolkAbout Platform to validly send data.
The responsibility of registering or deleting child devices is either on the gateway or on the Platform itself.
The gateway is considered inactive by the Platform until the control is determined.

This control over child devices is determined as a part of the gateway’s update request which is the first thing the gateway does upon establishing connection to the Platform.

A subdeviceManagement string attribute is added to the gateway’s update request to the “typeParameters” object.
The "subdeviceManagement" attribute can have a value of “GATEWAY” which means the gateway is in control of registering and deleting child devices, or “PLATFORM” which means the Platform is in control of registration and deletion of child devices.
By default, the Platform is considered to be in control if this attribute is not provided during the gateway update request.
Child devices will have a connectivity parameter which says who is in control of their gateway, the attribute is “MANAGED_BY”, and the possible values are “PLATFORM” and “GATEWAY”

Gateway Update

A gateway is registered on the Platform just like any other device. However, unlike other devices, a gateway can update its own assets over the appropriate channels.
Gateway update is a mandatory first step before the gateway can be used. During this step the gateway notifies the Platform who is in control of child devices and defines any personal device data that it is capable of sending.
Note: The gateway can update itself only once!

Name Direction Path
Gateway update request Device to Platform d2p/update_gateway_request/{path}
Gateway update response Platform to Device p2d/update_gateway_response/{path}

Gateway update request

Channel:
"d2p/update_gateway_request/g/{gateway_key}"

Payload:

{
    "firmwareUpdateType": null | "DFU", (optional)
    "sensors": Array of Sensor,
    "actuators": Array of Actuator,
    "alarms": Array of Alarm,
    "configurations": Array of Configuration,
    "typeParameters:": Object,
    "connectivityParameters": Object, (optional)
    "firmwareUpdateParameters": Object (optional)
}

typeParameters:

    {
        "subdeviceManagement": "GATEWAY" | "PLATFORM"
    }

Firmware update parameters tell the Platform what gateway supports related to file transfer and firmware update. The "supportsFirmwareUpdate" attribute is used to indicate if the gateway supports firmware update for itself.

firmwareUpdateParameters:

    {
        "supportsFirmwareUpdate": boolean,
        "supportsFileDownload": boolean,
        "supportsFileURL": boolean
    }

Gateway update response

Channel:
"p2d/update_gateway_response/g/{gateway_key}"

Payload:

{
    "result": Status,
    "description": "nullable string describing errors"
}

Gateway update response status

Status Description
Status Description
OK Gateway update performed successfully.
ERROR_GATEWAY_NOT_FOUND Gateway with specified key not present on the Platform.
ERROR_VALIDATION_ERROR The message received is not valid JSON.
ERROR_INVALID_DTO The update message was missing required fields or contained invalid values.
ERROR_GATEWAY_UPDATE_FORBIDDEN Gateway update was already performed once for this gateway.
ERROR_SUBDEVICE_MANAGEMENT_CHANGE_NOT_ALLOWED Child device management was already determined and cannot be changed.
ERROR_UNKNOWN Unknown error occurred.

Managing subdevices

Scenario 1: The gateway in control

The gateway was declared to be in control of managing child devices as part of the gateway update request.
The gateway must register child devices on the Platform (see Child device registration) before their use. Only the gateway can delete child devices (see Child device deletion).

The gateway is in charge of reporting connection status of child devices Child device status).

Scenario 2: The Platform in control

The Platform was declared to be in control of managing child devices as part of the gateway update request.
Creation of child devices (connectivityType = MQTT_SUB_DEVICE) is enabled on the Platform. The list of registered child devices exists only on the Platform. The gateway simply subscribes to all the channels of this protocol with wildcards so it can handle any device key.

When the gateway is sending data, it will forward everything to the Platform. The gateway does not know whether the data it is forwarding is coming from a registered child device or not. The Platform has to determine if it should ignore this data.

The gateway is in charge of reporting connection status of child devices (see Child device status).

Child device registration

The gateway can register any number of devices. Those devices are routed through the gateway meaning that they use the gateway’s credentials for authentication with the Platform. Channels

Name Direction Path
Child device registration request Device to Platform d2p/register_subdevice_request/{path}
Child device registration response Platform to Device p2d/register_subdevice_response/{path}

Child device registration request
Channel:
"d2p/register_subdevice_request/g/{gateway_key}"

Payload:

{
    "name": string,
    "deviceKey": string,
    "type": string, (optional, defaults to STANDARD)
    "defaultBinding": boolean, (optional, default false)
    "sensors" : Array of Sensor,
    "actuators" : Array of Actuator,
    "alarms": Array of Alarm,
    "configurations": Array of Configuration,
    "typeParameters:": Object, (optional)
    "connectivityParameters": Object, (optional)
    "firmwareUpdateParameters": Object (optional)
}

Firmware update parameters should contain:

"supportsFirmwareUpdate": boolean

which tells if the firmware can be updated on the child device.
If not sent, default will be false.
Existing child devices will not have this parameter, but they will support firmware update.

Child device registration response Channel:
"p2d/register_subdevice_response/g/{gateway_key}"

Payload:

{
    "payload":
    {
        "deviceKey": String
    },
    "result": Status,
    "description": "nullable string describing errors" (optional)
}

Child device registration response status

Status Description
OK Child device registration performed successfully.
ERROR_GATEWAY_NOT_FOUND The gateway with the specified key not present on the Platform.
ERROR_VALIDATION_ERROR The message received is not valid JSON.
ERROR_INVALID_DTO The update message was missing required fields or contained invalid values.
ERROR_SUBDEVICE_MANAGEMENT_FORBIDDEN The gateway is unable to register child devices.
ERROR_MAXIMUM_NUMBER_OF_DEVICES_EXCEEDED Child device management was already determined and cannot be changed.
ERROR_UNKNOWN Unknown error occurred.
ERROR_NOT_A_GATEWAY Key specified as the gateway key is not a gateway.
ERROR_KEY_MISSING Device key was not provided in the registration request.

Child device deletion

Channels

Name Direction Path
Child device deletion request Device to Platform d2p/delete_subdevice_request/{path}
Child device deletion response Platform to Device p2d/delete_subdevice_response/{path}

Child device deletion request Channel:
"d2p/delete_subdevice_request/g/{gateway_key}/d/{device_key}"

Payload:
None

Child device deletion response
Channel:
"p2d/delete_subdevice_response/g/{gateway_key}/d/{device_key}"

Payload:

{
    "result": "OK"
}

Child device status

The gateway reports the connection status of each child device whenever a change occurs. The Platform may optionally request child device status.
If the gateway is offline, all child devices are considered offline.
After the gateway goes online it must report the status for each child device.

Channels

Name Direction Path
Child device status update Device to Platform d2p/subdevice_status_update/{path}
Child device status confirm Platform to Device p2d/subdevice_status_confirm/{path}
Child device status request Platform to Device p2d/subdevice_status_request/{path}
Child device status response Device to Platform d2p/subdevice_status_response/{path}

Child device status update
Channel:
"d2p/subdevice_status_update/g/{gateway_key}/d/{device_key}"

Payload:

{
    "state": State
}

Device states

Status Description
CONNECTED Every time the device publishes data to the Platform it is considered to be in the CONNECTED state, so it doesn’t need to be sent explicitly.
OFFLINE If the device is going to terminate its connection to the Platform for an unforeseeable period of time, then the device should send the OFFLINE state prior to disconnecting.
SLEEP When the device works on a principle of only connecting periodically to the Platform to publish stored data, then prior to disconnecting from the Platform the device should publish the SLEEP state.
This state is considered to be a controlled offline state.
SERVICE_MODE Should the device need to perform any maintenance or any other action during which it would deviate from its default behavior, the device should publish the SERVICE_MODE state. This state implies that the device is unable to respond to commands issued from the Platform.

Child device status confirm

Channel:
"p2d/subdevice_status_confirm/g/{gateway_key}/d/{device_key}"

Payload:

{
    "result": "OK" | "ERROR_GATEWAY_NOT_FOUND" |
               "ERROR_KEY_MISSING" | "ERROR_NOT_A_GATEWAY" |
               "ERROR_DEVICE_NOT_FOUND" | "ERROR_INVALID_DEVICE"
}

Child device status request
Channel:
"p2d/subdevice_status_request/g/{gateway_key}/d/{device_key}"

Payload:
None

Child device status response
Channel:
"d2p/subdevice_status_response/g/{gateway_key}/d/{device_key}"

Payload:

{
       “state”: State
}

Gateway and child device status scenarios

Use Case 1

  • Given
    • Gateway not connected to the Platform
    • Device(s) connected to the gateway
  • When
    • Gateway connects to the Platform
    • Gateway sends device status for each device
  • Then
    • Gateway is declared to be connected to the Platform
    • Device(s) status is declared according to the received device status

If device status is omitted for a device, that device will be considered offline.

Use Case 2

  • Given
    • Gateway connected to the Platform
    • Device(s) connected to the gateway
  • When
    • Gateway disconnects from the Platform
  • Then
    • Gateway is declared offline
    • Device(s) bridged by gateway are declared offline

Use Case 3

  • Given
    • Gateway connected to the Platform
    • Device(s) connected to the gateway
  • When
    • Device(s) disconnects ungracefully from the gateway
  • Then
    • Gateway sends “OFFLINE” device status for each ungracefully disconnected device
    • Device(s) status is declared according to received device status (“OFFLINE”)

Use Case 4

  • Given
    • Gateway connected to the Platform
    • Device(s) connected to the gateway
  • When
    • Device(s) disconnects gracefully from the gateway
  • Then
    • Gateway sends “SLEEP” device status for each gracefully disconnected device
    • Device(s) status is declared according to received device status (“SLEEP”)

Firmware Update

For the firmware update to be enabled on the device or gateway and child devices, at least one of the file transfer methods must be enabled on the device or gateway (see File management).

Channels

Name Direction Path
Firmware install Platform to Device p2d/firmware_update_install/{path}
Firmware update abort Platform to Device p2d/firmware_update_abort/{path}
Firmware update status Device to Platform d2p/firmware_update_status/{path}
Firmware version Device to Platform d2p/firmware_version_update/{path}

Device

The device uses previously transferred files to update its firmware.
The Platform sends a firmware installation message to the device with the file name as a part of the payload. It is implied that the file is previously transferred to the device (see File management).
The device validates that the file exists and starts the firmware update process.
During the firmware update process the Platform may send a message containing an abort command. The device does not have to respond if the update cannot be aborted. During the firmware update process, the device reports update status and responds to install/abort commands in the "firmware_update_status" channel.

The device should report its current firmware version when it connects to the Platform.

Firmware install

Channel:
"p2d/firmware_update_install/d/{device_key}"

Payload:

{
    "fileName": string
}
Firmware update abort

Channel:
"p2d/firmware_update_abort/d/{device_key}"

Payload:
None

Firmware update status

Channel:
"d2p/firmware_update_status/d/{device_key}"

Payload:

{
       “status”: Status,
       “error”: integer (present only if status is ERROR)
}

Firmware version

Channel:
"d2p/firmware_version_update/d/{device_key}"

Payload:
string

Gateway

Gateway uses previously transferred files to update its own, or its child devices’ firmware.

Each device can be assigned an attribute named "DeviceFirmwareType". If the device is registered via gateway, the attribute is optionally sent as a part of its registration request inside of the "firmwareUpdateParameters" object.

The Platform sends firmware installation commands to the gateway with a list of device keys and the file name contained in the payload. It is implied that the file is previously transferred to the gateway (see File management). The gateway validates that the file exists and starts the firmware update process.

During the gateway’s firmware update process, performing the firmware update process on its child devices is forbidden.

During the firmware update process the Platform may send abort commands. The gateway does not have to respond if the firmware update process cannot be aborted. During the firmware update process, the child device reports its firmware update status and responds to any install/abort commands it has received to the "firmware_update_status" channel. The response may be given to each child device channel separately, or to the gateway channel with the list of device keys to which the status is applied.

The gateway reports the current firmware version for itself and each child device after connecting to the Platform.

Firmware install

Channel:
"p2d/firmware_update_install/g/{gateway_key}"

Payload:

{
    "devices": [device_keys], (can include gateway_key)
    "fileName": string
}
Firmware update abort

Channel:
"p2d/firmware_update_abort/g/{gateway_key}"

Payload:

{
    "devices": [device_keys]
}
Firmware update status

Channel:
"d2p/firmware_update_status/g/{gateway_key}[/d/{device_key}]"

Payload:

{
       “status”: Status,
       “error”: integer (present only if status is ERROR)
}

Firmware version Channel: “d2p/firmware_version_update/g/{gateway_key}[/d/{device_key}]”

Payload: string

Firmware update statuses

Status Description
INSTALLATION Installation in progress.
COMPLETED Firmware update completed successfully.
ERROR An uncorrectable error occurred during the firmware update.
ABORTED Firmware update aborted by the user.

Firmware update errors

Code Name Description
0 UNSPECIFIED_ERROR An unexpected error occurred.
1 FILE_NOT_PRESENT Firmware file is not present on the device.
2 FILE_SYSTEM_ERROR Firmware file cannot be handled on the device due to file system error.
3 INSTALLATION_FAILED An error occurred while installing the firmware.
4 SUBDEVICE_NOT_PRESENT A specified child device is not present on the gateway.

File management

Device and gateway may support file management. Gateway’s child devices do not support file management, but the files can be downloaded and stored by the gateway.

The Platform can upload a file to the device or issue a command to the device to download a file from the specified URL. The device reports file upload/download status to the Platform.
Both the device and the Platform should store information about the files that exist on the device.
The Platform can issue a command to the device to delete one or purge all the downloaded files.
After every file upload/download or deletion, the device should send the list of available files to the Platform.

File upload

The Platform initiates a file transfer. Device requests file chunks and reports upload status.
The Platform may issue a command to the device to abort file upload. If the abort is successful, the device responds with aborted status. The device may not respond if the abort is not possible. The device should delete the aborted file as soon as possible.
Upon uploading the file the device will send the list of available files (See File listing).

Channels

Name Direction Path
Upload initiation Platform to Device p2d/file_upload_initiate/{path}
Upload status Device to Platform d2p/file_upload_status/{path}
Upload abort Platform to Device p2d/file_upload_abort/{path}
Chunk upload Platform to Device p2d/file_binary_response/{path}
Chunk request Device to Platform d2p/file_binary_request/{path}
Upload initiation

Channel:
"p2d/file_upload_initiate/[g/{gateway_key}][d/{device_key}]"

Payload:

{
    "fileName": string,
    "fileSize": integer, (in bytes)
    "fileHash": string (base64 encoded sha256 hash of file)
}
Upload status

Channel:
"d2p/file_upload_status/[g/{gateway_key}][d/{device_key}]"

Payload: {
       “fileName”: string,
       “status”: Status,
       “error”: integer (present only if the status is ERROR)
}

Upload abort

Channel:
"p2d/file_upload_abort/[g/{gateway_key}][d/{device_key}]"

Payload:

{
    "fileName": string
}
Chunk upload

Channel:
"p2d/file_binary_response/[g/{gateway_key}][d/{device_key}]"

Payload type: Raw bytes
Payload consists of 3 parts:
32 bytes hash of the previous chunk (all 0s for the first chunk)
n bytes representing the requested chunk. n is the requested chunk size - 64.
32 bytes hash of the current chunk.
Chunk request

Channel:
"d2p/file_binary_request/[g/{gateway_key}][d/{device_key}]"

Payload:

{
    "fileName": string,
    "chunkIndex": integer,
    "chunkSize": integer
}

URL download

The Platform issues a command to the device to download a file from the specified URL. The device downloads the file and reports the download status. After a successful download, the device sends the file name to the Platform to store.
The Platform may issue a command to the device to abort URL download. If the abort is successful, the device responds with aborted status. The device may not respond if abort is not possible. The device should delete the aborted file as soon as possible.
Upon downloading the file the device will send the list of available files (See File listing).

Channels

Name Direction Path
File url download initiation Platform to Device p2d/file_url_download_initiate/{path}
File url download abort Platform to Device p2d/file_url_download_abort/{path}
File url download status Device to Platform d2p/file_url_download_status/{path}
Download initiation

Channel:
"p2d/file_url_download_initiate/[g/{gateway_key}][d/{device_key}]"

Payload:

{
    "fileUrl": string
}
Download status

Channel:
"d2p/file_url_download_status/[g/{gateway_key}][d/{device_key}]"

Payload:

{
    "fileUrl": string,
    "status": Status,
    "error": integer,(present only if the status is ERROR)
    "fileName": string (present only if the status is FILE_READY)
}
Download abort

Channel:
"p2d/file_url_download_abort/[g/{gateway_key}][d/{device_key}]"

Payload:

{
    "fileUrl": string
}

File deletion

The Platform issues a command to the device to delete one or purge all downloaded files. Upon receiving the command and deleting files the device will respond with the list of available files (See File listing).

Channels

Name Direction Path
File delete Platform to Device p2d/file_delete/{path}
File purge Platform to Device p2d/file_purge/{path}
File delete

Channel:
"p2d/file_delete/[g/{gateway_key}][d/{device_key}]"

Payload:

{
    "fileName": string
}
File purge

Channel:
"p2d/file_purge/[g/{gateway_key}][d/{device_key}]"

Payload:
None

File listing

The device will send the list of all existing files to the Platform after connection or when a change occurs.
Optionally, the Platform may issue a command to the device to request a list of all downloaded files and the device will respond.
The device is the only source of truth and the Platform must synchronise its file listing to whatever list of files the device sends.

Channels

Name Direction Path
File list request Platform to Device p2d/file_list_request/{path}
File list response Device to Platform d2p/file_list_response/{path}
File list update Device to Platform d2p/file_list_update/{path}
File list confirm Platform to Device p2d/file_list_confirm/{path}
File list request

Channel:
"p2d/file_list_request/[g/{gateway_key}][d/{device_key}]"

Payload:
None

File list response

Channel:
"d2p/file_list_response/[g/{gateway_key}][d/{device_key}]"

Payload:

{
    [
        {
            "fileName": string
        }
    ]
}
File list update

Channel:
"d2p/file_list_update/[g/{gateway_key}][d/{device_key}]"

Payload:

{
    [
        {
            "fileName": string
        }
    ]
}
File list confirm

Channel:
"p2d/file_list_confirm/[g/{gateway_key}][d/{device_key}]"

Payload:

{
    "result": "OK"
}

File management statuses

Status Description
FILE_TRANSFER File transfer in progress
FILE_READY File transfer completed
ERROR An uncorrectable error occurred during the file upload/download
ABORTED File upload/download aborted by the user

File management errors

Code Name Description
0 UNSPECIFIED_ERROR An unexpected error occurred.
1 TRANSFER_PROTOCOL_DISABLED Requested file transfer protocol is not supported on the device.
2 UNSUPPORTED_FILE_SIZE File size is greater than that supported by the device.
3 MALFORMED_URL Given file URL is malformed.
4 FILE_HASH_MISMATCH File with the same name but different hash is already present on the device.
5 FILE_SYSTEM_ERROR Firmware file cannot be handled on the device due to a file system error.
10 RETRY_COUNT_EXCEEDED A device has failed to recover from error 3 times in a row during upload/download.