From 7dbade1149c513a0b3669c1f5f7154403c6d837e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damian=20Kr=C3=B3lik?= <66667989+Damian-Nordic@users.noreply.github.com> Date: Fri, 21 Jan 2022 06:30:18 +0100 Subject: [PATCH] [nrfconnect] Update DFU documentation with info about Matter OTA (#13751) * [nrfconnect] Add description of the OTA testing procedure Signed-off-by: Damian Krolik * Restyled by prettier-markdown * Apply review comments * More review comments * Restyled by prettier-markdown * Silence mispell check Co-authored-by: Restyled.io --- .github/.wordlist.txt | 1 + .../nrfconnect_examples_software_update.md | 87 +++++++++++++++++-- 2 files changed, 80 insertions(+), 8 deletions(-) diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index 623f75eca7f241..bef9dbb18a275f 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -845,6 +845,7 @@ RendezVousTest repo req Requestor +Requestors responder retargeting reusability diff --git a/docs/guides/nrfconnect_examples_software_update.md b/docs/guides/nrfconnect_examples_software_update.md index 5b83ac0c9a4515..f15641670d20af 100644 --- a/docs/guides/nrfconnect_examples_software_update.md +++ b/docs/guides/nrfconnect_examples_software_update.md @@ -1,15 +1,86 @@ # Performing Device Firmware Upgrade in the nRF Connect examples Some examples for the development kits from Nordic Semiconductor support -over-the-air Device Firmware Upgrade. +over-the-air (OTA) Device Firmware Upgrade (DFU) using one of the following +protocols: -Currently, the Bluetooth LE is the only available transport for performing the -DFU operation and it uses nRF Connect SDK's -[Simple Management Protocol](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/zephyr/guides/device_mgmt/index.html#device-mgmt). -The upgrade can be done either using a smartphone application or a PC command -line tool. +- Matter-compliant OTA update protocol that uses the Matter operational + network for querying and downloading a new firmware image. +- [Simple Management Protocol](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/zephyr/guides/device_mgmt/index.html#device-mgmt) + over Bluetooth LE. In this case, the DFU can be done either using a + smartphone application or a PC command line tool. Note that this protocol is + not part of the Matter specification. -## Device Firmware Upgrade using smartphone +## Device Firmware Upgrade over Matter + +> **_NOTE:_** The procedure presented below requires that you have OpenThread +> Border Router (OTBR) set up either in Docker or on a Raspberry Pi. Read +> [Setup OpenThread Border Router on Raspberry Pi](openthread_border_router_pi.md) +> to learn how to install the OTBR on a Raspberry Pi. + +The DFU over Matter involves two kinds of nodes: OTA Provider and OTA Requestor. +An OTA Provider is a node that can respond to the OTA Requestors' queries about +available software updates and share the update packages with them. An OTA +Requestor is any node that needs to be updated and can communicate with the OTA +Provider to fetch applicable software updates. In the procedure described below, +the OTA Provider will be a Linux application and the example running on the +Nordic Semiconductor's board will work as the OTA Requestor. + +To test the DFU over Matter, you need to complete the following steps: + +1. Navigate to the CHIP root directory. +2. 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 + +3. Build chip-tool for Linux: + + $ scripts/examples/gn_build_example.sh examples/chip-tool out/chiptool 'chip_mdns="platform"' + +4. Run OTA Provider application with _app_update.bin_ replaced with the path to + the new firmware image which you wish to provide to the Matter device: + + $ out/provider/chip-ota-provider-app -f app_update.bin + + Keep the application running and use another terminal for the remaining + steps. + +5. Commission the OTA Provider into the Matter network using Node Id 1: + + $ ./out/chiptool/chip-tool pairing onnetwork 1 20202021 + +6. Use the OTBR web interface to form a new Thread network using the default + network settings. +7. Commission the Matter device into the same Matter network using Node Id 2. + 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 2 hex:000300000f02081111111122222222051000112233445566778899aabbccddeeff01021234 20202021 3840 + +8. Initiate the DFU procedure in one of the following ways: + + - If you have built the device firmware with `-DCONFIG_CHIP_LIB_SHELL=y` + option, which enables Matter shell commands, run the following command + on the device shell. The numeric arguments are Fabric Index, Provider + Node Id and Provider Endpoint Id, respectively. + + $ matter ota query 1 1 0 + + - Otherwise, 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-ota-provider 1 0 0 0 2 0 + + Once the device is made aware of the OTA Provider node, it automatically + queries the OTA Provider for a new firmware image. + +9. When the firmware image download is complete, reboot the device to apply the + update. + +## Device Firmware Upgrade over Bluetooth LE using smartphone To upgrade your device firmware over Bluetooth LE using smartphone, complete the following steps: @@ -30,7 +101,7 @@ following steps: [FOTA upgrades](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/ug_nrf52.html#fota-upgrades) page in the nRF Connect SDK documentation. -## Device Firmware Upgrade using PC command line tool +## Device Firmware Upgrade over Bluetooth LE using PC command line tool To upgrade your device firmware over Bluetooth LE, you can use the PC command line tool provided by the [mcumgr](https://github.com/zephyrproject-rtos/mcumgr)