diff --git a/components/soc/esp32s2/include/soc/soc_caps.h b/components/soc/esp32s2/include/soc/soc_caps.h index 63326b098a..13ef55669e 100644 --- a/components/soc/esp32s2/include/soc/soc_caps.h +++ b/components/soc/esp32s2/include/soc/soc_caps.h @@ -44,7 +44,7 @@ #define SOC_DEDICATED_GPIO_SUPPORTED 1 #define SOC_SUPPORTS_SECURE_DL_MODE 1 #define SOC_RISCV_COPROC_SUPPORTED 1 -#define SOC_USB_SUPPORTED 1 +#define SOC_USB_OTG_SUPPORTED 1 #define SOC_PCNT_SUPPORTED 1 #define SOC_ULP_SUPPORTED 1 #define SOC_RTC_SLOW_MEM_SUPPORTED 1 diff --git a/components/soc/esp32s3/include/soc/soc_caps.h b/components/soc/esp32s3/include/soc/soc_caps.h index a97f63c52a..1242ad4f64 100644 --- a/components/soc/esp32s3/include/soc/soc_caps.h +++ b/components/soc/esp32s3/include/soc/soc_caps.h @@ -15,6 +15,7 @@ #define SOC_CPU_CORES_NUM 2 #define SOC_CACHE_SUPPORT_WRAP 1 #define SOC_ULP_SUPPORTED 1 +#define SOC_USB_OTG_SUPPORTED 1 #define SOC_RTC_SLOW_MEM_SUPPORTED 1 #define SOC_CCOMP_TIMER_SUPPORTED 1 #define SOC_DIG_SIGN_SUPPORTED 0 diff --git a/docs/_static/usb-board-connection.png b/docs/_static/usb-board-connection.png index cdb81eccf3..76bed54cf8 100644 Binary files a/docs/_static/usb-board-connection.png and b/docs/_static/usb-board-connection.png differ diff --git a/docs/conf_common.py b/docs/conf_common.py index 322b3198f2..390b106f95 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -164,7 +164,7 @@ LEGACY_DOCS = ['api-guides/build-system-legacy.rst', 'api-guides/unit-tests-legacy.rst', 'get-started-legacy/**'] -USB_DOCS = ['api-reference/peripherals/usb.rst', +USB_DOCS = ['api-reference/peripherals/usb_device.rst', 'api-guides/usb-otg-console.rst', 'api-guides/dfu.rst'] @@ -212,7 +212,7 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS, 'SOC_SDMMC_HOST_SUPPORTED':SDMMC_DOCS, 'SOC_SDIO_SLAVE_SUPPORTED':SDIO_SLAVE_DOCS, 'SOC_MCPWM_SUPPORTED':MCPWM_DOCS, - 'SOC_USB_SUPPORTED':USB_DOCS, + 'SOC_USB_OTG_SUPPORTED':USB_DOCS, 'SOC_USB_SERIAL_JTAG_SUPPORTED':USB_SERIAL_JTAG_DOCS, 'SOC_DEDICATED_GPIO_SUPPORTED':DEDIC_GPIO_DOCS, 'SOC_SPIRAM_SUPPORTED':SPIRAM_DOCS, diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index b2b750bfbb..22ce505dbd 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -12,7 +12,7 @@ API Guides Build System :esp32: Build System (Legacy GNU Make) Deep Sleep Wake Stubs - :SOC_USB_SUPPORTED: Device Firmware Upgrade through USB + :SOC_USB_OTG_SUPPORTED: Device Firmware Upgrade through USB Error Handling :SOC_BT_SUPPORTED: ESP-BLE-MESH ESP-WIFI-MESH @@ -41,6 +41,6 @@ API Guides Unit Testing (Target) Unit Testing (Linux Host) :esp32: Unit Testing (Legacy GNU Make) - :SOC_USB_SUPPORTED: USB OTG Console + :SOC_USB_OTG_SUPPORTED: USB OTG Console :SOC_USB_SERIAL_JTAG_SUPPORTED: USB Serial/JTAG Controller Console WiFi Driver diff --git a/docs/en/api-guides/performance/speed.rst b/docs/en/api-guides/performance/speed.rst index 87693a9f4e..b97132d11c 100644 --- a/docs/en/api-guides/performance/speed.rst +++ b/docs/en/api-guides/performance/speed.rst @@ -91,8 +91,8 @@ Although standard output is buffered, it's possible for an application to be lim .. list:: - Reduce the volume of log output by lowering the app :ref:`CONFIG_LOG_DEFAULT_LEVEL` (the equivalent bootloader setting is :ref:`CONFIG_BOOTLOADER_LOG_LEVEL`). This also reduces the binary size, and saves some CPU time spent on string formatting. - :not SOC_USB_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE` - :SOC_USB_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`. (Unless using internal USB-CDC for serial console, in which case the serial throughput doesn't depend on the configured baud rate.) + :not SOC_USB_OTG_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE` + :SOC_USB_OTG_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`. (Unless using internal USB-CDC for serial console, in which case the serial throughput doesn't depend on the configured baud rate.) Not Recommended ^^^^^^^^^^^^^^^ diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index 889d273945..d52fbd8e7f 100644 --- a/docs/en/api-reference/peripherals/index.rst +++ b/docs/en/api-reference/peripherals/index.rst @@ -33,6 +33,6 @@ Peripherals API :esp32s2: Touch Element TWAI UART - :SOC_USB_SUPPORTED: USB + :SOC_USB_OTG_SUPPORTED: USB Device Code examples for this API section are provided in the :example:`peripherals` directory of ESP-IDF examples. \ No newline at end of file diff --git a/docs/en/api-reference/peripherals/usb.rst b/docs/en/api-reference/peripherals/usb_device.rst similarity index 94% rename from docs/en/api-reference/peripherals/usb.rst rename to docs/en/api-reference/peripherals/usb_device.rst index 72bda70c93..6e3d1c1c91 100644 --- a/docs/en/api-reference/peripherals/usb.rst +++ b/docs/en/api-reference/peripherals/usb_device.rst @@ -1,6 +1,9 @@ -USB Driver -========== +USB Device Driver +================= + +{IDF_TARGET_USB_DP_GPIO_NUM:default="20"} +{IDF_TARGET_USB_DM_GPIO_NUM:default="19"} Overview -------- @@ -21,12 +24,14 @@ Hardware USB Connection - Any board with the {IDF_TARGET_NAME} chip with USB connectors or with exposed USB's D+ and D- (DATA+/DATA-) pins. -If the board has no USB connector but has the pins, connect pins directly to the host (e.g. with do-it-yourself cable from any USB connection cable). For example, connect GPIO19/20 to D-/D+ respectively for an ESP32-S2 board: +If the board has no USB connector but has the pins, connect pins directly to the host (e.g. with do-it-yourself cable from any USB connection cable). + +On {IDF_TARGET_NAME}, connect GPIO {IDF_TARGET_USB_DP_GPIO_NUM} and {IDF_TARGET_USB_DM_GPIO_NUM} to D+/D- respectively: .. figure:: ../../../_static/usb-board-connection.png :align: center - :alt: Connection of a board to a host ESP32-S2 + :alt: Connection of a board to a host ESP chip :figclass: align-center Driver Structure diff --git a/docs/en/api-reference/system/freertos_additions.rst b/docs/en/api-reference/system/freertos_additions.rst index 189611c0a0..df312052fd 100644 --- a/docs/en/api-reference/system/freertos_additions.rst +++ b/docs/en/api-reference/system/freertos_additions.rst @@ -25,8 +25,8 @@ Ring Buffers The ESP-IDF FreeRTOS ring buffer is a strictly FIFO buffer that supports arbitrarily sized items. Ring buffers are a more memory efficient alternative to FreeRTOS queues in situations where the size of items is variable. The capacity of a ring buffer is not measured by the number of items -it can store, but rather by the amount of memory used for storing items. The ring buffer provides API -to send an item, or to allocate space for an item in the ring buffer to be filled manually by the user. +it can store, but rather by the amount of memory used for storing items. The ring buffer provides API +to send an item, or to allocate space for an item in the ring buffer to be filled manually by the user. For efficiency reasons, **items are always retrieved from the ring buffer by reference**. As a result, all retrieved items *must also be returned* to the ring buffer by using :cpp:func:`vRingbufferReturnItem` or :cpp:func:`vRingbufferReturnItemFromISR`, in order for them to be removed from the ring buffer completely. @@ -531,6 +531,6 @@ Hooks API Reference Component Specific Properties ----------------------------- -Besides standart component variables that could be gotten with basic cmake build properties FreeRTOS component also provides an arguments (only one so far) for simpler integration with other modules: +Besides standard component variables that could be gotten with basic cmake build properties FreeRTOS component also provides an arguments (only one so far) for simpler integration with other modules: - `ORIG_INCLUDE_PATH` - contains an absolute path to freertos root include folder. Thus instead of `#include "freertos/FreeRTOS.h"` you can refer to headers directly: `#include "FreeRTOS.h"`. diff --git a/docs/page_redirects.txt b/docs/page_redirects.txt index 33a5583ea1..e5725f82e2 100644 --- a/docs/page_redirects.txt +++ b/docs/page_redirects.txt @@ -16,6 +16,7 @@ api-reference/ethernet/esp_eth api-reference/network/esp_eth api-reference/mesh/index api-reference/network/index api-reference/mesh/esp_mesh api-reference/network/esp_mesh api-reference/peripherals/can api-reference/peripherals/twai +api-reference/peripherals/usb api-reference/peripherals/usb_device api-reference/wifi/index api-reference/network/index api-reference/wifi/esp_now api-reference/network/esp_now api-reference/wifi/esp_smartconfig api-reference/network/esp_smartconfig diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index 842f38da88..e23b69ae91 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -12,7 +12,7 @@ API 指南 构建系统 :esp32: 构建系统 (传统 GNU Make) 深度睡眠唤醒存根 - :esp32s2: 通过 USB 升级设备固件 + :SOC_USB_OTG_SUPPORTED: 通过 USB 升级设备固件 错误处理 :SOC_BT_SUPPORTED: ESP-BLE-MESH ESP-WIFI-MESH @@ -41,6 +41,6 @@ API 指南 单元测试 (Target) 单元测试 (Linux Host) :esp32: 单元测试 (传统 GNU Make) - :SOC_USB_SUPPORTED: USB 控制台 + :SOC_USB_OTG_SUPPORTED: USB 控制台 :SOC_USB_SERIAL_JTAG_SUPPORTED: USB Serial/JTAG Controller Console Wi-Fi 驱动 diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst index 8aca2ff658..373b041ed5 100644 --- a/docs/zh_CN/api-reference/peripherals/index.rst +++ b/docs/zh_CN/api-reference/peripherals/index.rst @@ -33,6 +33,6 @@ :esp32s2: Touch Element TWAI UART - :SOC_USB_SUPPORTED: USB + :SOC_USB_OTG_SUPPORTED: USB Device 本部分的 API 示例代码存放在 ESP-IDF 示例项目的 :example:`peripherals` 目录下。 \ No newline at end of file diff --git a/docs/zh_CN/api-reference/peripherals/usb.rst b/docs/zh_CN/api-reference/peripherals/usb.rst deleted file mode 100644 index 6fc57107c6..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../en/api-reference/peripherals/usb.rst diff --git a/docs/zh_CN/api-reference/peripherals/usb_device.rst b/docs/zh_CN/api-reference/peripherals/usb_device.rst new file mode 100644 index 0000000000..eeb934409f --- /dev/null +++ b/docs/zh_CN/api-reference/peripherals/usb_device.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/peripherals/usb_device.rst