Definition of a "device" in the device registry

incaseoftrouble · April 24, 2020, 12:31pm

Hey folks,

I’m crossposting from reddit, since the forums seem to be a more sensible place to ask this question. I’m unsure about what exactly constitutes a “device” in HA. Let me elaborate with an example.

I’m using homeassistant for some time now and I’m slowing adding my own appliances, in particular DIY ESP8266-based things. I’m connecting these devices via MQTT + autodiscovery. So far, all my (physical) devices were single-purpose, single-location, so no issue arose. Now, I’m adding a shutter controller which resides in the electrical cabinet (I’m not sure whether this is the correct word, I’m not a native) and switches several relays controlling shutters at various locations in my house.

Here comes the question: How do I map this scenario correctly into HAs device registry? I’m unsure about the definition of “device” (see Device Registry), since the controller (ESP) and the shutters are in distinct locations. I see three options sort of compatible with the documentation:

Each shutter motor (which is just a dumb device) is a separate device + a single entity
Each shutter is a different device + I add the ESP chip as via_device without any entity attached to it. (or rather 1.b)
The ESP is the device, the shutter motors only are entities.

The docs don’t seem to be too clear on this topic. In practice probably all of these options work, but I’m a bit obsessed with doing things the “right way”

EDIT: Made the title a bit clearer.

petro · April 24, 2020, 12:35pm

There is no ‘right way’. It’s how you want to use the items. Because these are all shutters, I would completely ignore the main controller and create a series of cover domain entities. 1 for each window. Now if they come into home assistant as various entities, you’d want to make template covers out of all the entities and ‘hide’ the other entities from the UI.

EDIT: I Just saw you mention MQTT. So this will be easier. Just create MQTT covers.

incaseoftrouble · April 24, 2020, 1:00pm

Thanks for your answer!

While I’m using MQTT, I think the problem is orthogonal to MQTT. My question is mainly about the abstract concept of a “device” as mentioned in the device registry, sorry for not being clear. For MQTT, this would be the (arguably optional) device section in the discovery message.

In particular, I think the phrasing of What is a device in the docs is not 100% clear (at least not to me).

However, I think that you’re essentially saying the correct thing, one device + one entity per shutter and nothing else.

petro · April 24, 2020, 1:08pm

I’m not sure why you care about a device. Home assistant is based on entities. Devices are a ‘new concept’ in home assistant and are largely meaningless unless you use the almond automation generator. All they are is a ‘group’ of entities that make up a device hardware. In your circumstances a devices is meaningless because it should be 1 to 1, entity to device. Now if your hardware has a temperature sensor attached to it, then you’d have a device that has a cover and a temperature sensor.

Or if you want to consider the whole system as a device, then you have 1 devices that has n covers. Either way, in MQTT land, it’s 100% meaningless because you’ll just be creating entities that do what you want. And you’d use those entities to do your automations.

Also for what it’s worth, you as a user cannot create your own devices. This is something created by the integrations themselves.

123 · April 24, 2020, 1:34pm

The concept of “device” is a recent addition. It is an aid to modeling a physical device (or even a service). For example, my laser printer is depicted as a device (manufacturer, model, etc) with several entities representing page-count, drum-life, etc.

You can look at it as a means of providing an inventory of your real-world hardware and a means of organizing (“grouping”) entities by their parent device. It also lets you created “device-oriented” automations (yet another recent enhancement).

I’m currently in the process of transitioning to a new Home Assistant server (now based on Home Assistant Supervised). I’m rethinking everything I have in my existing server’s configuration. I’ve decided to use MQTT Discovery instead of the existing YAML configuration because it offers the ability to define devices.

Here’s one example of what I mean. I have a few X10-based switches that, after 10 years of operation, still work perfectly so I’m not compelled to replace them. A completely separate computer communicates with these X10 switches via a device called a CM11A. That computer talks to Home Assistant via MQTT so each one of those X10 switches is modeled as an MQTT Switch in Home Assistant.

In my new server, I’ve modeled the CM11A as a device whose entities are the X10 switches. This is how they appear:

So now “X10 CM11A” appears as an entry in Configuration > Devices and, as seen in the screenshot above, reveals it is the “parent device” of three switches.

In order to achieve this, each switch entity’s MQTT Discovery payload must describe the CM11A device. Here’s an example; take note of the device portion:

        payload: >
          {
            "name": "Pool Pump",
            "state_topic": "pool/pump/powerstate",
            "command_topic": "command/pool/pump/powerstate",
            "payload_on": "1",
            "payload_off": "0",
            "state_on": "1",
            "state_off": "0",
            "unique_id": "x10_pool_pump_switch",
            "device": {
                "identifiers": ["x10"],
                "name": "X10 CM11A",
                "model": "CM11A",
                "manufacturer": "X10",
                "sw_version": "1.X"
            }
          }

Here’s a screenshot of the “device-oriented” means of creating an automation for the X10 CM11A device:

incaseoftrouble · April 24, 2020, 1:42pm

I care about the notion of device because (i) I am not sure whether I am misunderstanding something and want to make sure I am doing the right thing, and (ii) I think that the docs are lacking in that regard and I can use this discussion as a starting point to suggest an improvement in a github issue. As I said initially, all options work, I simply think that it is not well specified what is the “correct” way of doing it.

To clarify: I’m not the user, I’m the one writing the MQTT endpoint, so yes, in a way I can create devices, and I don’t want to create them in the wrong way. For example I don’t know what the connection, identifier etc. fields are for (I know what their contents should be, I don’t know what they are used for – I’m guessing its only more or less tagged text fields used for inventory management as of now). They make sense for the ESP but basically no sense at all for the shutter motors (they virtually indistinguishable up to location).

I did suspect that devices are mostly new. However, I am not a poweruser, my HA instance has maybe a dozen entitites, so I might be missing an important concept, which might get back to me once I get to hundreds of entities. On the other hand, if devices are completely meaningless in MQTT, then I don’t see why they should be there at all / mentioned so explicitly in the docs of every MQTT platform. For what its worth, other, mature MQTT-based projects do publish device information (zigbee2mqtt for example).

Thank you all for your input. As far as I understand it, all three of my options are viable and its mostly up to me to decide how I want to organize my devices. Probably I will completely remove the ESP controllers from HA and treat them as simple brokers, similar to how zigbee2mqtt does not introduce its bridge as a device. Then each physical box acting or sensing is one device. This would be different from your (123) approach.

123 · April 24, 2020, 1:58pm

Me neither (unfortunately, it’s not documented). Minimally, you need one unique item in identifier’s list. Based on my experience, Home Assistant computes the connection parameter (if it isn’t supplied).

The main advantage of modeling a device is, I believe, the ability to create device-oriented automations (see screenshot above). However, I feel this is slanted towards new users because it simplifies the process of creating an automation. If you have the programming skills to publish MQTT Discovery topics, you may be “over-qualified” to ever use device-oriented automations (and may prefer to compose automations in YAML).

In my case, I don’t foresee myself using “device-oriented” automations. I just want the organizational benefits of defining a device and its related entities.

petro · April 24, 2020, 2:07pm

Everything you’re asking is going to be MQTT specific and is not related to all devices. The MQTT integration handles how it makes devices. Your only option to find the ‘connection’ is to read the code that MQTT uses to create said devices or consult the dev(s) who did it.

Just glancing at the discovery code, it appears as if the information is stored in the payload, but I just glanced on the surface. I’m most likely wrong on that.

incaseoftrouble · April 24, 2020, 2:14pm

@123: Probably. I’m not using HA for automations at all. HA essentially is a unified proxy to all devices, automation happens purely in node-red. But yes, if I’d create automations in HA I’d definitely use YAML

@petro: The MQTT / autodiscovery integration creates devices as you tell it to. Basically you can declare all these device fields however you like in the discovery message (they are all optional string fields).

So jeah, I guess devices essentially are folders for entities with some additional metadata for convenience.

Marked the topic as solved. I only can mark one of your answers as solution though.

petro · April 24, 2020, 2:19pm

You can give it to @123, I don’t really care about them tbh.

Yeah, MQTT is completely unique on the Device side of things because topics are 100% not related other than the topic name itself. They had to come up with a tailored solution for MQTT.

Unlike Zwave where it’s clear how a device is made and where it comes from.

incaseoftrouble · April 24, 2020, 2:24pm

Agree. I think the main “issue” with MQTT is that mqtt devices can be anything, including custom made stuff without any structure. When I buy an applicance, it, basically by definition, constitutes a single device. If I solder together an ESP doing three completely different things its not so clear anymore. Which is where my question essentially stems from.

petro · April 24, 2020, 2:26pm

Yeah, you’re only running into the question because of MQTT. It’s such a great system too but this is one of the few drawbacks.

123 · April 24, 2020, 2:42pm

I had provided an example where physical X10 switches are represented as MQTT Switches. The device concept allows me to preserve their “heritage” and identify their “parent device”.

This can also apply to other integrations that translate from zigbee and zwave to MQTT (zigbee2MQTT, zwave2MQTT). However, that’s not the only way to preserve an entity’s “hardware characteristics”. You can also store that metadata in the entity’s attributes.

Personally, I would not use the device concept to create a one-to-one relationship with an entity. In other words, if I have a 6 switches, I wouldn’t created 6 devices, one for each switch. I’d just put the “hardware metadata” in each switch’s attributes.

On the other hand, if I had a gadget that reports temperature, humidity, pressure, vibration, and light level then I would be more inclined to create a device to represent it and its 5 related entities.