Skip to content

Commit 9322d21

Browse files
hcarter-775claude
andauthored
zigbee-lock: support programmingUser typed entries (#3332)
Represent the Zigbee master code pins as a programmingUser, keep it across delete-all, refuse to delete these kinds of codes, refuse to create these kinds of codes, and promote reported codes to master when the lock says so. A user cannot be changed to or from the programmingUser type via updateUser, and auto-assigned credentials start at index 1 so they never claim the master slot. Move Yale-specific handling into its own sub-driver, which normalizes Yale's misreported user ids. Extend the lockCodes migration to take the known master code slot (0 for Yale) and always migrate it as a programming user. --------- Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
1 parent e325599 commit 9322d21

21 files changed

Lines changed: 851 additions & 43 deletions

‎drivers/SmartThings/zigbee-lock/src/legacy-handlers/migrate.lua‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,9 @@ local LockUsers = capabilities.lockUsers
1212
local LockCredentials = capabilities.lockCredentials
1313

1414
-- Migrate lockCodes state to lockUsers/lockCredentials.
15-
return function(driver, device, command)
15+
-- `programming_code_slot` is the user_id, if any, known to hold a master code on this device. It is migrated
16+
-- as a programmingUser user rather than a guest.
17+
return function(driver, device, command, programming_code_slot)
1618
-- set supported credentials
1719
device:emit_event(LockCredentials.supportedCredentials({ post_migration_consts.CRED_TYPE_PIN }, { visibility = { displayed = false } }))
1820

@@ -43,14 +45,21 @@ return function(driver, device, command)
4345
for code_slot_str, _ in pairs(cached_lock_codes) do
4446
local code_slot = tonumber(code_slot_str)
4547
-- Slots that are not valid credential indices are dropped rather than migrated.
46-
if math.type(code_slot) == "integer" and code_slot >= min_credential then
48+
if code_slot and math.type(code_slot) == "integer" and code_slot >= min_credential then
4749
table.insert(ordered_code_slots, code_slot)
4850
if code_slot >= min_user then occupied_user_indices[code_slot] = true end
4951
else
5052
device.log.warn(string.format("migrate: dropping lockCodes slot %q, not a valid credential index", tostring(code_slot_str)))
5153
end
5254
end
5355

56+
-- A passed-in programming user code slot should always be migrated, even if it is not among the known codes.
57+
if math.type(programming_code_slot) == "integer" and programming_code_slot >= min_credential
58+
and cached_lock_codes[tostring(programming_code_slot)] == nil then
59+
cached_lock_codes[tostring(programming_code_slot)] = post_migration_consts.PROGRAMMING_USER.DEFAULT_NAME
60+
table.insert(ordered_code_slots, programming_code_slot)
61+
if programming_code_slot >= min_user then occupied_user_indices[programming_code_slot] = true end
62+
end
5463
table.sort(ordered_code_slots)
5564
local next_free_user_index = min_user
5665
for _, code_slot in ipairs(ordered_code_slots) do
@@ -64,7 +73,8 @@ return function(driver, device, command)
6473
occupied_user_indices[user_index] = true
6574
end
6675
-- cached_lock_codes is formatted as { ["1"] = "Guest 1", ["2"] = "Guest 2" }, etc
67-
table.insert(users, { userIndex = user_index, userType = "guest", userName = code_name })
76+
local user_type = code_slot == programming_code_slot and post_migration_consts.PROGRAMMING_USER.USER_TYPE or "guest"
77+
table.insert(users, { userIndex = user_index, userType = user_type, userName = code_name })
6878
table.insert(credentials, { userIndex = user_index, credentialIndex = code_slot, credentialType = post_migration_consts.CRED_TYPE_PIN, credentialName = code_name })
6979
end
7080
-- manually ensure user/cred state is persisted, then emit events to populate the new capabilities with the migrated data.

‎drivers/SmartThings/zigbee-lock/src/legacy-handlers/yale-fingerprint-lock/can_handle.lua‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
-- Licensed under the Apache License, Version 2.0
33

44
return function(opts, driver, device)
5-
local fingerprints = require("yale-fingerprint-lock.fingerprints")
5+
local fingerprints = require("yale.yale-fingerprint-lock.fingerprints")
66
for _, fingerprint in ipairs(fingerprints) do
77
if device:get_manufacturer() == fingerprint.mfr and device:get_model() == fingerprint.model then
88
local subdriver = require("legacy-handlers.yale-fingerprint-lock")

‎drivers/SmartThings/zigbee-lock/src/legacy-handlers/yale/init.lua‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,10 @@ local get_pin_response_handler = function(driver, device, zb_mess)
127127
end
128128
end
129129

130+
local migrate = function(driver, device, command)
131+
require("legacy-handlers.migrate")(driver, device, command, 0)
132+
end
133+
130134
local yale_door_lock_driver = {
131135
NAME = "Yale Door Lock",
132136
zigbee_handlers = {
@@ -139,7 +143,8 @@ local yale_door_lock_driver = {
139143
capability_handlers = {
140144
[LockCodes.ID] = {
141145
[LockCodes.commands.reloadAllCodes.NAME] = reload_all_codes,
142-
[LockCodes.commands.setCode.NAME] = set_code
146+
[LockCodes.commands.setCode.NAME] = set_code,
147+
[LockCodes.commands.migrate.NAME] = migrate
143148
}
144149
},
145150
can_handle = require("legacy-handlers.yale.can_handle")

‎drivers/SmartThings/zigbee-lock/src/lock_handlers/capabilities.lua‎

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,12 @@ function CapabilityHandlers.add_user(driver, device, command)
3535
return
3636
end
3737

38+
-- programming users cannot be created through the capability
39+
if command.args.userType == consts.PROGRAMMING_USER.USER_TYPE then
40+
lock_utils.emit_command_result(device, capabilities.lockUsers, consts.LOCK_USERS.ADD, consts.COMMAND_RESULT.INVALID_COMMAND)
41+
return
42+
end
43+
3844
-- Find the smallest positive userIndex not already in the table
3945
local next_available_index = tables.next_index(device, "users")
4046
local status = tables.add_entry(device, "users", {
@@ -52,6 +58,12 @@ function CapabilityHandlers.update_user(driver, device, command)
5258
return
5359
end
5460

61+
-- a user cannot be made a programming user, and a programming user cannot be changed to another type
62+
if (command.args.userType == consts.PROGRAMMING_USER.USER_TYPE) ~= lock_utils.is_programming_user(device, command.args.userIndex) then
63+
lock_utils.emit_command_result(device, capabilities.lockUsers, consts.LOCK_USERS.UPDATE, consts.COMMAND_RESULT.INVALID_COMMAND)
64+
return
65+
end
66+
5567
local result_status
5668
if not tables.find_entry(device, "users", command.args.userIndex) then
5769
result_status = tables.add_entry(device, "users", {
@@ -130,8 +142,11 @@ function CapabilityHandlers.add_credential(driver, device, command)
130142
-- userIndex 0 means "create a new user for this credential" (its index is chosen when the lock confirms the
131143
-- code). Any other userIndex must name an existing user that does not already have a credential (for now,
132144
-- each user may have at most one credential).
145+
-- A programming user cannot be created or given a credential through the capability.
133146
local user_index = command.args.userIndex
134-
if user_index ~= 0 and (not tables.find_entry(device, "users", user_index)
147+
if command.args.userType == consts.PROGRAMMING_USER.USER_TYPE
148+
or user_index ~= 0 and (not tables.find_entry(device, "users", user_index)
149+
or lock_utils.is_programming_user(device, user_index)
135150
or tables.find_entry_by(device, "credentials", "userIndex", user_index)) then
136151
lock_utils.emit_command_result(device, capabilities.lockCredentials, consts.LOCK_CREDENTIALS.ADD, consts.COMMAND_RESULT.INVALID_COMMAND)
137152
return
@@ -190,17 +205,33 @@ function CapabilityHandlers.update_credential(driver, device, command)
190205
device:send(LockCluster.server.commands.SetPINCode(device,
191206
command.args.credentialIndex,
192207
UserStatusEnum.OCCUPIED_ENABLED,
193-
UserTypeEnum.UNRESTRICTED,
208+
-- the credential's stored owner decides its type, so a known programming code stays a programming code
209+
lock_utils.is_programming_user(device, existing.userIndex) and UserTypeEnum.MASTER_USER or UserTypeEnum.UNRESTRICTED,
194210
command.args.credentialData)
195211
)
196212
end
197213

214+
-- Some locks report a successful ClearPINCode for a programming code but do not actually delete it,
215+
-- so refuse rather than dropping the credential from our tables.
216+
local function refuse_programming_credential_delete(device, injected_by_delete_user)
217+
device.log.warn("ignoring deleteCredential for a programming code, it cannot be deleted")
218+
if injected_by_delete_user then
219+
lock_utils.emit_command_result(device, capabilities.lockUsers, consts.LOCK_USERS.DELETE, consts.COMMAND_RESULT.FAILURE)
220+
lock_utils.clear_busy_state(device)
221+
end
222+
lock_utils.emit_command_result(device, capabilities.lockCredentials, consts.LOCK_CREDENTIALS.DELETE, consts.COMMAND_RESULT.FAILURE)
223+
end
224+
198225
function CapabilityHandlers.delete_credential(driver, device, command)
199226
local cmd_in_progress = device:get_field(consts.DRIVER_STATE.COMMAND_IN_PROGRESS)
200227

201228
if cmd_in_progress == consts.LOCK_USERS.DELETE then
202229
-- Injected by deleteUser; busy state was already set with the full LOCK_USERS.DELETE context.
203230
local credential_args = device:get_field(consts.DRIVER_STATE.CREDENTIAL_ARGS_IN_USE) or {}
231+
if lock_utils.is_programming_user(device, credential_args.userIndex) then
232+
refuse_programming_credential_delete(device, true)
233+
return
234+
end
204235
device:send(LockCluster.attributes.SendPINOverTheAir:write(device, true))
205236
device:send(LockCluster.server.commands.ClearPINCode(device, credential_args.credentialIndex))
206237
elseif lock_utils.is_device_busy(device) then
@@ -212,6 +243,10 @@ function CapabilityHandlers.delete_credential(driver, device, command)
212243
lock_utils.emit_command_result(device, capabilities.lockCredentials, consts.LOCK_CREDENTIALS.DELETE, consts.COMMAND_RESULT.FAILURE)
213244
return
214245
end
246+
if lock_utils.is_programming_user(device, found_cred.userIndex) then
247+
refuse_programming_credential_delete(device, false)
248+
return
249+
end
215250
lock_utils.set_busy_state(device, consts.LOCK_CREDENTIALS.DELETE, {
216251
credentialIndex = command.args.credentialIndex,
217252
credentialType = command.args.credentialType,

‎drivers/SmartThings/zigbee-lock/src/lock_handlers/zigbee_responses.lua‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -71,11 +71,12 @@ function ZigbeeHandlers.clear_all_pin_codes_response(driver, device, zb_rx)
7171
-- apply result and identify command result statuses
7272
local user_status, credential_status
7373
if clear_pin_code_status == ResponseStatus.PASS then
74+
-- The lock keeps programming codes when clearing all PINs, so keep them locally too.
7475
-- Only clear the users table when this response is for a deleteAllUsers flow.
7576
if command_in_progress == consts.LOCK_USERS.DELETE_ALL then
76-
user_status = tables.delete_all_entries(device, "users")
77+
user_status = lock_utils.delete_all_non_programming_users(device)
7778
end
78-
credential_status = tables.delete_all_entries(device, "credentials")
79+
credential_status = lock_utils.delete_all_non_programming_credentials(device)
7980
elseif clear_pin_code_status == ResponseStatus.FAIL then
8081
user_status = consts.COMMAND_RESULT.FAILURE
8182
credential_status = consts.COMMAND_RESULT.FAILURE
@@ -143,14 +144,15 @@ function ZigbeeHandlers.get_pin_code_response(driver, device, zb_rx)
143144
if command_in_progress == consts.SYNC.CODES_FROM_LOCK then
144145
-- Only add entries for slots that are actually occupied on the lock.
145146
local occupied = zb_rx.body.zcl_body.user_status.value == clusters.DoorLock.types.DrlkUserStatus.OCCUPIED_ENABLED
147+
local is_programming_code = zb_rx.body.zcl_body.user_type.value == clusters.DoorLock.types.DrlkUserType.MASTER_USER
146148
if user_id < device:get_field(consts.SYNC.CODE_INDEX) then
147149
device.log.warn_with({ hub_logs = true }, "GetPINCodeResponse for index %s already processed, expected %s", user_id, device:get_field(consts.SYNC.CODE_INDEX))
148150
return -- return early if we've already processed this response.
149151
elseif user_id ~= device:get_field(consts.SYNC.CODE_INDEX) then
150152
device.log.warn_with({ hub_logs = true }, "Unexpected GetPINCodeResponse for index %s, expected %s", user_id, device:get_field(consts.SYNC.CODE_INDEX))
151153
occupied = false -- treat this as an unoccupied slot to continue the sync
152154
end
153-
lock_utils.continue_code_sync(device, occupied, false)
155+
lock_utils.continue_code_sync(device, occupied, false, is_programming_code)
154156
end
155157
end
156158

@@ -179,12 +181,6 @@ function ZigbeeHandlers.programming_event_notification(driver, device, zb_rx)
179181
local user_id = tonumber(zb_rx.body.zcl_body.user_id.value)
180182
local event_code = tonumber(zb_rx.body.zcl_body.program_event_code.value)
181183

182-
if device:get_manufacturer() == "ASSA ABLOY iRevo" or device:get_manufacturer() == "Yale" then
183-
if user_id >= 256 then -- Index is incorrectly written on these devices. Attempt to shift it to get an actual value
184-
user_id = user_id >> 8
185-
end
186-
end
187-
188184
local ProgramEventCode = clusters.DoorLock.types.ProgramEventCode
189185
-- MASTER_CODE_CHANGED = 1
190186
-- PIN_CODE_ADDED = 2
@@ -218,7 +214,8 @@ function ZigbeeHandlers.programming_event_notification(driver, device, zb_rx)
218214
command_in_progress = consts.LOCK_CREDENTIALS.DELETE -- ensure the lockCredentials result is emitted after this with the correct command context
219215
end
220216
end
221-
elseif event_code == ProgramEventCode.PIN_CODE_CHANGED and command_in_progress == consts.LOCK_CREDENTIALS.UPDATE then
217+
elseif (event_code == ProgramEventCode.PIN_CODE_CHANGED or event_code == ProgramEventCode.MASTER_CODE_CHANGED)
218+
and command_in_progress == consts.LOCK_CREDENTIALS.UPDATE then
222219
result_status, user_index = lock_utils.apply_commanded_credential(device, command_in_progress, credential_args_in_use)
223220
end
224221

@@ -235,9 +232,12 @@ function ZigbeeHandlers.programming_event_notification(driver, device, zb_rx)
235232
end
236233

237234
-- handle the case where we receive a programming event notification for a code we didn't send a command for
238-
if event_code == ProgramEventCode.PIN_CODE_ADDED then
235+
if event_code == ProgramEventCode.MASTER_CODE_CHANGED then
236+
-- ensure the credential is represented locally. no-op if it already exists and state is accurate.
237+
lock_utils.add_reported_credential(device, user_id, true)
238+
elseif event_code == ProgramEventCode.PIN_CODE_ADDED then
239239
-- if no "addCredential" command is in progress, ensure the credential is represented locally
240-
lock_utils.add_reported_credential(device, user_id)
240+
lock_utils.add_reported_credential(device, user_id, false)
241241
elseif event_code == ProgramEventCode.PIN_CODE_DELETED then
242242
-- check if a credential exists locally for this user id, then
243243
-- try to delete the entries in our tables corresponding to this code.
@@ -349,24 +349,24 @@ function ZigbeeHandlers.lock_state(driver, device, value, zb_rx)
349349
end
350350
end
351351

352-
function ZigbeeHandlers.max_pin_code_length(driver, device, value)
353-
device:emit_event(capabilities.lockCredentials.maxPinCodeLen(value.value, { visibility = { displayed = false } }))
352+
function ZigbeeHandlers.max_pin_code_length(driver, device, zb_rx)
353+
device:emit_event(capabilities.lockCredentials.maxPinCodeLen(zb_rx.value, { visibility = { displayed = false } }))
354354
end
355355

356-
function ZigbeeHandlers.min_pin_code_length(driver, device, value)
357-
device:emit_event(capabilities.lockCredentials.minPinCodeLen(value.value, { visibility = { displayed = false } }))
356+
function ZigbeeHandlers.min_pin_code_length(driver, device, zb_rx)
357+
device:emit_event(capabilities.lockCredentials.minPinCodeLen(zb_rx.value, { visibility = { displayed = false } }))
358358
end
359359

360-
function ZigbeeHandlers.number_of_pin_users_supported(driver, device, value)
361-
if not device:supports_capability_by_id(capabilities.lockCodes.ID) and value.value > 0 then
360+
function ZigbeeHandlers.number_of_pin_users_supported(driver, device, zb_rx)
361+
if not device:supports_capability_by_id(capabilities.lockCodes.ID) and zb_rx.value > 0 then
362362
-- this device was generically fingerprinted, but supports PIN users, so we should migrate it.
363363
device:try_update_metadata({ profile = "base-lock" })
364364
end
365365
if device:supports_capability(capabilities.lockCredentials) then
366-
device:emit_event(capabilities.lockCredentials.pinUsersSupported(value.value, {visibility = {displayed = false}}))
366+
device:emit_event(capabilities.lockCredentials.pinUsersSupported(zb_rx.value, {visibility = {displayed = false}}))
367367
end
368368
if device:supports_capability(capabilities.lockUsers) then
369-
device:emit_event(capabilities.lockUsers.totalUsersSupported(value.value, {visibility = {displayed = false}}))
369+
device:emit_event(capabilities.lockUsers.totalUsersSupported(zb_rx.value, {visibility = {displayed = false}}))
370370
end
371371
end
372372

‎drivers/SmartThings/zigbee-lock/src/lock_utils/constants.lua‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,12 @@ lock_constants.SYNC = {
1919
CODES_SYNC_VERSION = 1, -- bump to force every device to re-sync its codes (a mismatch with codesSynced triggers it; with syncCodeIndexVersion, restarts from index 0)
2020
}
2121

22+
-- constants defining programming code representation in the lock's state tables.
23+
lock_constants.PROGRAMMING_USER = {
24+
USER_TYPE = "programmingUser",
25+
DEFAULT_NAME = "Programming Code"
26+
}
27+
2228
lock_constants.COMMAND_RESULT = {
2329
SUCCESS = "success",
2430
FAILURE = "failure",

‎drivers/SmartThings/zigbee-lock/src/lock_utils/tables.lua‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -258,6 +258,23 @@ function table_utils.delete_all_entries(device, table_name)
258258
return COMMAND_RESULT.SUCCESS
259259
end
260260

261+
-- Delete every entry of a table for which `keep(entry)` is false, emitting a single update.
262+
function table_utils.delete_entries_except(device, table_name, keep)
263+
device.log.debug("table_helpers: attempting to delete all non-kept entries from " .. table_name)
264+
local def = resolve_table_def(device, table_name)
265+
if not def then return COMMAND_RESULT.FAILURE end
266+
local t = table_utils.get_state(device, def)
267+
if not t then return COMMAND_RESULT.FAILURE end
268+
269+
local kept = {}
270+
for _, entry in ipairs(t) do
271+
if keep(entry) then table.insert(kept, entry) end
272+
end
273+
device:emit_event(def.attribute(kept, {visibility = {displayed = false}}))
274+
persist_table(device, def, kept)
275+
return COMMAND_RESULT.SUCCESS
276+
end
277+
261278
-- Restore capability state from the persistent field store.
262279
-- Called during init to re-emit table events if the capability state cache
263280
-- has been wiped (e.g. after a hub reboot). Only emits for tables that have

0 commit comments

Comments
 (0)