Connection via MQTT

Data an be sent as a json object to the MQTT broker of Enelyzer.

MQTT publisher setting

The messages, as per schema described below, should be published on a specific MQTT topic.

We will provide the required credentials (username and password) as well as the url and topic (telemetry/<organization>/<default|custom>).

• telemetry: global telemetry topic

• organization: specific topic for an organization, this will be a pre-defined slug name generated by Enprove

• default|custom:this is either our default topic or a custom named topic for specific integration

Each publisher should connect via MQTTS, which is the secured variant of MQTT. For this to work, it is possible that the enelyzer.com SSL certificate need to be installed on the device itself.

If MQTTS would not be possible, the alternative would be non-secured MQTT but this is greatly discouraged.

Messages published on the broker must have at least QoS 1 and if possible retain enabled. This is to prevent any loss of information.

The credentials will be provided during the integration phase. These will include

• URL, customized for the organization

• username

• password

• topic

Data schema

This is the default MQTT schema we expect from third parties. The schema support multiple meter readings for the same organization, location and timestamp:

• timestamp: in Epoch milliseconds or seconds (we will automatically determine if it is milliseconds or seconds based on the length) UTC value to prevent any issues with timezone information, required, 64bit integer

• data A list of meters/sensors/tags of which Enelyzer wants to receive data from, required

• meter_name: a unique technical name identifying where the readings are coming from. This could be a physical meter or a virtual data source. This code should only contain upper or lowercase letters, numbers and underscores. Any diacritic will be stripped, required, String max 255 characters

• value: the numeric value of the measurement using dot-notation to depicts precision (314.12, 314,12 is not correct), required, IEEE double precision

Example message:

{
  "data": [
    {
      "timestamp": 1727265998013, # always in utc
      "meter_name": "meter_123",
      "value": 679106.23,
    }
  ]
}

Other than the message format above we do also allow the following format;

{
  "timestamp": 1723022670, # always in utc
  "data": [
    {
      "meter_name": "meter_123",
      "value": 679106.23,
    }
  ]
}

You do not need to provide a schema property to indicate this as a custom format, Enelyzer will automatically detect both formats.

The meter_name is considered to be a singular measured point. Some hardware devices (meters) will be able to produce multiple measurements, while others will only have a singular measurement they output.

examples;

• a hardware meter for electricity can output multiple measurements, for example volt, amps, even different values for each phase. It can also output measurements of the hardware device itself, such as battery, temperature, ...

• a hardware meter for water, can output a single measurement, for example flow.

Both devices are hardware meters, but output different measurements. These measurements are defined as `meter_name` in the JSON message

Custom data formats

In some cases it's not possible to comply with our default schema, in this case we allow for an optional schema property, in the root of the JSON object. This property is of type String and will be used to indicate towards Enelyzer how to interpret and parse the incoming data.

Here are some examples;

The schema below mkv which is Meter Key Value will have a timestamp, metername and key-value pairs of the measurements of that meter. Here the properties timestamp schema and meter_name are fixed. All the others will be dynamic, where the meter_name + key will be a separate measurement.

{
    "schema": "mkv",
    "timestamp": 1728633877715,
    "meter_name": "ab100sdfk1h",
    "power": 1637.859,
    "volt": 221.78,
    "battery": 33.12
}

The schema below will output the following measurement points;

• ab100sdfk1h_power

• ab100sdfk1h_volt

• ab100sdfk1h_battery

A full list of all the supported formats can be found here.