Matter OTA Updates#

Introduction#

Matter is a royalty-free standard to connect compatible devices and systems with one another. Its goal is to make connections simpler, more secure and scalable with the foundation for connected things in home and building automation applications. In following the steps of this module, developers will understand how to set up their matter environment to support an over-the-air update between the Matter controller OTA provider and device OTA requestor. This will result in successfully updating the application of a Matter application, such as lock-app, using over-the-air communication.

In this lab we will be working with a 64-bit x86 Linux machine, either a BeagleBone Black or Raspberry Pi system, a Wi-Fi router, and two LaunchPads to create a Matter fabric. The following tasks and their companion instructions require familiarity with Linux environments and should take one to two hours to complete, not including installation or the prerequisite instructions listed below.

  • Task 0: Check prerequisites

  • Task 1: Build the OTA provider

  • Task 2: Build the new application image

  • Task 3: Perform the OTA update

Note

Technical support: For any questions you may have, please refer to the TI Zigbee & Thread E2E Forum.

Warning

Only Matter over Thread is discussed in this module

Prerequisites#

Both the Matter Device SLA and Matter Fabric SLA must be completed before attempting this module. It is also highly recommended that you read and get familiar with the Matter Documentation as it will be referenced throughout this module. The Matter Specification is also necessary for further Matter development.

Software#

Hardware#

Overview#

In this section we give an overview of the Matter device and OTA Software Update Clusters

Warning

Only Linux 64-bit x86 is supported SysConfig and UniFlash are not intended for 32-bit or ARM Linux machines

../../../_images/matter_blockdiagram3.png

Matter Environment#

About the Matter Device#

A Matter device is a device which exists within a Matter fabric. Through connection with a Thread Border Router, the Matter device can communicate with an adjacent IPv6 network (an Internet Protocol version 6 network that the Border Router is also connected to. Wi-Fi or Ethernet, for example). In this way the Matter device can achieve communication with Cloud services and other devices within the Matter fabric.

Matter devices can support many different home automation applications, including lighting, actuation, switches, controllers, sensors, closures, HVAC, and media. These are built on the ZCL (Zigbee Cluster Library)
which contains a defined structure of endpoints, clusters, attributes, commands, and data types. Endpoints represent one logical device, and multiple can exist per Matter device. One or more cluster, which is a set of attributes and commands that achieve the desired functionality, is defined per endpoint.

By adhering to the ZCL, products can become certifiable by the CSA (Connectivity Standards Alliance) and thus prove interoperability with third-party Matter devices available. You can learn more about the certification process from the CSA website. For additional details concerning Matter commissioning and controller resources, please review the Matter Device SLA and Matter Controller SLA.

About OTA Updates#

The OTA Software Update Requestor/Provider Clusters provide a standard mechanism for wirelessly upgrading a Matter device’s firmware utilizing the established Thread network. Over the Air upgrade sessions take place between a client and server. The OTA Client requests and then downloads an OTA Software image which is hosted by the OTA Provider Cluster Server. The clusters are typically defined on endpoint zero of both client/server, please see the Zigbee Specification Documents for more information.

The OTA Provider project will be utilized as the OTA Provider cluster server host to provide the updated OTA image. It will run consecutively on the same Linux device which operates the chip-tool project.

Task 0 – Check prerequisites#

Before beginning the OTA update procedure, there are two assumptions which must be confirmed:

  • Matter Device SLA: The Matter lock-app project has been built, programmed onto a CC1354P10 LaunchPad, and is fully operational

  • Matter Fabric SLA: The chip-tool project has been built using a Raspberry Pi 4 or 64-bit x86 Linux machine and uses the accompanying OTBR (OpenThread Border Router) and RCP (Radio Co-Processor) LaunchPad to establish a Matter Fabric

If at this point you cannot commission the lock-app project into the chip-tool Matter fabric, please review the previous SimpleLink Academy Labs.

Task 1 – Build the new application image#

The lock-app project has already enabled the OTA Requestor cluster server by having chip_enable_ota_requestor = true inside of args.gn. However, both matter_software_ver and matter_software_ver_str must be incremented so that the new image which will be stored by the OTA Provider shows as being an updated version when queried by the Matter device.

args.gn#
matter_software_ver = "0x0002"
matter_software_ver_str = "2.0d1"

After making the changes above and re-building the project, save the chip-LP_EM_CC1354P10-lock-example.ota file located in the matter/examples/lock-app/cc13x4_26x4/out/debug directory to a known location for future use.

Note

Want to make additional application changes? The Configuring Matter Device Applications SLA provides guidance concerning useful sections of the application code which can be modified to affect the physical behavior of the lock-app project.

Task 2 – Build the OTA provider project#

The instructions from this task should take place on the same Linux machine which is operates as the Matter controller and uses the CHIP Tool project. As with chip-tool, the ota-provider-app requires a one-line instruction to the target binaries. BUILD_PATH is the output directory (for example, use ota_provider_out to create a matter/ota_provider_out output folder).

$ cd ~/connectedhomeip
$ scripts/examples/gn_build_example.sh examples/ota-provider-app/linux BUILD_PATH chip_config_network_layer_ble=false

You can confirm operation of the OTA Provider application by entering the BUILD_PATH and using ./chip-ota-provider-app to print all available commands. The -f command line option specifies a path to the OTA image file, so for simplicity the chip-LP_EM_CC1354P10-lock-example.ota file should be directly copied into the OTA Provider output folder to be used in the next task.

Task 3 – Perform the OTA update#

The environment should now be completely set up to perform the OTA update.
Two terminals should be opened on the Linux platform, one directing to the ota-provider-app output folder. Run this project with the following command:

$ ./chip-ota-provider-app --passcode 20202021 --discriminator 22 --secured-device-port 5565 --KVS /tmp/chip_kvs_provider -f chip-LP_EM_CC1354P10-lighting-example.ota -q updateAvailable

The next teminal should point to the chip-tool output directory. First, make sure that the lock-app has joined the chip-tool Matter fabric (full instructions are available in the aforementioned Matter SLA prerequisites). The ota-provider-app can then be commissioned into the chip-tool network with the following command:

$ ./chip-tool pairing onnetwork-long 0xFEEDC0DE 20202021 22

Where 0xFEEDCODE is the node ID variable selected for the ota-provider-app and must be different from the lock-app designation. 20202021 is the PIN code and 3840 is the discriminator chosen when starting ota-provider-app. It is now possible to set the default OTA Provider for the Matter device (for the example given, 29 is the node ID).

$ ./chip-tool otasoftwareupdaterequestor write default-ota-providers '[{"fabricIndex":1, "providerNodeID": 2, "endpoint": 0}]' 29 0

The chip-tool project must then install necessary ACL entries to enable processing of QueryImage commands from OTA Requestors on their fabric, otherwise that OTA Provider will not be usable by OTA Requestors.

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

Finally, the OTA process can commence by announcing the OTA Provider to the lock-app device.

$ ./chip-tool otasoftwareupdaterequestor announce-ota-provider 0xFEEDC0DE 0 0 0 29 0

In the example above, 29 represents the node ID of the lock-app device. If done properly, the lock-app UART terminal and ota-provider-app log should begin rapidly transmitting messages (Image Block Requests/Responses). The OTA update will finish once the EOF (End Of Frame) Acknowledgement has been received by the OTA Provider App, at which point the Matter lock-app device will apply the update and start running the new image.

Further Reading#

It is recommended that you read the Matter Specification for specific network operation and other Matter documentation for more information on the Matter software development environment.