Home Managed Services IoT Hub Reference Content

Understanding Cloud Twins

IoT Cloud Twins reference

Published on 31 August 2021

Overview

Note:

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

Important:

The document named _config is reserved and cannot be used as a normal document see the twins configuration section below.

Tip:

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 with 1 and is increased in one every time the document is changed.
data can be filled with any valid JSON object of your choice.

Important:

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.

Note:

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 string me.
<document_name> is the document name.
<method> is one of get, put or patch.

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 are on-update or on-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.