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
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 names should comply to the following format:
"{direction}/{message_type}[_{method}]/{path}"
Device outbound messages channels are prepended with “d2p”.
Device inbound messages channels are prepended with “p2d”.
The identifier which categorises messages by type (Sensor reading, actuation request, etc.)
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} = "[/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)
| 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} |
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.
"lastwill/[{gateway_key}][{device_key}]"
None (optional)
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.
Channel:
"ping/[{gateway_key}][{device_key}]"
Payload:
None (optional)
Channel:
"pong/[{gateway_key}][{device_key}]"
Payload:
{
"value": int, (current Platform UTC timestamp)
"command": "SET"
}
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.
| 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 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.
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.
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")
}
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
}
}
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”
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. |
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).
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).
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. |
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"
}
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
}
| 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. |
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
}
Use Case 1
If device status is omitted for a device, that device will be considered offline.
Use Case 2
Use Case 3
Use Case 4
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} |
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.
Channel:
"p2d/firmware_update_install/d/{device_key}"
Payload:
{
"fileName": string
}
Channel:
"p2d/firmware_update_abort/d/{device_key}"
Payload:
None
Channel:
"d2p/firmware_update_status/d/{device_key}"
Payload:
{
“status”: Status,
“error”: integer (present only if status is ERROR)
}
Channel:
"d2p/firmware_version_update/d/{device_key}"
Payload:
string
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.
Channel:
"p2d/firmware_update_install/g/{gateway_key}"
Payload:
{
"devices": [device_keys], (can include gateway_key)
"fileName": string
}
Channel:
"p2d/firmware_update_abort/g/{gateway_key}"
Payload:
{
"devices": [device_keys]
}
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
| 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. |
| 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. |
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.
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).
| 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} |
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)
}
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)
}
Channel:
"p2d/file_upload_abort/[g/{gateway_key}][d/{device_key}]"
Payload:
{
"fileName": string
}
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.
Channel:
"d2p/file_binary_request/[g/{gateway_key}][d/{device_key}]"
Payload:
{
"fileName": string,
"chunkIndex": integer,
"chunkSize": integer
}
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).
| 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} |
Channel:
"p2d/file_url_download_initiate/[g/{gateway_key}][d/{device_key}]"
Payload:
{
"fileUrl": string
}
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)
}
Channel:
"p2d/file_url_download_abort/[g/{gateway_key}][d/{device_key}]"
Payload:
{
"fileUrl": string
}
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).
| Name | Direction | Path |
|---|---|---|
| File delete | Platform to Device | p2d/file_delete/{path} |
| File purge | Platform to Device | p2d/file_purge/{path} |
Channel:
"p2d/file_delete/[g/{gateway_key}][d/{device_key}]"
Payload:
{
"fileName": string
}
Channel:
"p2d/file_purge/[g/{gateway_key}][d/{device_key}]"
Payload:
None
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.
| 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} |
Channel:
"p2d/file_list_request/[g/{gateway_key}][d/{device_key}]"
Payload:
None
Channel:
"d2p/file_list_response/[g/{gateway_key}][d/{device_key}]"
Payload:
{
[
{
"fileName": string
}
]
}
Channel:
"d2p/file_list_update/[g/{gateway_key}][d/{device_key}]"
Payload:
{
[
{
"fileName": string
}
]
}
Channel:
"p2d/file_list_confirm/[g/{gateway_key}][d/{device_key}]"
Payload:
{
"result": "OK"
}
| 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 |
| 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. |