Matter Cluster 261 — Closure Dimension Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 261 values in the device shadow use this format:

endpoint_id / 261 / attribute_id

Example:

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

Cluster 261 Features

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

Data Types

ClosureUnitEnum

ModulationTypeEnum

OverflowEnum

RotationAxisEnum

Legend: Open Closed

StepDirectionEnum

This data type is derived from enum8 and used for the Step command to indicate the direction of the steps.

TranslationDirectionEnum

Legend: Open Closed

LatchControlModesBitmap (bitmap)

DimensionStateStruct (struct)

RangePercent100thsStruct (struct)

UnitRangeStruct (struct)

Cluster 261 Attributes

Cluster 261 defines 12 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 — CurrentState

Path example:

1/261/0

Indicates the current Position, Latching and/or Speed, based on the feature flags set. A value of null indicates that: - The position and latching state are both not known yet because the closure is not calibrated, or - The product has lost its position and latching state after manual motion during a shutdown.

Value is a DimensionStateStruct struct (see Data Types).

Example:

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

Attribute 1 / 0x0001 — TargetState

Path example:

1/261/1

Indicates the target Position, Latching and/or Speed, based on the feature flags set. A value of null indicates that the TargetState fields are unknown (typically after a reboot, no target has been yet requested). Each field is present only when its corresponding feature is supported. If the feature is not supported the field must NOT be present.

Value is a DimensionStateStruct struct (see Data Types).

Example:

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

Attribute 2 / 0x0002 — Resolution

Path example:

1/261/2

Indicates the minimal acceptable change to the Position field of the TargetState and CurrentState attributes. Resolution should not be confused with an accuracy, such as Current = Target +/- Accuracy. This cluster does not provide accuracy. Resolution gives a collection of valid Current position points over a linear ruler.

Example:

{
  "1/261/2": 1
}

Attribute 3 / 0x0003 — StepValue

Path example:

1/261/3

Indicates the size of a single step, expressed in percent100ths. When the Step command is used, each step changes the position by this amount. The value of this attribute is an integer multiple of the Resolution attribute. The StepValue should be large enough to cause a visible change in the closure's position when a Step command is invoked.

Example:

{
  "1/261/3": 1
}

Attribute 4 / 0x0004 — Unit

Path example:

1/261/4

Indicates the unit related to the Position.

Values (ClosureUnitEnum):

Example:

{
  "1/261/4": 0
}

Attribute 5 / 0x0005 — UnitRange

Path example:

1/261/5

Indicates the minimum and the maximum values expressed by Position following the unit indicated by "Unit". The value of this attribute may be null if the product has not been set up.

Value is a UnitRangeStruct struct (see Data Types).

Example:

{
  "1/261/5": {
    "min": 1,
    "max": 1
  }
}

Attribute 6 / 0x0006 — LimitRange

Path example:

1/261/6

Indicates the range of possible values for the Position field in the CurrentState attribute. This range may evolve dynamically. LimitRange.Min and LimitRange.Max is equal to an integer multiple of the Resolution attribute.

Value is a RangePercent100thsStruct struct (see Data Types).

Example:

{
  "1/261/6": {
    "min": 1,
    "max": 1
  }
}

Attribute 7 / 0x0007 — TranslationDirection

Path example:

1/261/7

Indicates the direction of the translation. A properly configured closure dimension should reflect as best as possible the translation as seen by the user. This attribute is not supposed to change once the installation is finalized.

Values (TranslationDirectionEnum):

Example:

{
  "1/261/7": 0
}

Attribute 8 / 0x0008 — RotationAxis

Path example:

1/261/8

Indicates the axis of the rotation. A properly configured closure dimension should reflect as best as possible the rotation axis as perceived by the user. This attribute is not supposed to change once the installation is finalized.

Values (RotationAxisEnum):

Example:

{
  "1/261/8": 0
}

Attribute 9 / 0x0009 — Overflow

Path example:

1/261/9

Indicates the overflow related to Rotation(RO). A closure that rotates following an axis (with Rotation(RO) feature declared in FeatureMap), could overflow Inside and/or Outside. If the axis is centered, one part goes Outside and the other part goes Inside. In this case, this attribute must use Top/Bottom/Left/Right Inside or Top/Bottom/Left/Right Outside enumerated value.

Values (OverflowEnum):

Example:

{
  "1/261/9": 0
}

Attribute 10 / 0x000A — ModulationType

Path example:

1/261/10

Indicates the modulation type related to Modulation(MD). The server should reflect, as best as possible, the modulation type as perceived by the user. This attribute is not supposed to change once the installation is finalized.

Values (ModulationTypeEnum):

Example:

{
  "1/261/10": 0
}

Attribute 11 / 0x000B — LatchControlModes

Path example:

1/261/11

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

Bits (LatchControlModesBitmap):

Example:

{
  "1/261/11": 0
}

Cluster 261 Commands

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

AcceptedCommandList

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

endpoint_id / 261 / 65529

{
  "1/261/65529": [
    0,
    1
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

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

Purpose

This command is used to move a dimension of the closure to a target position. 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

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 261,
    "command_name": "SetTarget",
    "payload": {
      "position": 1,
      "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: Step

Purpose

This command is used to move a dimension of the closure to a target position by a number of steps.

Command Identity

Payload Fields

Direction values (StepDirectionEnum): 0 = Decrease, 1 = Increase

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 261,
    "command_name": "Step",
    "payload": {
      "direction": 0,
      "numberOfSteps": 1
    },
    "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 261 Events

Cluster 261 defines no events.

SmartphoneKey Notes

• Cluster 261 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/261/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.