Device Communication

In the previous articles, we have described how to create a device, access its info and its live data. During the demo on how to send data, the quick commands have been used. In this article, the format of those commands will be explained, along with alternative options.

insigh.io platform supports multi-protocol message retrieval over:

  • HTTP
  • MQTT
  • CoAP

All protocols follow some common principles on:

  • the authentication
  • the formatting of the command
  • the message content format

In the Device Info view, there are 4 Communication Values. The Device ID/Key which will be used to specify the device that is uploading the data and the Key as the authentication method. Follows the Data Channel ID and the Control Channel ID which are specific data channels created for the User. The Data Channel is used to accept the device measurement uploads. On the other hand, Control Channel is used to bidirectionaly exchange control messages between devices and platform, such as OTA requests, Remote Configuration requests, device statistics upload, etc.

For the authentication, the ID/Key is combined with the channel id to specifically check device access to the specific data stream.

Regarding the message format, even though any message format can be passed to the platform, only if it is formatted as SenML message will it be processed by the various tools of the platform.

The advantages of SenML message format it that it formalizes how to provide device ID, multiple measurements with values and message timestamps.

Example message: [{"n":"board_humidity","u":"%RH","bn":"aa00bb11ccdd-","v":27.96, "dt":1659612813},{"n":"board_temp","u":"Cel","v":33.74}]

which expands to:

  • device mac: aa00bb11ccdd
  • measurement epoch timestamp: 1659612813
  • board_humidity: 27.96 %RH
  • board_temp: 33.74 Celsius

Having explained the basic principles, lets see how each protocol is used with the insigh.io platform.

HTTP

Send message over HTTP protocol (POST method):

Requires: device_id, device_key, data_channel_id

curl -s -S -i -X POST -H "Content-Type: application/json" -H "Authorization: <device_key>" http://console.insigh.io/http/channels/<data_channel_id>/messages/<device_id> -d '[{"n":"board_humidity","u":"%RH","bn":"aa00bb11ccdd-","v":27.96, "dt":1659612813},{"n":"board_temp","u":"Cel","v":33.74}]'

For HTTPS, devices can use it directly, though curl requires the public certificate to be explicitly defined. Download it from here and run the following command:

curl -s -S -i --cacert ./console-insighio.crt -X POST -H "Content-Type: application/json" -H "Authorization: <device_key>" https://console.insigh.io/http/channels/<data_channel_id>/messages/<device_id> -d '[{"n":"board_humidity","u":"%RH","bn":"aa00bb11ccdd-","v":27.96, "dt":1659612813},{"n":"board_temp","u":"Cel","v":33.74}]'

MQTT

The examples utilize mosquitto MQTT client

Send

Send message over MQTT protocol (Publish):

Requires: device_id, device_key, data_channel_id

mosquitto_pub -u <device_id> -P <device_key> -t channels/<data_channel_id>/messages/<device_id> -h console.insigh.io -m '[{"n":"board_humidity","u":"%RH","bn":"aa00bb11ccdd-","v":27.96, "dt":1659612813},{"n":"board_temp","u":"Cel","v":33.74}]'
Listen

Listen for messages over MQTT protocol (Subscribe):

Requires: device_id, device_key, data_channel_id

mosquitto_sub -u <device_id> -P <device_key> -t channels/<data_channel_id>/messages/<device_id> -h console.insigh.io -v

CoAP

Send messages over CoAP protocol (POST) to the URL:

Requires: device_id, device_key, data_channel_id

coap://console.insigh.io/channels/<data_channel_id>/messages/<device_id>?auth=<device_key>