/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ /*** THIS FILE IS GENERATED, DO NOT EDIT ***/ import type { ClusterType, ClusterTyping } from "../cluster/ClusterType.js"; import type { ClusterId } from "../datatype/ClusterId.js"; import type { ClusterModel } from "@matter/model"; import type { MaybePromise, Bytes } from "@matter/general"; import type { NodeId } from "../datatype/NodeId.js"; import type { EndpointNumber } from "../datatype/EndpointNumber.js"; import type { FabricIndex } from "../datatype/FabricIndex.js"; import type { VendorId } from "../datatype/VendorId.js"; /** * Definitions for the OtaSoftwareUpdateRequestor cluster. * * This cluster implements the Requestor role in the OTA process. * * @see {@link MatterSpecification.v151.Core} § 11.20.7 */ export declare namespace OtaSoftwareUpdateRequestor { /** * The Matter protocol cluster identifier. */ export const id: ClusterId & 0x002a; /** * Textual cluster identifier. */ export const name: "OtaSoftwareUpdateRequestor"; /** * The cluster revision assigned by {@link MatterSpecification.v151.Cluster}. */ export const revision: 1; /** * Canonical metadata for the OtaSoftwareUpdateRequestor cluster. * * This is the exhaustive runtime metadata source that matter.js considers canonical. */ export const schema: ClusterModel; /** * {@link OtaSoftwareUpdateRequestor} always supports these elements. */ export interface BaseAttributes { /** * This field is a list of ProviderLocation whose entries shall be set by Administrators, either during * Commissioning or at a later time, to set the ProviderLocation for the default OTA Provider Node to use for * software updates on a given Fabric. * * There shall NOT be more than one entry per Fabric. On a list update that would introduce more than one entry * per fabric, the write shall fail with CONSTRAINT_ERROR status code. * * Provider Locations obtained using the AnnounceOTAProvider command shall NOT overwrite values set in the * DefaultOTAProviders attribute. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.5.1 */ defaultOtaProviders: ProviderLocation[]; /** * This field shall be set to True if the OTA Requestor is currently able to be updated. Otherwise, it shall be * 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 shall NOT affect the * responses provided by an OTA Provider to an OTA Requestor. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.5.2 */ updatePossible: boolean; /** * This field shall reflect the current state of the OTA Requestor with regards to obtaining software updates. * See Section 11.20.7.4.2, "UpdateStateEnum Type" for possible values. * * This field SHOULD be updated in a timely manner whenever OTA Requestor internal state updates. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.5.3 */ updateState: UpdateState; /** * This field shall reflect the percentage value of progress, relative to the current UpdateState, if applicable * to the state. * * The value of this field shall be null if a progress indication does not apply to the current state. * * A value of 0 shall indicate that the beginning has occurred. A value of 100 shall indicate completion. * * This field may be updated infrequently. Some care SHOULD be taken by Nodes to avoid over-reporting progress * when this attribute is part of a subscription. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.5.4 */ updateStateProgress: number | null; } /** * Attributes that may appear in {@link OtaSoftwareUpdateRequestor}. */ export interface Attributes { /** * This field is a list of ProviderLocation whose entries shall be set by Administrators, either during * Commissioning or at a later time, to set the ProviderLocation for the default OTA Provider Node to use for * software updates on a given Fabric. * * There shall NOT be more than one entry per Fabric. On a list update that would introduce more than one entry * per fabric, the write shall fail with CONSTRAINT_ERROR status code. * * Provider Locations obtained using the AnnounceOTAProvider command shall NOT overwrite values set in the * DefaultOTAProviders attribute. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.5.1 */ defaultOtaProviders: ProviderLocation[]; /** * This field shall be set to True if the OTA Requestor is currently able to be updated. Otherwise, it shall be * 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 shall NOT affect the * responses provided by an OTA Provider to an OTA Requestor. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.5.2 */ updatePossible: boolean; /** * This field shall reflect the current state of the OTA Requestor with regards to obtaining software updates. * See Section 11.20.7.4.2, "UpdateStateEnum Type" for possible values. * * This field SHOULD be updated in a timely manner whenever OTA Requestor internal state updates. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.5.3 */ updateState: UpdateState; /** * This field shall reflect the percentage value of progress, relative to the current UpdateState, if applicable * to the state. * * The value of this field shall be null if a progress indication does not apply to the current state. * * A value of 0 shall indicate that the beginning has occurred. A value of 100 shall indicate completion. * * This field may be updated infrequently. Some care SHOULD be taken by Nodes to avoid over-reporting progress * when this attribute is part of a subscription. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.5.4 */ updateStateProgress: number | null; } /** * {@link OtaSoftwareUpdateRequestor} always supports these elements. */ export interface BaseCommands { /** * This command may be invoked by Administrators to announce the presence of a particular OTA Provider. * * This command shall be scoped to the accessing fabric. * * If the accessing fabric index is 0, this command shall fail with an UNSUPPORTED_ACCESS status code. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.6.1 */ announceOtaProvider(request: AnnounceOtaProviderRequest): MaybePromise; } /** * Commands that may appear in {@link OtaSoftwareUpdateRequestor}. */ export interface Commands extends BaseCommands {} /** * {@link OtaSoftwareUpdateRequestor} always supports these elements. */ export interface BaseEvents { /** * This event shall be generated when a change of the UpdateState attribute occurs due to an OTA Requestor * moving through the states necessary to query for updates. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.1 */ stateTransition: StateTransitionEvent; /** * This event shall be 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. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.2 */ versionApplied: VersionAppliedEvent; /** * This event shall be generated whenever an error occurs during OTA Requestor download operation. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.3 */ downloadError: DownloadErrorEvent; } /** * Events that may appear in {@link OtaSoftwareUpdateRequestor}. */ export interface Events { /** * This event shall be generated when a change of the UpdateState attribute occurs due to an OTA Requestor * moving through the states necessary to query for updates. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.1 */ stateTransition: StateTransitionEvent; /** * This event shall be 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. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.2 */ versionApplied: VersionAppliedEvent; /** * This event shall be generated whenever an error occurs during OTA Requestor download operation. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.3 */ downloadError: DownloadErrorEvent; } export type Components = [{ flags: {}, attributes: BaseAttributes, commands: BaseCommands, events: BaseEvents }]; /** * This structure encodes a fabric-scoped location of an OTA provider on a given fabric. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.4 */ export class ProviderLocation { constructor(values?: Partial); /** * This field shall contain the Node ID of the OTA Provider to contact within the Fabric identified by the * FabricIndex. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.4.1 */ providerNodeId: NodeId; /** * This field shall contain the endpoint number which has the OTA Provider device type and OTA Software Update * Provider cluster server on the ProviderNodeID. This is provided to avoid having to do discovery of the * location of that endpoint by walking over all endpoints and checking their Descriptor Cluster. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.4.2 */ endpoint: EndpointNumber; fabricIndex: FabricIndex; } /** * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.2 */ export enum UpdateState { /** * Current state is not yet determined. * * This value shall indicate that the current state is not yet determined. Nodes SHOULD attempt a better state * reporting. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.2.1 */ Unknown = 0, /** * Indicate a Node not yet in the process of software update. * * This value shall indicate a Node not yet in the process of software update, for example because it is * awaiting the moment when a query will be made. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.2.2 */ Idle = 1, /** * Indicate a Node in the process of querying an OTA Provider. * * This value shall indicate a Node in the process of querying an OTA Provider with QueryImage command, * including during the process of awaiting a response to that command. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.2.3 */ Querying = 2, /** * Indicate a Node waiting after a Busy response. * * This value shall indicate a Node waiting because it received a prior QueryImageResponse with a Status field * indicating Busy. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.2.4 */ DelayedOnQuery = 3, /** * Indicate a Node currently in the process of downloading a software update. * * This value shall indicate a Node currently in the process of downloading a software update. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.2.5 */ Downloading = 4, /** * Indicate a Node currently in the process of verifying and applying a software update. * * This value shall indicate a Node currently in the process of verifying and applying a software update. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.2.6 */ Applying = 5, /** * Indicate a Node waiting caused by AwaitNextAction response. * * This value shall indicate a Node waiting because it received a prior ApplyUpdateResponse with an Action field * set to AwaitNextAction. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.2.7 */ DelayedOnApply = 6, /** * Indicate a Node in the process of recovering to a previous version. * * This value shall indicate a Node in the process of recovering to a previous version from a new version that * was applied, but that could not remain in force, for reasons such as invalid data detected on boot, or * significant runtime issues such as reboot loops. Eventually, the next state seen SHOULD be Unknown or Idle. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.2.8 */ RollingBack = 7, /** * Indicate a Node is capable of user consent. */ DelayedOnUserConsent = 8 } /** * This command may be invoked by Administrators to announce the presence of a particular OTA Provider. * * This command shall be scoped to the accessing fabric. * * If the accessing fabric index is 0, this command shall fail with an UNSUPPORTED_ACCESS status code. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.6.1 */ export class AnnounceOtaProviderRequest { constructor(values?: Partial); /** * This field shall contain the Node ID of a Node implementing the OTA Provider cluster server, on the accessing * fabric. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.6.1.1 */ providerNodeId: NodeId; /** * This field shall contain the assigned Vendor ID of the Node invoking this command, as it would appear in that * Node's Basic Information Cluster VendorID attribute. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.6.1.2 */ vendorId: VendorId; /** * This field shall contain a value expressing the reason for the announcement. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.6.1.3 */ announcementReason: AnnouncementReason; /** * This optional field, if present, shall consist of a top-level anonymous list; each list element shall have a * profile-specific tag encoded in fully-qualified form. Each list element shall contain a manufacturer-specific * payload, which the Node invoking this command wants to expose to the receiving Node. This payload may be used * for any purpose and SHOULD be as small as practical, especially if invoked to groups, in order to reduce * networking burden of these payloads. * * This field SHOULD only be included if the sending OTA Provider has knowledge that some recipient can make use * of it. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.6.1.4 */ metadataForNode?: Bytes; /** * This field shall contain the endpoint number which has the OTA Provider device type and OTA Software Update * Provider cluster server on the ProviderNodeID. This is provided to avoid having to do discovery of the * location of that endpoint by walking over all endpoints and checking their Descriptor Cluster. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.6.1.5 */ endpoint: EndpointNumber; fabricIndex: FabricIndex; } /** * This event shall be generated when a change of the UpdateState attribute occurs due to an OTA Requestor moving * through the states necessary to query for updates. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.1 */ export class StateTransitionEvent { constructor(values?: Partial); /** * This field shall be set to the state that preceded the transition causing this event to be generated, if such * a state existed. If no previous state exists, the value shall be Unknown. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.1.1 */ previousState: UpdateState; /** * This field shall be set to the state now in effect through the transition causing this event to be generated. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.1.2 */ newState: UpdateState; /** * This field shall be set to the reason why this event was generated. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.1.3 */ reason: ChangeReason; /** * This field shall be set to the target SoftwareVersion which is the subject of the operation, whenever the * NewState is Downloading, Applying or RollingBack. Otherwise TargetSoftwareVersion shall be null. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.1.4 */ targetSoftwareVersion: number | null; } /** * This event shall be 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. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.2 */ export class VersionAppliedEvent { constructor(values?: Partial); /** * This field shall be set to the same value as the one available in the Software Version attribute of the Basic * Information Cluster for the newly executing version. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.2.1 */ softwareVersion: number; /** * This field shall be set to the ProductID applying to the executing version, as reflected by the Basic * Information Cluster. This can be used to detect a product updating its definition due to a large-scale * functional update that may impact aspects of the product reflected in the DeviceModel schema of the * Distributed Compliance Ledger. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.2.2 */ productId: number; } /** * This event shall be generated whenever an error occurs during OTA Requestor download operation. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.3 */ export class DownloadErrorEvent { constructor(values?: Partial); /** * This field shall be set to the value of the SoftwareVersion being downloaded, matching the SoftwareVersion * field of the QueryImageResponse that caused the failing download to take place. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.3.1 */ softwareVersion: number; /** * This field shall be set to the number of bytes that have been downloaded during the failing transfer that * caused this event to be generated. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.3.2 */ bytesDownloaded: number | bigint; /** * This field shall be set to the nearest integer percent value reflecting how far within the transfer the * failure occurred during the failing transfer that caused this event to be generated, unless the total length * of the transfer is unknown, in which case it shall be null. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.3.3 */ progressPercent: number | null; /** * This field SHOULD be set to some internal product-specific error code, closest in temporal/functional * proximity to the failure that caused this event to be generated. Otherwise, it shall be null. This event * field may be used for debugging purposes and no uniform definition exists related to its meaning. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.7.3.4 */ platformCode: number | bigint | null; } /** * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.1 */ export enum AnnouncementReason { /** * An OTA Provider is announcing its presence. * * An OTA Provider is announcing its presence, but there is no implication that an OTA Requestor would have a * new Software Image available if it queried immediately. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.1.1 */ SimpleAnnouncement = 0, /** * An OTA Provider is announcing, either to a single Node or to a group of Nodes, that a new Software Image MAY * be available. * * An OTA Provider is announcing, either to a single Node or to a group of Nodes, that a new Software Image may * be available. The details may only be obtained by executing a OTA Software Update Query procedure. A * receiving OTA Requestor SHOULD only query the indicated OTA Provider at the ProviderLocation at its next * upcoming OTA Provider query. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.1.2 */ UpdateAvailable = 1, /** * An OTA Provider is announcing, either to a single Node or to a group of Nodes, that a new Software Image MAY * be available, which contains an update that needs to be applied urgently. * * An OTA Provider is announcing, either to a single Node or to a group of Nodes, that a new Software Image may * be available, which contains an update that needs to be applied urgently. The details may only be obtained by * executing a OTA Software Update Query procedure. A receiving OTA Requestor SHOULD query the indicated OTA * Provider at the ProviderLocation after a random jitter delay between 1 and 600 seconds. This particular * reason SHOULD only be employed when an urgent update is available, such as an important security update, or * just after initial commissioning of a device, to assist OTA Requestors in more rapidly obtaining updated * software. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.1.3 */ UrgentUpdateAvailable = 2 } /** * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.3 */ export enum ChangeReason { /** * The reason for a state change is unknown. * * This value shall indicate that the reason for a state change is unknown. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.3.1 */ Unknown = 0, /** * The reason for a state change is the success of a prior operation. * * This value shall indicate that the reason for a state change is the success of a prior operation. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.3.2 */ Success = 1, /** * The reason for a state change is the failure of a prior operation. * * This value shall indicate that the reason for a state change is the failure of a prior operation. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.3.3 */ Failure = 2, /** * The reason for a state change is a time-out. * * This value shall indicate that the reason for a state change is a time-out condition as determined by the OTA * Requestor. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.3.4 */ TimeOut = 3, /** * The reason for a state change is a request by the OTA Provider to wait. * * This value shall indicate that the reason for a state change is a request by the OTA Provider to await for a * delay. * * @see {@link MatterSpecification.v151.Core} § 11.20.7.4.3.5 */ DelayByProvider = 4 } /** * Attribute metadata objects keyed by name. */ export const attributes: ClusterType.AttributeObjects; /** * Command metadata objects keyed by name. */ export const commands: ClusterType.CommandObjects; /** * Event metadata objects keyed by name. */ export const events: ClusterType.EventObjects; /** * @deprecated Use {@link OtaSoftwareUpdateRequestor}. */ export const Cluster: typeof OtaSoftwareUpdateRequestor; /** * @deprecated Use {@link OtaSoftwareUpdateRequestor}. */ export const Complete: typeof OtaSoftwareUpdateRequestor; export const Typing: OtaSoftwareUpdateRequestor; } /** * @deprecated Use {@link OtaSoftwareUpdateRequestor}. */ export declare const OtaSoftwareUpdateRequestorCluster: typeof OtaSoftwareUpdateRequestor; export interface OtaSoftwareUpdateRequestor extends ClusterTyping { Attributes: OtaSoftwareUpdateRequestor.Attributes; Commands: OtaSoftwareUpdateRequestor.Commands; Events: OtaSoftwareUpdateRequestor.Events; Components: OtaSoftwareUpdateRequestor.Components; }