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 库：
```batch
cargo.bat
```

2. 编译 ESP-IDF 项目：
```batch
idf.cmd build
```

## 烧录到 ESP32-S3

使用以下命令烧录：

```batch
idf.cmd flash
```

或者指定端口：

```batch
idf.cmd -p COM3 flash
```

### 擦除 flash

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

```batch
idf.cmd erase_flash
```

或者指定端口：

```batch
idf.cmd -p COM3 erase_flash
```

## 调试与日志

### 串口监视器

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

```batch
idf.cmd monitor
```

或者指定端口：

```batch
idf.cmd -p COM3 monitor
```

### 烧录并监视

一步完成烧录和监视：

```batch
idf.cmd flash monitor
```

### 退出监视器

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

### 日志级别

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

```c
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 对齐：

```ld
.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+ 上拉电阻