If you have a Nuki Lock system, and you are not satisfied by the official integration, here’s a way to overcome all the current limitations and monitor/operate the Nuki in a better way.
I know devs are working on the official integration to implement some of the things you’ll find in this configuration, but since I wanted to learn HA better, I decided to start doing this for the Nuki.
Main Features of this card:
- doesn’t require the official integration
- lock device support through bridge callback (fast updates, 10-15s)
- door sensor support through bridge callback (fast updates, 10-15s)
- ALL Nuki info mapped to sensors (polling via 2 REST sensors)
- Dynamic state icons (battery state and type, lock, door, etc.)
- Easy configuration - it only requires 4 items in secrets.yaml
- Automatic Bridge Callback Configuration and Enforcement (add/delete duplicate entries) with HA persistent notification of the actions
-= Nuki Card v8 =-
- v3.0 added the Door sensor and Nuki Lock switch based on callbacks.
- v3.1 changed the lock entity from
- v4.0 changed all legacy state sensors to the new Template State Sensors and recoded the Door Sensor to be ready for multiple triggers (not yet completed, it will allow to overcome the problem mentioned in the following note.
- v4.1 fixed some bugs in templates.yaml (if you configured v4.0, you just need to reconfigure templates.yaml)
- v4.2 fixed other minor things in templates.yaml (if you configured v4.1, you just need to reconfigure templates.yaml)
- v4.3 fixed some code in the trigger door sensor (if you configured v4.2, you just need to reconfigure templates.yaml)
- v4.4 fixed some code in several sensors (if you configured v4.3, you just need to reconfigure templates.yaml) that finally solved the problem of the initialization after a restart. thx to @Friedrieck and @123 for the advices and the debugging
- v4.5 fixed some nasty bugs introduced in 4.4 and updated icons for door/lock polled sensors (if you configured v4.4, you just need to reconfigure templates.yaml)
- v4.6 finally solved the HA restart issue, using a
state triggerto link the door triggered sensor to the polled state sensor. (if you configured v4.5, you just need to reconfigure templates.yaml)
- v4.7 removed homeassistant/start event from the door triggered sensor, added content_type to the rest_command, modified icon of device name sensor, moved door/lock polled sensors to attributes of the door triggered sensor - updated files:
- v5.0 reworked all sensors to avoid log errors at startup while REST sensors were not initialized yet - updated files:
- v5.1 modified rest_command (removed content_type) and keypad sensor to avoid log errors at startup for users without the keypad - updated files:
- v6.0 Automation version in package (supereasy installation)
- v7.0 automated bridge callback configuration and enforcement (with persistent notification) (super-super-easy installation), optimized some code, renamed some sensors, unified nuki secrets url variables
- v8.0 (major release): rewrote many parts of the package, optimized the code, and fixed 2 bugs regarding the automatic bridge configuration. Now the reconfiguration of the bridge should be much quicker (1m max.).
- v8.1 last minute minor changes
- v8.2 couple of bugs fixed, automation settings changed (thanks @spokin)
- v8.3 optimized automation settings and added checks everywhere a sensor was referenced in the code to avoid as much as possible errors in HA log, mainly in init/restart phase.
- v8.4 reconfigured automation mode and rest sensors polling times to avoid concurrent calls to the bridge
- v8.5 changed lock actions to Simple Lock Actions (thanks @kvj), device configuration driven, so if you configured the lock with a knob (instead of a handle) it will unlatch instead of simply unlocking. Min. bridge fw required: v2.5.3.
- v8.6 further optimized the code to avoid concurrent http requests to the bridge, that is poorly designed, supporting only 1 request at a time
- v8.7 localization support by @spokin (just use input_select.nuki_language to configure it). Removed the duplicated door/lock polling sensors. Relaxed the REST sensors polling periods even further. Lot of optimizations to the code. Please re-edit the lovelace card, as sensor names have changed.
- v8.8 typo in json file corrected, reference to an old binary_sensor corrected in the code.
Now let’s go to the configuration of the card.
- the code is based on Nuki Bridge API v1.12, make sure the bridge fw is updated to last available version before starting the configuration of this integration. min. version supported: v2.5.3
- Nuki Bridge doesn’t support https, so if you have HA secured with https-only, you need to allow http access locally (LAN/WLAN access, you can leave https from the internet). The NGINX HA addon allows this kind of configuration.
- 1st step is the creation of a long-lived token in HA profile’s page, used for the callback’s webhook. Create it and take note of it.
NOTE: Please don’t confuse the Nuki access token with the HA long-term token for the webhook, the first is needed by HA to communicate with the Nuki Bridge API, the second is needed by the Nuki Bridge to communicate with HA
secrets.yamlyou need to configure 4 items: Nuki Bridge full url path, Bridge API token you create through Nuki App or the web console, long-lived token (webhook) you created in the first step, HA full url path.
nuki_bridge_url: "http://nuki-bridge.axel.dom:8080" nuki_bridge_token: "yyxxzz" nuki_bridge_webhook: "hdCI6MTYyMTcyODg0MSwiZXhwIjoxOTM3MDg4ODQxfQ.-ECrJx_lbPLRRJwRTfJsoW-RfIaIioKVtcyfEvJiHZE" nuki_ha_internal_url: "http://hass.axel.dom:8123"
in previous versions (up to 6.1), you had to configure the callback on the bridge manually through curl or browser. this is no longer the case, v7.0 introduces automatic callback configuration/enforcement of the bridge. It does this through a script and a couple of new sensors, one of which (
sensor.nuki_bridge_callback_list) is configured to check the bridge callback config every 120s. Another sensor (
binary_sensor.nuki_bridge_callback) checks if the bridge config contains our specific webhook, and if not, it calls
script.nuki_bridge_check_callback, generating a persistent notification so you can be alerted of the change (see screenshots above).
create a folder called
packagesin the main CONFIG folder, and in that folder create two files called
nuki_card_callback_languages.json, you can download them here or copy the code from it, whatever way you prefer: Nuki Card v8.8 · GitHub
in configuration.yaml, under the
homeassistant:section, reference the directory containing all packages:
- and finally the code for the card, I included all sensors created, customize the list as you prefer. If you don’t have the Nuki Keypad, remove that line.
- type: entities entities: - entity: lock.nuki_lock_action secondary_info: last-updated - entity: sensor.nuki_door_sensor_state secondary_info: last-updated - entity: binary_sensor.nuki_bridge_callback secondary_info: last-updated - entity: sensor.nuki_last_activity - entity: input_select.nuki_language - entity: sensor.nuki_id - entity: sensor.nuki_friendly_name - entity: sensor.nuki_device_name - entity: sensor.nuki_bridge_lock_bt_state - entity: sensor.nuki_bridge_lock_bt_rssi - entity: sensor.nuki_lock_battery_level - entity: sensor.nuki_lock_fw_version - entity: sensor.nuki_bridge_fw_version - entity: sensor.nuki_bridge_wifi_fw_version - entity: sensor.nuki_bridge_wifi_connected - entity: sensor.nuki_bridge_cloud_connected - entity: sensor.nuki_lock_battery_critical_state - entity: sensor.nuki_keypad_battery_critical_state state_color: true title: Nuki Card