Matter Cluster 3 — Identify Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 3 values in the device shadow use this format:

endpoint_id / 3 / attribute_id

Example:

{
  "1/3/0": 0
}

Data Types

EffectIdentifierEnum

EffectVariantEnum

IdentifyTypeEnum

Cluster 3 Attributes

Cluster 3 defines 2 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 — IdentifyTime

Path example:

1/3/0

Indicates the remaining length of time, in seconds, that the endpoint will continue to identify itself. If this attribute is set to a value other than 0 then the device must enter its identification state, in order to indicate to an observer which of several nodes and/or endpoints it is. It is recommended that this state consists of flashing a light with a period of 0.5 seconds. The IdentifyTime attribute is decremented every second while in this state.

Example:

{
  "1/3/0": 0
}

Attribute 1 / 0x0001 — IdentifyType

Path example:

1/3/1

Indicates how the identification state is presented to the user. This attribute contains one of the values defined in IdentifyTypeEnum. The value None must NOT be used if the device is capable of presenting its identification state using one of the other methods defined in IdentifyTypeEnum.

Values (IdentifyTypeEnum):

Example:

{
  "1/3/1": 0
}

Cluster 3 Commands

Cluster 3 has 2 client-to-server commands and 0 responses.

AcceptedCommandList

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

endpoint_id / 3 / 65529

{
  "1/3/65529": [
    0,
    64
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

For Cluster 3, always use "cluster_id": 3. 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: Identify

Purpose

This command starts or stops the receiving device identifying itself.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 3,
    "command_name": "Identify",
    "payload": {
      "identifyTime": 0
    }
  }
}

Command: TriggerEffect

Purpose

This command allows the support of feedback to the user, such as a certain light effect. It is used to allow an implementation to provide visual feedback to the user under certain circumstances such as a color light turning green when it has successfully connected to a network. The use of this command and the effects themselves are entirely up to the implementer to use whenever a visual feedback is useful but it is not the same as and does not replace the identify mechanism used during commissioning.

Command Identity

Payload Fields

EffectIdentifier values (EffectIdentifierEnum): 0 = Blink, 1 = Breathe, 2 = Okay, 11 = ChannelChange, 254 = FinishEffect, 255 = StopEffect

EffectVariant values (EffectVariantEnum): 0 = Default

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 3,
    "command_name": "TriggerEffect",
    "payload": {
      "effectIdentifier": 0,
      "effectVariant": 0
    }
  }
}

Cluster 3 Events

Cluster 3 defines no events.

SmartphoneKey Notes

• Cluster 3 is present on SmartphoneKey devices or hubs today. See Matter Bridge Clusters — Detailed Reference and Matter Device Attributes & Commands for the values the bridge actually reports.
• Shadow paths follow endpoint/3/attribute; attribute values that the device reports as unreadable are written as n/a.
• Attribute IDs, command IDs and enum values on this page come from the CSA Matter 1.6.1 data model; descriptions are condensed from the specification text.