Advanced: Payload format - plan-d-io/P1-dongle GitHub Wiki

The P1-dongle is mainly meant as a P1-telegram-to-mqtt forwarder. Each measurement value that is extracted from the meter telegram (see: digital meter configuration) is available through the HTTP API or sent to its respective MQTT topic (if enabled), by default as a JSON encoded payload. The type of encoding is selectable.

Payload format

0 - Value only

Non-JSON payload. Just the numeric value of each meter reading.

Example of the active power consumption measurement (which is sent to data/devices/utility_meter/active_power_consumption):

1.54

This type of payload is incompatible with the native Home Assistant integration.

1 - Basic JSON (value, unit)

Measurement values are sent as JSON encoded payload containing both the value of the measurement and the unit as extracted from the meter telegram.

{  
	"unit": "kW",  
	"value": 1.54
}

2 - Standard JSON (value, unit, timestamp)

Measurement values are sent as JSON encoded payload containing the value of the measurement, the unit and the timestamp of measurement as extracted from the meter telegram.

{  
	"unit": "kW",  
	"value": 1.54,  
	"timestamp": 1294569020
}

3 - COFY JSON (as above, including metadata)

Measurement values are sent as JSON encoded MQTT payloads. The MQTT topic payload format is in the Community Flexbility (COFY) format developed for the COFY-box, roughly equivalent to the EnergieID webhook API. The COFY payload format is meant to be entirely self-contained, meaning the type of measurement can be inferred entirely from the payload without having to know the MQTT topic where the payload was delivered to. This is useful in cases where the MQTT messages are forwarded over other channels, e.g. an HTTP API.

{  
	"entity": "utility_meter",  
	"metric": "GridElectricityPower",  
	"metricKind": "gauge",  
	"unit": "kW",  
	"friendly_name": "Utility meter total active power",  
	"value": 1.54,  
	"timestamp": 1294569020,  
	"sensorId": "utility_meter.total_active_power"  
}

A description of the JSON fields is shown below. Some fields are COFY-application specific and can be ignored. Some fields are optional and will not be present in all MQTT payloads. The important fields are marked in bold.

Field	Info	Optional?
entity	Type of the data source	N
metric	COFY-specific, see EID API documentation	Y
metricKind	COFY-specific, see EID API documentation	N
unit	Unit of the measurement	N
friendly_name	Human readable name of the measurement	Y
value	Measurement value	N
timestamp	Timestamp of the measurement	N
sensorId	COFY-specific	Y

Timestamps

Every P1 data telegram contains a timestamp of the internal meter clock of when the telegram was transmitted. By default, the P1-dongle uses this internal timestamp for the timestamp field in the MQTT payload.

In some cases however, the P1 data telegram contains timestamped measurement values. These are measurement values followed by a timestamp that can be different from the internal meter time. If the measurement is timestamped, the P1-dongle will use this timestamp for the timestamp field.

Measurement values are timestamped if they originate from other meters, e.g. the natural gas meter or water meter. In that case the digital meter acts only as a gateway. Because these external meters are battery powered, they only send new readings every now and then (e.g. the Fluvius natural gas meter updates every 15 minutes). The P1 data telegram contains the value last received by the digital meter, together with the timestamp it was received on.

Usage with manual Home Assistant MQTT sensors

If you do not wish to use the Home Assistant autodiscovery feature but in stead rely on manually configured MQTT sensors, you can extract the measurement value by using the "{{ value_json.value }}" template in your config file.

Example:

sensor:
  - platform: mqtt
    state_topic: "data/devices/utility_meter/active_power_consumption"
    unit_of_measurement: 'kW'
    name: "Utility meter total active power"
    value_template: "{{ value_json.value }}"