/**
 * @license
 * Copyright 2022-2026 Matter.js Authors
 * SPDX-License-Identifier: Apache-2.0
 */
import { Resource } from "#models/Resource.js";
Resource.add(
  {
    tag: "cluster",
    name: "OtaSoftwareUpdateProvider",
    pics: "OTAP",
    xref: "core\xA711.20.6",
    details: "This cluster implements the Provider role in the OTA process.",
    children: [
      {
        tag: "command",
        name: "QueryImage",
        xref: "core\xA711.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\xA711.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\xA711.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\xA711.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\xA711.20.6.5.1.4",
            details: 'This field shall contain a list of all download protocols supported by the OTA Requestor.\nThis 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.\nThe 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.\nSee 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\xA711.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\xA711.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\xA711.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.\nSee Section 11.20.3.4, "Obtaining user consent for updating software" for application details about usage.'
          },
          {
            tag: "field",
            name: "MetadataForProvider",
            xref: "core\xA711.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.\nThe 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.\nAn 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.\nAn 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\xA711.20.6.5.2",
        details: "This command is sent in response to the QueryImage command.",
        children: [
          {
            tag: "field",
            name: "Status",
            xref: "core\xA711.20.6.5.2.1",
            details: 'This field shall contain the primary response regarding the availability of a Software Image.\nSee 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\xA711.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.\nSee Section 11.20.3.2, "Querying the OTA Provider" for details about the rules regarding this field.'
          },
          {
            tag: "field",
            name: "ImageUri",
            xref: "core\xA711.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 RFC 3986.
Beware, this field is conditionally present based on the conformance listed in Section 11.20.6.5.2, "QueryImageResponse Command".
If the ImageURI specifies a BDX Protocol bdx: scheme, then the following rules describe the location to be used for download:
  1. The URI's scheme field shall be exactly bdx in lowercase characters.
  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.
  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.
  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.
  4. The user section of the authority field shall be absent, as there are no "users" to be considered.
  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.
  6. The URI shall NOT contain a query field.
  7. The URI shall NOT contain a fragment field.
  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.
  1. The path shall only contain valid URI characters.
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.
  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.
  2. Verify the presence of prefix bdx:// indicating a BDX URI.
  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.
  4. Verify the presence of a path separator / and skip it.
  5. Extract the remaining characters of the string as the file designator to employ when initiating the BDX transfer.
Example ImageURI values are below, and illustrate some but not all of valid and invalid cases:
  - Synchronous or Asynchronous BDX Protocol:
  - Valid: bdx://8899AABBCCDDEEFF/the_file_designator123
  - Node ID: 0x8899AABBCCDDEEFF
  - File designator: the_file_designator123
  - Valid: bdx://0099AABBCCDDEE77/the%20file%20designator/some_more
  - Node ID: 0x0099AABBCCDDEE77
  - 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.
  - Invalid: bdx://99AABBCCDDEE77/the_file_designator123
  - Node ID: Invalid since it is not exactly 16 characters long, due to having omitted leading zeros.
  - Invalid: bdx://0099aabbccddee77/the_file_designator123
  - Node ID: Invalid since lowercase hexadecimal was used.
  - Invalid: bdx:8899AABBCCDDEEFF/the_file_designator123
  - Invalid since bdx scheme does not contain an authority, that is, it does not have // after the first :.
  - HTTP over TLS:
  - Valid: https://example.domain:8466/software/image.bin
See Section 11.20.3.2, "Querying the OTA Provider" for additional details about the flow.`
          },
          {
            tag: "field",
            name: "SoftwareVersion",
            xref: "core\xA711.20.6.5.2.4",
            details: 'This field indicates the version of the image being provided to the OTA Requestor by the OTA Provider.\nBeware, this field is conditionally present based on the conformance listed in Section 11.20.6.5.2, "QueryImageResponse Command".\nSee Section 11.20.3.2, "Querying the OTA Provider" for additional details about the flow and acceptable values.'
          },
          {
            tag: "field",
            name: "SoftwareVersionString",
            xref: "core\xA711.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.\nBeware, this field is conditionally present based on the conformance listed in Section 11.20.6.5.2, "QueryImageResponse Command".\nSee Section 11.20.3.2, "Querying the OTA Provider" for additional details about the flow and acceptable values.'
          },
          {
            tag: "field",
            name: "UpdateToken",
            xref: "core\xA711.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".\nSee Section 11.20.3.6.1, "UpdateToken usage" for additional details about the generation and usage of UpdateToken.'
          },
          {
            tag: "field",
            name: "UserConsentNeeded",
            xref: "core\xA711.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.\nSee Section 11.20.3.4, "Obtaining user consent for updating software" for application details about usage.'
          },
          {
            tag: "field",
            name: "MetadataForRequestor",
            xref: "core\xA711.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.\nThe presence of this field shall NOT be required for correct operation of any OTA Provider compliant with this Cluster specification.\nThe 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\xA711.20.6.5.3",
        details: "This command requests the specified version be installed on the device.",
        children: [
          {
            tag: "field",
            name: "UpdateToken",
            xref: "core\xA711.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\xA711.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\xA711.20.6.5.4",
        details: "This command is sent in response to the ApplyUpdateRequest command.",
        children: [
          {
            tag: "field",
            name: "Action",
            xref: "core\xA711.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\xA711.20.6.5.4.2",
            details: "The minimum time period the OTA Requestor shall wait before executing the Action, in seconds from receipt.\nIf 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\xA711.20.6.5.5",
        details: "This command tells the Provider that the specified update has been applied.",
        children: [
          {
            tag: "field",
            name: "UpdateToken",
            xref: "core\xA711.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\xA711.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\xA711.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\xA711.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\xA711.20.6.4.3",
        details: "Note that only HTTP over TLS (HTTPS) is supported (see RFC 7230). 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."
          }
        ]
      }
    ]
  }
);
//# sourceMappingURL=ota-software-update-provider.resource.js.map
