Matter Cluster 41 — OTA Software Update Provider Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 41 values in the device shadow use this format:

endpoint_id / 41 / attribute_id

Data Types

ApplyUpdateActionEnum

This enumeration is used in the Action field of the ApplyUpdateResponse command. See (Action).

DownloadProtocolEnum

Note that only HTTP over TLS (HTTPS) is supported. Using HTTP without TLS must NOT be supported, as there is no way to authenticate the involved participants.

StatusEnum

Cluster 41 Attributes

Cluster 41 defines no cluster-specific attributes; only the global attributes are present.

Global attributes

Cluster 41 Commands

Cluster 41 has 3 client-to-server commands and 2 responses.

AcceptedCommandList

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

endpoint_id / 41 / 65529

{
  "0/41/65529": [
    0,
    2,
    4
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

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

Purpose

On receipt, this command must trigger an attempt to find an updated Software Image by the OTA Provider to match the OTA Requestor's constraints provided in the payload fields.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 41,
    "command_name": "QueryImage",
    "payload": {
      "vendorID": 1,
      "productID": 1,
      "softwareVersion": 1,
      "protocolsSupported": []
    }
  }
}

The device answers with QueryImageResponse (see below).

Command: QueryImageResponse

Purpose

This command is sent in response to the QueryImage command.

Command Identity

Response Fields

Status values (StatusEnum): 0 = UpdateAvailable, 1 = Busy, 2 = NotAvailable, 3 = DownloadProtocolNotSupported

Command: ApplyUpdateRequest

Purpose

This command requests the specified version be installed on the device.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 41,
    "command_name": "ApplyUpdateRequest",
    "payload": {
      "updateToken": "AQID",
      "newVersion": 1
    }
  }
}

The device answers with ApplyUpdateResponse (see below).

Command: ApplyUpdateResponse

Purpose

This command is sent in response to the ApplyUpdateRequest command.

Command Identity

Response Fields

Action values (ApplyUpdateActionEnum): 0 = Proceed, 1 = AwaitNextAction, 2 = Discontinue

Command: NotifyUpdateApplied

Purpose

This command tells the Provider that the specified update has been applied.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 41,
    "command_name": "NotifyUpdateApplied",
    "payload": {
      "updateToken": "AQID",
      "softwareVersion": 1
    }
  }
}

Cluster 41 Events

Cluster 41 defines no events.

SmartphoneKey Notes

• Cluster 41 is present on SmartphoneKey devices or hubs today. See Matter Bridge Clusters — Detailed Reference and Matter Device Attributes & Commands for the values the bridge actually reports.
• Shadow paths follow endpoint/41/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.