Matter Cluster 258 — Window Covering Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 258 values in the device shadow use this format:

endpoint_id / 258 / attribute_id

Example:

{
  "1/258/0": 0
}

Cluster 258 Features

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

Data Types

EndProductTypeEnum

TypeEnum

ConfigStatusBitmap (bitmap)

ModeBitmap (bitmap)

OperationalStatusBitmap (bitmap)

The OperationalStatusBitmap is using several internal operational state fields (composed of 2 bits) following this definition: - 00b = Currently not moving - 01b = Currently opening (e.g. moving from closed to open). - 10b = Currently closing (e.g. moving from open to closed). - 11b = Reserved

SafetyStatusBitmap (bitmap)

Cluster 258 Attributes

Cluster 258 defines 14 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 — Type

Path example:

1/258/0

This attribute identifies the type of window covering. If the window covering supports the LF feature and not the TL feature, the following types is used as the constraint for this attribute: If the window covering supports the TL feature and not the LF feature, the following types is used as the constraint for this attribute: If the window covering supports both the LF and TL features, the following types are allowed to be used:

Values (TypeEnum):

Example:

{
  "1/258/0": 0
}

Attribute 5 / 0x0005 — NumberOfActuationsLift

Path example:

1/258/5

Indicates the total number of lift/slide actuations applied to the window covering since the device was installed.

Example:

{
  "1/258/5": 1
}

Attribute 6 / 0x0006 — NumberOfActuationsTilt

Path example:

1/258/6

Indicates the total number of tilt actuations applied to the window covering since the device was installed.

Example:

{
  "1/258/6": 1
}

Attribute 7 / 0x0007 — ConfigStatus

Path example:

1/258/7

This attribute specifies the configuration and status information of the window covering. To change settings, devices must write to the Mode attribute. The behavior causing the setting or clearing of each bit is vendor specific.

Bits (ConfigStatusBitmap):

Example:

{
  "1/258/7": 0
}

Attribute 8 / 0x0008 — CurrentPositionLiftPercentage

Path example:

1/258/8

Indicates the actual position as a percentage from 0% to 100% with 1% default step. This attribute is equal to CurrentPositionLiftPercent100ths attribute divided by 100.

Example:

{
  "1/258/8": 1
}

Attribute 9 / 0x0009 — CurrentPositionTiltPercentage

Path example:

1/258/9

Indicates the actual position as a percentage from 0% to 100% with 1% default step. This attribute is equal to CurrentPositionTiltPercent100ths attribute divided by 100.

Example:

{
  "1/258/9": 1
}

Attribute 10 / 0x000A — OperationalStatus

Path example:

1/258/10

Indicates the currently ongoing operations and applies to all type of devices.

Bits (OperationalStatusBitmap):

Example:

{
  "1/258/10": 0
}

Attribute 11 / 0x000B — TargetPositionLiftPercent100ths

Path example:

1/258/11

Indicates the position where the window covering lift will go or is moving to as a percentage (Unit 0.01%).

Example:

{
  "1/258/11": 1
}

Attribute 12 / 0x000C — TargetPositionTiltPercent100ths

Path example:

1/258/12

Indicates the position where the window covering tilt will go or is moving to as a percentage (Unit 0.01%).

Example:

{
  "1/258/12": 1
}

Attribute 13 / 0x000D — EndProductType

Path example:

1/258/13

This attribute should provide more detail about the product type than can be determined from the main category indicated by the Type attribute. If the window covering supports the LF feature and not the TL feature, the following types is used as the constraint for this attribute: If the window covering supports the TL feature and not the LF feature, the following types is used as the constraint for this attribute: If the window covering supports both the LF and TL features, the following types are allowed to be used: The table below helps to match the EndProductType attribute with the Type attribute.

Values (EndProductTypeEnum):

Example:

{
  "1/258/13": 0
}

Attribute 14 / 0x000E — CurrentPositionLiftPercent100ths

Path example:

1/258/14

Indicates the actual position as a percentage with a minimal step of 0.01%. E.g Max 10000 equals 100.00%.

Example:

{
  "1/258/14": 1
}

Attribute 15 / 0x000F — CurrentPositionTiltPercent100ths

Path example:

1/258/15

Indicates the actual position as a percentage with a minimal step of 0.01%. E.g Max 10000 equals 100.00%.

Example:

{
  "1/258/15": 1
}

Attribute 23 / 0x0017 — Mode

Path example:

1/258/23

The Mode attribute allows configuration of the window covering, such as: reversing the motor direction, placing the window covering into calibration mode, placing the motor into maintenance mode, disabling the network, and disabling status LEDs. In the case a device does not support or implement a specific mode, e.g. the device has a specific installation method and reversal is not relevant or the device does not include a maintenance mode, any write interaction to the Mode attribute, with an unsupported mode bit or any out of bounds bits set, must be ignored and a response containing the status of CONSTRAINT_ERROR will be returned.

Bits (ModeBitmap):

Example:

{
  "1/258/23": 0
}

Attribute 26 / 0x001A — SafetyStatus

Path example:

1/258/26

The SafetyStatus attribute reflects the state of the safety sensors and the common issues preventing movements. By default for nominal operation all flags are cleared (0). A device might support none, one or several bit flags from this attribute (all optional).

Bits (SafetyStatusBitmap):

Example:

{
  "1/258/26": 0
}

Cluster 258 Commands

Cluster 258 has 5 client-to-server commands and 0 responses.

AcceptedCommandList

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

endpoint_id / 258 / 65529

{
  "1/258/65529": [
    0,
    1,
    2,
    5,
    8
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

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

Purpose

On receipt, the window covering will adjust its position so the physical lift/slide and tilt is at the maximum open/up position. This will happen as fast as possible. The server attributes is updated as follows: if the PositionAware feature is supported: - TargetPositionLiftPercent100ths attribute is set to 0.00%. - TargetPositionTiltPercent100ths attribute is set to 0.00%.

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": 258,
    "command_name": "UpOrOpen",
    "payload": {}
  }
}

Command: DownOrClose

Purpose

On receipt, the window covering will adjust its position so the physical lift/slide and tilt is at the maximum closed/down position. This will happen as fast as possible. The server attributes supported is updated as follows: if the PositionAware feature is supported: - TargetPositionLiftPercent100ths attribute is set to 100.00%. - TargetPositionTiltPercent100ths attribute is set to 100.00%.

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": 258,
    "command_name": "DownOrClose",
    "payload": {}
  }
}

Command: StopMotion

Purpose

On receipt, the window covering will stop any adjusting to the physical tilt and lift/slide that is currently occurring. The server attributes supported is updated as follows: - TargetPositionLiftPercent100ths attribute will be set to CurrentPositionLiftPercent100ths attribute value. - TargetPositionTiltPercent100ths attribute will be set to CurrentPositionTiltPercent100ths attribute value.

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": 258,
    "command_name": "StopMotion",
    "payload": {}
  }
}

Command: GoToLiftPercentage

Purpose

This command is used to set the target lift position of the window covering to the percentage value specified in the command. Upon receipt of this command, the server will adjust the window covering to the lift/slide percentage specified in the payload of this command. If the command includes LiftPercent100thsValue, then TargetPositionLiftPercent100ths attribute is set to LiftPercent100thsValue. Otherwise the TargetPositionLiftPercent100ths attribute is set to LiftPercentageValue * 100.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 258,
    "command_name": "GoToLiftPercentage",
    "payload": {
      "liftPercent100thsValue": 1
    }
  }
}

Command: GoToTiltPercentage

Purpose

This command is used to set the target tilt position of the window covering to the percentage value specified in the command. Upon receipt of this command, the server will adjust the window covering to the tilt percentage specified in the payload of this command. If the command includes TiltPercent100thsValue, then TargetPositionTiltPercent100ths attribute is set to TiltPercent100thsValue. Otherwise the TargetPositionTiltPercent100ths attribute is set to TiltPercentageValue * 100.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 258,
    "command_name": "GoToTiltPercentage",
    "payload": {
      "tiltPercent100thsValue": 1
    }
  }
}

Cluster 258 Events

Cluster 258 defines no events.

SmartphoneKey Notes

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