Matter Cluster 37 — Actions Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 37 values in the device shadow use this format:

endpoint_id / 37 / attribute_id

Example:

{
  "0/37/0": []
}

Data Types

ActionErrorEnum

ActionStateEnum

Note that some of these states are applicable only for certain actions, as determined by their SupportedCommands.

ActionTypeEnum

EndpointListTypeEnum

The Room and Zone values are provided for the cases where a user (or the system on behalf of the user) has created logical grouping of the endpoints (e.g. bridged devices) based on location.

CommandBits (bitmap)

Note - The bit allocation of this bitmap must follow the ID's of the Commands of this cluster.

ActionStruct (struct)

This data type holds the details of a single action, and contains the data fields below.

EndpointListStruct (struct)

This data type holds the details of a single endpoint list, which relates to a set of endpoints that have some logical relation, and contains the data fields below.

Cluster 37 Attributes

Cluster 37 defines 3 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 — ActionList

Path example:

0/37/0

The ActionList attribute holds the list of actions. Each entry has an unique ActionID, and its EndpointListID must exist in the EndpointLists attribute.

Each entry is a ActionStruct (see Data Types).

Example:

{
  "0/37/0": []
}

Attribute 1 / 0x0001 — EndpointLists

Path example:

0/37/1

The EndpointLists attribute holds the list of endpoint lists. Each entry has an unique EndpointListID.

Each entry is a EndpointListStruct (see Data Types).

Example:

{
  "0/37/1": []
}

Attribute 2 / 0x0002 — SetupURL

Path example:

0/37/2

No condensed specification text is available for SetupURL; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/37/2": "example"
}

Cluster 37 Commands

Cluster 37 has 12 client-to-server commands and 0 responses.

AcceptedCommandList

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

endpoint_id / 37 / 65529

{
  "0/37/65529": [
    0,
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    10,
    11
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 37,
    "command_name": "InstantAction",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

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

Purpose

This command is used to trigger an instantaneous action. This command triggers an action (state change) on the involved endpoints, in a "fire and forget" manner. Afterwards, the action's state is Inactive. Example: recall a scene on a number of lights.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 37,
    "command_name": "InstantAction",
    "payload": {
      "actionID": 1
    }
  }
}

Command: InstantActionWithTransition

Purpose

This command is used to trigger an instantaneous action with a transition over a given time. It is recommended that, where possible (e.g., it is not possible for attributes with Boolean data type), a gradual transition should take place from the old to the new state over this time period. However, the exact transition is manufacturer dependent. This command triggers an action (state change) on the involved endpoints, with a specified time to transition from the current state to the new state.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 37,
    "command_name": "InstantActionWithTransition",
    "payload": {
      "actionID": 1,
      "transitionTime": 0
    }
  }
}

Command: StartAction

Purpose

This command is used to trigger the commencement of an action. This command triggers the commencement of an action on the involved endpoints. Afterwards, the action's state is Active. Example: start a dynamic lighting pattern (such as gradually rotating the colors around the setpoints of the scene) on a set of lights.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 37,
    "command_name": "StartAction",
    "payload": {
      "actionID": 1
    }
  }
}

Command: StartActionWithDuration

Purpose

This command is used to trigger the commencement of an action with a duration. This command triggers the commencement of an action on the involved endpoints, and must change the action's state to Active. After the specified Duration, the action will stop, and the action's state must change to Inactive. Example: start a dynamic lighting pattern (such as gradually rotating the colors around the setpoints of the scene) on a set of lights for 1 hour (Duration=3600).

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 37,
    "command_name": "StartActionWithDuration",
    "payload": {
      "actionID": 1,
      "duration": 1
    }
  }
}

Command: StopAction

Purpose

This command is used to stop an action. This command stops the ongoing action on the involved endpoints. Afterwards, the action's state is Inactive. Example: stop a dynamic lighting pattern which was previously started with StartAction.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 37,
    "command_name": "StopAction",
    "payload": {
      "actionID": 1
    }
  }
}

Command: PauseAction

Purpose

This command is used to pause an action. This command pauses an ongoing action, and must change the action's state to Paused. Example: pause a dynamic lighting effect (the lights stay at their current color) which was previously started with StartAction.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 37,
    "command_name": "PauseAction",
    "payload": {
      "actionID": 1
    }
  }
}

Command: PauseActionWithDuration

Purpose

This command is used to pause an action with a duration. This command pauses an ongoing action, and must change the action's state to Paused. After the specified Duration, the ongoing action will be automatically resumed. which must change the action's state to Active. Example: pause a dynamic lighting effect (the lights stay at their current color) for 10 minutes (Duration=600).

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 37,
    "command_name": "PauseActionWithDuration",
    "payload": {
      "actionID": 1,
      "duration": 1
    }
  }
}

Command: ResumeAction

Purpose

This command is used to resume an action. This command resumes a previously paused action, and must change the action's state to Active. The difference between ResumeAction and StartAction is that ResumeAction will continue the action from the state where it was paused, while StartAction will start the action from the beginning. Example: resume a dynamic lighting effect (the lights' colors will change gradually, continuing from the point they were paused).

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 37,
    "command_name": "ResumeAction",
    "payload": {
      "actionID": 1
    }
  }
}

Command: EnableAction

Purpose

This command is used to enable an action. This command enables a certain action or automation. Afterwards, the action's state is Active. Example: enable a motion sensor to control the lights in an area.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 37,
    "command_name": "EnableAction",
    "payload": {
      "actionID": 1
    }
  }
}

Command: EnableActionWithDuration

Purpose

This command is used to enable an action with a duration. This command enables a certain action or automation, and must change the action's state to be Active. After the specified Duration, the action or automation will stop, and the action's state must change to Disabled. Example: enable a "presence mimicking" behavior for the lights in your home during a vacation; the Duration field is used to indicated the length of your absence from home.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 37,
    "command_name": "EnableActionWithDuration",
    "payload": {
      "actionID": 1,
      "duration": 1
    }
  }
}

Command: DisableAction

Purpose

This command is used to disable an action. This command disables a certain action or automation, and must change the action's state to Inactive. Example: disable a motion sensor to no longer control the lights in an area.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 37,
    "command_name": "DisableAction",
    "payload": {
      "actionID": 1
    }
  }
}

Command: DisableActionWithDuration

Purpose

This command is used to disable an action with a duration. This command disables a certain action or automation, and must change the action's state to Disabled. After the specified Duration, the action or automation will re-start, and the action's state must change to either Inactive or Active, depending on the actions. Example: disable a "wakeup" experience for a period of 1 week when going on holiday (to prevent them from turning on in the morning while you're not at home).

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 37,
    "command_name": "DisableActionWithDuration",
    "payload": {
      "actionID": 1,
      "duration": 1
    }
  }
}

Cluster 37 Events

Event 0 — StateChanged

This event is generated when there is a change in the State of an ActionID during the execution of an action and the most recent command using that ActionID used an InvokeID data field. It provides feedback to the client about the progress of the action. Example: When InstantActionWithTransition is invoked (with an InvokeID data field), two StateChanged events will be generated: - one when the transition starts (NewState=Active) - one when the transition completed (NewState=Inactive)

Event 1 — ActionFailed

This event is generated when there is some error which prevents the action from its normal planned execution and the most recent command using that ActionID used an InvokeID data field. It provides feedback to the client about the non-successful progress of the action.

SmartphoneKey Notes

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