Matter Cluster 257 — Door Lock Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 257 values in the device shadow use this format:

endpoint_id / 257 / attribute_id

Example:

{
  "1/257/0": 1
}

Cluster 257 Features

The FeatureMap attribute (1/257/65532) is a bitmap. Each bit set means the device implements that feature and the attributes and commands that depend on it.

Example: FeatureMap = 0 means no optional feature is enabled; 32247 means every feature listed above is enabled.

Data Types

AlarmCodeEnum

This enumeration indicates the alarm type.

CredentialRuleEnum

This enumeration indicates the credential rule that can be applied to a particular user.

CredentialTypeEnum

This enumeration indicates the credential type.

DataOperationTypeEnum

This enumeration indicates the data operation performed.

DoorStateEnum

This enumeration indicates the current door state.

EventTypeEnum

LEDSettingEnum

LockDataTypeEnum

This enumeration indicates the data type that is being or has changed.

LockOperationTypeEnum

This enumeration indicates the type of Lock operation performed.

LockStateEnum

LockTypeEnum

OperatingModeEnum

This enumeration indicates the lock operating mode.

OperationErrorEnum

This enumeration indicates the error cause of the Lock/Unlock operation performed.

OperationSourceEnum

This enumeration indicates the source of the Lock/Unlock or user change operation performed.

SoundVolumeEnum

StatusCodeEnum

UserStatusEnum

This enumeration indicates what the status is for a specific user ID.

UserTypeEnum

This enumeration indicates what the type is for a specific user ID.

AlarmMaskBitmap (bitmap)

ConfigurationRegisterBitmap (bitmap)

CredentialRulesBitmap (bitmap)

DaysMaskBitmap (bitmap)

This bitmap indicates the days of the week the Week Day schedule applies for.

LocalProgrammingFeaturesBitmap (bitmap)

OperatingModesBitmap (bitmap)

For the OperatingModesBitmap, a bit SET indicates that the operating mode IS NOT supported. A bit CLEAR indicates that the operating mode IS supported.

CredentialStruct (struct)

This struct indicates the credential types and their corresponding indices (if any) for the event or user record.

Cluster 257 Attributes

Cluster 257 defines 46 attributes plus the global attributes. Conformance: M mandatory, O optional, a feature code means "mandatory when that feature is present", square brackets mean "optional when …".

Global attributes

Attribute Details

Attribute 0 / 0x0000 — LockState

Path example:

1/257/0

This attribute may be null if the lock hardware does not currently know the status of the locking mechanism. For example, a lock may not know the LockState status after a power cycle until the first lock actuation is completed. The Not Fully Locked value is used by a lock to indicate that the state of the lock is somewhere between Locked and Unlocked so it is only partially secured. For example, a deadbolt could be partially extended and not in a dead latched state.

Values (LockStateEnum):

Example:

{
  "1/257/0": 1
}

Attribute 1 / 0x0001 — LockType

Path example:

1/257/1

Indicates the type of door lock as defined in LockTypeEnum.

Values (LockTypeEnum):

Example:

{
  "1/257/1": 0
}

Attribute 2 / 0x0002 — ActuatorEnabled

Path example:

1/257/2

Indicates if the lock is currently able to (Enabled) or not able to (Disabled) process remote Lock, Unlock, or Unlock with Timeout commands.

Example:

{
  "1/257/2": true
}

Attribute 3 / 0x0003 — DoorState

Path example:

1/257/3

Indicates the current door state as defined in DoorStateEnum. Null only if an internal error prevents the retrieval of the current door state.

Values (DoorStateEnum):

Example:

{
  "1/257/3": 0
}

Attribute 4 / 0x0004 — DoorOpenEvents

Path example:

1/257/4

This attribute holds the number of door open events that have occurred since it was last zeroed.

Example:

{
  "1/257/4": 1
}

Attribute 5 / 0x0005 — DoorClosedEvents

Path example:

1/257/5

This attribute holds the number of door closed events that have occurred since it was last zeroed.

Example:

{
  "1/257/5": 1
}

Attribute 6 / 0x0006 — OpenPeriod

Path example:

1/257/6

This attribute holds the number of minutes the door has been open since the last time it transitioned from closed to open.

Example:

{
  "1/257/6": 1
}

Attribute 17 / 0x0011 — NumberOfTotalUsersSupported

Path example:

1/257/17

Indicates the number of total users supported by the lock.

Example:

{
  "1/257/17": 1
}

Attribute 18 / 0x0012 — NumberOfPINUsersSupported

Path example:

1/257/18

No condensed specification text is available for NumberOfPINUsersSupported; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "1/257/18": 1
}

Attribute 19 / 0x0013 — NumberOfRFIDUsersSupported

Path example:

1/257/19

No condensed specification text is available for NumberOfRFIDUsersSupported; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "1/257/19": 1
}

Attribute 20 / 0x0014 — NumberOfWeekDaySchedulesSupportedPerUser

Path example:

1/257/20

Indicates the number of configurable week day schedule supported per user.

Example:

{
  "1/257/20": 1
}

Attribute 21 / 0x0015 — NumberOfYearDaySchedulesSupportedPerUser

Path example:

1/257/21

Indicates the number of configurable year day schedule supported per user.

Example:

{
  "1/257/21": 1
}

Attribute 22 / 0x0016 — NumberOfHolidaySchedulesSupported

Path example:

1/257/22

Indicates the number of holiday schedules supported for the entire door lock device.

Example:

{
  "1/257/22": 1
}

Attribute 23 / 0x0017 — MaxPINCodeLength

Path example:

1/257/23

No condensed specification text is available for MaxPINCodeLength; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "1/257/23": 1
}

Attribute 24 / 0x0018 — MinPINCodeLength

Path example:

1/257/24

No condensed specification text is available for MinPINCodeLength; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "1/257/24": 1
}

Attribute 25 / 0x0019 — MaxRFIDCodeLength

Path example:

1/257/25

No condensed specification text is available for MaxRFIDCodeLength; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "1/257/25": 1
}

Attribute 26 / 0x001A — MinRFIDCodeLength

Path example:

1/257/26

No condensed specification text is available for MinRFIDCodeLength; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "1/257/26": 1
}

Attribute 27 / 0x001B — CredentialRulesSupport

Path example:

1/257/27

This attribute contains a bitmap with the bits set for the values of CredentialRuleEnum supported on this device.

Bits (CredentialRulesBitmap):

Example:

{
  "1/257/27": 0
}

Attribute 28 / 0x001C — NumberOfCredentialsSupportedPerUser

Path example:

1/257/28

Indicates the number of credentials that could be assigned for each user. Depending on the value of NumberOfRFIDUsersSupported and NumberOfPINUsersSupported it may not be possible to assign that number of credentials for a user. For example, if the device supports only PIN and RFID credential types, NumberOfCredentialsSupportedPerUser is set to 10, NumberOfPINUsersSupported is set to 5 and NumberOfRFIDUsersSupported is set to 3, it will not be possible to actually assign 10 credentials for a user because maximum number of credentials in the database is 8.

Example:

{
  "1/257/28": 1
}

Attribute 33 / 0x0021 — Language

Path example:

1/257/33

Indicates the language for the on-screen or audible user interface using a 2-byte language code from ISO-639-1.

Example:

{
  "1/257/33": "example"
}

Attribute 34 / 0x0022 — LEDSettings

Path example:

1/257/34

No condensed specification text is available for LEDSettings; use the type, conformance and constraint below together with the cluster description above.

Values (LEDSettingEnum):

Example:

{
  "1/257/34": 0
}

Attribute 35 / 0x0023 — AutoRelockTime

Path example:

1/257/35

Indicates the number of seconds to wait after unlocking a lock before it automatically locks again. 0=disabled. If set, unlock operations from any source will be timed. For one time unlock with timeout use the specific command.

Example:

{
  "1/257/35": 0
}

Attribute 36 / 0x0024 — SoundVolume

Path example:

1/257/36

Indicates the sound volume on a door lock as defined by SoundVolumeEnum.

Values (SoundVolumeEnum):

Example:

{
  "1/257/36": 0
}

Attribute 37 / 0x0025 — OperatingMode

Path example:

1/257/37

Indicates the current operating mode of the lock as defined in OperatingModeEnum.

Values (OperatingModeEnum):

Example:

{
  "1/257/37": 0
}

Attribute 38 / 0x0026 — SupportedOperatingModes

Path example:

1/257/38

This attribute contains a bitmap with all operating bits of the OperatingMode attribute supported by the lock. A bit position set to zero indicates that the mode is supported. A bit position set to one indicates that the mode is not supported. Any bit that is not yet defined in OperatingModesBitmap is set to 1.

Bits (OperatingModesBitmap):

Example:

{
  "1/257/38": 0
}

Attribute 39 / 0x0027 — DefaultConfigurationRegister

Path example:

1/257/39

Indicates the default configurations as they are physically set on the device (example: hardware dip switch setting, etc…) and represents the default setting for some of the attributes within this cluster (for example: LED, Auto Lock, Sound Volume, and Operating Mode attributes). This is a read-only attribute and is intended to allow clients to determine what changes may need to be made without having to query all the included attributes. It may be beneficial for the clients to know what the device’s original settings were in the event that the device needs to be restored to factory default settings.

Bits (ConfigurationRegisterBitmap):

Example:

{
  "1/257/39": 0
}

Attribute 40 / 0x0028 — EnableLocalProgramming

Path example:

1/257/40

This attribute must enable/disable local programming on the door lock of certain features. If this value is set to TRUE then local programming is enabled on the door lock for all features. If it is set to FALSE then local programming is disabled on the door lock for those features whose bit is set to 0 in the LocalProgrammingFeatures attribute. Local programming is enabled by default.

Example:

{
  "1/257/40": true
}

Attribute 41 / 0x0029 — EnableOneTouchLocking

Path example:

1/257/41

This attribute must enable/disable the ability to lock the door lock with a single touch on the door lock.

Example:

{
  "1/257/41": true
}

Attribute 42 / 0x002A — EnableInsideStatusLED

Path example:

1/257/42

No condensed specification text is available for EnableInsideStatusLED; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "1/257/42": true
}

Attribute 43 / 0x002B — EnablePrivacyModeButton

Path example:

1/257/43

This attribute must enable/disable a button inside the door that is used to put the lock into privacy mode. When the lock is in privacy mode it cannot be manipulated from the outside.

Example:

{
  "1/257/43": true
}

Attribute 44 / 0x002C — LocalProgrammingFeatures

Path example:

1/257/44

Indicates the local programming features that will be disabled when EnableLocalProgramming attribute is set to False. If a door lock doesn't support disabling one aspect of local programming it returns CONSTRAINT_ERROR during a write operation of this attribute. If the EnableLocalProgramming attribute is set to True then all local programming features is enabled regardless of the bits set to 0 in this attribute. The features that can be disabled from local programming are defined in LocalProgrammingFeaturesBitmap.

Bits (LocalProgrammingFeaturesBitmap):

Example:

{
  "1/257/44": 0
}

Attribute 48 / 0x0030 — WrongCodeEntryLimit

Path example:

1/257/48

Indicates the number of incorrect Pin codes or RFID presentment attempts a user is allowed to enter before the lock will enter a lockout state. The value of this attribute is compared to all failing forms of credential presentation, including Pin codes used in an Unlock Command when RequirePINforRemoteOperation is set to true. Valid range is 1-255 incorrect attempts. The lockout state will be for the duration of UserCodeTemporaryDisableTime.

Example:

{
  "1/257/48": 1
}

Attribute 49 / 0x0031 — UserCodeTemporaryDisableTime

Path example:

1/257/49

Indicates the number of seconds that the lock shuts down following wrong code entry. Valid range is 1-255 seconds. Device can shut down to lock user out for specified amount of time. (Makes it difficult to try and guess a PIN for the device.) If the attribute accepts writes and an attempt to write the attribute to 0 is made, the device must respond with CONSTRAINT_ERROR.

Example:

{
  "1/257/49": 1
}

Attribute 50 / 0x0032 — SendPINOverTheAir

Path example:

1/257/50

No condensed specification text is available for SendPINOverTheAir; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "1/257/50": true
}

Attribute 51 / 0x0033 — RequirePINforRemoteOperation

Path example:

1/257/51

No condensed specification text is available for RequirePINforRemoteOperation; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "1/257/51": true
}

Attribute 52 / 0x0034 — SecurityLevel

Path example:

1/257/52

No condensed specification text is available for SecurityLevel; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "1/257/52": 0
}

Attribute 53 / 0x0035 — ExpiringUserTimeout

Path example:

1/257/53

Indicates the number of minutes a PIN, RFID, Fingerprint, or other credential associated with a user of type ExpiringUser must remain valid after its first use before expiring. When the credential expires the UserStatus for the corresponding user record is set to OccupiedDisabled.

Example:

{
  "1/257/53": 1
}

Attribute 128 / 0x0080 — AliroReaderVerificationKey

Path example:

1/257/128

Indicates the verification key component of the Reader's key pair as defined in Aliro.

Example:

{
  "1/257/128": "AQID"
}

Attribute 129 / 0x0081 — AliroReaderGroupIdentifier

Path example:

1/257/129

Indicates the reader_group_identifier as defined in Aliro.

Example:

{
  "1/257/129": "AQID"
}

Attribute 130 / 0x0082 — AliroReaderGroupSubIdentifier

Path example:

1/257/130

Indicates the reader_group_sub_identifier as defined in Aliro.

Example:

{
  "1/257/130": "AQID"
}

Attribute 131 / 0x0083 — AliroExpeditedTransactionSupportedProtocolVersions

Path example:

1/257/131

Indicates the list of protocol versions supported for expedited transactions as defined in Aliro.

Example:

{
  "1/257/131": []
}

Attribute 132 / 0x0084 — AliroGroupResolvingKey

Path example:

1/257/132

Indicates the Group Resolving Key as defined in Aliro.

Example:

{
  "1/257/132": "AQID"
}

Attribute 133 / 0x0085 — AliroSupportedBLEUWBProtocolVersions

Path example:

1/257/133

No condensed specification text is available for AliroSupportedBLEUWBProtocolVersions; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "1/257/133": []
}

Attribute 134 / 0x0086 — AliroBLEAdvertisingVersion

Path example:

1/257/134

No condensed specification text is available for AliroBLEAdvertisingVersion; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "1/257/134": 1
}

Attribute 135 / 0x0087 — NumberOfAliroCredentialIssuerKeysSupported

Path example:

1/257/135

Indicates the maximum number of AliroCredentialIssuerKey credentials that can be stored on the lock.

Example:

{
  "1/257/135": 1
}

Attribute 136 / 0x0088 — NumberOfAliroEndpointKeysSupported

Path example:

1/257/136

Indicates the maximum number of endpoint key credentials that can be stored on the lock. This limit applies to the sum of the number of AliroEvictableEndpointKey credentials and the number of AliroNonEvictableEndpointKey credentials. The credential indices used for these two credential types are independent of each other, similar to all other credential types. As long as NumberOfAliroEndpointKeysSupported is at least 2 a client could add a credential of type AliroEvictableEndpointKey at any index from 1 to NumberOfAliroEndpointKeysSupported and also add a credential of type AliroNonEvictableEndpointKey at the same index, and both credentials would exist on the server.

Example:

{
  "1/257/136": 1
}

Cluster 257 Commands

Cluster 257 has 22 client-to-server commands and 6 responses.

AcceptedCommandList

The AcceptedCommandList attribute lists the command IDs the endpoint actually implements:

endpoint_id / 257 / 65529

{
  "1/257/65529": [
    0,
    1,
    2,
    3,
    11,
    12,
    13,
    14,
    15,
    16,
    17,
    18,
    19,
    26,
    27,
    29,
    34,
    36,
    38,
    39,
    40,
    41
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 257,
    "command_name": "LockDoor",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

For Cluster 257, always use "cluster_id": 257. Payload keys are the command field names in lowerCamelCase. Octet-string fields are base64-encoded. timed_request_timeout_ms is required for timed commands and ignored otherwise.

Command: LockDoor

Purpose

This command causes the lock device to lock the door. This command includes an optional code for the lock. The door lock may require a PIN depending on the value of the RequirePINForRemoteOperation attribute.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 257,
    "command_name": "LockDoor",
    "payload": {
      "pinCode": "AQID"
    },
    "timed_request_timeout_ms": 1000
  }
}

This is a timed command: the bridge must send it inside a timed interaction, so timed_request_timeout_ms is required.

Command: UnlockDoor

Purpose

This command causes the lock device to unlock the door. This command includes an optional code for the lock. The door lock may require a code depending on the value of the RequirePINForRemoteOperation attribute. If the attribute AutoRelockTime is supported the lock will transition to the locked state when the auto relock time has expired.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 257,
    "command_name": "UnlockDoor",
    "payload": {
      "pinCode": "AQID"
    },
    "timed_request_timeout_ms": 1000
  }
}

This is a timed command: the bridge must send it inside a timed interaction, so timed_request_timeout_ms is required.

Command: Toggle

Purpose

Toggle is a client-to-server command of the Door Lock cluster.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 257,
    "command_name": "Toggle",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

This is a timed command: the bridge must send it inside a timed interaction, so timed_request_timeout_ms is required.

Command: UnlockWithTimeout

Purpose

This command causes the lock device to unlock the door with a timeout parameter. After the time in seconds specified in the timeout field, the lock device will relock itself automatically. This timeout parameter is only temporary for this message transition and overrides the default relock time as specified in the AutoRelockTime attribute. If the door lock device is not capable of or does not want to support temporary Relock Timeout, it should NOT support this optional command.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 257,
    "command_name": "UnlockWithTimeout",
    "payload": {
      "timeout": 0
    },
    "timed_request_timeout_ms": 1000
  }
}

This is a timed command: the bridge must send it inside a timed interaction, so timed_request_timeout_ms is required.

Command: SetWeekDaySchedule

Purpose

Set a weekly repeating schedule for a specified user. The associated UserType may be changed to ScheduleRestrictedUser by the lock when a Week Day schedule is set. Return status is one of the following values:

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 257,
    "command_name": "SetWeekDaySchedule",
    "payload": {
      "weekDayIndex": 1,
      "userIndex": 1,
      "daysMask": 0,
      "startHour": 1,
      "startMinute": 1,
      "endHour": 1,
      "endMinute": 1
    }
  }
}

Command: GetWeekDaySchedule

Purpose

Retrieve the specific weekly schedule for the specific user.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 257,
    "command_name": "GetWeekDaySchedule",
    "payload": {
      "weekDayIndex": 1,
      "userIndex": 1
    }
  }
}

The device answers with GetWeekDayScheduleResponse (see below).

Command: GetWeekDayScheduleResponse

Purpose

Returns the weekly repeating schedule data for the specified schedule index.

Command Identity

Response Fields

Command: ClearWeekDaySchedule

Purpose

Clear the specific weekly schedule or all weekly schedules for the specific user. Return status is one of the following values:

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 257,
    "command_name": "ClearWeekDaySchedule",
    "payload": {
      "weekDayIndex": 1,
      "userIndex": 1
    }
  }
}

Command: SetYearDaySchedule

Purpose

Set a time-specific schedule ID for a specified user. The associated UserType may be changed to ScheduleRestrictedUser by the lock when a Year Day schedule is set. Return status is one of the following values:

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 257,
    "command_name": "SetYearDaySchedule",
    "payload": {
      "yearDayIndex": 1,
      "userIndex": 1,
      "localStartTime": 0,
      "localEndTime": 0
    }
  }
}

Command: GetYearDaySchedule

Purpose

Retrieve the specific year day schedule for the specific schedule and user indexes.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 257,
    "command_name": "GetYearDaySchedule",
    "payload": {
      "yearDayIndex": 1,
      "userIndex": 1
    }
  }
}

The device answers with GetYearDayScheduleResponse (see below).

Command: GetYearDayScheduleResponse

Purpose

Returns the year day schedule data for the specified schedule and user indexes.

Command Identity

Response Fields