Enhance Readme with Device Registry Best Practices

genestealer commented 5 months ago

UPDATE

I was wrong on one point. "Some MQTT entities have an entity name equal to the device name. This is not expected. The entity name is set to null as a work-a-round to avoid a duplicate name." "This stops working in version 2024.2.0. Please address before upgrading."

I have updated the examples to reflect the same naming as we have in the MQTT discovery, I have avoided using null.

Description

I'd like to propose a modification to the readme to better align with Home Assistant's Device Registry behavior. The current example might lead to unexpected results due to inconsistencies in device grouping.

Issue

The readme example attempts to group multiple entities under a single device. However, each device in Home Assistant should ideally represent a distinct physical device, with its own unique set of attributes (name, model, etc.).
Grouping entities under a single device can result in Home Assistant adopting the attributes of the first entity for all subsequent entities, as highlighted in the examples below.

Suggestion

Adjust the readme example to demonstrate device configuration that adheres to best practices, ensuring each device has its own unique attributes.
Provide clear guidance on how to:
- Configure devices with multiple entities (e.g., a light switch with multiple buttons).
- Employ the identifiers property for proper device linking.
- Use the name property appropriately to ensure device visibility in the Device Registry.

Issue Example

See the example below for that happens if different entities are attempted to be "grouped" under one device. Results in the "issue", where the first entities device settings are taken as ther master version for all following entities

mqtt:
  light:
    - name: "Lounge Light Switch"
      unique_id: MIHO008_light1
      command_topic: energenie/ook/87/1/command
      optimistic: true
      state_topic: energenie/ook/87/1/state
      availability_topic: energenie/availability/state
      device:
        name: "Energenie OOK"
        identifiers: "ook"
        model: "2-Gang Light Switch (MIHO009)"
        manufacturer: "Energenie"
        via_device: "mqtt-ener314rt"

  switch:
    - name: "Coffee Maker"
      unique_id: ENER002_socket
      command_topic: energenie/ook/89/1/command
      optimistic: true
      state_topic: energenie/ook/89/1/state
      availability_topic: energenie/availability/state
      device:
        name: "Energenie OOK"
        identifiers: "ook"
        model: "Smart Plug (MIHO002)"
        manufacturer: "Energenie"
        via_device: "mqtt-ener314rt"

    - name: "Subwoofer"
      unique_id: ENER010_socket_2
      command_topic: energenie/ook/564/2/command
      optimistic: true
      state_topic: energenie/ook/564/2/state
      availability_topic: energenie/availability/state
      device:
        name: "Energenie OOK"
        identifiers: "ook-4gang"
        model: "4-Gang (ENER010)"
        manufacturer: "Energenie"
        via_device: "mqtt-ener314rt"

Suggested Fix

[!IMPORTANT]
name is repeated. Omitting the first name / setting it to null will mean the device will not show in the device registry (xxx/devices/dashboard). Omitting the second name will result in the device being listed in the device registry with the IP address of the MQTT broker as a prefix.

For single devices, e.g. A light with only On/Off:

[!NOTE]
The two name's do not have to match. E.G. You could have the first name set to temperature and the second name set to Radiator

mqtt:
  light:
    - name: "Light"
      unique_id: MIHO009_light_hallway_up
      command_topic: energenie/ook/87/1/command
      optimistic: true
      state_topic: energenie/ook/87/1/state
      availability_topic: energenie/availability/state
      device:
        name: "Upstairs Hallway"
        identifiers: "miho009_light_hallway_up"
        model: "2-Gang Light Switch (MIHO009) [87/1]"
        manufacturer: "Energenie"
        via_device: "mqtt-ener314rt"
        suggested_area: "Hallway"

Example of device with multiple entities:

[!TIP]
On the second entity, only the identifier is required in the device registry, as Home Assistant will link the two entities together into one device.

mqtt:
  light:
    - name: "Light"
      unique_id: MIHO009_light_hallway_up
      command_topic: energenie/ook/87/1/command
      optimistic: true
      state_topic: energenie/ook/87/1/state
      availability_topic: energenie/availability/state
      device:
        name: "Hallway"
        identifiers: "miho009_light_hallway"
        model: "2-Gang Light Switch (MIHO009) [87/1]"
        manufacturer: "Energenie"
        via_device: "mqtt-ener314rt"
        suggested_area: "Hallway"

    - name: "Light"
      unique_id: MIHO009_light_hallway_down
      command_topic: energenie/ook/87/2/command
      optimistic: true
      state_topic: energenie/ook/87/2/state
      availability_topic: energenie/availability/state
      device:
        identifiers: "miho009_light_hallway"

Examples

mqtt:
  light:
    - name: "Light"
      unique_id: MIHO008_light_bedroom
      command_topic: energenie/ook/600/1/command
      optimistic: true
      state_topic: energenie/ook/600/1/state
      availability_topic: energenie/availability/state
      device:
        name: "Bedroom Ceiling"
        identifiers: "miho008_light_bedroom"
        model: "Light Switch (MIHO008) [600/1]"
        manufacturer: "Energenie"
        via_device: "mqtt-ener314rt"
        suggested_area: "Bedroom"

    - name: "Light"
      unique_id: MIHO010_Dimmer1
      command_topic: energenie/ook/669/dimmer/command
      optimistic: false
      state_topic: energenie/ook/669/dimmer/state
      state_value_template: "{{ 'OFF' if value == 'OFF' else 'ON' }}"
      brightness_state_topic: energenie/ook/669/dimmer/state
      brightness_command_topic: energenie/ook/669/dimmer/command
      brightness_scale: 10
      payload_on: 'ON'
      payload_off: 'OFF'
      on_command_type: "brightness"
      availability_topic: energenie/availability/state
      device:
        name: "Kitchen Dimmer"
        identifiers: "MIHO010_Dimmer1"
        model: "Dimmer Switch (MIHO010) [669]"
        manufacturer: "energenie"
        via_device: "mqtt-ener314rt"

  switch:
    - name: "Switch"
      unique_id: MIHO002_socket1
      command_topic: energenie/ook/697441/2/command
      optimistic: true
      state_topic: energenie/ook/697441/2/state
      availability_topic: energenie/availability/state
      device:
        name: "TV Speakers"
        identifiers: "miho002_socket1"
        model: "Smart Plug (MIHO002) [697441/2] (Button 2)"
        manufacturer: "Energenie"
        via_device: "mqtt-ener314rt"

    - name: "Switch"
      unique_id: MIHO002_socket2
      command_topic: energenie/ook/697441/3/command
      optimistic: true
      state_topic: energenie/ook/697441/3/state
      availability_topic: energenie/availability/state
      device:
        name: "Laptop Power"
        identifiers: "miho002_socket2"
        model: "Smart Plug (MIHO002) [697441/3] (Button 3)"
        manufacturer: "Energenie"
        via_device: "mqtt-ener314rt"

    - name: "Switch"
      unique_id: ENER010_socket_2
      command_topic: energenie/ook/564/2/command
      optimistic: true
      state_topic: energenie/ook/564/2/state
      availability_topic: energenie/availability/state
      device:
        name: "Subwoofer"
        identifiers: "ener010_socket_2"
        model: "4-Gang (ENER010) [564/2]"
        manufacturer: "Energenie"
        via_device: "mqtt-ener314rt"

Achronite commented 5 months ago

How about this, the devices are split by OOK zone code?

This would mean that if you have a 4-way gang or double socket/switch they would share the same device entry, and this should only be defined once. So something like:

  - unique_id: subwoofer
    name: "Subwoofer"
    command_topic: energenie/ook/8887/1/command
    optimistic: false
    state_topic: energenie/ook/8887/1/state
    availability_topic: energenie/availability/state
    device:
      name: "energenie 4 gang"
      identifiers: ["ook-8887"]
      model: "4 Way Extension Lead [8887]"
      manufacturer: "energenie"
      via_device: "mqtt-ener314rt"
  - unique_id: fountain
    name: "Fountain"
    command_topic: energenie/ook/8887/4/command
    optimistic: false
    state_topic: energenie/ook/8887/4/state
    availability_topic: energenie/availability/state
    device:
      identifiers: ["ook-8887"]

Similarly you could group devices together if you use the same zone; this could possibly allow for switch 0 (all in zone) switching too; providing I can come up with a good way to dealing with the multiple states...

genestealer commented 5 months ago

@Achronite I personally wish to keep the "appliance" which I'm controlling abstracted from the thing which is used to switch it on and off. E.G. Fountain and Coffee maker may share the same 4-gang, but I have no reason to groups them together in the device registry.

I'm not a fan of zone 0 switching, as home assistant will not see it as each device being commanded, rather zone 0 would be just another device in the map. Rather, if you want to perform the equivalent to command all devices of a zone, create a helper in home assistant which groups all the devices together. E.G. If you want to switch all things connected to a 4-gang, make a helper switch in home assistant and add the devices which are connected to the 4-gang to it.

Achronite commented 5 months ago

@genestealer FYI - I've decided that the suggestion for the README to make the primary entity name=null, should be implemented for the non-heating devices via MQTT Discovery:

I don't know what to set the primary entity to for the thermostat / eTRV... I'm thinking of Climate_Control - Do you have any preference?

I'll release it soon

Achronite commented 5 months ago

@genestealer Code released to develop.

This table is missing some primary entities, let me know if you have any suggestions:

Device	Description	Primary Entity name now set to null
MIHO004	MiHome Smart Monitor Plug (Pink)
MIHO005	MiHome Smart Plug+ (Purple)	switch
MIHO006	MiHome House Monitor
MIHO013	MiHome Radiator Valve
MIHO032	MiHome Motion sensor	motion
MIHO033	MiHome Open Sensor	contact
MIHO069	MiHome Heating Thermostat

genestealer commented 5 months ago

@Achronite I'm currently out today but I will have a look when I get home later tonight 😁

Achronite commented 5 months ago

Updated table:	Device	Description
MIHO004	MiHome Smart Monitor Plug (Pink)	real power
MIHO005	MiHome Smart Plug+ (Purple)	switch
MIHO006	MiHome House Monitor	apparent power
MIHO013	MiHome Radiator Valve	climate control
MIHO032	MiHome Motion sensor	motion
MIHO033	MiHome Open Sensor	contact
MIHO069	MiHome Heating Thermostat	climate control

I'm just about to add a change that these 'main' entities will also be the only ones that contain the details about the parent device in the MQTT discovery messages; the others will just have their ids set.

genestealer commented 5 months ago

@Achronite Sorry got home late last night. Yes those all look great.

Achronite commented 5 months ago

develop code has been updated.

genestealer commented 5 months ago

@Achronite Will pull it now

Achronite / mqtt-energenie-ener314rt