代码收藏家 ESP32S3 USB使用详解
0、前期准备
1、会使用idf开发环境
2、懂得kconfig
1、知识储备
1.1 概述
TingUSB是一个开源的跨平台的USB主机/设备的usb协议栈，常用在mcu开发平台，由于不采用动态分配内存以及阻塞所有中断事件，将中断事件
要处理的事情都放在，非中断函数中处理，因此该usb栈内存设计非常安全、线程非常安全。
1.2 功能架构
ESP32S3内部集成了一个USB OTG外设，可配置成主机模式（host）或者设备模式（device），符合usb2.0协议规范。支持全速模式（12Mbit/s）和低速模式（1.5Mbit/s），还支持主机协商协议（HNP）和会话请求协议（SRP）。
设备模式特性
主机模式特性
8 个通道（管道） – 由 IN 与 OUT 两个通道组成的一个控制管道，因为 IN 和 OUT 必须分开处理。仅支持控制传输类型。 – 其余 7 个管道可被配置为 IN 或OUT，支持批量、同步、中断中的任意传输类型。
所有通道共用一个 RX FIFO、一个非周期性 TX FIFO、和一个周期性 TX FIFO。每个 FIFO 大小可配置。
1.4 ESP32S3的tinyUSB使用配置（设备模式）流程介绍
1、使用idf.py新建工程
2、导入tinyUSB组件，导入命令如下：
idf.py add-dependency "leeebo/tinyusb_src^0.16.0~2"
3、设置usb的配置描述符并且注册usb驱动
以下对tinyusb_config_t 结构体进行说明
typedef struct {
union {
const tusb_desc_device_t *device_descriptor;//设备描述符
const tusb_desc_device_t *descriptor __attribute__((deprecated));
};
const char **string_descriptor;//字符描述
int string_descriptor_count; //字符描述的数量
bool external_phy;//是否使用外部phy，一般为false
const uint8_t *configuration_descriptor; //配置描述符
bool self_powered;//是否自供电
int vbus_monitor_io;//自供电电源检测脚
} tinyusb_config_t;
使用例子
tinyusb_config_t ubs_cfg = {
.device_descriptor = NULL,
.string_descriptor = NULL,
.external_phy = false,
.configuration_descriptor = NULL,
};
//一般为空即可，如果默认为空就会使用系统默认配置
//注册驱动
tinyusb_driver_install(&ubs_cfg);
4、初始化usb设备，并且注册相应的驱动
1.5 介绍如何使用ttyACM
以下是参考源码
#include "esp_log.h"
#include "tinyusb.h"
#include "tusb_cdc_acm.h"
#include "tusb_test.h"
void acm_rx_callback(int itf, cdcacm_event_t* event) {
size_t rx_size = 0;
esp_err_t err = tinyusb_cdcacm_read(itf, acm_buff, CONFIG_TINYUSB_CDC_RX_BUFSIZE, &rx_size);
if (err == ESP_OK) {
ESP_LOG_BUFFER_HEXDUMP(TAG, acm_buff, rx_size, ESP_LOG_INFO);
} else {
ESP_LOGE(TAG, "read error(%s:%s)", __FILE__, __func__);
}
}
void app_main(void) {
tinyusb_config_t ubs_cfg = {
.device_descriptor = NULL,
.string_descriptor = NULL,
.external_phy = false,
.configuration_descriptor = NULL,
};
ESP_LOGI(TAG, "acm initialzationning ...");
ESP_ERROR_CHECK(tinyusb_driver_install(&ubs_cfg));
tinyusb_config_cdcacm_t acm_cfg = {
.usb_dev = TINYUSB_USBDEV_0,
.cdc_port = TINYUSB_CDC_ACM_0,
.rx_unread_buf_sz = 64,
.callback_rx = acm_rx_callback,
.callback_rx_wanted_char = NULL,
.callback_line_coding_changed = NULL,
.callback_line_state_changed = NULL,
};
ESP_ERROR_CHECK(tusb_cdc_acm_init(&acm_cfg));
ESP_ERROR_CHECK(tinyusb_cdcacm_register_callback(TINYUSB_CDC_ACM_0, CDC_EVENT_LINE_STATE_CHANGED,
&line_state_changed_callback));
}
到此esp32s3的使用介绍完毕。
以上是直接使用官方写好的usb设备驱动，但是如果想自定义自己的usb外设的话，可以参考以下步骤：
番外
介绍如何注册自定义的esp32s3 usb设备
1、新建components文件，将espressif__ esp_tinyusb 和 espressif__tinyusb两个组件由managed_components拷贝到components，不然在编译的时候，如果有修改过组件的内容会导致编译不过，或者修改的内容会被覆盖
2、在espressif__tinyusb/src/class新建一个文件夹，名字取自定义usb设备名，如test
3、在test文件夹中新建test_device.c和test_device.h两个设备文件，内容可参考cdc_acm
test_device.c内容参考如下：
#include "tusb_option.h"
#if (CFG_TUD_ENABLED && CFG_TUD_TEST)
#include "device/usbd.h"
#include "device/usbd_pvt.h"
#include "test_device.h"
enum
{
BULK_PACKET_SIZE = (TUD_OPT_HIGH_SPEED ? 512 : 64)
};
/* 该结构体的用途：用于作为通讯节点 */
typedef struct {
uint8_t ep_in;
uint8_t ep_out;
tu_fifo_t rx_ff;
tu_fifo_t tx_ff;
uint8_t rx_ff_buf[CFG_TUD_TEXT_RX_BUFSIZE];
uint8_t tx_ff_buf[CFG_TUD_TEXT_TX_BUFSIZE];
OSAL_MUTEX_DEF(rx_ff_mutex);
OSAL_MUTEX_DEF(tx_ff_mutex);
CFG_TUSB_MEM_ALIGN uint8_t epin_buf[CFG_TUD_TEXT_EP_BUFSIZE];
CFG_TUSB_MEM_ALIGN uint8_t epout_buf[CFG_TUD_TEXT_EP_BUFSIZE];
} test_interface_t;
CFG_TUSB_MEM_SECTION tu_static test_interface_t _test_itf;
static bool prep_out_transaction(test_interface_t* p_test) {
uint8_t const rhport = 0;
uint16_t available = tu_fifo_remaining(_test_itf.rx_ff);
TU_VERIFY(available >= sizeof(p_test->epout_buf));
// claim endpoint
//判断端点是否在使用
TU_VERIFY(usbd_edpt_claim(rhport, p_test->ep_out));
// fifo can be changed before endpoint is claimed
available = tu_fifo_remaining(p_test->rx_ff);
if (available >= sizeof(p_test->epout_buf)) {
return usbd_edpt_xfer(rhport, p_test->ep_out, p_test->epout_buf, sizeof(p_test->epout_buf));
} else {
//释放端点
usbd_edpt_release(rhport, p_test->ep_out);
return false;
}
}
void test_init(void) {
tu_memclr(&_test_itf, sizeof(_test_itf));
//配置数据传输管道
tu_fifo_config(_test_itf.rx_ff, p_test->rx_ff_buf, TU_ARRAY_SIZE(p_test->rx_ff_buf), 1, false);
tu_fifo_config(_test_itf.tx_ff, p_test->tx_ff_buf, TU_ARRAY_SIZE(p_test->tx_ff_buf), 1, true);
//创建管道锁
tu_fifo_config_mutex(_test_itf.rx_ff, NULL, osal_mutex_create(_test_itf.rx_ff_mutex));
tu_fifo_config_mutex(_test_itf.tx_ff, osal_mutex_create(_test_itf.tx_ff_mutex), NULL);
}
void test_reset(uint8_t rhport) {
tu_memclr(&_test_itf, sizeof(uint8_t)*2);
//清空管道
tu_fifo_clear(_test_itf.rx_ff);
tu_fifo_clear(_test_itf.tx_ff);
tu_fifo_set_overwritable(_test_itf.tx_ff, true);
}
uint16_t test_open(uint8_t rhport, tusb_desc_interface_t const* itf_desc, uint16_t max_len) {
test_interface_t* p_test = NULL;
uint16_t drv_len = 0;
TU_VERIFY(TUSB_CLASS_VENDOR_SPECIFIC == itf_desc->bInterfaceClass, 0);
if (_test_itf.ep_in == 0) {
p_test = &_test_itf;
}
TU_ASSERT(p_test, 0);
uint8_t const* p_desc = (uint8_t const*)itf_desc;
drv_len = tu_desc_len(p_desc);
/* Interface */
if (TUSB_DESC_INTERFACE == tu_desc_type(p_desc)) {
/* Endpoint Descriptor */
p_desc = tu_desc_next(p_desc);
TU_ASSERT(
usbd_open_edpt_pair(rhport, p_desc, itf_desc->bNumEndpoints, TUSB_XFER_BULK, _test_itf.ep_out, _test_itf.ep_in),
0);
drv_len += itf_desc->bNumEndpoints * sizeof(tusb_desc_endpoint_t);
}
prep_out_transaction(p_test);
return drv_len;
}
bool test_xfer_cb(uint8_t rhport, uint8_t ep_addr, xfer_result_t event, uint32_t xferred_bytes) {
if (ep_addr == _test_itf.ep_out) {
tu_fifo_write_n(_test_itf.rx_ff, _test_itf.epout_buf, (uint16_t)xferred_bytes);
if (tud_test_rx_cb && !tu_fifo_empty(_test_itf.rx_ff)) {
tud_test_rx_cb();
}
prep_out_transaction(&_test_itf);
} else if (ep_addr == _test_itf.ep_in) {
if ( tud_text_tx_complete_cb ) tud_text_tx_complete_cb();//调用回调
if ( 0 == tud_test_write_flush())
{
if ( !tu_fifo_count(_test_itf.tx_ff) && xferred_bytes && (0 == (xferred_bytes & (BULK_PACKET_SIZE-1))) )
{
if ( usbd_edpt_claim(rhport, _test_itf.ep_in) )
{
usbd_edpt_xfer(rhport, _test_itf.ep_in, NULL, 0);
}
}
}
}
return true;
}
bool test_control_xfer_cb (uint8_t rhport, uint8_t stage, tusb_control_request_t const * request){
return true;
}
// app api
uint32_t tud_test_read(void* buffer, uint32_t bufsize) {
uint32_t num_read = tu_fifo_read_n(&_test_itf.rx_ff, buffer, (uint16_t)bufsize);
prep_out_transaction(&_test_itf);
return num_read;
}
bool tud_test_peek(uint8_t* chr) {
return tu_fifo_peek(&_test_itf.rx_ff, chr);
}
void tud_test_read_flush(void) {
tu_fifo_clear(_test_itf.rx_ff);
prep_out_transaction(&_test_itf);
}
uint32_t tu_test_write(void*buffer,uint32_t bufsize){
test_interface_t* p_test = &_test_itf;
uint16_t ret = tu_fifo_write_n(_test_itf.tx_ff,buffer,(uint16_t)bufsize);
if ((tu_fifo_count(_test_itf.tx_ff) >= BULK_PACKET_SIZE) || ((CFG_TUD_TEXT_TX_BUFSIZE < BULK_PACKET_SIZE) && tu_fifo_full(_test_itf.tx_ff)))
{
tud_test_write_flush();
}
return ret;
}
uint32_t tud_test_write_flush(void){
// Skip if usb is not ready yet
TU_VERIFY(tud_ready(), 0);
// No data to send
if ( !tu_fifo_count(_test_itf.tx_ff) ) return 0;
uint8_t const rhport = 0;
// Claim the endpoint
TU_VERIFY( usbd_edpt_claim(rhport, _test_itf.ep_in), 0 );
// Pull data from FIFO
uint16_t const count = tu_fifo_read_n(_test_itf.tx_ff, _test_itf.epin_buf, sizeof(_test_itf.epin_buf));
if (count)
{
TU_ASSERT( usbd_edpt_xfer(rhport, _test_itf.ep_in, _test_itf.epin_buf, count), 0 );
return count;
}else
{
// Release endpoint since we don't make any transfer
// Note: data is dropped if terminal is not connected
usbd_edpt_release(rhport,_test_itf.ep_in);
return 0;
}
}
uint32_t tud_test_write_available(void)
{
return tu_fifo_remaining(&_test_itf.tx_ff);
}
bool tud_test_write_clear(void)
{
return tu_fifo_clear(&_test_itf.tx_ff);
}
#endif
test_device.h内容参考如下：
#ifndef _TUSB_TEST_DEVICE_H_
#define _TUSB_TEST_DEVICE_H_
#include "common/tusb_common.h"
#ifdef __cplusplus
extern "C" {
#endif
void test_init (void);
void test_reset (uint8_t rhport);
uint16_t test_open (uint8_t rhport, tusb_desc_interface_t const * itf_desc, uint16_t max_len);
bool test_control_xfer_cb (uint8_t rhport, uint8_t stage, tusb_control_request_t const * request);
bool test_xfer_cb (uint8_t rhport, uint8_t ep_addr, xfer_result_t event, uint32_t xferred_bytes);
//callback
TU_ATTR_WEAK void tud_test_rx_cb(void);
TU_ATTR_WEAK void tud_test_tx_complete_cb(void);
// App API
uint32_t tud_test_read(void* buffer, uint32_t bufsize);
bool tud_test_peek(uint8_t* chr);
void tud_test_read_flush(void);
uint32_t tu_test_write(void*buffer,uint32_t bufsize);
uint32_t tud_test_write_flush(void);
uint32_t tud_test_write_available(void);
bool tud_test_write_clear(void);
#ifdef __cplusplus
}
#endif
#endif /* _TUSB_TEST_DEVICE_H_ */
4、在tu_static usbd_class_driver_t const _usbd_driver 数组中注册自定义设备
tu_static usbd_class_driver_t const _usbd_driver[] =
{
...
#if CFG_TUD_TEST
{
DRIVER_NAME("TEST")
.init = test_init,
.reset = test_reset,
.open = test_open,
.control_xfer_cb = test_control_xfer_cb,
.xfer_cb = test_xfer_cb,
.sof = NULL
},
#endif
...
}
5、在espressif__ esp_tinyusb/include/tusb_config.h文件中添加自定义设备配置
// TEST EP Size
#define CFG_TUD_TEST_EP_BUFSIZE 64
#define CFG_TUD_TEST_RX_BUFSIZE CONFIG_TINYUSB_TEST_RX_BUFSIZE
#define CFG_TUD_TEST_TX_BUFSIZE CONFIG_TINYUSB_TEST_TX_BUFSIZE
#define CFG_TUD_TEST CONFIG_TINYUSB_TEST_ENABLED
6、在espressif__ esp_tinyusb/include中新建tusb_test.h文件，内容可参考tusb_cdc_acm.h
内容如下
#pragma once
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include "freertos/timers.h"
#include "tusb.h"
#include "tinyusb_types.h"
#if (CONFIG_TINYUSB_TEST_ENABLED != 1)
#error "TinyUSB TEST driver must be enabled in menuconfig"
#endif
#define EPNUM_TEST_IN 0x81
#define EPNUM_TEST_OUT 0x01
#define TUSB_CLASS_TEST 0xFF
#define TUD_TEST_DESC_LEN (8 + 9 + 7 + 7)
// Interface number, string index, EP Out & EP In address, EP size
#define TUD_TEST_DESCRIPTOR(_itfnum, _stridx, _epout, _epin, _epsize) \
/* Interface */ \
8, TUSB_DESC_INTERFACE_ASSOCIATION, _itfnum, 1, TUSB_CLASS_TEST, 0, 0, 0, \
9, TUSB_DESC_INTERFACE, _itfnum, 0, 2, TUSB_CLASS_TEST, 0, 0, _stridx, \
7, TUSB_DESC_ENDPOINT, _epin, TUSB_XFER_BULK, U16_TO_U8S_LE(_epsize), 0, \
7, TUSB_DESC_ENDPOINT, _epout, TUSB_XFER_BULK, U16_TO_U8S_LE(_epsize), 0
typedef enum{
TEST_EVENT_RX,
TEST_EVENT_TX_COMPLETE
}test_event_type_t;
typedef void (* tusb_test_callback_t)(void);
typedef struct{
tusb_test_callback_t callback_rx;
tusb_test_callback_t callback_tx_complete_callback;
}tinyusb_config_test_t;
esp_err_t tinyusb_test_register_callback(test_event_type_t _event_type,tusb_test_callback_t _callback);
esp_err_t tinyusb_test_read(uint8_t *out_buf, size_t out_buf_sz, size_t *rx_data_size);
#ifdef __cplusplus
extern }
#endif
7、在espressif__ esp_tinyusb/中新建tusb_test.c文件，内容可参考tusb_cdc_acm.c
内容如下:
#include "tusb_test.h"
#include "esp_check.h"
#include "esp_err.h"
#include "esp_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "tusb.h"
#include "sdkconfig.h"
static portMUX_TYPE test_lock = portMUX_INITIALIZER_UNLOCKED;
#define TEST_ENTER_CRITICAL() portENTER_CRITICAL(&test_lock)
#define TEST_EXIT_CRITICAL() portEXIT_CRITICAL(&test_lock)
static const char* TAG = "tusb_test";
static tinyusb_config_test_t _test_cfg;
esp_err_t tinyusb_test_read(uint8_t* out_buf, size_t out_buf_sz, size_t* rx_data_size) {
*rx_data_size = tud_test_read(out_buf, out_buf_sz);
return ESP_OK;
}
esp_err_t tinyusb_test_register_callback(test_event_type_t _event_type, tusb_test_callback_t _callback) {
switch (_event_type) {
case test_EVENT_RX:
TEST_ENTER_CRITICAL();
_test_cfg.callback_rx = _callback;
TEST_EXIT_CRITICAL();
return ESP_OK;
case test_EVENT_TX_COMPLETE:
TEST_ENTER_CRITICAL();
_test_cfg.callback_tx_complete_callback = _callback;
TEST_EXIT_CRITICAL();
return ESP_OK;
default:
ESP_LOGE(TAG, "test Callback fun is NULL");
return ESP_FAIL;
}
}
void tud_test_rx_cb(void) {
if (_test_cfg.callback_rx) {
_test_cfg.callback_rx();
}
}
void tud_test_tx_complete_cb(void) {
if (_test_cfg.callback_tx_complete_callback) {
_test_cfg.callback_tx_complete_callback();
}
}
void tinyusb_test_relay_out_point(void){
tud_test_relay_out_point();
}
到此设备新加完毕
使用例子：
#include "esp_log.h"
#include "tinyusb.h"
#include "tusb_test.h"
static uint8_t test_buff[CONFIG_TINYUSB_TEXT_RX_BUFSIZE + 1];
void test_rx_callback(int itf, cdcacm_event_t* event) {
size_t rx_size = 0;
esp_err_t err = tinyusb_test_read(itf, acm_buff, CONFIG_TINYUSB_TEXT_RX_BUFSIZE, &rx_size);
if (err == ESP_OK) {
ESP_LOG_BUFFER_HEXDUMP(TAG, test_buff, rx_size, ESP_LOG_INFO);
} else {
ESP_LOGE(TAG, "read error(%s:%s)", __FILE__, __func__);
}
}
void app_main(void) {
tinyusb_config_t ubs_cfg = {
.device_descriptor = NULL,
.string_descriptor = NULL,
.external_phy = false,
.configuration_descriptor = NULL,
};
ESP_LOGI(TAG, "test initialzationning ...");
ESP_ERROR_CHECK(tinyusb_driver_install(&ubs_cfg));
ESP_ERROR_CHECK(tinyusb_test_register_callback(DCM_EVENT_RX, test_rx_callback));
}
作者：MagicKingC
