[APP][Pro] Nuki Direct


Your home has never been so smartly secured

This is an alternative Homey app for Nuki Smart Lock 1.0, 2.0, 3.0 (Pro) and Nuki Opener. Differently from The Nuki app created by Athom that relies on the Nuki cloud service for controlling your devices, Nuki Direct uses nothing but your local network for communications between your Homey and your Nuki devices via Nuki Bridge (internet access is optionally used for simplifying the initial pairing of a device). When a Nuki device changes its state, it will notify the new state directly to Homey. When Homey issues a command to a Smart Lock or to an Opener, it will send the request directly to the device.
So, benefits of this approach over the cloud approach are:

  • No internet connection needed for communication between Homey and Nuki.
  • Improved reliability: it does work even if the internet is down or the Nuki cloud service is temporarily unavailable.
  • Quick responsiveness thanks to the direct communication: the faster Homey knows about a state change, the better Homey can serve us.
  • Simpler code, smaller memory footprint.

Nuki Direct can also manage the extra features provided by Nuki API in addition to the standard commands, settings, capabilities and flow cards supplied by Homey. With Nuki Direct you can fine-tune the settings and control the specific lock states and events of your Nuki devices.

Since Nuki Direct and Nuki app by Athom have been developed with distinct APIs, they can happily run side by side on the same Homey without interfering.


Automatic installation: Nuki Direct is available for installation on the Homey Community Store.
Manual installation: the latest version of the Nuki Bridge API app can be found in the GitHub repository. Manual installation will require you to sideload this app with a CLI install. This involves some technical knowledge.

Adding your Nuki devices

Please, follow these steps to add your Nuki devices to Homey after you have installed the app.

  • First, make sure the Bridge HTTP API in your Nuki Bridge is enabled. You can do this within the Nuki smartphone app. Go to “Manage your devices” and select your Nuki Bridge. There you can enable the HTTP API.
  • Once enabled, go to the Homey app and add a Nuki device by selecting the “Nuki Direct” icon and then “Nuki Smart Lock” or “Nuki Homey”.
  • Tap the “Connect” button and wait for the searching process to start.
  • Press the button of your Nuki Bridge when requested.
  • Select the Nuki device(s) you wish to add to Homey and confirm.

Your Nuki(s) have now been added to Homey.

Release Notes

v3.1.0 - 2022-07-25

  • Support for Nuki Smart Lock 3.0 (Pro).
  • New trigger flow card when the new Nuki Bluetooth door sensor has been tampered with.
  • Notice: The existing trigger cards “Nuki state changed” for the Opener have lost the local tag “Previous Continuous mode”. If your flows need this local tag, you need to delete and re-create these flow cards. This is due to an internal code refactoring induced by a new app validation constraint in Homey (app cannot define multiple flow card triggers with same id).
  • Bug: Due to some changes in Homey Apps SDK v3, the “Nuki state changed” trigger cards (for both Smart Lock and Opener) were fired before the Nuki state capabilities were updated to the new values. Now, when a flow is started by these cards, the capability values (that can be used in a condition flow card) are already updated.
  • Bug: When a device was removed from Nuki Bridge, Nuki Direct did not react and the device appeared to still be available in Homey. Now the removed device is marked as unavailabl

v3.0.6 - 2020-11-03

  • Complete German translation of the app UI (thanks to Dirk).

  • New condition flow card “The contact alarm changed {less|more} than n seconds ago”. For more information see here.

  • Open (unlatch) a Smart Lock or an Opener by app UI or by action flow card: added a “safety” timer that restores the correct state in case the final event from the device is not received.

  • Pairing procedure has been rewritten. The new pairing procedure asks automatically the Nuki Servers for the list of registered Bridges (each Nuki Bridge is always registered at the Nuki Servers infrastructure).
    The Nuki Servers’s answer can be one of the following:

    1. More than one Bridge is registered. The user must select a Bridge from the list of Bridges.
    2. A single Bridge is registered (or the user selected a Bridge in the previous step). The new pairing procedure tries to authenticate against the Bridge via HTTP API. If API Quick Discovery is enabled, Authentication requires the user to press the button on the Bridge. Once authenticated, the procedure asks the Bridge for the list of its devices (Smart Locks and Openers).
    3. Other (unexpected answer, Nuki Servers are unreachable, …). Go to manual pairing.

    The Nuki Bridge’s answer can be one of the following:

    1. HTTP API is not enabled on the Bridge. Pairing failure.
    2. API Quick Discovery is not enabled on the Bridge. Go to manual paring.
    3. API Quick Discovery is enabled but the user did not press the button on the Nuki Bridge within 30 seconds. Go to manual paring.
    4. The Bridge returned a valid device list. The user can select the device they want to add to Homey and the pairing is successful.
    5. Other (answer not received, unexpected answer, …). Pairing failure.

    The manual pairing procedure prompts the user to enter IP address, port and API Token of the Bridge. If the entered data are correct, the pairing procedure retrieves the device list from the Bridge, the user can select the device they want to add to Homey and the pairing is successful.
    Thus, in the most common case (a single Bridge, HTTP API and API Quick Discovery already enabled in the Bridge) the paring procedure only requires the user to press the button on the Bridge.

  • Previous versions of Nuki Direct lose all devices and flows if the local IP address Homey changes. This version loses neither devices nor flows.

  • Some users have reported Nuki Direct’s slowness in updating the status of the devices in the first few minutes after a restart. Indeed, previous versions of Nuki Direct may take up to 5 minutes after a restart for the device status to update. This version updates the devices status immediately after the initialization.

  • Nuki Direct v3.0.0 introduced the ability to mark as unavailable all the devices of an unreachable Bridge. This version adds the ability to mark as unavailable a device that is unreachable by the Bridge as well.

  • Bug: the condition flow card “Doorbell rang less than n seconds ago” introduced in version v.3.0.3 was always evaluated as false.

v3.0.4 - 2020-09-26

  • Overlapping actions. Electromechanical actions such as Unlock and Lock, take time to actuate (from a few seconds to a few tens of seconds for the Lock ‘n’ Go). Therefore, it may occur that an action (from user interface or from an action flow) starts when another action is already in progress. Previous versions of Nuki Direct did not handle explicitly overlapping actions and this could lead to unexpected behaviors. This version applies the following rules to overlapping actions (i.e.: action B starts before the action A is finished). RULE 1: If action B is the same as action A (for example: B is a Lock action in progress and A is also a Lock action) then action B simply waits for the completion of A and return success. RULE 2: If action B is different from action A (for example: A is a Lock action in progress and B is an Open/Unlatch action) then action B is rejected. The action flow card “Nuki action” provides a new setting that optionally enables the following RULE 3: If the action B defined in the flow card is different from action A (same as RULE 2) then the flow card defers the execution of action B after the completion of action A. These rules also apply to more than two actions.
  • The ability to open a door directly from the Homey app user interface has been reintroduced (it was removed in v3.0.3 for security reason). In order to avoid accidental opening the original tap gesture has been replaced by a swipe gesture on a slider. The slider can be hidden in the “Advanced Settings” of the device.
  • Added German UI language (partial translation).
  • Pairing procedure reviewed. Manual pairing procedure improved (stronger input verification; “Test connection” button, “Connect” button, “Close” button merged into a single “Connect” button).
  • Keypad battery (minimum firmware version required: Keypad firmware 1.7, Bridge firmware 2.7.0/1.17.1, Smart Lock firmware 2.8.3/1.10.1, Opener firmware 1.5.2). The availability of a Nuki Keypad is automatically detected. If a Keypad is detected, the Keypad battery status is shown in the "Battery" page of the device (Smart Lock or Opener) it is paired with. Also added trigger flow cards and condition flow card for Keypad battery alarm.
  • Fixed an error introduced in v3.0.3: the Open/Unlatch action of the “Nuki action” action flow cards did not work.

v3.0.3 - 2020-08-28

This is the first version after the handover of the app development. New developer and new intents.

  • Differentiate the aspect from the Nuki app by Athom to avoid appearing as a duplicate app
    The new name “Nuki Direct” emphasizes straight, fast, reliable communication between Homey and Nuki devices. The app’s icon and color have also been changed.
  • Highlight the extra features offered by Nuki and implemented by this app over the standard features of Homey
    For this purpose, the icon and title of the device status displayed by the app have been changed; the trigger flow cards related to specific Nuki events have also been modified.
  • Make Smart Lock and Opener devices more homogeneous
    Before this version the devices were managed by two different developers and it was difficult to adopt the same model and the same terminology for the two devices.
  • Simplify the app
    Whenever a new version is released, new features are introduced; when introducing new features, existing features should also be re-evaluated: Is the new functionality consistent with the existing ones? Is the application getting too complicated? Am I creating overlapping features?
    After this re-evaluation the Continuous mode of the Opener and the Smart Lock battery status have been simplified. The device settings have been reordered. The pairing instructions have been refined.
  • Improve security
    In my opinion the possibility to unlatch a Smart Lock (or an Opener) directly from the Homey app user interface is dangerous; a single wrong tap can open the door when you are miles away from home! For now, I have hidden the unlatch command from the user interface. If there are no counter-observations, I will remove it completely in the future.
  • Resolve known issues
    The “Nuki Opener Ring Action” trigger flow card added to version 3.0.0 did not work correctly; furthermore, the Timestamp tag associated with this flow-card was difficult to use in practice.
    The problem has been solved and the tag has been removed and replaced by a new condition flow card: “Doorbell rang {less | more} than n seconds ago”.

v3.0.2 - 2020-08-17

  • App structure refactored using Homeycompose model in order to reduce the duplicated code between SmartLock driver and Opener driver.
  • Smartlock and Opener have different objects (SmartLock: 4xAA batteries; Opener: power supply or 4xAAA batteries). Created a specific Energy object for each driver.
  • Added to Opener devices an event handler that reacts immediately to Power Settings change.
  • Fixed a small comparison error that prevents the manual pairing of a SmartLock device.
  • Manual pairing of SmartLock and Opener: fixed the resolved promise argument (the custom view needs a result object, not the true constant).


I enjoy creating apps for Homey and try to support them as best as I can. If you enjoy using my apps a donation in return for the time I put into this is much appreciated.



v3.0.1 - 2020-08-07

  • Updated the app structure using Homey compose
  • Fixed manual pairing

v3.0.0 - 2020-08-07

  • Updated to SDK3 (this require Homey firmware 5.x).
  • Fixed issue with triggercards for continuous mode for Nuki opener.
  • Added instructions in pairing wizard.
  • Added battery percentage for Nuki Lock (requires Nuki Bridge firmware 2.7.0 and Nuki Lock firmware 2.8.1)
  • Added triggercard for Nuki Opener Ring actions including timestamp token (requires Nuki Bridge firmware 2.7.0 and Nuki Opener firmware 1.5.1)
  • Added Nuki Opener setting for configuring battery powered device. When enabled the battery alarm capability will be available
  • Added functionality where the Nuki will show as unreachable when it cant be reached

v1.4.0 - 2020-06-15

Added support for the door sensor of the Nuki lock. This requires bridge firmware 2.6.0 / 1.16.0 which is currently in beta. Please be aware that the Nuki callbacks of the door sensor are not real time. So there will be a delay in response which can also result in missed events.

v1.3.0 - 2020-06-01

Added support for Nuki Opener (kudo’s to Piero Freguia).

v1.2.0 - 2020-05-25

Added a manual pairing fallback mechanism, specifically useful for pairing a software Nuki bridge.

v1.1.3 - 2020-03-01

Small code refactoring to reduce complexity and lines of code.

v1.1.2 - 2019-12-04

Fixed custom condition card for (un)locked but also deprecated it as it’s a duplicate of the default condition cards for the locked capability

v1.1.1 - 2019-11-17

Fix for alarm_battery capability due to a bug in Homey core

v1.1.0 - 2019-11-11

  • Changed endpoint from /lockState to /list for polling the lock. The /list endpoints gets the cached state from the lock and using this will spare the batteries of the lock
  • Added the alarm_battery capability and deprecated the previous “Battery Critical” trigger card. Please switch to the default “Battery Alarm” trigger card as the old one does not work anymore

v1.0.3 - 2019-03-20

  • FIX: removed code to set the device unavailable when it is not reachable (due to know issue with 503 errors)
  • FIX: only trigger battery critical once until the batteries have been replaced

v1.0.2 - 2019-03-13

  • FIX: small workaround for random 503 errors from Nuki Bridge

v1.0.1 - 2019-03-13

  • FIX: small fix for quick action

Super work! Why not release it in the appstore? There are more apps that have different versions in the store. Its up to the Homey user to choose which one he likes best. And I like your version best :kissing_heart:

I’ll ask Athom on their opinion on this. I dont wanna contribute to a confusing eco system.

I agree with @gruijter it should be added. I see it as contributing to a versatile eco system.

Let the user choose which app to use, just like the Philips Hue, Ikea Trädfri and Weather Flow apps, an option for a (local) direct device connection and an option for a (cloud based) bridge connection.


I asked Emile from Athom on their point of view on this. As suspected they do not want two Nuki apps in the app store. I won’t be publishing this in the app store but it will stay available for side loading thorough CLI.


I can’t understand why your ‘second’ Nuki App is treated differently as the second Homekit, Philips Hue, Ikea Trädfri, Osram Lightify, WeatherFlow and the multiple timer/countdown apps.
I thought Athom was improving on listening to their customers but it seems I was wrong :frowning:


And I guess Athom has had direct contact with Nuki while building the app. Looking at the the store actions has with things like free fobs…

Problem is that Athom also sells other Smart Home stuff, so they have a costumer/supplier reilationship with some of the company’s with an app in the app store. And they sometimes make aggreements with eachother.

Well I gues Athom needs some sort of a cashflow next to Homey so I prefer this way above some sprt of subscription plan. However this isn’t flawless either I understand.

@Phuturist Im using the Nuki v2, with the doorsensor (door opend or closed) any possibility you can add that to the app? i’ll be happy to test.

Thnx in advance

It’s not available in the bridge API yet. You can vote for my feature request on the Nuki forum here: https://developer.nuki.io/t/add-user-to-bridge-http-api-notifications/151/15

Ok, didnt knew that thanks.
But is strange do, i can see the lock status when im not at home so its passed through the bride than right?

Linked to the wrong feature request, this is the right one. But please vote on both.

It might be available in the bridge, it’s not in the API yet.

Thnx, i voted

Can’t add my nuki v2.
error: request to failed, reason:
connect econnrefused.
Am I doing something wrong?

Looking at the error you do not have the correct password.

There is no window where do i type my password.
In the Athom app i’ll get a window to fill in my nuki web password.
But not in you’re app

sorry doesn’t matter i’ve installed the athom app and uninstalled your nuki app.
Now i get a login windows.

1 Like


my alarm is based on the nuki status, which with the atom app was not updated fast enough
Do you confirm your version will update its status much faster?

edit: installed your app and it seems the status update is almost slower than the athom app, i guess something is wrong in my config

got an error message once trying to open and close the door from you app
, any idea how to correct this?

Make sure you have the latest firmware and the latest version of my nuki app. It’s an issue with the Nuki. More info here:

1 Like