[OTA] Remove provider and fabric command line options from the reques…

…tor application (#15287)
project-chip · Feb 24, 2022 · 1135671 · 1135671
1 parent 3a82c94
commit 1135671
Show file tree

Hide file tree

Showing 3 changed files with 216 additions and 76 deletions.
diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt
@@ -303,6 +303,7 @@ DCONFIG
 debianutils
 DEDEDEDE
 deepnote
+DefaultOTAProviders
 definedValue
 DehumidificationControl
 DelayedActionTime
@@ -437,6 +438,7 @@ extern
 extpanid
 FabricId
 fabricIdx
+fabricIndex
 factoryreset
 FanControl
 fb
@@ -903,6 +905,7 @@ protobuf
 protos
 Prover
 providerFabricIndex
+ProviderLocation
 providerNodeId
 ProxyConfiguration
 ProxyDiscovery
@@ -1075,6 +1078,7 @@ storagepath
 str
 strcpy
 struct
+structs
 su
 Subclassing
 subcommand
@@ -1265,6 +1269,7 @@ Xcode
 xcodeproj
 xcworkspace
 xd
+xDEADBEEF
 xdeadbeefcafe
 xds
 xdsdfu

diff --git a/examples/ota-requestor-app/linux/README.md b/examples/ota-requestor-app/linux/README.md
@@ -17,12 +17,10 @@ scripts/examples/gn_build_example.sh examples/ota-requestor-app/linux out/debug
 In addition to the general options available to all Linux applications, the
 following command line options are available for the OTA Requestor application.
 
-| Directory                               | Description                                                                                                                                                                       |
-| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| -n/--providerNodeId <node ID>           | Node ID of the OTA Provider to connect to (hex format) <br> This assumes that you've already commissioned the OTA Provider node with chip-tool                                    |
-| -f/--providerFabricIndex <fabric index> | Fabric index of the OTA Provider to connect to. If none is specified, default value is 1. <br> This assumes that you've already commissioned the OTA Provider node with chip-tool |
-| -q/--delayQuery <Time in seconds>       | From boot up, the amount of time to wait before triggering the QueryImage command. If none or zero is supplied, QueryImage will not be triggered automatically.                   |
-| -c/--requestorCanConsent                | If supplied, the RequestorCanConsent field of the QueryImage command is set to true. Otherwise, the value is determined by the driver.                                            |
+| Directory                         | Description                                                                                                                                                                                                                                          |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| -q/--delayQuery <Time in seconds> | From boot up, the amount of time to wait before triggering the QueryImage command. If none or zero is supplied, QueryImage will not be triggered automatically. At least one provider location must be written to the DefaultOTAProviders attribute. |
+| -c/--requestorCanConsent          | If supplied, the RequestorCanConsent field of the QueryImage command is set to true. Otherwise, the value is determined by the driver.                                                                                                               |
 
 ## Software Image Header
 
@@ -34,100 +32,263 @@ software images that the OTA Requestor application receives must contain the
 required header. If the header is missing, the software download will not
 succeed.
 
-## Example
+## Common Instructions
 
-One way to use this reference application to connect to a device running OTA
-Provider server and download a software image is to issue an AnnounceOTAProvider
-command. This will trigger a QueryImage command and start the OTA process. To
-test using this method, the following steps should be followed:
+The Linux
+[ota-provider-app](https://github.com/project-chip/connectedhomeip/tree/master/examples/ota-provider-app/linux)
+can be used together with this reference application to test OTA features. Here
+are some common instructions for building and commissioning the applications.
 
-### In terminal 1:
+### OTA Provider application
 
-**Build the OTA Provider application**
+#### Build the OTA Provider application
 
 Follow instructions
 [here](https://github.com/project-chip/connectedhomeip/tree/master/examples/ota-provider-app/linux#building)
 
-**Run the OTA Provider application**
+#### Run the OTA Provider application
 
 ```
-./chip-ota-provider-app --discriminator ${REQUESTOR_LONG_DISCRIMINATOR} --secured-device-port ${REQUESTOR_UDP_PORT} --KVS ${KVS_STORE_LOCATION} --filepath ${SW_IMAGE_FILE}
+out/chip-ota-provider-app --discriminator ${PROVIDER_LONG_DISCRIMINATOR} --secured-device-port ${PROVIDER_UDP_PORT} --KVS ${KVS_STORE_LOCATION} --filepath ${SW_IMAGE_FILE}
 ```
 
--   `{PROVIDER_LONG_DISCRIMINATOR}` is the long discriminator specified for the
+-   `${PROVIDER_LONG_DISCRIMINATOR}` is the long discriminator specified for the
     OTA Provider application for commissioning discovery. If none is supplied,
     the default is 3840. This must be different from the value used by the OTA
     Requestor application.
--   `{PROVIDER_UDP_PORT}` is the UDP port that the OTA Provider application
+-   `${PROVIDER_UDP_PORT}` is the UDP port that the OTA Provider application
     listens on for secure connections. If none is supplied, the default is 5540.
     This must be different from the value used by the OTA Requestor application.
--   `{KVS_STORE_LOCATION}` is a location where the KVS items will be stored. If
+-   `${KVS_STORE_LOCATION}` is a location where the KVS items will be stored. If
     none is supplied, the default is /tmp/chip_kvs. This must be different from
     the value used by the OTA Requestor application.
 -   `${SW_IMAGE_FILE}` is the file representing a software image to be served.
     This file must include a header as defined in the specification.
 
-### In terminal 2:
+#### Commission the OTA Provider application
 
-**Build the OTA Requestor application**
+```
+out/chip-tool pairing onnetwork-long ${PROVIDER_NODE_ID} 20202021 ${PROVIDER_LONG_DISCRIMINATOR}
+```
+
+-   `${PROVIDER_NODE_ID}` is the node id to assign to the OTA Provider
+    application running
+-   `${PROVIDER_LONG_DISCRIMINATOR}` is the long discriminator of the OTA
+    Provider application running
+
+### OTA Requestor application
+
+#### Build the OTA Provider application
 
 Follow instructions
 [here](https://github.com/project-chip/connectedhomeip/tree/master/examples/ota-requestor-app/linux#building)
 
-**Run the OTA Requestor application:**
+#### Run the OTA Requestor application:
 
 ```
-./chip-ota-requestor-app --discriminator ${REQUESTOR_LONG_DISCRIMINATOR} --secured-device-port ${REQUESTOR_UDP_PORT} --KVS ${KVS_STORE_LOCATION}
+out/chip-ota-requestor-app --discriminator ${REQUESTOR_LONG_DISCRIMINATOR} --secured-device-port ${REQUESTOR_UDP_PORT} --KVS ${KVS_STORE_LOCATION} --delayQuery ${TIME_IN_SECONDS}
 ```
 
--   `{REQUESTOR_LONG_DISCRIMINATOR}` is the long discriminator specified for the
-    OTA Requestor application for commissioning discovery. If none is supplied,
-    the default is 3840. This must be different from the value used by the OTA
-    Provider application.
--   `{REQUESTOR_UDP_PORT}` is the UDP port that the OTA Requestor application
+-   `${REQUESTOR_LONG_DISCRIMINATOR}` is the long discriminator specified for
+    the OTA Requestor application for commissioning discovery. If none is
+    supplied, the default is 3840. This must be different from the value used by
+    the OTA Provider application.
+-   `${REQUESTOR_UDP_PORT}` is the UDP port that the OTA Requestor application
     listens on for secure connections. If none is supplied, the default is 5540.
     This must be different from the value used by the OTA Provider application.
--   `{KVS_STORE_LOCATION}` is a location where the KVS items will be stored. If
+-   `${KVS_STORE_LOCATION}` is a location where the KVS items will be stored. If
     none is supplied, the default is /tmp/chip_kvs. This must be different from
     the value used by the OTA Provider application.
+-   `${TIME_IN_SECONDS}` is the amount of time to wait before triggering the
+    QueryImage command specified by the DefaultOTAProviders attribute
+
+#### Commission the OTA Requestor application
+
+```
+out/chip-tool pairing onnetwork-long ${REQUESTOR_NODE_ID} 20202021 ${REQUESTOR_LONG_DISCRIMINATOR}
+```
 
-### In terminal 3:
+-   `${REQUESTOR_NODE_ID}` is the node id to assign to the OTA Requestor
+    application running
+-   `${REQUESTOR_LONG_DISCRIMINATOR}` is the long discriminator of the OTA
+    Requestor application running
+
+## Examples
+
+There are two methods for this reference application to connect to a device
+running OTA Provider server and download a software image.
+
+### AnnounceOTAProvider Command
+
+When the `AnnounceOTAProvider` command is received, it will trigger a QueryImage
+command to the provider specified in the command and start the OTA process.
+
+#### In terminal 1:
+
+**Build the OTA Provider application**
+
+```
+scripts/examples/gn_build_example.sh examples/ota-provider-app/linux/ out chip_config_network_layer_ble=false
+```
+
+**Run the OTA Provider application**
+
+```
+out/chip-ota-provider-app --discriminator 22 --KVS /tmp/chip_kvs_provider --filepath /tmp/test.bin
+```
+
+#### In terminal 2:
+
+**Build the OTA Requestor application**
+
+```
+scripts/examples/gn_build_example.sh examples/ota-requestor-app/linux/ out chip_config_network_layer_ble=false
+```
+
+**Run the OTA Requestor application**
+
+```
+out/chip-ota-requestor-app --discriminator 18 --secured-device-port 5560 --KVS /tmp/chip_kvs_requestor
+```
+
+#### In terminal 3:
 
 **Commission the OTA Provider application**
 
 ```
-./chip-tool pairing onnetwork-long ${PROVIDER_NODE_ID} 20202021 ${PROVIDER_LONG_DISCRIMINATOR}
+out/chip-tool pairing onnetwork-long 0xDEADBEEF 20202021 22
 ```
 
--   `${PROVIDER_NODE_ID}` is the node id to assign to the OTA Provider
-    application running in terminal 1
--   `${PROVIDER_LONG_DISCRIMINATOR}` is the long discriminator of the OTA
-    Provider application specified in terminal 1 above
+**Commission the OTA Requestor application**
+
+```
+out/chip-tool pairing onnetwork-long 0x1234567890 20202021 18
+```
+
+**Issue the AnnounceOTAProvider command**
+
+```
+out/chip-tool otasoftwareupdaterequestor announce-ota-provider 0xDEADBEEF 0 0 0 0x1234567890 0
+```
+
+The OTA Requestor application with node ID 0x1234567890 will process this
+command and send a QueryImage command to the OTA Provider with node ID
+0xDEADBEEF, as specified in the `AnnounceOTAProvider` command.
+
+### DefaultOTAProviders attribute
+
+If one or more provider locations have been written to the `DefaultOTAProviders`
+attribute, this can be used to trigger a QueryImage command to a provider in the
+attribute and start the OTA process.
+
+#### In terminal 1:
+
+**Build the OTA Provider application**
+
+```
+scripts/examples/gn_build_example.sh examples/ota-provider-app/linux/ out chip_config_network_layer_ble=false
+```
+
+**Run the OTA Provider application**
+
+```
+out/chip-ota-provider-app --discriminator 22 --KVS /tmp/chip_kvs_provider --filepath /tmp/test.bin
+```
+
+#### In terminal 2:
+
+**Build the OTA Requestor application**
+
+```
+scripts/examples/gn_build_example.sh examples/ota-requestor-app/linux/ out chip_config_network_layer_ble=false
+```
+
+**Run the OTA Requestor application**
+
+```
+out/chip-ota-requestor-app --discriminator 18 --secured-device-port 5560 --KVS /tmp/chip_kvs_requestor --delayQuery 30
+```
+
+#### In terminal 3:
+
+**Commission the OTA Provider application**
+
+```
+out/chip-tool pairing onnetwork-long 0xDEADBEEF 20202021 22
+```
 
 **Commission the OTA Requestor application**
 
 ```
-./chip-tool pairing onnetwork-long ${REQUESTOR_NODE_ID} 20202021 ${REQUESTOR_LONG_DISCRIMINATOR}
+out/chip-tool pairing onnetwork-long 0x1234567890 20202021 18
 ```
 
--   `${REQUESTOR_NODE_ID}` is the node id to assign to the OTA Requestor
-    application running in terminal 2
--   `${REQUESTOR_LONG_DISCRIMINATOR}` is the long discriminator of the OTA
-    Requestor application specified in terminal 2 above
+**Write to the DefaultOTAProviders attribute**
 
-**Issue the AnnounceOTAProvider command**
+Note that this must be done within 30 seconds (as specified by the
+`--delayQuery 30`) from when the OTA Requestor application was launched
+
+```
+out/chip-tool otasoftwareupdaterequestor write default-ota-providers '[{"fabricIndex": 1, "providerNodeID": 3735928559, "endpoint": 0}]' 0x0000001234567890 0
+```
+
+After 30 seconds from when the OTA Requestor application has launched, the OTA
+Requestor application with node ID 0x1234567890 will send a QueryImage command
+to the OTA Provider with node ID 0xDEADBEEF, as specified in the
+`DefaultOTAProviders` attribute.
+
+## DefaultOTAProviders attribute
+
+The `DefaultOTAProviders` attribute represents a list of `ProviderLocation`
+structs. Each entry in this list is a default OTA Provider per fabric. There can
+not be more than one entry containing the same fabric.
+
+To add more than one entry to the `DefaultOTAProviders` attribute, the OTA
+Requestor app must be commissioned on multiple fabrics. This can be done as
+specified below:
+
+**Build and run the OTA Requestor application**
+
+```
+scripts/examples/gn_build_example.sh examples/ota-requestor-app/linux/ out chip_config_network_layer_ble=false
+out/chip-ota-requestor-app --discriminator 18 --secured-device-port 5560 --KVS /tmp/chip_kvs_requestor
+```
+
+**Commission to the first fabric**
+
+```
+out/chip-tool pairing onnetwork-long 0x1234567890 20202021 18
+```
+
+**Open Basic Commissioning Window**
+
+```
+out/chip-tool administratorcommissioning open-basic-commissioning-window 600 0x1234567890 0 --timedInteractionTimeoutMs 600
+```
+
+**Commission to the second fabric**
 
 ```
-./chip-tool otasoftwareupdaterequestor announce-ota-provider ${PROVIDER_NODE_ID} 0 0 0 ${REQUESTOR_NODE_ID} 0
+out/chip-tool pairing onnetwork-long 0x858 20202021 10 --commissioner-name beta
 ```
 
--   `${PROVIDER_NODE_ID}` is the OTA Provider application node ID assigned
-    during the pairing step above
--   `${REQUESTOR_NODE_ID}` is the OTA Requestor application node ID assigned
-    during the pairing step above
+For all operations, specify which fabric to use by passing in
+`--commissioner-name`. The supported values are alpha, beta, and gamma. By
+default, if none is supplied, alpha is used.
 
-The OTA Requestor application will process this command and send a QueryImage
-command to the OTA Provider
+**Write/Read DefaultOTAProviders on first fabric**
+
+```
+out/chip-tool otasoftwareupdaterequestor write default-ota-providers '[{"fabricIndex": 1, "providerNodeID": 3735928559, "endpoint": 0}]' 0x0000001234567890 0
+out/chip-tool otasoftwareupdaterequestor read default-ota-providers 0x1234567890 0
+```
+
+**Write/Read DefaultOTAProviders on second fabric**
+
+```
+out/chip-tool otasoftwareupdaterequestor write default-ota-providers '[{"fabricIndex": 1, "providerNodeID": 3735928559, "endpoint": 0}]' 0x858 0 --commissioner-name beta
+out/chip-tool otasoftwareupdaterequestor read default-ota-providers 0x858 0 --commissioner-name beta
+```
 
 ## Limitations