/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ /*** THIS FILE IS GENERATED, DO NOT EDIT ***/ import { Resource } from "#models/Resource.js"; Resource.add( { tag: "cluster", name: "OtaSoftwareUpdateProvider", pics: "OTAP", xref: "core§11.20.6", details: "This cluster implements the Provider role in the OTA process.", children: [ { tag: "command", name: "QueryImage", xref: "core§11.20.6.5.1", details: "Upon receipt, this command shall 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.", children: [ { tag: "field", name: "VendorId", xref: "core§11.20.6.5.1.1", details: "The value shall be the Vendor ID applying to the OTA Requestor's Node and shall match the value " + "reported by the Basic Information Cluster VendorID attribute." }, { tag: "field", name: "ProductId", xref: "core§11.20.6.5.1.2", details: "The value shall be the Product ID applying to the OTA Requestor's Node and shall match the value " + "reported by the Basic Information Cluster ProductID attribute." }, { tag: "field", name: "SoftwareVersion", xref: "core§11.20.6.5.1.3", details: "The SoftwareVersion included in the request payload shall provide the value representing the current " + "version running on the OTA Requestor invoking the command. This version shall be equal to the " + "Software Version attribute of the Basic Information Cluster." }, { tag: "field", name: "ProtocolsSupported", xref: "core§11.20.6.5.1.4", details: "This field shall contain a list of all download protocols supported by the OTA Requestor." + "\n" + "This field shall be used by the OTA Provider to generate the correct URI for the location of the " + "Software Image when one is found to be available. BDX Synchronous transfer mode shall always be " + "supported by an OTA Provider. Furthermore, OTA Providers with access to external networking SHOULD " + "support the HTTPS protocol. OTA Providers may support other protocols." + "\n" + "The algorithm to select the specific protocol to use in a given Software Image URI is " + "implementation-dependent, provided that the rules in Section 11.20.3.3.1, \"Download Protocol " + "selection\" are followed." + "\n" + "See Section 11.20.3.2, \"Querying the OTA Provider\" and Section 11.20.3.5, \"Transfer of OTA Software " + "Update images\" for more details about usage of this field." }, { tag: "field", name: "HardwareVersion", xref: "core§11.20.6.5.1.5", details: "The value of this field, if present, shall contain the OTA Requestor's hardware version, and shall " + "be equal to the HardwareVersion attribute of the Basic Information Cluster." }, { tag: "field", name: "Location", xref: "core§11.20.6.5.1.6", details: "The location, if present, shall provide the same value as the Basic Information Cluster Location " + "attribute for the OTA Requestor as configured. This may be used by the OTA Provider logic to allow " + "per-region selection of the Software Image." }, { tag: "field", name: "RequestorCanConsent", xref: "core§11.20.6.5.1.7", details: "This field shall be set to true by an OTA Requestor that is capable of obtaining user consent for " + "OTA application by virtue of built-in user interface capabilities. Otherwise, it shall be false." + "\n" + "See Section 11.20.3.4, \"Obtaining user consent for updating software\" for application details about " + "usage." }, { tag: "field", name: "MetadataForProvider", xref: "core§11.20.6.5.1.8", details: "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 OTA Requestor invoking this command wants to expose to the " + "receiving OTA Provider. This payload may be used for any purpose and SHOULD be as small as " + "practical." + "\n" + "The use of this field SHOULD be restricted to Vendor-specific usage and shall NOT be used as a " + "selector required to match for the selection of a Software Image in production environments, unless " + "absolutely necessary, as the interpretation of this field may be ambiguous to OTA Providers " + "implementing the Cluster in a compliant but divergent way from the sender." + "\n" + "An example of usage for this field is for an OTA Requestor to provide specific data about grouping " + "or authentication in field trial environments, where the OTA Provider is likely to understand it and " + "be able to act upon it, either for special selection of image, or recording of activity." + "\n" + "An OTA Provider shall report the availability of Software Images, if one is found to be applicable " + "using the other provided fields, even if the MetadataForProvider field is deemed to contain invalid " + "or unknown information. That is, the contents of the MetadataForProvider field shall NOT be used to " + "deny a software update to an OTA Requestor, unless both OTA Requestor and OTA Provider have an " + "externally agreed-upon policy whereby strictly correct additional MetadataForProvider is expected to " + "fulfill the OTA Software Update process." } ] }, { tag: "command", name: "QueryImageResponse", xref: "core§11.20.6.5.2", details: "This command is sent in response to the QueryImage command.", children: [ { tag: "field", name: "Status", xref: "core§11.20.6.5.2.1", details: "This field shall contain the primary response regarding the availability of a Software Image." + "\n" + "See Section 11.20.3.2, \"Querying the OTA Provider\" for details about the possible values for this " + "field and their meaning." }, { tag: "field", name: "DelayedActionTime", xref: "core§11.20.6.5.2.2", details: "This field shall be provided when the Status field is set to Busy, and may be provided in other " + "cases. This field, if provided, shall convey the minimum time to wait, in seconds from the time of " + "this response, before sending another QueryImage command or beginning a download from the OTA " + "Provider. OTA Requestors shall respect this minimum delay, unless they had previously restarted and " + "lost track of it. OTA Providers SHOULD expect OTA Requestors to follow this value to their best " + "capability, however, a restarting Node may come back sooner, due to having lost track of this state " + "response." + "\n" + "See Section 11.20.3.2, \"Querying the OTA Provider\" for details about the rules regarding this field." }, { tag: "field", name: "ImageUri", xref: "core§11.20.6.5.2.3", details: "This field, when present, shall contain a URI where the OTA Requestor SHOULD download a Software " + "Image. The syntax of the ImageURI field shall follow the URI syntax as specified in RFC3986." + "\n" + "Beware, this field is conditionally present based on the conformance listed in Section 11.20.6.5.2, " + "\"QueryImageResponse Command\"." + "\n" + "If the ImageURI specifies a BDX Protocol bdx: scheme, then the following rules describe the location " + "to be used for download:" + "\n" + " 1. The URI's scheme field shall be exactly bdx in lowercase characters." + "\n" + " 2. The URI's authority field shall contain only the host portion and shall use string " + "representation of the Operational Node ID of the Node where to proceed with the download, on " + "the same Fabric on which the OTA Requestor received the QueryImageResponse." + "\n" + " 3. The encoding of the Node ID in the host field shall use an uppercase hexadecimal format, using " + "exactly 16 characters to encode the network byte order value of the NodeID, in a similar " + "fashion as the Node Identifier portion of the Operational Instance Name." + "\n" + " 1. The Operational Node ID in the host field shall match the NodeID of the OTA Provider " + "responding with the QueryImageResponse. The usage of a different Node ID than that of the " + "provider is reserved for future use. This constraint reduces the number of independent CASE " + "secure channel sessions that have to be maintained to proceed with OTA software updates, thus " + "reducing energy and resource utilization for the software update process." + "\n" + " 4. The user section of the authority field shall be absent, as there are no \"users\" to be " + "considered." + "\n" + " 5. The port section of the authority field shall be absent, as the port for transport shall be " + "determined through Operational Discovery of the target Node." + "\n" + " 6. The URI shall NOT contain a query field." + "\n" + " 7. The URI shall NOT contain a fragment field." + "\n" + " 8. The path field shall employ absolute path representation and shall contain the file designator " + "of the software image to download at the BDX server. When used with the BDX server, the leading " + "/ separating the URI authority from the path shall be omitted. When contacting the BDX server, " + "further processing of the file designator shall NOT be done, including handling of URL-encoded " + "escape sequences. Rather, the exact octets of the path, as received shall be the values used by " + "both client and server in handling the file designator." + "\n" + " 1. The path shall only contain valid URI characters." + "\n" + "These rules above for BDX URIs simplify parsing for OTA Requestors receiving Image URIs. The " + "following example procedure shows how the format constraints simplify the extraction of the " + "necessary data to reach the BDX server for download." + "\n" + " 1. Verify that the URI is 24 characters or longer, which is the minimum length of a valid BDX URI " + "with all elements present, for example bdx://00112233AABBCCDD/0." + "\n" + " 2. Verify the presence of prefix bdx:// indicating a BDX URI." + "\n" + " 3. Extract the next 16 characters and convert from uppercase hexadecimal to a 64-bit scalar value, " + "considering network byte order. This is the destination Node ID." + "\n" + " 4. Verify the presence of a path separator / and skip it." + "\n" + " 5. Extract the remaining characters of the string as the file designator to employ when initiating " + "the BDX transfer." + "\n" + "Example ImageURI values are below, and illustrate some but not all of valid and invalid cases:" + "\n" + " - Synchronous or Asynchronous BDX Protocol:" + "\n" + " - Valid: bdx://8899AABBCCDDEEFF/the_file_designator123" + "\n" + " - Node ID: 0x8899AABBCCDDEEFF" + "\n" + " - File designator: the_file_designator123" + "\n" + " - Valid: bdx://0099AABBCCDDEE77/the%20file%20designator/some_more" + "\n" + " - Node ID: 0x0099AABBCCDDEE77" + "\n" + " - File designator: the%20file%20designator/some_more. Note that the %20 are retained and not " + "converted to ASCII 0x20 (space). The file designator is the path as received verbatim, after " + "the first '/' (U+002F / SOLIDUS) following the host." + "\n" + " - Invalid: bdx://99AABBCCDDEE77/the_file_designator123" + "\n" + " - Node ID: Invalid since it is not exactly 16 characters long, due to having omitted leading " + "zeros." + "\n" + " - Invalid: bdx://0099aabbccddee77/the_file_designator123" + "\n" + " - Node ID: Invalid since lowercase hexadecimal was used." + "\n" + " - Invalid: bdx:8899AABBCCDDEEFF/the_file_designator123" + "\n" + " - Invalid since bdx scheme does not contain an authority, that is, it does not have // after " + "the first :." + "\n" + " - HTTP over TLS:" + "\n" + " - Valid: https://example.domain:8466/software/image.bin" + "\n" + "See Section 11.20.3.2, \"Querying the OTA Provider\" for additional details about the flow." }, { tag: "field", name: "SoftwareVersion", xref: "core§11.20.6.5.2.4", details: "This field indicates the version of the image being provided to the OTA Requestor by the OTA " + "Provider." + "\n" + "Beware, this field is conditionally present based on the conformance listed in Section 11.20.6.5.2, " + "\"QueryImageResponse Command\"." + "\n" + "See Section 11.20.3.2, \"Querying the OTA Provider\" for additional details about the flow and " + "acceptable values." }, { tag: "field", name: "SoftwareVersionString", xref: "core§11.20.6.5.2.5", details: "This field provides a string version of the image being provided to the OTA Requestor by the OTA " + "Provider." + "\n" + "Beware, this field is conditionally present based on the conformance listed in Section 11.20.6.5.2, " + "\"QueryImageResponse Command\"." + "\n" + "See Section 11.20.3.2, \"Querying the OTA Provider\" for additional details about the flow and " + "acceptable values." }, { tag: "field", name: "UpdateToken", xref: "core§11.20.6.5.2.6", details: "Beware, this field is conditionally present based on the conformance listed in Section 11.20.6.5.2, " + "\"QueryImageResponse Command\"." + "\n" + "See Section 11.20.3.6.1, \"UpdateToken usage\" for additional details about the generation and usage " + "of UpdateToken." }, { tag: "field", name: "UserConsentNeeded", xref: "core§11.20.6.5.2.7", details: "This field, if present, shall only be interpreted if the OTA Requestor had previously indicated a " + "value of True in the RequestorCanConsent field of the QueryImageRequest. This field, when present " + "and set to True, shall indicate that a capable OTA Requestor must obtain user-visible consent prior " + "to downloading the OTA Software Image." + "\n" + "See Section 11.20.3.4, \"Obtaining user consent for updating software\" for application details about " + "usage." }, { tag: "field", name: "MetadataForRequestor", xref: "core§11.20.6.5.2.8", details: "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 OTA Provider wants to expose to the receiving OTA " + "Requestor. This payload may be used for any purpose and SHOULD be as small as practical." + "\n" + "The presence of this field shall NOT be required for correct operation of any OTA Provider compliant " + "with this Cluster specification." + "\n" + "The data for this field does not exist in any Distributed Compliance Ledger record and SHOULD only " + "be emitted by an OTA Provider with this additional knowledge if it has knowledge that the receiving " + "OTA Requestor may be able to use it." } ] }, { tag: "command", name: "ApplyUpdateRequest", xref: "core§11.20.6.5.3", details: "This command requests the specified version be installed on the device.", children: [ { tag: "field", name: "UpdateToken", xref: "core§11.20.6.5.3.1", details: "This field shall contain the UpdateToken as specified in Section 11.20.3.6.1, \"UpdateToken usage\". " + "This field may be used by the OTA Provider to track minimal lifecycle state to allow finer-grained " + "scheduling of the application of Software Images by OTA Requestors." }, { tag: "field", name: "NewVersion", xref: "core§11.20.6.5.3.2", details: "The NewVersion field included in the request payload shall provide the SoftwareVersion value of the " + "new Software Image which the OTA Requestor is ready to start applying. The OTA Provider may use this " + "new version to track or record Software Image application by OTA Requestors." } ] }, { tag: "command", name: "ApplyUpdateResponse", xref: "core§11.20.6.5.4", details: "This command is sent in response to the ApplyUpdateRequest command.", children: [ { tag: "field", name: "Action", xref: "core§11.20.6.5.4.1", details: "The Action field shall express the action that the OTA Provider requests from the OTA Requestor. See " + "Section 11.20.3.6, \"Applying a software update\" for a description of the Action values provided in " + "response to an OTA Provider receiving an invocation of this command." }, { tag: "field", name: "DelayedActionTime", xref: "core§11.20.6.5.4.2", details: "The minimum time period the OTA Requestor shall wait before executing the Action, in seconds from " + "receipt." + "\n" + "If this field has a value higher than 86400 seconds (24 hours), then the OTA Requestor may assume a " + "value of 86400, in order to reduce undue Software Image application delays." } ] }, { tag: "command", name: "NotifyUpdateApplied", xref: "core§11.20.6.5.5", details: "This command tells the Provider that the specified update has been applied.", children: [ { tag: "field", name: "UpdateToken", xref: "core§11.20.6.5.5.1", details: "This field shall contain the UpdateToken as specified in Section 11.20.3.6.1, \"UpdateToken usage\"." }, { tag: "field", name: "SoftwareVersion", xref: "core§11.20.6.5.5.2", details: "The SoftwareVersion included in the request payload shall provide the same value as the " + "SoftwareVersion attribute in the invoking OTA Requestor's Basic Information Cluster, and SHOULD be " + "consistent with the value representing a new version running on the Node invoking the command." } ] }, { tag: "datatype", name: "StatusEnum", xref: "core§11.20.6.4.1", details: "See Section 11.20.3.2, \"Querying the OTA Provider\" for the semantics of these values.", children: [ { tag: "field", name: "UpdateAvailable", description: "Indicates that the OTA Provider has an update available." }, { tag: "field", name: "Busy", description: "Indicates OTA Provider may have an update, but it is not ready yet." }, { tag: "field", name: "NotAvailable", description: "Indicates that there is definitely no update currently available from the OTA Provider." }, { tag: "field", name: "DownloadProtocolNotSupported", description: "Indicates that the requested download protocol is not supported by the OTA Provider." } ] }, { tag: "datatype", name: "ApplyUpdateActionEnum", xref: "core§11.20.6.4.2", details: "See Section 11.20.3.6, \"Applying a software update\" for the semantics of the values. This " + "enumeration is used in the Action field of the ApplyUpdateResponse command. See (Action).", children: [ { tag: "field", name: "Proceed", description: "Apply the update." }, { tag: "field", name: "AwaitNextAction", description: "Wait at least the given delay time." }, { tag: "field", name: "Discontinue", description: "The OTA Provider is conveying a desire to rescind a previously provided Software Image." } ] }, { tag: "datatype", name: "DownloadProtocolEnum", xref: "core§11.20.6.4.3", details: "Note that only HTTP over TLS (HTTPS) is supported (see RFC7230). Using HTTP without TLS shall NOT be " + "supported, as there is no way to authenticate the involved participants." + "\n" + "> [!NOTE]" + "\n" + "> NOTE: Support for the asynchronous BDX mode is provisional.", children: [ { tag: "field", name: "BdxSynchronous", description: "Indicates support for synchronous BDX." }, { tag: "field", name: "BdxAsynchronous", description: "Indicates support for asynchronous BDX." }, { tag: "field", name: "Https", description: "Indicates support for HTTPS." }, { tag: "field", name: "VendorSpecific", description: "Indicates support for vendor specific protocol." } ] } ] } );