Skip to content

Commit 64848f4

Browse files
lijunru-hublijunru-hub
committed
Merge branch 'feat/usb_host_device_switch' into 'master'
feat(otg): add manual switch example See merge request ae_group/esp-iot-solution!1115
2 parents c683b16 + 81440f9 commit 64848f4

File tree

20 files changed

+800
-2
lines changed

20 files changed

+800
-2
lines changed

‎.gitlab/ci/build.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -816,6 +816,14 @@ build_example_usb_host_usb_msc_ota:
816816
variables:
817817
EXAMPLE_DIR: examples/usb/host/usb_msc_ota
818818

819+
build_example_usb_otg_usb_host_device_mode_manual_switch:
820+
extends:
821+
- .build_examples_template
822+
- .rules:build:example_usb_host_usb_msc_ota
823+
- .build_idf_version_greater_equal_v5_0
824+
variables:
825+
EXAMPLE_DIR: examples/usb/otg/usb_host_device_mode_manual_switch
826+
819827
build_example_utilities_xz_decompress_file:
820828
extends:
821829
- .build_examples_template

‎.gitlab/ci/rules.yml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -563,6 +563,9 @@
563563
.patterns-example_usb_host_usb_msc_ota: &patterns-example_usb_host_usb_msc_ota
564564
- "examples/usb/host/usb_msc_ota/**/*"
565565

566+
.patterns-example_usb_otg_usb_host_device_mode_manual_switch: &patterns-example_usb_otg_usb_host_device_mode_manual_switch
567+
- "examples/usb/otg/usb_host_device_mode_manual_switch/**/*"
568+
566569
.patterns-example_utilities_xz_decompress_file: &patterns-example_utilities_xz_decompress_file
567570
- "examples/utilities/xz_decompress_file/**/*"
568571

@@ -1411,6 +1414,18 @@
14111414
- <<: *if-dev-push
14121415
changes: *patterns-example_usb_host_usb_msc_ota
14131416

1417+
.rules:build:example_usb_otg_usb_host_device_mode_manual_switch:
1418+
rules:
1419+
- <<: *if-protected
1420+
- <<: *if-label-build
1421+
- <<: *if-trigger-job
1422+
- <<: *if-dev-push
1423+
changes: *patterns-build_system
1424+
- <<: *if-dev-push
1425+
changes: *patterns-components_usb_esp_msc_ota
1426+
- <<: *if-dev-push
1427+
changes: *patterns-example_usb_otg_usb_host_device_mode_manual_switch
1428+
14141429
.rules:build:example_utilities_xz_decompress_file:
14151430
rules:
14161431
- <<: *if-protected

‎docs/en/usb/usb_overview/usb_otg.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,3 +127,10 @@ USB Device development using USB-OTG peripherals
127127
USB-OTG peripherals support USB Device functionality, and Espressif has officially adapted the ``TinyUSB`` stack. Users can develop USB standard devices or custom devices based on the open-source ``TinyUSB``, such as HID, MSC, CDC, ECM, UAC, and more.
128128

129129
For more details on the USB Device solution, please refer to :doc:`USB Device Solution <./usb_device_solutions>`.
130+
131+
Dynamic Switching of USB-OTG Peripheral Modes
132+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
133+
134+
The USB-OTG peripheral supports dynamic switching of its mode. Users can achieve dynamic switching by dynamically registering the USB Host Driver or USB Device Driver.
135+
136+
* Example Code: USB OTG Manual Switching :example:`usb/otg/usb_host_device_mode_manual_switch`

‎docs/zh_CN/usb/usb_overview/usb_otg.rst‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -81,15 +81,15 @@ USB-OTG 外设内置功能
8181
ESP32-S2/S3 等内置 USB-OTG 外设的芯片，ROM Code 中内置了 USB 通信设备类 (CDC) 的功能，该功能可用于替代 UART 接口，实现 Log、Console 和固件下载功能。
8282

8383

84-
#.
84+
#.
8585
由于 USB OTG Console 默认为关闭状态，如需使用它下载固件，需要通过以下方法完成初次下载：
8686

8787

8888
#. 在 ``menuconfig`` 中先使能 USB OTG Console 功能，然后编译固件
8989
#. 手动芯片的 Boot 控制引脚拉低，然后将芯片通过 USB 线连接到 PC，进入下载模式。PC 会发现新的串口设备，Windows 为 ``COM*``\ ，Linux 为 ``/dev/ttyACM*``\ , MacOS 为 ``/dev/cu*``\ 。
9090
#. 使用 esptool 工具（或直接使用 idf.py flash）配置设备对应的串口号下载固件。
9191

92-
#.
92+
#.
9393
初次下载完成以后，USB OTG Console 功能将自动使能，即可通过 USB 线连接到 PC，PC 会发现新的串口设备，Windows 为 ``COM*``\ ，Linux 为 ``/dev/ttyACM*``\ , MacOS 为 ``/dev/cu*``\ ，LOG 数据将从该虚拟串口打印。
9494

9595
#. 用户无需再手动拉低 Boot 控制引脚，使用 esptool 工具（或直接使用 idf.py flash）配置设备对应的串口号即可下载固件，下载期间，esptool 通过 USB 控制协议自动将设备 Reset 并切换到下载模式。
@@ -129,3 +129,10 @@ USB Host 方案详情，请参考 :doc:`USB Host Solution <./usb_host_solutions>
129129
USB-OTG 外设支持 USB Device 功能，乐鑫已经官方适配了 TinyUSB 协议栈，用户可以直接使用基于 TinyUSB 开源协议栈开发的 USB 标准设备或自定义设备，例如 HID，MSC，CDC，ECM, UAC 等。
130130

131131
USB Device 方案详情，请参考 :doc:`USB Device Solution <./usb_device_solutions>` 。
132+
133+
动态切换 USB-OTG 外设模式
134+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
135+
136+
USB-OTG 外设支持动态切换 USB-OTG 外设模式，用户可以通过动态的注册 USB Host Driver 或 USB Device Driver，实现 USB-OTG 外设的动态切换。
137+
138+
* 示例代码: USB OTG 手动切换 :example:`usb/otg/usb_host_device_mode_manual_switch`

‎examples/.build-rules.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -350,6 +350,10 @@ examples/usb/host/usb_msc_ota:
350350
temporary: true
351351
reason: esp32-s3-usb-otg not supported idf release 5.0 build yet
352352

353+
examples/usb/otg/usb_host_device_mode_manual_switch:
354+
enable:
355+
- if: SOC_USB_OTG_SUPPORTED == 1
356+
353357
examples/utilities/xz_decompress_file:
354358
enable:
355359
- if: INCLUDE_DEFAULT == 1

‎examples/usb/otg/usb_host_device_mode_manual_switch/CMakeLists.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# For more information about build system see
2+
# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
3+
# The following five lines of boilerplate have to be in your project's
4+
# CMakeLists in this exact order for cmake to work correctly
5+
cmake_minimum_required(VERSION 3.16)
6+
7+
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
8+
project(manual_switch)

‎examples/usb/otg/usb_host_device_mode_manual_switch/README.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# USB Host Device mode manual switch
2+
3+
This example demonstrates how to dynamically switch the USB OTG peripheral between host and device modes.
4+
In this example, the device is emulated as a USB CDC device, while the host functions as an MSC host capable of connecting to a USB flash drive.
5+
6+
## Dependences
7+
8+
USB Host:
9+
10+
* [esp_msc_ota](https://components.espressif.com/components/espressif/esp_msc_ota/versions/1.0.0)
11+
12+
The host application must support dynamic registration and unregistration.
13+
14+
USB Device:
15+
16+
* [tinyusb](https://components.espressif.com/components/espressif/tinyusb/versions/0.17.0~1)
17+
18+
The TinyUSB version must be greater than **0.17.0**, as versions after this support deinitializing the DWC2 driver.
19+
20+
## How to use the example
21+
22+
### Hardware Required
23+
24+
The example can be run on ESP32-S2 or ESP32-S3 or ESP32-P4 based development board with USB Disk (with Fat32 format).
25+
26+
### Setup the Hardware
27+
28+
Connect the external USB MSC device to ESP32-S USB interface directly.
29+
30+
| ESP32-Sx GPIO | ESP32-P4 GPIO | USB Device |
31+
| ------------- | ------------- | ----------- |
32+
| 20 | 50 | D+ (green) |
33+
| 19 | 49 | D- (white) |
34+
| GND | GND | GND (black) |
35+
| +5V | +5V | +5V (red) |
36+
37+
### Configure the project
38+
39+
1. Use the command below to set build target to the chip.
40+
41+
```
42+
idf.py set-target esp32s3
43+
```
44+
45+
2. Build the project and flash it to the board, then run monitor tool to view serial output:
46+
47+
```
48+
idf.py -p PORT build flash monitor
49+
```
50+
51+
(To exit the serial monitor, type ``Ctrl-]``.)
52+
53+
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
54+
55+
3. Connect a USB disk to the USB port, and you will see the USB disk being detected along with its descriptors printed.
56+
57+
4. Disconnect the USB disk, then press the boot button to set the device to device mode. At this point, connect it to a computer, and a serial device will appear.

‎examples/usb/otg/usb_host_device_mode_manual_switch/cdc_device/tusb_config.h‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
/*
2+
* The MIT License (MIT)
3+
*
4+
* Copyright (c) 2019 Ha Thach (tinyusb.org)
5+
*
6+
* Permission is hereby granted, free of charge, to any person obtaining a copy
7+
* of this software and associated documentation files (the "Software"), to deal
8+
* in the Software without restriction, including without limitation the rights
9+
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10+
* copies of the Software, and to permit persons to whom the Software is
11+
* furnished to do so, subject to the following conditions:
12+
*
13+
* The above copyright notice and this permission notice shall be included in
14+
* all copies or substantial portions of the Software.
15+
*
16+
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17+
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18+
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19+
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20+
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21+
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22+
* THE SOFTWARE.
23+
*
24+
*/
25+
26+
#ifndef _TUSB_CONFIG_H_
27+
#define _TUSB_CONFIG_H_
28+
29+
#include "sdkconfig.h"
30+
31+
#ifdef __cplusplus
32+
extern "C" {
33+
#endif
34+
35+
//--------------------------------------------------------------------+
36+
// Board Specific Configuration
37+
//--------------------------------------------------------------------+
38+
39+
#ifdef CONFIG_TINYUSB_RHPORT_HS
40+
# define CFG_TUSB_RHPORT1_MODE OPT_MODE_DEVICE | OPT_MODE_HIGH_SPEED
41+
# define CONFIG_USB_HS 1
42+
#else
43+
# define CFG_TUSB_RHPORT0_MODE OPT_MODE_DEVICE | OPT_MODE_FULL_SPEED
44+
# define CONFIG_USB_HS 0
45+
#endif
46+
47+
//--------------------------------------------------------------------
48+
// Common Configuration
49+
//--------------------------------------------------------------------
50+
51+
// defined by compiler flags for flexibility
52+
#ifndef CFG_TUSB_MCU
53+
#error CFG_TUSB_MCU must be defined
54+
#endif
55+
56+
#ifndef CFG_TUSB_OS
57+
#define CFG_TUSB_OS OPT_OS_FREERTOS
58+
#endif
59+
60+
#ifndef ESP_PLATFORM
61+
#define ESP_PLATFORM 1
62+
#endif
63+
64+
// Espressif IDF requires "freertos/" prefix in include path
65+
#if TU_CHECK_MCU(OPT_MCU_ESP32S2, OPT_MCU_ESP32S3, OPT_MCU_ESP32P4)
66+
#define CFG_TUSB_OS_INC_PATH freertos/
67+
#endif
68+
69+
#ifndef CFG_TUSB_DEBUG
70+
#define CFG_TUSB_DEBUG 0
71+
#endif
72+
73+
// Enable Device stack
74+
#define CFG_TUD_ENABLED 1
75+
76+
/* USB DMA on some MCUs can only access a specific SRAM region with restriction on alignment.
77+
* Tinyusb use follows macros to declare transferring memory so that they can be put
78+
* into those specific section.
79+
* e.g
80+
* - CFG_TUSB_MEM SECTION : __attribute__ (( section(".usb_ram") ))
81+
* - CFG_TUSB_MEM_ALIGN : __attribute__ ((aligned(4)))
82+
*/
83+
#ifndef CFG_TUSB_MEM_SECTION
84+
#define CFG_TUSB_MEM_SECTION
85+
#endif
86+
87+
#ifndef CFG_TUSB_MEM_ALIGN
88+
#define CFG_TUSB_MEM_ALIGN __attribute__ ((aligned(4)))
89+
#endif
90+
91+
//--------------------------------------------------------------------
92+
// DEVICE CONFIGURATION
93+
//--------------------------------------------------------------------
94+
95+
#ifndef CFG_TUD_ENDPOINT0_SIZE
96+
#define CFG_TUD_ENDPOINT0_SIZE 64
97+
#endif
98+
99+
#define USB_VID CONFIG_TUSB_VID
100+
#define USB_PID CONFIG_TUSB_PID
101+
#define USB_MANUFACTURER CONFIG_TUSB_MANUFACTURER
102+
#define USB_PRODUCT CONFIG_TUSB_PRODUCT
103+
104+
//------------- CLASS -------------//
105+
/*!< CDC ACM Class */
106+
#define CFG_TUD_CDC 1
107+
// CDC FIFO size of TX and RX
108+
#define CFG_TUD_CDC_RX_BUFSIZE 512
109+
#define CFG_TUD_CDC_TX_BUFSIZE 512
110+
#define CFG_TUD_CDC_EP_BUFSIZE CONFIG_USB_HS ? 512 : 64
111+
112+
#ifdef __cplusplus
113+
}
114+
#endif
115+
116+
#endif /* _TUSB_CONFIG_H_ */

0 commit comments

Comments
 (0)