Connectors APIs

Connectors are connectivity layer of CloudThing software stack and consist of APIs for Open Source IoT protocols, networking stacks (Sigfox, LoRaWAN) and others. It is possible to develop custom connector if required (ask us about it: hello@cloudthing.io).

General

The connectors share a general concept of channels. CloudThing creates 4 messaging channels for every device in system:

  • Data: v1/{deviceId}/data
  • Events: v1/{deviceId}/events
  • Commands: v1/{deviceId}/commands
  • Responses: v1/{deviceId}/responses

Data channel is used for device-to-cloud communication and is intended to be used as ordinary, regular measurements stream (eg. temperature, pressure).

Events channel is used for device-to-cloud communication and is intended to be as non-regular event reporting stream (eg. button pressed). It is possible for device to get response from cloud using this channel, so one may consider it as a remote (on cloud) function execution.

Commands channel is used for cloud-to-device communication and is intended to be used for sending execution commands or configuration options from user/application to device (eg. turn on LED, set config).

Responses is bidirectional channel supporting commands and events. It differs between connectors.

Serialization formats

CloudThing connectors support different serialization formats including:

  • JSON,
  • CBOR,
  • Google Protocol Buffers,
  • custom formats.

Only messages sending via data channel requires to use one of supported serialization formats.

JSON

The basic stucture of data message is:

{
        "records": [
                {"key":"temp", "value": 36.6},
                {"key":"bat", "value": 3.5}
        ]
}

Value can by any JSON base type object (number, string, bool). Soon, we’ll enable usage of nested JSON object.

Every entry may also include time as RFC3339-formatted string, Unix timestamp (number) of diff between previous point (number):

{
        "records": [
                {"key":"temp", "value": 36.6, "time":"2016-05-03T13:24:16Z"},
                {"key":"bat", "value": 3.5, "time": 6}
        ]
}

It is also possible to geo-locate measurements by adding:

{
        "records": [
                {
                        "key":"temp",
                        "value": 36.6,
                        "geo": {
                                "lat": 52.24325,
                                "lon": 26.32256
                        }
                },
                {"key":"bat", "value": 3.5}
        ]
}

JSON serialization supports also indexing of entries what is really helpful in decreasing message size when sending lot of entries in one message:

{
        "index": ["temp", "bat"],
        "records": [
                {"key":0, "value": 36.6},
                {"key":1, "value": 3.5}
        ]
}

To reduce size even more, one can use shorter field names:

{
        "i": ["temp", "bat"],
        "r": [
                {
                        "k":0,
                        "v": 36.6,
                        "g": {
                                "lt": 52.24325,
                                "ln": 26.32256
                        }
                },
                {"k":1, "v": 3.5}
        ]
}

CBOR

CBOR or Constrained Binary Object Representation is JSON-compatible binary format designed for constrained devices.

This serialization format is higly recommended for production and most use-cases.

When using it, one can pack data as shown for JSON with short field names.

Google Protocol Buffers

Since Protobuf is unstructured format and requires struct definitions when (de)serializing, you’ll need to provide us with your .proto file. Get in touch hello@cloudthing.io.

Custom

You can use custom format and transform it to our internal one by implementing transform function which we use on every incoming data point.

MQTT API

MQTT is a lightweight messaging protocol implementing publish/subscribe model.

MQTT connector allows devices to use it for cloud communication.

Broker

MQTT connector broker allows TCP and TLS connections on ports 1883 and 1884 respectively of virtual host (eg. tenant-name.cloudthing.io:1883).

Authentication

Device has to provide proper authentication credentials as MQTT’s username and password. Client ID is not taking into account during authentication process.

  • Username: {tenant-name}:{deviceId},
  • Password: {deviceToken}.

Topics

For publishing measurements to data channel one has to use topic v1/{deviceId}/data?ct=json where ct parameter defines content type and may be on of:

  • json,
  • cbor,
  • proto,
  • custom.

custom is default one.

The publish example using mosquitto_pub:

mosquitto_pub -h short-name.cloudthing.io \
-u short-name:SoMEc0MpL1Cat3D1D \
-P 3xAmpLeT0K3n \
-t v1/SoMEc0MpL1Cat3D1D/data?ct=json \
-m '{"r":[{"k":"temp","v":36.6}]}'

New event may be generated by publish to topic v1/{deviceId}/events/{eventId}.

To recieve commands, device needs to subscribe on topic v1/{deviceId}/commands/+. Every incoming message will have command id (name) as a last part of MQTT topic.

HTTP API

HTTP is a well-known and widely implemented protocol, although it is considered as too heavy for small, constrained devices.

Host

HTTP connector allows devices to use unencrypted or encrypted (TLS) version of protocol.

The HTTP server listens on port 81 and HTTPS on port 444 of tenant’s virtual host.

Authentication

The connector supports Basic authentication with:

  • Username: {deviceId},
  • Password: {deviceToken}

Content Type

Connector supports all available serialization formats and maps “Content-Type” header to format as follows:

  • “application/json” -> JSON,
  • “application/cbor” -> CBOR,
  • “application/octet-stream” -> PROTOBUF,
  • other -> CUSTOM.

Endpoints

Endpoints are created by appending channel name to base path:

  • Data (POST): {scheme}://{short-name}.cloudthing.io:{port}/v1/{deviceId}/data
  • Events (POST): {scheme}://{short-name}.cloudthing.io:{port}/v1/{deviceId}/events/{eventId}
  • Commands (GET): {scheme}://{short-name}.cloudthing.io:{port}/v1/{deviceId}/commands
  • Firmware (GET): {scheme}://{short-name}.cloudthing.io:{port}/v1/deviceId}/fw/dl/{firmwareId}

Commands supports streaming (subscribtion) and long connections (similar to MQTT’s subscribe). Streaming must be enabled by adding ?stream={keepAliveMilliseconds} as query parameter, where keepAliveMilliseconds is a period of time after which cloud will send blank message to keep connection alive. Chunked streaming is implemented with respect to Chunked responses specification, command id (key) is send as parameter of every chunk.

Example sending data:

curl -H "Content-Type: application/json" \
-u "SoMEc0MpL1Cat3D1D:3xAmpLeT0K3n" \
-X POST https://short-name.cloudthing.io:444/v1/SoMEc0MpL1Cat3D1D/data \
-d '{"r":[{"k":"temp","v":36.6}]}'

Example subscribtion for commands:

curl -H "Content-Type: application/json" \
-u "SoMEc0MpL1Cat3D1D:3xAmpLeT0K3n" \
-X GET https://short-name.cloudthing.io:444/v1/SoMEc0MpL1Cat3D1D/commands?stream=10000

CoAP API

CoAP connector and API will be released soon. Note, that it will be recommended way of connecting constrained devices.

Sigfox

CloudThing is integrated with Sigfox backend and it is possible to gather all data from Sigfox deployment in our cloud. To start using it, you need to enable Sigfox connector and choose parsing JavaScript function in Control Center application. Then, you need to configure your Sigfox backend with HTTP POST callback as follows:

http://short-name.cloudthing.io:82/sigfox/{{productId}}?id={device}&data={data}

Example:

http://vanilla-ice.cloudthing.io:82/sigfox/SoMEc0MpL1Cat3D1D?id={device}&data={data}

The Things Network

CloudThing is integrated with TTN network and it is possible to create devices and connect them via OTAA to cloud. The connector will be enabled in Week 22.

LoRaWAN networks

It is possible to connect to commercial LoRaWAN network or deploy private one with our software stack. Ask us about it hello@cloudthing.io.