Matter Cluster 260 — Closure Control Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 260 values in the device shadow use this format:

endpoint_id / 260 / attribute_id

Example:

{
  "1/260/1": 0
}

Cluster 260 Features

The FeatureMap attribute (1/260/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; 511 means every feature listed above is enabled.

Data Types

ClosureErrorEnum

The following ranges are reserved for general and manufacturer specified closure errors. The manufacturer-specific error definitions must NOT duplicate the general error definitions.

CurrentPositionEnum

MainStateEnum

TargetPositionEnum

LatchControlModesBitmap (bitmap)

OverallCurrentStateStruct (struct)

OverallTargetStateStruct (struct)

Cluster 260 Attributes

Cluster 260 defines 6 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 — CountdownTime

Path example:

1/260/0

Indicates the estimated time left before the operation is completed, in seconds. A value of 0 (zero) means that the operation has completed. A value of null indicates that there is no time currently defined until operation completion. This may happen because the completion time is unknown.

Example:

{
  "1/260/0": 0
}

Attribute 1 / 0x0001 — MainState

Path example:

1/260/1

Indicates the current operational state of the closure associated with the server. The MainState diagram is provided exclusively for informational purposes only and is an exemplary design of the internals of a closure implementation to help illustrate the aspects of function that are considered by the cluster's normative text.

Values (MainStateEnum):

Example:

{
  "1/260/1": 0
}

Attribute 2 / 0x0002 — CurrentErrorList

Path example:

1/260/2

Indicates the currently active errors. An empty list indicates that there are no active errors. There must NOT be duplicate values of ClosureErrorEnum within the CurrentErrorList.

Example:

{
  "1/260/2": []
}

Attribute 3 / 0x0003 — OverallCurrentState

Path example:

1/260/3

Indicates the current Position, Latch and/or Speed states, whichever are applicable according to the feature flags set. Null, if the state is unknown. Examples could be, but are not limited to: - The state of Position/Latch is not known yet because the closure is not calibrated. - The product has lost its Position/Latch state after manual motion during a shutdown. The values of the different fields within the structure of this attribute depend on: - The effects of MoveTo commands. - The effects of SetTarget and Step commands in a Closure Dimension Cluster associated with this cluster. - The Stop command.

Value is a OverallCurrentStateStruct struct (see Data Types).

Example:

{
  "1/260/3": {
    "position": 0,
    "latch": true,
    "speed": 0,
    "secureState": true
  }
}

Attribute 4 / 0x0004 — OverallTargetState

Path example:

1/260/4

Indicates the TargetPosition, TargetLatch and/or TargetSpeed values, whichever are applicable according to the feature flags set. Null, if the state is unknown. For example after a reboot.

Value is a OverallTargetStateStruct struct (see Data Types).

Example:

{
  "1/260/4": {
    "position": 0,
    "latch": true,
    "speed": 0
  }
}

Attribute 5 / 0x0005 — LatchControlModes

Path example:

1/260/5

This attribute specifies whether the latch mechanism can be latched or unlatched remotely.

Bits (LatchControlModesBitmap):

Example:

{
  "1/260/5": 0
}

Cluster 260 Commands

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

AcceptedCommandList

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

endpoint_id / 260 / 65529

{
  "1/260/65529": [
    0,
    1,
    2
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

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

Purpose

On receipt of this command, the closure must stop its movement as fast as the closure is able too. If the server's MainState attribute has one of the following values: - Moving - WaitingForMotion - Calibrating then any motions is stopped and the MainState attribute is set to Stopped. A status code of SUCCESS must always be returned, regardless of the value of the MainState attribute when this command is received.

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": 260,
    "command_name": "Stop",
    "payload": {}
  }
}

Command: MoveTo

Purpose

On receipt of this command, the closure must operate to update its position, latch state and/or motion speed. The rationale behind defining the conformance as being purely optional in the table above is to ensure that commands containing one or more fields related to unsupported features are still accepted, rather than being rejected outright. For example, if a simple client, which is not able to determine the capabilities of the server, invokes a command that includes both position and speed, a server that does not support the speed feature would simply ignore the speed field while still adjusting its position as requested.

Command Identity

Payload Fields

Position values (TargetPositionEnum): 0 = MoveToFullyClosed, 1 = MoveToFullyOpen, 2 = MoveToPedestrianPosition, 3 = MoveToVentilationPosition, 4 = MoveToSignaturePosition

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 260,
    "command_name": "MoveTo",
    "payload": {
      "position": 0,
      "latch": true
    },
    "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: Calibrate

Purpose

This command is used to trigger a calibration of the closure.

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": 260,
    "command_name": "Calibrate",
    "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.

Cluster 260 Events

Event 0 — OperationalError

This event is generated when a reportable error condition is detected. A closure that generates this event must also set the MainState attribute to Error, indicating an error condition. This event contains the following fields:

Event 1 — MovementCompleted

This event, if supported, is generated when the overall operation ends, either successfully or otherwise. For example, the event is sent upon the completion of a movement operation in a blind.

This event has no fields.

Event 2 — EngageStateChanged

This event, if supported, is generated when the MainStateEnum attribute changes state to and from disengaged, indicating if the actuator is Engaged or Disengaged. This event contains the following fields: - True, when the actuator is in a Engaged state, actuator movements possible. - False, when the actuator is in a Disengaged state, preventing any actuator movements.

Event 3 — SecureStateChanged

This event, if supported, is generated when the SecureState field in the OverallCurrentState attribute changes. It is used to indicate whether a closure is securing a space against possible unauthorized entry. This event contains the following fields: - True, when the closure is in a secure state, e.g. unauthorized/undetectable access is not possible. - False, when the closure is in an insecure state, e.g. unauthorized/undetectable access is possible.

SmartphoneKey Notes

• Cluster 260 is not currently exposed by SmartphoneKey devices. This page documents the Matter 1.6.1 specification so that future devices can be interpreted without changes to the backend.
• Shadow paths follow endpoint/260/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.