| # 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.<br>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.<br>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.<br>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.<br>For all subsequent responses, the value of updateAvailable will be used. | |
| | -t, --delayedQueryActionTimeSec <time> | Value for the DelayedActionTime field in the first QueryImageResponse.<br>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.<br>Note that --queryImageStatus overrides this option.<li> granted: Status field in the first QueryImageResponse is set to updateAvailable <li> denied: Status field in the first QueryImageResponse is set to updateNotAvailable <li> 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 <milliseconds> | 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](https://github.com/project-chip/connectedhomeip/blob/master/src/app/ota_image_tool.py) |
| 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](https://github.com/project-chip/connectedhomeip/tree/master/examples/ota-requestor-app/linux#generate-images) |
| 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`) |
