Skip to content

MQTT

The MQTT service enables you to receive real-time data updates via an MQTT subscription, eliminating the need to poll the REST API at regular intervals. Currently, the service supports the delivery of meter readings as soon as they become available.

Please note:

  • Only meter readings are sent over MQTT.
  • Any metadata related to these readings must still be fetched from the REST API.
  • Creation, modification and deletion of entities are not supported via the MQTT service.

Broker

Host: mqtt.ainsite.io

Port: 8883

TLS: Required

Username: Required, see authentication

Password: Required, see authentication

ClientId: No limitations, select a unique ID.

Quality of Service (QoS) Level: 1

Topics

Each customer is separated into individual base topics. This allows consumers to have a single subscription and receive data for all installations, meters and registers.

meters/outbound/[customer-id]/[subscription-id]/[meter-id]

MQTT subscriptions must be made to the same base topic the consumer has been granted access to. This means that subscriptions must include the customer-id, and cannot subscribe to root topic with wildcard #. Trying to connect to customer-ids you do not have access to will lead to being kicked from MQTT-session.

Missing data

Please contact support@ainsite.io if you are lacking data from installations or meters in your MQTT topic. This might be due to the configuration of the topic.

Quality of Service (QoS) and Session Persistence

To prevent data loss, please use QoS level 1 to ensure messages are delivered at least once. For reliable message tracking, we recommend to set Clean Session to false, retaining subscriptions and undelivered messages across sessions. Following this approach—Clean Session = false and QoS >= 1—ensures consistent data delivery even in unstable networks.

Duplicates

Because we use QoS level 1 our MQTT service may publish duplicate values, in particular for subscriptions with frequency under 60 seconds.

Payload format

Because of historical reasons there are currently two payload formats. This is in process of being updated.

Version 1 data payload is transmitted for register 2 (accumulated energy consumption) measurements.

{
    "smarteo_payload_schema_version": 1,
    "data_timestamp_utc": "2023-01-01T12:34:56.789Z",
    "system_timestamp_utc": "2023-01-01T12:30:00.000Z",
    "register_id": 2,
    "meter_reading": 123.456
}

Version 2 data payload is transmitted for all other register types.

{
    "smarteo_payload_schema_version": 2,
    "measurement_start_timestamp_utc": "2023-01-01T12:00:00.000Z",
    "measurement_end_timestamp_utc": "2023-01-01T12:01:00.000Z",
    "register_id": 12,
    "value": 123.456
}