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 :
- Via the SPOT web interface (FAQ documentation)
- By REST API (available only in v2) (API documentation)
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