This is a reference application that implements an example of an OTA Provider Cluster Server.
Suggest doing the following:
scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/debug chip_config_network_layer_ble=false
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
--filepath
is supplied, the application will automatically serve that file to the OTA Requestor--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--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" } ] }
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.
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
In the example above, the provider is on fabric index 1 with provider node ID being 0xDEADBEEF
on endpoint 0.
UpdateTokens
)