IoT Cloud Twins reference
Overview
This feature is currently in beta status.
Cloud Twins are virtual representations of your physical assets. Technically, they are JSON document sets stored in the Hub. You can store and fetch data at any time in those documents.
A Cloud twin is associated with each Device and remains online regardless of the actual device state.
- The Hub provides a REST API to all twins.
- The device has a dedicated inband API over MQTT to interact with its own twin.
Document store
Each twin is a document store that can hold several JSON documents.
A Document is identified by the twin ID (twin_id
) and a name.
As each device has a twin: the twin_id
is equal to the corresponding device_id
.
Document name
There is a restriction on the characters allowed to form a document_name
. Valid characters are limited to: letters, numbers, dashes, underscores, dots and tildes ([-_.~0-9a-zA-Z]
).
The document named _config
is reserved and cannot be used as a normal document see the twins configuration section below.
Create your documents in such a way that REST and MQTT inband API do not write the same. A good example is the current_state
/ desired_state
pair.
Document format
A document is a JSON formatted object with the following format:
{ "version": 1, "data": { }}
Where:
version
is the current version of the document, it starts with1
and is increased in one every time the document is changed.data
can be filled with any valid JSON object of your choice.
Names starting with the underscore _
character are reserved. While still valid, you should avoid using special characters in your key name (in particular dot .
and slash /
), as both might conflict with future API and configuration options.
Accessing the documents
The concepts for both MQTT and REST APIs are similar. There are 3 basic operations you can perform on a document:
- Get: Get the content of a chosen document.
- Put: Create or replace a document.
- Patch: Update a part of a document (see the patch format section below).
Simplified version handling
To manage concurrency and ensure that each user has a chance to modify the document without losing changes made by another user, the Cloud Twins feature provides locking through version numbers.
- A document is created with version 1.
- For every change made to the document the version number is increased by one
- To avoid data loss, a user must provide the current version number along with the modifications to the document.
- If the provided version is incorrect, the operation is not carried out and an error is returned.
For simple usages, concurrency is not typically an issue. Providing a version is optional. If you do not set it or set it to 0, the version constraint for that request is ignored.
Document patch format
The patch format is a regular JSON document respecting the following rules:
- Keys not in the patch are not modified.
- Keys with a null value in the patch are removed.
- Keys with a non-null value behave this way:
- Primitive types (strings, numbers, booleans) are replaced.
- Arrays are fully replaced and cannot contain null values.
- Objects sub-keys are updated using the same rules.
Cloud twins REST API
The REST API is documented on the Scaleway Developers Website.
Cloud twins inband MQTT API
The device can communicate with its twin through inband MQTT API.
The general use of the inband MQTT API is similar for all methods (get, put, patch):
- Subscribe to the response topic.
- Publish a request.
Note:
Inband API MQTT messages are not dispatched to other devices. A response is only sent to the connection issuing the request.
Response Topics
The response topics use the following scheme:
$SCW/twins/<twin_id>/<document_name>/<method>/response/error
$SCW/twins/<twin_id>/<document_name>/<method>/response/success
Where:
<twin_id>
is the twin id or alternatively the stringme
.<document_name>
is the document name.<method>
is one ofget
,put
orpatch
.
In case of an error, the response will arise on the …/error
topic with a payload formatted in JSON as follows:
{ "error": "<error message>"}
In case of success, the response will arise on the …/success
topic with the (new) document:
{ "version": <x>, "data": { <...customer_data> }}
The get method
To implement a get:
- Subscribe to the
get
response topics. - Publish an empty payload on
$SCW/twins/<twin_id>/<document_name>/get
. - You should receive the document on the
$SCW/twins/<twin_id>/<document_name>/get/response/success
topic (or an error on the …/error
topic).
The put method
To implement a put:
- Subscribe to the
put
response topics. - Publish a valid document JSON on
$SCW/twins/<twin_id>/<document_name>/put
. - You should receive the document on the
$SCW/twins/<twin_id>/<document_name>/put/response/success
topic (or an error on the …/error
topic).Note:See the version handling section above.
The patch method
To implement a patch:
- Subscribe to the
patch
response topics. - Publish a patch formatted document on
$SCW/twins/<twin_id>/<document_name>/patch
. - You should receive the document on the
$SCW/twins/<twin_id>/<document_name>/patch/response/success
topic (or an error on the …/error
topic).Note:See the version handling and patch format sections above.
Twins configuration
The _config
document associates configuration values with your documents. Its keys and subkeys enable more twins features.
The _config
document is accessed as a normal twin document. However its content has a special meaning.
Configuration document format
The _config
document is formatted as follows:
{ "version": <x>, "data": { "documents": { "<document_name>": { "_<config_key>": "<config_value>", "<document_key>": { "_<config_key>": "<config_value>" } <...> }, <... more document names> } }}
<document_name>
is the name of the document you want to configure._<config_key>
,<config_value>
are configuration parameters, see the configuration parameters section below.<document_key>
is a key of your document where you want a more precise configuration.
The document is seen as a tree, when a configuration parameter is set it is applied to all the subkeys of this level. Setting the same _<config_key>
for a particular <document_key>
will replace the values for this <document_key>
and all its subkeys (these can be replaced by null
to delete the configuration).
Configuration parameters
The following parameters are available:
_tags
: associates a set of tags (key/value pairs) with the key._tsdb_trigger
: enables pushing all the numerical subkeys to a Time Series Database. Possible values areon-update
oron-change
.on-update
will trigger the push whenever the value is present in a successful Put or Patch request.on-change
will trigger the push whenever the value is modified by a Put or Patch request.
Time Series Database integration
Currently, only the Graphite Database integration is available.
The integration is enabled at two levels:
-
By setting the push url of your graphite instance.
-
By using the
_config
document to select which keys to push.Only the numerical values are supported (booleans are converted to 0 or 1): when selecting a document or key in the configuration, only the numerical values of the leaves under it will be pushed.