Breaking changes for MQTT in Home Assistant 2023.8

Nardol · July 26, 2023, 10:55pm

Hello,

Some changes in MQTT will impact the way Nuki is integrated in Home Assistant.

To quote the beta release note:

The way MQTT entities are named and how device configuration can be shared between discovered entities has changed.

Sharing of device configuration

Discovered MQTT entities can share device configuration, meaning one entity can include the full device configuration and other entities can link to that device by only setting mandatory fields.

The mandatory fields were previously limited to at least one of connection and identifiers, but has now been extended to at least one of connection and identifiers as well as the name.

Naming of MQTT entities

Naming of MQTT entities has been changed to be aligned with the entity naming guidelines:

The has_entity_name entity will be set to True on all MQTT entities.

This means any MQTT entity which is part of a device will automatically have it’s friendly_name attribute prefixed with the device name.

Unnamed binary_sensor, button, event, number and sensor entities will now be named by their device class instead of being named “MQTT binary sensor” etc.

It’s now allowed to set an MQTT entity’s name to None to mark it as the main feature of a device.

(@jbouwh - #95159) (documentation)

As for everything, there is good and bad because if the current implementation is not changed names will become very long for people who will update Home Assistant, and if changed it will impact people who will not update.

An advantage of the future implementation is more information will be shared so a lot of information will only be useful to be specified once instead of being for each entity.

An article is also available in the Home Assistant developers blog:

Juergen · July 31, 2023, 9:44am

Do you have a suggestion what should be changed?

nanosonde · August 3, 2023, 7:21am

@Juergen

Hi Jürgen!
I have just observed that my Nukis (Pro 3.0, integration via MQTT) have warnings in Home Assistant 2023.8.0.

I get the following info:

"Einige MQTT-Entitäten haben einen Entitätsnamen, der mit dem Gerätenamen beginnt. Dies ist nicht zu erwarten. Um einen doppelten Namen zu vermeiden, wird als Work-Around das Präfix des Gerätenamens aus dem Entitätsnamen entfernt. Bitte informiere den Betreuer der Softwareanwendung, die die betroffenen Entitäten bereitstellt, um dieses Problem zu beheben. "

sensor.nebeneingang_battery
binary_sensor.garagentur_battery_critical
button.garagentur_lock_n_go_with_unlatch
button.nebeneingang_lock_n_go
binary_sensor.nebeneingang_battery_critical
sensor.garagentur_battery
binary_sensor.garagentur_battery_charging
button.nebeneingang_unlatch
binary_sensor.nebeneingang_battery_charging
button.nebeneingang_lock_n_go_with_unlatch
button.garagentur_unlatch
button.garagentur_lock_n_go
lock.nebeneingang
lock.garagentur

So it seems that it is enough to remove the device name prefix from the entity names.

nanosonde · August 3, 2023, 7:26am

Another screenshot which shows the text next to the warning icon.
grafik

So starting from 2024.2.0 the Nuki Home Assistant Discovery won’t work anymore.

spanzetta · August 3, 2023, 7:46am

Same issue here…

How to fix?

jakub.k · August 3, 2023, 7:51am

FYI, I integrated Nuki yesterday (so after upgrading HA to 2023.8) and it worked nicely. No repair warnings and it works great.

spanzetta · August 3, 2023, 7:57am

are you saying that we need to remove it… and add it again after the upgrade?
In my case, I had it installed before, did the upgrade and then the warning appears…

Nardol · August 3, 2023, 8:01am

Hi,

Sorry for the late reply.

The lock and the door sensor should be named ""
All related battery binary sensor and sensor need no name as these have correct class
Buttons only need their function in the name
In the device part, only the name and identifier must be defined for all other entities than the lock. Other information only have to be defined for the smart lock. Information will be shared with other entities because identifier will be the same but I am not sure I understood what has to be done for the device name so defining it for all entities should be OK.

I will try to be more precise latter if needed.

spanzetta · August 3, 2023, 8:06am

Thanks… but in order to me more precise … could you make an exmple (with screenshots) on how to configure the integration properly (after this change)?
I think this would be usefull for many people…

jakub.k · August 3, 2023, 8:28am

I integrated it for the first time. Did not remove & add it back. But yeah, if it stopped working for you, removing and adding it back it should help.

Nardol · August 3, 2023, 9:23am

Warnings and repair issues can safely be ignored, the modifications have to be done from Nuki.
These warning should not prevent to use your smart lock in Home Assistant.

I should have replied to @Juergen’s reply of this topic, sorry for this confusion.

aurelmarius · August 3, 2023, 10:29am

Nardol · August 3, 2023, 1:25pm

OK, so more precisely:

In the device section, the lock entity must have all information, other entities only need to have name and identifier set
The lock and the door sensor binary sensor, entities should have name set to ""
The charging state binary sensor, battery level sensor and smart lock battery critical sensor don’t really need a name because their state will be their respective name, maybe some people would not agree with me and would prefer to have a name set to the battery critical binary sensor to avoid having two entities named Door name battery even if the state allows to make the difference
The door sensor battery critical should keep its actual name except the smart lock name should be removed from the name, else we will have two binary sensors for battery critical. IIRC the name should be Door sensor battery critical.
Same for the fob battery critical sensor.

I hop I did not forget any entity.
The done side is for people using Home Assistant versions earlier than 2023.8 who won’t have the smart lock name in the entities.
They also will have default MQTT entity name for those which will have no name set at all and I don’t remember what happens for entities which have name set to null.

TheGamersCubeNL · August 9, 2023, 8:02pm

how did you set it up in home assistent/ the nuki app

NoeG · August 10, 2023, 4:50am

Thanks!! Would you be able to send some screenshots of where you did this?

Nardol · August 10, 2023, 7:30am

@TheGamersCubeNL @NoeG I have not changed my HA settings, in fact I have not this issue because I have not updated HA yet.
Information in my previous message are about the implementation Nuki should use to comply with new Home Assistant naming style in MQTT as @Juergen asked.

I still can give a YAML configuration to comply with new HA version if you want but you will have two devices so two of each entities except if you disable Home Assistant autodiscovery in the MQTT settings of the Nuki app.

ThomasKrammer · August 13, 2023, 6:08am

Morning,
so if I get it correctly, there are 2 options right now.
Option 1) disable mqtt auto discovery and add the sensors manually with proper naming in the configuration yaml
Option 2) wait for nuki devs to adopt the mqtt naming scheme in their products

Could you please provide your custom configuration for the entities?
BR

Nardol · August 18, 2023, 4:44pm

Sure I can provide a configuration which should work, but I really hop an update will be provided before Home Assistant will stop supporting old names.
@Juergen could you tel us if and eventually when an update will be provided?

mqtt:
  lock:
  - name: ""
    unique_id: "nuki_12345ABC_lock_yaml"
    command_topic: "nuki/12345ABC/lockAction"
    payload_lock: "2"
    payload_unlock: "1"
    payload_open: "3"
    state_topic: "nuki/12345ABC/state"
    state_locked: "1"
    state_locking: 4
    state_unlocked: "3"
    state_unlocking: 2
    state_jammed: 254
    value_template: '{% if value in ("5","6","7") %}3{% else %}{{value}}{% endif %}'
    availability_topic: "nuki/12345ABC/connected"
    payload_available: "true"
    payload_not_available: "false"
    device:
      identifiers: "12345ABC_yaml"
      name: "Lock name YAML"
      manufacturer: "Nuki home solutions GMBH"
      model: "Smartlock 3.0 pro"
      hw_version: "3.0p"
      sw_version: "3.5.9"

  binary_sensor:
  - name: ""
    device_class: "door"
    unique_id: "nuki_12345ABC_door_sensor_yaml"
    state_topic: "nuki/12345ABC/doorsensorState"
    payload_on: "3"
    payload_off: "2"
    availability_topic: "nuki/12345ABC/connected"
    payload_available: "true"
    payload_not_available: "false"
    device:
      identifiers: "12345ABC_yaml"
      name: "Lock name YAML"
  - unique_id: "nuki_12345ABC_battery_charging_yaml"
    device_class: "battery_charging"
    state_topic: "nuki/12345ABC/batteryCharging"
    payload_on: "true"
    payload_off: "false"
    availability_topic: "nuki/12345ABC/connected"
    payload_available: "true"
    payload_not_available: "false"
    device:
      identifiers: "12345ABC_yaml"
      name: "Lock name YAML"
  - unique_id: "nuki_12345ABC_lock_critical_yaml"
    device_class: "battery"
    state_topic: "nuki/12345ABC/batteryCritical"
    payload_on: "true"
    payload_off: "false"
    availability_topic: "nuki/12345ABC/connected"
    payload_available: "true"
    payload_not_available: "false"
    device:
      identifiers: "12345ABC_yaml"
      name: "Lock name YAML"
  - name: "Door sensor battery critical"
    device_class: "battery"
    unique_id: "nuki_12345ABC_door_critical_yaml"
    state_topic: "nuki/12345ABC/doorsensorBatteryCritical"
    payload_on: "true"
    payload_off: "false"
    availability_topic: "nuki/12345ABC/connected"
    payload_available: "true"
    payload_not_available: "false"
    device:
      identifiers: "12345ABC_yaml"
      name: "Lock name YAML"

  sensor:
  - unique_id: "nuki_12345ABC_battery_percentage_yaml"
    device_class: "battery"
    state_class: "measurement"
    unit_of_measurement: "%"
    state_topic: "nuki/12345ABC/batteryChargeState"
    availability_topic: "nuki/12345ABC/connected"
    payload_available: "true"
    payload_not_available: "false"
    device:
      identifiers: "12345ABC_yaml"
      name: "Lock name YAML"

Replace lock name by the desired name and 12345ABC by your smart lock ID.

Juergen · August 19, 2023, 2:08pm

No. In general we do no provide dates and contents of future updates. Besides that breaking changes are always problematic because they create lots of testing and communication efforts on our side in order to ensure that every update case is covered and no user is left unnoticed with a broken system.

chma73 · August 20, 2023, 7:57pm

Hi @Juergen you are aware that all Home Assistant users which use a Nuki with MQTT are affected from this issue?