Sending Telemetry and Controllable Load Data

This tutorial provides a quick guide to submitting telemetry readings (either controllable load or meter readings) via the Voltus API.

About Telemetry and Controllable Load

Telemetry readings represent instantaneous points of energy usage via a point of interconnection. Voltus uses these readings to measure site performance during and after demand-response dispatches. You can also view these readings in the VoltApp Real-Time Energy Dashboard and retrieve them in the API as described in Retrieving Telemetry Data.

Controllable load, on the other hand, is supposed to represent the amount of energy that a site can reduce or increase in response to a dispatch signal. This is meant to help Voltus understand the site's capabilities and constraints in advance of a dispatch.

Requirements

For testing, you can just need a Sandbox API key (or you can use the secret API key). To actually see your sites' telemetry in production, you'll need:

A Voltus API key (VOLTUS_API_KEY). If you don’t have one, email api-support@voltus.co or your Account Manager.
One or more sites configured. If sending telemetry (as opposed to controllable load), these sites must also be configured with meter objects.

Getting Site and Meter IDs

You can skip this step if you already have a set of IDs you want to send telemetry data for.

Otherwise, retrieve a list of your sites through the get /sites endpoint. The following cURL request will do this for you:

curl --header 'X-Voltus-API-Key: YOUR_API_KEY' https://api.voltus.co/2022-04-15/sites

The response will look something like this:

{
  "sites": [
    {
      "name": "site 1",
      "id": "as7f",
      "customer_location_id": "your_id_1",
      "meters": [
        {
          "id": "rtas",
          "name": "meter for site 1"
        }
      ]
    },
    {
      "name": "site 2",
      "id": "k829",
      "customer_location_id": "you_id_2",
      "meters": [
        {
          "id": "1k38",
          "name": "meter for site 2"
        },
        {
          "id": "8j3j",
          "name": "generator meter for site 2"
        }
      ]
    }
  ],
  "page": 0,
  "perPage": 0
}

For sending telemetry, you'll need the meter id (what's under the "meters" object in the above example). For controllable load, you need the site id.

Sending Telemetry

A telemetry reading has 5 components:

interval_seconds: The time interval in seconds for which the reading is valid.
meter_id: The ID of the meter object associated with the reading.
timestamp: The time at which the reading was taken is ISO8601 format.
units: The units of the reading (kW for an instantaneous power reading, kWh to represent energy used).
value: The value of the reading.

To send a telemetry reading, you'll need to send a POST request to the /2022-04-15/telemetry endpoint with a list of these readings. Here's a quick example using cURL:

curl --header 'X-Voltus-API-Key: YOUR_API_KEY' --header 'Content-Type: application/json' --data-raw '{
    "telemetry": [
        {
            "interval_seconds": 30,
            "site_id": "yd4g",
            "timestamp": "2024-01-02T09:00:00Z",
            "units": "kW",
            "value": 300.5
        }
    ]
}' https://sandbox.voltus.co/2022-04-15/telemetry

In this case, we are submitting the data to the sandbox server. This will test that you are sending well-formed payloads, without actually saving the data.

To submit to production, replace sandbox.voltus.co with api.voltus.co (https://api.voltus.co/2022-04-15/telemetry, to be precise).

Sending Controllable Load

Controllable load readings are like telemetry readings, but are associated with a site rather than a meter. Thus, you need to send the site_id instead of the meter_id. These readings are sent to a different endpoint: /2022-04-15/telemetry/controllable-load. Here's an example cURL request:

curl --header 'X-Voltus-API-Key: YOUR_API_KEY' --header 'Content-Type: application/json' --data-raw '{
    "controllable_load": [
        {
            "interval_seconds": 30,
            "site_id": "yd4g",
            "timestamp": "2024-01-02T09:00:00Z",
            "units": "kW",
            "value": 500.0
        }
    ]
}' https://sandbox.voltus.co/2022-04-15/telemetry/controllable-load

As with regular telemetry, replace sandbox.voltus.co with api.voltus.co to submit data to production.

Submitting Data Programatically

Here's a quick python script which you can use as a basis for your own telemetry submission.

This source code to this script can also be found in voltus-api-examples as telemetry/send_telemetry.py.

import dataclasses
import os
import sys
from typing import List, Union

import requests


VOLTUS_API_URL = os.getenv("VOLTUS_API_URL", "https://sandbox.voltus.co/2022-04-15")
VOLTUS_API_KEY = os.getenv("VOLTUS_API_KEY")

s = requests.Session()
s.headers.update({"X-Voltus-API-Key": VOLTUS_API_KEY, "Accept": "application/json"})

@dataclasses.dataclass
class TelemetryReading:
    interval_seconds: int
    meter_id: str
    timestamp: str
    units: str
    value: float

@dataclasses.dataclass
class ControllableLoadReading:
    interval_seconds: int
    site_id: str
    timestamp: str
    units: str
    value: float

def _send_telemetry(url: str, datatype: str, readings: Union[List[TelemetryReading], List[ControllableLoadReading]]):
    try:
        r = s.post(url, json={
            datatype: [dataclasses.asdict(reading) for reading in readings]
        })
        if r.status_code != 200:
            sys.stderr.write(f"Failed to send telemetry: {r.text}\n")
            sys.exit(1)
    except requests.exceptions.RequestException as e:
        sys.stderr.write(f"Failed to send telemetry: {e}\n")
        sys.exit(1)


if __name__ == "__main__":
    if len(sys.argv) < 7:
        sys.stderr.write("Usage: python send_telemetry.py <telemetry_type> <interval_seconds> <meter_or_site_id> <timestamp> <units> <value>")
        sys.exit(1)

    if VOLTUS_API_KEY is None:
        sys.stderr.write("VOLTUS_API_KEY environment variable is unset\n")
        sys.exit(1)

    telemetry_type = sys.argv[1]
    reading_class = None
    if telemetry_type == "telemetry":
        url = f"{VOLTUS_API_URL}/telemetry"
        reading_class = TelemetryReading
    elif telemetry_type == "controllable_load":
        url = f"{VOLTUS_API_URL}/telemetry/controllable-load"
        reading_class = ControllableLoadReading
    else:
        sys.stderr.write("Invalid telemetry type. Must be 'telemetry' or 'controllable_load'\n")
        sys.exit(1)

    # Create a telemetry reading object
    reading = reading_class(
        int(sys.argv[2]), # interval seconds
        sys.argv[3], # site or meter id
        timestamp=sys.argv[4],
        units=sys.argv[5],
        value=float(sys.argv[6])
    )

    # Attempt to send it
    _send_telemetry(url, telemetry_type, [reading])

Next Steps

When you are successfully streaming data to our systems, contact us at api-support@voltus.co. We will mark these sites as enabled, and you (and/or your customers) will be able to see the data in the VoltApp Real-Time Energy Dashboard.

About Telemetry and Controllable Load​

Requirements​

Getting Site and Meter IDs​

Sending Telemetry​

Sending Controllable Load​

Submitting Data Programatically​

Next Steps​