Home Assistant MQTT auto-discovery implementation requirements


Following to @Juergen asked for, this topic is some requirements about the MQTT autodiscovery requirements for Home Assistant.

Firstly, the documentation: MQTT - Home Assistant

By reading MQTT API specifications V1.3, in the final stage MQTT wil be configured in the app with Wi-Fi settings.
To make Nuki auto-discovered working for all types of configuration, another field should be added to set the Home Assistant topic because it can be changed in MQTT settings.
Durring the beta it look like only Home Assistant default settings could work, with the topic prefix homeassistant.

Basically, a binary sensor for the door sensor state and of course the lock should be discovered, locks are supported.
An example of discovery topic for the lock: homeassistant/lock/lock_<lock_id>/config
Payload should include a command topic, a state topic and the lock name, for the door sensor with the suffix Door sensor for example.
All properties are here for lock and here for binary sensor.
Lock, unlock and open could be implemented.

The native integration also manage opener but because I don’t own one, it would be better if other users talk about it.

A binary sensor set to on when battery is critical would also be useful.
Because [buttons)(MQTT Button - Home Assistant) are also compatible with MQTT in Home Assistant, a button for lock’n’go would be useful.

All sensors being attached to an MQTT device would simplify the placement to a room.

All these points might be just a beginning but I hop it could help about what could be expected for a native Home Assistant support.

My SL3P is still not mounted instead of my V2 but the moment it will be I will make some experiment to be able to post a configuration which could give an idea of the requirements.

I hop other people will complete this topic, for example @alexdelprete. And I hop I am not totally out of what you expected @Juergen :slight_smile:


For the opener IIRC the native integration use events which could be also done with MQTT:

Patrick, sorry but I just noticed this topic, I missed the notification.

I’d be glad to help, but I think your post contains almost everything @Juergen needs.

@Juergen: if there’s anything specific you need, feel free to ask, I hope I can help and if I’m missing some info, I will chase it for you.

Sorry again for the very late reply.

1 Like

If needed to better understand autodiscovery, here’s the source of the Nuki Hub project (an alternative ESP32-based bridge for Nuki) that integrates MQTT and HA autodiscovery. Here’s the source that implements the autodiscovery: nuki_hub/NetworkLock.cpp at master · technyon/nuki_hub (github.com)

1 Like

I guess the main question is whether there is only one way of doing Auto-Discovery or different ones?

If you look at how the HomeBridge Plugins (Link 1, Link 2) expose the Nuki functionality to HomeKit, there are a lot of different options the user can choose. It also depends from whether there is a knob or handle on the outside of the door. There might be such different options for HA as well. If we integrate it in the firmware, we won’t integrate a plethora of different options, but the one that is most popular. → Which one is it?

I don’t know HomeBridge nor HomeKit, I was referring to Home Assistant. And there’s only one way of doing MQTT auto-discovery.

Auto-discovery has to do with devices integration, not how devices are configured, that would be represented by the mqtt topics/states.

Do you mean we need to choose between Home Assistant Home Bridge etc.? Only one?

Both can exist, you can publish the state of the Lock and they can be used by any other system with “manual” configuration. But if you publish the Home Assistant in topic for Auto-Discovery, this manual configuration will be done automatically into Home Assistant.

Don’t need to choose. I have used some integration done by myself in both HomeBridge and Home Assistant in parallel without issue.

I know how HA works, but thanks anyway for the explanation. :slight_smile:

It’s not me saying they can’t coexist, Juergen asked to choose, if I interpreted wrongly it’s better for him to better explain what he meant. Probably he’s referring only to auto-discovery, he didn’t say you can’t configure other platforms manually. This thread is specific to HA auto-discovery.

1 Like

My question was whether there is only one way to represent a Nuki Smart Lock in Home Assistant Auto-Discovery or if there are different ways to do it ? E.g. because some people prefer it one way and others in another way. Or because of different Smart Lock configurations requiring different Auto-Discovery configurations.

Like I wrote above, there’s only one way, documented in the OP. Basically the device integrates in HA by describing its entities in MQTT and the device will automatically appear in HA. That’s how Nuki Hub is working right now, that’s why I linked its source, to give you an idea of how it works. I replaced my bridge with a small ESP32 device, and I didn’t have to do anything in HA: I had the Nuki Lock immediately with all the entities and associated services.

it’s not a user-preference, a lock device has a minimum (and common among all locks) subset of entities, the device components are not chosen by the user, it’s a “physical” representation mapped to logical entities.

Sorry for my misunderstanding, I thought you were talking about the different automation platforms.

The only thing which can change is the auto-discovery topic prefix which can be set by user.
By default it is homeassistant so it would mean a field in the app, except that @alexdelprete told everything :slight_smile:

Correct: the default autodiscovery topic is homeassistant, so in the app, when user has to fill in the MQTT server hostname, user/pw, etc. an option to enable/disable HA Autodiscovery and when enabled the app asks for the topic, presenting the default one that the user can adapt to his system.

Here’s the MQTT config page of Nuki Hub, as an example:

These are the entities created in MQTT for autodiscovery for my SL Pro + Door Sensor. I don’t have the opener, so I can’t show you the entities for that.

We currently do plan to integrate auto-discovery but we do not plan to make the auto-discovery topic changeable. Is it common to change it?

Somehow related, but a bit off topic is the problem that we can not offer secure MQTT because of memory restrictions that we run into with the SSL connection. If the memory restrictions are resolved in a future product, we would still use it without certificate pinning. e.g. no uploading of a custom certificate is supported.

1 Like

I would really like to have the option to set the lock’s MQTT connection to “read-only” / sensors-only so that my “potentially insecure” SmartHome has the ability to read the status of the lock and react on it, but does not have the ability to control the lock - i.e. cannot open the door (in theory, the lock should only have to ignore the command topic if the connection is set to sensors-only).
If it is not possible to secure the MQTT connection, then this option would be even more important to me.

1 Like

It’s a user option when you configure the MQTT integration, so can’t say how many people change it, I didn’t personally. If you don’t implement it as a configurable option, at least specify the pre-requirement in the documentation and obviously in the code if you don’t find that specific topic throw a specific error, otherwise I expect a lot of tickets will be created. :slight_smile:

Users who have a custom discovery topic could implement some kind of automation that replicates the default topic to their custom one. Not nice, but it should do the job.

The device provides status and interface to its services to the automation platform. Secure MQTT has nothing to do with what you are asking, if you don’t want your automation platform to do any action on the lock, you can configure it not to do it (disable services, etc.), it’s not a device configuration but an automation configuration.

Furthermore, the Nuki Lock and the MQTT server are in the same local network typically for this use-case, so I don’t even think securing that channel is actually required, also because if you have user/pw to access MQTT, the secure channel doesn’t guarantee you any improved security. Secure MQTT is a must if you need to send data to an external broker and you don’t want to transmit data unencrypted. This is not the use-case here.

Here I have expressed myself misleadingly: I am not (only) concerned that my SmartHome does not have the ability to control the lock, but that no one in the network has the ability to do so. You should always consider your own network as compromised. And if someone has gained access to my Home Assistant server, then he necessarily also has access to the MQTT server. And then a very simple command is enough and the door is open. An unencrypted connection increases the risk in that a potential attacker can see which devices are communicating when logging network traffic - but I don’t really have to care about that, if the lock isn’t controllable via MQTT.

No one would enable complete read and write access to a firewall just to read out the status of a connection, for example. That would be extremely negligent - so why do it with the lock of an entrance door?

If this simple option does not exist, then it means that the MQTT connection cannot be used in the enterprise environment for security reasons - which would be a great pity, because I would have many practical uses for it for my employer. But even at home, I would much rather not have to grant unnecessary permissions on the device.

This is exactly what I have already requested. To be able to integrate Lock in HomeAssistant, to see the state changes, to be able to trigger actions based on state changes, like Ring in Opener, etc …
BUT have an option to NOT allow to perform unlock action! As I only trust the Nuki application to open the locks.

1 Like

If you consider your home network ALWAYS compromised, it means you shouldn’t use your home network in the first place, let alone an automation platform. Your home door can be opened in traditional ways, so you always consider your door ALWAYS compromised too? What about the keypad accessories Nuki sells? Those are compromised too? :slight_smile:

That is absolutely not correct, it depends on how you setup security of your network, your servers, your infrastructure in general, and access to the MQTT server. But even without MQTT, if someone has full access to your network, it can access Nuki via all the other interfaces (REST, Bluetooth, etc.). How are you using Nuki now in HA, with the nuki_ng component and the bridge? If not, are you simply using the mobile app? And don’t you consider your mobile phone TOTALLY compromised too? What about the cloud access, you trust opening the lock from the cloud?

In any case, what you ask (even if totally wrong conceptually) cannot be done, read HA documentation on MQTT locks (I underlined the relevant statement):

What does a firewall have to do with a lock? What a confusion. We’re talking about integration of a lock in a home automation platform, and there are pre-requirements and constraints in order to do so.

Another conceptual thing: Nuki will access MQTT but it won’t send COMMANDS. HA will send commands, and you can configure a secure MQTT connection between HA and MQTT, so the commands to open the lock through MQTT will go through a secure connection if you configure it properly. Furthermore, the secure connection between the lock and the broker only encrypts data flowing locally, but if you have user/pw to the broker, it doesn’t improve security. MQTT secure is necessary when sending sensitive data to a public broker, a LAN broker is not the proper use-case.

So concentrate on securing your network, your HA server, before thinking about the end device.