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
- You can ask your credentials from your Thingsee sales rep or send us a message to support@haltian.com
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.
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.
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.
POST /things/{tuid}/commands