OTA Requestor

This is an implementation of the Matter OTA Requestor functionality that can be used by Matter applications for OTA software updates

Design Overview

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.

OTARequestorInterface

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.

DefaultOTARequestor class is the default implementation of this interface. Any custom implementation should reside under examples/platform/<platform-name>.

OTARequestorDriver

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.

DefaultOTARequestorDriver class is the default implementation of this interface. Any custom implementation should reside under examples/platform/<platform-name>.

Please note the following implementation choices in the default implementation:

• 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

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.

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