Skip to main content

Nuki community integration, free and open source

Nuki integration for Gladys Assistant

Nuki Smart Lock, Opener and Smart Door: via Bridge, MQTT or Nuki Web.

View on GitHubAll integrations

Control your Nuki devices from Gladys: Smart Lock (all generations, 3.0 Pro, 4th generation, Ultra), Smart Door and Opener — lock, unlock, open the door, follow the batteries, the door sensor and the keypad, and react to every operation in your scenes.

Choose how Gladys talks to your Nuki devices​

The integration supports three channels. Configure at least one; you can combine them.

ChannelTypeDevicesWhat it brings
Nuki BridgeLocal (HTTP)Every Smart Lock, Smart Door and OpenerWorks without internet, Opener doorbell detection
MQTTLocal (real time)Smart Lock 3.0 Pro, 4th generation, UltraInstant updates without polling, who/how of each operation (button, keypad…)
Nuki WebCloudEvery device linked to your Nuki Web accountWho operated the lock (user name, keypad, fingerprint), activity log

When several channels reach a device, Gladys uses the local one first (MQTT, then the Bridge) and falls back to the other if it fails. Turn off Prefer the local connection in the configuration screen to use Nuki Web first. The badge on each device card shows the channel in use: Local, Cloud or Unreachable; an orange dot means Gladys had to fall back (for example: Bridge offline, Nuki Web used instead).

Setup​

Nuki Bridge (local)​

  1. In the Nuki app, open Manage Bridge and enable the HTTP API.
  2. In Gladys, open the Nuki integration configuration and click Find my Bridge: the IP address is filled in for you (or type it by hand: it is shown in the Nuki app).
  3. Click Pair the Bridge, then press the button of the Bridge within 30 seconds: the API token is saved automatically. You can also copy the token shown in the app.
  4. Keep Send the token hashed enabled (Bridge firmware 1.13 or later): the token never travels in clear on your network.

Give your Bridge a fixed IP address in your router: if it changes, run Find my Bridge again.

MQTT (local, Smart Lock 3.0 Pro / 4.0 / Ultra)​

  1. You need an MQTT broker (Mosquitto…). The one of the Gladys MQTT integration works.
  2. In the Nuki app, open the lock settings → Features & Configuration → MQTT, enable it and enter the broker IP address, port, user and password.
  3. In Gladys, fill in MQTT broker URL (e.g. mqtt://192.168.1.10:1883), user and password. The locks appear within seconds.

Nuki Web (cloud)​

  1. Enable Nuki Web for your devices in the Nuki app.
  2. On web.nuki.io, open API and generate an API token with at least the rights Smartlock, Smartlock action and Smartlock log.
  3. Paste it in Nuki Web API token.

Create the devices​

Open the Discovery tab of the integration and create the devices you want. If you later pair a door sensor or a keypad, the Discovery tab offers to update the device.

Options​

  • Refresh interval: how often the Bridge is read (10 s minimum, 30 s by default). Nuki Web is read at most every 30 seconds, and only when needed. MQTT needs no polling.
  • When Gladys unlocks: Unlock only (default) or Unlock and open the door (unlatch).
  • When Gladys locks: Lock (default) or Full lock (two turns, Smart Lock 3.0 and later; a plain lock on older models).

Devices and features​

Smart Lock / Smart Door

FeatureDescription
LockSwitch: 1 = locked, 0 = unlocked (controls the lock)
Lock stateLocked / unlocked / moving / error
BatteryCharge level in %
Battery lowCritical battery alert
ChargingPower pack charging (3.0 and later)
DoorOpen / closed (if a door sensor is paired)
Door sensor battery low(if a door sensor is paired)
Keypad battery low(if a keypad is paired)

Opener: Ring to Open and Continuous mode switches, Battery low, and Doorbell (ring detection, through the Bridge).

Scenes​

Triggers​

  • Nuki lock operated — a lock was locked, unlocked, opened or used Lock 'n' Go. Filter on the lock, the operation, how it was operated (app, by hand, button, keypad, fingerprint, auto lock, Nuki Web, HomeKit, MQTT, Gladys…) and the Nuki user (with Nuki Web). Variables: action, trigger, user, device_name. Example: "when Alice unlocks the front door with the keypad, turn off the alarm".
  • Nuki Opener: doorbell rang — someone rang the intercom (Opener with a Bridge).
  • Nuki lock problem — motor blocked, lock uncalibrated, or a command refused.
  • Nuki battery critical — the battery of a lock, Opener, keypad or door sensor is low.

Operations started by Gladys itself are reported with the trigger gladys: exclude it in the filter to avoid a scene reacting to its own actions.

Actions​

  • Operate a Nuki lock — lock, unlock, open the door, Lock 'n' Go, full lock. Output: success.
  • Operate a Nuki Opener — buzz the door, Ring to Open on/off, continuous mode on/off. Output: success.
  • Read a Nuki device — outputs locked, state, door_open, battery, battery_critical, reachable, to use in the following actions (e.g. send a message "the door is still unlocked").
  • Lock every Nuki lock — outputs locked_count and failed_count.

The standard Gladys "device state" trigger also works on every feature (door opened, battery below 20 %…).

Dashboard widgets​

  • Nuki lock — one lock or Opener: state, live battery, door, accessories, channel, last activity, and Lock / Unlock / Open door buttons (the door opening asks for confirmation). For an Opener: Open and Ring to Open.
  • Nuki overview — every Nuki device at a glance and a Lock all button.
  • Nuki activity — the latest operations: who, how and when (from Nuki Web when configured, otherwise from what the integration saw).

Troubleshooting​

  • "Nuki Bridge refused the API token": pair the Bridge again, or turn off Send the token hashed if your Bridge firmware is older than 1.13.
  • "Nuki Bridge unreachable": check the IP address, and that the HTTP API is enabled. The Bridge handles one request at a time: avoid other software polling it too often.
  • MQTT: no lock appears: check in the Nuki app that MQTT is connected, that the lock uses the broker IP address, and that Gladys uses the same broker.
  • No user name in the triggers: user names come from Nuki Web; add an API token.
  • The Test the connection button checks every configured channel and tells what works.

Privacy and security​

Tokens and passwords are stored by Gladys as secrets and never written to the logs. The Bridge token is sent hashed by default. Nuki Web is only contacted when you configure an API token. The activity history is kept in the integration's own data volume.

Configuration settings​

These are the settings Nuki asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Connect your Nuki devicessectionNoFill in at least one of the three channels below. The Bridge and MQTT are local (fast, work without internet); Nuki Web is the cloud and also tells who operated the lock. You can combine them: Gladys uses the local one first and falls back to the other (see “Prefer the local connection”).
Nuki Bridge (local)sectionNoIn the Nuki app, open the Bridge settings and enable the HTTP API. Then use “Find my Bridge” and “Pair the Bridge” below (press the Bridge button when asked), or copy the IP address and the API token shown by the app.
Bridge IP addressstringNo
Bridge portnumberNo
Bridge API tokensecretNoFilled in automatically by “Pair the Bridge”.
Send the token hashedbooleanNoRecommended: the token never travels in clear on your network. Turn off only for a Bridge firmware older than 1.13.
MQTT (local, real time)sectionNoFor the Smart Lock 3.0 Pro, 4th generation and Ultra: in the Nuki app, enable MQTT and point the lock to your broker (use its IP address). Enter the same broker here. Changes arrive instantly, without polling.
MQTT broker URLstringNo
MQTT usernamestringNo
MQTT passwordsecretNo
Nuki Web (cloud)sectionNoEnable Nuki Web in the Nuki app, then on web.nuki.io open “API” and generate an API token with the smartlock, smartlock action and log permissions. Nuki Web also tells who locked or unlocked (user, keypad, fingerprint...).
Nuki Web API tokensecretNo
OptionssectionNoHow often the Bridge and Nuki Web are read (MQTT needs no polling), and what the lock switch of Gladys does.
Refresh interval (s)numberNoSeconds between two reads of the Bridge (10 minimum). Nuki Web is never read more often than every 30 seconds.
When Gladys unlocksselectNo
When Gladys locksselectNo

How to install Nuki in Gladys​

  1. In Gladys, open Integrations: Nuki appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/gboulvin/gladys-nuki:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/gboulvin/Gladys-Nuki.

Nuki requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Nuki is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by gboulvin, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on