# esp32s2-vmk

**Repository Path**: Deffece/esp32s2-vmk

## Basic Information

- **Project Name**: esp32s2-vmk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-08
- **Last Updated**: 2026-01-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP32 TinyUSB HID 设备项目

这是一个基于 ESP32 的 TinyUSB HID（Human Interface Device）设备项目，通过 WiFi 和 UDP 协议实现远程控制键盘、鼠标操作以及 LED 灯光控制。

## 功能特点

- **USB HID 设备模拟**：模拟键盘和鼠标设备，可通过 USB 连接到计算机
- **WiFi 远程控制**：通过 WiFi 连接到网络，监听 UDP 端口接收控制指令
- **多类型指令支持**：支持键盘按键、鼠标移动、鼠标点击和 LED 控制指令
- **LED 控制功能**：支持固定亮度和呼吸灯两种模式
- **简单的指令格式**：使用简单的字符串指令格式，便于集成和扩展

## 硬件需求

- ESP32-S2/S3 开发板（支持 USB OTG 功能）
- 计算机或其他支持 USB HID 设备的主机
- 可选：LED 灯（用于演示灯光控制功能）

## 软件需求

- ESP-IDF 5.x 或更高版本
- Python 3.7+（用于构建和烧录）
- 支持 UDP 通信的客户端软件（如 Python 脚本、网络调试工具等）

## 安装和配置

### 1. 克隆项目

```bash
git clone <项目仓库地址>
cd tusb_hid
```

### 2. 配置 WiFi 参数

编辑 `main/tusb_hid_example_main.c` 文件，修改以下 WiFi 配置参数：

```c
#define WIFI_SSID      "your_wifi_ssid"  // 修改为您的WiFi名称
#define WIFI_PASS      "your_wifi_password"  // 修改为您的WiFi密码
#define UDP_PORT       3333              // UDP监听端口（可选修改）
```

### 3. 构建和烧录

使用 ESP-IDF 工具构建和烧录项目：

```bash
idf.py set-target esp32s3  # 根据您的开发板型号选择目标
idf.py build
idf.py flash monitor
```

## 使用方法

### 1. 设备连接

1. 将 ESP32 开发板通过 USB 连接到计算机
2. 计算机将识别出一个新的 HID 设备（键盘和鼠标）
3. 设备将自动连接到配置的 WiFi 网络

### 2. 发送 UDP 指令

通过 UDP 协议向设备发送控制指令，设备默认监听端口为 3333。

#### 键盘指令

格式：`KEY:<keycode>`

示例：
```
KEY:4  # 发送 A 键（keycode 4 = 'a'）
KEY:5  # 发送 B 键（keycode 5 = 'b'）
```

#### 鼠标移动指令

格式：`MOUSE_MOVE:<delta_x>,<delta_y>`

示例：
```
MOUSE_MOVE:10,10  # 向右下方移动鼠标
MOUSE_MOVE:-5,0   # 向左移动鼠标
```

#### 鼠标点击指令

格式：`MOUSE_CLICK:<button>`

示例：
```
MOUSE_CLICK:1  # 左键点击
MOUSE_CLICK:2  # 右键点击
MOUSE_CLICK:4  # 中键点击
```

#### LED 控制指令

格式：`LED:<brightness>,<mode>`

- `brightness`：0-255（亮度值）
- `mode`：0（固定亮度）或 1（呼吸灯模式）

示例：
```
LED:128,0  # 设置固定亮度为 128
LED:0,1    # 开启呼吸灯模式
```

### 3. 示例客户端代码

以下是一个简单的 Python 客户端示例，用于发送 UDP 指令：

```python
import socket

# 设备的 IP 地址和端口号
DEVICE_IP = "192.168.1.100"  # 替换为您的设备 IP
UDP_PORT = 3333

# 创建 UDP 套接字
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

# 发送键盘指令
sock.sendto(b"KEY:4", (DEVICE_IP, UDP_PORT))
print("发送了 'a' 键指令")

# 发送鼠标移动指令
sock.sendto(b"MOUSE_MOVE:10,10", (DEVICE_IP, UDP_PORT))
print("发送了鼠标移动指令")

# 发送 LED 控制指令
sock.sendto(b"LED:128,0", (DEVICE_IP, UDP_PORT))
print("发送了 LED 控制指令")

# 关闭套接字
sock.close()
```

## 代码结构说明

### 主要文件

- `main/tusb_hid_example_main.c`：主应用程序文件，包含所有功能实现
- `README.md`：项目说明文档
- `sdkconfig`：ESP-IDF 配置文件

### 核心功能模块

1. **USB HID 设备实现**：
   - HID 描述符定义
   - TinyUSB 驱动初始化
   - HID 报告发送函数

2. **WiFi 和 UDP 通信**：
   - WiFi 连接初始化
   - UDP 服务器监听
   - 指令解析和处理

3. **LED 控制**：
   - PWM 初始化和控制
   - 固定亮度和呼吸灯模式实现

4. **HID 指令处理**：
   - 键盘指令处理
   - 鼠标指令处理
   - LED 指令处理

## 注意事项

1. **USB 设备识别**：确保您的计算机支持 HID 设备，部分系统可能需要额外的驱动程序

2. **WiFi 连接**：设备将自动尝试连接到配置的 WiFi 网络，如果连接失败，将每 5 秒重试一次

3. **指令格式**：请严格按照指定的指令格式发送 UDP 数据包，否则设备可能无法正确解析

4. **LED 硬件**：如果您要使用 LED 控制功能，请确保正确连接 LED 到 ESP32 的 GPIO 3 引脚

5. **电源供应**：某些 ESP32 开发板可能需要额外的电源供应，特别是在连接 USB 设备时

## 扩展建议

1. **增加更多 HID 设备类型**：可以扩展支持触摸板、游戏控制器等其他 HID 设备类型

2. **实现加密通信**：为 UDP 通信添加加密功能，提高安全性

3. **添加 Web 界面**：实现一个简单的 Web 界面，方便用户配置和控制设备

4. **增加传感器支持**：可以添加传感器（如加速度计）来实现更丰富的交互方式

## 许可证

本项目基于 Espressif Systems 的示例代码修改，遵循相同的许可证条款。

## 贡献

欢迎提交 Issue 和 Pull Request 来改进项目！
| Supported Targets | ESP32-P4 | ESP32-S2 | ESP32-S3 |
| ----------------- | -------- | -------- | -------- |

# TinyUSB Human Interface Device Example

(See the README.md file in the upper level 'examples' directory for more information about examples.)

Human interface devices (HID) are one of the most common USB devices, it is implemented in various devices such as keyboards, mice, game controllers, sensors and alphanumeric display devices.
In this example, we implement USB keyboard and mouse.
Upon connection to USB host (PC), the example application will sent 'key a/A pressed & released' events and move mouse in a square trajectory. To send these HID reports again, press the BOOT button, that is present on most ESP development boards (GPIO0).

As a USB stack, a TinyUSB component is used.

## How to use example

### Hardware Required

Any ESP board that have USB-OTG supported.

#### Pin Assignment

_Note:_ In case your board doesn't have micro-USB connector connected to USB-OTG peripheral, you may have to DIY a cable and connect **D+** and **D-** to the pins listed below.

See common pin assignments for USB Device examples from [upper level](../../README.md#common-pin-assignments).

Boot signal (GPIO0) is used to send HID reports to USB host.

### Build and Flash

Build the project and flash it to the board, then run monitor tool to view serial output:

```bash
idf.py -p PORT flash monitor
```

(Replace PORT with the name of the serial port to use.)

(To exit the serial monitor, type ``Ctrl-]``.)

See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.

## Example Output

After the flashing you should see the output at idf monitor:

```
I (290) cpu_start: Starting scheduler on PRO CPU.
I (0) cpu_start: Starting scheduler on APP CPU.
I (310) example: USB initialization
I (310) tusb_desc:
┌─────────────────────────────────┐
│  USB Device Descriptor Summary  │
├───────────────────┬─────────────┤
│bDeviceClass       │ 0           │
├───────────────────┼─────────────┤
│bDeviceSubClass    │ 0           │
├───────────────────┼─────────────┤
│bDeviceProtocol    │ 0           │
├───────────────────┼─────────────┤
│bMaxPacketSize0    │ 64          │
├───────────────────┼─────────────┤
│idVendor           │ 0x303a      │
├───────────────────┼─────────────┤
│idProduct          │ 0x4004      │
├───────────────────┼─────────────┤
│bcdDevice          │ 0x100       │
├───────────────────┼─────────────┤
│iManufacturer      │ 0x1         │
├───────────────────┼─────────────┤
│iProduct           │ 0x2         │
├───────────────────┼─────────────┤
│iSerialNumber      │ 0x3         │
├───────────────────┼─────────────┤
│bNumConfigurations │ 0x1         │
└───────────────────┴─────────────┘
I (480) TinyUSB: TinyUSB Driver installed
I (480) example: USB initialization DONE
I (2490) example: Sending Keyboard report
I (3040) example: Sending Mouse report
```