[OTA] Update OTA Requestor cluster README (#17156)

.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

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/<platform-name>`.
 
--   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/<platform-name>`.
 
--   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/<platform-name>`.
+
+### 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/<platform-name>`.
+
+## 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