# ESP Delta OTA
## Getting Started
Compressed Delta OTA Updates aims at enabling Over-the-Air firmware update with compressed delta binaries.
### Compressed Delta Image for OTA
### Advantages of using this design for OTA update:
* Patch file have smaller size than the original firmware file. This reduces the time and network usage to download the file from server.
* No additional storage partition is required for the "patch".
* Only firmware level changes are required for integrating this component. No bootloader related changes required.
* This scheme can be implemented for the existing devices in the field.
* **ESP-IDF v4.3 and above**
You can visit the [ESP-IDF Programmming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html#installation-step-by-step) for the installation steps.
* **detools v0.49.0 and above**
Binary delta encoding in Python 3.6+. You can install detools using the following command:
pip install -r examples/https_delta_ota/tools/requirements.txt
More information about the package [here](https://pypi.org/project/detools/).
Refer to the [https_delta_ota](https://github.com/espressif/idf-extra-components/blob/master/esp_delta_ota/examples/https_delta_ota/) example to see the use of `esp_delta_ota` component for OTA updates.
## API Reference
To learn more about how to use this component, please check API Documentation from header file [esp_delta_ota.h](https://github.com/espressif/idf-extra-components/blob/master/esp_delta_ota/include/esp_delta_ota.h)
* Distributed under the Apache-2.0 License. Refer [esp_delta_ota LICENSE](https://github.com/espressif/idf-extra-components/blob/master/esp_delta_ota/LICENSE) for more information.
* `detools` : Distributed under the BSD 2-Clause License. Refer [detools LICENSE](https://github.com/eerimoq/detools/blob/master/LICENSE) for more information.
* `heatshrink` : Distributed under the ISC License. Refer [heatshrink LICENSE](https://github.com/eerimoq/detools/blob/master/c/heatshrink/README.rst) for more information.
- Added support to pass user data to write callback with new callback function: `merged_stream_write_cb_with_user_ctx_t`
- The older write callback function: `merged_stream_write_cb_t` has been deprecated and will be removed in the next major release.
readme of https_delta_ota example
# HTTPS Delta OTA
Compressed Delta OTA Updates aims at enabling Over-the-Air firmware update with compressed delta binaries. Instead of the original binary to be hosted on the OTA update server, a patch file is hosted which is the difference between the base firmware and the new firmware in compressed form. This reduces the size of the file to be downloaded when performing OTA updates thus reducing the network usage. This also reduces the time taken to complete the OTA process.
This example demonstrates OTA updates with compressed patch binary using `esp_delta_ota` component's APIs and tool.
Compressed patch generated for the new firmware must be hosted on OTA update server. See [How to generate the patch](#creating-patch).
This patch will be downloaded and then applied on the current running firmware on device. The new firmware after applying the patch will be written in a new partition.
## ESP Delta OTA Abstraction Layer
This example uses `esp_delta_ota` component hosted at [idf-extra-components/esp_delta_ota](https://github.com/espressif/idf-extra-components/blob/master/esp_delta_ota) and available though the [IDF component manager](https://components.espressif.com/component/espressif/esp_delta_ota).
Please refer to its documentation [here](https://github.com/espressif/idf-extra-components/blob/master/esp_delta_ota/README.md) for more details.
## How to use the example
### Configure the project
Open the project configuration menu(`idf.py menuconfig`)
In the `Example Connection Configuration` menu:
* Choose the network interface in the `Connect using` option based on your board. Currently both Wi-Fi and Ethernet are supported
* If the Wi-Fi interface is used, provide the Wi-Fi SSID and password of the AP you wish to connect to
* If using the Ethernet interface, set the PHY model under `Ethernet PHY Device` option, e.g. `IP101`
In the `Example Configuration` menu:
* Set the URL of the firmware to download in the `Firmware Upgrade URL` option. The format should be `https://<host-ip-address>:<host-port>/<firmware-image-filename>`, e.g. `https://192.168.2.106:8070/hello_world.bin`
### Build and Flash example
idf.py build flash
### Creating Patch
Now we will consider this firmware as the base firmware which we will flash into the device. We need a new firmware to which we want to upgrade to. You can try building the `hello_world` example present in ESP-IDF.
We need to create a patch file for this new firmware.
Install required packages:
pip install -r tools/requirements.txt
To create a patch file, use the [python tool](./tools/esp_delta_ota_patch_gen.py)
python esp_delta_ota_patch_gen.py --chip <target> --base_binary <base_binary> --new_binary <new_binary> --patch_file_name <patch_file_name>
This will generate the patch file for the new binary which needs to be hosted on the OTA update server.
> **_NOTE:_** Make sure that the firmware present in the device is used as `base_binary` while creating the patch file. For this purpose, user should keep backup of the firmware running in the device as it is required for creating the patch file.