|
1 | 1 | ## ESP TinyUF2 |
2 | 2 |
|
3 | | -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**. |
| 3 | +`esp_tinyuf2` is an enhanced version of [TinyUF2](https://github.com/adafruit/tinyuf2) for ESP chips with USB-OTG support. Which features: |
4 | 4 |
|
5 | | -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). |
| 5 | +- support over-the-air (OTA) updates through the virtual USB drive |
| 6 | +- support dumping NVS key-value pairs to ini file in the virtual USB drive |
| 7 | +- support modify ini file and write back to NVS |
6 | 8 |
|
7 | | -## Support UF2 OTA/NVS in Your Project |
| 9 | + |
8 | 10 |
|
9 | | -1. Add the component to your project using `idf.py add_dependency` command. |
10 | 11 |
|
11 | | - ```sh |
12 | | - idf.py add-dependency "esp_tinyuf2" |
13 | | - ``` |
| 12 | +### How to use |
14 | 13 |
|
15 | | -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. |
| 14 | +[esp_tinyuf2 user guide]() |
16 | 15 |
|
17 | | - ``` |
18 | | - # Partition Table Example |
19 | | - # Name, Type, SubType, Offset, Size, Flags |
20 | | - nvs, data, nvs, , 0x4000, |
21 | | - otadata, data, ota, , 0x2000, |
22 | | - phy_init, data, phy, , 0x1000, |
23 | | - ota_0, app, ota_0, , 1500K, |
24 | | - ota_1, app, ota_1, , 1500K, |
25 | | - ``` |
26 | | - |
27 | | -3. Using `idf.py menuconfig` to config the component's behavior in `(Top) → Component config → TinyUF2 Config` |
28 | | -
|
29 | | -* `USB Virtual Disk size(MB)`: The size of the virtual U-disk shows in File Explorer, 8MB by default |
30 | | -* `Max APP size(MB)`: Maximum APP size, 4MB by default |
31 | | -* `Flash cache size(KB)`: Cache size used for writing Flash efficiently, 32KB by default |
32 | | -* `USB Device VID`: Espressif VID (0x303A) by default |
33 | | -* `USB Device PID`: Espressif test PID (0x8000) by default, refer [esp-usb-pid](https://github.com/espressif/usb-pids) to apply new. |
34 | | -* `USB Disk Name`: The name of the virtual U-disk shows in File Explorer, "ESP32Sx-UF2" by default |
35 | | -* `USB Device Manufacture`: "Espressif" by default |
36 | | -* `Product Name`: "ESP TinyUF2" by default |
37 | | -* `Product ID`: 12345678 by default |
38 | | -* `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 |
39 | | -* `UF2 NVS ini file size`: The `ini` file size prepares for NVS function |
40 | | -
|
41 | | -4. Install tinyuf2 function like below, for more details, please refer example `usb_uf2_nvs` and `usb_uf2_ota` |
42 | | -
|
43 | | - ```c |
44 | | - /* install UF2 OTA */ |
45 | | - tinyuf2_ota_config_t ota_config = DEFAULT_TINYUF2_OTA_CONFIG(); |
46 | | - ota_config.complete_cb = uf2_update_complete_cb; |
47 | | - /* disable auto restart, if false manual restart later */ |
48 | | - ota_config.if_restart = false; |
49 | | - /* install UF2 NVS */ |
50 | | - tinyuf2_nvs_config_t nvs_config = DEFAULT_TINYUF2_NVS_CONFIG(); |
51 | | - nvs_config.part_name = "nvs"; |
52 | | - nvs_config.namespace_name = "myuf2"; |
53 | | - nvs_config.modified_cb = uf2_nvs_modified_cb; |
54 | | - esp_tinyuf2_install(&ota_config, &nvs_config); |
55 | | - ``` |
56 | | -
|
57 | | -5. Run `idf.py build flash` for the initial download, later `idf.py uf2-ota` can be used to generate new `uf2` app bin |
58 | | -
|
59 | | -6. Drag and drop UF2 format file to the disk, to upgrade to new `uf2` app bin |
60 | | -
|
61 | | - |
62 | | -
|
63 | | -## Enable UF2 USB Console |
64 | | -
|
65 | | -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). |
66 | | -
|
67 | | -
|
68 | | -## Build APP to UF2 format |
69 | | -
|
70 | | -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. |
71 | | -
|
72 | | -```sh |
73 | | -idf.py uf2-ota |
74 | | -``` |
75 | | -
|
76 | | -## Convert Existing APP to UF2 Format |
77 | | -
|
78 | | -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. |
79 | | -
|
80 | | -1. convert as follows |
81 | | -
|
82 | | - using: |
83 | | -
|
84 | | - ```sh |
85 | | - $ENV{UF2_UTILS_PATH}/uf2conv.py your_firmware.bin -c -b 0x00 -f ESP32S3 |
86 | | - ``` |
87 | | -
|
88 | | - or: |
89 | | -
|
90 | | - ```sh |
91 | | - $ENV{UF2_UTILS_PATH}/uf2conv.py your_firmware.bin -c -b 0x00 -f 0xc47e5767 |
92 | | - ``` |
93 | | -
|
94 | | -## Note |
95 | | -
|
96 | | -* To use the UF2 OTA function continuously, the TinyUF2 function must be enabled in the updated APP. |
0 commit comments