Matter Cluster 152 — Device Energy Management Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 152 values in the device shadow use this format:

endpoint_id / 152 / attribute_id

Example:

{
  "1/152/0": 0
}

Cluster 152 Features

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

Data Types

AdjustmentCauseEnum

CauseEnum

CostTypeEnum

ESAStateEnum

ESATypeEnum

ForecastUpdateReasonEnum

OptOutStateEnum

PowerAdjustReasonEnum

ConstraintsStruct (struct)

The ConstraintsStruct allows a client to inform an ESA about a constraint period (such as a grid event, or perhaps excess solar PV). The format allows the client to suggest that the ESA can either turn up its energy consumption, or turn down its energy consumption during this period.

CostStruct (struct)

This indicates a generic mechanism for expressing cost to run an appliance, in terms of financial, GHG emissions, comfort value etc.

ForecastStruct (struct)

This indicates a list of 'slots' describing the overall timing of the ESA's planned energy and power use, with different power and energy demands per slot. For example, slots might be used to describe the distinct stages of a washing machine cycle.

PowerAdjustCapabilityStruct (struct)

PowerAdjustStruct (struct)

SlotAdjustmentStruct (struct)

SlotStruct (struct)

This indicates a specific stage of an ESA's operation.

Cluster 152 Attributes

Cluster 152 defines 8 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 — ESAType

Path example:

1/152/0

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

Values (ESATypeEnum):

Example:

{
  "1/152/0": 0
}

Attribute 1 / 0x0001 — ESACanGenerate

Path example:

1/152/1

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

Example:

{
  "1/152/1": true
}

Attribute 2 / 0x0002 — ESAState

Path example:

1/152/2

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

Values (ESAStateEnum):

Example:

{
  "1/152/2": 0
}

Attribute 3 / 0x0003 — AbsMinPower

Path example:

1/152/3

Indicates the minimum electrical power that the ESA can consume when switched on. This does not include when in power save or standby modes. For Generator ESAs that can discharge an internal battery (such as a battery storage inverter) to loads in the home, the AbsMinPower will be a negative number representing the maximum power that the ESA can discharge its internal battery.

Example:

{
  "1/152/3": 1
}

Attribute 4 / 0x0004 — AbsMaxPower

Path example:

1/152/4

Indicates the maximum electrical power that the ESA can consume when switched on. Note that for Generator ESAs that can charge a battery by importing power into the node (such as a battery storage inverter), the AbsMaxPower will be a positive number representing the maximum power at which the ESA can charge its internal battery. For example, a battery storage inverter that can charge its battery at a maximum power of 2000W and can discharge the battery at a maximum power of 3000W, would have a AbsMinPower: -3000, AbsMaxPower: 2000W.

Example:

{
  "1/152/4": 1
}

Attribute 5 / 0x0005 — PowerAdjustmentCapability

Path example:

1/152/5

Indicates how the ESA can be adjusted at the current time, and the state of any active adjustment. A null value indicates that no power adjustment is currently possible, and nor is any adjustment currently active. This attribute should be updated periodically by ESAs to reflect any changes in internal state, for example temperature or stored energy, which would affect the power or duration limits. Changes to this attribute only be marked as reportable in the following cases: - At most once every 10 seconds on changes, or - When it changes from null to any other value and vice versa.

Value is a PowerAdjustCapabilityStruct struct (see Data Types).

Example:

{
  "1/152/5": {
    "powerAdjustCapability": [],
    "cause": 0
  }
}

Attribute 6 / 0x0006 — Forecast

Path example:

1/152/6

This attribute allows an ESA to share its intended forecast with a client (such as an Energy Management System). A null value indicates that there is no forecast currently available (for example, a program has not yet been selected by the user). A server may reset this value attribute to null on a reboot, and it does not need to persist any previous forecasts.

Value is a ForecastStruct struct (see Data Types).

Example:

{
  "1/152/6": {
    "forecastID": 1,
    "activeSlotNumber": 1,
    "startTime": 0,
    "endTime": 0
  }
}

Attribute 7 / 0x0007 — OptOutState

Path example:

1/152/7

Indicates the current Opt-Out state of the ESA. The ESA may have a local user interface to allow the user to control this OptOutState. An EMS may subscribe to the OptOutState to get notified about changes in operational state. If the ESA is in the LocalOptOut or OptOut states, so it cannot be controlled by an EMS for local optimization reasons, it must reject any commands which have the AdjustmentCauseEnum value LocalOptimization.

Values (OptOutStateEnum):

Example:

{
  "1/152/7": 0
}

Cluster 152 Commands

Cluster 152 has 8 client-to-server commands and 0 responses.

AcceptedCommandList

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

endpoint_id / 152 / 65529

{
  "1/152/65529": [
    0,
    1,
    2,
    3,
    4,
    5,
    6,
    7
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

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

Purpose

Allows a client to request an adjustment in the power consumption of an ESA for a specified duration.

Command Identity

Payload Fields

Cause values (AdjustmentCauseEnum): 0 = LocalOptimization, 1 = GridOptimization

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 152,
    "command_name": "PowerAdjustRequest",
    "payload": {
      "power": 1,
      "duration": 1,
      "cause": 0
    }
  }
}

Command: CancelPowerAdjustRequest

Purpose

Allows a client to cancel an ongoing PowerAdjustmentRequest operation.

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": 152,
    "command_name": "CancelPowerAdjustRequest",
    "payload": {}
  }
}

Command: StartTimeAdjustRequest

Purpose

Allows a client to adjust the start time of a Forecast sequence that has not yet started operation (i.e. where the current Forecast StartTime is in the future).

Command Identity

Payload Fields

Cause values (AdjustmentCauseEnum): 0 = LocalOptimization, 1 = GridOptimization

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 152,
    "command_name": "StartTimeAdjustRequest",
    "payload": {
      "requestedStartTime": 0,
      "cause": 0
    }
  }
}

Command: PauseRequest

Purpose

Allows a client to temporarily pause an operation and reduce the ESAs energy demand.

Command Identity

Payload Fields

Cause values (AdjustmentCauseEnum): 0 = LocalOptimization, 1 = GridOptimization

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 152,
    "command_name": "PauseRequest",
    "payload": {
      "duration": 1,
      "cause": 0
    }
  }
}

Command: ResumeRequest

Purpose

Allows a client to cancel the PauseRequest command and enable earlier resumption of operation.

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": 152,
    "command_name": "ResumeRequest",
    "payload": {}
  }
}

Command: ModifyForecastRequest

Purpose

Allows a client to modify a Forecast within the limits allowed by the ESA.

Command Identity

Payload Fields

Cause values (AdjustmentCauseEnum): 0 = LocalOptimization, 1 = GridOptimization

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 152,
    "command_name": "ModifyForecastRequest",
    "payload": {
      "forecastID": 1,
      "slotAdjustments": [],
      "cause": 0
    }
  }
}

Command: RequestConstraintBasedForecast

Purpose

Allows a client to ask the ESA to recompute its Forecast based on power and time constraints.

Command Identity

Payload Fields

Cause values (AdjustmentCauseEnum): 0 = LocalOptimization, 1 = GridOptimization

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 152,
    "command_name": "RequestConstraintBasedForecast",
    "payload": {
      "constraints": [],
      "cause": 0
    }
  }
}

Command: CancelRequest

Purpose

Allows a client to request cancellation of a previous adjustment request in a StartTimeAdjustRequest, ModifyForecastRequest or RequestConstraintBasedForecast command.

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": 152,
    "command_name": "CancelRequest",
    "payload": {}
  }
}

Cluster 152 Events

Event 0 — PowerAdjustStart

This event is generated when the Power Adjustment session is started.

This event has no fields.

Event 1 — PowerAdjustEnd

This event is generated when the Power Adjustment session ends.

Event 2 — Paused

This event is generated when the ESA enters the Paused state. There is no data for this event.

This event has no fields.

Event 3 — Resumed

This event is generated when the ESA leaves the Paused state and resumes operation.

SmartphoneKey Notes

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