Examples of MQTT APIs for competing products

Post examples of other consumer products that use MQTT here and explain why they could act as role model for the Nuki MQTT API.

Not competing, but I’d like to show an example what the LoxBerry Nuki Plugin currently does.

The Nuki plugin currently manages the callback to post to our callback handler. This callback handler directly forwards the callback json dataset to the mqtt server.
Furthermore, it enriches the data by sentAtTimeISO and sentAtTimeLox (that’s Epoch with another time base).
Also, sentBy/sentByName fields are added, as in the plugin the callback can be a real callback from the bridge, or a healthcheck call from a cronjob or test button in the webif.
Topic hierarchy is

In the screenshot, the topic slashes (/) are converted to underscores (_), as Loxone does not allow slashes via it’s rest webservice.


For a direct Nuki mqtt integration, an LWT topic should be available (“Online” or “Connected” are usual terms).

Regards, Christian

If in any way possible, it would be nice to have additional infos (that the SmartLock possibly already uses internally):

  • The lock trigger (by App, Fob, Keypad, pushed the button indoor, opened manually)
  • If known, the user, userid, Fob, Fobid or what is known about the user.

This enables further automation, e.g. to start individual playlists or light moods dependent to the user, or do other feasible or unfeasible things, or simply log activity externally.

1 Like

The SL has for every lock command a trigger and a userid. The bridge did not have this information. So it’s something that could in theory be included in an MQTT API. However, first off we would like to start with the basic featureset of the HTTP-API. Once that is done we can discuss extensions … Goals and non goals are also explained here.

Considering the limitation of having to match the functionality of the HTTP-Bridge-API there is not much to discuss here.

As mentioned already I would suggest to keep it simple and match the structure of the HTTP-Bridge-API. There should be a default topic structure with nuki/nukiid (but preferably configurable) containing an LWT topic for instance nuki/nukiid/LWT.

And either a seperate topic for each attribute (for instance nuki/nukiid/lockstate for lockState) which are updated individually on change or a status topic (for instance nuki/nukiid/status) which holds all attributes as a JSON object which is updated when any of it’s attributes are changed.

I see both implementation with other products and both have advantages and disadvantages. Seeying that more attributes are often changed at the same time it’s probably better to send them as one updated JSON payload.

The purpose of the LWT topic is just to have a connection state right?
So it’s either 1 = connected or 0 = not connected.

JSON vs. individual topics is a central discussion point where we need an agreement on.
Any opinion on this from someone else?

Essentially yes. Read more about the purpose and implementation here.

The Last Will And Testament is a special message type that is sent to the broker on connecting, with the topic the broker should set when the connection is dying.
Therefore, on connecting you e.g. send the
LWT: nuki/1234567/connected = 0
and additionally publish
nuki/1234567/connected = 1

In any condition where the mqtt connection fails, the broker automatically sets nuki/1234567/connected = 0.
After reconnection (or regularly) you again publish nuki/1234567/connected = 1

About plain or json:
I a little prefer simple topics compared to json payload. With single topics it is easier to only subscribe the required messages, whereas in json it always requires to parse the full payload.
If json payload, to easily uniquify and transform the data, you should prevent the array data type, or multiple levels of hierarchy, because that makes it more complicated to parse.
Simple topics have the fewest requirements on the client side.

Hi All,

I am new in this game, but if I might suggest, I really like the MQTT structure of Shelly devices.

See the full documentation here:


and/or any of the particulars device MQTT documentation (for example the simple one button switch Shelly1):


To give a TL;DR:

  • Individual topics > JSON objects
    ** you can utilize f.e. the HA template for lock if you use individual topics MQTT Lock - Home Assistant
  • LWT is a must (in case the lock disconnects to have a graceful state handling)

I am happy to help with designing/testing/etc. (even building if you let me :smiley: ) but in order to do so… @Juergen do you know when 3.0 would be available again ? (as I currently don’t have any)

As far as i know an update about availability (or at least the upgrade program) is coming sometime this week on the Nuki blog. Make sure that you subscribe to it.

I agree with you, simple topics are easier to manage (no parsing) and also less overhead to integrate: in Home Assistant for example, you can create sensors that map a specific topic without templates or parsing whatsoever. Way better for end users.

For HA, autodiscovery topics would be really good to have, so basically HA would discover the lock(s) automatically and end users would have to do little or nothing to start using them. It would be like a native integration.

MQTT Discovery - Home Assistant (home-assistant.io)

1 Like