主题
映射配置说明
本章节介绍 Web 配置面板（映射配置页）的全部功能与配置项。页面左侧为手机截图底图与映射控件，浮在上面的是可拖动的配置面板。
面板分三段，上下两段常驻，中间分四个分页切换：
| 位置 | 内容 |
|---|---|
| 顶部状态条 | 拖动面板（左侧把手）、主题切换（「映射面板」右边的按钮，点一下在 亮色 → 暗色 → 自适应 之间循环，图标跟着当前模式变）、未保存提醒、Pico 连接状态、日志/全屏按钮、收起面板 |
| 状态行 | 当前在做什么：「点击画布空白处添加映射」；选键弹窗打开时变成「正在选键 · 按一个键盘/手柄键即绑定」 |
| 分页 | 设备（截图、存档、设备设置、关于/官网）· 映射（映射开关按键、全部按键映射）· 屏幕（分辨率、视角）· 轮盘（中心半径、方向键、shift 疾跑） |
| 底部操作栏 | 配置名称输入、保存（写入槽位）、导出（下载 JSON） |
所有修改先在页面内存中生效，点击底部的「保存」后才写入 Pico 的当前槽位。
配置文件
配置文件为 JSON 格式，默认配置示例如下：
json
{
"SCREEN": {
"SIZE": [3040, 1904, 3040, 1904]
},
"MOUSE": {
"SWITCH_KEYS": ["KEY_GRAVE"],
"RANGE": 0.05,
"EDGE_RESET_ENABLE": true,
"RS_WHEEL_ENABLE": false,
"POS": [0.5936192468619247, 0.42093023255813955],
"SPEED": [0.3, 0.3]
},
"WHEEL": {
"POS": [0.15010460251046026, 0.6802325581395349],
"RANGE": 0.06,
"SHIFT_RANGE": 0.14,
"RAND_RANGE": 0,
"SHIFT_RANGE_ENABLE": true,
"SHIFT_RANGE_SWITCH_ENABLE": true,
"SHIFT_RANGE_SWITCH_KEEP_ENABLE": false,
"WASD": ["KEY_W", "KEY_A", "KEY_S", "KEY_D"]
},
"KEY_MAPS": {
"BTN_LEFT": {
"TYPE": "AUTO_FIRE",
"POS": [0.0653765690376569, 0.1325581395348837, 0.053],
"INTERVAL": [18, 20]
},
"BTN_RIGHT": {
"TYPE": "PRESS",
"POS": [0.9513598326359832, 0.10465116279069768, 0.038]
}
},
"IMG": ""
}字段说明
| 字段 | 含义 |
|---|---|
SCREEN.SIZE | 屏幕宽度、屏幕高度、外接显示器宽度、外接显示器高度。 |
MOUSE.SWITCH_KEYS | 用于切换映射开关的按键，最多 4 个（固件只有 4 个槽位，面板加满后会禁用添加入口）。支持键盘键、鼠标按键（左/右/中/后退/前进）与手柄按键；滚轮不能作为切换键。固件内置的 SELECT+RS 组合切换仍然有效。 |
MOUSE.RANGE | 开始映射时，鼠标在该半径范围内随机选择坐标作为视角映射起点。 |
MOUSE.POS | 鼠标视角映射的起始坐标，按屏幕宽度比例计算。 |
MOUSE.SPEED | 鼠标 X、Y 轴的灵敏度缩放比例。 |
MOUSE.EDGE_RESET_ENABLE | 视角拖动超出屏幕边界、重置回起始位置时的触点释放方式：true 交替释放（新旧触点短暂并存，模拟双手交替滑动），false 单点释放。 |
MOUSE.RS_WHEEL_ENABLE | 手柄右摇杆映射类型：false（默认）映射为视角拖动；true 映射为轮盘——右摇杆变为绝对定位的轮盘触点，中心为视角指定中心（MOUSE.POS）、半径为随机范围（MOUSE.RANGE），与快捷轮盘按键配合可实现 MoBA 手游滑动施法（见快捷轮盘说明）。 |
WHEEL.POS | WASD 映射轮盘的中心位置。 |
WHEEL.RANGE | WASD 轮盘半径。 |
WHEEL.SHIFT_RANGE | 疾跑状态下的 WASD 轮盘半径。 |
WHEEL.RAND_RANGE | 轮盘触点初始位置的随机半径（按屏幕宽度比例），0 表示不随机。 |
WHEEL.SHIFT_RANGE_ENABLE | 是否启用 Shift 疾跑模式。 |
WHEEL.SHIFT_RANGE_SWITCH_ENABLE | 疾跑切换方式：true 表示点击开启、再点击关闭；false 表示按住开启、松开关闭。 |
WHEEL.SHIFT_RANGE_SWITCH_KEEP_ENABLE | 仅疾跑切换方式有效：true 表示松开 WASD 后保持疾跑状态（下次按下仍以疾跑半径起步）；false 表示松开 WASD 自动取消疾跑。 |
WHEEL.WASD | 控制轮盘的四个方向键，顺序固定 = 上、左、下、右（默认 ["KEY_W", "KEY_A", "KEY_S", "KEY_D"]）。可改成任意键盘按键（例如改成 ["KEY_E", "KEY_S", "KEY_D", "KEY_F"] 即 ESDF 布局）。 |
IMG | 截图的 base64 字符串。存储到 PICO 时会丢失，前端导出 JSON 时会保留。 |
KEY_MAPS | 按键映射字典。 |
说明：所有浮点类型坐标均按屏幕宽度比例计算，实际坐标值为
浮点值 × screenWidth。
基本操作
上传截图
- 在游戏界面截图（分辨率为手机实际分辨率）。
- 在面板「设备」分页点击「上传截图」选择图片。截图加载后会自动把屏幕尺寸设置为截图的实际宽高，并进入全屏方便编辑。
截图只是编辑底图，用于精确定位触屏坐标，不会保存到 Pico（
IMG字段在写入槽位时丢弃）。重新打开页面时，若槽位配置无截图会生成纯蓝占位背景，重新上传即可。
放置按键映射
先点位置，再选键——点击截图上的空白位置，会在点击处弹出「添加映射」面板，面板标题栏里的坐标就是这次要放置的落点：
- 按一下键即可（最快）：弹窗打开时直接按键盘上的某个键、或按手柄上的某个按键，映射立刻绑定到这个位置（弹窗顶部有这条提示）。
- 点选：弹窗里有鼠标键快捷按钮（左 / 中 / 右 / 前 / 后 / 轮上 / 轮下，滚轮键固定使用「单次点击」类型），以及「选择其它按键…」按钮 —— 点开是按键选择面板：按鼠标 / 键盘 / 手柄分组的列表、每行显示中文名与原始键名，顶部搜索框可用中文名、
KEY_W或裸名W过滤（搜索框不会自动聚焦，移动端点开面板不会先弹出软键盘挡住列表——要搜索时点一下输入框即可）；点某一行即选中。 - 一个键只能有一条映射：如果这个键已经有映射，弹窗会提示并保持打开，不会覆盖原来的那条。
- 弹窗在点击处打开；再点画布的任何其它位置就是关掉它（想换个落点重开一次即可），点画布以外、按
Esc或点 ✕ 同样关闭。
放置之后：
- 触摸点可拖动调整位置；触摸点处于选中状态时滚动滚轮调整作用半径（每次点击的落点在半径内随机，模拟真人操作）。
- 点击触摸点会弹出编辑面板：可修改按键、类型与各项参数，面板内还有「屏幕取点」按钮（点击后直接在截图上点选新坐标）；按住面板顶部标题栏可拖动面板位置，点击面板外或 ✕ 关闭。
- 编辑面板与「映射」分页里的按键卡片内容一致，两处都能改按键、类型或删除：
- 改按键：点按键按钮打开按键选择面板（分组列表 + 搜索框，可搜中文名 /
KEY_W/ 裸名W），点一行即改；也可以点右侧的键盘图标按钮后直接按一下要换成的键（键盘或手柄，Esc取消）。换成已有映射的键会被拒绝并提示（列表里也不会出现已经用掉的键）。 - 删除：点右侧 ✕。
- 改按键：点按键按钮打开按键选择面板（分组列表 + 搜索框，可搜中文名 /
受浏览器限制的按键
部分按键在浏览器里无法捕获或映射不准确，例如 ESC、CapsLock。可以先用其他键创建，再在编辑面板/按键卡片的下拉框里改选目标按键（下拉框可搜索）；或将键盘单独接在 Pico 的 Host 口上——此时由 Pico 读取按键事件并经 WebSocket 转发到前端，可映射全部按键，也能直接用「按一下」的方式捕获。
按键类型
每个按键映射可选择以下类型（与页面类型下拉一致）：
| 类型 | 参数 | 说明 |
|---|---|---|
| 同步按下释放 | 坐标 | 按键按下时触摸点按下，按键松开时触摸点释放。 |
| 切换按下释放 | 坐标 | 按键第一次按下时按下触摸点并保持，再次按下时释放；按键松开无响应。适合开关型操作（如开镜/收镜、开关面板）。 |
| 快捷轮盘 | 坐标、长按判定、短按点击、松开后关闭映射 | 按下后先等待「长按判定」（默认 200ms），期间不创建轮盘触点，鼠标仍照常控制当前视角；在阈值内松开只在指定位置快速点击一次（默认保持 18ms），不控制轮盘、也不把视角挪到轮盘位置。超过阈值后才创建轮盘触点并由鼠标控制；长按松开后立即释放，并等待固定 200ms 再接受鼠标视角移动，期间位移直接丢弃。可用于轮盘选择物品、小眼睛观察等场景。 「右摇杆映射 = 轮盘」模式（ MOUSE.RS_WHEEL_ENABLE）下，超过阈值后触点由右摇杆绝对拖动；短按仍只执行一次点击。可多个快捷轮盘共存，后按的优先。「松开后关闭映射」开关：开启后，松开该按键会关闭整个映射、切回虚拟光标（与切换热键关闭映射的效果一致）。 |
| 光标智能切换 | 两个触点、触发方式、执行内容 | 触发方式：「按住-松开」或「点击-再点击」。 执行内容：三选一「仅释放光标」「仅点击触点」「点击并释放光标」。组合动作开始时点击第一个触点并临时释放光标；结束时点击第二个触点，从第二触点按下起继续保持临时光标固定 200ms，再恢复视角控制。「仅释放光标」结束时立即恢复视角，不加延迟；「仅点击触点」不切换光标模式。延迟为内置固定值，无需用户配置。 可用于打开/关闭地图和背包、临时释放光标等场景。触点 0/1 均可通过「重设」在截图上重新点选。 |
| 单次点击 | 点击时间 (ms) | 仅响应按键按下，在指定位置按下触摸点，经过设置的延迟后释放。 |
| 连发 | 点击时长、间隔 (ms) | 按住按键期间，按照设置的点击时长与间隔，反复执行触摸按下与松开。 |
| 滑动 | 间隔 (ms)、关键点列表 | 按下时触摸点按照设置的关键点，依据设定的延迟依次滑动，并在终点停留；按键松开则释放触摸点。通过「添加关键点」在截图上逐个点选。 |
| 多点触摸 | 触摸点列表 | 按下时依次按下设置的触摸点，按键松开时依次释放。通过「添加触摸点」逐个点选。 |
| 短按长按 | 两个触点、判定阈值 / 短按时长 / 长按时长 (ms)、两个开关 | 按下后不立即产生触点：在判定阈值内松开按键视为短按——点击触点 A，经过「短按时长」后自动抬起；按住超过判定阈值视为长按——立即点击触点 B，经过「长按时长」后自动抬起（长按触发后继续按住或松开按键都不再有动作）。两个触点均可通过「重设」在截图上重新点选。 「短按后关闭映射」「长按后关闭映射」开关：对应动作完成后退出映射、切换为光标模式。 |
切换类型时会尽量保留已设置的坐标：多点类型转单点取第一个触点，单点转多点以原位置作为第一个触点。
屏幕与视角
屏幕尺寸 / 外接屏幕
都在「屏幕」分页的「屏幕尺寸」一组里：
- 实际分辨率：手机实际分辨率。上传截图后自动填充，一般无需手改。
- 外接屏幕：安卓设备外接显示器（或采集卡）时的显示器分辨率，详见下文外接显示器。
视角（鼠标控制）
| 配置项 | 说明 |
|---|---|
| 灵敏度（横向 / 纵向） | 鼠标移动转成视角滑动的缩放比例，MOUSE.SPEED。 |
| 中心位置 | 开始映射时视角触点的落点，MOUSE.POS（只显示数值）。可在截图上直接拖动视角图标调整。 |
| 随机范围 | 开始映射时在中心附近随机取点的半径（像素），MOUSE.RANGE（只显示数值）。可在截图上滚轮调整，或拖动视角图标外圈。 |
| 越界释放方式（交替 / 单点） | 视角拖出屏幕边界、重置回起始位置时的触点释放方式（MOUSE.EDGE_RESET_ENABLE），两个模式二选一。交替更接近真人双手交替滑动，单点则直接抬起再按。 |
| 手柄右摇杆映射（视角 / 轮盘） | 右摇杆的用途切换（MOUSE.RS_WHEEL_ENABLE）：「视角」为右摇杆拖动视角（默认）；「轮盘」时右摇杆改为绝对定位轮盘触点（中心=视角中心、半径=随机范围），供快捷轮盘按键滑动施法，此模式下右摇杆不再控制视角。 |
陀螺仪配置（手柄六轴）
「屏幕」分页的「陀螺仪配置」一组（原「陀螺仪辅助视角」），需手柄带六轴（如 DS5）：
| 配置项 | 说明 |
|---|---|
| 功能开关 | 陀螺仪总开关（MOUSE.GYRO_ENABLE）。 |
| 生效时机 | 视角路的生效门控（MOUSE.GYRO_TRIGGER_MODE）：始终 / 仅LT / 仅RT / LT或RT（开镜/开火辅助瞄准）。 |
| 飞鼠切换键 | 绑定一个手柄按键（MOUSE.GYRO_MOUSE_KEY，仅手柄键可选）。未绑定（=0）时飞鼠整体禁用——陀螺仪不能控制鼠标；绑定后默认关闭，映射关闭时按一下该键开启「陀螺仪控鼠标」，再按关闭。这是系统级开关，Lua 脚本收不到该键事件。 |
| 瞄准模式 | 玩家空间（默认，水平转向绕重力竖直，任意持握姿态自动正确）/ 本地空间（旧版固定轴兼容回退）。 |
| 灵敏度（水平 / 俯仰） | 视角路灵敏度倍率（MOUSE.GYRO_SENS，0.01~100）。 |
| 开镜/开火倍率 | LT 或 RT 按下期间视角灵敏度乘以该倍率（MOUSE.GYRO_ADS_SENS）。 |
| 飞鼠灵敏度 | 「陀螺仪控鼠标」专用倍率（MOUSE.GYRO_MOUSE_SENS，0.01~100，水平/俯仰同值）；生效时机与开镜倍率不作用于飞鼠。 |
| 平滑强度 / 轴反向 | 传感器调参：平滑越大越稳但延迟越高、方向相反时开对应轴反向。 |
死区与零偏已不在这个分组里。它们改成了设备级的三轴校准（不跟游戏配置走，整机一份）， 在「设备 → 手柄参数」弹窗的「陀螺仪校准」分组里设置，详见下一节。
陀螺仪校准（三轴零偏 / 死区）
打开「设备」分页 →「手柄参数」→「摇杆死区」下面那组「陀螺仪校准」。 这一组是设备级设置（跟手柄走，不跟游戏配置/槽位走），需手柄带六轴（如 DS5）。
它取代了原来映射配置里的「死区」「零偏」：旧的两个参数只有水平/俯仰两轴、要用户手填； 新的是三轴（X/Y/Z）的自动或手动校准。
展开这一组、并且窗口在前台时才会推实时数据（收起、切到别的应用、切标签页、 关掉弹窗都会停；切回来自动续上）。上电默认不推。
| 显示 | 说明 |
|---|---|
| 角速度 dps / raw | 最近一帧三轴原始角速度（度/秒，以及对应的原始计数值） |
| 抖动幅度 | 最近 1 秒内该轴读数的最大值减最小值（raw）。它衡量的是「抖」而不是「偏」：手柄静止时的恒定零偏在这个值里会被自动抵消，所以只有漂移、没有抖动的手柄这一列照样很小，别拿它当零偏是否正常的证据。三轴抖动幅度都小于「静止阈值」才算静止 |
| 零偏 / 死区 | 当前生效值（raw） |
| 输出 dps / raw | 校准后的角速度，也就是映射引擎实际拿去用的值（= 原始 − 零偏，再按死区硬归零） |
| 配置项 | 说明 |
|---|---|
| 自动校准 | 开启后，手柄静止时持续跟踪零偏与死区。只改设备内存，不写 flash——重启后回到保存值。 |
| 静止阈值 | 静止判定的容差（raw，默认 5）。三轴抖动幅度都小于它才算静止。想看自己的手柄该填多少，就展开这一组、把手柄静置，照「抖动幅度」那几列的读数填（比读数略大一点）。太大 → 运动中也被当成静止；太小 → 永远判不出静止。 |
| 开始校准 | 手动校准：点一下后把手柄静置约 2 秒（别移动、别放在会震动的桌面上）。期间显示进度；移动会导致重试，反复移动则失败。完成后三轴零偏/死区会填进下面的输入框。 |
| 三轴零偏 / 死区 | 可直接手改。零偏范围 ±1000，死区 0~1000（都是 raw 单位）。 |
三轴零偏/死区的含义：设备的角速度输出 =
原始读数 − 零偏；再去掉 |值| < 死区 的部分（硬归零）。 零偏消除「手柄静止却一直缓慢漂」的恒定偏置，死区吸收「静止时的抖动噪声」。
校准只算不写：无论自动还是手动校准，结果都只存在设备的运行期内存里（立刻生效）。 要让它们下次开机仍然有效，必须点弹窗底部的「保存」把这一组连同手柄参数一起写进设备。 保存后无需重启即生效。
WASD 轮盘
轮盘用于把四个方向键（或手柄左摇杆）映射为游戏虚拟摇杆。都在「轮盘」分页里，分三组：中心与半径 / 方向键 / shift 疾跑（开关键右侧的小药丸显示当前状态）：
| 配置项 | 说明 |
|---|---|
| 中心位置 / 半径 | 轮盘触点的中心与移动半径（只显示数值）。可在截图上拖动轮盘、滚轮调整半径。 |
| 轮盘方向键 | 控制上 / 左 / 下 / 右四个方向的键盘按键（WHEEL.WASD，默认 W / A / S / D）。四个按钮按键盘 WASD 的键位排列（上排在中间，下排是左 / 下 / 右）：点击某个方向后按下一个键盘按键即可设置，Esc 取消。只支持键盘按键——按下鼠标键、滚轮或手柄键会提示不支持并退出设置；同一个键不能给两个方向。想用 ESDF 布局就把这四项改成 E / S / D / F。 |
| shift 轮盘（已启用 / 已禁用） | 是否启用疾跑外环（WHEEL.SHIFT_RANGE_ENABLE）。 |
| 疾跑触发方式（长按 / 切换） | 疾跑触发方式（WHEEL.SHIFT_RANGE_SWITCH_ENABLE），两个模式二选一：长按＝按住疾跑键才生效；切换＝点一下切换疾跑状态。 |
| 松开方向键后（保持 / 重置） | 仅切换模式下显示（WHEEL.SHIFT_RANGE_SWITCH_KEEP_ENABLE），二选一：松开方向键后保持疾跑，或回到走路半径。 |
| 疾跑 / 静步（常规 / 互换） | 仅启用 shift 轮盘时显示（WHEEL.SHIFT_RANGE_SWAP_ENABLE），二选一：互换＝默认疾跑、按疾跑键变静步。 |
上述"二选一"在面板上用分段按钮表示（两个选项并排、当前生效的高亮），而不是开关——开关的语义是"开/关"，表达不了"A 模式 / B 模式"。真正的开/关（如「shift 轮盘」是否启用、「释放光标」是否退出映射）仍用开关。 | 疾跑半径 | 疾跑外环半径的滑条（
WHEEL.SHIFT_RANGE），仅启用 shift 轮盘时显示。 | | 初始位置随机范围 | 滑条，每次开启映射时轮盘触点从配置中心附近随机位置开始（半透明圆显示范围，WHEEL.RAND_RANGE）；0 表示固定中心。 |
打开「参数配置」中的「随机轮盘」开关（默认开启）时，轮盘按神经网络轨迹 + 随机抖动移动，行为更拟人；关闭后进入直连模式：无轨迹与随机，按下方向键触点直接移动到对应方向位置。轨迹细节（精细度、速度、抖动等）在「轮盘参数」弹窗中调整。
映射切换按键
- 切换键用于在映射模式与虚拟光标模式间开关映射（默认键盘飘号键
`与鼠标中键，按任意一个均可切换）。 - 添加方式有两种，和按键映射一致：点「添加映射切换键」后按下一个键盘、鼠标或手柄按键（也支持 Pico Host 口直连设备的按键事件），或点「选择按键…」在按键选择面板的列表里挑（分组列表 + 搜索框；已经用作切换键的键不会出现在列表里）。
- 最多 4 个（固件只有 4 个槽位）：加满后两个添加入口都会置灰、按钮显示「已达上限 4 个」——删掉一个才能再加。重复添加会提示已存在；捕获态按
Esc取消。点击已添加的按键名可删除。 - 槽位热键「修饰键 + 数字行 1~9」与切换键独立：热键切槽位，切换键开关映射。修饰键默认左 Alt，可在「参数配置」弹窗里改成任意键盘/鼠标/手柄按键（Num 小键盘区不支持切换）。
面板里的弹窗与分页共用同一套视觉语言：设置项按「分组卡片 + 设置行」排列，在两个模式之间选一个用分段按钮（当前生效的高亮），真正的开/关用开关（右侧带「已开启 / 已关闭」状态）。操作结果与错误都在弹窗标题右侧以状态药丸或行内提示条给出，不使用会阻塞页面的弹出框（
alert/confirm）。
槽位管理
在「设备」分页点击「选择槽位」打开配置槽位管理，共 9 个槽位（编号 0–8，热键数字行 1 = 槽 0）：
- 编辑此配置：把该槽位内容加载到编辑器（编辑中标记），并同时把设备切换到这个槽位（等同于顺手点了一次「使用此配置」——点「编辑」通常就是要跑这份配置；已经在用的槽位不会重复切换）。正在编辑的那个槽位这颗按钮是灰的（内容已经在编辑器里了）；要把正在编辑的槽位切到设备上，用它卡片上的「使用此配置」。反向不成立：「使用此配置」只切设备，不动编辑器里的内容，也不会改变「编辑中」是哪个槽位。
- 空槽位上有两颗按钮，都是从零开始以外的选择：
- 新建配置：回到默认模板（鼠标 / 轮盘 / 按键映射全部重置，只保留屏幕尺寸），把编辑器切到这个空槽位；无真实截图时生成带引导文字的占位底图。
- 复制当前配置：把编辑器里当前这一份（含尚未保存的改动与当前截图）原样带到这个空槽位——配置内容一个字节都不变，只是把「当前槽位」指过去，配置名改成「原名-copy」（免得两套配置在列表里同名分不清），要别的名字直接在底部输入框改。适合「在这份配置基础上改改存成另一套」。
- 两者都不写设备：内容立刻在编辑器里生效，但要真正落盘仍要点底部「保存」（否则关掉页面就没了）。
- 使用此配置：将设备切换为使用该槽位（使用中标记）。
- 设为默认：设备重启后默认使用的槽位（默认标记）。
- 删除：清空该槽位。删除是卡片内二次确认（点「删除」后卡片里出现「确认删除 / 取消」，不再弹浏览器确认框——浏览器确认框会阻塞整个页面）。
- 未激活设备只能使用槽位 0，槽位 1–8 显示锁定，激活后可用。
底部「保存」按钮把当前编辑器内容写入当前选中的槽位（需先用槽位弹窗选择，否则会提示）；它只写入不切换，「使用此配置」才改变设备正在运行的配置。「导出」按钮把当前配置（含截图）下载为 JSON 文件。
参数配置弹窗
「设备」分页里的「参数配置」打开的设置独立于映射 JSON，保存在设备存储中，点「保存」后立即生效，「恢复默认」还原全部默认值：
| 配置项 | 说明 |
|---|---|
| 光标显示方式 | 光标怎么画：虚拟光标（默认，需装安卓端 app）/ 空心环（免 app，需打开系统「显示点按操作反馈」）/ 触摸笔（系统原生笔形光标）/ 直接鼠标（以 USB 鼠标方式输出，苹果安卓通用）/ Tablet 绝对鼠标（USB Puck 绝对坐标，系统显示标准鼠标光标）/ 关闭（不输出任何光标，虚拟光标的按下/抬起/滚轮手势一并停用）/ 融合器光标（光标渲染交给前端：位置经 WebSocket 推送，配合面板 #cursor 绿幕页 + OBS 色键当直播光标，见 WebSocket API 的 0x03 帧；点击与虚拟光标模式相同，在光标位置产生真实触摸）。涉及 USB 形态变化时设备自动热重载 USB 生效。目标平台为苹果时：选「直接鼠标」「关闭」「融合器光标」按所选生效，其它方式在 iOS 上无效、以「直接鼠标」运行（运行期覆盖，不写入设备存储）。 |
| 键盘直通 | 映射关闭时，插在设备上的键盘直接在手机/电脑上打字。切换需重启设备后生效。 |
| 随机轮盘 | 开启：WASD 轮盘走神经网络轨迹 + 随机抖动（拟人化，默认）。关闭：直连模式，按下直接落位到方向半径处，无中间轨迹、无随机。 |
| 疾跑键 | 触发疾跑的按键，支持键盘/鼠标/手柄按键，默认不修改（左 Shift）。点「选择按键」直接按一下或从列表挑（滚轮伪键不可用），Esc 取消，「重置」恢复默认。 |
| 配置切换修饰键 | 槽位热键的修饰键：按住它 + 主键盘数字行 1~9 切换配置槽位（1 = 槽 0；Num 小键盘区不支持）。支持键盘/鼠标/手柄按键，默认不修改（左 Alt）。不能选数字行 1~9（触发键本身），也不能与疾跑键相同。「重置」恢复默认。 |
| 光标显示位置 | 虚拟光标由隐藏切换为显示时强制移动到此坐标（屏幕像素）。0,0 = 不重置（保持当前位置）。可点击「在屏幕点选」直接在截图上选位置。 |
| 鼠标速度 | 鼠标移动速度倍率，0 = 不调整（默认），1.0 = 原始速度。 |
| 滚轮速度 | 一格滚轮折算的屏幕像素，0 = 默认（64）。 |
| 视角自动释放超时 | 视角模式下停止输入后自动松开视角的时间（毫秒），0 = 默认（400），负数 = 永不自动释放。 |
「ESDF 方向键」开关已弃用并从面板移除：它以前做的事（把轮盘方向键从 W/A/S/D 换成 E/S/D/F）现在由映射配置里的「轮盘方向键」（
WHEEL.WASD）直接完成——在WASD 轮盘区把那四项改成 E/S/D/F 即得到原来的 ESDF 布局。旧版本留下的开关状态在保存配置时原样保留，不会影响使用。
轮盘参数弹窗
「轮盘参数」（设备分页）调整随机轮盘的轨迹手感（直连模式下不生效），同样支持「恢复默认 / 刷新 / 保存」：
| 参数 | 默认值 | 说明 |
|---|---|---|
| 轨迹精细度 | 3 | 航点间线性插值点数，越大轨迹越顺滑。 |
| 响应密度 | 8000 μs | MOVE 发送周期（回报率），越大事件数越少。 |
| 移动速度 | 1000 μs | 每航点耗时，决定整段移动快慢。 |
| 转向灵敏度 | 25 px | 方向改变时目标移动超过此值才重规划轨迹。 |
| 游走活跃度 | 1000 ms | 长按同方向时微漂移重新随机的时间间隔。 |
| 长按平滑度 | 160000 μs | 轨迹结束后长按发送 MOVE 的节拍。 |
| 游走幅度 | 20° | 微漂移扇形半角，越大游走范围越宽。 |
| 抖动大小 | 0.04 | 方向向量噪声比例，影响目标落点偏差。 |
| 疾跑乱晃 | 3.0× | 疾跑时半径额外抖动倍数，越大落点越飘忽。 |
手柄参数弹窗
「手柄参数」（设备分页）配置手柄摇杆映射（连接手柄后生效）：
| 配置项 | 说明 |
|---|---|
| 左摇杆 / 右摇杆死区 | 摇杆未推过死区不产生输入（比例 0–1，默认 0.062）。 |
| 回报率 | 鼠标移动事件的发送频率上限（125–1000 Hz，默认 500）。 |
| 视角灵敏度 | 右摇杆控制视角时的移动速度系数（正数）。 |
| 鼠标灵敏度 | 右摇杆映射鼠标指针时的移动速度系数（正数）。 |
| 视角映射曲线 / 鼠标映射曲线 | 摇杆输入 → 输出速度的响应曲线，可在图上添加/拖动/删除中间点（最多 6 个），微调小幅度推杆与推到底的手感。 |
弹窗底部除了「保存 / 恢复默认 / 刷新 / 关闭」还有两个按钮：
| 按钮 | 作用 |
|---|---|
| 预览 | 把当前设置只写进设备内存，立即生效但不写 flash。反复调参试手感不会磨损 flash，也不会因为写 flash 冻结 USB 总线而打断手柄输入。 |
| 放弃 | 让设备从 flash 重读覆盖内存，并把面板里的数值也恢复成设备上已保存的那份（设备侧同样不写 flash）。 |
这三颗按钮管整张弹窗：手柄参数与「陀螺仪校准」是两个独立的存储项，但它们在同一个 弹窗里，所以「预览 / 放弃 / 保存」对两者一起生效——不会出现"预览了手柄参数、 陀螺仪那组却还是旧值"这种情况。
唯一的例外是陀螺仪那组的「自动校准开关 / 静止阈值」：那两项要边看实时读数边调， 所以改完就立即下发到设备内存（同样不写 flash），不等你点「预览」或「保存」。
「预览」上传过的设置不会自动落盘，重启即回到上次保存的值——试好之后再点「保存」固化。 预览也不跨弹窗：重新打开「手柄参数」时会先回到设备已保存的值。
PICO 系统配置弹窗
「PICO 配置」（设备分页）为设备级设置：
| 配置项 | 说明 |
|---|---|
| 链路延迟统计 | 显示"收到鼠标点击 → vmouse 触摸事件发送完成"的 min / avg / max 延迟与样本数。 |
| 授权激活 | 显示设备序列号与激活状态；未激活时输入作者签发的 128 位十六进制激活码并点击「激活」。序列号全零表示 OTP 未编程，无法激活。 |
| PIO 工作模式 | 分段按钮选择 Host（默认，经扩展坞连接键鼠）或 Device（连接 PC 接收上位机控制）。切换后自动保存并重启生效。未激活设备也可切换 Host，但仅开放下方基础输入白名单。 |
| 目标平台 | 分段按钮三选一：安卓（默认，触屏形态）；苹果（iPadOS，触控板形态并自动适配光标与设备识别，连 iPhone/iPad 时选它）；自动（设备通过 DHCP 指纹 / mDNS / 联网探测识别主机系统，自行在两种形态间切换，检测结果断电保存）。手动切换后 USB 自动热重载，无需重启。 |
| 屏幕旋转方向 | 分段按钮选择 0° / 90° / 180° / 270° / 自动（跟随上位机 vmouse 上报的方向），立即生效。外接显示器场景一般手动设为 0°。 |
| USB 描述符配置 | 自定义原生 USB 口的 VID / PID / Manufacturer / Product / Serial Number（VID/PID 为 4 位十六进制，字符串最长 32 个 ASCII 字符），重启后生效。「恢复默认值」回到出厂标识（伪装 Sony DualSense 手柄）。 |
| 危险操作 — 恢复出厂设置 | 清除全部按键映射、PIO 模式、屏幕方向、手柄/轮盘参数与 Lua 脚本，重启回到出厂默认，不可撤销（授权激活码固化在芯片 OTP，不受影响）。详见快速开始中的「故障恢复：恢复出厂设置」。 |
| 重启 / 重启到烧录模式 | 底部按钮：普通重启；或重启到 BOOTSEL 烧录模式（无需拔插设备即可刷固件）。 |
未激活设备的基础输入测试
未激活设备不会被强制限制为 Device 模式，可以切换 Host 验证连接和基本映射。此时只放行以下输入：
| 设备 | 可用输入 |
|---|---|
| 键盘 | W、A、S、D、飘号/波浪号键（KEY_GRAVE，HID Usage 0x35） |
| 鼠标 | X/Y 移动、左键、中键 |
| 手柄 | Select、RS、RT 按键，左、右摇杆，RT 模拟量 |
鼠标滚轮、其它键盘和鼠标按键、手柄 LT、其它手柄按键、六轴和触摸板不在测试白名单内。蓝牙 DS5 变体采用同样的手柄限制；激活后恢复完整输入能力。槽位 1–8、Lua 脚本写入等功能仍保留各自的激活要求。
默认配置可用飘号键或鼠标中键开关映射。已有自定义配置不会自动增加中键切换，需要在「映射切换按键」中自行添加。
过滤发生在 hidkit 输出回调、进入映射引擎之前；蓝牙 DS5 在自己的输入转发层执行相同规则。被过滤按键的按下和对应松开均不会进入引擎；白名单内的按键在映射关闭时仍可能正常记录 key event with map off 日志。
外接显示器
当安卓设备外接显示器（或采集卡）时外接 USB 触摸屏将绑定到外接显示器，会导致以下问题：
- 按键位置错乱
- 屏幕旋转方向失效
针对屏幕旋转方向错乱，需要在PICO 系统配置-屏幕旋转方向中将旋转方向手动设置为 0。
分辨率设置分为以下三种情况：
直接镜像
安卓画面等比例显示在外接显示器上，左右或上下可能出现黑边。此时截图分辨率应使用安卓原生屏幕截图分辨率，外接显示器分辨率设置为外接显示器的实际分辨率。wm size后镜像（推荐）
使用wm size指令将安卓原生屏幕分辨率设置为与外接显示器分辨率相同后再镜像。此时使用wm size修改分辨率后的截图创建设置，外接显示器分辨率无需修改，保持与截图相同。扩展显示
安卓设备与外接显示器独立显示画面，互不干扰。此时使用外接显示器上的游戏画面截图创建设置，外接显示器分辨率无需修改，保持与截图相同。
拓展坞的选择
使用拓展坞可同时完成映射、供电、投屏和外接耳机。选择自己设备支持的拓展坞即可，开发板对拓展坞来说类似于鼠标+usb网卡。
- 苹果设备
拓展坞网卡与开发板模拟网卡可同时识别并独立访问，互不影响。
- 安卓设备
大多数安卓设备并不支持两个外接网卡同时工作，由于开发板的网卡不能外接网络，所以一般会被屏蔽。导致在插入网线时候，无法使用虚拟光标与访问后台，但是映射功能正常。不插入网线的时候，并不影响正常工作。
- 供电
选择带 PD 供电输入的型号。同时使用投屏、有线网络和外设时，建议至少 45W，并留有余量。
- 验收测试
收货后同时测试“插网线 + 投屏 + 供电”，确认 PICO 网卡是否仍可用；若被屏蔽，按安卓插网线情况处理。