# SerialKeyBoard

**Repository Path**: PengLinCode/serial-key-board

## Basic Information

- **Project Name**: SerialKeyBoard
- **Description**: 用程序控制键盘输入
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Raspberry Pi Pico USB 键盘模拟工具

基于 Raspberry Pi RP2040 开发的系统工具，通过 USB 串口接收指令，模拟本地物理键盘输出。
适用于自动化输入 PIN 码、密码、固定文本等场景——Pico 同时呈现为 **USB HID 键盘** 与 **USB CDC 串口**，
PC 端通过串口下发命令，Pico 按指令执行键盘输出并返回结果。

## 硬件要求

| 项目 | 说明 |
|------|------|
| 开发板 | Raspberry Pi Pico (RP2040) |
| Bootloader | UF2 Bootloader v3.0, Board-ID: RPI-RP2 |
| 固件环境 | CircuitPython 10.x (原生支持 USB HID + CDC，兼容 MicroPython 语法) |
| 连接方式 | 单根 USB 线同时承载 串口(CDC) + 键盘(HID) |
| 固件烧录盘 | 将 UF2 拖入 Pico 的 BOOTSEL 大容量存储盘 (如 E:) |

## 项目结构

```
pythonPI/
├── firmware/                 # Pico 端固件代码 (CircuitPython / MicroPython 兼容)
│   ├── code.py              # 主程序 (CircuitPython 入口)
│   ├── main.py              # 主程序 (MicroPython 入口，内容同 code.py)
│   ├── usb_keyboard.py      # USB HID 键盘封装库 (双平台兼容)
│   ├── presets.py           # 预置字符串配置 (PIN/密码等)
│   └── *.uf2                # 固件 UF2 文件 (CircuitPython / MicroPython)
├── client/                  # PC 端 Python 客户端
│   ├── pico_client.py       # 串口通信库
│   └── example.py           # 使用示例
├── docs/                    # 文档目录
├── flash_tool.py            # 一键烧录部署工具
├── requirements.txt         # Python 客户端依赖
└── README.md
```

## 快速开始

### 一键烧录部署 (推荐)

```bash
python flash_tool.py
```

工具自动完成全部流程：检测设备 → 烧录固件 → 部署代码 → 验证通信。

- 若 Pico 未进入 BOOTSEL 模式，工具会提示操作步骤并等待
- 若 Pico 已运行 CircuitPython，自动跳过固件烧录，仅更新代码
- 若本地无固件 UF2 文件，自动从 CircuitPython 官网下载

可选参数:
- `--code-only` : 仅更新代码，跳过固件烧录
- `--no-verify` : 跳过通信验证
- `--version 10.3.0` : 指定 CircuitPython 版本

---

### 手动步骤

### 第一步：烧录 CircuitPython 固件

> **为什么用 CircuitPython？** MicroPython 官方固件未启用 `machine.USBHID`，
> 无法模拟 USB 键盘。CircuitPython 是 MicroPython 的超集，语法兼容，
> 且原生支持 `usb_hid` (键盘) + `usb_cdc` (串口) 双设备。

1. 从 CircuitPython 官方下载页获取 Raspberry Pi Pico 固件 (UF2 格式)：
   https://circuitpython.org/board/raspberry_pi_pico/
   > 推荐最新稳定版 (本项目已测试 10.2.1)。

2. 按住 Pico 的 **BOOTSEL** 按钮，将 Pico 通过 USB 接入电脑。
3. Pico 会枚举为大容量存储设备 (即你的 **E:** 盘)。
4. 将下载的 UF2 固件文件拖入 E: 盘，Pico 自动重启，进入 CircuitPython。
5. Pico 重新枚举为名为 **CIRCUITPY** 的大容量存储设备 (如 E:)。

### 第二步：上传项目代码到 Pico

CircuitPython 的 CIRCUITPY 驱动器如同 U 盘，直接复制文件即可：

```bash
# 将 firmware/ 下的三个 .py 文件复制到 CIRCUITPY 驱动器 (如 E:)
copy firmware\code.py           E:\
copy firmware\usb_keyboard.py   E:\
copy firmware\presets.py        E:\
```

复制完成后，CircuitPython 自动检测文件变化并重新运行 `code.py`，
USB HID 键盘与串口同时就绪。

> 也可在文件管理器中直接拖拽文件到 CIRCUITPY 驱动器。

### 第三步：安装 PC 端客户端依赖

```bash
pip install -r requirements.txt
```

### 第四步：运行示例

```bash
cd client
python example.py
```

示例会自动检测 Pico 串口并演示文本输入、预置字符串、特殊按键、组合键等功能。

## 命令协议

PC 端通过串口发送命令 (以 `\n` 结尾)，Pico 执行后返回单行响应。

### 请求命令

| 命令 | 说明 | 示例 |
|------|------|------|
| `TEXT:<文本>` | 原始输出指令：输入文本，自动处理大小写与符号 | `TEXT:Hello World!` |
| `RAW:<键码hex>` | 发送原始 HID 键码 (无修饰键) | `RAW:28` (Enter) |
| `RAW:<修饰hex>:<键码hex>` | 带修饰键的原始键码 | `RAW:02:04` (Shift+A = A) |
| `PRESET:<名称>` | 预置字符串指令：输出固件中预定义的字符串 | `PRESET:PASSWORD` |
| `KEY:<按键名>` | 按下特殊按键，支持 `+` 组合 | `KEY:CTRL+ALT+DELETE` |
| `DELAY:<毫秒>` | 延时等待 | `DELAY:500` |
| `PING` | 心跳检测 | `PING` |
| `HELP` | 获取命令列表 | `HELP` |
| `LIST` | 列出所有预置字符串名称 | `LIST` |

### 响应格式

| 响应 | 说明 |
|------|------|
| `OK` | 成功 |
| `OK:<数据>` | 成功并附带数据 (如 `OK:typed=12,skipped=0`) |
| `ERROR:<消息>` | 失败并附带错误信息 |
| `PONG` | 心跳响应 |

### 支持的特殊按键名

```
ENTER  ESC  BACKSPACE  TAB  SPACE  CAPSLOCK
F1-F12  INSERT  DELETE  HOME  END  PAGEUP  PAGEDOWN
UP  DOWN  LEFT  RIGHT  PRINTSCREEN  SCROLLLOCK  PAUSE  NUMLOCK
```

修饰键：`CTRL` `SHIFT` `ALT` `GUI`(Win/Meta)，可用 `+` 组合，如 `CTRL+SHIFT+HOME`。

## Python 客户端 API

```python
from pico_client import PicoKeyboard

with PicoKeyboard() as kb:               # 自动检测并连接
    kb.ping()                            # 心跳检测
    kb.type_text("Hello World!")         # 输入文本
    kb.tap_key("ENTER")                  # 按回车
    kb.send_preset("PASSWORD")           # 输出预置密码
    kb.tap_key("CTRL+ALT+DELETE")        # 三键组合
    kb.send_raw(0x04, modifier=0x02)     # 原始键码: Shift+A
    kb.delay(500)                        # 延时 500ms
    kb.list_presets()                    # 获取预置列表

    # 便捷组合
    kb.type_and_enter("user@test.com")   # 输入文本并回车
    kb.login(username="admin",           # 登录流程
             password_preset="PASSWORD")
```

手动指定串口端口：

```python
kb = PicoKeyboard(port="COM3")           # Windows
kb = PicoKeyboard(port="/dev/ttyACM0")   # Linux
```

## 自定义预置字符串

编辑 `firmware/presets.py`，在 `PRESETS` 字典中添加或修改：

```python
PRESETS = {
    "HELLO": "Hello",
    "PIN": "123456",
    "PASSWORD": "P@ssw0rd!",
    "MY_PIN": "987654",        # 新增
}
```

修改后重新上传 `presets.py` 到 Pico 即可生效。

> **安全提示**：预置敏感信息以明文存储于固件中。生产环境建议仅保留非敏感模板，
> 敏感值通过 `TEXT` 命令实时下发，用后即弃。

## 工作原理

```
  ┌──────────┐    串口命令     ┌───────────────────┐    USB HID 报告    ┌─────────┐
  │  PC 端   │ ──────────────> │  Pico (RP2040)    │ ────────────────> │ 目标主机 │
  │ Python   │   (USB CDC)     │  code.py 解析命令  │   (键盘报告)      │ (接收键盘 │
  │ 客户端   │ <────────────── │  驱动 usb_hid 输出 │ <──────────────── │  输入)   │
  └──────────┘    响应结果     └───────────────────┘                   └─────────┘
```

Pico 通过单根 USB 线同时呈现两个设备：
- **USB CDC 串口** — 接收 PC 端 Python 客户端的命令
- **USB HID 键盘** — 向目标主机发送按键报告

## 常见问题

**Q: 为什么使用 CircuitPython 而非 MicroPython？**
A: MicroPython 官方 RP2040 固件未启用 `machine.USBHID`，无法模拟 USB 键盘。
   CircuitPython 原生支持 `usb_hid` + `usb_cdc`，且语法与 MicroPython 兼容。
   代码已做双平台兼容设计，若使用含 USBHID 的自定义 MicroPython 固件亦可运行。

**Q: 客户端提示"未找到 Pico 设备"？**
A: 手动指定端口：`PicoKeyboard(port="COM4")`。可在设备管理器中确认 Pico 的 COM 号。

**Q: 键盘输出有乱码或漏字？**
A: 调整按键间隔延时，在 `usb_keyboard.py` 中增大 `default_delay_ms` (默认 12ms)。

**Q: 如何进入 CircuitPython REPL？**
A: 用串口终端 (如 PuTTY) 连接 Pico 的 COM 端口，按 `Ctrl+C` 可中断 `code.py` 进入 REPL。

**Q: 支持中文输入吗？**
A: USB HID 键盘基于 ASCII 字符映射，不直接支持中文。中文需通过目标系统的输入法处理。

## 参考文档

- Raspberry Pi 官方微控制器文档: https://www.raspberrypi.com/documentation/microcontrollers/
- CircuitPython (Raspberry Pi Pico): https://circuitpython.org/board/raspberry_pi_pico/
- CircuitPython usb_hid 文档: https://docs.circuitpython.org/en/latest/shared-bindings/usb_hid/
- MicroPython RP2040 文档: https://docs.micropython.org/en/latest/rp2/
- USB HID Usage Table: https://usb.org/document-library/hid-usage-tables-12