Thingsee Open Services API message sequences

If you decide to use Thingsee Open Services API then these are the sequences and requirements that you should follow. It is not mandatory to follow all these sequences and you are allowed to be more creative than this. However, these are the best practices that we have learned from the different installation processes and tools with our customers.

These examples makes your life easier and our management operations less painful.

Authenticate to the API

sequenceDiagram
    participant YC as YourCloud
    participant A as ThingseeAPI
    YC->>A: POST /auth/client-token
    A->>YC: 200 {token}
  • You can ask your credentials from your Thingsee sales rep or send us a message to support@haltian.com

Check the spec

Create a group for the device

Every device is assigned to a default group, but to make massive device pools more manageable it is highly recommended that the installation pools are split into more specific groups. Groups can be created by your cloud or by your installation application. The group definition and resolution is up to your own design; you can create a group for Northern Finland or you can create a group for Lab in HQ. A group can contain a single device or a gazillion of devices.

Read more details how you must construct the group id. Note that this API requires you to give a full groupid e.g. prfi00northernfinland.

sequenceDiagram
    participant YC as YourCloud
    participant A as ThingseeAPI
    YC->>A: POST /groups {group_id}
    A->>YC: 200

Check the spec

Activate the device during the installation process

The following sequence uses YourApp as the installation tool, but it can be also some of our standard Thingsee mobile applications that can do the same trick.

Preferably YourApp will also assign the device to a group, so that the device management operations can be targeted for a smaller set of devices.

sequenceDiagram
    participant YC as YourCloud
    participant YA as YourApp
    participant A as API
    participant T as ThingseeDevice
    YA->>T: Read QR code form the sensor
    T-->>YA: Returns PSN,IMC
    YA->>YA: Create TUID = IMC + PSN
    YA->>A: POST /things/{tuid}/installations {status}
    A->>YA: 200
    YA->>YC: Assign the device to a customer asset
    alt Set the group
    YA->>A: POST /things/{tuid}/group
    end

POST /things/{tuid}/installations

POST /things/{tuid}/group

Remotely change the sensor configuration

This one is a bit tricky. You need to create a configuration JSON message (part of Thingsee Message specifications), and sent that to the API. That’s the easy part. Thingsee Cloud will make its magic so that the configuration reaches the sensor device. The sensor will process the message and do whatever the configuration message told it to do, and then replies the new configuration back to the cloud.

The reply (“echo”) comes using the same route as the any other uplink data from the sensor. Therefore you will receive the echo to that other endpoint which is not the REST client you used to sent the data, but instead an MQTT broker or e.g. some Azure IoT hub integration that receives the sensor data anyway.

As you receive the echo you should (not a mandatory thing to do) update your internal inventory of send configuration messages, so that you know what configurations are processed. There are properties in the Thingsee message that makes this configuration-echo mapping straightforward.

sequenceDiagram
    participant YC as YourCloud
    participant A as API
    participant TSD as ThingseeDataAPI 
    participant T as ThingseeDevice
    YC->>YC: Construct configuration JSON
    YC->>A: POST /things/{tuid}/commands {configuration}
    A->>YC: 200
    A->>T: route the configuration message
    T->>T: Process the message
    T->>TSD: echo new config
    TSD->>YC: echo new config
    YC->>YC: update internal configuration inventory

POST /things/{tuid}/commands

Previous
Next