Home Assistant Energy Dashboard: Device Class, Unit and State Class in the Discovery Payload
Contents
The sensor arrives. It shows a number, the number changes, the history draws a line. Then the energy dashboard is opened, the list of possible sources is short, and the sensor is not in it – with no error anywhere, because from the system’s point of view nothing went wrong.
What is missing is agreement between three fields of the discovery payload. Each one is optional, each one is accepted on its own, and only the combination decides whether an entity is a number on a graph or a quantity that can be added up.
Where the Payload Goes and Why It Stays There
Discovery is a message on a topic the broker keeps: homeassistant/<component>/<node>/<object>/config, published with the retain flag. Retained means the broker hands it to Home Assistant again after every restart, which is what makes an MQTT device survive a reboot without a device sending anything.
# create, retained
mosquitto_pub -h broker -r -t "homeassistant/sensor/zaehler01/energie/config" -m "$(cat sensor.json)"
# remove: an empty payload on the same topic, retained again
mosquitto_pub -h broker -r -t "homeassistant/sensor/zaehler01/energie/config" -m ""The second command is the one that is usually missing. Deleting the entity in the interface removes it until the next restart, at which point the broker replays the retained config and the device is back. An MQTT entity is only gone when the topic that created it is empty.
The Three Fields That Decide Everything
device_class declares what kind of quantity this is, and by doing so fixes the set of units that may accompany it. For energy that set is Wh, kWh and MWh. For power it is W and kW, and a power sensor is not a candidate for an energy source no matter what else the payload says – watts are a rate, and a dashboard that adds up rates would be wrong.
unit_of_measurement is compared literally. kWh passes; kwh and KWH do not, and the result of failing is not a rejected payload but an entity whose unit does not match its class and which therefore cannot be selected. This is the single most common cause, and it is invisible from every screen except the one where the entity refuses to appear.
state_class decides whether long-term statistics are recorded at all. Without it, the value is kept in the short-term history and nothing more; with the wrong one, the same. Only total and total_increasing produce the hourly sums that an energy dashboard reads.
total_increasing, total, measurement
total_increasing is for meters that only count up. A drop is interpreted as a meter reset – a replaced device, a firmware that starts at zero – and the new value is counted from there rather than as negative consumption. It needs no last_reset and it is the right choice for almost every energy meter.
total is for values that can also fall, such as a net balance, and it expects a last_reset timestamp to know when a cycle began. measurement is for everything that is a state rather than a sum: temperature, power, humidity. It is the default people reach for because it sounds neutral, and it is the reason a perfectly good meter reading produces a beautiful graph and never a single kilowatt hour.
One detail of total_increasing is worth knowing before it happens: a value that jitters downward is read as a reset if the drop is large enough, and the entire new reading is then booked as consumption in that hour. A meter that occasionally reports a stale, lower value therefore does not produce a small error but a spike the size of the whole meter reading.
Which Symptom Comes from Which Line
| Symptom | Cause in the payload |
|---|---|
| Entity exists, cannot be chosen as an energy source | state_class missing or set to measurement |
| Entity exists, unit shown but never summed | unit does not match device_class, e.g. kwh |
| Entity cannot be renamed or edited in the interface | unique_id missing – and without it, no energy source either |
| A single enormous spike in one hour | total_increasing on a meter that reported a lower value |
| Value frozen for days, consumption reads zero | no availability_topic and no expire_after |
| A deleted device returns after a restart | the retained config topic was never emptied |
Five of the six show up as something other than an error. That is the shape of the whole problem: a discovery payload is accepted or ignored field by field, and a field that is ignored leaves no trace beyond the capability it silently withheld.
The Sensor That Keeps Its Last Value Forever
An MQTT sensor with no availability handling has no concept of being offline. The last value that arrived stays on screen, and for a meter reading that is worse than a gap: the number looks plausible, the graph is flat, and the energy dashboard reports a household that consumed nothing since Tuesday.
availability_topic with a last will on the device side is the clean solution, and expire_after is the blunt one – a number of seconds after which the state becomes unavailable if nothing new has arrived. For a meter that publishes every ten seconds, three hundred is generous and still catches a dead device within five minutes.
Statistics Do Not Look Back
Long-term statistics are computed once an hour from the states that were recorded in that hour. A payload corrected on Friday does not produce statistics for Monday through Thursday, because there were none to compute from – the states existed, but nothing was told to sum them.
The hole can be closed by hand in the statistics editor under the developer tools, which allows individual sums to be adjusted, and that is worth doing for a meter whose readings matter. It is also the reason the three fields deserve a check on the day a device is added rather than at the end of the month: everything else in a discovery payload can be fixed later without losing anything.
Sources
Related articles
