From a47fb4019cd068eb8a2a3a69737be7663121e7f2 Mon Sep 17 00:00:00 2001 From: Li Bo Date: Thu, 19 Sep 2024 19:11:00 +0800 Subject: [PATCH 1/2] docs(esp_tinyuf2): add api reference --- .gitlab/ci/rules.yml | 21 ++-- components/usb/esp_tinyuf2/README.md | 95 ++------------- components/usb/esp_tinyuf2/esp_tinyuf2.h | 24 ++-- components/usb/esp_tinyuf2/idf_component.yml | 3 +- docs/Doxyfile | 5 +- docs/_static/usb/uf2_disk.png | Bin 0 -> 4011 bytes docs/en/usb/usb_device/esp_tinyuf2.rst | 113 ++++++++++++++++++ docs/en/usb/usb_device/usb_driver_index.rst | 3 +- docs/zh_CN/usb/usb_device/esp_tinyuf2.rst | 113 ++++++++++++++++++ .../zh_CN/usb/usb_device/usb_driver_index.rst | 3 +- .../device/usb_uf2_nvs/main/idf_component.yml | 2 +- .../device/usb_uf2_ota/main/idf_component.yml | 2 +- 12 files changed, 269 insertions(+), 115 deletions(-) create mode 100644 docs/_static/usb/uf2_disk.png create mode 100644 docs/en/usb/usb_device/esp_tinyuf2.rst create mode 100644 docs/zh_CN/usb/usb_device/esp_tinyuf2.rst diff --git a/.gitlab/ci/rules.yml b/.gitlab/ci/rules.yml index 9b12fbe80..243a458fb 100644 --- a/.gitlab/ci/rules.yml +++ b/.gitlab/ci/rules.yml @@ -308,10 +308,18 @@ - "**/*.md" .patterns-docs_inc: &patterns-docs_inc + - "components/audio/dac_audio/include/dac_audio.h" - "components/audio/pwm_audio/include/pwm_audio.h" - "components/bluetooth/ble_conn_mgr/include/esp_ble_conn_mgr.h" + - "components/bluetooth/ble_conn_mgr/include/esp_ble_conn_mgr.h" - "components/bluetooth/ble_hci/include/ble_hci.h" + - "components/bluetooth/ble_services/ans/include/esp_ans.h" + - "components/bluetooth/ble_services/bas/include/esp_bas.h" + - "components/bluetooth/ble_services/dis/include/esp_dis.h" + - "components/bluetooth/ble_services/hrs/include/esp_hrs.h" + - "components/bluetooth/ble_services/hts/include/esp_hts.h" + - "components/bluetooth/ble_services/tps/include/esp_tps.h" - "components/bus/include/spi_bus.h" - "components/button/include/iot_button.h" - "components/display/screen/interface_driver/scr_interface_driver.h" @@ -329,28 +337,21 @@ - "components/motor/esp_sensorless_bldc_control/user_cfg/bldc_user_cfg.h" - "components/motor/servo/include/iot_servo.h" - "components/openai/include/OpenAI.h" + - "components/sensors/ntc_driver/include/ntc_driver.h" + - "components/sensors/power_monitor/ina236/include/ina236.h" - "components/sensors/sensor_hub/include/hal/humiture_hal.h" - "components/sensors/sensor_hub/include/hal/imu_hal.h" - "components/sensors/sensor_hub/include/hal/light_sensor_hal.h" - "components/sensors/sensor_hub/include/iot_sensor_hub.h" - "components/sensors/sensor_hub/include/sensor_type.h" - - "components/sensors/ntc_driver/include/ntc_driver.h" - - "components/sensors/power_monitor/ina236/include/ina236.h" - "components/touch/touch_proximity_sensor/include/touch_proximity_sensor.h" - "components/usb/esp_msc_ota/include/esp_msc_ota.h" + - "components/usb/esp_tinyuf2/esp_tinyuf2.h" - "components/usb/iot_usbh_cdc/include/iot_usbh_cdc.h" - "components/usb/usb_device_uac/include/usb_device_uac.h" - "components/usb/usb_device_uvc/include/usb_device_uvc.h" - "components/usb/usb_stream/include/usb_stream.h" - "components/zero_detection/include/zero_detection.h" - - "components/bluetooth/ble_conn_mgr/include/esp_ble_conn_mgr.h" - - "components/bluetooth/ble_services/ans/include/esp_ans.h" - - "components/bluetooth/ble_services/bas/include/esp_bas.h" - - "components/bluetooth/ble_services/dis/include/esp_dis.h" - - "components/bluetooth/ble_services/hrs/include/esp_hrs.h" - - "components/bluetooth/ble_services/hts/include/esp_hts.h" - - "components/bluetooth/ble_services/tps/include/esp_tps.h" - # examples folder, in the alphabetic order .patterns-example_audio_wav_player: &patterns-example_audio_wav_player - "examples/audio/**/*" diff --git a/components/usb/esp_tinyuf2/README.md b/components/usb/esp_tinyuf2/README.md index 28e733941..8c5910723 100644 --- a/components/usb/esp_tinyuf2/README.md +++ b/components/usb/esp_tinyuf2/README.md @@ -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 +![](./uf2_disk.png) -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]() - ``` - # 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 - -![UF2 Disk](./uf2_disk.png) - -## 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. \ No newline at end of file diff --git a/components/usb/esp_tinyuf2/esp_tinyuf2.h b/components/usb/esp_tinyuf2/esp_tinyuf2.h index be7d73d8e..b9b65bd9b 100644 --- a/components/usb/esp_tinyuf2/esp_tinyuf2.h +++ b/components/usb/esp_tinyuf2/esp_tinyuf2.h @@ -41,10 +41,10 @@ typedef void (*nvs_modified_cb_t)(void); * */ typedef struct { - esp_partition_subtype_t subtype; /*! Partition subtype. if ESP_PARTITION_SUBTYPE_ANY will use the next_update_partition by default. */ - const char *label; /*! Partition label. Set this value if looking for partition with a specific name. if subtype==ESP_PARTITION_SUBTYPE_ANY, label default to NULL.*/ - bool if_restart; /*! if restart system to new app partition after UF2 flashing done */ - update_complete_cb_t complete_cb; /*! user callback called after uf2 update complete */ + esp_partition_subtype_t subtype; /*!< Partition subtype. if ESP_PARTITION_SUBTYPE_ANY will use the next_update_partition by default. */ + const char *label; /*!< Partition label. Set this value if looking for partition with a specific name. if subtype==ESP_PARTITION_SUBTYPE_ANY, label default to NULL.*/ + bool if_restart; /*!< if restart system to new app partition after UF2 flashing done */ + update_complete_cb_t complete_cb; /*!< user callback called after uf2 update complete */ } tinyuf2_ota_config_t; /** @@ -52,15 +52,18 @@ typedef struct { * */ typedef struct { - const char *part_name; /*! Partition name. */ - const char *namespace_name; /*! Namespace name. */ - nvs_modified_cb_t modified_cb; /*! user callback called after uf2 update complete */ + const char *part_name; /*!< Partition name. */ + const char *namespace_name; /*!< Namespace name. */ + nvs_modified_cb_t modified_cb; /*!< user callback called after uf2 update complete */ } tinyuf2_nvs_config_t; +/** + * @brief tinyuf2 current state + */ typedef enum { - TINYUF2_STATE_NOT_INSTALLED = 0, - TINYUF2_STATE_INSTALLED, - TINYUF2_STATE_MOUNTED, + TINYUF2_STATE_NOT_INSTALLED = 0, /*!< tinyuf2 driver not installed */ + TINYUF2_STATE_INSTALLED, /*!< tinyuf2 driver installed */ + TINYUF2_STATE_MOUNTED, /*!< USB mounted */ } tinyuf2_state_t; /** @@ -81,6 +84,7 @@ esp_err_t esp_tinyuf2_install(tinyuf2_ota_config_t *ota_config, tinyuf2_nvs_conf * @note not release memory due to tinyusb not support teardown * * @return esp_err_t + * - ESP_ERR_INVALID_STATE tinyuf2 not installed * - ESP_OK Success */ esp_err_t esp_tinyuf2_uninstall(void); diff --git a/components/usb/esp_tinyuf2/idf_component.yml b/components/usb/esp_tinyuf2/idf_component.yml index cf8676c44..d41f6a5a0 100644 --- a/components/usb/esp_tinyuf2/idf_component.yml +++ b/components/usb/esp_tinyuf2/idf_component.yml @@ -1,4 +1,4 @@ -version: "0.2.2" +version: "1.0.0" targets: - esp32s2 - esp32s3 @@ -6,6 +6,7 @@ targets: description: Enhanced TinyUF2 for ESP32Sx, support OTA update and NVS operate through USB MSC url: https://github.com/espressif/esp-iot-solution repository: https://github.com/espressif/esp-iot-solution.git +documentation: https://docs.espressif.com/projects/esp-iot-solution/en/latest/usb/usb_device/esp_tinyuf2.html issues: https://github.com/espressif/esp-iot-solution/issues dependencies: diff --git a/docs/Doxyfile b/docs/Doxyfile index bdd4837da..2d05d0980 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -52,15 +52,16 @@ INPUT = \ $(PROJECT_PATH)/components/motor/esp_sensorless_bldc_control/user_cfg/bldc_user_cfg.h \ $(PROJECT_PATH)/components/motor/servo/include/iot_servo.h \ $(PROJECT_PATH)/components/openai/include/OpenAI.h \ + $(PROJECT_PATH)/components/sensors/ntc_driver/include/ntc_driver.h \ + $(PROJECT_PATH)/components/sensors/power_monitor/ina236/include/ina236.h \ $(PROJECT_PATH)/components/sensors/sensor_hub/include/hal/humiture_hal.h \ $(PROJECT_PATH)/components/sensors/sensor_hub/include/hal/imu_hal.h \ $(PROJECT_PATH)/components/sensors/sensor_hub/include/hal/light_sensor_hal.h \ $(PROJECT_PATH)/components/sensors/sensor_hub/include/iot_sensor_hub.h \ $(PROJECT_PATH)/components/sensors/sensor_hub/include/sensor_type.h \ - $(PROJECT_PATH)/components/sensors/ntc_driver/include/ntc_driver.h \ - $(PROJECT_PATH)/components/sensors/power_monitor/ina236/include/ina236.h \ $(PROJECT_PATH)/components/touch/touch_proximity_sensor/include/touch_proximity_sensor.h \ $(PROJECT_PATH)/components/usb/esp_msc_ota/include/esp_msc_ota.h \ + $(PROJECT_PATH)/components/usb/esp_tinyuf2/esp_tinyuf2.h \ $(PROJECT_PATH)/components/usb/iot_usbh_cdc/include/iot_usbh_cdc.h \ $(PROJECT_PATH)/components/usb/usb_device_uac/include/usb_device_uac.h \ $(PROJECT_PATH)/components/usb/usb_device_uvc/include/usb_device_uvc.h \ diff --git a/docs/_static/usb/uf2_disk.png b/docs/_static/usb/uf2_disk.png new file mode 100644 index 0000000000000000000000000000000000000000..1c34a2db3dcfe6f9e634a822da3025020ecd2c95 GIT binary patch literal 4011 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 UC$MN^lF$ZdsXu#M3AG9T7l~iAa{vGU literal 0 HcmV?d00001 diff --git a/docs/en/usb/usb_device/esp_tinyuf2.rst b/docs/en/usb/usb_device/esp_tinyuf2.rst new file mode 100644 index 000000000..dc168ba60 --- /dev/null +++ b/docs/en/usb/usb_device/esp_tinyuf2.rst @@ -0,0 +1,113 @@ +ESP TinyUF2 +============ + +:link_to_translation:`zh_CN:[中文]` + +``esp_tinyuf2`` is an enhanced version of `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 `__, that is particularly suitable for flashing microcontrollers over MSC (Mass Storage Class). For a more friendly explanation, check out `the blog post `__. + +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 `__ and `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 `__ 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 `__ + + .. 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 `__ 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 diff --git a/docs/en/usb/usb_device/usb_driver_index.rst b/docs/en/usb/usb_device/usb_driver_index.rst index 5dbcc5c9f..b5076d17f 100644 --- a/docs/en/usb/usb_device/usb_driver_index.rst +++ b/docs/en/usb/usb_device/usb_driver_index.rst @@ -7,4 +7,5 @@ USB Device Drivers :maxdepth: 1 USB UVC Device - USB UAC Device \ No newline at end of file + USB UAC Device + USB UF2 Device \ No newline at end of file diff --git a/docs/zh_CN/usb/usb_device/esp_tinyuf2.rst b/docs/zh_CN/usb/usb_device/esp_tinyuf2.rst new file mode 100644 index 000000000..5aa4d752d --- /dev/null +++ b/docs/zh_CN/usb/usb_device/esp_tinyuf2.rst @@ -0,0 +1,113 @@ +ESP TinyUF2 +============ + +:link_to_translation:`en:[English]` + +``esp_tinyuf2`` 是一个扩展功能的 `TinyUF2 `__，针对支持 USB-OTG 功能 ESP 芯片开发。支持以下功能: + +- 支持通过虚拟 USB 驱动器（U 盘）进行 OTA 升级 +- 支持将 NVS 键值输出到虚拟 USB 驱动器中的 ini 文件 +- 支持通过修改 ini 文件修改 NVS + +UF2 是 Microsoft 开发的文件格式 `PXT `__, 特别适合通过 MSC（存储类）烧录微控制器。 有关更友好的解释，请查看 `博客 `__. + +在您的项目中支持 UF2 OTA/NVS +----------------------------------- + +1. 使用 ``idf.py add_dependency`` 命令将组件添加到项目中. + + .. code:: sh + + idf.py add-dependency "esp_tinyuf2" + +2. 定义您的分区表。 像其他 OTA 解决方案一样，您需要至少保留两个 OTA 应用程序分区. 请参考 `Partition Tables `__ 和示例 `usb_uf2_ota `__. + + :: + + # 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. 使用 ``idf.py menuconfig`` 配置组件 ``(Top) → Component config → TinyUF2 Config`` + +- ``USB Virtual Disk size(MB)``: 虚拟 USB 驱动器在文件资源管理器中显示的大小，默认情况下为 8MB +- ``Max APP size(MB)``: 最大应用大小，默认情况下 4MB +- ``Flash cache size(KB)``: 缓存大小，用于缓存即将烧录的 bin 片段，默认情况下为 32KB +- ``USB Device VID``: Espressif VID (默认 0x303A) +- ``USB Device PID``: Espressif test PID (默认 0x8000), 如需申请 PID 请参考 `esp-usb-pid `__. +- ``USB Disk Name``: 虚拟 USB 驱动器在文件资源管理器中显示的名称, ``ESP32Sx-UF2`` 默认 +- ``USB Device Manufacture``: 制造商 ``Espressif`` 默认 +- ``Product Name``: 产品名称 ``ESP TinyUF2`` 默认 +- ``Product ID``: 产品 ID ``12345678`` 默认 +- ``Product URL``: ``index`` 文件将被添加到 U 盘, 用户可以单击进入网页, ``https://products.espressif.com/`` 默认 +- ``UF2 NVS ini file size``: ``ini`` 文件大小，用于保存 NVS 键值对 + +4. 如下所示，安装 ``tinyuf2`` 功能，有关更多详细信息，请参阅示例 `usb_uf2_nvs `__ 和 `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. 运行 ``idf.py build flash`` 进行初始下载, 之后可以使用 ``idf.py uf2-ota`` 生成新的 ``uf2`` app bin + +6. 将 UF2 格式 app bin 拖放到磁盘, 升级将自动进行 + +.. figure:: ../../../_static/usb/uf2_disk.png + :alt: UF2 Disk + +使用 UF2 USB Console +----------------------- + +通过 menuconfig ``(Top) → Component config → TinyUF2 Config → Enable USB Console For log``, 该日志将输出到 USB 串行端口（默认向 UART 输出）. + +编译 APP 为 UF2 格式 +----------------------- + +该组件添加了新的命令 ``idf.py uf2-ota``, 可以用于将 app 编译为 UF2 格式. 编译完成后, 新的 UF2 文件 (``${PROJECT_NAME}.uf2``) 将被产生到 ``project`` 文件夹. + +.. code:: sh + + idf.py uf2-ota + +将现有 bin 转换为 UF2 格式 +---------------------------------- + +将您现有的应用 bin 转换为UF2格式, 可以使用 `uf2conv.py `__, 您需要指定 family id 为 ``ESP32S2``, ``ESP32S3`` 或如下的 magic number. 并且还需使用 ``-b`` 指定地址, tinyuf2 将使用它作为偏移来写入 OTA 分区. + +1. 转换指令 + + 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 + +注意 +----- + +- 要连续使用 UF2 OTA 功能，必须在更新的应用中同样启用 tinyuf2. + +API 参考 +------------- + +.. include-build-file:: inc/esp_tinyuf2.inc diff --git a/docs/zh_CN/usb/usb_device/usb_driver_index.rst b/docs/zh_CN/usb/usb_device/usb_driver_index.rst index 6ad0f8910..4a575be3e 100644 --- a/docs/zh_CN/usb/usb_device/usb_driver_index.rst +++ b/docs/zh_CN/usb/usb_device/usb_driver_index.rst @@ -7,4 +7,5 @@ USB 设备驱动 :maxdepth: 1 USB UVC 视频设备 - USB UAC 音频设备 \ No newline at end of file + USB UAC 音频设备 + USB UF2 设备 \ No newline at end of file diff --git a/examples/usb/device/usb_uf2_nvs/main/idf_component.yml b/examples/usb/device/usb_uf2_nvs/main/idf_component.yml index 7319dd657..a3979c40b 100644 --- a/examples/usb/device/usb_uf2_nvs/main/idf_component.yml +++ b/examples/usb/device/usb_uf2_nvs/main/idf_component.yml @@ -1,7 +1,7 @@ dependencies: idf: ">=4.4" esp_tinyuf2: - version: "0.*" + version: "*" override_path: "../../../../../components/usb/esp_tinyuf2" espressif/esp32_s3_usb_otg: version: "^1.5.1" diff --git a/examples/usb/device/usb_uf2_ota/main/idf_component.yml b/examples/usb/device/usb_uf2_ota/main/idf_component.yml index 7319dd657..a3979c40b 100644 --- a/examples/usb/device/usb_uf2_ota/main/idf_component.yml +++ b/examples/usb/device/usb_uf2_ota/main/idf_component.yml @@ -1,7 +1,7 @@ dependencies: idf: ">=4.4" esp_tinyuf2: - version: "0.*" + version: "*" override_path: "../../../../../components/usb/esp_tinyuf2" espressif/esp32_s3_usb_otg: version: "^1.5.1" From 23bdc16d9757775f988ab30c4fc324314f4b0934 Mon Sep 17 00:00:00 2001 From: Li Bo Date: Mon, 14 Oct 2024 17:48:07 +0800 Subject: [PATCH 2/2] fix(usb_webcam): fix build error with latest component manager --- components/usb/esp_tinyuf2/README.md | 2 +- examples/usb/device/usb_webcam/CMakeLists.txt | 15 +++++++-------- .../usb/device/usb_webcam/main/idf_component.yml | 6 +++--- 3 files changed, 11 insertions(+), 12 deletions(-) diff --git a/components/usb/esp_tinyuf2/README.md b/components/usb/esp_tinyuf2/README.md index 8c5910723..1c27a0e76 100644 --- a/components/usb/esp_tinyuf2/README.md +++ b/components/usb/esp_tinyuf2/README.md @@ -11,5 +11,5 @@ ### How to use -[esp_tinyuf2 user guide]() +[esp_tinyuf2 user guide](https://docs.espressif.com/projects/esp-iot-solution/en/latest/usb/usb_device/esp_tinyuf2.html) diff --git a/examples/usb/device/usb_webcam/CMakeLists.txt b/examples/usb/device/usb_webcam/CMakeLists.txt index 90088c7f6..d77c2ed3f 100644 --- a/examples/usb/device/usb_webcam/CMakeLists.txt +++ b/examples/usb/device/usb_webcam/CMakeLists.txt @@ -6,20 +6,19 @@ include($ENV{IDF_PATH}/tools/cmake/project.cmake) if("$ENV{IDF_TARGET}" STREQUAL "esp32s3") if(EXISTS ${CMAKE_CURRENT_LIST_DIR}/sdkconfig) file(READ ${CMAKE_CURRENT_LIST_DIR}/sdkconfig SDKCONFIG_RULE) - string(REGEX MATCH "CONFIG_CAMERA_MODULE_ESP_S3_EYE=y" ENABLE_EYES_SHOW "${SDKCONFIG_RULE}") + string(REGEX MATCH "CONFIG_CAMERA_MODULE_ESP_S3_EYE=y" ENABLE_ESP_S3_EYE "${SDKCONFIG_RULE}") else() message(STATUS "sdkconfig not exist") file(READ ${CMAKE_CURRENT_LIST_DIR}/main/Kconfig.projbuild SDKCONFIG_RULE) - string(REGEX MATCH "default CAMERA_MODULE_ESP_S3_EYE" ENABLE_EYES_SHOW "${SDKCONFIG_RULE}") + string(REGEX MATCH "default CAMERA_MODULE_ESP_S3_EYE" ENABLE_ESP_S3_EYE "${SDKCONFIG_RULE}") endif() endif() -if (ENABLE_EYES_SHOW) - set(ENV{EYES_SHOW_TARGET} "esp32s3") - message("EYES_SHOW_TARGET is set to esp32s3") - else() - set(ENV{EYES_SHOW_TARGET} "none") - message("EYES_SHOW_TARGET is set to none") +if (ENABLE_ESP_S3_EYE) + set(ENV{USB_WEBCAM_BOARD} "esp32_s3_eye") +else() + set(ENV{USB_WEBCAM_BOARD} "general") endif() +message("USB_WEBCAM_BOARD is set to $ENV{USB_WEBCAM_BOARD}") project(usb_webcam) diff --git a/examples/usb/device/usb_webcam/main/idf_component.yml b/examples/usb/device/usb_webcam/main/idf_component.yml index aaffda02a..ea14e70d0 100644 --- a/examples/usb/device/usb_webcam/main/idf_component.yml +++ b/examples/usb/device/usb_webcam/main/idf_component.yml @@ -6,14 +6,14 @@ dependencies: idf: version: ">=5.0" esp32-camera: - version: ">=2.0.5" + version: "2.0.10" esp32_s3_eye: version: ^2.0.2 rules: - - if: "target == $EYES_SHOW_TARGET" + - if: "${USB_WEBCAM_BOARD} in [esp32_s3_eye]" eyes_show: rules: - - if: "target == $EYES_SHOW_TARGET" + - if: "${USB_WEBCAM_BOARD} in [esp32_s3_eye]" override_path: "../eyes_show" cmake_utilities: "*" usb_device_uvc: