Matter Lock: modular reprofiling should run when the target profile changes, not only when optional capabilities change

[ldeora]

Summary

The new-matter-lock sub-driver can detect that a Matter lock supports the DoorLock UNBOLT feature and correctly emits:

"supportedLockValues": ["locked", "unlocked", "unlatched", "not fully locked"],
"supportedLockCommands": ["lock", "unlock", "unlatch"]

However, the device may still remain on a profile that does not expose the unlatch UI, because match_profile_modular() only calls try_update_metadata() when the optional capability list changes.

This means a device can have the correct capability state, but the SmartThings app does not show the unlatch feature because the profile was not updated.

Tested with a real device

This was tested with a real Nuki Smart Lock Ultra.

With the current behavior, the device reported unlatch support in component status, but the SmartThings app did not show the unlatch control because the device remained on the non-unlatch profile.

After applying the proposed reprofiling fix locally, the same real device successfully migrated to:

lock-modular-embedded-unlatch

The SmartThings app then showed the unlatch feature as expected.

Observed behavior

Tested with a Nuki Smart Lock Ultra using the Matter Lock driver.

The device initially used a non-unlatch fallback profile. The driver detected UNBOLT and emitted:

"supportedLockCommands": ["lock", "unlock", "unlatch"]

but the app did not show the unlatch feature until the profile was actually changed to:

lock-modular-embedded-unlatch

The key difference was that try_update_metadata() did not run when only the target profile name changed.

Current code pattern

In drivers/SmartThings/matter-lock/src/new-matter-lock/init.lua, match_profile_modular() determines the correct modular profile name:

modular_profile_name = "lock-modular-embedded-unlatch"

when DoorLock.types.Feature.UNBOLT is supported.

But the metadata update is gated only by:

if lock_utils.optional_capabilities_list_changed(enabled_optional_component_capability_pairs, device.profile.components) then
  device:try_update_metadata({
    profile = modular_profile_name,
    optional_component_capabilities = enabled_optional_component_capability_pairs
  })
end

SmartThingsEdgeDrivers/drivers/SmartThings/matter-lock/src/new-matter-lock/init.lua

Lines 262 to 264 in b889ef9

	if lock_utils.optional_capabilities_list_changed(enabled_optional_component_capability_pairs, device.profile.components) then
	device:try_update_metadata({profile = modular_profile_name, optional_component_capabilities = enabled_optional_component_capability_pairs})
	end

This misses the case where the optional capabilities are unchanged, but the required profile changes from a non-unlatch profile to lock-modular-embedded-unlatch.

Expected behavior

The driver should update metadata when either:

1. the optional capability list changed, or
2. the target profile name changed.

Suggested fix

local optional_capabilities_changed = lock_utils.optional_capabilities_list_changed(
  enabled_optional_component_capability_pairs,
  device.profile.components
)

local profile_changed = device.profile.id ~= modular_profile_name and
  device.profile.name ~= modular_profile_name

if profile_changed or optional_capabilities_changed then
  device:try_update_metadata({
    profile = modular_profile_name,
    optional_component_capabilities = enabled_optional_component_capability_pairs
  })
end

Why this matters

The lock-modular-embedded-unlatch profile contains the detail-view push button for the unlatch command. Without the profile migration, the API state can correctly report that unlatch is supported, while the SmartThings app still does not expose the unlatch control.

Notes

This does not require changing the static fingerprint fallback profile. The fallback profile can remain as-is, provided the dynamic reprofiling logic can migrate the device once the DoorLock FeatureMap is known.

[ldeora]

@hcarter-775 @ctowns

I would like to add a little more context and explain why this issue is relatively urgent from an end-user/device-support perspective.

I had been using my own Matter Lock driver for a while because I needed DoorState support for my Nuki Smart Lock Ultra. A couple of weeks ago, I switched the device back to the production Matter Lock driver to check the current state of the official implementation. At that point I noticed that the device was still using the fallback/static profile:

lock-nocodes-notamper

Since there appeared to be heavy active development around the Matter Lock driver, I assumed this would likely be resolved by the ongoing modular-profile work and temporarily switched back to my own driver.

I tested the production driver again later and found that the behavior had not changed: the lock still did not migrate to the expected unlatch-capable profile:

lock-modular-embedded-unlatch

That is what prompted me to look into the driver logic more closely.

The latest logs make the issue quite clear:

1. The production driver receives the DoorLock FeatureMap from the device.
2. The driver correctly detects that the lock supports the relevant functionality.
3. It emits:

"supportedLockValues": ["locked", "unlocked", "unlatched", "not fully locked"],
"supportedLockCommands": ["lock", "unlock", "unlatch"]

4. However, the device remains on the existing profile and no metadata update to lock-modular-embedded-unlatch is performed.

With the local fix applied, the same real device follows the same initial path, emits the same supported lock values/commands, and then performs the expected profile migration:

Updating device profile to lock-modular-embedded-unlatch. Enabling the optional capabilities [battery] on component 'main'

After that, infoChanged is received and the device is resubscribed with the profile/capability set expected for the unlatch-capable profile.

So the device itself and the FeatureMap detection appear to be working correctly. The failure is specifically that try_update_metadata() is skipped when the optional capability set is unchanged, even though the target profile name has changed.

From a user-facing perspective, this means the API state can report that unlatch is supported while the SmartThings app does not expose the unlatch control. For a door lock, this is a fairly important mismatch because it hides a core device function even though the driver already knows the device supports it.

The local fix was tested with a real Nuki Smart Lock Ultra and resolves this specific behavior without requiring a change to the fingerprint fallback profile.

[hcarter-775]

Thanks @ldeora for the callout. I've reproduced the issue and this work should fix it.