Streaming data

Real-time data is essential for providing flexibility through our platform. Continuous streaming of measurements allows us to:

• Accurately verify flexibility delivery
• Quickly respond to grid needs
• Maximize your activation opportunities

Requirements

You need to stream measurements every 4 seconds for each connected resource and site. This high-frequency data is crucial for:

1. Accurately modeling your resource's behavior
2. Verifying flexibility delivery in real-time
3. Enabling quick responses if resources don't perform as expected

Data Storage

For the 4-second data streaming, there's no need to store the data. You can simply fire and forget, allowing the system to process the data in real-time without the overhead of storage.

Connecting

In order to send over real-time data, we employ the MQTT 5.0 protocol, the standard when it comes to IoT messaging.

You can connect to our MQTT broker using many of the popular MQTT clients out there, as long as it supports the MQTT 5.0 protocol, and TLS.

The following environments are available:

Environment	Broker
Production	mqtts://mqtt.powernaut.io:8883
Sandbox	mqtts://mqtt.sandbox.powernaut.io:8883

Client Configuration

When configuring your MQTT client, please pay close attention to the following:

1. Unique Client ID (Mandatory): Every MQTT client connecting to our broker must provide a unique client ID. This identifier must be unique across all devices connecting to the broker. Using a non-unique client ID could lead to your device being disconnected by other devices. It is also preferred that each specific device uses the same client ID consistently across reconnections (e.g., deriving it from a unique device serial number).

2. Persistent Sessions (Recommended): To improve data continuity and reduce potential data loss during network interruptions, we recommend configuring your client for persistent sessions. This allows the broker to maintain session state for your client across temporary disconnections, aiding reliable message delivery (also see Quality of Service). To enable persistent sessions you generally have to disable a Clean Session/Start option in your MQTT client configuration.

Example configuration using the mqtt npm package:

import mqtt from "mqtt";

const client = mqtt.connect("mqtts://mqtt.powernaut.io:8883", {
  clientId: "unique-fixed-device-id-12345", // Use a unique for each device that you reuse for reconnections
  username: "<site-key>", // Your site's (edge-cloud) key
  password: "<site-secret>", // Your site's (edge-cloud) secret
  protocolVersion: 5, // Required, ensures MQTT v5 connection
  clean: false, // Enable persistent sessions
});

SSL

For security reasons, plain MQTT (without TLS) is not available.

Authentication

The MQTT broker supports two authentication methods, and the method you choose depends on your own setup:

1. Edge-Cloud Authentication

   • Use site specific credentials
   • Ideal for edge devices
   • Learn more about Edge-Cloud Authentication here.

2. Cloud-Cloud Authentication

   • Use your cloud credentials
   • Ideal for cloud integrations
   • Learn more about Cloud-Cloud Authentication here.

Security

Never hardcode cloud-cloud credentials on edge devices. These credentials provide full access to your account and should only be used in secure cloud environments. Use edge-cloud credentials for devices instead.

Credential Rotation

When rotating credentials, both old and new credentials remain valid for MQTT authentication until the rotation is either completed or cancelled. This allows for a seamless transition between credential sets.

Messages

Topics

There are two different topics to send messages to:

1. resource/{id}/data
2. site/{id}/data

Each topic serves its purpose: sending data for a resource and site, respectively. Use the identifier from the general REST APIs to identify the resource or site.

Content

Sites

Metering data should be provided in watts (W), i.e. the current consumption (positive) or injection (negative) of the site.

Resources

The data sent for resources is the same as for sites, except that you also need to send the current State of Charge for resources that have one.

State of Charge

The SoC (State of Charge) parameter is only required for certain resources. See Specification for more details.

Structure

All messages are send in JSON format, with the following structure:

{
  "value": -2500, // Example 2.5 kW production
  "soc": 8150, // Example a 10 kWh battery with 81.5% SoC
  "time": 1744858463 // Optional, UNIX timestamp no more than 1 minute old
}

Field	Type	Description
value	Integer	Meter reading in watts (W).
soc	Integer	(Optional) State of charge in watt-hours (Wh).
time	Integer	(Optional) UNIX timestamp representing the time of the actual measurement.

Time

The time parameter is optional but recommended, see Timing for more details.

Units

Make sure to send values in W or Wh (for SoC). Do not include decimals.

Multiple messages at once

You can send multiple messages at once (as an array), and the broker will process them in batches.

[
  {
    value: -3000, // Integer, meter reading, in W
    time: 1744858460, // (Optional) Integer, UNIX timestamp
  },
  {
    value: -3050, // Integer, meter reading, in W
    time: 1744858464, // (Optional) Integer, UNIX timestamp
  },
]

Timing

The time parameter is recommended and should be the time of actual measurements.

When not provided, the time the broker receives the message will be used.

Maximum delay

Timestamps older than 1 minute will not be processed. Your data will be discarded.

Quality of Service (QoS)

The Powernaut platform supports two QoS levels:

• Level 1: "At least once"
• Level 2: "Exactly once"

"At most once"

Level 0 ("At most once") is not supported.

Retained messages

The Powernaut platform does not support retained messages.

info

Any message marked as retained will be discarded.

Specification

The specification for this real-time data flow is also available in an AsyncApi specification.