How does Home Assistant Discovery work? JSON format, sensors, device classes, units

.
Here I will show the inner workings of MQTT-based HASS Discovery, a way for Home Assistant to automatically detect and configure devices. HASS Discovery only requires our device to be connected to the MQTT broker in HA. After that, our device can already be detected. In order for the discovery to take place, our device needs to publish a properly formatted text in JSON format to a specific subject from Discovery. This JSON contains information describing the entity, i.e. its type, name, icon, entity and the associated MQTT topics, among others, the topic for reading the value (listening) and the topic for setting the new value (from the HA).

These types of mechanisms are best presented in practice, so I suggest starting with practice. Let's try firing up some Discovery and take a look at what is being sent. Fortunately, there is a ready-made tool in Home Assistant to listen in on MQTT communications. It comes with Mosquitto broker integrations:
.
Then we click Configure:
.
This brings us to the tool that allows us to publish packages and listen for publications.
Now it's time to listen to something.
Just a note - of course, I'm assuming that the user knows the basics of HA, MQTT, or JSON there.... The inner workings of Discovery are already a bit advanced, but also a worthy topic.
It's also worth looking at the HA documentation if you have questions.
So, Home Assistant Discovery by default is based on the subject homeassistant , we append a multi-level wildcard behind it, i.e. #, so that it listens to all matching subjects:
.
And then we click Start Listening:
.
Now it's time to do some Discovery - e.g. from within OpenBeken:
.
For the example, I used a simulated OBK device with two channels (relays).
Let's see what such a thing "caught" with MQTT:
.
Here we have a separate publish for each separate entity.
Let's start with the IP address. Topic (the so-called "mqtt topic"):
.
Content (so-called "mqtt payload"):
.
Here we have, in sequence:
- "dev" - section describing the device, its ID, name, software version (sw), manufacturer (mf), model (mdl), cu (panel URL)
- "name" - entity name, here "IP"
- "~" - abbreviation for the MQTT topic path, "WT00000000". This allows you to write ~/ip instead of the full "WT00000000/ip"
- "avty_t" - the topic for the availability status, "~/connected", i.e. "WT00000000/connected". On this topic, the device reports its presence.
- "uniq_id" - unique identifier of the entity in the HA, "WinTest_00000000_ip"
- "qos" - Quality of Service level for MQTT, here "1" (guaranteed to be delivered at least once)
- "stat_t" - the topic on which the entity value is published, "~/ip", i.e. "WT00000000/ip". Home Assistant here only listens for changes on this topic.
- "entity_category" - entity category, "diagnostic", i.e. HA treats this as diagnostic information
- "icon" - an icon in HA, "mdi:ip-network", which stands for the network icon from Material Design Icons (MDI)
It is worth noting that abbreviations are used here, making the JSON shorter and easier for the microcontroller to generate and publish.
Similarly, we have separate entities for different device parameters, e.g. for the SSID:
.
Content:
.
Here only there is a different "state_topic" ("stat_t") and a different icon.
Similarly for uptime:

Content:
.
Here the unit of measurement is entered - "unit_of_meas", in this example it is seconds. In addition, the entity class, "duration", i.e. the period of time, and the value type "total_increasing" are specified, meaning that the value will increase continuously.

Similarly, the temperature of the device (from Beken's internal thermometer) is also specified:
.
Content:
.
Here, however, the unit is changed - °C - and the type of measurement is changed, here it is just that, a measurement, or 'measurement'.
In a similar way, this whole section is created:
.
Forgive the deficiencies in the screenshot, I was testing on the Simulator.

It's now time to see something that supports both writing and reading. Relay. Its state can Home Assistant both set and read.
.
Content:
.
We have some new fields here:
- "pl_on", or "payload_on", a value that sets the relay to on
- "pl_off", as above, analogous to off
- "stat_t" - "state_topic", the relay's state topic, this is where HA listens for changes
- "cmd_t" - "command_topic", command topic, this is where the Home Assistant sends a new state when the user wants to change the state of the relay

Now a curiosity. This is what relays look like, but what if we turn on light mode in the OBK? There is a flag for that:

.
Let's check. I have performed HASS Discovery again:
.
.
So Home Assistant has lights and relay mode separately.... although you could probably just as well change the icon - but here it's also about the entity type itself, those "lights" after the slash in the publish subject.

Now, it would be possible to go more deeply into the topic of lights, but I decided I'd leave that for now. This will be covered separately, as there are more topics out there.

In the meantime, I would like to show a few more options for sensors, sensors. In the OBK we have channels for this.
Let's set up:
.
Let's perform another Discovery.
.
.
Humidity - the unit of measurement is percentages. Simple.
Let's look further.
Movement.
.
.
Here only the class is set - it is the class that provides the corresponding icon.


Now a more interesting thing - a temperature type, but divisible by 10. This comes from the fact that TuyaMCU operates on integers and this type of value is used there. Topic:
.
.
This is where a new field appears - 'val_tpl'. This is short for "value_template", which means value template. It defines how the value ("value") is formatted before being displayed. You can conveniently test these templates in Developer Tools -> Templates, but about that another time:
.

What's left is the voltage - also from TuyaMCU, divided by 100:
.
.
There is rather nothing new here - the value template is similar to that for temperature, just a different multiplier.

That's enough for today.
Now you know more or less how it works that the Home Assistant is able to detect devices on its own. This way, they do not have to be manually added to configuration.yaml. Home Assistant Discovery relies on the device itself publishing information about its entities separately in JSON format under the subject subordinate to "homeassistant/". These JSONs describe their parameters as well as subjects, values, types, icons and entities, and even templates for processing the values on receipt. Home Assistant parses this JSON and then creates the entities and devices itself in MQTT devices. For example:
.
And you can already create automations from these:
.
In the next section, I will already try to look at a more specific use case, namely the handling of coloured LED lights, operating in both RGB colour and white temperature (CCT) modes.
Do you use Home Assistant Discovery, or perhaps you happen to add devices to configuration.yaml yourself? .
PS: For a complete list of available keys, options and icons, I refer you to the HA documentation, especially as these may change over time... .