x

Introduction Last updated: 2020-01-12

Messages and values can be routed by the SPOT platform to an external application.

The following protocols or connectors are supported:

  • HTTP/HTTPS,
  • AWS IoTCore,
  • Azure IoTHub, EventHub, IoTCentral and PowerBI
  • Google PubSub and IoT Core
  • MQTT

The body sent to the external application is encoded in JSON and can have the following formats:

  • Messages: the full message exchanged with the devices is sent via the routing
  • Values: only the values are sent via the routing (only available if messages are decoded by the Objenious platform) platform)

How to configure a routing

A routing can be configured :

Messages format

The external application will receive a request for every message exchanged with a device: joins, uplinks, downlinks or external messages.

Example:

                                
    {
        "id": "d5e2c4cc722-126c17ed", // id of message (string)
        "timestamp": "2016-05-04T16:01:26.572226000Z", // RFC3339 date
        "device_id": 3421, // id on the objenious platform (int64)
        "type": "uplink", // join, uplink, downlink, external (string)
        "count": 21, // fcount (int)
        "payload_encrypted": "...", // encrypted payload - hexa (string)
        "payload_cleartext": "...", // decrypted payload - hexa (string)
        "payload": [{
            "timestamp": "2016-05-04T16:01:26.572226000Z", // RFC3339 date
            "data": {
                "Temperature": 21,
                "ButtonPushed": true
            }
        }],
        "protocol_data": {
            "AppNonce": "...",
            "DevAddr": "...",
            "DevNonce": "...",
            "NetID": "...",
            "port": 1
        },
        "device_properties": {
            "external_id": "...", // id on the client platform (string)
            "deveui": "...", // deveui (big endian/hexa) (string)
            "appeui": "...", // appeui (big endian/hexa) (string)
            "property": "value"   // client defined device properties
        },
        "ack": true, // the message is an acknowledgment of a previous message
        "lat": 48.64332, // latitude (float64)
        "lng": 2.34123, // longitude (float64)
        "geolocation_type": "network", // none, tdoa, network, device, zone or fixed (string)
        "command_id": 456, // as set on the downlink request (only present in downlinks) (int32)
        "error": "...", // error (only present in downlink/join in case of an error) (string)
        "delivered_at": "2016-05-04T16:01:26.572226000Z", // (downlink) (RFC3339 date)
        "mac_command": {
            "type": "LINK_ADR_REQ", // type of mac command
            "payload": "0351001001",
            "payload_decoded": {
                "channel_mask_control": ...,
                "channels": [
                  13
                ],
                "data_rate": 5,
                "data_rate_eu": "SF7/125kHz",
                "nb_trans": 1,
                "tx_power": 1,
                "tx_power_eu": "14dBm"
            }
        }
    }
                            
                            

Notes:

  • payload_cleartext is only present if decryption is configured on the Objenious platform,
  • payload is only present if decryption and decoding are configured on the Objenious platform, and will be found in uplink or external messages,
  • payload may contain multiple entries, as decoded,
  • join messages are sent to your platform when a device joins the network,
  • downlink messages are sent to the external application when a downlink request is delivered to the device or when the network decides that a downlink cannot be sent, either due to a timeout, a network error or a message formatting problem,
  • external messages are messages received by the Objenious platform from external platforms – e.g. a third-party service used to decode payloads,
  • ack is only present if set to true, missing if false,
  • an uplink with the ack flag acknowledges the reception of the previous downlink, a downlink with the ack flag acknowledges the previous uplink,
  • if location cannot be computed, latitude and longitude will not be set,
  • some devices report measurements in the past - payload timestamp is the measurement timestamp, as reported by the device, whereas message timestamp is the date the message was processed by the SPOT platform.

Values format

The external application will receive a request for every set of measurements received from the device.

Example:

                                

        "timestamp": "2016-05-04T16:01:26.572226000Z", // RFC3339 date
        "device_id": 3421, // id on the objenious platform (int64)
        "data": {
            "Temperature": 21,
            "ButtonPushed": true
        },
        "device_properties": {
            "external_id": "...", // id on the client platform (string)
            "deveui": "...", // deveui (big endian/hexa) (string)
            "appeui": "...", // appeui (big endian/hexa) (string)
            "property": "value"   // client defined device properties
        },
        "lat": 48.64332, // latitude (float64)
        "lng": 2.34123, // longitude (float64)
        "geolocation_type": "network" // none, tdoa, network, device, zone or fixed (string)
    }
                                
                            

Notes:

  • The values format only works if decryption and decoding a properly configured for the device; no HTTP requests will be sent otherwise
  • When using the values format, a HTTP request will only contain a single set of measurements; if the device sends an uplink containing multiple measurements within a single payload, multiple HTTP requests will be sent
  • If location cannot be computed, latitude and longitude will not be

Events format

The external application will receive a request for every event generated by the SPOT platform for the device.

Example:

                                
    {
        "timestamp": "2016-05-04T16:01:26.572226000Z", // RFC3339 date
        "device_id": 3421, // id on the objenious platform (int64)
        "type": "ChangeStatusInactive", // event type (string) ChangeStatusActive, ChangeStatusInactive, ChangeStatusError, ChangeStatusJoined
        "device_properties": {
            "external_id": "...", // id on the client platform (string)
            "deveui": "...", // deveui (big endian/hexa) (string)
            "appeui": "...", // appeui (big endian/hexa) (string)
            "property": "value"   // client defined device properties
        }
    }
                                
                            

Error handling

If a message cannot be sent to a remote application due to an error (connectivity problem, unavailable remote server, …), the SPOT platform will try again using the following strategy:

  • If the remote server reports a client error (HTTP status codes 4XX), no retries will be attempted,
  • If the remote server is unreachable, or does not respond within 30 seconds, retries will be attempted,
  • If the remote server reports a server error (HTTP status codes 5XX), retries will be attempted,
  • If the remote server reports too many errors or if the average response time is too high, retries may be delayed.

Retries may be attempted multiple times during 30 seconds, every 10 minutes for 2 days.

If the remote server is unreacheable for more than 7 days, the routing scenario may be automatically disabled. You will need to reenable it on the SPOT interface.

Message ordering

In some cases, messages can be sent to the external application out of order:

  • In case of errors, messages may be queued for a later redelivery. New messages may be delivered between the failed delivery attempt and subsequent attempts.
  • Some devices are able to resend missing past measurements. Sometimes, the SPOT platform will detect that measurements are missing, it might ask the device to send the missing data.

In some rare cases, a message can be delivered twice.

Formats

The following formats are used:

  • Times: RFC3339 with optional nanoseconds, UTC timezone - 2016-05-04T16:01:26.572226000Z or 2016-05-04T16:01:26Z
  • DevEUIs and AppEUIs: bigendian/hexadecimal
  • Latitudes and longitudes: WGS84, in degrees
  • Binary data: hexadecimal strings

HTTP/HTTPS

Notes for the HTTPS protocol:

  • Self-signed certificates are not supported,
  • The destination port should be 443, 8443, 8883 or 9443.

Messages sent to the external application using either the "values" format or the "messages" format or "events" format, as described below.

Configuration

You can configure a routing HTTP/HTTPS

Authentication

The following authentication schemes are supported for external HTTP applications:

  • Request parameters located in the URL,
  • Custom HTTP headers (e.g. API Token, Basic Authentication, …).

Dynamic parameters

Dynamic parameters can be added to the destination URL or to header values:

  • {{appeui}} will be replaced by the device AppEUI
  • {{deveui}} will be replaced by the device DevEUI
  • {{external_id}} will be replaced by the "external_id" custom property
  • {{device_id}} will be replaced by the device ID
  • {{device_name}} will be replaced by the device name
  • {{message_id}} will be replaced by the message ID
  • {{group}} will be replaced by the ID of the device group
  • {{type}} will be replaced by the message type (uplink downlink join)
  • {{timestamp}} will be replaced by the timestamp of the message (message format) or the measurement (values format)

Example:

                            
    https://api.example.com/incoming/objenious?device={{device_id}}&message_type={{type}}
                            
                        

AWS

SPOT can be integrated with AWS IoTcore.

AWS IoTcore

The external application will receive a request for every message exchanged with a device: joins, uplinks, downlinks or external messages.

To integrate AWS IoTCore:

Azure

SPOT can be integrated with Azure IoTHub, EventHub, IoTCentral, PowerBi.

Azure IoTHub

SPOT can be integrated with IoTHub.

For each SPOT device, an identity and a device twin are created. Both are created/updated on IoTHub when a message is forwarded to azure for the specified device.

The ID of the device is the same ID used on the REST API. As a device can be recycled, the DevEUI of the physical device may migrate to a new logical device. Multiple logical devices can therefore share the same DevEUI, only one being active at a specific point of time.

Messages sent to Azure use either the "values" format or the "messages" format, as described below.

An Azure IoTHub application needs to use the SPOT REST API to send a downlink to a device (see https://api.objenious.com/doc/doc-swagger-v2.html#tag/downlinks).

To integrate Azure IoTHub:

Azure EventHub

SPOT can be integrated with EventHub. EventHub enables you to forward data to a data lake or a data processing platform, but does not implement device management or cloud-to-device (downlink) communication.

Messages are sent to EventHub either using the "values" format or the "messages" format, as described below.

To integrate Azure EventHub:

Azure IoTCentral

SPOT can be integrated with IoTCentral. IoTCentral enables you to forward data to a data lake or a data processing platform, but does not implement device management or cloud-to-device (downlink) communication.

Messages are sent to IoTCentral either using the "values" format or the "messages" format, as described below.

To integrate Azure IoTCentral:

Azure PowerBI

SPOT can be integrated with PowerBI. PowerBI enables you to forward data to a data lake or a data processing platform but does not implement device management or cloud-to-device (downlink) communication.

Messages are sent to PowerBi using the "values" format, as described below.

To integrate Azure PowerBI:

  • with SPOT interface - Related guide: FAQ (Coming soon)
  • with API - Related guide: API (Coming soon)

Google

SPOT can be integrated with Google Pubsub, IoTCore.

Google Pubsub

SPOT can be integrated with PubSub. PubSub enables you to forward data to a data lake or a data processing platform, but does not implement device management or cloud-to-device (downlink) communication.

Messages are sent to PubSub either using the "values" format or the "messages" format, as described below.

To integrate Google Pubsub:

Google IoTCore

SPOT can be integrated with IoTCore. IoTCore enables you to forward data to a data lake or a data processing platform, but does not implement device management or cloud-to-device (downlink) communication.

Messages are sent to IoTCore either using the "values" format or the "messages" format, as described below.

To integrate Google IoTCore:

MQTT

SPOT can be integrated with MQTT.

MQTT enables you to forward data to a broker or a data processing platform, but does not implement device management or cloud-to-device (downlink) communication.

Messages are sent to broker either using the "values" format or the "messages" format, as described below.

To integrate MQTT:

FAQ

For more information, log into your account and check out the FAQ.