# RemoteMouseOpenCode

**Repository Path**: HFUTZHAO/remote-mouse-open-code

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Remote Mouse (USB Gadget Emulator)

基于 Raspberry Pi Zero 2W 的 USB Gadget 模拟器，模拟 **鼠标 + 键盘 + 1GB U盘**，提供 Web 远程控制。

## 特性

- 🖱️ **HID 鼠标模拟**: 远程控制鼠标移动和点击
- ⌨️ **HID 键盘模拟**: 发送文本和按键事件
- 💾 **U盘模拟**: 1GB FAT32 虚拟磁盘，支持文件读写
- 🌐 **Web 控制界面**: 响应式 Web UI，支持移动设备
- 🔧 **系统服务**: systemd 服务，支持开机自启
- 📊 **实时监控**: 设备状态和日志监控
- 🔒 **可选认证**: 可配置的 Web UI 认证
- 🖐️ **触摸板模式**: 百分比坐标映射，实时光标跟随，支持点击穿透，适配不同屏幕分辨率
- ⚡ **自定义动作序列**: 可视化拖拽创建鼠标/键盘/延时/循环动作，支持绝对/相对坐标，可远程 API 触发

## 自定义动作序列 (Custom Actions)

可视化拖拽创建自动化动作序列，支持以下操作单元：

- 🖱️ **鼠标移动**: 支持绝对坐标 (X, Y) 和相对坐标 (deltaX, deltaY) 两种模式
- 🖱️ **鼠标点击**: 左键、右键、中键，支持单击/双击
- ⌨️ **键盘输入**: 发送任意文本，支持修饰键 (Ctrl, Shift, Alt, Meta)
- ⌨️ **按键按下**: 发送单个按键事件（如 Enter, Tab, Escape）
- ⏱ **延时等待**: 可配置 0-60000ms 延时
- 🔁 **循环**: 重复执行子步骤 1-10000 次

### 快速使用

1. 访问 Web UI → 点击 **Custom Actions** 导航链接
2. 从左侧调色板拖拽动作块到画布
3. 配置每个动作块参数（点击画布上的块）
4. 点击 **Save** 保存序列
5. 点击 **Run** 执行序列

### 远程 API 触发

```bash
# 触发序列执行（需开启认证时需加 -u）
curl -X POST http://<pi-ip>:8080/api/actions/<sequence-id>/run

# 查询执行状态
curl http://<pi-ip>:8080/api/actions/execution/status

# 停止执行
curl -X POST http://<pi-ip>:8080/api/actions/stop
```

所有动作序列通过 JSON 文件持久化存储在 `data/actions/` 目录，服务重启后不丢失。

## 硬件需求

- Raspberry Pi Zero 2W (推荐) 或其他支持 USB OTG 的设备
- USB Micro-B 数据线 (OTG模式，支持数据传输)
- 宿主机 (Windows/Mac/Linux)
- MicroSD 卡 (推荐 16GB+)

## 快速开始

### 1. 系统配置

#### Raspberry Pi OS 配置
```bash
# 编辑 /boot/firmware/config.txt (Pi OS Bookworm+) 或 /boot/config.txt
sudo nano /boot/firmware/config.txt

# 在文件末尾添加:
dtoverlay=dwc2
```

#### 内核模块配置
```bash
# 编辑 /etc/modules 或 /etc/modules-load.d/
echo "dwc2" | sudo tee -a /etc/modules
echo "libcomposite" | sudo tee -a /etc/modules
```

### 2. 部署

```bash
# 克隆项目
git clone <repository-url>
cd remote-mouse-open-code

# 安装依赖
pip3 install -r requirements.txt

# 安装系统服务
sudo make install

# 设置 USB gadget (需要 root 权限)
sudo make gadget-setup
```

### 3. 启动服务

```bash
# 启动服务
sudo systemctl start gadget-emulator

# 查看状态
sudo systemctl status gadget-emulator

# 查看日志
sudo journalctl -u gadget-emulator -f
```

### 4. 访问 Web UI

打开浏览器访问 `http://<raspberry-pi-ip>:8080`

## 配置

编辑 `config/gadget.conf` 自定义设置:

```ini
[hid]
enabled = true
vendor_id = 0x1d6b
product_id = 0x0104
product_name = Remote Mouse

[mass_storage]
enabled = true
disk_image_path = ./data/gadget_disk.img
capacity_mb = 1024

[web]
host = 0.0.0.0
port = 8080
auth_enabled = false
username = admin
password = changeme

[logging]
level = INFO
file_path = logs/gadget.log
```

## Makefile 命令

| 命令 | 说明 |
|------|------|
| `make update` | 更新代码 (git pull) |
| `make install` | 安装 systemd 服务 |
| `make uninstall` | 卸载 systemd 服务 |
| `make start` | 启动服务 |
| `make stop` | 停止服务 |
| `make status` | 查看服务状态 |
| `make logs` | 查看服务日志 |
| `make run` | 直接运行服务 (开发模式，会自动清理冲突，会停止其他实例) |
| `make gadget-setup` | 手动设置 USB gadget |
| `make clean` | 清理 Python 缓存文件 |
| `make clean-all` | 清理所有缓存、日志和镜像文件 |
| `make clean-data` | 清理所有数据 (包括磁盘镜像) |
| `make docs` | 显示 API 文档 |

## 版本管理

Web 页面底部显示版本号、Git 提交哈希和构建时间，定义在 `web/app.py`：

- **版本号** (`VERSION`): 手动定义，大版本更新时修改 `web/app.py` 中的值
- **Git 提交哈希** + **构建时间**: 从 `.git/HEAD` 读取，每次 `git pull` 后自动更新

### 部署流程

1. 在 `dev` 分支开发代码
2. 如需更新版本号，修改 `web/app.py` 中 `VERSION`
3. 提交并推送：`git push origin dev`
4. 设备上拉取并重启：`ssh <pi> 'cd ~/Downloads/remote-mouse-open-code && git pull && sudo systemctl restart gadget-emulator'`
5. 合并到 `master`：`git checkout master && git merge dev && git push origin master`

---

## 硬件接线
1. Pi Zero 2W 通过 USB Micro-B OTG 线连接宿主机
2. 确保已启用 `dtoverlay=dwc2`  
3. 宿主机识别: 鼠标, 键盘, U盘

## 故障排查
| 问题 | 解决 |
|------|------|
| Gadget 不识别 | 检查 dtoverlay=dwc2, 重启 |
| Web 无法访问 | 检查防火墙, 确认 Pi IP |
| 鼠标不动 | 检查 USB OTG 线质量 (需数据线非充电线) |
| 服务无法启动 | `journalctl -u gadget-emulator -f` 查看日志 |
| Device or resource busy | 运行 `sudo make clean-all` 清理冲突配置 |
| 服务启动后立即停止 | 检查日志中的 INVOCATION_ID 环境变量，或手动停止其他实例后重启 |
| dd command failed | 检查磁盘空间，运行 `df -h` 查看可用空间 |
| U盘需要格式化 | Windows 对小容量 U盘有特殊要求，已调整为 1GB 容量 |

## 项目结构
```
remote-mouse-open-code/
├── gadget/           # USB Gadget 核心实现
│   ├── configfs/     # configfs 配置
│   ├── hid/          # HID (鼠标/键盘)
│   └── mass_storage/ # 大容量存储
├── services/         # 服务层
├── web/              # Web UI & API
│   ├── static/       # 静态资源
│   └── templates/    # HTML 模板
├── startup/          # 系统启动配置
├── config/           # 配置文件
├── logs/             # 日志文件
├── scripts/          # 辅助脚本
├── docs/             # 文档
├── specs/            # 功能规格与设计文档
├── .opencode/        # OpenCode 命令定义
├── .specify/         # SpecKit 模板与记忆
├── main.py           # 服务入口
├── Makefile          # 构建/部署/管理命令
└── requirements.txt  # Python 依赖
```

## 许可证
[待定]