From 3992a17bd17cc669376286713d4160ce62bcf8cc Mon Sep 17 00:00:00 2001 From: Carol Yang Date: Thu, 7 Apr 2022 19:00:05 -0700 Subject: [PATCH] [OTA] Update OTA Requestor cluster README (#17156) --- .github/.wordlist.txt | 10 +- src/app/clusters/ota-requestor/README.md | 154 ++++++++++++++++++----- 2 files changed, 127 insertions(+), 37 deletions(-) diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index 76d98db1ac11f4..2ee3662f89df21 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -338,6 +338,9 @@ debugText DEDEDEDE deepnote DefaultOTAProviders +DefaultOTARequestor +DefaultOTARequestorDriver +DefaultOTARequestorStorage DefaultSuccess definedValue DehumidificationControl @@ -414,6 +417,7 @@ DoorLock doru DOTBR DOVERLAY +DownloadProtocolEnum downcasting Doxygen dpkg @@ -730,8 +734,6 @@ lightin LightingColor LightingState LinkSoftwareAndDocumentationPack -LinuxOTAImageProcessor -LinuxOTARequestorDriver LocalConfigDisabled localedef localhost @@ -921,9 +923,10 @@ OTAProviderIpAddress OTAProviderNodeId OTAProviderSerialPort OTARequesterImpl -OTARequestor +OTARequestorInterface OTARequestorDriver OTARequestorSerialPort +OTARequestorStorage OtaSoftwareUpdateProvider otasoftwareupdaterequestor otatesting @@ -1126,6 +1129,7 @@ SerialNumber ServiceId SetDns SetImageProcessorDelegate +SetOTADownloader SetOtaRequestorDriver setpin setpoint diff --git a/src/app/clusters/ota-requestor/README.md b/src/app/clusters/ota-requestor/README.md index e76e16a4e57e44..30550cbd300ad6 100644 --- a/src/app/clusters/ota-requestor/README.md +++ b/src/app/clusters/ota-requestor/README.md @@ -3,48 +3,134 @@ This is an implementation of the Matter OTA Requestor functionality that can be used by Matter applications for OTA software updates -## Steps for including the OTA Requestor functionality in a Matter application +## Design Overview -- Enable the OTA Requestor Server cluster and the OTA Provider cluster in the - application +There are various components defined to support OTA software updates. The Matter +SDK supplies the default implementation to all components. If so desired, a +custom implementation may be used to replace the default implementation. -- Explicitly list all the source files in `src/app/clusters/ota-requestor` in - the application's make/build file. See for example - `examples/ota-requestor-app/ota-requestor-common/BUILD.gn` +### OTARequestorInterface -- Implement a class derived from `OTARequestorDriver`, see for example - `LinuxOTARequestorDriver`. This class would typically be a part of the - application. +This is an interface for processing the core requestor logic. This includes +sending commands to the OTA Provider cluster as well as handling the responses +for those commands. This component also maintains the server attributes for the +OTA Requestor cluster. -- In the application initialization logic create an instance of the - `OTARequestor` class and register it through `SetRequestorInstance()`. - Create an instance of the `OTARequestorDriver` implementation and connect it - to the `OTARequestor` object by calling - `OTARequestor::SetOtaRequestorDriver()` +`DefaultOTARequestor` class is the default implementation of this interface. Any +custom implementation should reside under `examples/platform/`. -- Implement a class derived from `OTAImageProcessorInterface`, see for example - `LinuxOTAImageProcessor`. This class would typically be a part of the - platform. +### OTARequestorDriver -- In the application initialization logic create an instance of the - `BDXDownloader` class. Create an instance of the - `OTAImageProcessorInterface`-derived implementation (e.g. - `LinuxOTAImageProcessor`) and connect it to the `BDXDownloader` object by - calling `BDXDownloader::SetImageProcessorDelegate()` +This is an interface for using/driving the `OTARequestorInterface`. This +component determines the next action to take based on the current status +returned by `OTARequestorInterface`. For instance, after `OTARequestorInterface` +receives a QueryImageResponse that an update is available, it informs +`OTARequestorDriver` which then decides whether it is ready to immediately start +the download or to wait on some conditions. -- See `examples/ota-requestor-app/linux/main.cpp` for an example of the - initialization code discussed above +`DefaultOTARequestorDriver` class is the default implementation of this +interface. Any custom implementation should reside under +`examples/platform/`. -- Implement application- and platform-specific logic related to image download - and update such as platform-specific image storage and validation, - application-specific logic for triggering image query and applying the - downloaded image, etc. +Please note the following implementation choices in the default implementation: -- The interface between the core OTA Requestor functionality and the - platform/application logic is realized through the virtual functions of - `OTARequestorDriver` and `OTAImageProcessorInterface` and through the - application interface methods of `OTARequestor` and `BDXDownloader`. +- Upon being notified that an update is available, the image is + unconditionally downloaded +- Upon being notified that the provider is busy, a max number of retries is + attempted before the next provider in the default OTA provider list (if one + exists) is attempted +- Upon being notified that an update is not available, querying of the next + provider in the default OTA Provider list (if one exists) is attempted +- Upon being notified that an update has been downloaded, the request to apply + the image is immediately sent to the provider +- Upon being notified that the update may proceed after download, the image is + unconditionally applied via the `OTAImageProcessorInterface` +- Upon being notified that the update should be discontinued after download, + the entire process is aborted +- Upon a first time boot into a newly applied image, if the image can be + confirmed, the provider is immediately notified of the update being applied + successfully +- If an existing OTA update is already in progress, any new attempts to query + will be denied +- A periodic query is attempted every 24 hours, unless overridden +- The periodic query timer starts whenever `OTARequestorInterface` is in the + idle state -## Design Overview +### OTAImageProcessorInterface + +This is a platform-agnostic interface for processing downloaded chunks of OTA +image data. The data could be raw image data meant for flash or metadata. This +component should interact with the `OTADownloader` to drive the download +process. + +Each platform should provide an implementation of this interface which should +reside under `src/platform/`. + +### OTADownloader + +This is an interface for image download functionality over a particular +protocol. Each `DownloadProtocolEnum` supported should provide an implementation +of this interface. -To be completed.. +`BDXDownloader` class is an implementation of this interface for the BDX +protocol. + +### OTARequestorStorage + +This is an interface for storing/loading persistent data related to OTA. + +`DefaultOTARequestorStorage` class is the default implementation of this +interface. Any custom implementation should reside under +`examples/platform/`. + +## Steps for including the OTA Requestor functionality in a Matter application + +- Enable `Server` for the OTA Software Update Requestor cluster in the + application zap file +- Enable `Client` for the OTA Software Update Provider cluster in the + application zap file +- Implement OTA Requestor components: + - Use the `DefaultOTARequestor` class or implement a class derived from + `OTARequestorInterface` + - Use the `DefaultOTARequestorDriver` class or implement a class derived + from `OTARequestorDriver` + - Use the `BDXDownloader` class or implement a class derived from + `OTADownloader` + - Implement a class derived from `OTAImageProcessorInterface` + - Use the `DefaultOTARequestorStorage` class or implement a class derived + from `OTARequestorStorage` +- If using the default implementation of the interfaces defined above, + explicitly list all the source files in `src/app/clusters/ota-requestor` in + the application make/build file. For example: `src/app/chip_data_model.gni`. + Otherwise, list the source files where the component implementation reside. +- Explicitly list all the OTA platform specific files in `src/platform`. For + example: `src/platform/Linux/BUILD.gn` +- Instantiate and initialize each component in the application. For example, + in an application which uses the default implementation on the Linux + platform: + - Create an instance of the `DefaultOTARequestor` class + - Create an instance of the `DefaultOTARequestorDriver` class + - Create an instance of the `OTAImageProcessorImpl` class from + `src/platform/Linux/OTAImageProcessorImpl.h` + - Create an instance of the `BDXDownloader` class + - Create an instance of the `DefaultOTARequestorStorage` class + - Register the instance of `DefaultOTARequestor` through + `SetRequestorInstance()` + - Initialize the instance of `DefaultOTARequestorStorage` through + `DefaultOTARequestorStorage::Init` + - Connect the instances of `DefaultOTARequestorStorage`, + `DefaultOTARequestorDriver`, and `BDXDownloader` with the instance of + `DefaultOTARequestor` through `DefaultOTARequestor::Init`() + - Connect the instances of `DefaultOTARequestor` and + `OTAImageProcessorImpl` with the instance of `DefaultOTARequestorDriver` + through `DefaultOTARequestorDriver::Init`(). It is important that this + is performed after `DefaultOTARequestor::Init` as there are dependencies + that `DefaultOTARequestor` already has access to + `DefaultOTARequestorDriver` by the time this initialization occurs. + - Connect the instance of `BDXDownloader` with the instance of + `OTAImageProcessorImpl` through + `OTAImageProcessorImpl::SetOTADownloader` + - Connect the instance of `OTAImageProcessorImpl` with the instance of + `BDXDownloader` through `OTADownloader::SetImageProcessorDelegate` +- See `examples/ota-requestor-app/linux/main.cpp` for an example of the + initialization code above