matter_clusters.h
what this device answers, as opposed to how.
Overview
what this device answers, as opposed to how. matter_im.c owns the ReportData wire format and knows nothing about door locks or vendor IDs. This is the other half: the endpoints, clusters and attributes that exist, and what they say. Scope is deliberately the commissioner's FIRST question and no further. A real iPhone, immediately after PASE, reads nine attribute paths: endpoint 0 GeneralCommissioning 0x0030 attributes 0x00..0x04 and 0x0C endpoint 0 BasicInformation 0x0028 VendorID 0x02, ProductID 0x04 endpoint 0 TimeSynchronization 0x0038 all attributes (wildcard) Everything else answers UNSUPPORTED_*, which is a legal answer and a truthful one. Clusters get added when a commissioner is observed asking for them, rather than because the spec lists them. Device-specific values arrive in @ref matter_device_info instead of being read from Kconfig here, so the host suite can build this without Zephyr and assert on the encoded bytes.
depends on matter_attest.h matter_fabric.h matter_im.h matter_thread.h · used by matter_clusters.c
API
Cstruct matter_user
One user slot. Reported by GetUser, filled by SetUser.
Cstruct matter_device_info
Complete device information structure held by the Matter node, including vendor/product IDs, Aliro identity, user table, commissioning state, operational network configuration, and session-specific attestation and key data.
Cstruct matter_admin_hooks
What the application must do when a controller opens a commissioning window. The cluster decodes and validates; everything it would then have to TOUCH -- the SPAKE2+ verifier the PASE responder uses, the BLE advertising payload, the expiry timer -- belongs to the port. So this module stays free of both Bluetooth and Zephyr, which is what lets tests/host compile it. All three return a MATTER_ADMIN_STATUS_* code, or 0 for success.
##define MATTER_CLUSTER_BASIC_INFORMATION 0x0028u
##define MATTER_CLUSTER_GENERAL_COMMISSIONING 0x0030u
##define MATTER_CLUSTER_NETWORK_COMMISSIONING 0x0031u
##define MATTER_CLUSTER_DESCRIPTOR 0x001Du
##define MATTER_CLUSTER_ACCESS_CONTROL 0x001Fu
##define MATTER_CLUSTER_OPERATIONAL_CREDENTIALS 0x003Eu
##define MATTER_CLUSTER_ADMIN_COMMISSIONING 0x003Cu
##define MATTER_CLUSTER_DOOR_LOCK 0x0101u
##define MATTER_ATTR_ADMIN_WINDOW_STATUS 0x0000u
##define MATTER_ATTR_ADMIN_FABRIC_INDEX 0x0001u
##define MATTER_ATTR_ADMIN_VENDOR_ID 0x0002u
##define MATTER_CMD_ADMIN_OPEN_WINDOW 0x0000u
##define MATTER_CMD_ADMIN_OPEN_BASIC_WINDOW 0x0001u
##define MATTER_CMD_ADMIN_REVOKE 0x0002u
##define MATTER_ADMIN_WINDOW_NOT_OPEN 0u
CommissioningWindowStatusEnum (AdministratorCommissioning/Enums.h).
##define MATTER_ADMIN_WINDOW_ENHANCED 1u
##define MATTER_ADMIN_WINDOW_BASIC 2u
##define MATTER_ADMIN_STATUS_BUSY 1u
##define MATTER_ADMIN_STATUS_PAKE_PARAM_ERROR 2u
##define MATTER_ADMIN_STATUS_WINDOW_NOT_OPEN 3u
##define MATTER_ATTR_DESC_DEVICE_TYPE_LIST 0x0000u
##define MATTER_ATTR_DESC_SERVER_LIST 0x0001u
##define MATTER_ATTR_DESC_CLIENT_LIST 0x0002u
##define MATTER_ATTR_DESC_PARTS_LIST 0x0003u
##define MATTER_DEVICE_TYPE_ROOT_NODE 0x0016u
##define MATTER_DEVICE_TYPE_ROOT_REV 3u
##define MATTER_DEVICE_TYPE_DOOR_LOCK 0x000Au
##define MATTER_DEVICE_TYPE_LOCK_REV 3u
##define MATTER_ATTR_DL_LOCK_STATE 0x0000u
##define MATTER_ATTR_DL_LOCK_TYPE 0x0001u
##define MATTER_ATTR_DL_ACTUATOR_ENABLED 0x0002u
##define MATTER_ATTR_DL_OPERATING_MODE 0x0025u
##define MATTER_ATTR_DL_SUPPORTED_OPERATING_MODES 0x0026u
##define MATTER_ATTR_DL_ALIRO_VERIFICATION_KEY 0x0080u
##define MATTER_ATTR_DL_ALIRO_GROUP_ID 0x0081u
##define MATTER_ATTR_DL_ALIRO_GROUP_SUB_ID 0x0082u
##define MATTER_ATTR_DL_ALIRO_EXPEDITED_VERSIONS 0x0083u
##define MATTER_ATTR_DL_ALIRO_GROUP_RESOLVING_KEY 0x0084u
##define MATTER_ATTR_DL_ALIRO_BLE_UWB_VERSIONS 0x0085u
##define MATTER_ATTR_DL_ALIRO_BLE_ADV_VERSION 0x0086u
##define MATTER_ATTR_DL_ALIRO_ISSUER_KEYS_MAX 0x0087u
##define MATTER_ATTR_DL_ALIRO_ENDPOINT_KEYS_MAX 0x0088u
##define MATTER_DL_FEATURE_ALIRO_PROVISIONING 0x2000u
##define MATTER_DL_FEATURE_ALIRO_BLE_UWB 0x4000u
##define MATTER_DL_FEATURE_USER 0x0100u
##define MATTER_ATTR_DL_USERS_MAX 0x0011u
##define MATTER_ATTR_DL_CREDS_PER_USER_MAX 0x001Cu
##define MATTER_CMD_DL_SET_USER 0x001Au
##define MATTER_CMD_DL_GET_USER 0x001Bu
##define MATTER_CMD_DL_GET_USER_RESPONSE 0x001Cu
##define MATTER_CMD_DL_SET_ALIRO_READER_CONFIG 0x0028u
SetAliroReaderConfig (DoorLock/CommandIds.h:122-125). The command this whole Matter node exists to receive: it is how Apple Home hands over the reader identity, and it is what makes this device provisionable by its owner rather than only by whoever built the firmware. Always preceded by a TimedRequest, because it must not be replayed.
##define MATTER_CMD_DL_LOCK_DOOR 0x0000u
##define MATTER_CMD_DL_UNLOCK_DOOR 0x0001u
##define MATTER_CMD_DL_GET_CREDENTIAL_STATUS 0x0024u
##define MATTER_CMD_DL_GET_CREDENTIAL_STATUS_RESPONSE 0x0025u
##define TAG_CREDSTATUS_EXISTS 0u
##define TAG_CREDSTATUS_USER_INDEX 1u
##define TAG_CREDSTATUS_CREATOR_FABRIC 2u
##define TAG_CREDSTATUS_MODIFIER_FABRIC 3u
##define TAG_CREDSTATUS_NEXT_INDEX 4u
##define TAG_CREDSTATUS_DATA 5u
##define TAG_ALIRO_CFG_SIGNING_KEY 0u
##define TAG_ALIRO_CFG_VERIFICATION_KEY 1u
##define TAG_ALIRO_CFG_GROUP_ID 2u
##define TAG_ALIRO_CFG_GROUP_RESOLVING_KEY 3u
##define MATTER_ALIRO_SIGNING_KEY_LEN 32u
##define MATTER_ALIRO_VERIFICATION_KEY_LEN 65u
##define MATTER_CMD_DL_SET_CREDENTIAL 0x0022u
##define MATTER_CMD_DL_SET_CREDENTIAL_RESPONSE 0x0023u
##define TAG_SETCRED_OPERATION 0u
##define TAG_SETCRED_CREDENTIAL 1u
##define TAG_SETCRED_DATA 2u
##define TAG_SETCRED_USER_INDEX 3u
##define TAG_CREDSTRUCT_TYPE 0u
##define TAG_CREDSTRUCT_INDEX 1u
##define TAG_SETCREDRESP_STATUS 0u
##define TAG_SETCREDRESP_USER_INDEX 1u
##define TAG_SETCREDRESP_NEXT_INDEX 2u
##define MATTER_DL_CRED_ALIRO_ISSUER_KEY 6u
##define MATTER_DL_CRED_ALIRO_EVICTABLE_ENDPOINT 7u
##define MATTER_DL_CRED_ALIRO_ENDPOINT_KEY 8u
##define TAG_SETUSER_OPERATION 0u
##define TAG_SETUSER_INDEX 1u
##define TAG_SETUSER_NAME 2u
##define TAG_SETUSER_UNIQUE_ID 3u
##define TAG_SETUSER_STATUS 4u
##define TAG_SETUSER_TYPE 5u
##define TAG_SETUSER_CREDENTIAL_RULE 6u
##define TAG_GETUSER_INDEX 0u
##define TAG_GETUSER_NAME 1u
##define TAG_GETUSER_UNIQUE_ID 2u
##define TAG_GETUSER_STATUS 3u
##define TAG_GETUSER_TYPE 4u
##define TAG_GETUSER_CREDENTIAL_RULE 5u
##define TAG_GETUSER_CREDENTIALS 6u
##define TAG_GETUSER_CREATOR_FABRIC 7u
##define TAG_GETUSER_MODIFIER_FABRIC 8u
##define TAG_GETUSER_NEXT_INDEX 9u
##define MATTER_DL_USERS_MAX 10u
How many user slots this lock reports. Reported, not stored: this node holds no user database yet. The count has to be non-zero because a lock claiming the User feature with room for nobody is not a coherent answer.
##define MATTER_DL_CREDS_PER_USER_MAX 5u
##define MATTER_DL_LOCK_STATE_LOCKED 1u
##define MATTER_DL_LOCK_STATE_UNLOCKED 2u
##define MATTER_DL_OPERATING_MODE_NORMAL 0u
##define MATTER_DL_SUPPORTED_OPERATING_MODES 0x0001u
SupportedOperatingModes is a bitmap; bit 0 is Normal and it is the only one.
##define MATTER_ALIRO_PROTOCOL_VERSION 0x0100u
##define MATTER_ALIRO_BLE_ADV_VERSION 0u
0 is the only defined Aliro BLE advertising version.
##define MATTER_ALIRO_KEYS_SUPPORTED 10u
Matches the ESP32 lock's kAliroKeysSupported (aliro_reader_delegate.h:94).
##define MATTER_ALIRO_GROUP_ID_LEN 16u
Aliro group identifier, sub-identifier and resolving key are all 16 bytes.
##define MATTER_ATTR_AC_ACL 0x0000u
Access Control attributes (access-control-cluster.cpp, AclAttribute).
##define MATTER_ATTR_AC_EXTENSION 0x0001u
##define MATTER_ATTR_AC_SUBJECTS_PER_ENTRY 0x0002u
##define MATTER_ATTR_AC_TARGETS_PER_ENTRY 0x0003u
##define MATTER_ATTR_AC_ENTRIES_PER_FABRIC 0x0004u
##define MATTER_ACL_MAX 256u
How much of an ACL this node will hold. One fabric, and the spec's floor is four entries per fabric; a commissioner writes the whole list at once, so this bounds the encoded list rather than any single entry.
##define MATTER_ATTR_FEATURE_MAP 0xFFFCu
FeatureMap, on every cluster (GlobalAttributeIds.h).
##define MATTER_ATTR_BASIC_DATA_MODEL_REVISION 0x0000u
##define MATTER_ATTR_BASIC_VENDOR_NAME 0x0001u
##define MATTER_ATTR_BASIC_VENDOR_ID 0x0002u
##define MATTER_ATTR_BASIC_PRODUCT_NAME 0x0003u
##define MATTER_ATTR_BASIC_PRODUCT_ID 0x0004u
##define MATTER_ATTR_BASIC_NODE_LABEL 0x0005u
##define MATTER_ATTR_BASIC_LOCATION 0x0006u
##define MATTER_ATTR_BASIC_HARDWARE_VERSION 0x0007u
##define MATTER_ATTR_BASIC_HARDWARE_VERSION_STR 0x0008u
##define MATTER_ATTR_BASIC_SOFTWARE_VERSION 0x0009u
##define MATTER_ATTR_BASIC_SOFTWARE_VERSION_STR 0x000Au
##define MATTER_ATTR_BASIC_SERIAL_NUMBER 0x000Fu
##define MATTER_ATTR_BASIC_UNIQUE_ID 0x0012u
##define MATTER_ATTR_BASIC_CAPABILITY_MINIMA 0x0013u
##define MATTER_ATTR_BASIC_SPECIFICATION_VERSION 0x0015u
##define MATTER_ATTR_BASIC_MAX_PATHS_PER_INVOKE 0x0016u
##define MATTER_DATA_MODEL_REVISION 17u
##define MATTER_SPECIFICATION_VERSION 0x01020000u
##define MATTER_CASE_SESSIONS_PER_FABRIC 3u
##define MATTER_SUBSCRIPTIONS_PER_FABRIC 3u
##define MATTER_MAX_PATHS_PER_INVOKE 1u
CHIP_CONFIG_MAX_PATHS_PER_INVOKE (CHIPConfig.h:1877), and what this node parses.
##define MATTER_ATTR_GC_BREADCRUMB 0x0000u
##define MATTER_ATTR_GC_BASIC_COMMISSIONING_INFO 0x0001u
##define MATTER_ATTR_GC_REGULATORY_CONFIG 0x0002u
##define MATTER_ATTR_GC_LOCATION_CAPABILITY 0x0003u
##define MATTER_ATTR_GC_SUPPORTS_CONCURRENT_CONNECTION 0x0004u
##define MATTER_REGULATORY_INDOOR 0u
##define MATTER_REGULATORY_OUTDOOR 1u
##define MATTER_REGULATORY_INDOOR_OUTDOOR 2u
##define MATTER_CMD_GC_ARM_FAIL_SAFE 0x0000u
##define MATTER_CMD_GC_ARM_FAIL_SAFE_RESPONSE 0x0001u
##define MATTER_CMD_GC_SET_REGULATORY_CONFIG 0x0002u
##define MATTER_CMD_GC_SET_REGULATORY_CONFIG_RESPONSE 0x0003u
##define MATTER_CMD_GC_COMMISSIONING_COMPLETE 0x0004u
##define MATTER_CMD_GC_COMMISSIONING_COMPLETE_RESPONSE 0x0005u
##define MATTER_COMMISSIONING_OK 0u
##define MATTER_COMMISSIONING_VALUE_OUTSIDE_RANGE 1u
##define MATTER_COMMISSIONING_INVALID_AUTH 2u
##define MATTER_COMMISSIONING_NO_FAIL_SAFE 3u
##define MATTER_ATTR_NC_MAX_NETWORKS 0x0000u
##define MATTER_ATTR_NC_NETWORKS 0x0001u
##define MATTER_ATTR_NC_SCAN_MAX_TIME_S 0x0002u
##define MATTER_ATTR_NC_CONNECT_MAX_TIME_S 0x0003u
##define MATTER_ATTR_NC_INTERFACE_ENABLED 0x0004u
##define MATTER_ATTR_NC_LAST_NETWORKING_STATUS 0x0005u
##define MATTER_CMD_NC_ADD_OR_UPDATE_THREAD_NETWORK 0x0003u
##define MATTER_CMD_NC_REMOVE_NETWORK 0x0004u
##define MATTER_CMD_NC_NETWORK_CONFIG_RESPONSE 0x0005u
##define MATTER_CMD_NC_CONNECT_NETWORK 0x0006u
##define MATTER_CMD_NC_CONNECT_NETWORK_RESPONSE 0x0007u
##define MATTER_NC_FEATURE_THREAD 0x2u
NetworkCommissioning Feature bits (python clusters/Objects.py, Feature).
##define MATTER_NC_STATUS_SUCCESS 0x00u
##define MATTER_NC_STATUS_OUT_OF_RANGE 0x01u
##define MATTER_NC_STATUS_NETWORK_ID_NOT_FOUND 0x03u
##define MATTER_NC_STATUS_OTHER_CONNECTION_FAILUR 0x09u
##define MATTER_THREAD_DATASET_MAX 254u
A Thread operational dataset, kSizeOperationalDataset (lib/support/ThreadOperationalDataset.h:36).
##define MATTER_THREAD_XPANID_LEN 8u
Extended PAN ID: 8 bytes, and the id a network is referred to by.
##define MATTER_THREAD_ATTACH_TIMEOUT_MS 20000u
How long ConnectNetwork waits for the attach before answering. Well under the 60 s this node reports as ConnectMaxTimeSeconds, because the commissioner is blocked on the reply for the whole of it. A Thread attach to a network whose dataset is already known normally completes in a few seconds; this leaves room for a retry without leaving the phone waiting a minute.
##define MATTER_CMD_OC_ATTESTATION_REQUEST 0x0000u
##define MATTER_CMD_OC_ATTESTATION_RESPONSE 0x0001u
##define MATTER_CMD_OC_CERTIFICATE_CHAIN_REQUEST 0x0002u
##define MATTER_CMD_OC_CERTIFICATE_CHAIN_RESPONSE 0x0003u
##define MATTER_CMD_OC_CSR_REQUEST 0x0004u
##define MATTER_CMD_OC_CSR_RESPONSE 0x0005u
##define MATTER_CMD_OC_ADD_NOC 0x0006u
##define MATTER_CMD_OC_NOC_RESPONSE 0x0008u
##define MATTER_CMD_OC_ADD_TRUSTED_ROOT_CERTIFICATE 0x000Bu
##define MATTER_ATTR_OC_NOCS 0x0000u
##define MATTER_ATTR_OC_FABRICS 0x0001u
##define MATTER_ATTR_OC_SUPPORTED_FABRICS 0x0002u
##define MATTER_ATTR_OC_COMMISSIONED_FABRICS 0x0003u
##define MATTER_ATTR_OC_TRUSTED_ROOTS 0x0004u
##define MATTER_ATTR_OC_CURRENT_FABRIC_INDEX 0x0005u
##define MATTER_SUPPORTED_FABRICS 2u
How many fabrics this node can hold at once. Two, which is not a round number -- it is what a single Apple Home needs. The phone and the home hub commission the device onto SEPARATE fabrics, each with its own trusted root and its own operational key, and a node that advertises one answers the second AddNOC with TABLE_FULL and is never adopted. The spec's floor is five; there is a struct matter_fabric of RAM behind every entry and this part has 128 KB in total.
##define MATTER_NOC_STATUS_OK 0u
##define MATTER_NOC_STATUS_INVALID_PUBLIC_KEY 1u
##define MATTER_NOC_STATUS_INVALID_NOC 3u
##define MATTER_NOC_STATUS_MISSING_CSR 4u
##define MATTER_NOC_STATUS_TABLE_FULL 5u
##define MATTER_ENDPOINT_ROOT 0u
Every Matter node's root endpoint is 0.
##define MATTER_ENDPOINT_LOCK 1u
The Door Lock. Listed in the root endpoint's PartsList.
Fvoid matter_clusters_set_admin_hooks(const struct matter_admin_hooks *hooks)
Install the hooks above. Until this is called the cluster still APPEARS -- a controller reading ServerList sees it, which is the point, because a node that hides it can never be shared with a second ecosystem -- but every command answers FAILURE rather than pretending to have opened something.
Fvoid matter_clusters_init(struct matter_im_server *srv, struct matter_device_info *info)
Fvoid matter_clusters_failsafe_expire(struct matter_device_info *info)
Undo a commissioning that never finished. This is what the fail-safe MEANS, and until AddNOC there was nothing for it to undo -- so the flag recorded the state without enforcing it. Now a commissioner that gives up half way leaves a fabric behind, and the next attempt is answered TableFull for a reason that has nothing to do with what went wrong. The caller decides when: on this port, when the commissioning link drops. Does nothing once commissioning_complete is set -- a finished fabric is not the fail-safe's to remove. The THREAD attachment is deliberately kept. Strictly the fail-safe owns the network config too, but the commissioner re-sends the identical dataset on the next attempt, and staying attached turns the following attach from two seconds into none. Nothing secret is retained that the next commissioner would not immediately re-supply.
Fint matter_clusters_resume(struct matter_device_info *info)
Bring a restored identity back onto the network. A node that reloads its fabric table from storage is commissioned but not REACHABLE: the Thread dataset has not been handed to the stack and no SRP instance exists, so the controller resolves nothing and reports the accessory dead. Commissioning does both of those as a side effect of AddOrUpdateThreadNetwork and AddNOC; this is that same pair, for the boot path that has no commissioner to trigger them. Call it after loading info and only when a fabric was actually restored. @return MATTER_OK when Thread started and every fabric was advertised, MATTER_E_STATE when there is no stored dataset to start from.