JoyD/ESP32/my_usb_project/README.md

USB 虚拟键鼠项目说明

项目概述

ESP32-S3 USB 复合设备项目，采用 C + Rust 混合编程：

• USB 部分：C + TinyUSB（稳定可靠）
• 应用逻辑：Rust（通过 FFI 与 C 交互）

编译成功

项目已成功编译，生成的文件位于：

• build/my_usb_project.bin - 主程序固件
• build/bootloader/bootloader.bin - 引导程序
• build/partition_table/partition-table.bin - 分区表

编译步骤

1. 编译 Rust 库：

cargo.bat

2. 编译 ESP-IDF 项目：

idf.cmd build

烧录到 ESP32-S3

使用以下命令烧录：

idf.cmd flash

或者指定端口：

idf.cmd -p COM3 flash

擦除 flash

使用以下命令擦除整个 flash：

idf.cmd erase_flash

或者指定端口：

idf.cmd -p COM3 erase_flash

调试与日志

串口监视器

烧录后启动串口监视器查看日志：

idf.cmd monitor

或者指定端口：

idf.cmd -p COM3 monitor

烧录并监视

一步完成烧录和监视：

idf.cmd flash monitor

退出监视器

按 Ctrl+] 退出串口监视器。

日志级别

在代码中使用 ESP_LOG 系列函数输出日志：

ESP_LOGI(TAG, "This is an info message");
ESP_LOGW(TAG, "This is a warning");
ESP_LOGE(TAG, "This is an error");

默认日志级别可在 sdkconfig 中配置：CONFIG_LOG_DEFAULT_LEVEL

功能说明

当前实现的 USB 复合设备包含：

• ✅ USB 键盘 (HID)
• ✅ USB 鼠标 (HID)
• ✅ USB 虚拟 U盘 (MSC)

技术细节

链接器脚本修复

由于 Rust 库包含的 rodata 数据与 ESP-IDF 的 app desc 段冲突，需要修改链接器脚本 build/esp-idf/esp_system/ld/sections.ld，在 .flash.appdesc 段末尾添加 64KB 对齐：

.flash.appdesc : ALIGN(0x10)
{
  _rodata_reserved_start = ABSOLUTE(.);
  _rodata_start = ABSOLUTE(.);
  *(.rodata_desc .rodata_desc.*)
  *(.rodata_custom_desc .rodata_custom_desc.*)
  /* Force to next 64KB boundary */
  . = ALIGN(0x10000);
} >default_rodata_seg

下一步开发

要实现具体的键盘/鼠标功能，需要：

1. 添加 HID 键盘报告描述符 - 在 tusb_config.h 中配置
2. 实现键盘事件处理 - 添加按键发送代码
3. 实现鼠标事件处理 - 添加鼠标移动/点击代码
4. 添加 USB CDC (串口) - 用于调试输出

注意事项

• 确保 ESP32-S3 开发板支持 USB OTG
• 连接 USB 线到 ESP32-S3 的 USB 微口
• 某些开发板可能需要配置 USB D+ 上拉电阻