# HID

**Repository Path**: FANKYT/hid

## Basic Information

- **Project Name**: HID
- **Description**: 自定义动态HID协议
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-05-24
- **Last Updated**: 2025-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HID_BOX

HID_BOX 是一个强大的 USB HID 设备透传和模拟工具库，基于 Linux USB Gadget 实现。它可以将物理 HID 设备（如鼠标、键盘）透传到目标系统，也可以创建自定义的虚拟 HID 设备。

## 功能特性

### 1. 动态 HID 设备配置
- **自动检测模式**：自动检测并解析接入的 HID 设备信息
- **自定义配置模式**：完全自定义设备特征（VID/PID/制造商/产品名/报告描述符）
- 支持从物理设备克隆配置

### 2. USB HID 透传
- 完整的 HID 设备透传功能
- 支持复合设备（多接口/多端点）
- 低延迟数据转发
- 实时输入数据回调

### 3. 自定义设备模拟
- 预定义的鼠标报告描述符模板
  - 标准 3 键鼠标
  - 5 键带滚轮鼠标
  - 高精度游戏鼠标（16位坐标）
- 灵活的自定义报告描述符构建器
- 支持通过 OTG 接口连接到 PC 进行模拟输入

### 4. 架构设计
```
HIDDeviceManager
├── UsbGadget         # USB Gadget 配置和管理
├── InputHIDDevice    # 从物理设备读取输入
└── OutputHIDDevice   # 向虚拟设备写入输出
```

## 系统要求

- **操作系统**：Linux (内核支持 USB Gadget)
- **硬件**：支持 USB OTG/Device 模式的设备（如 RK3588）
- **权限**：需要 root 权限运行
- **依赖**：
  - CMake >= 3.15
  - C++20 编译器
  - libusb-1.0
  - libusbgx (USB Gadget Configfs 库)
  - fmt (格式化库)
  - hid-rp (HID 报告描述符解析库)

## 构建项目

```bash
# 创建构建目录
mkdir build && cd build

# 配置项目
cmake ..

# 编译
cmake --build .

# 安装（可选）
sudo cmake --install .
```

## 使用示例

### 示例 1：HID 设备透传

将物理 USB 鼠标透传到目标 PC：

```cpp
#include "hidbox/hid_device_manager.h"

using namespace hidbox;

int main() {
    HIDDeviceManager manager;

    // 配置自动检测模式
    HIDDeviceConfig config;
    config.auto_detect = true;
    config.input_identifier.vid = 0x046d;  // 罗技鼠标
    config.input_identifier.pid = 0xc52b;

    manager.Configure(config);
    manager.StartPassthrough();

    // 保持运行...
    while (true) {
        std::this_thread::sleep_for(std::chrono::seconds(1));
    }

    return 0;
}
```

### 示例 2：自定义虚拟鼠标

创建自定义虚拟鼠标设备：

```cpp
#include "hidbox/hid_device_manager.h"
#include "hidbox/mouse_descriptor_builder.h"

using namespace hidbox;

int main() {
    HIDDeviceManager manager;

    // 配置自定义鼠标
    HIDDeviceConfig config;
    config.auto_detect = false;
    config.custom.vendor_id = 0x1234;
    config.custom.product_id = 0x5678;
    config.custom.manufacturer = "MyCompany";
    config.custom.product = "Custom Mouse";

    // 使用预定义的鼠标描述符
    config.custom.report_descriptor =
        MouseDescriptorBuilder::BuildMouseWithWheel();

    manager.Configure(config);

    // 发送鼠标移动
    MouseReport report{};
    report.x = 10;  // 向右移动 10 像素
    report.y = 5;   // 向下移动 5 像素
    report.buttons = 0x01;  // 左键按下

    manager.WriteToOutput(&report, sizeof(report));

    return 0;
}
```

### 示例 3：自定义报告描述符

创建完全自定义的 HID 设备：

```cpp
auto custom_descriptor = MouseDescriptorBuilder::BuildCustomMouse(
    8,      // 8 个按键
    true,   // 包含滚轮
    true    // 使用高精度 16 位坐标
);

HIDDeviceConfig config;
config.auto_detect = false;
config.custom.report_descriptor = custom_descriptor;
config.custom.vendor_id = 0x1234;
config.custom.product_id = 0xabcd;

manager.Configure(config);
```

## 运行示例程序

项目包含两个示例程序：

### 1. 透传示例

```bash
# 编译后运行
sudo ./build/src/examples/passthrough_example

# 该程序会自动检测第一个 HID 设备并进行透传
```

### 2. 自定义鼠标示例

```bash
# 编译后运行
sudo ./build/src/examples/custom_mouse_example

# 该程序会创建一个虚拟鼠标，并在屏幕上画圆形移动轨迹
```

## API 文档

### HIDDeviceManager

主要的设备管理类。

#### 方法

- `void Configure(const HIDDeviceConfig& config)` - 配置 HID 设备
- `void StartPassthrough()` - 启动透传模式
- `void StopPassthrough()` - 停止透传模式
- `ssize_t WriteToOutput(const void* data, size_t size)` - 写入数据到虚拟设备
- `void SetInputCallback(std::function<void(u8*, u32)> callback)` - 设置输入回调

### HIDDeviceConfig

设备配置结构体。

#### 字段

- `bool auto_detect` - 是否自动检测设备
- `HIDDeviceIdentifier input_identifier` - 输入设备标识符（VID/PID）
- `CustomConfig custom` - 自定义配置（当 auto_detect = false）
- `std::string gadget_name` - Gadget 名称
- `u32 hid_number` - HID 设备编号（/dev/hidgN）

### MouseDescriptorBuilder

鼠标报告描述符构建器。

#### 静态方法

- `BuildStandardMouse()` - 标准 3 键鼠标
- `BuildMouseWithWheel()` - 5 键带滚轮鼠标
- `BuildGamingMouse()` - 高精度游戏鼠标
- `BuildCustomMouse(num_buttons, has_wheel, high_precision)` - 自定义鼠标

## 配置 USB Gadget

在运行程序之前，确保系统支持 USB Gadget：

```bash
# 检查 configfs 是否挂载
ls /sys/kernel/config

# 如果没有挂载，执行：
sudo mount -t configfs none /sys/kernel/config

# 加载必要的内核模块
sudo modprobe libcomposite
sudo modprobe usb_f_hid
```

## 故障排除

### 错误：Permission denied

确保以 root 权限运行：
```bash
sudo ./your_program
```

### 错误：USB device not found

- 检查设备是否已连接
- 确认 VID/PID 是否正确
- 尝试 `lsusb` 查看设备列表

### 错误：Gadget already exists

删除现有的 Gadget：
```bash
sudo rm -rf /sys/kernel/config/usb_gadget/hidbox
```

或在代码中调用：
```cpp
manager.GetUsbGadget()->RemoveGadgets();
```

## 许可证

本项目基于原 AiBox 项目的 HID 模块抽离而来，保留原有代码风格和架构设计。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 技术支持

如有问题，请在 GitHub 上提交 Issue。