docs/guides/updating-matter-device-guide.md

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

```bash
# 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.

    ```bash
    # 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.

```bash
# 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:**

    ```bash
    # 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}`

    ```bash
    # 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`

    ```bash
    # 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.

    ```bash
    # 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:**

    ```bash
    # 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!