Matter Cluster 129 — Valve Configuration and Control Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 129 values in the device shadow use this format:

endpoint_id / 129 / attribute_id

Example:

{
  "1/129/0": 1
}

Cluster 129 Features

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

Data Types

StatusCodeEnum

ValveStateEnum

ValveFaultBitmap (bitmap)

Cluster 129 Attributes

Cluster 129 defines 11 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 — OpenDuration

Path example:

1/129/0

Indicates the total duration, in seconds, for which the valve will remain open for this current opening. A value of null indicates the duration is not set, meaning that the valve will remain open until closed by the user or some other automation.

Example:

{
  "1/129/0": 1
}

Attribute 1 / 0x0001 — DefaultOpenDuration

Path example:

1/129/1

Indicates the default duration, in seconds, for which the valve will remain open, if the OpenDuration field is not present in the Open command. A value of null indicates the duration is not set, meaning that the valve will remain open until closed by the user or some other automation.

Example:

{
  "1/129/1": 1
}

Attribute 2 / 0x0002 — AutoCloseTime

Path example:

1/129/2

Indicates the UTC time when the valve will close, depending on value of the OpenDuration attribute. Null: - When OpenDuration is null, or - When the valve does not have a synchronized UTCTime in the Time Synchronization cluster, or - When the valve is closed. When the value of this attribute is earlier or equal to the current UTC time, the valve must automatically transition to its closed position. The behavior of transitioning to the closed position, must match the behavior described in the Close command.

Example:

{
  "1/129/2": 0
}

Attribute 3 / 0x0003 — RemainingDuration

Path example:

1/129/3

Indicates the remaining duration, in seconds, until the valve closes. Null: - When OpenDuration is null, or - When the valve is closed. The value of this attribute only be reported in the following cases: - When it changes from null to any other value and vice versa, or - When it changes to 0, or - When it increases, or - When the closing time changes. Meaning that clients should NOT rely on the reporting of this attribute in order to keep track of the remaining duration, due to this attribute not being reported during regular countdown.

Example:

{
  "1/129/3": 1
}

Attribute 4 / 0x0004 — CurrentState

Path example:

1/129/4

Indicates the current state of the valve. A value of null indicates that the current state is not known.

Values (ValveStateEnum):

Example:

{
  "1/129/4": 0
}

Attribute 5 / 0x0005 — TargetState

Path example:

1/129/5

Indicates the target state, while changing the state, of the valve. A value of null indicates that no target position is set, since the change in state is either done or failed.

Values (ValveStateEnum):

Example:

{
  "1/129/5": 0
}

Attribute 6 / 0x0006 — CurrentLevel

Path example:

1/129/6

Indicates the current level of the valve as a percentage value, between fully closed and fully open. During a transition from one level to another level, the valve should keep this attribute updated to the best of its ability, in order to represent the actual level of the valve during the movement. A value of 100 percent indicates the fully open position. A value of 0 percent indicates the fully closed position.

Example:

{
  "1/129/6": 100
}

Attribute 7 / 0x0007 — TargetLevel

Path example:

1/129/7

Indicates the target level of the valve as a percentage value, between fully closed and fully open. The interpretation of the percentage value is the same as for the CurrentLevel attribute. A value of null indicates that no target position is set, since the change of level is either done or failed.

Example:

{
  "1/129/7": 100
}

Attribute 8 / 0x0008 — DefaultOpenLevel

Path example:

1/129/8

Indicates the default value used for the TargetLevel attribute, when a valve transitions from the closed to the open state, caused by an Open command, if a TargetLevel field is not present in the Open command. If the LevelStep attribute is present and the value of a write interaction to this attribute field is not 100, the value is a supported value as defined by the LevelStep attribute, such that (Value received in the write interaction) % (Value of LevelStep attribute) equals 0. If the resulting value is not 0, the requested DefaultOpenLevel value is considered an unsupported value and a CONSTRAINT_ERROR status is returned.

Example:

{
  "1/129/8": 100
}

Attribute 9 / 0x0009 — ValveFault

Path example:

1/129/9

Indicates any faults registered by the valve.

Bits (ValveFaultBitmap):

Example:

{
  "1/129/9": 0
}

Attribute 10 / 0x000A — LevelStep

Path example:

1/129/10

Indicates the step size the valve can support. The step size defined by this attribute is counted from 0 and the final step towards 100 may be different than what is defined in this attribute. For example, if the value of this attribute is 15, it results in these target values being supported; 0, 15, 30, 45, 60, 75, 90 and 100. The values of 0 and 100 must always be supported, regardless of the value of this attribute.

Example:

{
  "1/129/10": 1
}

Cluster 129 Commands

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

AcceptedCommandList

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

endpoint_id / 129 / 65529

{
  "1/129/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": 129,
    "command_name": "Open",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

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

Purpose

This command is used to set the valve to its open position.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 129,
    "command_name": "Open",
    "payload": {
      "openDuration": 1,
      "targetLevel": 100
    }
  }
}

Command: Close

Purpose

This command is used to set the valve to its closed position.

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": 129,
    "command_name": "Close",
    "payload": {}
  }
}

Cluster 129 Events

Event 0 — ValveStateChanged

This event is generated when the valve state changed. For level changes, after the end of movement, for state changes when the new state has been reached.

Event 1 — ValveFault

This event is generated when the valve registers or clears a fault, e.g. not being able to transition to the requested target level or state.

SmartphoneKey Notes

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