SmartGanjaGarden.hardware

Nuki SmartLock 4.0 Pro

MQTT API 1.4

#LockActions

ID	smartlock	opener
1	unlock	activate rto
2	lock	deactivate rto
3	unlatch	electric strike actuation
4	lock ‘n’ go	activate continuous mode
5	lock ‘n’ go with unlatch	deactivate continuous mode
6	full lock
80	fob (without action)	fob (without action)
90	button (without action)	button (without action)

#Simple Lock Actions

Possible outcome of a simple lock action (mapping handled in the firmware of the device):

action	smartlock/knob	smartlock/handle	opener
lock	lock	lock	deactivate rto and cm
unlock	unlatch	unlock	open

#Lock States

ID	smartlock	opener
0	uncalibrated	untrained
1	locked	online
2	unlocking	-
3	unlocked	rto active
4	locking	-
5	unlatched	open
6	unlocked (lock ‘n’ go)	-
7	unlatching	opening
253	-	boot run
254	motor blocked	-
255	undefined	undefined

#Doorsensor States

ID	name
1	deactivated
2	door closed
3	door opened
4	door state unknown
5	calibrating
16	Uncalibrated
240	Tampered
255	Unknown

#Trigger

ID	name
0	system / bluetooth command
1	(reserved)
2	button
3	automatic (e.g. time control)
6	auto lock
171	HomeKit
172	MQTT

#Device Type

ID	name
0	Smart Lock
2	Opener
3	Smart Door
4	Smart Lock 3.0 (Pro)

#Modes

mode	smartlock	opener	Description
2	door mode	door mode	Operation mode after complete setup
3	-	continuous mode	Ring to Open permanently active

#Published Topics for Device States

The following topic structure is available per device and updated whenever an update to a device state occurs. In addition the “last updated” timestamp is changed with every update. The retain flag is activated with all topics and QOS = 0 is used.

Topic	Description	Example
deviceType	Nuki device type (see Device Types)	4
name	Name of the device	Home door
firmware	Current firmware version of the device	3.2.0
mode	ID of the lock mode (see Modes)	2
state	ID of the lock state (see Lock States)	1
batteryCritical	Flag indicating if the batteries of the Nuki device are at critical level	true
batteryChargeState	Value representing the current charge status in %	18
batteryCharging	Flag indicating if the batteries of the Nuki device are charging at the moment	false
keypadBatteryCritical	Flag indicating if the batteries of the paired Nuki Keypad are at critical level	false
doorsensorState	ID of the door sensor state	2
doorsensorBatteryCritical	Flag indicating if the batteries of the paired Nuki Door Sensor are at critical level	false
ringactionTimestamp	Timestamp of the last ring-action. Only for Nuki Opener.	2018-10-03T06:49:00+00:00
serverConnected	Connection state to the Nuki server.	true
timestamp	Timestamp of the retrieval of the last update	2018-10-03T06:49:00+00:00
connected	Indicates if the device is currently connected to the MQTT server or not. Uses “false” as the last will message, which will be set by the mqtt server automatically if the device disconnects.	true

#Published and Subscribed Topics for Device Control

The following topic structure allows to send commands to the device via a topic to which the device subscribes. For all messages QOS = 2 is used. The retain flag is not set.

If “Allow locking” is disabled during provisioning, the device does not subscribe to the lockAction, lock and unlock topics.

Topic	Description	Example
lockAction	ID of the desired Lock Action. Only actions 1-6 are supported.	1
lock	Set to “true” to execute the simple lock action “lock”	true
unlock	Set to “true” to execute the simple lock action “unlock”	true
commandResponse	The Nuki device publishes to this topic the return code of the last command it executed: 0 = Success 1-255 = Error code as described in the BLE API. Note: Nuki devices can only process one command at a time. If several commands are sent in parallel the commandResponses might overlap.	0
lockActionEvent	The Nuki device publishes to this topic a comma separated list whenever a lock action is about to be executed: ● LockAction ● Trigger ● Auth-ID: Auth-ID of the user ● Code-ID: ID of the Keypad code, 0 = unknown ● Auto- Unlock (0 or 1) or number of button presses (only button & fob actions) or Keypad source (0 = back key, 1 = code, 2 = fingerprint) ● Only lock actions that are attempted to be executed are reported. E.g. unsuccessful Keypad code entries or lock commands outside of a time window are not published.	Unlatch via Keypad with Auth-ID 54321 from Code-ID 12345: 3,0,54321,12345,1 Auto-Unlock via App from Auth-ID 54322: 1,0,54322,0,1 Lock’n Go via Button: 4,2,0,0,0 Button configured to “no action on double click” and pressed twice: 90,2,0,0,2 Fob with auth-id 54322 configured to “unlatch” on triple click and pressed 3x: 3,3,54322,0,3