-
Notifications
You must be signed in to change notification settings - Fork 768
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'docs/esp_tinyuf2' into 'master'
docs(esp_tinyuf2): add api reference Closes AEG-1008 See merge request ae_group/esp-iot-solution!1084
- Loading branch information
Showing
14 changed files
with
279 additions
and
126 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,96 +1,15 @@ | ||
| ## ESP TinyUF2 | ||
|
|
||
| The enhanced version of [TinyUF2](https://github.com/adafruit/tinyuf2) for ESP32Sx, which supports over-the-air (OTA) updates for APP. **and supports dumping NVS key-value pairs to the config file, users can modify and write back to NVS**. | ||
| `esp_tinyuf2` is an enhanced version of [TinyUF2](https://github.com/adafruit/tinyuf2) for ESP chips with USB-OTG support. Which features: | ||
|
|
||
| UF2 is a file format developed by Microsoft for [PXT](https://github.com/Microsoft/pxt), that is particularly suitable for flashing microcontrollers over MSC (Mass Storage Class). For a more friendly explanation, check out [this blog post](https://makecode.com/blog/one-chip-to-flash-them-all). | ||
| - support over-the-air (OTA) updates through the virtual USB drive | ||
| - support dumping NVS key-value pairs to ini file in the virtual USB drive | ||
| - support modify ini file and write back to NVS | ||
|
|
||
| ## Support UF2 OTA/NVS in Your Project | ||
|  | ||
|
|
||
| 1. Add the component to your project using `idf.py add_dependency` command. | ||
|
|
||
| ```sh | ||
| idf.py add-dependency "esp_tinyuf2" | ||
| ``` | ||
| ### How to use | ||
|
|
||
| 2. Customer your partition table. Like other OTA solutions, you need to reserve at least two OTA app partitions. Please refer to [Partition Tables](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html) and [usb_uf2_ota](../../../examples/usb/device/usb_uf2_ota/) example for details. | ||
| [esp_tinyuf2 user guide](https://docs.espressif.com/projects/esp-iot-solution/en/latest/usb/usb_device/esp_tinyuf2.html) | ||
|
|
||
| ``` | ||
| # Partition Table Example | ||
| # Name, Type, SubType, Offset, Size, Flags | ||
| nvs, data, nvs, , 0x4000, | ||
| otadata, data, ota, , 0x2000, | ||
| phy_init, data, phy, , 0x1000, | ||
| ota_0, app, ota_0, , 1500K, | ||
| ota_1, app, ota_1, , 1500K, | ||
| ``` | ||
|
|
||
| 3. Using `idf.py menuconfig` to config the component's behavior in `(Top) → Component config → TinyUF2 Config` | ||
| * `USB Virtual Disk size(MB)`: The size of the virtual U-disk shows in File Explorer, 8MB by default | ||
| * `Max APP size(MB)`: Maximum APP size, 4MB by default | ||
| * `Flash cache size(KB)`: Cache size used for writing Flash efficiently, 32KB by default | ||
| * `USB Device VID`: Espressif VID (0x303A) by default | ||
| * `USB Device PID`: Espressif test PID (0x8000) by default, refer [esp-usb-pid](https://github.com/espressif/usb-pids) to apply new. | ||
| * `USB Disk Name`: The name of the virtual U-disk shows in File Explorer, "ESP32Sx-UF2" by default | ||
| * `USB Device Manufacture`: "Espressif" by default | ||
| * `Product Name`: "ESP TinyUF2" by default | ||
| * `Product ID`: 12345678 by default | ||
| * `Product URL`: A `index` file will be added to the U-disk, users can click to goto the webpage, "https://products.espressif.com/" by default | ||
| * `UF2 NVS ini file size`: The `ini` file size prepares for NVS function | ||
| 4. Install tinyuf2 function like below, for more details, please refer example `usb_uf2_nvs` and `usb_uf2_ota` | ||
| ```c | ||
| /* install UF2 OTA */ | ||
| tinyuf2_ota_config_t ota_config = DEFAULT_TINYUF2_OTA_CONFIG(); | ||
| ota_config.complete_cb = uf2_update_complete_cb; | ||
| /* disable auto restart, if false manual restart later */ | ||
| ota_config.if_restart = false; | ||
| /* install UF2 NVS */ | ||
| tinyuf2_nvs_config_t nvs_config = DEFAULT_TINYUF2_NVS_CONFIG(); | ||
| nvs_config.part_name = "nvs"; | ||
| nvs_config.namespace_name = "myuf2"; | ||
| nvs_config.modified_cb = uf2_nvs_modified_cb; | ||
| esp_tinyuf2_install(&ota_config, &nvs_config); | ||
| ``` | ||
| 5. Run `idf.py build flash` for the initial download, later `idf.py uf2-ota` can be used to generate new `uf2` app bin | ||
| 6. Drag and drop UF2 format file to the disk, to upgrade to new `uf2` app bin | ||
|  | ||
| ## Enable UF2 USB Console | ||
| If enable UF2 USB console `(Top) → Component config → TinyUF2 Config → Enable USB Console For log`, the log will be output to the USB Serial port (Output to UART by default). | ||
| ## Build APP to UF2 format | ||
| The new command `idf.py uf2-ota` is added by this component, which can be used to build the APP to UF2 format. After the build is complete, the UF2 file (`${PROJECT_NAME}.uf2`) will be generated in the current `project` directory. | ||
| ```sh | ||
| idf.py uf2-ota | ||
| ``` | ||
| ## Convert Existing APP to UF2 Format | ||
| To convert your existing APP binary to UF2 format, simply use the [uf2conv.py](./utils/uf2conv.py) on a `.bin` file, specifying the family id as `ESP32S2`, `ESP32S3` or their magic number as follows. And you must specify the address of 0x00 with the `-b` switch, the tinyuf2 will use it as offset to write to the OTA partition. | ||
| 1. convert as follows | ||
| using: | ||
| ```sh | ||
| $ENV{UF2_UTILS_PATH}/uf2conv.py your_firmware.bin -c -b 0x00 -f ESP32S3 | ||
| ``` | ||
| or: | ||
| ```sh | ||
| $ENV{UF2_UTILS_PATH}/uf2conv.py your_firmware.bin -c -b 0x00 -f 0xc47e5767 | ||
| ``` | ||
| ## Note | ||
| * To use the UF2 OTA function continuously, the TinyUF2 function must be enabled in the updated APP. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| ESP TinyUF2 | ||
| ============ | ||
|
|
||
| :link_to_translation:`zh_CN:[中文]` | ||
|
|
||
| ``esp_tinyuf2`` is an enhanced version of `TinyUF2 <https://github.com/adafruit/tinyuf2>`__ for ESP chips with USB support. Which features: | ||
|
|
||
| - support over-the-air (OTA) updates through the virtual USB drive | ||
| - support dumping NVS key-value pairs to ini file in the virtual USB drive | ||
| - support modify ini file and write back to NVS | ||
|
|
||
| UF2 is a file format developed by Microsoft for `PXT <https://github.com/Microsoft/pxt>`__, that is particularly suitable for flashing microcontrollers over MSC (Mass Storage Class). For a more friendly explanation, check out `the blog post <https://makecode.com/blog/one-chip-to-flash-them-all>`__. | ||
|
|
||
| Support UF2 OTA/NVS in Your Project | ||
| ----------------------------------- | ||
|
|
||
| 1. Add the component to your project using ``idf.py add_dependency`` command. | ||
|
|
||
| .. code:: sh | ||
| idf.py add-dependency "esp_tinyuf2" | ||
| 2. Customer your partition table. Like other OTA solutions, you need to reserve at least two OTA app partitions. Please refer to `Partition Tables <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html>`__ and `usb_uf2_ota <https://github.com/espressif/esp-iot-solution/tree/master/examples/usb/device/usb_uf2_ota>`__ example for details. | ||
|
|
||
| :: | ||
|
|
||
| # Partition Table Example | ||
| # Name, Type, SubType, Offset, Size, Flags | ||
| nvs, data, nvs, , 0x4000, | ||
| otadata, data, ota, , 0x2000, | ||
| phy_init, data, phy, , 0x1000, | ||
| ota_0, app, ota_0, , 1500K, | ||
| ota_1, app, ota_1, , 1500K, | ||
|
|
||
| 3. Using ``idf.py menuconfig`` to config the component’s behavior in ``(Top) → Component config → TinyUF2 Config`` | ||
|
|
||
| - ``USB Virtual Disk size(MB)``: The size of the virtual U-disk shows in File Explorer, 8MB by default | ||
| - ``Max APP size(MB)``: Maximum APP size, 4MB by default | ||
| - ``Flash cache size(KB)``: Cache size used for writing Flash efficiently, 32KB by default | ||
| - ``USB Device VID``: Espressif VID (0x303A) by default | ||
| - ``USB Device PID``: Espressif test PID (0x8000) by default, refer `esp-usb-pid <https://github.com/espressif/usb-pids>`__ to apply new. | ||
| - ``USB Disk Name``: The name of the virtual U-disk shows in File Explorer, ``ESP32Sx-UF2`` by default | ||
| - ``USB Device Manufacture``: ``Espressif`` by default | ||
| - ``Product Name``: ``ESP TinyUF2`` by default | ||
| - ``Product ID``: ``12345678`` by default | ||
| - ``Product URL``: A ``index`` file will be added to the U-disk, users can click to goto the webpage, ``https://products.espressif.com/`` by default | ||
| - ``UF2 NVS ini file size``: The ``ini`` file size prepares for NVS function | ||
|
|
||
| 4. Install tinyuf2 function like below, for more details, please refer example `usb_uf2_nvs <https://github.com/espressif/esp-iot-solution/tree/master/examples/usb/device/usb_uf2_nvs>`__ and `usb_uf2_ota <https://github.com/espressif/esp-iot-solution/tree/master/examples/usb/device/usb_uf2_ota>`__ | ||
|
|
||
| .. code:: c | ||
| /* install UF2 OTA */ | ||
| tinyuf2_ota_config_t ota_config = DEFAULT_TINYUF2_OTA_CONFIG(); | ||
| ota_config.complete_cb = uf2_update_complete_cb; | ||
| /* disable auto restart, if false manual restart later */ | ||
| ota_config.if_restart = false; | ||
| /* install UF2 NVS */ | ||
| tinyuf2_nvs_config_t nvs_config = DEFAULT_TINYUF2_NVS_CONFIG(); | ||
| nvs_config.part_name = "nvs"; | ||
| nvs_config.namespace_name = "myuf2"; | ||
| nvs_config.modified_cb = uf2_nvs_modified_cb; | ||
| esp_tinyuf2_install(&ota_config, &nvs_config); | ||
| 5. Run ``idf.py build flash`` for the initial download, later ``idf.py uf2-ota`` can be used to generate new ``uf2`` app bin | ||
|
|
||
| 6. Drag and drop UF2 format file to the disk, to upgrade to new ``uf2`` app bin | ||
|
|
||
| .. figure:: ../../../_static/usb/uf2_disk.png | ||
| :alt: UF2 Disk | ||
|
|
||
| Enable UF2 USB Console | ||
| ----------------------- | ||
|
|
||
| Through menuconfig ``(Top) → Component config → TinyUF2 Config → Enable USB Console For log``, the log will be output to the USB Serial port (Output to UART by default). | ||
|
|
||
| Build APP to UF2 format | ||
| ----------------------- | ||
|
|
||
| The new command ``idf.py uf2-ota`` is added by this component, which can be used to build the APP to UF2 format. After the build is complete, the UF2 file (``${PROJECT_NAME}.uf2``) will be generated in the current ``project`` directory. | ||
|
|
||
| .. code:: sh | ||
| idf.py uf2-ota | ||
| Convert Existing APP to UF2 Format | ||
| ---------------------------------- | ||
|
|
||
| To convert your existing APP binary to UF2 format, simply use the `uf2conv.py <https://github.com/espressif/esp-iot-solution/blob/master/components/usb/esp_tinyuf2/utils/uf2conv.py>`__ on a ``.bin`` file, specifying the family id as ``ESP32S2``, ``ESP32S3`` or their magic number as follows. And you must specify the address of 0x00 with the ``-b`` switch, the tinyuf2 will use it as offset to write to the OTA partition. | ||
|
|
||
| 1. convert as follows | ||
|
|
||
| using: | ||
|
|
||
| .. code:: sh | ||
| uf2conv.py your_firmware.bin -c -b 0x00 -f ESP32S3 | ||
| or: | ||
|
|
||
| .. code:: sh | ||
| uf2conv.py your_firmware.bin -c -b 0x00 -f 0xc47e5767 | ||
| Note | ||
| ---- | ||
|
|
||
| - To use the UF2 OTA function continuously, the TinyUF2 function must be enabled in the updated APP. | ||
|
|
||
| API Reference | ||
| ------------- | ||
|
|
||
| .. include-build-file:: inc/esp_tinyuf2.inc |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.