{"id":12956,"date":"2026-09-10T07:35:00","date_gmt":"2026-09-10T05:35:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=12956"},"modified":"2026-10-24T06:15:04","modified_gmt":"2026-10-24T04:15:04","slug":"tutorial-publishing-an-mqtt-discovery-payload-that-reaches-the-energy-dashboard","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/en\/smart-home\/tutorials-en-smart-home\/tutorial-publishing-an-mqtt-discovery-payload-that-reaches-the-energy-dashboard\/","title":{"rendered":"Tutorial: Publishing an MQTT Discovery Payload That Reaches the Energy Dashboard"},"content":{"rendered":"
MQTT discovery describes a sensor to Home Assistant. A separate topic carries its readings. The Energy dashboard then uses suitable sensor data and statistics. These are three different stages: valid JSON alone does not guarantee a working entity or an energy graph.<\/p>\n
1. Define the measurement first<\/h2>\n
The example represents cumulative imported electricity in kWh. The counter normally increases but may restart from zero, so total_increasing<\/code> fits this example. A lifetime counter that never resets can use total<\/code> without last_reset<\/code>. A net counter that rises and falls needs different treatment; total_increasing<\/code> would misinterpret genuine decreases.<\/p>\n
Power in W describes the current rate, while energy in kWh describes an accumulated amount. Current Home Assistant versions also accept suitable power sensors in the dashboard\u2019s power fields: device_class: power<\/code> with state_class: measurement<\/code>. A W reading cannot simply be relabelled kWh.<\/p>\nFour checks from discovery to the Energy dashboard<\/figcaption><\/figure>\n
2. Publish a valid sensor configuration<\/h2>\n
Prerequisites are a reachable broker, a configured Home Assistant MQTT integration and enabled discovery with the expected prefix. This component-discovery example uses homeassistant\/sensor\/example_meter_import\/config<\/code>. Topic identifiers accept letters, digits, underscores and hyphens; they are not unrestricted prose.<\/p>\n
The following file, energy-discovery.json<\/code>, describes an invented meter. The stable unique ID should be unique within the installation. The display name can change independently.<\/p>\n
state_topic<\/code> is required for an MQTT sensor. Other fields depend on the intended behavior. A unique ID enables registry-based management and is needed for the device association shown here; it is not a universal Energy dashboard requirement. Device discovery using a single device<\/code> payload has additional mandatory fields and is a different format.<\/p>\n
3. Keep configuration available and readings fresh<\/h2>\n
The example retains the configuration at the broker. An alternative is for the publisher to resend discovery when Home Assistant announces its birth, normally online<\/code> on homeassistant\/status<\/code>. Fresh states must also follow discovery. Retain is therefore a useful delivery option, not a compulsory field or a guarantee of disk persistence across broker failures.<\/p>\n
The commands below require Mosquitto clients 2.1 or newer because they use -o<\/code>. mqtt-client.conf<\/code> contains the actual broker address, TLS settings and authentication options, one option per line. Restrictive file permissions protect its credentials; passwords are not placed in the command line. The default client configuration is an alternative on older versions. The file must not contain a retain option for state publications.<\/p>\n
The configuration command runs first. The entity and its state subscription must be ready before the two reading commands run; a successful publish does not prove Home Assistant has processed discovery. An existing retained value on the state topic must also be cleared during a migration. Omitting Retain from later messages does not erase that older stored value.<\/p>\n
The two sample readings differ by 0.125 kWh. This example must use an isolated test sensor; invented readings must not enter a real meter\u2019s history. The publisher should report regularly, comfortably within the configured 900-second expiry period.<\/p>\n
State messages deliberately omit -r<\/code>. With expire_after<\/code>, a retained old state could be replayed after a reload and appear fresh again. Device availability using birth\/will messages can additionally report connection loss. It does not prove that the physical measurement itself is current.<\/p>\n
4. Check each stage separately<\/h2>\n
\n
Discovery: subscribe to the exact configuration topic and inspect Home Assistant\u2019s MQTT errors. A syntactically valid JSON document can still violate the sensor schema.<\/li>\n
Reading: check example\/meter\/import_kwh<\/code> for a numeric payload with a decimal point and no unit suffix. A subscription to that branch does not include homeassistant\/...<\/code>.<\/li>\n
Statistics: confirm the energy class, kWh unit, appropriate total class and active Recorder. Statistics errors and unavailable readings need resolving before interpreting a graph.<\/li>\n
Dashboard: select the sensor in the imported-energy field. Short-term statistics are compiled every five minutes, long-term statistics hourly. The first reading establishes a baseline; it is not consumption since installation. A full graph is not guaranteed immediately after discovery.<\/li>\n<\/ul>\n
Unexpected decreases require investigating the counter and its class. A reset and a genuine negative flow are different events. Adding counters that reset at different moments can create artificial totals; separate dashboard sources avoid that particular summation problem.<\/p>\n
\n
Questions and answers<\/h2>\n
How is a discovered sensor removed?<\/h3>\n
An empty retained payload on this exact discovery topic removes its configuration. That does not mean historical statistics are erased. Cleanup should target only the intended topic and entity.<\/p>\n
Can one net counter provide import and export totals?<\/h3>\n
Not from cumulative net readings alone. Separate import and export registers preserve both flows; netting loses that information. Available registers depend on the meter. Integrating sufficiently frequent power samples is another approach, with accuracy depending on sampling and the numerical method.<\/p>\n
Which permissions are needed?<\/h3>\n
The example publisher needs write access to its configuration and state topics. Home Assistant needs matching subscriptions. Birth-triggered discovery and availability require their additional topics. This is a sensor example, not a complete ACL policy for actuators or an entire installation.<\/p>\n<\/div>\n
![\"Four](\"https:\/\/www.lukaswojcik.com\/blog\/wp-content\/uploads\/diagrams\/dia-12956-mqtt-energy-20261024-en.png\")