Matter Cluster 42 — OTA Software Update Requestor Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 42 values in the device shadow use this format:

endpoint_id / 42 / attribute_id

Example:

{
  "0/42/1": true
}

Data Types

AnnouncementReasonEnum

ChangeReasonEnum

UpdateStateEnum

ProviderLocation (struct) — fabric-scoped

This structure encodes a fabric-scoped location of an OTA provider on a given fabric.

Cluster 42 Attributes

Cluster 42 defines 4 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 — DefaultOTAProviders

Path example:

0/42/0

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

Each entry is a ProviderLocation (see Data Types).

Example:

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

Attribute 1 / 0x0001 — UpdatePossible

Path example:

0/42/1

This field is set to True if the OTA Requestor is currently able to be updated. Otherwise, it is set to False in case of any condition preventing update being possible, such as insufficient capacity of an internal battery. This field is merely informational for diagnostics purposes and must NOT affect the responses provided by an OTA Provider to an OTA Requestor.

Example:

{
  "0/42/1": true
}

Attribute 2 / 0x0002 — UpdateState

Path example:

0/42/2

This field should be updated in a timely manner whenever OTA Requestor internal state updates.

Values (UpdateStateEnum):

Example:

{
  "0/42/2": 1
}

Attribute 3 / 0x0003 — UpdateStateProgress

Path example:

0/42/3

This field reflects the percentage value of progress, relative to the current UpdateState, if applicable to the state. The value of this field is null if a progress indication does not apply to the current state. A value of 0 indicates that the beginning has occurred. A value of 100 indicates completion.

Example:

{
  "0/42/3": 0
}

Cluster 42 Commands

Cluster 42 has 1 client-to-server command and 0 responses.

AcceptedCommandList

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

endpoint_id / 42 / 65529

{
  "0/42/65529": [
    0
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

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

Purpose

AnnounceOTAProvider is a client-to-server command of the OTA Software Update Requestor cluster.

Command Identity

Payload Fields

AnnouncementReason values (AnnouncementReasonEnum): 0 = SimpleAnnouncement, 1 = UpdateAvailable, 2 = UrgentUpdateAvailable

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 42,
    "command_name": "AnnounceOTAProvider",
    "payload": {
      "providerNodeID": 1,
      "vendorID": 1,
      "announcementReason": 0,
      "endpoint": 1
    }
  }
}

Cluster 42 Events

Event 0 — StateTransition

This event is generated when a change of the UpdateState attribute occurs due to an OTA Requestor moving through the states necessary to query for updates.

Event 1 — VersionApplied

This event is generated whenever a new version starts executing after being applied due to a software update. This event should be generated even if a software update was done using means outside of this cluster.

Event 2 — DownloadError

This event is generated whenever an error occurs during OTA Requestor download operation.

SmartphoneKey Notes

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