Nuki Local

Local MQTT integration for Nuki Smart Locks

Current Release
0.1.3
Developer
helfi9999
License
MIT

Local Nuki Smart Lock integration for ioBroker using an integrated MQTT broker.

Manufacturer and product information: Nuki.

The adapter is designed for direct local communication with compatible Nuki Smart Locks over MQTT. Optionally, the Nuki Web API can be enabled to enrich the local MQTT data with authorization names and activity information.

Features

  • Integrated MQTT broker
  • Local communication with Nuki Smart Locks
  • No separate MQTT broker required
  • MQTT authentication with username and password
  • Persistent retained MQTT data using LevelDB
  • Automatic restore of retained Nuki states after adapter restart
  • Automatic device creation
  • Lock status
  • Door sensor status
  • Battery information
  • Firmware information
  • Device type
  • Online status
  • Lock / unlock / unlatch commands
  • Lock'n'Go commands
  • Fingerprint detection
  • Keypad code detection
  • Configurable Code-ID to user-name mapping
  • Optional Nuki Web API integration
  • Activity information
  • Dynamic status icons
  • Local operation remains available even when the Nuki Web API is disabled

Installation

Install the adapter from the ioBroker Admin interface once it is available in the ioBroker repository.

MQTT configuration

Default MQTT port:

1883

Default MQTT username:

nuki

Configure the same MQTT username and password in the Nuki app.

Use the IP address of the ioBroker server as MQTT broker.

Example:

Broker: 192.168.178.124
Port: 1883
Username: nuki
Password: your configured password

MQTT persistence

Retained MQTT states are stored using LevelDB.

Example persistence directory:

/opt/iobroker/iobroker-data/nuki-local.0/mqtt-leveldb

The adapter restores retained Nuki states automatically after a restart.

Object structure

Each Nuki device is created below:

nuki-local.0.<NUKI-ID>

Structure:

<NUKI-ID>
├── activity
├── advanced
├── battery
├── commands
├── device
├── keypad
├── status
└── raw

Status

Available states include:

status.lockState
status.lockStateText
status.locked
status.doorState
status.doorStateText
status.doorOpen
status.timestamp
status.iconState
status.icon

Battery

battery.percent
battery.critical
battery.charging
battery.keypadCritical
battery.doorSensorCritical

Device information

device.name
device.firmware
device.deviceType
device.mode
device.online

Commands

Commands are available below:

nuki-local.0.<NUKI-ID>.commands

Lock

commands.lock

Internally:

lockAction = 2

Unlock

commands.unlock

Internally:

lockAction = 1

This unlocks the lock without intentionally pulling the latch.

Unlatch

commands.unlatch

Internally:

lockAction = 3

Lock'n'Go

commands.lockNgo

Internally:

lockAction = 4

Lock'n'Go with unlatch

commands.lockNgoUnlatch

Internally:

lockAction = 5

Full lock

commands.fullLock

Internally:

lockAction = 6

Keypad and fingerprint

The adapter processes lockActionEvent messages.

Example:

3,0,195249,8193,2

Fields:

action
trigger
authId
codeId
source

Keypad source:

0 = Back button
1 = Keypad code
2 = Fingerprint

Relevant ioBroker states:

keypad.lastType
keypad.lastUser
keypad.lastTimestamp

Configurable keypad users

Users can map a Nuki codeId to a custom name in the adapter configuration.

Example:

Code ID   Name
8193      User 1
8192      User 2

The names are not hard-coded into the adapter.

Resolution priority:

1. Configured Code-ID mapping
2. Nuki Web API authorization name
3. Technical fallback

Activity

activity.lastAction
activity.lastActionText
activity.lastUser
activity.lastDate

Advanced data

advanced.authId
advanced.codeId
advanced.source
advanced.trigger
advanced.smartlockId
advanced.serverState
advanced.authorizations

Raw MQTT data

Unknown MQTT topics are stored below:

raw

This helps with debugging and future topic support.

Nuki Web API

The Web API integration is optional.

MQTT remains the primary local communication method.

The Web API can provide additional information such as:

  • authorization names
  • activity logs
  • cloud-side device information

The adapter continues operating locally if the Web API is unavailable.

Dynamic icons

Available states:

status.iconState
status.icon

Possible values:

locked
unlocked
door_open
door_closed
charging
pairing
unknown

Icon files are stored under:

admin/icons/Nuki_Vis/

Files:

nuki_locked.png
nuki_unlocked.png
nuki_door_open.png
nuki_door_closed.png
nuki_charging.png
nuki_pairing.png
nuki_unknown.png

Example icon path:

/adapter/nuki-local/icons/Nuki_Vis/nuki_locked.png

Security

Use a strong MQTT password.

Do not expose the integrated MQTT broker directly to the public internet.

Treat the Nuki Web API token as a secret.

Keypad PIN codes are intentionally not stored by the adapter.

Troubleshooting

Show adapter logs:

iobroker logs nuki-local.0 --watch

Upload adapter files:

iobroker upload nuki-local

Restart:

iobroker restart nuki-local.0

Changelog

0.1.3 (2026-10-04)

  • (helfi9999) Replaced the default adapter icon with a custom Nuki icon.

  • (helfi9999) Limited the Web API polling interval to 60–86400 seconds and prevented overlapping updates.

  • (helfi9999) Corrected access and activity date roles and removed an unused translation key.

  • (helfi9999) Reset the code ID when importing Web API activity data.

  • (helfi9999) Changed state texts to English and completed configuration label translations.

  • (helfi9999) Corrected command button, authorization JSON and timestamp roles.

  • (helfi9999) Added a Web API request timeout and MQTT device ID validation.

  • (helfi9999) Updated Aedes, Node.js types, testing tools and transitive dependencies.

  • (helfi9999) Added Node.js 26 testing and updated the workflow check action.

  • (helfi9999) Updated documentation, keywords and maintainer contact information.

  • (helfi9999) Adapter requires admin >= 7.8.23 now.

0.1.2

  • Improved publishing workflow
  • Added npm trusted publishing support
  • Updated package metadata and repository checks

0.1.0

Initial functional development version.

  • Integrated MQTT broker
  • MQTT authentication
  • LevelDB persistence
  • Retained state restore
  • Smart Lock status
  • Door sensor support
  • Battery information
  • Explicit lock actions
  • Keypad code detection
  • Fingerprint detection
  • Configurable Code-ID user mapping
  • Optional Nuki Web API
  • Activity information
  • Dynamic status icons

License

MIT License

Copyright (c) 2026 helfi9999 helfi9999@gmail.com