快速开始

按顺序完成：刷固件 → 连接设备 → 进入配置面板 → 配置映射 → 开始使用。不同硬件在对应步骤中选择自己的接法即可。

你需要准备

定制硬件（推荐）

群友定制的 RP2350A 键鼠映射板：板载键鼠主机口、GPIO8 扩展 USB 主机口，以及 MAKCU 串口的 USB 转串口（连电脑免焊接、免 USB-TTL 适配器）。固件刷写方式与微雪板完全一致。另需两根 USB 数据线：一根连手机，一根连 PC（或充电器）。

👉 【闲鱼】自制 RP2350A 键鼠映射硬件板

微雪 RP2350-USB-C（DIY）

物品	用途
微雪 RP2350-USB-C 开发板	目标板，自带双 USB-C 口（也可使用 RP2350 开发板自行焊接）
USB 数据线 ×2	连接手机、电脑或拓展坞
CH334 USB 2.0 拓展坞	Host 模式直连键鼠（其他型号不保证兼容）
USB 转串口（可选）	连接 GPIO2/3，用于 MAKCU 串口控制
安卓手机 / iPhone / iPad	目标平台

蓝牙版

微雪 RP2350-Plus-W，或树莓派 PICO 2 W（USB-C 版）+ 串联 C 口电阻。适合使用 DS5 等蓝牙手柄直连的场景；蓝牙版没有 PIO 口，不能接 USB 键鼠或使用 PIO 上位机控制。

第一步：刷入固件

1. 按住板子上的 BOOTSEL 按钮（白色小按钮）
2. 保持按住，用 USB 线将 原生 Type-C 口 连接到电脑
3. 松开 BOOTSEL → 电脑出现名为 RP2350 的 U 盘
4. 用 Chrome / Edge 打开 固件烧录网站，按板型选择固件（默认板选「稳定版」，蓝牙板选「稳定版 · Pico 2 W（蓝牙）」或「稳定版 · Waveshare（蓝牙）」）

稳定版固件会自动适配安卓 / 苹果，无需单独选择 iOS 固件。后续固件升级重复此步骤即可覆盖。

第二步：连接设备

定制硬件

1. Type-C 口（标有手机插口）连接手机；串口口连接 PC 或充电器。先接入的一侧会为开发板与 USB-A 口供电。
2. USB-A 两个口分别连接键盘、鼠标或手柄。
3. PIO 工作模式在第四步设为 Host；该板自带 USB 转串口，上位机通过串口（MAKCU 协议）控制，无需 Device 模式。

微雪 RP2350-USB-C

按使用方式接线（PIO 工作模式同样在第四步设置）：

使用方式	接线
上位机控制（Device 模式）	原生 Type-C 口 → 手机；PIO-USB-C 口 → 电脑
直连键鼠（Host 模式，默认）	原生 Type-C 口 → 手机；PIO-USB-C 口 → CH334 拓展坞 → 键鼠

部分主机可能把设备显示为 DualSense 手柄，属正常现象；USB 网卡（ECM） 会自动识别。

蓝牙版

1. 原生 Type-C 口连接手机，开发板灯光闪烁。
2. 初次配对手柄：长按 PS + △ / ○ / × / □ 直到灯光闪烁，手柄会自动配对；之后点按 PS 即可自动回连。

第三步：进入配置面板

设备通过原生 USB 口提供 USB 网卡（ECM），固定 IP 为 192.168.73.1。安卓和苹果的主要差异如下；苹果还需要完成下方的「苹果设备前置设置」，其余配置步骤完全一致：

平台	访问地址	光标
安卓	用 vPointer 端口转发后打开 http://127.0.0.1:8000	虚拟光标（vPointer）
苹果（iPhone / iPad）	Safari 直接打开 http://192.168.73.1/，不影响 Wi-Fi 上网	系统原生鼠标 / 触控板（无需额外 App）

设备默认自动识别安卓 / 苹果，插上即可使用；如果曾手动固定过平台，可在「PICO 配置 → 目标平台」改回「自动」。

苹果设备前置设置

iPhone / iPad 使用前，先在系统设置里完成以下项目：

iPadOS

设置 → 辅助功能 → 缩放：打开

设置 → 多任务与手势：选择「全屏幕 App」，关闭「四指与五指 App 切换」和「高效手势」

iOS

设置 → 辅助功能 → 缩放：打开

设置 → 辅助功能 → 触控 → 辅助触控：打开

打开「辅助触控」后，把 Pico 接到 iPhone，再在「辅助触控 → 指针设备 → 设备」里选择它。

出现放大镜：三指点击一下即可恢复。

方向设置：苹果不能自动检测方向。触控方向不对时，在「PICO 配置 → 屏幕旋转方向」或「参数配置 → 旋转 → 屏幕旋转方向」手动选择 0° / 90° / 180° / 270°；鼠标方向不对时，在「参数配置 → 旋转 → 鼠标旋转方向」调整。

安卓：vPointer 端口转发

vPointer 是配套的 Android 应用，提供两个核心功能：

• 虚拟光标 — 在手机屏幕上显示鼠标光标，通过 TCP/UDP 接收 Pico 发送的光标坐标
• 端口转发 — 将 Pico 的 Web 配置面板（192.168.73.1:80）转发到手机本地端口 8000，正常联网时也能通过 http://127.0.0.1:8000 访问

网络限制：安卓系统会限制应用直接访问这块 USB 网卡，浏览器通常打不开 192.168.73.1。vPointer 的端口转发会解决这个问题：它把 Pico 的 80 端口映射到手机本地 127.0.0.1:8000，并自动把 Socket 绑定到 USB 网卡，无需手动断网。

使用前授权：授予悬浮窗权限，关闭后台优化与电池优化，并允许 vPointer 持续后台运行。

打开 vPointer，切换到「端口转发」Tab 并点击启动，之后可以通过以下方式访问配置面板：

• 手机浏览器 — 打开 http://127.0.0.1:8000
• 同局域网设备 — 打开 http://<手机IP>:8000（手机需保持 Wi-Fi 连接）

OBS：融合器光标（直播叠加）

想在直播/录屏画面里显示鼠标光标，可以不用任何 app：「参数配置 → 光标显示方式」选 融合器光标，然后在 OBS 里：

1. 添加浏览器源，地址填 http://192.168.73.1/#cursor（与设备同一局域网的电脑均可打开）
2. 给该浏览器源加色键（Chroma Key）滤镜，选绿色——页面是纯绿幕，抠掉后只剩一个箭头指针
3. 把浏览器源拖到游戏采集画面之上、调整到与游戏画面重合即可；按下鼠标时指针会缩小提示

背景色可用 ?color=十六进制 自定义（如 #cursor?color=7FFF5a，支持 3/6 位、可带 #）， 缺省纯绿；面板「设备」分页的「黑幕光标」入口打开黑色背景（#cursor?color=000000）， 直接叠加无需抠像。指针位置与触屏落点同坐标系（外接显示器的黑边缩放已含在内），页面任意 分辨率自适应；光标隐藏（如关闭映射）时页面只剩纯背景，色键后即完全透明。浏览器源断线时 左下角会出现一行提示文字，重连后消失。

添加到主屏幕（可选）

配置面板可以安装到手机 / 平板主屏，之后像 App 一样全屏打开（没有浏览器地址栏，也没有标签页）：

• 苹果（Safari） — 打开 http://192.168.73.1/ → 分享 → 「添加到主屏幕」
• 安卓（Chrome） — 用 vPointer 转发后的 http://127.0.0.1:8000 打开面板 → 右上菜单 → 「安装应用 / 添加到主屏幕」

浏览器只把 http://127.0.0.1 和 https:// 当作「安全来源」。安卓直接打开 http://192.168.73.1 时只会生成普通快捷方式（点击后仍在浏览器标签页里打开）；iOS 不受此限制。

安卓端安装后仍需 vPointer 保持运行；苹果端只要 Pico 保持连接。面板不会离线缓存，它显示的永远是设备上的当前状态；首次安装需要联网获取图标。

touch_forwarder 触屏转发

touch_forwarder 运行在安卓手机上，可实现手搓与开发板共同工作不冲突

安装

adb 连接PC后，在PC的终端执行：

curl.exe -fL --retry 3 -o touch_forwarder_arm64 "https://1833788059.cdn.123clouddisk.com/1833788059/direct/projects/touch_forwarder/touch_forwarder_arm64"
adb push touch_forwarder_arm64 /data/local/tmp/touch_forwarder_arm64
adb shell chmod 755 /data/local/tmp/touch_forwarder_arm64

测试运行

adb shell /data/local/tmp/touch_forwarder_arm64

看到「监听 :6532，等待客户端…」即工作正常，此时插入开发板即可手搓不冲突。

后台运行

测试正常后，按 Ctrl+C 退出，使用如下命令进入后台运行，之后PC可断开，保持usb调试开启即可：

adb shell /data/local/tmp/touch_forwarder_arm64 start

• 程序脱离终端持续运行：关掉 cmd 窗口、拔掉 USB 线都不影响
• 只有 stop、手机重启或系统强杀会让它停下；手机重启后重新执行一次 start 即可

管理命令

adb shell /data/local/tmp/touch_forwarder_arm64 status    # 运行状态：pid、已运行时长、日志大小
adb shell /data/local/tmp/touch_forwarder_arm64 logf      # 实时查看日志（Ctrl+C 只退出查看）
adb shell /data/local/tmp/touch_forwarder_arm64 log 200   # 最近 200 行（默认 50 行）
adb shell /data/local/tmp/touch_forwarder_arm64 restart   # 重启
adb shell /data/local/tmp/touch_forwarder_arm64 stop      # 停止

第四步：配置设备与映射

进入配置面板后，先完成设备级设置，再编辑按键映射。

设置 PIO 工作模式

打开 「PICO 配置」→「PIO 工作模式」，按接线方式选择（切换后设备自动重启生效）：

使用方式	PIO 工作模式	说明
上位机控制（微雪板）	Device	电脑通过 WebHID 工具（Chrome / Edge）发送键鼠报文
直连键鼠（微雪板）	Host（默认）	经 CH334 拓展坞连接键鼠
定制硬件	Host	上位机通过板载 USB 转串口（MAKCU 协议）控制

Host 模式支持普通键盘、鼠标以及 NKRO 全键无冲键盘。

未激活设备也可切换 Host 做基础输入测试：键盘 WASD 与飘号键，鼠标 X/Y、左键和中键，手柄 Select/RS/RT 按键、左右摇杆和 RT 模拟量。蓝牙 DS5 使用相同手柄白名单。其它输入需激活，详见基础输入测试和第六步「普通版 vs 高级版」。

校准屏幕与旋转方向

1. 上传游戏截图 — 作为映射参考背景，用来校准屏幕坐标，否则虚拟光标的位置会错乱。
2. 检查方向 — 安卓一般保持「自动」；苹果不能自动检测，按第三步「苹果设备前置设置」手动设置屏幕与鼠标方向。

编辑并保存映射

1. 点击屏幕对应位置放置触摸点，再按一下要绑定的键即可完成映射（也支持点选鼠标 / 手柄按键）。
2. 触摸点可拖动调整位置；选中触点后滚动滚轮可调整作用半径。
3. 确认无误后，点击底部的「保存」写入当前槽位并应用配置。

💡 快捷切换槽位：Pico 最多支持 9 个配置槽位，按「修饰键 + 数字行 1~9」可在槽位间快速切换（修饰键默认左 Alt，可在「参数配置」里改成其它按键）。

详细说明见：映射配置说明

第五步：开始使用

• ✅ 固件已刷入
• ✅ 设备已连接
• ✅ 配置已保存

1. 移动鼠标 → 安卓屏幕上出现 虚拟光标（vPointer）；苹果由系统显示 鼠标 / 触控板
2. 按下 ` 键（ESC 下方，KEY_GRAVE）或鼠标中键（默认配置）→ 切换至映射模式，键鼠操作开始生效
3. 需要核对触点落点时，点击顶栏的「触控预览」，在实机上查看触摸位置

第六步：普通版 vs 高级版

固件未激活时部分功能受限，激活后解锁完整输入与高级能力。

激活流程：打开「PICO 配置 → 设备授权」，把「设备序列号」发给作者，获取激活码粘贴后点「激活」，验证通过立即生效，无需重启。激活码与硬件绑定，不能跨设备使用；

激活码固化在芯片 OTP 中，恢复出厂设置不会使激活失效，无需重新激活（旧固件升级后首次开机自动迁移）

功能	普通版（未激活）	高级版（激活）
核心映射（9 种按键类型、WASD 轮盘、视角控制）	✅ 可用	✅ 可用
连接PC控制	✅ 可用	✅ 可用
开发板直连键鼠控制	✅ 受限（仅部分按键可用）	✅ 可用
配置面板与 PWA（截图 / 编辑 / 保存 / 导出 / 触控预览 / 日志）	✅ 可用	✅ 可用
安卓 / 苹果自动识别	✅ 可用	✅ 可用
配置槽位	仅槽位 0	9 个槽位（0–8）
Lua 脚本 / 宏	❌ 不可用	✅ 可用（宏、连招、压枪、自定义事件）
MAKCU 串口注入	❌ 仅握手 / 版本 / 切速	✅ 完整注入（文本 / V2 / 扩展帧）
兼容同时手搓	❌ 仅支持一个触摸点	✅ 完整支持（触摸注入与MAKCU协议）

蓝牙 DS5 变体使用相同的手柄白名单。

状态指示灯

板载 RGB LED 指示设备状态（亮度由固件 FR_DEBUG_LED_BRIGHT 配置）：

阶段	颜色	含义
开机	洋红	正在检测恢复出厂 strap
开机	红	未检测到恢复出厂 strap（正常）
开机	绿	检测到 strap，正在擦除配置
开机	蓝	配置擦除完成
运行	绿	已连接主机设备
运行	熄灭	未连接主机设备

恢复出厂 strap：上电时短接 GPIO29 与 3V3。

故障恢复

固件启动失败自动进入 BOOTSEL

固件内置自恢复机制：若固件连续 2 次启动失败（每次上电 8 秒内未完成初始化，例如刷入了损坏或不兼容的固件文件），设备会自动重启 1~2 次后进入 BOOTSEL 模式——电脑/主机上会出现名为 RP2350 的 U 盘。

恢复方法：从发布页下载正确的 .uf2 固件文件，拖入 RP2350 U 盘（或用 picotool 刷入），设备自动重启回正常固件。全程无需拆机、无需按 BOOTSEL 按键。

此机制针对固件本身的启动失败；配置数据损坏请用下文的「恢复出厂设置」。

恢复出厂设置

如果配置异常导致设备无法正常启动，或想清空所有设置回到出厂默认，可通过以下任一方式恢复出厂设置：

方式	操作	适用场景
配置面板	PICO 配置 → 危险操作 → 恢复出厂设置	设备能正常启动、能访问配置面板
GPIO strap	上电时短接 GPIO29 与 3V3，再连接电源供电	设备无法启动 / 无法访问配置面板

⚠️ 恢复出厂设置会清除全部数据，包括所有按键映射、PIO 模式、屏幕方向、手柄/轮盘参数与 Lua 脚本，设备重启回到出厂默认，且不可撤销。授权激活码不受影响（固化在芯片 OTP，恢复出厂后仍为激活状态）。

进阶

• 了解 HIDAPI，可自行编码实现自定义上位机控制设备
• 学习 Lua 脚本 编写自定义宏，实现压枪、连招、一键丢弃等高级功能
• 通过 WebSocket API 或 HIDAPI 向 Lua 发送自定义指令，实现外部程序联动
• 使用 MAKCU 串口控制，通过 USB-TTL 连接 GPIO2/3 串口远程控制键鼠（115200 握手后可切换到工作波特率）

映射配置说明、各接口完整文档（HIDAPI / WebSocket / Lua 脚本 / 串口协议 MAKCU）与键码参考，见 文档中心。

常见问题

问题	解决
设备未识别	换一根 USB 2.0 数据线
无法访问配置面板	安卓：确认已识别 USB 网卡，且 vPointer 端口转发已启动，用 http://127.0.0.1:8000 访问；苹果：直连后访问 http://192.168.73.1/
root 设备插网卡后整机断网	见下文 root 设备：插网卡后整机断网
键鼠按下无反应	确认 PIO 工作模式与接线匹配（上位机控制选 Device，直连键鼠选 Host），见第四步
配置保存失败	检查 JSON 格式是否正确；查看 WebSocket 日志
配置损坏导致设备异常/无法启动	上电时短接 GPIO29 与 3V3（开机自动清除全部配置），或连接配置面板后执行恢复出厂设置
设备每约 60 秒自动重启一次	设备仅在 USB 被主机成功识别（枚举+配置）时持续运行；插在只供电不通信的口（充电器、劣质线、未识别的 Hub）上会周期性重启，属正常保护行为，换可通信的 USB 口即可

root 设备：插网卡后整机断网

现象：root 过的平板/手机插上 USB 网卡后整机断网，WiFi 已连接却不被使用，也不弹"登录到网络"提示；拔掉网卡即恢复。

原因：设备上的 root 广告拦截/代理类模块（内置 Clash 的去广告模块、AdGuard、加速器等）劫持了全机 DNS 和流量，替 USB 网卡"完成"了系统的联网检测，使其被误判为可上网并获得最高优先级；而实际它没有外网，拦截模块的上游又绑定了这块网卡，形成死循环导致断网。此问题与固件无关，未 root 设备不受影响。

解决（任选其一）：

1. 使用 USB 网卡期间停用该模块（Magisk 模块开关或 killall clash），拔插一次网卡即可恢复；
2. 需要常驻：关闭模块的 fake-ip DNS 模式，并将 192.168.73.0/24 加入 DIRECT 绕行名单；
3. 自查：root shell 执行 ps -A | grep -iE "clash|adguard|proxy"，有输出即中招。