Skip to content

README.zh-CN.md

Latest commit

 

History

History
145 lines (106 loc) · 6.36 KB

README.zh-CN.md

File metadata and controls

145 lines (106 loc) · 6.36 KB
Raw

Cardputer 键盘鼠标

English | 简体中文 | 繁體中文 | Italiano | Français | Português

banner

把 M5Stack Cardputer Adv 变成一个口袋键鼠,通过 蓝牙 LE 或 USB-C 连接任何电脑、手机或平板。

  • ⌨️ 键盘 — 全部 56 个按键发送标准 HID 键码(走 USB 时连 BIOS 里都能用)
  • 🖱️ 体感鼠标 — 利用内置加速度计,倾斜设备即可移动光标(也可退回方向键光标)
  • 📶 3 个蓝牙槽位 — 最多与 3 台设备保持配对,随时切换
  • ⚙️ 设备端设置菜单 — 设置保存在 TF 卡上
  • 支持 Windows / macOS / Linux / Android / iPadOS / iOS

work1 work2

快速上手

  1. 烧录固件 — 见烧录。
  2. 蓝牙(默认): 在你的设备蓝牙设置中配对 Cardputer-Keyboard-Mouse,无需 PIN。
  3. 想用 USB? 长按 BtnA 约 0.7 秒打开菜单,选择 Transport → USB(设备会重启),然后接上一根 USB-C 数据线。
  4. 开始打字。按 Fn+Space 切换输入模式:键盘 → 鼠标 → 键盘+鼠标。

顶部状态栏显示:连接状态(OK / ADV)、输入模式([KEY] / [MOUSE] / [K+M])、CAPS、倾斜灵敏度 S1–S5 和电量。

输入模式

模式 键盘 光标
键盘 所有按键正常输入 关闭
鼠标 按键变为鼠标控制 倾斜移动 — 按住任意键才移动(离合)
键盘+鼠标 (默认) 所有按键正常输入 倾斜始终生效,打字时暂停

鼠标模式按键

按方向键的布局排在 ; , . / 上:

按键 动作
, / Enter / BtnA 左键
/ 右键
m 中键
; / . 滚轮上 / 下
其他任意键(按住) 离合 — 只在按住期间移动光标

键盘+鼠标模式附加操作

按键 动作
BtnA 短按 左键单击
Opt + , / / / m 左 / 右 / 中键
Opt + ; / . 滚轮上 / 下
Opt 快速点按 发送一次 GUI/Win/Cmd 键

按住期间,Opt 作为本地鼠标前缀键,不会发给主机。 需要 GUI 组合键(如 Win+C)时,请切到键盘模式,此时 Opt 是普通的 GUI 修饰键。

方向键光标

在菜单中设置 Cursor source = arrows,或运动传感器故障时自动启用。仅在鼠标模式下生效:

按键 动作
; , . / 上 / 左 / 下 / 右移动(按住会加速)
j / k 左 / 右键
u / n 滚轮上 / 下
Enter / BtnA 左键

Fn 层

修饰键:Ctrl、Shift(Aa)、Alt、Opt = GUI/Win/Cmd。Fn 是本地键,永远不会发给主机。

按键 Fn 层 按键 Fn 层
` Esc u PgUp
1 … 9、0 F1 … F9、F10 i Insert
- / = F11 / F12 p PrintScreen
Backspace Delete a CapsLock
e End d PgDn
h Home ; ↑
, / . / / ← / ↓ / → Space 切换输入模式

其余按键均输入键面印刷的字符(US 布局;实际以主机布局为准)。

设置菜单

长按 BtnA 约 0.7 秒打开/关闭(菜单打开时暂停向主机发送输入)。 ; 上移、. 下移、Enter 确认、` / Backspace 返回。

条目 作用
Transport BLE / USB(保存并重启)
BLE host slot 1 / 2 / 3 — 每个槽位是独立的蓝牙身份
Clear pairing 清除全部 3 个槽位的配对信息 — 记得同时在主机上删除该设备
Sensitivity 倾斜光标速度,1–5
Clutch mode 默认 / 按住移动 / 按住冻结 / 始终开启
Cursor source 倾斜 / 方向键
Recalibrate tilt 以你习惯的中位姿态保持静止约 1 秒
Brightness 屏幕亮度,20%-100%,步进 20%(默认 80%)
Device name 循环切换预设名称(自定义名称:直接编辑设置文件)
About 版本 + 设置存储后端

设置保存在 TF 卡的 /kbmouse/settings.txt(纯文本 key=value,可放心手动编辑);未插卡时退回内部 flash 存储。

烧录

预编译镜像

make release

会在 release/ 目录生成两个发布镜像:

文件 烧录方式
Cardputer-Keyboard-Mouse-full.bin 用 esptool / M5Burner 写入偏移 0x0
Cardputer-Keyboard-Mouse-app.bin 拷贝到 TF 卡,通过 M5Launcher 安装 
esptool.py --chip esp32s3 write_flash 0x0 release/Cardputer-Keyboard-Mouse-full.bin

从源码编译(PlatformIO)

pio run -e cardputer-adv            # 编译
pio run -e cardputer-adv -t upload  # 通过 USB 烧录
pio test -e native                  # 单元测试(无需硬件)

如果 USB 端口不出现(首次烧录 / 固件损坏),请进入下载模式:关机 → 按住 G0/BtnA → 接上 USB → 松开。

M5Launcher 说明: 设置存放在 TF 卡上,切换固件后依然保留;BLE 配对信息在切换固件时可能丢失 — 之后重新配对即可。本固件从不触碰 G5,也从不整体擦除 NVS。

技巧与故障排查

  • 20 秒无操作后屏幕自动熄灭以省电——任何按键、点击或倾斜移动都会立即唤醒屏幕。熄屏期间输入照常工作。
  • 开机后保持设备静止约 1 秒 — 此时会记录中位姿态(屏幕显示 CALIBRATING)。此后每次光标移动生效的瞬间,当时的姿态都会成为新的中心,因此光标不会自己漂移。
  • iPhone/iPad 上要用鼠标指针: 开启设置 → 辅助功能 → 触控 → 辅助触控(AssistiveTouch)。键盘则开箱即用。
  • 重新配对后蓝牙失灵? 先在主机的蓝牙列表中删除设备,再在菜单里执行 Clear pairing,然后重新配对。
  • 检测不到运动传感器? 固件会自动切换到方向键光标,并在屏幕上提示。
  • 你的硬件上倾斜方向反了? 调整 src/core/mouse_engine.h 中的 rollSign / pitchSign。
  • 重新烧录永远可行: 无论哪种传输模式,USB 端口都保持为串口控制台 — 不需要按住启动键的操作。在 USB 传输模式下,设备是 CDC + HID 键盘 + HID 鼠标 复合设备,在 BIOS/UEFI 中也能输入。