Created At

Sep 30, 2017

Last Update

Jan 15, 2019


HC 2





Nuki Smart Lock Virtual Device for Fibaro HC2:

The Smart Lock from Nuki is an extension to your home's existing lock which offers various ways to lock and unlock your door, including from the outside, using your existing keys, a manual button inside of the house, a bluetooth fob, a smartphone app and widget, a smartwatch app, IFTTT, the Web and through a Homebridge shim. 


With the Nuki Smart Lock Virtual Device for Fibaro HC2 you can lock, unlock or unltach your door with a single tap on your Fibaro web or smartphone app or through a scene that leverages this Virtual Device.


  • Nuki Smart Lock
  • Nuki Bridge

Developed and tested for use in conjunction with:

  • Nuki Smart Lock firmware version 1.4.5
  • Nuki Bridge HTTP-API version 1.5
  • Nuki Hardware Bridge

Supported functionality:

As provided, the Nuki Smart Lock VD offers three lock actions:

  1. Lock
  2. Unlock
  3. Unlatch (open door)

The Nuki Smart Lock VD (main loop) contacts the Nuki Bridge every 6 seconds and will update the VD status field with the latest known:

Nuki Smart Lock status:

  •           uncalibrated
  •           locked
  •           unlocking
  •           unlocked
  •           locking
  •           unlatched
  •           unlocked (lock ‘n’ go)
  •           unlatching
  •           motor blocked
  •           undefined

Nuki Smart Lock battery status.

Timestamp of the last lock action (optional). 

At the same time, the following predefined global variables are updated with a numerical value, which can be used in (block) scenes.


             0 - uncalibrated

             1 - locked

             2 - unlocking

             3 - unlocked

             4 - locking

             5 - unlatched

             6 - unlocked (lock ‘n’ go)

             7 - unlatching

        254 - motor blocked

        255 - undefined


             0 - battery OK

             1 - replace battery


By pressing a VD lock action button:

  • The VD icon is updated to show the corresponding lock action
  • The Bridge is instructed to perform the corresponding lock action on the Nuki Smart Lock and report back lock action status.


  • Whereas the Nuki Bridge can support multiple connected Nuki Smart Locks, the current version of the Nuki Smart Lock VD, will support only one Nuki Bridge connected Nuki Smart Lock.
  • Whereas the Nuki REST API supports a rich set of functionality, including device discovery and maintenance, the current version of the Nuki Smart Lock VD, will support only certain lock, unlock and unlatch operations and the provision of associated status information.
  • It takes 3-6 seconds before the Nuki Smart Lock VD confirms that the Bridge was successful or failed instructing the Nuki Smart Lock to perform the given lock action. It takes up to 24 seconds for the Nuki Smart Lock to perform the lock action on the door and report back its lock state via the Bridge to the Nuki Smart Lock VD.
  • Lock states are requested from the Nuki Bridge via the /list command, which produces the last known lock state cached by Nuki Bridge. This means, that the Bridge does not connect to the Nuki Smart Lock via Bluetooth to retrieve its lock state. Whilst this provides the fastest available feedback and limits smart lock battery consumption, the drawback is that the last known state might not always be correct.
  • The Nuki Smart Lock VD will not provide a lock action icon or lock action status indication when lock actions are in the process of being performed outside of the VD, such as by means of a regular key, fob, smart phone app, IFTT or through other means.
  • After providing a lock action, the Nuki Smart Lock VD will replace its main device icon with the lock action icon for a few seconds and then go back to displaying the main device icon, which provides no indication of lock status. Current lock status is always displayed as text.

Installation and configuration:

Download and extract the zip file provided below to a folder on your computer.

Locate the Nuki Smart Lock VD file (extension .vfib) in the folder and install by following the guidelines provided in the installation guide below.

Locate the icon files for the Nuki Smart Lock VD in the folder and use these files to customize the icons displayed for: 

  1. The virtual device itself
  2. The lock action buttons
  •           Lock
  •           Unlock
  •           Unlatch

Enter the maintenance mode to manage your Nuki Bridge:

  • Press and hold the button on your Bridge
  • Whilst pressing the button, insert the Bridge into the power socket
  • Keep pressing the button until the light on your Bridge is flashing
  • Open the menu in the Nuki app (top left) and choose “Manage Bridge” to search for your Bridge in maintenance mode.

When found, follow the instructions below:

  • Enable developer mode (HTTP API)
  • Note the Nuki Bridge IP address and enter this in the virtual device IP address field.
  • Note the Nuki Bridge Port (default: 8080) and enter this in the virtual device Port field.
  • Note the Nuki Bridge API token and enter this in the virtual device -> advanced configuration -> Main Loop section. 

In the main loop section you can further enable or disable:

  • Debugging. When disabled only main loop errors are shown. When enabled, the debug log will show detailed status information.
  • Timestamp. When disabled the VD status field will only show battery status and lock action confirmations. When enabled, the VD status field will show the latest lock action performed by the VD, along with a timestamp. This information displays well within a browser, but does not fit the VD frame in the Fibaro smart phone app.


As mentioned the Nuki Smart Lock VD comes preconfigured with the following three lock actions:

  1. Lock
  2. Unlock
  3. Unlatch (open door)

These lock actions can be customized by changing one digit (1-5) in the following line of VD button lock action= code:

local bridge_command = 'lockAction?nukiId='..nuki_id..'&action=2&noWait=1&token='..bridge_token

The following five lock actions are available:

  1. unlock
  2. lock
  3. unlatch
  4. lock ‘n’ go
  5. lock ‘n’ go with unlatch

Terms and conditions:

Nuki, the Nuki logo are trademarks of Nuki Home Solutions GmbH ("Nuki"). The Nuki HTTP API is a service provided by Nuki and governed by the terms and conditions imposed upon you by Nuki. By downloading this Virtual Device you agree to be bound by Nuki's terms and conditions of service. If you do not want to be bound by Nuki's terms your only option is not to download the Virtual Device. 

Barlow and Fibaro make no warranty, express or implied, and do not assume any legal liability or responsibility for the right to disclose and publish Nuki proprietarty information, nor for the  accuracy, completeness, usefulness, reliability, or timeliness of any documents or information contained on this website or for the suitability, functionality, or operation of this work.

Barlow and Fibaro shall not be liable to anyone for any decision made or action taken, or not taken, in reliance on the information found on or dowbloaded from this website.  Users are advised to do their own independent investigation before relying on or taking/not taking any action based on information found on this website. All information on this web site is subject to change or removal without notice.

Barlow and Fibaro do not represent that use of any documents or information on this website would not infringe privately or commercially owned rights.

The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.

Feedback and questions:

Leave your feedback and questions on the Fibaro Forum

11 Comments,  Want to add comment please login

does this work on the Nuki 3.0 Pro with WiFi? How do we go into management mode to recover IP, Port and API token?


Hello, I have a second bridge that controls two Nuki locks and it doesn't work, the first brige with only 1 lock works, the second doesn't, what should I change?


Hi, muss die NUKI ID nicht eingetragen werden? Ich bekomme keine Verbindung von HC2 zu Nuki


Hello Yesterday I did my installation with new Nuki Components. Same Error -> line 187: attempt to index global 'nuki_list' (a nil value). Any idea? Thank a lot...


Hello, Your VD works flawless for me until today, that it stops working and continue to tells me this error on debug: [DEBUG] 19:18:25: Nuki main loop activated [ERROR] 19:19:25: line 187: attempt to index global 'nuki_list' (a nil value) Can you help me? I haven't changed anything and until today it works fantastically well

© 2024. Nice-Polska Sp. z o.o.Privacy policyTerms & ConditionsFeedback