-It exposes the lock state (and much more) through MQTT and allows executing commands like locking and unlocking through MQTT.
+It exposes the lock state (and much more) through MQTT and allows executing commands like locking and unlocking as well as changing the Nuki Lock/Opener configuration through MQTT.
***Nuki Hub does not integrate with the Nuki mobile app, it can't register itself as a bridge in the official Nuki mobile app.***
@@ -15,10 +15,12 @@ Feel free to join us on Discord: https://discord.gg/feB9FnMY
## Supported devices
Supported ESP32 devices:
-- All dual-core ESP32 models with WIFI and BLE which are supported by Arduino Core 2.0.15 should work. Tested builds are provided for the ESP32 and ESP32-S3.
-- Single-core ESP32 models with WIFI and BLE which are supported by Arduino Core 2.0.15 might work. Untested builds are provided for the ESP32-C3 and ESP32-Solo1.
+- All ESP32 models with WIFI and BLE which are supported by Arduino Core 2.0.15 should work. Tested builds are provided for the ESP32, ESP32-S3 and ESP32-C3.
+- Untested builds are provided for the ESP32-Solo1.
+
+Not supported ESP32 devices:
- The ESP32-S2 has no BLE and as such can't run Nuki Hub.
-- The ESP32-C6 and ESP32-H2 are not supported by Arduino Core 2.0.15 as such can't run Nuki Hub (at this time).
+- The ESP32-C6 and ESP32-H2 are not supported by Arduino Core 2.0.15 and as such Nuki Hub is not compiled against these targets (at this time).
Supported Nuki devices:
- Nuki Smart Lock 1.0
@@ -65,7 +67,7 @@ In a browser navigate to the IP address assigned to the ESP32 via DHCP (often fo
Next click on "Edit" below "MQTT and Network Configuration" and enter the address and port (usually 1883) of your MQTT broker and a username and a password if required by your MQTT broker.
The firmware supports SSL encryption for MQTT, however most people and especially home users don't use this.
-In that case leave all fields starting with "MQTT SSL" blank. Otherwise see the "MQTT Encryption" section of this README.
+In that case leave all fields starting with "MQTT SSL" blank. Otherwise see the "[MQTT Encryption](#mqtt-encryption-optional-wi-fi-and-lan8720-only)" section of this README.
## Pairing with a Nuki Lock or Opener
@@ -82,7 +84,7 @@ Enable "Register as app" before pairing to allow this. Otherwise the Bridge will
## Support
If you haven't ordered your Nuki product yet, you can support me by using my referrer code when placing your order:
-REFNW2959GXR7
+REFXH49NT9NGP
This will also give you a 10% discount on your order.
This project is free to use for everyone. However if you feel like donating, you can buy me a coffee at ko-fi.com:
@@ -106,11 +108,11 @@ In a browser navigate to the IP address assigned to the ESP32.
- Home Assistant discovery topic: Set to the Home Assistant auto discovery topic, leave empty to disable auto discovery. Usually "homeassistant" unless you manually changed this setting on the Home Assistant side.
- Home Assistant device configuration URL: When using Home Assistant discovery the link to the Nuki Hub Web Configuration will be published to Home Assistant. By default when this setting is left empty this will link to the current IP of the Nuki Hub. When using a reverse proxy to access the Web Configuration you can set a custom URL here.
-- Set Nuki Opener Lock/Unlock action in Home Assistant to Continuous mode (Opener only): By default the lock entity in Home Assistant will enable Ring-to-Open (RTO) when unlocking and disable RTO when locking. By enabling this setting this behaviour will change and now unlocking will enable Continuous Mode and locking will disable Continuous Mode, for more information see the "Home Assistant Discovery" section of this README.
-- MQTT SSL CA Certificate: Optionally set to the CA SSL certificate of the MQTT broker, see the "MQTT Encryption" section of this README.
-- MQTT SSL Client Certificate: Optionally set to the Client SSL certificate of the MQTT broker, see the "MQTT Encryption" section of this README.
-- MQTT SSL Client Key: Optionally set to the Client SSL key of the MQTT broker, see the "MQTT Encryption" section of this README.
-- Network hardware: "Wi-Fi only" by default, set to one of the specified ethernet modules if available, see the "Supported Ethernet devices" and "Connecting via Ethernet" section of this README.
+- Set Nuki Opener Lock/Unlock action in Home Assistant to Continuous mode (Opener only): By default the lock entity in Home Assistant will enable Ring-to-Open (RTO) when unlocking and disable RTO when locking. By enabling this setting this behaviour will change and now unlocking will enable Continuous Mode and locking will disable Continuous Mode, for more information see the "[Home Assistant Discovery](#home-assistant-discovery-optional)" section of this README.
+- MQTT SSL CA Certificate: Optionally set to the CA SSL certificate of the MQTT broker, see the "[MQTT Encryption](#mqtt-encryption-optional-wi-fi-and-lan8720-only)" section of this README.
+- MQTT SSL Client Certificate: Optionally set to the Client SSL certificate of the MQTT broker, see the "[MQTT Encryption](#mqtt-encryption-optional-wi-fi-and-lan8720-only)" section of this README.
+- MQTT SSL Client Key: Optionally set to the Client SSL key of the MQTT broker, see the "[MQTT Encryption](#mqtt-encryption-optional-wi-fi-and-lan8720-only)" section of this README.
+- Network hardware: "Wi-Fi only" by default, set to one of the specified ethernet modules if available, see the "Supported Ethernet devices" and "[Connecting via Ethernet](#connecting-via-ethernet-optional)" section of this README.
- Disable fallback to Wi-Fi / Wi-Fi config portal: By default the Nuki Hub will fallback to Wi-Fi and open the Wi-Fi configuration portal when the network connection fails. Enable this setting to disable this fallback.
- RSSI Publish interval: Set to a positive integer to set the amount of seconds between updates to the maintenance/wifiRssi MQTT topic with the current Wi-Fi RSSI, set to -1 to disable, default 60.
- Network Timeout until restart: Set to a positive integer to restart the Nuki Hub after the set amount of seconds has passed without an active connection to the MQTT broker, set to -1 to disable, default 60.
@@ -143,16 +145,15 @@ In a browser navigate to the IP address assigned to the ESP32.
- Query interval keypad (Only available when a Keypad is detected): Set to a positive integer to set the maximum amount of seconds between actively querying the Nuki device for the current keypad state, default 1800.
- Number of retries if command failed: Set to a positive integer to define the amount of times the Nuki Hub retries sending commands to the Nuki Lock or Opener when commands are not acknowledged by the device, default 3.
- Delay between retries: Set to the amount of milliseconds the Nuki Hub waits between resending not acknowledged commands, default 100.
-- Nuki Bridge is running alongside Nuki Hub: Enable to allow Nuki Hub to co-exist with a Nuki Bridge by registering Nuki Hub as an (smartphone) app instead of a bridge. Changing this setting will require re-pairing. Enabling this setting is strongly discouraged as described in the "Pairing with a Nuki Lock or Opener" section of this README
+- Nuki Bridge is running alongside Nuki Hub: Enable to allow Nuki Hub to co-exist with a Nuki Bridge by registering Nuki Hub as an (smartphone) app instead of a bridge. Changing this setting will require re-pairing. Enabling this setting is strongly discouraged as described in the "[Pairing with a Nuki Lock or Opener](#pairing-with-a-nuki-lock-or-opener)" section of this README
- Presence detection timeout: Set to a positive integer to set the amount of seconds between updates to the presence/devices MQTT topic with the list of detected bluetooth devices, set to -1 to disable presence detection, default 60.
- Restart if bluetooth beacons not received: Set to a positive integer to restart the Nuki Hub after the set amount of seconds has passed without receiving a bluetooth beacon from the Nuki device, set to -1 to disable, default 60. Because the bluetooth stack of the ESP32 can silently fail it is not recommended to disable this setting.
### Access Level Configuration
#### Nuki General Access Control
-- Change Lock/Opener configuration: Allows changing the Nuki Lock/Opener configuration through MQTT.
-- Publish keypad codes information (Only available when a Keypad is detected): Enable to publish information about keypad codes through MQTT, see the "Keypad control" section of this README
-- Add, modify and delete keypad codes (Only available when a Keypad is detected): Enable to allow configuration of keypad codes through MQTT, see the "Keypad control" section of this README
+- Publish keypad codes information (Only available when a Keypad is detected): Enable to publish information about keypad codes through MQTT, see the "[Keypad control](#keypad-control-optional)" section of this README
+- Add, modify and delete keypad codes (Only available when a Keypad is detected): Enable to allow configuration of keypad codes through MQTT, see the "[Keypad control](#keypad-control-optional)" section of this README
- Publish time control information: Enable to publish information about time control entries through MQTT, see the "Time control" section of this README
- Add, modify and delete time control entries: Enable to allow configuration of time control entries through MQTT, see the "Time control" section of this README
- Publish auth data: Enable to publish authorization data to the MQTT topic lock/log. Requires the Nuki security code / PIN to be set, see "Nuki Lock PIN / Nuki Opener PIN" below.
@@ -160,6 +161,10 @@ In a browser navigate to the IP address assigned to the ESP32.
#### Nuki Lock/Opener Access Control
- Enable or disable executing each available lock action for the Nuki Lock and Nuki Opener through MQTT. Note: GPIO control is not restricted through this setting.
+#### Nuki Lock/Opener Config Control
+- Enable or disable changing each available configuration setting for the Nuki Lock and Nuki Opener through MQTT.
+- NOTE: Changing configuration settings requires the Nuki security code / PIN to be set, see "Nuki Lock PIN / Nuki Opener PIN" below.
+
### Credentials
#### Credentials
@@ -199,13 +204,6 @@ In a browser navigate to the IP address assigned to the ESP32.
- lock/rssi: The signal strenght of the Nuki Lock as measured by the ESP32 and expressed by the RSSI Value in dBm.
- lock/address: The BLE address of the Nuki Lock.
- lock/retry: Reports the current number of retries for the current command. 0 when command is succesfull, "failed" if the number of retries is greater than the maximum configured number of retries.
-
-- configuration/autoLock: enable or disable autoLock (0 = disabled; 1 = enabled). Maps to "Auto lock enabled" in the bluetooth API.
-- configuration/autoUnlock: enable or disable autoLock in general (0 = disabled; 1 = enabled). Maps to "Auto unlock disabled" in the bluetooth API.
-- configuration/buttonEnabled: enable or disable the button on the lock (0 = disabled; 1 = enabled).
-- configuration/ledBrightness: Set the brightness of the LED on the lock (0=min; 5=max).
-- configuration/ledEnabled: enable or disable the LED on the lock (0 = disabled; 1 = enabled).
-- configuration/singleLock: configures wether to single- or double-lock the door (0 = double; 1 = single).
### Opener
@@ -228,10 +226,19 @@ In a browser navigate to the IP address assigned to the ESP32.
- lock/rssi: The bluetooth signal strength of the Nuki Lock as measured by the ESP32 and expressed by the RSSI Value in dBm.
- lock/address: The BLE address of the Nuki Lock.
- lock/retry: Reports the current number of retries for the current command. 0 when command is succesfull, "failed" if the number of retries is greater than the maximum configured number of retries.
-
-- configuration/buttonEnabled: enable or disable the button on the opener (0 = disabled; 1 = enabled).
-- configuration/ledEnabled: enable or disable the LED on the opener (0 = disabled; 1 = enabled).
-- configuration/soundLevel: configures the volume of sounds the opener plays back (0 = min; 255 = max).
+
+### Configuration
+- configuration/buttonEnabled: 1 if the Nuki Lock/Opener button is enabled, otherwise 0.
+- configuration/ledEnabled: 1 if the Nuki Lock/Opener LED is enabled, otherwise 0.
+- configuration/ledBrightness: Set to the brightness of the LED on the Nuki Lock (0=min; 5=max) (Lock only).
+- configuration/singleLock: 0 if the Nuki Lock is set to double-lock the door, otherwise 1 (= single-lock) (Lock only).
+- configuration/autoLock: 1 if the Nuki Lock is set to Auto Lock, otherwise 0 (Lock only).
+- configuration/autoUnlock: 1 if the Nuki Lock is set to Auto Unlock, otherwise 0 (Lock only).
+- configuration/soundLevel: Set to the volume for sounds the Nuki Opener plays (0 = min; 255 = max) (Opener only).
+- configuration/action: Allows changing configuration settings of the Nuki Lock/Opener using a JSON formatted value. After receiving the action, the value is set to "--". See the "[Changing Nuki Lock/Opener Configuration](#changing-nuki-lockopener-configuration)" section of this README for possible actions/values
+- configuration/commandResult: Result of the last configuration change action as JSON data. See the "[Changing Nuki Lock/Opener Configuration](#changing-nuki-lockopener-configuration)" section of this README for possible values
+- configuration/basicJson: The current basic configuration of the Nuki Lock/Opener as JSON data. See [Nuki Smart Lock API](https://developer.nuki.io/page/nuki-smart-lock-api-2/2/#heading--set-config) and [Nuki Opener API](https://developer.nuki.io/page/nuki-opener-api-1/7/#heading--set-config) for available settings. Please note: Longitude and Latitude of the Lock/Opener are not published to MQTT by design. These values can still be changed though.
+- configuration/advancedJson: The current advanced configuration of the Nuki Lock/Opener as JSON data. See [Nuki Smart Lock API](https://developer.nuki.io/page/nuki-smart-lock-api-2/2/#heading--advanced-config) and [Nuki Opener API](https://developer.nuki.io/page/nuki-opener-api-1/7/#heading--advanced-config) for available settings.
### Query
@@ -254,7 +261,7 @@ In a browser navigate to the IP address assigned to the ESP32.
### Keypad
-- See the "Keypad control" section of this README.
+- See the "[Keypad control](#keypad-control-optional)" section of this README.
### Time Control
@@ -277,19 +284,125 @@ In a browser navigate to the IP address assigned to the ESP32.
- maintenance/wifiRssi: The Wi-Fi signal strength of the Wi-Fi Access Point as measured by the ESP32 and expressed by the RSSI Value in dBm.
- maintenance/log: If "Enable MQTT logging" is enabled in the web interface, this topic will be filled with debug log information.
- maintenance/freeHeap: Only available when debug mode is enabled. Set to the current size of free heap memory in bytes.
-- maintenance/restartReasonNukiHub: Only available when debug mode is enabled. Set to the last reason Nuki Hub was restarted. See RestartReason.h for possible values
-- maintenance/restartReasonNukiEsp: Only available when debug mode is enabled. Set to the last reason the ESP was restarted. See RestartReason.h for possible values
+- maintenance/restartReasonNukiHub: Only available when debug mode is enabled. Set to the last reason Nuki Hub was restarted. See [RestartReason.h](/RestartReason.h) for possible values
+- maintenance/restartReasonNukiEsp: Only available when debug mode is enabled. Set to the last reason the ESP was restarted. See [RestartReason.h](/RestartReason.h) for possible values
### Misc
- presence/devices: List of detected bluetooth devices as CSV. Can be used for presence detection.
+## Changing Nuki Lock/Opener Configuration
+
+To change Nuki Lock/Opener settings set the `configuration/action` topic to a JSON formatted value with any of the following settings. Multiple settings can be changed at once. See [Nuki Smart Lock API Basic Config](https://developer.nuki.io/page/nuki-smart-lock-api-2/2/#heading--set-config), [Nuki Smart Lock API Advanced Config](https://developer.nuki.io/page/nuki-smart-lock-api-2/2/#heading--advanced-config), [Nuki Opener API Basic Config](https://developer.nuki.io/page/nuki-opener-api-1/7/#heading--set-config) and [Nuki Opener API Advanced Config](https://developer.nuki.io/page/nuki-opener-api-1/7/#heading--advanced-config) for more information on the available settings.
+Changing settings has to enabled first in the configuration portal. Check the settings you want to be able to change under "Nuki Lock/Opener Config Control" in "Access Level Configuration" and save the configuration.
+
+### Nuki Lock Configuration
+
+| Setting | Usage | Possible values | Example |
+|-----------------------------------------|--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|------------------------------------|
+| name | The name of the Smart Lock. | Alphanumeric string, max length 32 chars |`{ "name": "Frontdoor" }` |
+| latitude | The latitude of the Smart Locks geoposition. | Float |`{ "latitude": "48.858093" }` |
+| longitude | The longitude of the Smart Locks geoposition | Float |`{ "longitude": "2.294694" }` |
+| autoUnlatch | Whether or not the door shall be unlatched by manually operating a door handle from the outside. | 1 = enabled, 0 = disabled |`{ "autoUnlatch": "1" }` |
+| pairingEnabled | Whether or not activating the pairing mode via button should be enabled. | 1 = enabled, 0 = disabled |`{ "pairingEnabled": "0" }` |
+| buttonEnabled | Whether or not the button should be enabled. | 1 = enabled, 0 = disabled |`{ "buttonEnabled": "1" }` |
+| ledEnabled | Whether or not the flashing LED should be enabled to signal an unlocked door. | 1 = enabled, 0 = disabled |`{ "ledEnabled": "1" }` |
+| ledBrightness | The LED brightness level | 0 = off, …, 5 = max |`{ "ledBrightness": "2" }` |
+| timeZoneOffset | The timezone offset (UTC) in minutes | Integer between 0 and 60 |`{ "timeZoneOffset": "0" }` |
+| dstMode | The desired daylight saving time mode. | 0 = disabled, 1 = European |`{ "dstMode": "0" }` |
+| fobAction1 | The desired action, if a Nuki Fob is pressed once. | "No Action", "Unlock", "Lock", "Lock n Go", "Intelligent" |`{ "fobAction1": "Lock n Go" }` |
+| fobAction2 | The desired action, if a Nuki Fob is pressed twice. | "No Action", "Unlock", "Lock", "Lock n Go", "Intelligent" |`{ "fobAction2": "Intelligent" }` |
+| fobAction3 | The desired action, if a Nuki Fob is pressed three times. | "No Action", "Unlock", "Lock", "Lock n Go", "Intelligent" |`{ "fobAction3": "Unlock" }` |
+| singleLock | Whether only a single lock or double lock should be performed | 0 = double lock, 1 = single lock |`{ "singleLock": "0" }` |
+| advertisingMode | The desired advertising mode. | "Automatic", "Normal", "Slow", "Slowest" |`{ "advertisingMode": "Normal" }` |
+| timeZone | The current timezone or "None" if timezones are not supported | "None" or one of the timezones from [Nuki Timezones](https://developer.nuki.io/page/nuki-smart-lock-api-2/2/#heading--list-of-timezone-ids) |`{ "timeZone": "Europe/Berlin" }` |
+| unlockedPositionOffsetDegrees | Offset that alters the unlocked position in degrees. | Integer between -90 and 180 |`{ "unlockedPositionOffsetDegrees": "-90" }` |
+| lockedPositionOffsetDegrees | Offset that alters the locked position in degrees. | Integer between -180 and 90 |`{ "lockedPositionOffsetDegrees": "80" }` |
+| singleLockedPositionOffsetDegrees | Offset that alters the single locked position in degrees. | Integer between -180 and 180 |`{ "singleLockedPositionOffsetDegrees": "120" }` |
+| unlockedToLockedTransitionOffsetDegrees | Offset that alters the position where transition from unlocked to locked happens in degrees. | Integer between -180 and 180 |`{ "unlockedToLockedTransitionOffsetDegrees": "180" }` |
+| lockNgoTimeout | Timeout for lock ‘n’ go in seconds | Integer between 5 and 60 |`{ "lockNgoTimeout": "60" }` |
+| singleButtonPressAction | The desired action, if the button is pressed once. | "No Action", "Intelligent", "Unlock", "Lock", "Unlatch", "Lock n Go", "Show Status" |`{ "singleButtonPressAction": "Lock n Go" }` |
+| doubleButtonPressAction | The desired action, if the button is pressed twice. | "No Action", "Intelligent", "Unlock", "Lock", "Unlatch", "Lock n Go", "Show Status" |`{ "doubleButtonPressAction": "Show Status" }` |
+| detachedCylinder | Wheter the inner side of the used cylinder is detached from the outer side. | 0 = not detached, 1 = detached |`{ "detachedCylinder": "1" }` |
+| batteryType | The type of the batteries present in the smart lock. | "Alkali", "Accumulators", "Lithium" |`{ "batteryType": "Accumulators" }` |
+| automaticBatteryTypeDetection | Whether the automatic detection of the battery type is enabled. | 1 = enabled, 0 = disabled |`{ "automaticBatteryTypeDetection": "Lock n Go" }` |
+| unlatchDuration | Duration in seconds for holding the latch in unlatched position. | Integer between 1 and 30 |`{ "unlatchDuration": "3" }` |
+| autoLockTimeOut | Seconds until the smart lock relocks itself after it has been unlocked. | Integer between 30 and 180 |`{ "autoLockTimeOut": "60" }` |
+| autoUnLockDisabled | Whether auto unlock should be disabled in general. | 1 = auto unlock disabled, 0 = auto unlock enabled |`{ "autoUnLockDisabled": "1" }` |
+| nightModeEnabled | Whether nightmode is enabled. | 1 = enabled, 0 = disabled |`{ "nightModeEnabled": "1" }` |
+| nightModeStartTime | Start time for nightmode if enabled. | Time in "HH:MM" format |`{ "nightModeStartTime": "22:00" }` |
+| nightModeEndTime | End time for nightmode if enabled. | Time in "HH:MM" format |`{ "nightModeEndTime": "07:00" }` |
+| nightModeAutoLockEnabled | Whether auto lock should be enabled during nightmode. | 1 = enabled, 0 = disabled |`{ "nightModeAutoLockEnabled": "1" }`|
+| nightModeAutoUnlockDisabled | Whether auto unlock should be disabled during nightmode. | 1 = auto unlock disabled, 0 = auto unlock enabled |`{ "nightModeAutoUnlockDisabled": "1" }`|
+| nightModeImmediateLockOnStart | Whether the door should be immediately locked on nightmode start. | 1 = enabled, 0 = disabled |`{ "nightModeImmediateLockOnStart": "1" }`|
+| autoLockEnabled | Whether auto lock is enabled. | 1 = enabled, 0 = disabled |`{ "autoLockEnabled": "1" }` |
+| immediateAutoLockEnabled | Whether auto lock should be performed immediately after the door has been closed. | 1 = enabled, 0 = disabled |`{ "immediateAutoLockEnabled": "1" }`|
+| autoUpdateEnabled | Whether automatic firmware updates should be enabled. | 1 = enabled, 0 = disabled |`{ "autoUpdateEnabled": "1" }` |
+
+### Nuki Opener Configuration
+
+| Setting | Usage | Possible values | Example |
+|-----------------------------------------|--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|------------------------------------|
+| name | The name of the Opener. | Alphanumeric string, max length 32 chars |`{ "name": "Frontdoor" }` |
+| latitude | The latitude of the Openers geoposition. | Float |`{ "latitude": "48.858093" }` |
+| longitude | The longitude of the Openers geoposition | Float |`{ "longitude": "2.294694" }` |
+| pairingEnabled | Whether or not activating the pairing mode via button should be enabled. | 1 = enabled, 0 = disabled |`{ "pairingEnabled": "0" }` |
+| buttonEnabled | Whether or not the button should be enabled. | 1 = enabled, 0 = disabled |`{ "buttonEnabled": "1" }` |
+| ledFlashEnabled | Whether or not the flashing LED should be enabled to signal CM or RTO. | 1 = enabled, 0 = disabled |`{ "ledFlashEnabled": "1" }` |
+| timeZoneOffset | The timezone offset (UTC) in minutes | Integer between 0 and 60 |`{ "timeZoneOffset": "0" }` |
+| dstMode | The desired daylight saving time mode. | 0 = disabled, 1 = European |`{ "dstMode": "0" }` |
+| fobAction1 | The desired action, if a Nuki Fob is pressed once. | "No Action", "Toggle RTO", "Activate RTO", "Deactivate RTO", "Open", "Ring" |`{ "fobAction1": "Toggle RTO" }` |
+| fobAction2 | The desired action, if a Nuki Fob is pressed twice. | "No Action", "Toggle RTO", "Activate RTO", "Deactivate RTO", "Open", "Ring" |`{ "fobAction2": "Open" }` |
+| fobAction3 | The desired action, if a Nuki Fob is pressed three times. | "No Action", "Toggle RTO", "Activate RTO", "Deactivate RTO", "Open", "Ring" |`{ "fobAction3": "Ring" }` |
+| operatingMode | The desired operating mode | "Generic door opener", "Analogue intercom", "Digital intercom", "Siedle", "TCS", "Bticino", "Siedle HTS", "STR", "Ritto", "Fermax", "Comelit", "Urmet BiBus", "Urmet 2Voice", "Golmar", "SKS", "Spare" |`{ "operatingMode": "TCS" }` |
+| advertisingMode | The desired advertising mode. | "Automatic", "Normal", "Slow", "Slowest" |`{ "advertisingMode": "Normal" }` |
+| timeZone | The current timezone or "None" if timezones are not supported | "None" or one of the timezones from [Nuki Timezones](https://developer.nuki.io/page/nuki-smart-lock-api-2/2/#heading--list-of-timezone-ids) |`{ "timeZone": "Europe/Berlin" }` |
+| intercomID | Database ID of the connected intercom. | Integer |`{ "intercomID": "1" }` |
+| busModeSwitch | Method to switch between data and analogue mode | 0 = none, 1 =vshort circuit |`{ "busModeSwitch": "0" }` |
+| shortCircuitDuration | Duration of the short circuit for BUS mode switching in ms. | Integer |`{ "shortCircuitDuration": "250" }` |
+| electricStrikeDelay | Delay in ms of electric strike activation in case of an electric strike actuation by RTO | Integer between 0 and 30000 |`{ "electricStrikeDelay": "2080" }` |
+| randomElectricStrikeDelay | Random delay (3-7s) in order to simulate a person inside actuating the electric strike. | 1 = enabled, 0 = disabled |`{ "randomElectricStrikeDelay": "1" }`|
+| electricStrikeDuration | Duration in ms of electric strike actuation. . | Integer between 1000 and 30000 |`{ "electricStrikeDuration": "5000" }` |
+| disableRtoAfterRing | Whether to disable RTO after ring. | 1 = disable RTO after ring, 0 = Don't disable RTO after ring |`{ "disableRtoAfterRing": "0" }` |
+| rtoTimeout | After this period of time in minutes, RTO gets deactivated automatically | Integer between 5 and 60 |`{ "rtoTimeout": "60" }` |
+| doorbellSuppression | Whether the doorbell is suppressed when Ring, CM and/or RTO are active | "Off", "CM", "RTO", "CM & RTO", "Ring", "CM & Ring", "RTO & Ring", "CM & RTO & Ring"|`{ "doorbellSuppression": "CM & Ring" }`|
+| doorbellSuppressionDuration | Duration in ms of doorbell suppression. | Integer between 500 and 10000 |`{ "doorbellSuppressionDuration": "2000" }` |
+| soundRing | The Ring sound | "No Sound", "Sound 1", "Sound 2", "Sound 3" |`{ "soundRing": "No Sound" }` |
+| soundOpen | The Open sound. | "No Sound", "Sound 1", "Sound 2", "Sound 3" |`{ "soundOpen": "Sound 1" }` |
+| soundRto | The RTO sound. | "No Sound", "Sound 1", "Sound 2", "Sound 3" |`{ "soundRto": "Sound 2" }` |
+| soundCm | The CM sound. | "No Sound", "Sound 1", "Sound 2", "Sound 3" |`{ "soundCm": "Sound 3" }` |
+| soundConfirmation | Sound confirmation | 0 = no sound, 1 = sound |`{ "soundConfirmation": "1" }` |
+| soundLevel | The sound level for the opener | Integer between 0 and 255 |`{ "soundLevel": "200" }` |
+| singleButtonPressAction | The desired action, if the button is pressed once. | "No Action", "Toggle RTO", "Activate RTO", "Deactivate RTO", "Toggle CM", "Activate CM", "Deactivate CM", "Open" |`{ "singleButtonPressAction": "Open" }` |
+| doubleButtonPressAction | The desired action, if the button is pressed twice. | "No Action", "Toggle RTO", "Activate RTO", "Deactivate RTO", "Toggle CM", "Activate CM", "Deactivate CM", "Open" |`{ "doubleButtonPressAction": "No Action" }` |
+| batteryType | The type of the batteries present in the smart lock. | "Alkali", "Accumulators", "Lithium" |`{ "batteryType": "Accumulators" }` |
+| automaticBatteryTypeDetection | Whether the automatic detection of the battery type is enabled. | 1 = enabled, 0 = disabled |`{ "automaticBatteryTypeDetection": "1" }` |
+
+Example usage for changing multiple settings at once:
+- `{ "buttonEnabled": "1", "lockngoTimeout": "60", "automaticBatteryTypeDetection": "1" }`
+- `{ "fobAction1": "Unlock", "fobAction2": "Intelligent", "nightModeImmediateLockOnStart": "1" }`
+
+### Result of attempted configuration changes
+
+The result of the last configuration change action will be published to the `configuration/commandResult` MQTT topic as JSON data.
+
+The JSON data will include a node called "general" and a node for every setting that Nuki Hub detected in the action.
+Possible values for the "general" node are "noPinSet", "invalidJson", "invalidConfig", "success" and "noChange".
+Possible values for the node per setting are "unchanged", "noValueSet", "invalidValue", "valueTooLong", "accessDenied", "success", "failed", "timeOut", "working", "notPaired", "error" and "undefined"
+
+Example:
+- `{"advertisingMode":"success","general":"success"}`
+
+### Home Assistant discovery
+
+If Home Assistant discovery is enabled (see the [Home Assistant Discovery](#home-assistant-discovery-optional) section of this README) Nuki Hub will create entities for almost all of the above settings. These entities will be disabled by default in Home Assistant, but can be found in the MQTT devices section of the Home Assistant UI under the "Configuration" section of the Nuki Lock/Opener and enabled there.
+
## Over-the-air Update (OTA)
After the initial installation of the Nuki Hub firmware via serial connection, further updates can be deployed via OTA update from a browser.
In the configuration portal, scroll down to "Firmware update" and click "Open".
Then Click "Browse" and select the new "nuki_hub.bin" file and select "Upload file".
-After about a minute the new firmware should be installed.
+After about a minute the new firmware should be installed afterwhich the ESP will reboot automatically.
## MQTT Encryption (optional; Wi-Fi and LAN8720 only)
@@ -314,7 +427,7 @@ The following mapping between Home Assistant services and Nuki commands is setup
| lock.unlock | Unlock | Enable Ring To Open | Enable Continuous Mode |
| lock.open | Unlatch | Electric Strike Actuation | Electric Strike Actuation |
-NOTE: MQTT Discovery uses retained MQTT messages to store devices configurations. In order to avoid orphan configurations on your broker please disable autodiscovery first if you no longer want to use this SW. Retained messages are automatically cleared when unpairing and when changing/disabling autodiscovery topic in MQTT Configuration page.
+NOTE: MQTT Discovery uses retained MQTT messages to store devices configurations. In order to avoid orphan configurations on your broker please disable autodiscovery first if you no longer want to use this software. Retained messages are automatically cleared when unpairing and when changing/disabling autodiscovery topic in MQTT Configuration page.
NOTE2: Home Assistant can be setup manually using the [MQTT Lock integration](https://www.home-assistant.io/integrations/lock.mqtt/), but this is not recommended
## Keypad control using JSON (optional)
@@ -327,21 +440,20 @@ For security reasons, the code itself is not published.
To change Nuki Lock/Opener keypad settings set the `keypad/actionJson` topic to a JSON formatted value containing the following nodes.
-| Node | Delete | Add | Update | Usage | Possible values |
-|------------------|----------|----------|----------|------------------------------------------------------------------------------------------|----------------------------------------------------------------|
-| action | Required | Required | Required | The action to execute | "delete", "add", "update" |
-| codeId | Required | Not used | Required | The code ID of the existing code to delete or update | Integer |
-| code | Not used | Required | Required | The code to create or update | 6-digit Integer without zero's |
-| enabled | Not used | Not used | Optional | Enable or disable the code, enabled if not set | 1 = enabled, 0 = disabled |
-| name | Not used | Required | Required | The name of the code to create or update | String, max 20 chars |
-| timeLimited | Not used | Optional | Optional | If this authorization is restricted to access only at certain times, disabled if not set | 1 = enabled, 0 = disabled |
-| allowedFrom | Not used | Optional | Optional | The start timestamp from which access should be allowed (requires timeLimited = 1) | "YYYY-MM-DD HH:MM:SS" |
-| allowedUntil | Not used | Optional | Optional | The end timestamp until access should be allowed (requires timeLimited = 1) | "YYYY-MM-DD HH:MM:SS" |
-| allowedWeekdays | Not used | Optional | Optional | Allowed weekdays on which access should be allowed (requires timeLimited = 1) | Array of days: "mon", "tue", "wed", "thu" , "fri" "sat", "sun" |
-| allowedFromTime | Not used | Optional | Optional | The start time per day from which access should be allowed (requires timeLimited = 1) | "HH:MM" |
-| allowedUntilTime | Not used | Optional | Optional | The end time per day until access should be allowed (requires timeLimited = 1) | "HH:MM" |
+| Node | Delete | Add | Update | Usage | Possible values |
+|------------------|----------|----------|----------|------------------------------------------------------------------------------------------------------------------|----------------------------------------|
+| action | Required | Required | Required | The action to execute | "delete", "add", "update" |
+| codeId | Required | Not used | Required | The code ID of the existing code to delete or update | Integer |
+| code | Not used | Required | Required | The code to create or update | 6-digit Integer without zero's, can't start with "12"|
+| enabled | Not used | Not used | Optional | Enable or disable the code, always enabled on add, disabled if not set on update | 1 = enabled, 0 = disabled |
+| name | Not used | Required | Required | The name of the code to create or update | String, max 20 chars |
+| timeLimited | Not used | Optional | Optional | If this authorization is restricted to access only at certain times, disabled if not set (requires enabled = 1) | 1 = enabled, 0 = disabled |
+| allowedFrom | Not used | Optional | Optional | The start timestamp from which access should be allowed (requires enabled = 1 and timeLimited = 1) | "YYYY-MM-DD HH:MM:SS" |
+| allowedUntil | Not used | Optional | Optional | The end timestamp until access should be allowed (requires enabled = 1 and timeLimited = 1) | "YYYY-MM-DD HH:MM:SS" |
+| allowedWeekdays | Not used | Optional | Optional | Weekdays on which access should be allowed (requires enabled = 1 and timeLimited = 1) | Array of days: "mon", "tue", "wed", "thu" , "fri" "sat", "sun"|
+| allowedFromTime | Not used | Optional | Optional | The start time per day from which access should be allowed (requires enabled = 1 and timeLimited = 1) | "HH:MM" |
+| allowedUntilTime | Not used | Optional | Optional | The end time per day until access should be allowed (requires enabled = 1 and timeLimited = 1) | "HH:MM" |
-Example usage:
Examples:
- Delete: `{ "action": "delete", "codeId": "1234" }`
- Add: `{ "action": "add", "code": "589472", "name": "Test", "timeLimited": "1", "allowedFrom": "2024-04-12 10:00:00", "allowedUntil": "2034-04-12 10:00:00", "allowedWeekdays": [ "wed", "thu", "fri" ], "allowedFromTime": "08:00", "allowedUntilTime": "16:00" }`
@@ -358,6 +470,7 @@ If a keypad is connected to the lock, keypad codes can be added, updated and rem
This has to enabled first in the configuration portal. Check "Add, modify and delete keypad codes" under "Access Level Configuration" and save the configuration.
Information about codes is published under "keypad/code_x", x starting from 0 up the number of configured codes. This needs to be enabled separately by checking "Publish keypad codes information" under "Access Level Configuration" and saving the configuration.
+
For security reasons, the code itself is not published. To modify keypad codes, a command
structure is setup under keypad/command:
@@ -398,12 +511,11 @@ To change Nuki Lock/Opener time control settings set the `timecontrol/actionJson
|------------------|----------|----------|----------|------------------------------------------------------------------------------------------|----------------------------------------------------------------|
| action | Required | Required | Required | The action to execute | "delete", "add", "update" |
| entryId | Required | Not used | Required | The entry ID of the existing entry to delete or update | Integer |
-| enabled | Not used | Not used | Optional | Enable or disable the entry, enabled if not set | 1 = enabled, 0 = disabled |
-| weekdays | Not used | Optional | Optional | Weekdays on which the chosen lock action should be exectued | Array of days: "mon", "tue", "wed", "thu" , "fri" "sat", "sun" |
-| time | Not used | Required | Required | The time on which the chosen lock action should be executed | "HH:MM" |
-| lockAction | Not used | Required | Required | The lock action that should be executed on the chosen weekdays at the chosen time | For the Nuki lock: "Unlock", "Lock", "Unlatch", "LockNgo", "LockNgoUnlatch", "FullLock". For the Nuki Opener: "ActivateRTO", "DeactivateRTO", "ElectricStrikeActuation", "ActivateCM", "DeactivateCM" |
+| enabled | Not used | Not used | Optional | Enable or disable the entry, always enabled on add, disabled if not set on update | 1 = enabled, 0 = disabled |
+| weekdays | Not used | Optional | Optional | Weekdays on which the chosen lock action should be exectued (requires enabled = 1) | Array of days: "mon", "tue", "wed", "thu" , "fri" "sat", "sun" |
+| time | Not used | Required | Required | The time on which the chosen lock action should be executed (requires enabled = 1) | "HH:MM" |
+| lockAction | Not used | Required | Required | The lock action that should be executed on the chosen weekdays at the chosen time (requires enabled = 1) | For the Nuki lock: "Unlock", "Lock", "Unlatch", "LockNgo", "LockNgoUnlatch", "FullLock". For the Nuki Opener: "ActivateRTO", "DeactivateRTO", "ElectricStrikeActuation", "ActivateCM", "DeactivateCM |
-Example usage:
Examples:
- Delete: `{ "action": "delete", "entryId": "1234" }`
- Add: `{ "action": "add", "weekdays": [ "wed", "thu", "fri" ], "time": "08:00", "lockAction": "Unlock" }`
@@ -442,7 +554,7 @@ Note: The old setting "Enable control via GPIO" is removed. If you had enabled t
If you prefer to connect to the MQTT Broker via Ethernet instead of Wi-Fi, you either use one of the supported ESP32 modules (see about section above),
or wire a seperate Wiznet W5x00 Module (W5100, W5200, W5500 are supported). To use a supported module, flash the firmware, connect via Wi-Fi and
-select the correct network hardware in the MQTT and network settings section.
+select the correct network hardware in the "MQTT and Network Configuration" section.
To wire an external W5x00 module to the ESP, use this wiring scheme:
@@ -481,7 +593,7 @@ To erase the flash, use the espressif download tool and click the "Erase" button
Afterwards flash the firmware as described in the readme within the 7z file.
-Also, there are reports that ESP32 "DEVKIT1" module don't work and pairing is not possible. The reason is unknown, but if you use such a module, try a different one.
+Also, there are reports that the ESP32 "DEVKIT1" module doesn't work and pairing is not possible. The reason is unknown, but if you use such a module, try a different one.
Reported as working are:
- [M5Stack ATOM Lite](https://shop.m5stack.com/products/atom-lite-esp32-development-kit)
@@ -521,7 +633,7 @@ See the previous point, this functionality needs the correct PIN to be configure
### Using Home Assistant, it's only possible to lock or unlock the door, but not to unlatch it
-Make sure "Access level" under "Advanced Nuki Configuration" is set to "Full".
+Make sure the "Unlatch" option is checked under "Access Level Configuration".
Unlatching can be triggered using the lock.open service.