Skip to content

MQTT services

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

Subscribe to meter data over MQTT

This section is relevant for those who want to recieve processed metering data from Å Insite over MQTT.

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
}

Publish meter data over MQTT

This section is relevant if you have a system or hardware capable of sending data over MQTT, and want to send that data to Å Insite for processing and quality assurance. Get in touch with your Å Insite commercial contact or our helpdesk to get started.

Connecting to our broker

Broker connection information is the same as for data consumers; see the section above. Unlike data consumers, the credentials you recieve will not be valid in our Metering API, only the MQTT broker. The credentials are valid for 1 device / data source. A data source may send data for multiple meters, and each meter may send data for multiple registers.

NOTE: The format specified below (both for the topic and payload) is our suggested standard format. If this does not work with your device, reach out to us to resolve this issue.

Topic structure

Our standard topic consist of a total of 7 levels. Levels 1-4 are specific to a gateway device, and you will get it along with the username and password for the broker. It will look something like gateways/generic/<service_account_id>/<parser_id>.

The next two levels identify the meter utility type and a unique meter ID. The final level should be an integer describing the Å Insite register type ID. This results in a format like /<utility_type>/<meter_external_id>/<register_type_id>.

The utility type must be one of the following values:

Value Description
Electrical A meter measuring electrical energy consumption or production
Thermal A meter measuring thermal energy consumption, such as district heating or ground heat exchange
Water A meter measuring water or wastewater consumption
NaturalGas A meter measuring thermal energy consumption, such as district heating or ground heat exchange

The meter_external_id should be a descriptive string or an ID you recognize. We will generate a GUID to use as our meter ID, but the meter_external_id you supply will be used for the meter name.

The final level of the topic should simply be an integer describing the register type ID.

Some example topics are:

  • gateways/generic/42/6e6a4667-22a8-4e54-a5b8-7b75c158c525/Electrical/MAIN_SUPPLY/2
  • gateways/generic/52/c863d30b-7c02-4851-aeeb-c75319ed4340/Water/Toilets/10

Payload

The payload should be a simple numeric value, like 123.456. We will use the current timestamp as the meter reading timestamp.