Enersee MQTT Connector Documentation

Written By Kevin Vinck

Last updated 24 days ago

Overview

The Enersee MQTT Connector enables partners to stream energy data from their devices directly into Enersee’s platform.

It focuses on one core data flow:

  1. Time Series Data: Regularly transmitted energy usage data.

Meter and building information are not transmitted over MQTT. Instead, Enersee collects that information collaboratively with the partner at the start of the integration using a Master Data File (spreadsheet) that contains buildings, meters, and associated metadata such as location and unit type.

Connection Settings

ParameterValue

Broker URL

df4c3ed8.ala.eu-central-1.emqxsl.com

Broker Port

8883

TLS / Encryption

Enabled

QoS Level

1 or 2

Client ID

Their choice, must be unique (a long random string works)

Username

<partner name generally>
e.g. “acme”

Password

Provided by Enersee

Topic

<partner name>/<customer name>[/<meter identifier>]
e.g. “acme/contoso/building_1/main_gas”, or just “acme/contoso” if the meter identifier is in the payload. Used for authorization so prefix is critical.

Message format

Payload

The payload is customizable based on customer requirements with a couple of rules.

  • No nesting of parameters is supported.

  • Each message may contain only one measurement.

  • Field names must be static, but can be chosen.

  • The timestamp can be unix epoch in seconds, milliseconds, microseconds or nanoseconds, ISO timestamp, or a format accepted by the Python strptime function. It must contain the timezone offset if the time is not in UTC.

  • The measured value must be parse-able as a floating point value.

  • The external meter identifier must be available either in the payload, or in the topic name. It may not be a combination of both.

Examples

Ideal format with identifier in topic name and epoch timestamp in UTC

# topic: acme/contoso/building_1/main_gas_meter
{
	"time": 1598767200,
	"value": 300.6,
}

ISO timestamp with identifier in payload

# topic: acme/contoso
{
  "identifier": "building_1/main_gas_meter",
  "timestamp": "2020-08-30 08:00:00.000+02:00",
  "measurement": 283.5
}

Data Transmission Guidelines

  • Send Time Series Data every 15 or 60 minutes.

  • All payloads must be formatted as JSON.

  • Align each timestamp to the nearest 15-minute or hourly boundary (e.g., 12:00, 12:15, 12:30…). Values with offsets like 12:17 will be rejected.

  • Use UTC time.

  • Buffer at least 30 days of data at partner side to prevent loss during network outages.

  • Best practice: resend the previous 24 hours of buffered data at the end of each day for redundancy.

  • Publish with QoS 1 or QoS 2 for guaranteed delivery.

Security & Authentication

  • Authenticate with the MQTT broker using username & password.

  • Enable TLS encryption for all connections.

Conclusion

By following the structured topics, payload format, and best practices outlined in this guide, partners can seamlessly integrate their energy data with the Enersee platform.