Skip to content

Commit 96786b0

Browse files
roma-jamroma-jam
authored
Merge pull request #192 from espressif/docs/readme_update
docs(esp_tinyusb): Added esp-idf version of documentation to v1.x.x
2 parents 82a759e + 2255455 commit 96786b0

File tree

2 files changed

+142
-4
lines changed

2 files changed

+142
-4
lines changed

‎device/esp_tinyusb/CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
## 1.7.7 [unreleased]
2+
3+
- esp_tinyusb: Added documentation to README.md
4+
15
## 1.7.6
26

37
- MSC: Fixed the possibility to use SD/MMC storage with large capacity (more than 4 GB)

‎device/esp_tinyusb/README.md‎

Lines changed: 138 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,6 @@ It contains:
1212
* VBUS monitoring for self-powered devices
1313
* SPI Flash or sd-card access via MSC USB device Class.
1414

15-
## Documentation and examples
16-
You can find documentation in [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/usb_device.html).
17-
18-
You can find examples in [ESP-IDF on GitHub](https://github.com/espressif/esp-idf/tree/master/examples/peripherals/usb/device).
1915
## How to use?
2016

2117
This component is distributed via [IDF component manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html). Just add `idf_component.yml` file to your main component with the following content:
@@ -30,3 +26,141 @@ Or simply run:
3026
```
3127
idf.py add-dependency esp_tinyusb~1.0.0
3228
```
29+
30+
## Documentation
31+
32+
Hardware-related documentation could be found in [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/usb_device.html).
33+
34+
### Device Stack Structure
35+
36+
The Device Stack is built on top of TinyUSB and provides:
37+
38+
- Custom USB descriptor support
39+
- Serial device (CDC-ACM) support
40+
- Standard stream redirection through the serial device
41+
- Storage media support (SPI-Flash and SD-Card) for USB MSC Class
42+
- A dedicated task for TinyUSB servicing
43+
44+
### Configuration Options
45+
46+
Configure the Device Stack using `menuconfig`:
47+
48+
- TinyUSB log verbosity
49+
- Device Stack task options
50+
- Default device/string descriptor options
51+
- Class-specific options
52+
53+
### Descriptor Configuration
54+
55+
Configure USB descriptors using the `tinyusb_config_t` structure:
56+
57+
- `device_descriptor`
58+
- `string_descriptor`
59+
- `configuration_descriptor` (full-speed)
60+
- For high-speed devices: `fs_configuration_descriptor`, `hs_configuration_descriptor`, `qualifier_descriptor`
61+
62+
If any descriptor field is set to `NULL`, default descriptors (based on menuconfig) are used.
63+
64+
### Installation
65+
66+
Install the Device Stack by calling `tinyusb_driver_install` with a `tinyusb_config_t` structure. Members set to `0` or `NULL` use default values.
67+
68+
```c
69+
const tinyusb_config_t partial_init = {
70+
.device_descriptor = NULL,
71+
.string_descriptor = NULL,
72+
.external_phy = false,
73+
#if (TUD_OPT_HIGH_SPEED)
74+
.fs_configuration_descriptor = NULL,
75+
.hs_configuration_descriptor = NULL,
76+
.qualifier_descriptor = NULL,
77+
#else
78+
.configuration_descriptor = NULL,
79+
#endif
80+
};
81+
```
82+
83+
### Self-Powered Device
84+
85+
Self-powered devices must monitor VBUS voltage. Use a GPIO pin with a voltage divider or comparator to detect VBUS state. Set `self_powered = true` and assign the VBUS monitor GPIO in `tinyusb_config_t`.
86+
87+
### USB Serial Device (CDC-ACM)
88+
89+
If enabled, initialize the USB Serial Device with `tusb_cdc_acm_init` and a `tinyusb_config_cdcacm_t` structure:
90+
91+
```c
92+
const tinyusb_config_cdcacm_t acm_cfg = {
93+
.usb_dev = TINYUSB_USBDEV_0,
94+
.cdc_port = TINYUSB_CDC_ACM_0,
95+
.rx_unread_buf_sz = 64,
96+
.callback_rx = NULL,
97+
.callback_rx_wanted_char = NULL,
98+
.callback_line_state_changed = NULL,
99+
.callback_line_coding_changed = NULL
100+
};
101+
tusb_cdc_acm_init(&acm_cfg);
102+
```
103+
104+
Redirect standard I/O streams to USB with `esp_tusb_init_console` and revert with `esp_tusb_deinit_console`.
105+
106+
### USB Mass Storage Device (MSC)
107+
108+
If enabled, initialize storage media for MSC:
109+
110+
**SPI-Flash Example:**
111+
```c
112+
static esp_err_t storage_init_spiflash(wl_handle_t *wl_handle) {
113+
// ... partition and mount logic ...
114+
}
115+
storage_init_spiflash(&wl_handle);
116+
117+
const tinyusb_msc_spiflash_config_t config_spi = {
118+
.wl_handle = wl_handle
119+
};
120+
tinyusb_msc_storage_init_spiflash(&config_spi);
121+
```
122+
123+
**SD-Card Example:**
124+
```c
125+
static esp_err_t storage_init_sdmmc(sdmmc_card_t **card) {
126+
// ... SDMMC host and slot config ...
127+
}
128+
storage_init_sdmmc(&card);
129+
130+
const tinyusb_msc_sdmmc_config_t config_sdmmc = {
131+
.card = card
132+
};
133+
tinyusb_msc_storage_init_sdmmc(&config_sdmmc);
134+
```
135+
136+
### MSC Performance Optimization
137+
138+
- **Single-buffer approach:** Buffer size is set via `CONFIG_TINYUSB_MSC_BUFSIZE`.
139+
- **Performance:** SD cards offer higher throughput than internal SPI flash due to architectural constraints.
140+
141+
**Performance Table (ESP32-S3):**
142+
143+
| FIFO Size | Read Speed | Write Speed |
144+
|-----------|------------|-------------|
145+
| 512 B | 0.566 MB/s | 0.236 MB/s |
146+
| 8192 B | 0.925 MB/s | 0.928 MB/s |
147+
148+
**Performance Table (ESP32-P4):**
149+
150+
| FIFO Size | Read Speed | Write Speed |
151+
|-----------|------------|-------------|
152+
| 512 B | 1.174 MB/s | 0.238 MB/s |
153+
| 8192 B | 4.744 MB/s | 2.157 MB/s |
154+
| 32768 B | 5.998 MB/s | 4.485 MB/s |
155+
156+
**Performance Table (ESP32-S2, SPI Flash):**
157+
158+
| FIFO Size | Write Speed |
159+
|-----------|-------------|
160+
| 512 B | 5.59 KB/s |
161+
| 8192 B | 21.54 KB/s |
162+
163+
**Note:** Internal SPI flash is for demonstration only; use SD cards or external flash for higher performance.
164+
165+
## Examples
166+
You can find examples in [ESP-IDF on GitHub](https://github.com/espressif/esp-idf/tree/master/examples/peripherals/usb/device).

0 commit comments

Comments
 (0)