Interface QueryImageResponse

This field 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.

The DelayedActionTime field shall only be present if the Status field is set to Busy.

See Section 11.20.3.2, “Querying the OTA Provider” for details about the rules regarding this field.

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.

This field shall be present if it appears in a QueryImageResponse with a Status of UpdateAvailable.

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.

a. 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.

a. 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.

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.

The presence of this field shall NOT be required for correct operation of any OTA Provider compliant with this Cluster specification.

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.

This field indicates the version of the image being provided to the OTA Requestor by the OTA Provider when the Status is UpdateAvailable.

This field shall be present if it appears in a QueryImageResponse with a Status of UpdateAvailable.

See Section 11.20.3.2, “Querying the OTA Provider” for additional details about the flow and acceptable values.

This field provides a string version of the image being provided to the OTA Requestor by the OTA Provider when the Status is UpdateAvailable.

This field shall be present if it appears in a QueryImageResponse with a Status of UpdateAvailable.

See Section 11.20.3.2, “Querying the OTA Provider” for additional details about the flow and acceptable values.

This field shall contain the primary response regarding the availability of a Software Image.

See Section 11.20.3.2, “Querying the OTA Provider” for details about the possible values for this field and their meaning.

This optional field shall be present when the Status field contains UpdateAvailable.

See Section 11.20.3.6.1, “UpdateToken usage” for additional details about the generation and usage of UpdateToken.

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.

See Section 11.20.3.4, “Obtaining user consent for updating software” for application details about usage.