OTA Requestor

The Matter Over-The-Air is a process that allows a Matter device in a Matter fabric to update its firmware.

The Matter Core Specification requires that each device implements a method for firmware update for security reasons. This OTA requestor sample demonstrates the usage of the Matter operational network for querying and downloading a new firmware image.

You can use this sample as a reference for creating your own application.

OTA Provider - This is a node that can respond to the OTA Requestors’ queries about available software updates and share the update packages with them.
OTA Requestor - This is any node that needs to be updated and can communicate with the OTA Provider to fetch applicable software updates.

In this sample, the OTA Provider will be a Linux application and this example will work as the OTA Requestor.

Requirements

The sample supports the following development kits:

Supported Development Kits
Hardware platforms	Board name
RTL8777G HDK	RTL8777G EVB

Prepare Matter Environment

To set up the Matter environment, follow the steps listed in Development Setup.

Prepare CHIP Tool

The CHIP Tool (chip-tool) is a Matter controller implementation that allows commissioning a Matter device into the network and communicating with it using Matter messages, which may encode Data Model actions, such as cluster commands. The tool also provides other utilities specific to Matter, such as parsing the setup payload or performing discovery actions.

To build the target, follow the steps listed on the CHIP Tool.

Configurations

The following configurations may be used in this sample.

CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION
A monotonic number identifying the software version running on the device.

CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION_STRING
A string identifying the software version running on the device.

See Matter APP Config for more information about configuration items.

Building and Downloading

Building

Navigate to the specified directory and build ota-requestor app.

$ cd beeSDK/subsys/matter/samples
$ rm -r build/
$ ./build.py rtl8777g ota-requestor --preset dual

Downloading

After a successful compilation, the app bin matter-cli-ftd_bank0_MP_dev_*.bin will be generated in the directory build/bank0/bin.

To download app bin into EVB board, follow the steps listed on the Downloading in Quick Start. If the factory data is enabled, also refer to Program Factory Data in Factory Data.

Then press reset button on EVB board and it will start running.

Preparing OTA image

To validate booting into a newer OTA Requestor image, the following must be performed:

The current software version of the OTA Requestor application is defined by CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION in CHIPProjectConfig.h. Modify CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION to a value greater than the current running version.
Building an OTA Requestor application with the new version.
The Matter OTA image is one of the build output files. The default location of the ota image is build/ota/matter.ota in the build directory.
Use this generated binary when supplying the image file to the OTA Provider application.

Experimental Verification

To test the sample, you need to complete the following steps:

Navigate to the CHIP root directory.

Build the OTA Provider application for Linux:

$ scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/provider chip_config_network_layer_ble=false

Run OTA Provider application with matter.ota replaced with the path to the Matter OTA image which you wish to provide to the Matter device. Note that the Matter OTA image is, by default, generated at build/ota/matter.ota in the example’s build directory:
```
$ ./out/provider/chip-ota-provider-app -f matter.ota
```
- Keep the application running and use another terminal for the remaining steps.
Commission the Matter device using Node ID 1. The parameter starting with the hex: prefix is the Thread network’s Active Operational Dataset. It can be retrieved from the OTBR in case you have changed the default network settings when forming the network.
```
$ ./out/chiptool/chip-tool pairing ble-thread 1 hex:<operationalDataset> 20202021 3840
```
Commission the OTA Provider into the Matter network using Node ID 2:
```
$ ./out/chiptool/chip-tool pairing onnetwork 2 20202021
```
Configure the Matter device with the default OTA Provider by running the following command (the last two arguments are Requestor Node ID and Requestor Endpoint ID, respectively):
```
$ ./out/chiptool/chip-tool otasoftwareupdaterequestor write default-otaproviders '[{"fabricIndex": 1, "providerNodeID": 2, "endpoint": 0}]' 1 0
```

Configure the OTA Provider with the access control list (ACL) that grants Operate privileges to all nodes in the fabric. This is necessary to allow the nodes to send cluster commands to the OTA Provider:

$ ./out/chiptool/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": [{"cluster": 41, "endpoint": null, "deviceType": null}]}]' 2 0

Use chip-tool to send the Announce OTA Provider command to the device (the numeric arguments are Provider Node ID, Provider Vendor ID, Announcement Reason, Provider Endpoint ID, Requestor Node ID and Requestor Endpoint ID, respectively):
```
$ ./out/chiptool/chip-tool otasoftwareupdaterequestor announce-otaprovider 2 0 0 0 1 0
```
The OTA process should include downloading the image, verification of image header, erasing upgraded flash partition, writing to flash and checksum verification. Once OTA signature is updated, device will reboot into the new image after 10 seconds countdown.