Device Telemetry API

Overview

The Opti Device Telemetry API allows systems integrators to send data to the Opti Platform. It can be used to integrate many different data sources via the HTTP protocol, including:

SCADA PLCs.
Cellular Data Loggers.
Smart Sensors.
Monitoring Agents.
Custom or proprietary data collection platforms.

This document is intended for a systems integrator or web developer fluent with HTTP protocol, JSON-formatted data, and the sources of data being integrated. It contains details required to integrate your device with the Opti Platform, including how to configure your device, and what metadata you must provide to the platform describe the data you send before you start sending it.

What is a Device

A compatible “Device” is any hardware system or application process that: 1. Makes observations of up to 32 metrics at the same moment in time (referred to a snapshot). 2. Is capable of sending HTTPS POST requests with JSON-formatted payloads and a specific header over the public Internet.

Register a Device with the Opti Platform

To get started, you need to register your Device with the Opti Platform. Registering a device results in the two pieces of data necessary to configure that device to send data to the Opti Platform:

A unique Device ID (“Device ID”) that identifies the data you send to the Opti Platform.
Device Subscription Keys (one primary, one secondary) that authorize sending data to your Opti Account from your Device.

You Opti Product Delivery representative will assist you in registering your devices on the Opti Platform.

Device ID

Registering a device with the Opti Platform results in a Device ID to use when sending data to Opti from that device. The Device ID is an up-to-40-characters-long, alphanumeric-plus-hyphen string that uniquely identifies a device that sends data to the Opti Platform. Opti will provide a Device ID when a Device is registered with the Opti Platform.

Device Subscription Key

When a device is registered the Opti Platform creates two Subscription Keys, Primary and Secondary, to authorize requests made from that device. The Primary and Secondary keys allow you to rotate the keys on the device without any downtime - there is no need to use one over the other or both at any time.

The combination of your Device ID and Device Subscription Keys allow data to be sent from your device. Please take care to store these keys in a secure location. To rotate your device’s Subscription Keys, please contact your Opti Sales or Product Delivery representative.

Specifying Metadata

Metadata are descriptive terms about the metrics you send to Opti. Opti uses metadata to present and help users find your data in Opti web portals and other reporting tools. Metadata for each metric includes location, data type, unit of measurement, and a unique name. Metadata for each device describes its expected messaging frequency, which allows the Opti Platform to assess when an operational issue is likely to have occurred and notify the appropriate individuals.

As soon as you have Registered a Device with the Opti Platform you will be able to send data to the Opti Platform with those device credentials and not receive 401 - Access Denied. However, you will not be able to see or otherwise access the data you send, nor will Opti store it, until you define its metadata.

Device Metadata

Field	Description	Example
Expected Reporting Interval	The longest expected duration between data reports from this Device during normal operations, in seconds.	900 seconds
Expected Observation Interval	The expected duration between the snapshots reported by this device, specified either as a number (in seconds) greater than 1 or as ‘Adaptive’, meaning observations are always collected in response to some locally observed condition occurring. The Expected Observation Interval must be less than or equal to the Expected Reporting Interval.	300 seconds
Outage Recipients	Comma-separated list of email addresses to notify when this device has an extended outage. Notifications will be sent periodically to these addresses from alerts@optirtc.com during prolonged outages until the device is paused or otherwise shut down.	admin@envmgmtco.com, maintenance@example.com, ssmith@engineer.com

Metric Metadata

All metrics defined for a Device and included in a message sent from that Device will be persisted in Opti and made available via the Opti Platform APIs.

For each metric you ship, you must provide:

Field	Description	Example
Name	The field of the JSON payload containing this metric’s values. The field must be alphanumeric, must not be “observationTime” or “OnlineStatus,” and cannot be longer than 60 characters.	“PT1”, “PT2”, “sensor1”, “sensor2”, “sensor3”, “temp”, “turb”
Title	Optional. A human-friendly name for this metric. If none is specified, the Name will be used.	“Piezometer 1”, “Piezometer 2”, “Sensor 1”, “Sensor 2”, “Sensor 3”, “Temperature”, “Turbidity”
Unit of Measure	The unit of measure of this metric.	Inches, degrees Fahrenheit, degrees Celsius, cubic feet per second
Data Type	The expected data type of the metric’s values. One of: “Int32, Int64, Double, DateTime, or String.” All types except Int32 support 64-bit values. String characters are interpreted as UTF-8.	Int32, Int64, Double, DateTime, or String. Observations of metrics with String data type can be up to 2Kb in size.
Property	The general term for the metric, independent of its specific name for this installation.	Elevation, Flow Rate, Precipitation Intensity
Medium	The source environment that is sampled, observed, or measured to produce the metric values.	Water, air, network
Procedure	The make and model of the device, or other identifying name of the process that created these data points.	Ultrasonic flowmeter, acoustic backscatter
Latitude	Latitude WGS84 coordinates of the sampling location, in decimal degrees.	42.361145
Longitude	Longitude WGS84 coordinates of the sampling location, in decimal degrees.	-71.057083

Updating Already-Sent Snapshots

Sometimes time-series data changes after it was originally observed. For example, a manual QA/QC process may determine that sensor measurements need corrections. The Opti Platform provides a means for devices to update snapshot values that were sent previously - all you have to do is send snapshots with the same timestamp as a snapshot that was already sent. After a short period of processing, the updated values will be visible on dashboards and anywhere else the data is consumed. Opti maintains a copy of the original value of any updated snapshots to ensure traceability of any alarms, events, and device commands based on the original values. The Opti Support team (support@optirtc.com) can aid customers who are interested in the original values of any snapshots.

Batch Requests

If a Device has more than 100 Kb of data to send, it can do so via Batch Requests. Batch Requests allow Devices to break a large set of observations into multiple HTTP requests. This pattern enables Devices to send more data per time than they otherwise would be allowed (see Device Throttling). The Opti Platform waits until an entire batch has been sent before processing the received data and making it available via APIs and dashboards. Received but unprocessed batch messages are dropped when a message from the same device and a new batch is received, or the whole batch is not received within 5 minutes of the first message, whichever comes first.

To send Batch Requests, include a Batch-Details header with each HTTP request. The value of the Batch-Details header must consist of 3 values delimited by ‘-’ characters as shown:

Batch-Details: {Batch Request Number}-{Total requests In Batch}-{Batch ID}

The values of of the Batch-Details are:

‘Batch Request Number’ is a positive integer (1, 2, 3, …) identifying the request in the batch. For example, the first request of a batch of 3 requests should use 1 for the Batch Request Number, and the last request should use 3.
‘Total Requests In Batch’ is the total count of requests that will be included in the batch. The maximum number of requests allowed in a batch is 999.
‘Batch ID’ is a unique set of characters that the device will not repeat across consecutive batches of data. Opti suggests using the epoch time that the device starts sending the messages as a Batch ID if that is accessible. If sending a batch is interrupted for more than 5 minutes, the device should restart sending from the beginning of that batch.

Up to 10 Days per Batch

All snapshots sent in a given Batch Request (i.e. with the same Batch ID) must have observationTimes within a 10 day window of time. If you need to upload data for a period spanning longer than 10 days, you must break your requests into multiple batches.

Device Throttling

In order to ensure availability of platform services, data sent via the Device Telemetry API is limited per device in several ways, including limits to the size of individual messages and the rate messages can be sent, known as message throttling. There are two throttles in place, which are applied to all requests for a specific Device ID.

Throttle	Criteria
Maximum request rate	100 requests per 5 minutes per Device
Maximum batch rate	1 distinct Batch ID per Device per 45 seconds. Requests without a valid Batch-Details header are considered to be their own batch, and count against this limit.

The combined effect of these rules is:

Devices can initiate sending data to the Opti platform once every 45 seconds at most.
Devices can send batch parts as quickly as they are able without worrying about throttling as long as the batch is less than 100 messages.

All throttled requests will include a 429 HTTP Status Code in the response, along with information about when the device should retry its operation. An assumption any device can make if it receives a 429 Status Code - without having to parse and react to the information in the response body - is “wait 5 minutes and try again.”

Authorization

You must include either the Primary or Secondary Device Subscription Key provided by Opti Support in the Authorization HTTP header for all requests for a given device.