Home

Awesome

hacs_badge

Better support for Nuki devices in Home Assistant

Features:

Screenshots:

<img width="1020" alt="Screenshot 2021-10-11 at 14 02 42" src="https://user-images.githubusercontent.com/159124/136786951-d1ffdb22-637a-49c2-a1ff-43c465a03f0b.png">

Setup

{% if not installed %}

Installation:

Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.

{% endif %}

Configuration:

Open your Home Assistant instance and start setting up a new integration.

Bridge API Token:

The API token for the Nuki Bridge needs to be configured on the bridge, e.g. using the Nuki mobile app. The Home Assistant Nuki documentation explains it like this:

To add a Nuki bridge to your installation, you need to enable developer mode on your bridge and define a port and an access token. This can be achieved using the Android app or iPhone app. Go to manage my devices, and select the bridge. Within the bridge configuration turn on the HTTP API and check the details in the screen. Please note that the API token should be 6-20 characters long, even though the app allows you to set a longer one.

Web API Token:

Usage:

Devices:

The integration provides several devices and entities to Home Assistant, depending on your setup. For example:

DeviceDescription
Nuki BridgeProviding four diagnostic sensors about the state of the bridge.
Nuki LockProviding one lock entity, three state sensors and eight diagnostic sensors about the lock.
Nuki OpenerProviding one lock entity, one state sensor and five diagnostic sensors about the opener.
Nuki Web APIProviding configuration switch entities for access permissions as set in the Nuki app.

In your setup, you could have several locks, but maybe no opener, no bridge or no web API.

Entities:

Nuki Bridge:

Entity IDTypeDescription
binary_sensor.nuki_bridge_bridge_callback_setDiagnosticOn, if the integration successfully registered a callback with the bridge
binary_sensor.nuki_bridge_connectedDiagnosticOn, if the bridge is reachable via WiFi
sensor.nuki_bridge_firmware_versionDiagnosticThe current firmware version of the bridge
sensor.nuki_bridge_wifi_firmware_versionDiagnosticThe current WiFi firmware version of the bridge

Nuki Lock:

The entity IDs depend on the Nuki names of the lock. In the example below, it is Wohnung.

Entity IDTypeDescription
lock.nuki_wohnung_lockControlThe main entity to control the lock
binary_sensor.nuki_wohnung_door_openSensorShows the state of the door
binary_sensor.nuki_wohnung_lockedSensorShows the state of the lock
sensor.nuki_wohnung_door_security_stateSensorCombines the state of the door with the lock
sensor.nuki_wohnung_batteryDiagnosticShows the battery level of the lock
binary_sensor.nuki_wohnung_battery_chargingDiagnosticShows if the battery is currently charging
binary_sensor.nuki_wohnung_battery_criticalDiagnosticShows if the battery has a critical level
sensor.nuki_wohnung_door_stateDiagnosticShows the state of the door
sensor.nuki_wohnung_firmware_versionDiagnosticShows the current firmware of the lock
binary_sensor.nuki_wohnung_keypad_battery_criticalDiagnosticShows if the battery of the keypad has a critical level
sensor.nuki_wohnung_rssiDiagnosticShows the received signal strength indicator of the lock
sensor.nuki_wohnung_stateDiagnosticShows the state of the lock

Nuki Opener:

The entity IDs depend on the Nuki names of the lock. In the example below, it is Haustur.

Entity IDTypeDescription
lock.nuki_haustur_lockControlThe main entity to control the opener
binary_sensor.nuki_haustur_lockedSensorShows the state of the opener (locked or unlocked)
binary_sensor.nuki_haustur_battery_criticalDiagnosticShows if the battery has a critical level
sensor.nuki_haustur_firmware_versionDiagnosticShows the current firmware of the opener
sensor.nuki_haustur_rssiDiagnosticShows the received signal strength indicator of the opener
sensor.nuki_haustur_stateDiagnosticShows the state of the opener (e.g., rto active)

Nuki Web API:

The entity IDs depend on the authorization you have given to your devices. There will be as many switch entities as there are authorizations stored on the Nuki platform. While they are all named switch.nuki_ followed by a descriptive name, there are three different types:

TypeExample
Authorization of local devicesThe keypad, which is granted access to the lock
Authorization of access codesA code registered with the keypad
Authorization of appsAccess granted to members of the family

Services:

The integration provides the following services:

Service lock.lock

The attribute should appear as a target for the service.

Target attributeOptionalDescription
entity_idnoEntity of the relevant lock.

Service lock.unlock

The attribute should appear as a target for the service.

Target attributeOptionalDescription
entity_idnoEntity of the relevant lock.

Service lock.open

The attribute should appear as a target for the service.

Target attributeOptionalDescription
entity_idnoEntity of the relevant lock.

Service nuki_ng.bridge_reboot

Reboots the Nuki Bridge. This service has no attributes

Service nuki_ng.bridge_fwupdate

Performs a bridge software update. This service has no attributes

Service nuki_ng.bridge_delete_callback

Deletes a callback URL from the bridge callbacks list. The callbacks currently set are exposed as attributes of the 'Bridge Callback Set' entity.

The attribute should appear as a target for the service.

Service data attributeOptionalDescription
commandnoURL to delete.

Useful tips

Open/unlatch Nuki lock via UI

Even though the component supports the lock.open service and advertises support of it, Lovelace UI doesn't show any controls to trigger. This can be achieved via simple script similar to the one below:

alias: Nuki Lock Open
sequence:
  - device_id: 8d159025411a270ecb9024794bc54361
    domain: lock
    entity_id: lock.nuki_front_door_lock
    type: open
mode: single
icon: mdi:lock-open

or manually calling the service:

type: button
entity: lock.nuki_front_door_lock
tap_action:
  action: call-service
  service: lock.open
  service_data: {}
  target:
    entity_id: lock.nuki_front_door_lock
name: Nuki