This guide details the end-to-end process of updating a Matter device using the standard OTA Provider and chip-tool applications.
.ota) for your device.software_version number associated with your OTA image.| Node ID | |
|---|---|
| Device (OTA Requestor) | 1000 |
| OTA Provider Sample App | 2000 |
| Node ID | |
|---|---|
| chip-tool (controller) | 112233 |
First, build the chip-tool and the ota-provider-app. These commands build the tools from the connectedhomeip root directory and place the output in the out/ directory.
# Activate the build environment source scripts/activate.sh # Build chip-tool ./scripts/examples/gn_build_example.sh examples/chip-tool out/chiptool # Build the Linux OTA Provider App ./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/debug chip_config_network_layer_ble=false
Before an OTA can be performed, the target device must be commissioned into a Matter fabric.
Commission the Device: Use chip-tool to pair the device. This example uses a manual pairing code. Replace ${DEVICE_NODE_ID} with a unique Node ID for your device (e.g., 1000) and ${MANUAL_PAIRING_CODE} with the code from your device.
# Command to pair a device using its manual pairing code ./out/chiptool/chip-tool pairing code ${DEVICE_NODE_ID} ${MANUAL_PAIRING_CODE} # Example: ./out/chiptool/chip-tool pairing code 1000 3497-011-2332
./out/chiptool/chip-tool pairing code ${DEVICE_NODE_ID} '${QR_CODE_PAYLOAD}', for example: ./out/chiptool/chip-tool pairing code 1000 'MT:EXAMPLE-QR-CODE-PAYLOAD'After successful commissioning, your device is part of the fabric and ready for the next steps. Let's assume you assigned the device Node ID 1000.
This process involves running the provider app and then using chip-tool to command the device to check for an update.
Open a new terminal and start the OTA Provider application. It needs to be running to serve the OTA image file to the device when requested.
.ota image file using the -f flag.# In a new terminal, activate the environment source scripts/activate.sh # Run the OTA provider app ./out/debug/chip-ota-provider-app --filepath ${OTA_IMAGE_PATH} -q updateAvailable --KVS ${OTA_PROVIDER_KVS_FILE} --secured-device-port ${OTA_PROVIDER_PORT} --discriminator ${OTA_PROVIDER_DISCRIMINATOR} --passcode ${OTA_PROVIDER_MANUAL_PAIRING_CODE} # Example: ./out/debug/chip-ota-provider-app --filepath image.ota -q updateAvailable --KVS /tmp/chip_kvs_provider --secured-device-port 5541 --discriminator 1111 --passcode 1234-567-8901
The provider is now running and waiting for devices to query it.
To ensure the device immediately checks for an update, we will manually configure it to trust our running OTA provider and then trigger an announcement.
Perform these chip-tool commands in your original terminal.
Pair OTA Provider using chip-tool on the same fabric:
# Command to pair a provider using its manual pairing code ./out/chiptool/chip-tool pairing code ${PROVIDER_NODE_ID} ${OTA_PROVIDER_MANUAL_PAIRING_CODE} # Example: ./out/chiptool/chip-tool pairing onnetwork 2000 0451-082-8541
Set ACL on Provider: Write to the ACL attribute on the device's “AccessControl” cluster in order to let the Device (DUT) request the Provider about available updates.
${ADMIN_NODE_ID}, defaults to 112233${DEVICE_NODE_ID}${PROVIDER_NODE_ID}# Write ACL to the Provider: ./out/chiptool/chip-tool accesscontrol write acl '[{"privilege": 5, "authMode": 2, "subjects": [${ADMIN_NODE_ID}], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": [${DEVICE_NODE_ID}], "targets": [{"cluster": 41, "endpoint": null, "deviceType": null}]}]' ${PROVIDER_NODE_ID} 0 # Example: ./out/chiptool/chip-tool accesscontrol write acl '[{"privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": [1000], "targets": [{"cluster": 41, "endpoint": null, "deviceType": null}]}]' 2000 0
Trigger the Update (Announce OTA Provider): This is the most effective command to force the device to check for an update. It simulates the provider announcing its presence to the device.
20000 (can be used as a wildcard)2 for kUrgentUpdateAvailable (advisory).1000# Announce OTA Provider ./out/chiptool/chip-tool otasoftwareupdatemanagement announce-ota-provider ${PROVIDER_NODE_ID} 0 2 0 ${DEVICE_NODE_ID} 0 # Example: ./out/chiptool/chip-tool otasoftwareupdaterequestor announce-otaprovider 2000 0 2 0 1000 0
In the OTA Provider terminal, you will see log output showing the device connecting and downloading the image. Key messages include:
[BDX] ...).On the device's console/log, you will see it receiving the command, querying the provider, downloading the new image, and applying the update before rebooting.
After the device reboots, you can use chip-tool to verify that its software version has changed.
Verify the OTA Provider Logs: Verify that the transfer of the software image happens all the way until the last Block is acknowledged from OTA Provider to DUT and below is the sample log provided for the raspi platform:
[1645748688025] [99779:20370762] CHIP: [BDX] OutputEvent type: AckEOFReceived [1645748688025] [99779:20370762] CHIP: [BDX] Transfer completed, got AckEOF
Read the SoftwareVersion attribute: Check the “Basic Information” cluster on the device.
# Replace ${DEVICE_NODE_ID} with your device's ID ./out/chiptool/chip-tool basicinformation read software-version ${DEVICE_NODE_ID} 0 # Example: ./out/chiptool/chip-tool basicinformation read software-version 1000 0
Read the SoftwareVersionString attribute:
# Replace ${DEVICE_NODE_ID} with your device's ID ./out/chiptool/chip-tool basicinformation read software-version-string ${DEVICE_NODE_ID} 0 # Example: ./out/chiptool/chip-tool basicinformation read software-version-string 1000 0
The output should now show the new software_version that corresponds to the OTA image you provided. Congratulations, you have successfully updated your Matter device!