Matter Cluster 148 — Water Heater Management Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 148 values in the device shadow use this format:

endpoint_id / 148 / attribute_id

Example:

{
  "1/148/0": 0
}

Cluster 148 Features

The FeatureMap attribute (1/148/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

BoostStateEnum

WaterHeaterHeatSourceBitmap (bitmap)

WaterHeaterBoostInfoStruct (struct)

Cluster 148 Attributes

Cluster 148 defines 6 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 — HeaterTypes

Path example:

1/148/0

Indicates the heat sources that the water heater can call on for heating. If a bit is set then the water heater supports the corresponding heat source.

Bits (WaterHeaterHeatSourceBitmap):

Example:

{
  "1/148/0": 0
}

Attribute 1 / 0x0001 — HeatDemand

Path example:

1/148/1

Indicates if the water heater is heating water. If a bit is set then the corresponding heat source is active.

Bits (WaterHeaterHeatSourceBitmap):

Example:

{
  "1/148/1": 0
}

Attribute 2 / 0x0002 — TankVolume

Path example:

1/148/2

Indicates the volume of water that the hot water tank can hold (in units of Litres). This allows an energy management system to estimate the required heating energy needed to reach the target temperature.

Example:

{
  "1/148/2": 1
}

Attribute 3 / 0x0003 — EstimatedHeatRequired

Path example:

1/148/3

Indicates the estimated heat energy needed to raise the water temperature to the target setpoint. This can be computed by taking the specific heat capacity of water (4182 J/kg °C) and by knowing the current temperature of the water, the tank volume and target temperature.

Example:

{
  "1/148/3": 1
}

Attribute 4 / 0x0004 — TankPercentage

Path example:

1/148/4

Indicates an approximate level of hot water stored in the tank, which might help consumers understand the amount of hot water remaining in the tank. The accuracy of this attribute is manufacturer specific. In most hot water tanks, there is a stratification effect where the hot water layer rests above a cooler layer of water below. For this reason cold water is fed in at the bottom of the tank and the hot water is drawn from the top.

Example:

{
  "1/148/4": 1
}

Attribute 5 / 0x0005 — BoostState

Path example:

1/148/5

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

Values (BoostStateEnum):

Example:

{
  "1/148/5": 0
}

Cluster 148 Commands

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

AcceptedCommandList

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

endpoint_id / 148 / 65529

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

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

Purpose

Allows a client to request that the water heater is put into a Boost state.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 148,
    "command_name": "Boost",
    "payload": {
      "boostInfo": {
        "duration": 1,
        "oneShot": true,
        "emergencyBoost": true,
        "temporarySetpoint": 1
      }
    }
  }
}

Command: CancelBoost

Purpose

Allows a client to cancel an ongoing Boost operation. This command has no payload.

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": 148,
    "command_name": "CancelBoost",
    "payload": {}
  }
}

Cluster 148 Events

Event 0 — BoostStarted

This event is generated whenever a Boost command is accepted. The corresponding structure fields within the WaterHeaterBoostInfoStruct are copied from the Boost command.

Event 1 — BoostEnded

This event is generated whenever the BoostState transitions from Active to Inactive.

This event has no fields.

SmartphoneKey Notes

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