Guide: Updating a Matter Device Using the OTA Provider Sample App

Guide: Updating a Matter Device Using the OTA Provider Sample App#

This guide details the end-to-end process of updating a Matter device using the standard OTA Provider and chip-tool applications.

Prerequisites#

  1. A working Matter build environment.

  2. A Matter device (e.g., an example app running on a dev kit) that you can commission.

  3. An OTA image package file (.ota) for your device.

  4. The software_version number associated with your OTA image.

Node IDs#

Node ID

Device (OTA Requestor)

1000

OTA Provider Sample App

2000

Default from SDK#

Node ID

chip-tool (controller)

112233

Step 1: Build the Required Tools#

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

Step 2: Commission Your Matter Device#

Before an OTA can be performed, the target device must be commissioned into a Matter fabric.

  1. 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

    • Finding the Pairing Code: The device will either print a QR code link or a numeric code to its console/log output upon startup.

    • QR Code: If you have a QR code, you can use: ./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.

Step 3: Prepare and Run the OTA Update#

This process involves running the provider app and then using chip-tool to command the device to check for an update.

3.1. Start the OTA Provider App#

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.

  • The provider will be assigned its own Node ID on the fabric. By default, it will use Node ID ${PROVIDER_NODE_ID}.

  • You must provide the path to your .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.

3.2. Configure the Device to Use the OTA Provider#

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.

  1. 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

  2. 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.

    • Chip-tool (controller) Node ID: ${ADMIN_NODE_ID}, defaults to 112233

    • DUT (Requestor) Node ID: ${DEVICE_NODE_ID}

    • OTA Provider 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

  3. 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.

    • Provider Node ID: for example, 2000

    • Vendor/Product ID: 0 (can be used as a wildcard)

    • Announcement Reason: 2 for kUrgentUpdateAvailable (advisory).

    • Target Device Node ID: e.g., 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

3.3. Monitor the Update#

  • In the OTA Provider terminal, you will see log output showing the device connecting and downloading the image. Key messages include:

    • Progress indicators for the image download ([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.

Step 4: Verify the Update#

After the device reboots, you can use chip-tool to verify that its software version has changed.

  1. 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

  2. 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

  3. 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!