串口协议（MAKCU）

📥 下载此API文档：serial-api.md

设备的 UART 串口（GPIO2/3，8N1）使用 MAKCU 协议族。设备开机默认 115200；主机先发送 DE AD 05 00 A5 <baud LE32> 握手帧，再切换到目标工作波特率（常用 4M）。握手、km.version()、km.baud(n) 和 V2 0xB1 属于传输控制，不受授权状态阻断；这样未激活设备仍能被网页发现、切速和连接。MAKCU 文本/V2 的实际键鼠注入、配置与调度命令受授权门控；网页使用的 55 AA 控制路径保持可用。运行期切速后重启恢复 115200。协议提供鼠标/键盘注入、连点、定时按压、字符串输入、平滑移动、按键锁定与物理输入屏蔽、状态遥测等能力。

与 HID 控制的区别

	HID（Device 模式）	串口（MAKCU 协议）
物理链路	PIO-USB-C 口的 HID OUT/IN 端点	GPIO2/3 UART（经 USB-TTL 或板载转串口）
帧格式	55 AA 命令帧（见 HIDAPI）	km.* 文本、DE AD、0x50 V2、55 AA 私有扩展帧
命令集	触屏 / 鼠标 / 键盘 / core_input 调度 / vmouse / Lua 自定义事件	上述全部能力 + 连点 / 打字 / 平滑移动 / 锁定屏蔽 / 遥测
生态	自定义上位机	MAKCU 文本/V2 客户端；可使用仓库 pytester/test_makcu.py 回归

两个通道最终进入同一套设备控制路径，功能语义一致；区别只在传输与命令集广度。

握手与帧格式概要

握手时以 115200 打开串口，发送：

DE AD 05 00 A5 <baud:uint32 little-endian>

设备不回复握手帧；主机等待短暂的 TX 排空时间后盲切到相同波特率。由于运行期可以用 km.baud(n) 改成任意支持值，健壮的上位机应逐档尝试已知速率，并在切到工作速率后发送 km.version() 确认，不能只凭握手帧判断成功。当前 Web Serial 工具依次探测 115200、921600、2000000、4000000，确认 km.MAKCU_V1.0 后才显示连接成功；若设备被改成探测表之外的自定义速率，需要把该速率加入客户端探测表。

工具提供「串口低延迟模式」开关（localStorage 记忆）：开启后工作速率改用 6M（探测表末尾追加 6M 档，板子已被留在 6M 时重连无需重启）。6M 实测可用但可能出现不稳定；开关的生效点是连接时刻——会话中途切换会断开当前连接，提示用户重启开发板后重连（板子回到 115200 再由工具切到新速率）。文本命令以 \r 或 \n 结束，例如 km.version()、km.move(10,20)、km.baud()。V2 帧格式为 [50][CMD][LEN:u16 LE][payload]；MAKCU 私有扩展帧格式为 [55][AA][LEN:u8][CMD][payload]。

按钮状态流（km.buttons）

km.buttons(mode[,period_ms]) 开启鼠标按钮状态流（物理 + 注入合并可见掩码，变化即上报）。位序 bit0=左 / bit1=右 / bit2=中 / bit3=侧1 / bit4=侧2，掩码恒 0x00–0x1F。本固件为事件驱动上报（掩码变化即发，不做周期采样），period_ms（1–1000）仅作参数兼容。

线上格式按 mode 区分（对齐官方 V4.036+ 语义）：

mode	流帧格式	适用客户端
1 / 2	6B 6D 2E <mask> 0D 0A（"km." + 掩码 + CRLF）	现行官方固件形态；WhizKid 等"扫描 km. 前缀"的上位机只认这一种
3	裸 <mask> 单字节	老固件（V4.024–035）形态，保留给 makcu-py-lib 类旧解析客户端

km.axis(mode[,period_ms]) 的 mode 语义不变（仅 1/2）。

键盘数字注入（km.key）

km.key(code,state) 按数字 HID 码注入键盘（state：1=按下，0=释放）。code 接受 0x04–0x73（主键区至 F24）与 0xE0–0xE7（修饰键），其余值静默忽略但照常应答。按键名注入仍走 km.down('name') / km.up('name')；两条路径相互独立（数字码不经过键名表与上档 shift 展开）。

55 AA 私有扩展帧

串口保留 MAKCU 私有扩展帧 55 AA，格式与 HID 控制帧相同，用于把 HIDAPI 的控制指令复用到串口：

• 帧格式：[55 AA][LEN][CMD][payload...]，LEN 为 CMD 与 payload 的总长度
• 例：55 AA 0E FC FF <dx:i32><dy:i32><wheel:i32> 注入一次相对移动
• 固件收到后在设备侧重放同一控制路径，语义与 HID 通道一致

噪声处理说明

串口只解析上述 MAKCU 帧型。无法组成完整帧的字节会按噪声消费；二进制半帧超过 50ms 未继续接收时复位解析状态。文本行必须以换行结束，非 km.* 文本静默消费。

示例

115200: DE AD 05 00 A5 00 09 3D 00   # 请求切到 4000000
4000000: km.version()\r\n           # 收到 km.MAKCU_V1.0 才确认链路
4000000: km.baud(921600)\r\n          # 收到 ACK 后主机切到 921600
921600:  km.baud()\r\n