Better support for Nuki devices in Home Assistant

Features:

• Supported modes:
  • Nuki Bridge-only, with automatic webhook registration
  • Cloud Web API, without Nuki bridge (Nuki Lock 3.0 Pro). Polling only
  • Hybrid, using best parts of both
• Exposes the detailed device information via sensors
• If supported, enables access control to Nuki authorization objects (keypad codes, accounts)

Screenshots:

Setup

{% if not installed %}

Installation:

• Go to HACS -> Integrations
• Click the three dots on the top right and select Custom Repositories
• Enter https://github.com/kvj/hass_nuki_ng as repository, select the category Integration and click Add
• A new custom integration shows up for installation (Nuki Lock) - install it
• Restart Home Assistant

{% endif %}

Configuration:

• Go to Configuration -> Integrations
• Click Add Integration
• Search for Nuki Lock (not just Nuki, as this is the native integration from Home Assistant) and select it
• The integration will try to automatically discover your Nuki Bridge hostname or IP address, if you have a bridge
• It will also automatically enter the Home Assistant internal URL
• Provide either the Bridge API token and URL and/or a web API token and click Submit
• You can provide both, but you need to provide at least one

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:

• Go to the Nuki Web API management site at https://web.nuki.io/
• Nuki Web needs to be activated in the Nuki app - there is a link on the site that tells you how to do that
• Once activated, login on the web
• In the menu on the left, select API
• Click Generate API token
• Give it a name, leave the other settings as they are and click Save
• Copy the token and save it in a secure place. It will only be shown this once to you.

Usage:

Devices:

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

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

Entities:

Nuki Bridge:

Nuki Lock:

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

Nuki Opener:

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

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:

Services:

The integration provides the following services:

Service lock.lock

• For a Nuki Lock, this locks the door
• For a Nuki Opener, this stops an active ring-to-open function

The attribute should appear as a target for the service.

Service lock.unlock

• For a Nuki Lock, this unlocks the door
• For a Nuki Opener, this starts the ring-to-open function

The attribute should appear as a target for the service.

Service lock.open

• For a Nuki Lock, this unlatches the door
• For a Nuki Opener, this buzzes the door open

The attribute should appear as a target for the service.

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.

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