Device Telemetry (1.0)

Download OpenAPI specification:Download

Overview

The Opti Device Telemetry API allows systems integrators to send data to the Opti Platform. It can be used to integrate data sources from a wide variety of platforms including:

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

This document summarizes all you need to know to integrate your device with the Opti Platform:

  • How to configure your device.
  • What metadata you must provide to describe the data you send.

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:

  1. A unique Device ID (“Device ID”) that identifies the data you send to the Opti Platform.
  2. 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:

  1. ‘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.
  2. ‘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.
  3. ‘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. A simple 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.”

Authentication

apiKeyHeader

Either the Primary or Secondary Device Subscription Key provided by the Opti Delivery Team for the device that is sending data.

Security Scheme Type API Key
Header parameter name: Authorization

snapshots

Send sensor observations, statuses, and other telemetry data to the Opti Platform.

Authorizations:
path Parameters
deviceId
required
string

Opti-provided device identifier, used for shipping data to Opti.

header Parameters
Content-Type
string
Default: application/json
Value: "application/json"

The request body must be JSON-encoded; ‘application/json’ is the only valid option.

Batch-Details
string

Individual requests are limited to 100 Kb per payload. The Batch-Details header enables Batch Requests, as may be necessary when a device recovers from a long network outage and uploads all of the observations it recorded during the outage. Opti recommends only using this capability if it is a known requirement - the vast majority of integrations will not require use of Batch Requests or the Batch-Details header.

Request Body schema: application/json

The message body is where snapshots are encoded. A snapshot consists of key-value pairs of metric values or “observations”, and one special key-value pair that defines that snapshot’s timestamp. All timestamps will be truncated to seconds resolution. The special timestamp key-value pair must use the reserved key: “observationTime”. Further, the special timestamp value must be encoded in the subset of the ISO 8601 format defined in section 5.6 of RFC 3339. The format of observations is colloquially referred to as “Flat” JSON, a reference to its simple 1-level hierarchy structure. Refer to Specifying Metadata for a full description of valid snapshot key names.

Opti will ignore any snapshots it receives in which the observationTime is 3 seconds or more in the future from the moment Opti’s service receives it. Device operators are required to keep the clock of their devices synchronized to ensure data flow is not interrupted.

Array ()
observationTime
required
string
sensor1
integer
sensor2
integer
sensor3
number
sensor4
number

Responses

Request samples

Content type
application/json
[
  • {
    }
]