ota-provider-app#

This is a reference application that implements an example of an OTA Provider Cluster Server.

Build#

Suggest doing the following:

scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/debug chip_config_network_layer_ble=false

Usage#

Command Line Options

Description

-a, –applyUpdateAction <proceed | awaitNextAction | discontinue>

Value for the Action field in the first ApplyUpdateResponse.
For all subsequent responses, the value of proceed will be used.

-c, –userConsentNeeded

If supplied, value of the UserConsentNeeded field in the QueryImageResponse is set to true. This is only applicable if value of the RequestorCanConsent field in QueryImage Command is true.
Otherwise, value of the UserConsentNeeded field is false.

-f, –filepath <file path>

Path to a file containing an OTA image

-i, –imageUri <uri>

Value for the ImageURI field in the QueryImageResponse. If none is supplied, a valid URI is generated.

-o, –otaImageList <file path>

Path to a file containing a list of OTA images

-p, –delayedApplyActionTimeSec <time in seconds>

Value for the DelayedActionTime field in the first ApplyUpdateResponse.
For all subsequent responses, the value of zero will be used.

-q, –queryImageStatus <updateAvailable | busy | updateNotAvailable>

Value for the Status field in the first QueryImageResponse.
For all subsequent responses, the value of updateAvailable will be used.

-t, –delayedQueryActionTimeSec

Value for the DelayedActionTime field in the first QueryImageResponse.
For all subsequent responses, the value of zero will be used.

-u, –userConsentState <granted | denied | deferred>

The user consent state for the first QueryImageResponse. For all subsequent responses, the value of granted will be used.
Note that –queryImageStatus overrides this option.

  • granted: Status field in the first QueryImageResponse is set to updateAvailable
  • denied: Status field in the first QueryImageResponse is set to updateNotAvailable
  • deferred: Status field in the first QueryImageResponse is set to busy

    		•

    -x, –ignoreQueryImage <ignore count>

    The number of times to ignore the QueryImage Command and not send a response

    -y, –ignoreApplyUpdate <ignore count>

    The number of times to ignore the ApplyUpdate Request and not send a response

    -P, –pollInterval

    Poll interval for the BDX transfer.

    Using --filepath and --otaImageList

    • The two options cannot be supplied together

    • At least one option must be supplied

    • If --filepath is supplied, the application will automatically serve that file to the OTA Requestor

    • If --otaImageList is supplied, the application will parse the JSON file and extract all required data. The most recent/valid software version will be selected and the corresponding OTA file will be sent to the OTA Requestor

    • The SoftwareVersion and SoftwareVersionString sent in the QueryImageResponse is derived from the OTA image header. Please note that if the version in the --otaImageList JSON file does not match that in the image header, the application will terminate.

    An example of the --otaImageList file contents:

    { "foo": 1, // ignored by parser
  "deviceSoftwareVersionModel":
  [
      { "vendorId": 1, "productId": 1, "softwareVersion": 10, "softwareVersionString": "1.0.0", "cDVersionNumber": 18, "softwareVersionValid": true, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v10.bin" },
      { "vendorId": 1, "productId": 1, "softwareVersion": 20, "softwareVersionString": "1.0.1", "cDVersionNumber": 18, "softwareVersionValid": false, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v20.bin" },
      { "vendorId": 1, "productId": 1, "softwareVersion": 30, "softwareVersionString": "1.0.2", "cDVersionNumber": 18, "softwareVersionValid": true, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v30.bin" },
      { "vendorId": 1, "productId": 1, "softwareVersion": 40, "softwareVersionString": "1.1.0", "cDVersionNumber": 18, "softwareVersionValid": true, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v40.bin" },
      { "vendorId": 1, "productId": 1, "softwareVersion": 50, "softwareVersionString": "1.1.1", "cDVersionNumber": 18, "softwareVersionValid": false, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "/tmp/ota_v50.bin" }
  ]
}

    Software Image Header#

    All Matter software images must contain a header as defined in section 11.21.1 of the specification. The ota_image_tool is available for generating the required header on a software image.

    All images supplied to the OTA Provider application (via --filepath or --otaImageList) must contain the software image header. The OTA Provider application will use the software version specified in the header to set the SoftwareVersion field of the QueryImageResponse. For instance, if the image supplied represents an image with software version 2, the tool can be used as follows:

    src/app/ota_image_tool.py create -v 0xDEAD -p 0xBEEF -vn 2 -vs "2.0" -da sha256 firmware.bin firmware.ota

    Please see this section for information on building an OTA Requestor application with a specific software version.

    Access Control Requirements#

    Commissioner or Administrator SHOULD install necessary ACL entries at commissioning time or later to enable processing of QueryImage commands from OTA Requestors on their fabric, otherwise that OTA Provider will not be usable by OTA Requestors.

    Since the ACL attribute contains a list of ACL entries, writing of the attribute should not just contain the values for the new entry. Any existing entries should be read and included as part of the write. Below is an example of how to write the ACL attribute with two entries:

    out/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": [{"cluster": 41, "endpoint": null, "deviceType": null}]}]' 0xDEADBEEF 0

    • Entry 1: This is the original entry created as part of commissioning which grants administer privilege to the node ID 112233 (default controller node ID) for all clusters on every endpoint

    • Entry 2: This is the new entry being added which grants operate privileges to all nodes for the OTA Provider cluster (0x0029) on every endpoint

    In the example above, the provider is on fabric index 1 with provider node ID being 0xDEADBEEF on endpoint 0.

    Current Limitations#

    • Synchronous BDX transfer only

    • Does not check VID/PID

    • Only one transfer at a time (does not check incoming UpdateTokens)