Integrations

Throughout the previous articles, the data received by the devices are either displayed in their raw form in Live View panels or displayed in Dashboards.

What about the case where the data need to be sent/captured by 3rd party applications?

insigh.io platform offers 3 different ways of accessing the device data as an external application / user.

  1. Directly subscribe on the device Data Channel with MQTT. Regardless of the protocol that the devices use to upload data, if a user or application subscribes to the topic channels/<data-channel-id>/messages/# or channels/<data-channel-id>/messages/<device-id> will receive all the raw measurements as soon as they are received by the insigh.io platform.
    • the MQTT subscription, requires username/password. The data channels of each user can only be accessed using the Device ID/Key of any device.
  2. Use HTTP API: As described in article HTTP API description device data can be queried and retrieved on demand.
  3. Integrations: Use the build-in Integrations service of insigh.io platform. The service listens to all device messages, and based on filters, it is responsible of redirecting the message to 3rd party systems over MQTT, HTTP or socket.io. It also supports the option to alter the message format using Decoders to match 3rd party system requirements.

MQTT redirection

Setting up an MQTT integration, the service publishes every message received at a selected topic to a 3rd party MQTT broker. First thing of each MQTT integration is to setup the connection details of the remote MQTT broker. The connection details includes:

  • MQTT broker URL
  • MQTT broker Port
  • Username (optional)
  • Password (optional)

Integrations MQTT

HTTP redirection

Setting up an HTTP integration, the service calls the provided HTTP API upon receiving every message. For instance, this could be an HTTP API that a remote system requires to store locally the device data. The connection details includes:

  • HTTP URL
  • HTTP method (POST, PUT)
  • Username (optional): if HTTP authentication is required
  • Password (optional): if HTTP authentication is required
  • Headers: JSON with the custom Headers to be used in the request.
  • Query Params: JSON with the query Parameters that the URL might require

Integrations HTTP

socket.io

under construction

Decoders

Regardless the selected communication protocol, each can optionally be altered before forwarded to a 3rd party system. This operation is done by setting up a Decoder.

Each decoder is a Javascript callback that is called for every message that passes the topic filter with:

  • arguments:
    • deviceId: the device ID as provided by the Device Info view.
    • senmlMessage: the raw SenML message as provided by the device.
  • expected return:
    • any string message. Objects must be stringified before returning.

By default there are a couple of decoders ready to be used that cover very common cases of message decoding. (the list will be expanded in the future, as requested)

  • influx DB line: translate into a line that when posted to an influx service will be immediately stored
  • JSON: convert the SenML message into a simple JSON string. Common case is its use in Telegraf.
  • Custom: an empty callback ready to be coded to user needs

Each implementation can be tested on the fly the evaluating the expressing against an example of input message, returning the result in the Evaluated Output field.

Note: the registered decoders can be used across transfer protocols

Integrations HTTP

Setting up rule with message filter

The final step is to create a Rule. In the Rule setup, the user defines the incoming message filter, the outgoing path (if applicable), the transfer protocol that has been setup before and optionally a Decoder.

  • In Rule: a string relating to the MQTT topic of the Data Channel or the Control Channel. It is accepted only if the channel id defined is accessible by user that create the rule! Supports regexes.
    • example with regex: channels/bc7d700d-7b04-4576-ac52-c281558f9f99/messages/.*: capture messages from published by any device on the data channel with id: bc7d700d-7b04-4576-ac52-c281558f9f99
    • example: channels/bc7d700d-7b04-4576-ac52-c281558f9f99/messages/0d129ed0-0109-4ead-97da-43302a758eed: capture messages published only by device with ID: 0d129ed0-0109-4ead-97da-43302a758eed
  • Out Rule: (applicable only for MQTT integrations) the MQTT topic of the remote MQTT broker where the message will be published
  • Destination Broker, HTTP Hook: select the previously configured 3rd party system details
  • Decoder: select the active decoder to be run for each message

When the Rule it is marked as Active. Each rule can be paused or started by editing the rule and pressing Pause or Play button.

Integrations HTTP