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#
Matter Controller options:
64-bit x86 Linux machine: Linux distribution
Raspberry Pi 4: Raspberry Pi Imager
OpenThread Border Router options:
Raspberry Pi 3 or 4: Raspberry Pi Imager
BeagleBone Black: Debian IoT image and Etcher
(Optional) Raspberry Pi SSH:
Hardware#
Matter Controller options:
64-bit x86 Linux machine
OpenThread Border Router options:
RCP
(Radio Co-Processor) LaunchPad options:Matter device: SimpleLink CC1354P10 LaunchPad with XDS110ET LaunchPad
Wi-Fi Router, ethernet cable
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
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) andRCP
(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.
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.