# Matter OTA ## Generate CHIP OTA image User can generate the Matter OTA image by simply enabling `CONFIG_CHIP_OTA_IMAGE_BUILD` config option. OTA image is generated in `build` directory with name `-ota.bin`. This image then can be used with OTA Provider Application. Please make sure that version number is set to correct value. Use `CONFIG_DEVICE_SOFTWARE_VERSION` and `CONFIG_DEVICE_SOFTWARE_VERSION_NUMBER` config options for setting software version. Matter OTA image can also be generated using [ota_image_tool.py](https://github.com/project-chip/connectedhomeip/blob/master/src/app/ota_image_tool.py) script. ## Enabling OTA Requestor - Please make sure `CONFIG_ENABLE_OTA_REQUESTOR` config option is enabled for enabling OTA requestor feature. - Currently all-clusters-app, lighting-app, and ota-requestor-app supports OTA requestor functionality. - Build and flash any supported app, and commission it. ## Setup OTA Provider app Setup any of the OTA Provider, commission it and install the appropriate access control list. - [Linux OTA Provider](../../../examples/ota-provider-app/linux) - [ESP32 OTA Provider](../../../examples/ota-provider-app/esp32) ## Query for an OTA Image ### Using Console After commissioning is successful, read the default-otaproviders list of requestor using the command below. ``` ./out/debug/chip-tool otasoftwareupdaterequestor read default-otaproviders 0 ``` If the list does not have your provider, write into default-otaproviders list of requestor using the command below. ``` ./out/debug/chip-tool otasoftwareupdaterequestor write default-otaproviders '[{"fabricIndex": 1, "providerNodeID": , "endpoint": 0}, {"fabricIndex": 1, "providerNodeID": , "endpoint": 0}]' 0 ``` Press Enter in requestor device console and type below query. ``` >matter ota query ``` Once the transfer is complete, OTA requestor sends ApplyUpdateRequest command to OTA provider for applying the image. Device will restart on successful application of OTA image. ### Using chip-tool After commissioning is successful, announce OTA provider's presence using chip-tool. On receiving this command OTA requestor will query for OTA image. ``` ./out/debug/chip-tool otasoftwareupdaterequestor announce-otaprovider 0 0 0 0 ``` ## Encrypted OTA ESP32 supports transferring encrypted OTA images. Currently, an application image can be encrypted/decrypted using an RSA-3072 key pair. ### Firmware Changes - Enable configuration options for OTA requestor and Encrypted OTA: ``` CONFIG_ENABLE_OTA_REQUESTOR=y CONFIG_ENABLE_ENCRYPTED_OTA=y ``` - Applications need to provide the key pair to the OTA image processor using the `InitEncryptedOTA()` API to decrypt the received OTA image. - For testing purposes, in `examples/lighting-app/esp32`, there is a logic of embedding the private key in the firmware. To quickly test, please generate the key pair and rename it as `esp_image_encryption_public_key.pem` and copy it to directory `examples/lighting-app/esp32`. Please follow the steps below to generate an application image for OTA upgrades: 1. Generate a new RSA-3072 key pair or use an existing one. - To generate a key pair, use the following command: ``` openssl genrsa -out esp_image_encryption_key.pem 3072 ``` - Extract the public key from the key pair: ``` openssl rsa -in esp_image_encryption_key.pem -pubout -out esp_image_encryption_public_key.pem ``` 2. Encrypt the application binary using the [esp_enc_img_gen.py](https://github.com/espressif/idf-extra-components/blob/master/esp_encrypted_img/tools/esp_enc_img_gen.py) script. - Use the following command to encrypt the OTA image with the public key: ``` python3 esp_enc_img_gen.py encrypt lighting-app.bin esp_image_encryption_public_key.pem lighting-app-encrypted.bin ``` - Append the Matter OTA header: ``` src/app/ota_image_tool.py create --vendor-id 0xFFF1 --product-id 0x8000 --version 2 --version-str "v2.0" -da sha256 lighting-app-encrypted.bin lighting-app-encrypted-ota.bin ``` 3. Use the `lighting-app-encrypted-ota.bin` file with the OTA Provider app. ## Delta OTA Delta OTA Updates is a feature that enables Over-the-Air (OTA) firmware update with compressed delta binaries. Patch files have smaller size than the original firmware file, which reduces the time and network usage to download the file from the server. Also, no additional storage partition is required for the "patch". ### Firmware Changes - Enable configuration options for OTA requestor and Delta OTA: ``` CONFIG_ENABLE_OTA_REQUESTOR=y CONFIG_ENABLE_DELTA_OTA=y ``` Please follow the steps below to generate an application image for OTA upgrades: 1. Delta binary needs to be generated using binary delta encoding in Python 3.6+. You can install `detools` using the following command. ``` pip install detools>=0.49.0 ``` 2. Generate delta binary. ``` python managed_components/espressif__esp_delta_ota/examples/https_delta_ota/tools/esp_delta_ota_patch_gen.py --chip --base_binary --new_binary --patch_file_name ``` 3. Append the Matter OTA header: `src/app/ota_image_tool.py create --vendor-id 0xFFF1 --product-id 0x8000 --version 2 --version-str "v2.0" -da sha256 lighting-app-delta-ota.bin` 4. Use the `lighting-app-delta-ota.bin` file with the OTA Provider app. ## Encrypted Delta OTA To use encrypted delta OTA, follow the below steps. ### Firmware Changes - Enable configuration options for OTA requestor, Delta OTA and Encrypted OTA: ``` CONFIG_ENABLE_OTA_REQUESTOR=y CONFIG_ENABLE_DELTA_OTA=y CONFIG_ENABLE_ENCRYPTED_OTA=y ``` 1. Follow the step of `Generate a new RSA-3072 key pair or use an existing one` of [Encrypted OTA](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/esp32/ota.md#encrypted-ota) to build your binary. 2. Create delta binary as shown in `Generate delta binary` of [Delta OTA](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/esp32/ota.md#delta-ota) 3. Encrypt the application binary. 4. Append the Matter OTA header.