Matter Cluster 336 — Service Area Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 336 values in the device shadow use this format:

endpoint_id / 336 / attribute_id

Example:

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

Cluster 336 Features

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

Data Types

OperationalStatusEnum

SelectAreasStatus

SkipAreaStatus

AreaInfoStruct (struct)

The data from this structure indicates the name and/or semantic data describing an area, as detailed below. This data type includes the LocationInfo field, with the following fields: LocationName, FloorNumber, AreaType.

AreaStruct (struct)

This is a struct representing an area known to the server.

LandmarkInfoStruct (struct)

The data from this structure indicates a landmark and position relative to the landmark.

MapStruct (struct)

This is a struct representing a map.

ProgressStruct (struct)

This is a struct indicating the progress.

Cluster 336 Attributes

Cluster 336 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 — SupportedAreas

Path example:

1/336/0

This attribute contains the list of areas that can be included in the SelectedAreas attribute's list. Each item in this list represents a unique area, as indicated by the AreaID field of AreaStruct. Each entry in this list has a unique value for the AreaID field. If the SupportedMaps attribute is not empty, each entry in this list has a unique value for the combination of the MapID and AreaInfo fields.

Each entry is a AreaStruct (see Data Types).

Example:

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

Attribute 1 / 0x0001 — SupportedMaps

Path example:

1/336/1

This attribute contains the list of supported maps. A map is a full or a partial representation of a home, known to the device. For example: - a single level home may be represented using a single map - a two level home may be represented using two maps, one for each level - a single level home may be represented using two maps, each including a different set of rooms, such as "map of living room and kitchen" and "map of bedrooms and hallway" - a single level home may be represented using one map for the indoor areas (living room, bedrooms etc.) and one for the outdoor areas (garden, swimming pool etc.) Each map includes one or more areas - see the SupportedAreas attribute.

Each entry is a MapStruct (see Data Types).

Example:

{
  "1/336/1": []
}

Attribute 2 / 0x0002 — SelectedAreas

Path example:

1/336/2

Indicates the set of areas where the device should attempt to operate. The mobile devices may travel without operating across any areas while attempting to reach the areas indicated by the SelectedAreas attribute. For example, a robotic vacuum cleaner may drive without cleaning when traveling without operating. If this attribute is empty, the device is not constrained to operate in any specific areas.

Example:

{
  "1/336/2": []
}

Attribute 3 / 0x0003 — CurrentArea

Path example:

1/336/3

If the device is mobile, this attribute indicates the area where the device is currently located, regardless of whether it is operating or not, such as while traveling between areas. If the device is not mobile and can operate at multiple areas sequentially, this attribute indicates the area which is currently being serviced, or the area which is currently traversed by the device. For example, a camera device may use this attribute to indicate which area it currently takes video of (serviced area) or which area it currently has in view but not taking video of (e.g. an area which is traversed while panning).

Example:

{
  "1/336/3": 1
}

Attribute 4 / 0x0004 — EstimatedEndTime

Path example:

1/336/4

Indicates the estimated Epoch time for completing operating at the area indicated by the CurrentArea attribute, in seconds. A value of 0 means that the operation has completed. When this attribute is null, that represents that there is no time currently defined until operation completion. This may happen, for example, because no operation is in progress or because the completion time is unknown.

Example:

{
  "1/336/4": 0
}

Attribute 5 / 0x0005 — Progress

Path example:

1/336/5

Indicates the operating status at one or more areas. Each entry in this list has a unique value for the AreaID field. For each entry in this list, the AreaID field must match an entry on the SupportedAreas attribute's list. When this attribute is empty, that represents that no progress information is currently available.

Each entry is a ProgressStruct (see Data Types).

Example:

{
  "1/336/5": []
}

Cluster 336 Commands

Cluster 336 has 2 client-to-server commands and 2 responses.

AcceptedCommandList

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

endpoint_id / 336 / 65529

{
  "1/336/65529": [
    0,
    2
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

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

Purpose

This command is used to select a set of device areas, where the device is to operate. On receipt of this command the device must respond with a SelectAreasResponse command.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 336,
    "command_name": "SelectAreas",
    "payload": {
      "newAreas": []
    }
  }
}

The device answers with SelectAreasResponse (see below).

Command: SelectAreasResponse

Purpose

This command is sent by the device on receipt of the SelectAreas command.

Command Identity

Response Fields

Status values (SelectAreasStatus): 0 = Success, 1 = UnsupportedArea, 2 = InvalidInMode, 3 = InvalidSet

Command: SkipArea

Purpose

This command is used to skip the given area, and to attempt operating at other areas on the SupportedAreas attribute list. On receipt of this command the device must respond with a SkipAreaResponse command.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 336,
    "command_name": "SkipArea",
    "payload": {
      "skippedArea": 1
    }
  }
}

The device answers with SkipAreaResponse (see below).

Command: SkipAreaResponse

Purpose

This command is sent by the device on receipt of the SkipArea command.

Command Identity

Response Fields

Status values (SkipAreaStatus): 0 = Success, 1 = InvalidAreaList, 2 = InvalidInMode, 3 = InvalidSkippedArea

Cluster 336 Events

Cluster 336 defines no events.

SmartphoneKey Notes

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