Matter Cluster Documentation

What is Matter?

Matter is a smart-device interoperability standard. Instead of every vendor inventing a completely different device data model, Matter defines a common structure so controllers, apps, hubs, and cloud systems can understand devices in a predictable way.

The most important building blocks are:

• Node: the full physical device on the network.
• Endpoint: a functional part of the device. One physical product can expose multiple endpoints.
• Cluster: a group of related features or properties. Think of a cluster as a topic area, such as Door Lock, Battery, or Temperature Measurement.
• Attribute: one specific value inside a cluster, such as LockState or BatVoltage.
• Command: an action you can send to a cluster, such as lock/unlock for a lock device.

How to read the table

• Endpoint tells you which functional part of the device the row belongs to.
• Cluster gives the human-readable cluster name followed by its numeric ID in parentheses, for example Basic Information (40).
• Attribute is the exact property exposed by the cluster.
• Path uses the format endpoint/cluster/attribute and is shown as inline code.

Detailed meaning, value semantics, and examples for each attribute are in the expandable cards under each table.

Important beginner note

A cluster is not the same thing as a device type.

For example, the Boolean State cluster only gives a true/false value. That value can mean very different things depending on the endpoint device type:

• for a contact sensor, it may mean open/closed
• for a leak sensor, it may mean leak/no leak

So Matter data must always be interpreted using both:

1. the cluster and attribute
2. the endpoint role / device type context

Device info data

This section documents values reported by Matter device clusters. These fields are data attributes used for inventory, state shadows, diagnostics, power status, and sensor readings. They are not commands.

Root device / system information

These rows describe the overall device identity and diagnostic/network-management information. They are important for inventory, troubleshooting, and support, but they do not directly control the main user-facing lock function.

Field details

VendorName — Human-readable vendor name. Example: "SmartphoneKey Systems Inc". String value. This is not an enum. It is the vendor display name reported by the device, so different manufacturers return different text.

ProductName — Human-readable product name. Example: "SmartphoneKey Reader". String value. This is the product/model display name exposed by the node, not a device-type enum.

HardwareVersionString — Hardware version string. Example: "release". String value. Usually a human-readable hardware revision, board revision, or release label. Treat as vendor-defined text.

SoftwareVersionString — Software/firmware version string. Example: "1.26.1+1". String value. Usually firmware/software version. Use as text because vendors may include semantic versions, build metadata, or custom labels.

ManufacturingDate/DateCode — Manufacturing date or date code supplied by the device. Example: "20250903". String/date-code value. Format is vendor-provided. In this export it looks like YYYYMMDD, but do not assume all devices use the same format.

SerialNumber — Serial number string. Example: "11064672519639222187". String value. Physical serial number. It may look numeric but should be stored as text to avoid losing leading zeros or formatting.

VendorID — Vendor identifier. Example: 4619. Numeric vendor identifier assigned through the Matter/CSA vendor ID process. Store as number, but display can also be useful in hex for engineering logs.

ProductURL — Product URL if implemented. Example: "". String URL value when implemented. Empty string means the device did not provide a product/support URL.

UpTime — Current uptime. Example: 588758. Numeric duration in seconds. Means the device has been up for 588,758 seconds since last boot. A sudden low value usually means the node rebooted recently.

TotalOperationalHours — Total operational hours. Example: 163. Numeric duration in hours. Means the device reports 163 total operational hours. This value is cumulative if the device persists it.

BootReason — Reason for most recent boot. Example: 6. Enum value. Common Matter meanings include 0 = Unspecified, 1 = PowerOnReboot, 2 = BrownOutReset, 3 = SoftwareWatchdogReset, 4 = HardwareWatchdogReset, 5 = SoftwareUpdateCompleted, 6 = SoftwareReset. Here 6 means software-triggered reset/reboot.

NeighborTable — Neighbor table entries. Example: [{"averageRssi": -25, ...}] or simplified as [-25]. Table/list value. Each entry describes a Thread neighbor. RSSI values are normally negative dBm: closer to 0 is stronger; around -25 is very strong, -50 is good, -70 is weak.

RoutingRole — Current Thread routing role. Example: 6. Enum value describing Thread role. Typical values are role-like states such as disabled, detached, child/end device, router, leader, or border-router-capable role depending on implementation/spec version. Use this mainly for diagnostics, not business state.

NetworkName — Thread network name. Example: "OpenThread-952e". String value. Thread network name. It should match the expected Thread mesh if the device joined the correct network.

RSSI — Received signal strength indicator. Example: nan. Numeric RSSI in dBm when reported. Wi-Fi RSSI is usually negative: closer to 0 is stronger. nan, null, or missing usually means Wi-Fi is not used or the device does not report it.

IdleModeDuration — Idle mode duration for ICD behavior. Example: 300. Numeric duration in seconds. For ICD devices this is the idle-mode interval where the device may sleep or be less immediately reachable.

ActiveModeDuration — Active mode duration for ICD behavior. Example: 300. Numeric duration in milliseconds in Matter ICD definitions. It describes how long the device stays in active mode after wake/active behavior before returning to idle behavior.

ActiveModeThreshold — Threshold for entering active mode. Example: 300. Numeric threshold in milliseconds. Used by ICD behavior to decide active-mode timing/responsiveness. Larger values usually keep the device responsive longer but can affect battery.

UserActiveModeTriggerHint — Hint describing how to trigger active mode. Example: 4381. Bitmap/bitmask value. Each bit hints a possible user action that can wake or activate the device. Decode as flags, not as a single plain number. Pair with UserActiveModeTriggerInstruction for human-readable instructions.

UserActiveModeTriggerInstruction — Instruction text for user-triggered active mode. Example: "Restart the application". String value. Human-readable instruction for how a user can trigger active mode. This is directly displayable text if needed.

Door lock / access control

These rows describe the access-control behavior of the device. This is the most business-critical group for teams working with door-entry logic, credentials, remote operations, and physical security behavior.

Battery / power source

These rows describe how the device is powered and whether maintenance may be needed. This is especially important for field support teams and for platforms that need to show battery health.

Humidity sensor

These rows show environmental humidity sensing data. Even though the main product is a reader/lock-oriented device, this export also exposes humidity measurement information on one endpoint.

MeasuredValue — Current relative humidity measured value. Example: 3011. Numeric measured humidity in hundredths of a percent. Convert with value / 100, so 3011 means 30.11% RH.

Occupancy / presence sensor

These rows show whether the endpoint currently detects occupancy or presence. This is typically used by automation and monitoring systems rather than by core lock workflows.

Occupancy — Current occupancy/presence state. Example: 0. Bitmap value. Bit 0 indicates occupied/presence detected. 0 means no occupancy detected; 1 means occupied. Future/additional bits may represent more sensing modes.

Contact sensor interpretation

This section isolates the Boolean State row that is documented as a contact/door-sensor style interpretation. It is separated on purpose to show that Boolean State needs device-type context.

StateValue — Binary state value. For this door sensor it maps to open/closed contact state. Example: true. Boolean value. For a contact sensor endpoint, map with endpoint context: commonly true = open/contact active, false = closed/inactive, but verify with the specific device behavior.

Water leak sensor interpretation

This section isolates the Boolean State row that is documented as a water-leak interpretation. It is separated on purpose to show that the same Boolean State cluster can represent a completely different real-world condition.

Temperature sensor

These rows show temperature measurement data from the endpoint that reports temperature. As with humidity, the raw value normally needs conversion before end-user display.

MeasuredValue — Current temperature measured value. Example: 2591. Numeric measured temperature in hundredths of a degree Celsius. Convert with value / 100, so 2591 means 25.91 °C.

Supported commands

This section documents command capabilities. These fields describe what the device can accept as actions. In Matter, command support is normally discovered from the global AcceptedCommandList attribute, path format endpoint/cluster/65529.

Use this section separately from Device info data:

• Device info data = attributes reported by the device, for example 0/40/1, 1/257/0, or 1/47/12.
• Supported commands = actions the device/cluster accepts, for example LockDoor, UnlockDoor, GetUser, or general commissioning commands.

Matter command capability fields

Matter exposes command capability through global cluster attributes. In the endpoint/cluster/attribute format, the most important command-capability paths are:

Example path: 0/49/65529 means endpoint 0, cluster 49, attribute 65529. That tells you which commands the Network Commissioning cluster accepts on endpoint 0.

General endpoint 0 commands for all Matter device types

Endpoint 0 is the root/system endpoint. These commands are not lock-specific. They are common Matter system, commissioning, diagnostics, security, and fabric-management capabilities. Any device type may expose some of these clusters depending on what it supports.

For bridge implementation, these endpoint 0 command lists should usually be treated as system capabilities. They are useful for commissioning, diagnostics, network setup, and fabric administration, but they should not be exposed as normal user commands like lock/unlock, temperature read, or leak state.

Door Lock cluster supported commands

The Door Lock cluster has a command set for lock operation, user/PIN/RFID management, schedules, credentials, logs, and Aliro reader configuration. Important: a real lock may support only a subset of these commands. To know what one exact device supports, read the standard AcceptedCommandList global attribute for cluster 257 on the lock endpoint, for example path 1/257/65529 when using the endpoint/cluster/attribute format.

For python-matter-server / bridge usage, commands are normally sent to cluster 257 on the lock endpoint, usually endpoint 1. In your AWS IoT payload, the bridge should resolve device_uuid -> node_id, then send the command with node_id, endpoint_id, cluster command name, and command-specific args.

Door Lock command support check

Door Lock command support is separate from the general endpoint 0 system commands above. Do not assume every Matter lock supports every command listed above. The practical support check is:

Matter Device Types Mapping

Source of Truth

Matter device types are read from the Matter Descriptor cluster:

<endpoint>/29/0

Where:

29 = Descriptor cluster
0  = DeviceTypeList attribute

python-matter-server returns the value in decimal form:

"1/29/0": [
  {
    "0": 21,
    "1": 1
  }
]

Meaning:

"0" = Matter Device Type ID
"1" = Device Type Revision

The official Matter SDK data model publishes the Matter 1.5 device type ID map in connectedhomeip/data_model/1.5/device_types/device_type_ids.json.

Source:

• https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.5/device_types/device_type_ids.json

Bridge Rules

device_info shadow

The device_info shadow stores the numeric Matter device type under the real Matter path.

Example for Contact Sensor:

{
  "1/29/0": 21
}

Do not write this custom field to device_info:

{
  "device_type": "contact_sensor"
}

Composite Sensor Rules

Some physical devices expose multiple sensor endpoints.

Example:

770 = Temperature Sensor
775 = Humidity Sensor

The bridge combines them into:

temperature_humidity_sensor

The device_info shadow still stores only one selected numeric Matter path, for example:

{
  "1/29/0": 770
}

But internal bridge type and AWS IoT Thing Type become:

temperature_humidity_sensor

Complete Matter Device Type List