MAKCU API

KM 主机协议 — v3.9 · MAKCU 生态的完整指令参考。

最后更新 2026-10-02 · V4.073 正式版 API 兼容更新· 固件版本与能力矩阵 →

旧程序连接兼容 · V4.073

V27/V29 与 V4.027/V4.029 是不同版本。连接 USB2 的 CH343 串口，使用 8N1、无流控；分别探测 4000000 和 115200，关闭占用端口的其他工具。波特率不匹配时，发送切换命令不会生效。

用 km.version() 加换行探测。旧 V27/V29 会回显查询命令；当前版本返回 km.MAKCU 和提示符。程序应识别结果行并读完提示符，不要整段字符串硬匹配；连接成功前不要开启按键流。

V4.073 新增 km.baud() 查询和 km.baud(115200/4000000/0) 设置（每次一个参数，0 表示 115200），以及二进制 0xA4 四字节小端波特率查询。切换后重新以目标速率打开并验证；不修改保存的上电速率。此前版本不支持这两个查询入口。

本次保留现有 version/echo 回复。km.serial、km.info、km.help、km.catch_* 仍不支持，不能把它们作为必需握手。新增兼容已通过软件测试，具体第三方程序与实物串口仍待验证。

固件 V4（V4.0xx）与本页的差异

本页是 V3.x 固件（V30 及 AIO 工具时代）的指令。用 MAKCU 工具箱（原诊断工具）更新过的设备运行 V4.0xx 固件，它的 km.* 文本指令集更小，其余功能走二进制接口和网页设置（app.makcu.com）。

V4 可用：version、device、echo、buttons、left、right、middle、side1、side2、move(x,y)、wheel、move_mask、wheel_mask、left_mask … side2_mask、down、up、init、press、string、isdown、multidown、multiup、multipress、mask、remap、keys、stream、controller、controller_state、controller_mask、controller_physical；V4.026 起还有 click、moveto、getpos、screen、silent、lock_*。move_now / moving 并非"V4.028 起连续可用":V4.030 线（V4.030/031/033）有 move_now、moving、flick、ms1/ms2；V4.032/V4.035 端点线都没有；V4.036 默认线仅恢复 move_now；moving 与 ms1/ms2 自 V4.039 才回归，flick 至今未回到默认线。

V4 没有对应文本指令：axis、bypass、catch_*、disable、fault、help、hs、info、invert_x/y、keyboard、led、log、mo、mouse、pan、reboot、release、remap_button、serial、swap_xy、tilt、turbo。屏蔽物理输入请用 move_mask / wheel_mask / *_mask / mask。

回应格式（V4.018 起）：查询回 结果\r\n>>> ，如 km.version() → km.MAKCU，与 V3.x 相同；km.echo(1) 时先回显指令。按键查询（V4.020 起）：km.left() 等返回 0 无 / 1 物理 / 2 注入 / 3 两者。文本 km.buttons 的按键流按固件不同：V30 发 0x53 事件帧；V4.024/026/032/035 每次变化发裸 1 字节掩码；V4.030 线与 V4.036 起为 mode 1/2 = 6B 6D 2E（"km."）+ 掩码 + 0D 0A（CRLF），mode 3 = 裸字节。寻找 "km." 前缀的客户端在裸字节版本上会漏读。

手柄（仅 V4）：摇杆 +Y 一律朝下；V4.008–V4.023 误把通用 HID 手柄（如 SCUF Envision）的 Y 轴也翻转了，V4.024 已修复。轮询率：MAKCU 为全速 USB，任何鼠标或 8K 接收器最高 1000 Hz。

V3 鼠标指令（V4.026 起）：km.lock_*（与 *_mask 同一状态）、km.click、km.screen、km.getpos、km.moveto、km.silent。指针位置按 km.screen 设定的虚拟屏幕（默认 1920×1080，设定时居中）由每个发给电脑的鼠标报告累计并在边缘截断；Windows 指针加速会使其漂移，与 V3.x 相同。km.moveto 接受 V3 的分段/控制点参数但不使用；km.silent 移到目标、左键点击后按原距离移回（V4 对 V3 描述的解释）。鼠标注入平滑（interpolate）：把 km.move 摊开到多帧发送。V4.036 默认 50%（1000 Hz 下 25% 以内约 4 ms、50% 约 17 ms、80% 约 42 ms），V4.039 起默认改为 0（下一帧直接发出，还原 V3 时序）。km.move_now（下一帧直接发）在 V4.036 默认线起可用；km.moving()（注入移动仍在发送时回 1）仅 V4.030 线与 V4.039 起有，V4.032–V4.038 没有。V4.028 起：经 MAKCU 的手柄不再提供 USB 音频（扬声器、耳机孔、麦克风、USB 触觉），震动和自适应扳机不受影响。

MAKXD 固件（0.2.0 起）：以下行为与 MAKCU V4 一致——查询回 结果\r\n>>> ，只有 km.echo(1) 时才回显指令（更早的 MAKXD 固件总是回显）；km.left()…km.side2() 返回 0–3，文本 km.buttons(1) 每次变化发一个按键字节；摇杆 +Y 在所有手柄上都朝下，轴屏蔽模式同样如此（更早的 MAKXD 对 Xbox 协议/XInput 手柄直接透传，+Y 朝上）；鼠标键盘转手柄默认关闭，未保存过设置的升级设备也关闭；第三方 Xbox 协议（GIP）和 XInput 手柄按接口识别，通用 HID 手柄的右摇杆和扳机按报告描述符选取，支持任意 16 位量程。MAKXD 版本号：V24 及以前为 Vn；0.1.0 起为 主.次.修订，数值为 主×10000+次×100+修订（0.2.0 即 200），与旧版本的数值比较仍然成立。

V4.036 起（二进制）：新增 0x55 PHYS_BUTTONS（读物理鼠标按键掩码）、0x56 INJECT_SNAPSHOT（读 40 字节注入状态快照）、0x67 move_now（下一帧直接发送移动）、0x34 鼠标历史读出（信号分析）；均为 host bridge / 诊断用的只读或注入接口。

两套二进制协议不要混用：本页的「V2 API (Binary)」是 AIO/MAKXD 遗留二进制协议；V4 固件的二进制接口是 MAK_API（DE AD | LEN | CMD | PAYLOAD 框架），两者 opcode 空间不同，用遗留 opcode 打 V4 会失败。完整的逐 opcode 载荷/回复表、稳定性承诺与各固件版本可用性见 固件版本与能力矩阵。

传统 API (ASCII)

所有响应都会以km.开头，并以CRLF 结尾，随后是提示符>>> 。
下方 TX 示例中的最后提示符均表示为\r\n>>> 。
RX（主机 → 设备）
  • 命令格式：以 . 开头，以 ) 结尾。不再需要 km. 前缀。
  • 其他值（如 km、\r\n 等）会被忽略。示例：.move(1,1,)
  • 可选二进制帧：DE AD <lenLE:2> <ASCII 或二进制负载>
TX（设备 → 主机）
  • 格式：km.payload\r\n>>> （为兼容性保留 km. 前缀）
  • Setter 指令会回显输入作为 ACK，除非通过echo(0) 关闭。
  • 部分流式响应在 km. 前缀后携带二进制：km.mouse<8字节>、km.buttons<1字节掩码>。行尾仍为 CRLF 与提示符。

鼠标

单个按键 (GET/SET)

命令
left([state]) | right([state]) | middle([state]) | side1([state]) | side2([state])
参数
state: 0=释放（发送帧），1=按下，2=静默释放（设为0但不发送帧）
响应 (GET)
km.left()
>>>

返回锁定状态：0=无，1=原始，2=注入，3=两者。

响应 (SET)
km.left(1)
>>>

回显 ACK（受 echo(0|1) 控制）。

点击调度 (SET)

命令
click(button[,count[,delay_ms]])
参数
button: 按键编号; count: 点击次数（可选）; delay_ms: 延迟（可选，默认随机 35-75ms，内部计时）
响应 (SET)
km.click(1,3)
>>>

回显 ACK。

turbo([button[,delay_ms]]) — GET/SET

命令
turbo([button[,delay_ms]])
描述

启用鼠标按键的连发模式。当按键被按住时，自动触发快速的按下/释放循环。多个按键可以同时启用连发，每个按键有独立的延迟设置。

参数
  • button: 1-5（鼠标按键：1=左键，2=右键，3=中键，4=侧键1，5=侧键2），0=禁用所有连发
  • delay_ms: 1-5000ms（0=禁用）。如果省略，使用随机 35-75ms。延迟是每次按下/释放切换之间的时间（例如，500ms = 按下 500ms，释放 500ms，重复）
  • 延迟会自动舍入到鼠标端点的 bInterval 以进行 USB 同步
  • turbo() - 仅返回活动的连发设置，如 (m1=200, m2=400)（仅显示已设置的，不显示零值）
  • turbo(button) - 使用随机 35-75ms 延迟设置连发（自动舍入到 bInterval）
  • turbo(button, delay_ms) - 使用指定延迟设置连发（自动舍入到 bInterval）
  • turbo(button, 0) - 禁用该按键的连发
  • turbo(0) - 禁用所有连发
示例
km.turbo(1, 500)
>>> 
km.turbo(2, 250)
>>> 
km.turbo(1)
>>> 
km.turbo()
>>>

鼠标移动

move(dx,dy[,segments[,cx1,cy1[,cx2,cy2]]]) — SET

命令
move(dx,dy[,segments[,cx1,cy1[,cx2,cy2]]])
参数

dx,dy: 相对移动距离; segments: 分段数（可选，默认1，最大512）; cx1,cy1,cx2,cy2: 三次贝塞尔控制点（可选）

响应 (SET)
km.move(10,-3)
>>> 
km.move(100,50,8,40,25,80,10)
>>>

回显 ACK。

moveto(x,y[,segments[,cx1,cy1[,cx2,cy2]]]) — SET

命令
moveto(x,y[,segments[,cx1,cy1[,cx2,cy2]]])
描述

将指针移动到绝对位置。内部计算到达请求屏幕位置所需的 x,y 移动量。参数与 km.move() 对齐。

参数

x,y: 绝对坐标; segments: 分段数（可选，默认1，最大512）; cx1,cy1,cx2,cy2: 三次贝塞尔控制点（可选）

响应 (SET)
km.moveto(640,360)
>>> 
km.moveto(100,50,8,40,25,80,10)
>>>

回显 ACK。

wheel(delta) — SET

命令
wheel(delta)
描述

Windows 不允许在单个命令中执行多个滚轮步数。delta 值会被限制为 ±1 步（正数向上滚动，负数向下滚动）。大于 1 的值视为 1，小于 -1 的值视为 -1。

参数
delta: 滚轮步数（限制为 ±1）
响应 (SET)
km.wheel(-1)
>>> 
km.wheel(1)
>>>

回显 ACK。注意：km.wheel(-5) 只会向下滚动 1 步，km.wheel(5) 只会向上滚动 1 步。

pan([steps]) — GET/SET

命令
pan([steps])
参数
steps: 水平滚动步数（SET）; 无参数时查询待处理数量（GET）
响应
km.pan(3)
>>>

tilt([steps]) — GET/SET

命令
tilt([steps])
参数
steps: 倾斜/z轴滚动步数（SET）; 无参数时查询待处理数量（GET）
响应
km.tilt(2)
>>>

getpos() — GET

命令
getpos()
响应 (GET)
km.getpos()
>>> km.getpos(123,456)
>>>

返回当前指针位置 (x,y)。

silent(x,y) — SET

命令
silent(x,y)
参数
移动并在 (x,y) 处执行静默左键点击
响应 (SET)
km.silent(400,300)
>>>

回显 ACK。

鼠标高级

mo(buttons,x,y,wheel,pan,tilt) — SET

命令
mo(buttons,x,y,wheel,pan,tilt)
描述

发送完整的原始鼠标帧（仅SET，不支持GET）。(0) 清除所有状态。x,y,wheel,pan,tilt 为一次性值；按键掩码镜像按键状态。

参数
buttons: 按键掩码; x,y: 移动增量; wheel,pan,tilt: 滚轮值
响应 (SET)
km.mo(1,10,5,0,0,0)
>>>

lock_<target>(state) — GET/SET

命令格式
lock_<target>([state])
描述

锁定按钮或轴。目标（target）是命令名的一部分，不是参数。state: 1=锁定，0=解锁。调用时使用 `()` 可读取锁定状态。

目标

按键: ml/mm/mr/ms1/ms2

  • ml - 左键
  • mm - 中键
  • mr - 右键
  • ms1 - 侧键1
  • ms2 - 侧键2

轴: mx/my/mw/mx+/mx-/my+/my-/mw+/mw-

  • mx/my/mw - 完全锁定（阻止该轴的所有移动）
  • mx+/my+/mw+ - 正向锁定（仅阻止正向移动）
  • mx-/my-/mw- - 负向锁定（仅阻止负向移动）
响应 (GET)
km.lock_mx()
>>> km.lock_mx(1)
>>>

返回值：1=已锁定，0=未锁定

响应 (SET)
km.lock_mx(1)
>>>

锁定所有 X 轴移动

km.lock_mx+(1)
>>>

仅锁定正向 X 移动（向右）

km.lock_mx-(1)
>>>

仅锁定负向 X 移动（向左）

km.lock_my(1)
>>>

锁定所有 Y 轴移动

km.lock_mw(1)
>>>

锁定所有滚轮移动

km.lock_mw+(1)
>>>

仅锁定正向滚轮移动（向上滚动）

km.lock_mw-(1)
>>>

仅锁定负向滚轮移动（向下滚动）

km.lock_ml(1)
>>>

锁定左键

catch_<target>(mode) — GET/SET

命令格式
catch_<target>([mode])
描述

在锁定的按钮上启用捕获。目标（target）是命令名的一部分，不是参数。注意：捕获仅适用于按钮，不适用于轴。需要先设置对应的 km.lock_<target>。

目标
ml, mm, mr, ms1, ms2（仅按钮，不适用于轴）
参数
mode: 0=自动，1=手动; () 返回状态
响应 (GET)
km.catch_ml()
>>>

使用 `()` 查询捕获状态

响应 (SET)
km.catch_ml(1)
>>>

为左键启用手动捕获

km.catch_ml(0)
>>>

为左键启用自动捕获

鼠标重映射（物理）

以下命令仅影响物理输入，注入不受影响。这意味着您可以重映射物理鼠标按键和轴，而通过 API 注入的输入将保持不变。

remap_button([src,dst]) — GET/SET

命令
remap_button([src,dst])
描述

重映射鼠标按键（仅物理）。自动清除冲突的映射；可以映射两个方向（交换）。

参数
  • () - 仅显示活动的映射，如 (left:right,right:left)
  • (0) - 重置所有按键映射
  • (src,dst) - 映射按键 src→dst（1=左键，2=右键，3=中键，4=侧键1，5=侧键2）
  • (src,0) - 清除 src 按键的映射
示例
km.remap_button()
>>> 
km.remap_button(1,2)
>>> 
km.remap_button(0)
>>>

remap_axis([inv_x,inv_y,swap]) — GET/SET

命令
remap_axis([inv_x,inv_y,swap])
描述

重映射鼠标轴（仅物理）。一次设置所有三个标志。

参数
  • () - 显示当前设置，如 (invert_x=0,invert_y=1,swap_xy=0)
  • (0) - 重置所有轴映射
  • (inv_x,inv_y,swap) - 设置所有三个标志（0 或 1）
示例
km.remap_axis()
>>> 
km.remap_axis(0,1,0)
>>> 
km.remap_axis(0)
>>>

invert_x([state]) — GET/SET

命令
invert_x([state])
描述
反转 X 轴（仅物理）
参数
() 查询; (0) 禁用; (1) 启用
响应
km.invert_x(1)
>>>

invert_y([state]) — GET/SET

命令
invert_y([state])
描述
反转 Y 轴（仅物理）
参数
() 查询; (0) 禁用; (1) 启用
响应
km.invert_y(1)
>>>

swap_xy([state]) — GET/SET

命令
swap_xy([state])
描述
交换 X 和 Y 轴（仅物理）
参数
() 查询; (0) 禁用; (1) 启用
响应
km.swap_xy(1)
>>>

键盘命令

键盘命令支持两种格式：数字 HID 码（如 4）或字符串名称（如 'a'、"enter"）。 支持的按键名称包括字母、数字、功能键、导航键和修饰键。详见规范。

down(key) — SET

命令
down(key)
参数
key: HID码或字符串（'a'、"shift"）
响应 (SET)
km.down('shift')
>>>

up(key) — SET

命令
up(key)
参数
key: HID码或字符串（'a'、"ctrl"）
响应 (SET)
km.up("ctrl")
>>>

press(key[,hold_ms[,rand_ms]]) — SET

命令
press(key[,hold_ms[,rand_ms]])
参数
  • key: HID码（0-255）或引用的按键名称
  • hold_ms: 按住时间（可选）。如果省略，使用随机 35-75ms（值会被记录日志）
  • rand_ms: 可选随机范围，添加到 hold_ms（0 = 无随机化）
  • 注意：持续时间会自动舍入到键盘的 bInterval 以进行 USB 同步
示例
km.press('a')
>>>

使用随机 35-75ms 按住时间（已记录）

km.press('d', 50)
>>>

精确按住 50ms

km.press('d', 50, 10)
>>>

50ms 基础 + 随机 0-10ms

string(text) — SET

命令
string(text)
描述

使用自动计时的队列按键输入输入 ASCII 字符串。自动处理大写字母和符号的 Shift。使用定时队列系统（无定时器插槽限制）。

参数
  • text: 要输入的 ASCII 字符串（最多 256 个字符）
  • 每个字符使用随机 35-75ms 按住时间（内部计时，不记录日志）
  • 字符间延迟：字符之间 10ms
示例
km.string("Hello")
>>> 
km.string("Test123!")
>>>
响应 (SET)
km.string("hello")
>>>

init() — SET

命令
init()
描述
清除键盘状态并释放按下的按键
响应 (SET)
km.init()
>>>

isdown(key) — GET

命令
isdown(key)
参数
key: HID码或字符串（'a'、"shift"）
响应 (GET)
km.isdown("ctrl")
>>> km.isdown(1)
>>>

如果按键按下返回 1，释放返回 0。

disable([key1,key2,...] | [key,mode]) — GET/SET

命令
disable([key1,key2,...] | [key,mode])
描述

禁用/启用键盘按键以阻止它们被发送到主机。

参数
  • () - 列出所有当前禁用的按键，格式为 (a,c,f,)（显示按键名称（如果可用），否则显示 HID 码）
  • (key1,key2,...) - 一次禁用多个按键。按键可以是 HID 码或引用的按键名称（例如，'a'、'f1'、'ctrl'）
  • (key,mode) - 启用或禁用单个按键。mode：1=禁用，0=启用
示例
km.disable()
>>> km.disable(a,c,f,)
>>> 
km.disable('a','c','f')
>>> 
km.disable('f1','alt','win')
>>> 
km.disable('a', 0)
>>> 
km.disable('a', 1)
>>> 
km.disable(4,6,9)
>>>

mask(key[,mode]) — GET/SET

命令
mask(key[,mode])
参数
key: HID码或字符串; mode: 0=关闭，1=开启
响应
km.mask('a',1)
>>>

remap(source,target) — GET/SET

命令
remap(source,target)
参数
source,target: 均可为HID码或字符串; target=0 清除映射（透传）
示例
km.remap('a','b')
>>> 
km.remap('a',0)
>>>

完整键盘按键参考

单字符字母区分大小写（'a' 输入小写，'A' 输入大写）。多字符特殊键不区分大小写（'f1'、'F1'、'ctrl'、'CTRL' 都相同）。
命令
press(key)
描述

键盘按键参考表。所有按键支持 HID 码或字符串名称。单字符字母区分大小写（小写输入小写，大写自动使用 Shift 输入大写）。多字符特殊键不区分大小写。

字母（HID 4-29）
按键名称HID正常输出Shift 输出
'a'4aA
'b'5bB
'c'6cC
'd'7dD
'e'8eE
'f'9fF
'g'10gG
'h'11hH
'i'12iI
'j'13jJ
'k'14kK
'l'15lL
'm'16mM
'n'17nN
'o'18oO
'p'19pP
'q'20qQ
'r'21rR
's'22sS
't'23tT
'u'24uU
'v'25vV
'w'26wW
'x'27xX
'y'28yY
'z'29zZ
响应
km.press('a')      # types "a" (HID 4)
km.press('A')      # types "A" (HID 4 + Shift)
数字和 Shift 变体（HID 30-39）
按键名称HID正常输出Shift 输出
'1'301!
'2'312@
'3'323#
'4'334$
'5'345%
'6'356^
'7'367&
'8'378*
'9'389(
'0'390)
响应
km.press('1')      # types "1" (HID 30)
km.down('shift')
km.press('1')      # types "!" (HID 30 + Shift)
km.up('shift')
控制键（HID 40-44）
按键名称HID正常输出Shift 输出
'enter', 'return'40Enter-
'escape', 'esc'41Escape-
'backspace', 'back'42Backspace-
'tab'43Tab-
'space', 'spacebar'44 -
响应
km.press('enter')  # Enter key (HID 40)
符号和 Shift 变体（HID 45-57）
按键名称HID正常输出Shift 输出
'minus', 'dash', 'hyphen'45-_
'equals', 'equal'46=+
'leftbracket', 'lbracket', 'openbracket'47[{
'rightbracket', 'rbracket', 'closebracket'48]}
'backslash', 'bslash'49\|
'nonus_hash'50#-
'semicolon', 'semi'51;:
'quote', 'apostrophe', 'singlequote'52'"
'grave', 'backtick', 'tilde'53`~
'comma'54,<
'period', 'dot'55.>
'slash', 'forwardslash', 'fslash'56/?
'capslock', 'caps'57Caps Lock-
响应
km.press('minus')  # types "-" (HID 45)
km.down('shift')
km.press('minus')  # types "_" (HID 45 + Shift)
km.up('shift')
功能键（HID 58-69）
按键名称HID正常输出Shift 输出
'f1'58F1-
'f2'59F2-
'f3'60F3-
'f4'61F4-
'f5'62F5-
'f6'63F6-
'f7'64F7-
'f8'65F8-
'f9'66F9-
'f10'67F10-
'f11'68F11-
'f12'69F12-
响应
km.press('f1')     # F1 key (HID 58)
系统键（HID 70-83）
按键名称HID正常输出Shift 输出
'printscreen', 'prtsc', 'print'70Print Screen-
'scrolllock', 'scroll'71Scroll Lock-
'pause', 'break'72Pause/Break-
'insert', 'ins'73Insert-
'home'74Home-
'pageup', 'pgup'75Page Up-
'delete', 'del'76Delete-
'end'77End-
'pagedown', 'pgdown', 'pgdn'78Page Down-
'right', 'rightarrow'79Right Arrow-
'left', 'leftarrow'80Left Arrow-
'down', 'downarrow'81Down Arrow-
'up', 'uparrow'82Up Arrow-
'numlock', 'num'83Num Lock-
响应
km.press('home')   # Home key (HID 74)
数字键盘（HID 84-99）
按键名称HID正常输出Shift 输出
'kpdivide', 'npdivide'84/-
'kpmultiply', 'npmultiply'85*-
'kpminus', 'npminus'86--
'kpplus', 'npplus'87+-
'kpenter', 'npenter'88Enter-
'kp1', 'np1'891-
'kp2', 'np2'902-
'kp3', 'np3'913-
'kp4', 'np4'924-
'kp5', 'np5'935-
'kp6', 'np6'946-
'kp7', 'np7'957-
'kp8', 'np8'968-
'kp9', 'np9'979-
'kp0', 'np0'980-
'kpperiod', 'kpdot', 'npperiod', 'npdot'99.-
响应
km.press('kp1')    # Numpad 1 (HID 89)
修饰键（HID 224-231）
按键名称（别名）HID正常输出Shift 输出
'leftctrl', 'lctrl', 'leftcontrol', 'lcontrol', 'ctrl', 'control'224Left Ctrl-
'leftshift', 'lshift', 'shift'225Left Shift-
'leftalt', 'lalt', 'alt'226Left Alt-
'leftgui', 'lgui', 'leftwin', 'lwin', 'gui', 'win', 'windows', 'super', 'meta', 'cmd', 'command'227Left GUI-
'rightctrl', 'rctrl', 'rightcontrol', 'rcontrol'228Right Ctrl-
'rightshift', 'rshift'229Right Shift-
'rightalt', 'ralt'230Right Alt-
'rightgui', 'rgui', 'rightwin', 'rwin', 'rightwindows'231Right GUI-

注意：通用名称（'ctrl'、'shift'、'alt'、'gui'）默认为左侧变体

响应
km.down('ctrl')    # Left Ctrl (HID 224)
km.up('ctrl')

流式

keyboard([mode[,period]]) — GET/SET

命令
keyboard([mode[,period]])
描述

流式传输键盘按键，使用人类可读的名称。模式 1=raw（物理输入），2=constructed frame（重映射/屏蔽后）；周期限制在 1-1000 帧。

参数
mode: 1=raw（原始），2=constructed frame（构造帧）; period: 1-1000 帧; () 查询; (0) 禁用
输出格式

输出格式：keyboard(raw,shift,'h') 或 keyboard(constructed,ctrl,shift,'a') - 修饰键和按键显示为名称（如 'shift', 'ctrl', 'h', 'a'）而不是 HID 数字。

响应 (GET)
km.keyboard(2,50)
>>>
响应 (SET)
km.keyboard(1,100)
>>>

buttons([mode[,period_ms]]) — GET/SET

命令
buttons([mode[,period_ms]])
参数
mode: 1/2（V4.036 起亦支持 3）; (0) 关闭。第二个参数（period）仅前缀流版本（V4.030 线、V4.036 起）接受且被忽略；V4.032 / V4.035 对两参 km.buttons(mode,period) 返回 ERR（tk-0437），请用单参 km.buttons(mode)。
响应 (GET)
km.buttons(2,25)
>>>
响应 (SET)
km.buttons(1,10)
>>>

启用后，设备发送非请求的按键流（行尾无 >>> 提示符），格式按固件不同：

V4.030 线 / V4.036 起 (mode 1/2):  6B 6D 2E <mask_u8> 0D 0A   ("km." + 掩码 + CRLF)
V4.036 起 (mode 3):            <mask_u8>                 (裸字节)
V4.024/026/032/035:           <mask_u8>                 (裸字节)
V30:                          DE AD 03 00 53 01 <id> <state>  (0x53 事件帧)

axis([mode[,period_ms]]) — GET/SET

命令
axis([mode[,period_ms]])
参数
1=raw（原始），2=constructed frame（构造帧）; period_ms: 1-1000ms; (0) 或 (0,0) 重置
输出格式

输出格式：raw(x,y,w) 或 mut(x,y,w)，其中 w 是滚轮增量。

响应 (GET)
km.axis(1,25)
>>>
响应 (SET)
km.axis(2,10)
>>>

mouse([mode[,period_ms]]) — GET/SET

命令
mouse([mode[,period_ms]])
模式
1=raw（原始），2=constructed frame（构造帧）; period_ms: 1-1000ms; () 查询; (0) 或 (0,0) 重置
响应 (GET)
km.mouse(2,25)
>>>
响应 (SET)
km.mouse(1,10)
>>>
流格式

设备发送 8 字节二进制帧（x,y 为 int16）：

km.mouse<8 bytes>
>>>

其他

help() — GET

命令
help()
描述
显示命令列表
响应 (GET)
km.help()
>>>

info() — GET

命令
info()
描述
报告系统信息：MAC 地址、MCU 温度（可用时）、RAM 统计、固件信息、CPU 和运行时间
响应 (GET)
km.info()
>>>

version() — GET

命令
version()
描述
报告固件版本
响应 (GET)
km.version()
>>>

device() — GET

命令
device()
描述
报告使用较多的设备：(keyboard)、(mouse) 或 (none)
响应 (GET)
km.device()
>>>

fault() — GET

命令
fault()
描述

返回存储的解析故障信息，包括 ESP32 MAC 地址、失败的端点地址、接口编号、失败原因和原始 HID 描述符字节。用于调试解析失败的设备。

响应 (GET)
km.fault()
>>>

reboot() — SET

命令
reboot()
描述
重启设备（响应后重启）
响应 (SET)
km.reboot()
>>>

serial([text]) — GET/SET

命令
serial([text])
描述

用于更改连接到 MAKCU 的鼠标或键盘的序列号。此更改是持久的，即使在未来的固件更新后也会保留。注意：MAKCU 不允许为不包含序列号的设备更改序列号。

参数
() 查询; (0) 重置; (text) 设置清理后的序列号
响应 (GET)
km.serial()
>>> km.serial("MAKCU001")
>>>

返回当前序列号。

响应 (SET)
km.serial("MAKCU001")
>>> 
km.serial(0)
>>>

回显 ACK。更改在固件更新后仍然保留。

log([level]) — GET/SET

命令
log([level])
参数
level: 0-5; 空参数时查询当前级别。设置会持续 3 个电源周期，然后自动禁用
响应
km.log(3)
>>>

echo([enable]) — GET/SET

命令
echo([enable])
参数
enable: 1=开启，0=关闭; 空参数时查询
响应
km.echo(1)
>>>

baud([rate]) — GET/SET

命令
baud([rate])
参数
rate: 115200 – 4000000; 0=重置为默认115200; 空参数时查询
响应 (GET)
km.baud(115200)
>>>
响应 (SET)
km.baud(921600)
>>>

立即生效；主机需以新波特率重新打开串口。

bypass([mode]) — GET/SET

命令
bypass([mode])
描述

阻止鼠标端点发送到 USB 1，所有其他端点将正常通过。可在未连接 USB 设备的情况下工作。

参数
  • () - 查询当前状态
  • (0) - 关闭（恢复 USB 写入，禁用遥测）
  • (1) - 鼠标绕过（启用 km.mouse(1,1) 并禁用 USB 写入）
  • (2) - 键盘绕过（启用 km.keyboard(1,1) 并禁用 USB 写入）
响应 (GET)
km.bypass()
>>> km.bypass(0)
>>>

如果未检测到设备，会警告 (no mouse) 或 (no keyboard)

响应 (SET)
km.bypass(1)
>>> 
km.bypass(2)
>>> 
km.bypass(0)
>>>

hs([enable]) — GET/SET

命令
hs([enable])
描述
USB 高速兼容性（用于可能不正确报告轮询率的设备）*持久化设置
参数
() 查询; (1/0) 启用/禁用
响应
km.hs(1)
>>>

led([target[,mode[,times,delay_ms]]]) — GET/SET

命令
led([target[,mode[,times,delay_ms]]])
描述

控制设备和主机两侧的 LED 和 RGB 状态。支持查询、控制和闪烁功能。

查询
  • led() - 查询设备 LED 状态（向后兼容）
  • led(1) - 查询设备 LED 状态
  • led(2) - 查询主机 LED 状态（通过 UART）
  • 返回：(device,off)、(device,on)、(device,slow_blink)、(device,fast_blink)、(host,off)、(host,on) 等
控制
  • led(0) - 关闭设备 LED（向后兼容）
  • led(1) - 打开设备 LED（向后兼容，但与查询冲突 - 使用 led(1,1) 进行显式控制）
  • led(1, 0) - 关闭设备 LED
  • led(1, 1) - 打开设备 LED
  • led(2, 0) - 关闭主机 LED（通过 UART）
  • led(2, 1) - 打开主机 LED（通过 UART）
  • Target: 1 = 设备 LED，2 = 主机 LED（USB 主机侧，通过 UART 控制）
  • Mode: 0 = 关闭，1 = 打开
闪烁
  • led(1, times, delay_ms) - 闪烁设备 LED（例如，led(1, 3, 200) = 3 次闪烁，每次 200ms）
  • led(2, times, delay_ms) - 闪烁主机 LED（例如，led(2, 5, 100) = 5 次闪烁，每次 100ms）
  • Flash parameters: times = 闪烁次数（默认 1），delay_ms = 闪烁之间的延迟（毫秒）（默认 100ms，最大 5000ms）
示例
km.led()
>>> km.led(device,on)
>>> 
km.led(2)
>>> km.led(host,off)
>>> 
km.led(1, 0)
>>> 
km.led(2, 1)
>>> 
km.led(1, 3, 200)
>>> 
km.led(2, 5, 100)
>>>

release([timer_ms]) — GET/SET

命令
release([timer_ms])
描述

自动释放监控系统。持续监控独立的锁定、按键和键状态。当计时器到期时，仅释放仍处于活动状态的相应值（不是全部）。该设置会持久保存到存储中，并在启动/引导时自动启用。`()` 获取状态（0=禁用，否则为时间 ms）；`(timer_ms)` 设置计时器 500-300000ms（5 分钟），(0) 禁用。

参数
() 获取状态; (timer_ms) 设置计时器 500-300000ms，(0) 禁用
响应 (GET)
km.release()
>>>
响应 (SET)
km.release(5000)
>>> 
km.release(0)
>>>

screen([W,H]) — GET/SET

命令
screen([width,height])
参数
() 查询; (width,height) 设置虚拟屏幕尺寸
响应 (GET)
km.screen(1920,1080)
>>>
响应 (SET)
km.screen(2560,1440)
>>>

波特率变更（传统）

用途
通过二进制帧设置 UART 波特率（无 ASCII 指令）。
帧格式
DE AD <lenLE:2> <cmd:0xA5> <baud_rate:LE32>
示例 (115200)
DE AD 05 00 A5 00 C2 01 00

解析：DE AD ｜ 05 00（长度=5）｜ A5（命令）｜00 C2 01 00（115200 小端）

可用性
V4.039 前均不可用。V4.032 / V4.035 无此 handler，返回 FF。V4.030 与 V4.036–V4.038 有 handler，但 handler 要求 payload 长度为 4（不含命令字节），而 AIO 发的是 len=5 的整帧，因此被拒（回 FF）并吞掉紧随其后的下一条命令的首字节（tk-0454）。V4.039 起修复可靠可用。V30 / V4.024 / V4.026 不支持该帧。

V2 API (二进制)

所有二进制命令使用相同的帧结构。帧格式在下方说明，后续命令示例仅显示命令字节和负载数据。
RX（主机 → 设备）
  • 帧格式：[0x50] [CMD] [LEN_LO] [LEN_HI] [PAYLOAD...]
  • 0x50 - 帧起始字节（固定）
  • CMD - 命令字节（0x01-0xFF）
  • LEN_LO / LEN_HI - 负载长度（小端序，16位）
  • PAYLOAD - 命令特定数据（可变长度）
TX（设备 → 主机）
  • 设置命令 (SET)：返回 [0x50] [CMD] [LEN_LO] [LEN_HI] [status:u8]，其中 0x00 表示成功 (OK)，0x01 表示错误 (ERR)
  • 查询命令 (GET)：返回 [0x50] [CMD] [LEN_LO] [LEN_HI] [PAYLOAD...]，包含原始值字节或结构化数据
  • 流式命令：返回原始 HID 帧字节（无文本格式），格式为 [0x50] [CMD] [LEN_LO] [LEN_HI] [PAYLOAD...]
  • 数据格式：多字节值使用小端序（little-endian）。示例：查询波特率（命令 0xB1，无负载）返回 [0x50] [0xB1] [0x04] [0x00] [0x00] [0xC2] [0x01] [0x00]，其中 0x00C20100 = 115200（小端序）
  • 在后续命令示例中，我们仅显示：[CMD] [PAYLOAD...]

鼠标

单个按键 (GET/SET)

命令
left(0x08) | right(0x11) | middle(0x0A) | side1(0x12) | side2(0x13)
描述
控制单个鼠标按键 - 状态：0=释放 1=按下 2=静默释放；查询返回：0=无 1=原始 2=注入 3=两者
参数
() 查询; (state) 设置状态。state: 0=释放（发送帧），1=按下，2=静默释放（设为0但不发送帧）
响应 (GET)
[0x08]
Response: [0x08] [state:u8]

返回锁定状态：0=无，1=原始，2=注入，3=两者。

响应 (SET)
[0x08] [state:u8]
Response: [0x08] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

点击调度 (SET)

命令
[0x04]
描述
调度点击 - 按钮 1-5，次数 1-255，延迟 ms（0=随机 35-75ms）
参数
button: 1-5（左、右、中、侧1、侧2）；count: 1-255；delay_ms: 延迟毫秒，0=随机 35-75ms
响应 (SET)
[0x04] [button:u8] [count:u8] [delay_ms:u8]
Response: [0x04] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

turbo() (GET/SET)

命令
[0x17]
描述
鼠标按键 1-5 的连发 - 延迟：1-5000ms 或 (button) 随机 35-75ms - (0) 禁用所有
参数
() 返回活动设置; (button) 随机延迟; (button,delay_ms) 设置延迟；(0) 禁用所有
响应 (GET)
[0x17]
Response: [0x17] [btn1-5_delay:u16×5]

返回 10 字节：按键 1-5 的 5 个延迟（每个 u16）。

响应 (SET)
[0x17] [button:u8] [delay_ms:u16]
Response: [0x17] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

鼠标移动

move(dx,dy[,segments[,cx1,cy1]]) — SET (0x0D)

命令
[0x0D]
描述
相对移动并带贝塞尔曲线
参数
dx,dy: 相对移动距离（int16）；segments: 贝塞尔分段数；cx1,cy1: 控制点1（int8）
响应 (SET)
[0x0D] [x:i16] [y:i16] [segments:u8] [cx1:i8] [cy1:i8]
Response: [0x0D] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

moveto(x,y[,segments[,cx1,cy1[,cx2,cy2]]]) — SET (0x0E)

命令
[0x0E]
描述
绝对移动并带贝塞尔曲线
参数
x,y: 绝对位置（int16）；segments: 贝塞尔分段数；cx1,cy1,cx2,cy2: 控制点（int16）
响应 (SET)
[0x0E] [x:i16] [y:i16] [segments:u8] [cx1:i16] [cy1:i16] [cx2:i16] [cy2:i16]
Response: [0x0E] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

wheel(delta) — SET (0x18)

命令
[0x18]
描述
滚轮步数
参数
delta: 滚轮增量（int8，正值向上，负值向下）
响应 (SET)
[0x18] [delta:i8]
Response: [0x18] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

pan([steps]) — GET/SET (0x0F)

命令
[0x0F]
描述
水平滚动/平移步数
参数
() 查询待处理的平移；(steps) 设置平移步数（int8）
响应 (GET)
[0x0F]
Response: [0x0F] [pending:i8]
响应 (SET)
[0x0F] [steps:i8]
Response: [0x0F] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

swap_xy([enable]) — GET/SET (0x15)

命令
[0x15]
描述
交换 X 和 Y 轴（仅物理） - 0=禁用，1=启用
参数
() 查询; (enable) 设置。enable: 0=禁用，1=启用
响应 (GET)
[0x15]
Response: [0x15] [enabled:u8]

返回 0=禁用，1=启用。

响应 (SET)
[0x15] [enable:u8]
Response: [0x15] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

tilt([steps]) — GET/SET (0x16)

命令
[0x16]
描述
倾斜/z轴步数
参数
() 查询待处理的倾斜；(steps) 设置倾斜步数（int8）
响应 (GET)
[0x16]
Response: [0x16] [pending:i8]
响应 (SET)
[0x16] [steps:i8]
Response: [0x16] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

silent(x,y) — SET (0x14)

命令
[0x14]
描述
移动然后静默左键点击
参数
x,y: 移动到的位置（int16）
响应 (SET)
[0x14] [x:i16] [y:i16]
Response: [0x14] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

鼠标高级

catch_<target>([mode]) — GET/SET (0x03)

命令
[0x03]
描述
捕获模式 - 0=关闭，1=注入，2=锁定
参数
() 查询; (mode) 设置模式。mode: 0=关闭，1=注入，2=锁定
响应 (GET)
[0x03]
Response: [0x03] [mode:u8]
响应 (SET)
[0x03] [mode:u8]
Response: [0x03] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

getpos() — GET (0x05)

命令
[0x05]
描述
获取当前鼠标位置
参数
无参数
响应 (GET)
[0x05]
Response: [0x05] [x:i16] [y:i16]

返回当前指针位置（int16 坐标）。

invert_x([enable]) — GET/SET (0x06)

命令
[0x06]
描述
反转 X 轴（仅物理） - 0=禁用，1=启用
参数
() 查询; (enable) 设置。enable: 0=禁用，1=启用
响应 (GET)
[0x06]
Response: [0x06] [enabled:u8]

返回 0=禁用，1=启用。

响应 (SET)
[0x06] [enable:u8]
Response: [0x06] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

invert_y([enable]) — GET/SET (0x07)

命令
[0x07]
描述
反转 Y 轴（仅物理） - 0=禁用，1=启用
参数
() 查询; (enable) 设置。enable: 0=禁用，1=启用
响应 (GET)
[0x07]
Response: [0x07] [enabled:u8]

返回 0=禁用，1=启用。

响应 (SET)
[0x07] [enable:u8]
Response: [0x07] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

lock_<target>([state]) — GET/SET (0x09)

命令
[0x09]
描述
锁定按钮或轴 - state: 1=锁定，0=解锁；target 是命令的一部分（mx, my, mw, mx+, mx-, my+, my-, mw+, mw-, ml, mm, mr, ms1, ms2）
参数
() 查询; (state) 设置状态。state: 1=锁定，0=解锁
目标
轴：mx, my, mw（全部）；mx+, mx-, my+, my-, mw+, mw-（方向）；按钮：ml, mm, mr, ms1, ms2
响应 (GET)
[0x09]
Response: [0x09] [locked:u8]

返回 1=锁定，0=解锁。

响应 (SET)
[0x09] [state:u8]
Response: [0x09] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

mo(buttons,x,y,wheel,pan,tilt) — SET (0x0B)

命令
[0x0B]
描述
发送原始鼠标帧 - 按键掩码镜像状态，轴为一次性
参数
buttons: 按键掩码（u8）；x,y: 位置（i16）；wheel,pan,tilt: 轴值（i8）
响应 (SET)
[0x0B] [buttons:u8] [x:i16] [y:i16] [wheel:i8] [pan:i8] [tilt:i8]
Response: [0x0B] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

remap_button([src,dst]) — GET/SET (0x10)

命令
[0x10]
描述
重映射鼠标按键（1-5：左、右、中、侧1、侧2）；dst=0 清除 src
参数
() 显示映射; (0) 重置所有; (src,dst) 映射按键 src→dst; (src,0) 清除 src
响应 (GET)
[0x10]
Response: [0x10] [map1-5:u8×2×5]

返回 10 字节：5 个映射，每个 2 字节（src,dst）。

响应 (SET)
[0x10] [src:u8] [dst:u8]
Response: [0x10] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

remap_axis([inv_x,inv_y,swap]) — GET/SET (0x19)

命令
[0x19]
描述
重映射鼠标轴（仅物理） - 原子性设置所有三个标志：inv_x, inv_y, swap（每个 0=禁用，1=启用）
参数
  • () - 查询当前设置
  • (0) - 重置所有轴映射
  • (inv_x,inv_y,swap) - 设置所有三个标志（每个 0 或 1）
响应 (GET)
[0x19]
Response: [0x19] [inv_x:u8] [inv_y:u8] [swap:u8]

返回 3 字节：inv_x, inv_y, swap（每个 0=禁用，1=启用）。

响应 (SET)
[0x19] [inv_x:u8] [inv_y:u8] [swap:u8]
Response: [0x19] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。原子性设置所有三个标志。

[0x19] [0x00]
Response: [0x19] [status:u8]

重置所有轴映射（将所有标志设为 0）。

键盘

键盘命令使用数字 HID 码（u8）。支持的 HID 码范围：0x00-0xFF。详见完整按键参考。

disable([key1,key2,...] | [key,mode]) — GET/SET (0xA1)

命令
[0xA1]
描述
禁用按键 - key: HID 码 - mode: 0=启用 1=禁用 - 可禁用多个按键
参数
() 列出禁用的按键; (key1,key2,...) 禁用多个按键; (key,mode) 启用/禁用单个按键
响应 (GET)
[0xA1]
Response: [0xA1] [disabled_keys:u8×N]

返回禁用的 HID 码列表。

响应 (SET)
[0xA1] [key1:u8]...[keyN:u8]
Response: [0xA1] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

down(key) — SET (0xA2)

命令
[0xA2]
描述
按下按键
参数
key: HID 码（u8）
响应 (SET)
[0xA2] [key:u8]
Response: [0xA2] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

init() — SET (0xA3)

命令
[0xA3]
描述
清除键盘状态
参数
无参数
响应 (SET)
[0xA3]
Response: [0xA3] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

isdown(key) — GET (0xA4)

命令
[0xA4]
描述
查询按键是否按下
参数
key: HID 码（u8）
响应 (GET)
[0xA4] [key:u8]
Response: [0xA4] [is_down:u8]

返回 0=释放，1=按下。

mask(key[,mode]) — SET (0xA6)

命令
[0xA6]
描述
掩码按键 - key: HID 码 - mode: 0=关闭 1=开启
参数
key: HID 码（u8）；mode: 0=关闭掩码，1=开启掩码
响应 (SET)
[0xA6] [key:u8] [mode:u8]
Response: [0xA6] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

press(key[,hold_ms[,rand_ms]]) — SET (0xA7)

命令
[0xA7]
描述
点击按键 - key: HID 码 - hold_ms: 省略时随机 35-85ms - rand_ms 可选
参数
key: HID 码（u8）；hold_ms: 按住时间（u8，0=随机 35-85ms）；rand_ms: 随机化（u8，可选）
响应 (SET)
[0xA7] [key:u8] [hold_ms:u8] [rand_ms:u8]
Response: [0xA7] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

remap(source,target) — SET (0xA8)

命令
[0xA8]
描述
重映射键码 - 两者：HID 码；target=0 清除重映射（直通）
参数
source: 源 HID 码（u8）；target: 目标 HID 码（u8），0=清除重映射
响应 (SET)
[0xA8] [source:u8] [target:u8]
Response: [0xA8] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

string(text) — SET (0xA9)

命令
[0xA9]
描述
输入 ASCII 字符串 - 最大 256 字符
参数
text: ASCII 字节数组（u8×N，最大 256 字节）
响应 (SET)
[0xA9] [text:u8×N]
Response: [0xA9] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

up(key) — SET (0xAA)

命令
[0xAA]
描述
释放按键
参数
key: HID 码（u8）
响应 (SET)
[0xAA] [key:u8]
Response: [0xAA] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

流式

buttons([mode[,period_ms]]) — GET/SET (0x02)

命令
[0x02]
描述
流式输出按键状态 - 模式：1=原始 2=修改；周期：1-1000ms（四舍五入到 bInterval）；需要波特率 >= 1M；仅在帧变化时输出
参数
() 查询; (mode) 设置模式; (mode,period_ms) 设置模式和周期。mode: 1=原始 2=修改；period: 1-1000ms
响应 (GET)
[0x02]
Response: [0x02] [mode:u8] [period:u8]

返回当前流式模式和周期。

响应 (SET)
[0x02] [mode:u8] [period:u8]
Response: [0x02] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

流格式

设备在按键变化时发送 2 字节二进制帧：

[0x02] [buttons_lo:u8] [buttons_hi:u8]

按键掩码：位 0=左键，1=右键，2=中键，3=侧键1，4=侧键2

axis([mode[,period_ms]]) — GET/SET (0x01)

命令
[0x01]
描述
流式输出 x/y/滚轮轴增量 - 模式：1=原始 2=修改；周期：1-1000ms（四舍五入到 bInterval）；需要波特率 >= 1M；仅在帧变化时输出
参数
() 查询; (mode) 设置模式; (mode,period_ms) 设置模式和周期。mode: 1=原始 2=修改；period: 1-1000ms
响应 (GET)
[0x01]
Response: [0x01] [mode:u8] [period:u8]
响应 (SET)
[0x01] [mode:u8] [period:u8]
Response: [0x01] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

流格式

设备在轴变化时发送 6 字节二进制帧：

[0x01] [dx:i16] [dy:i16] [wheel:i8]

mouse([mode[,period_ms]]) — GET/SET (0x0C)

命令
[0x0C]
描述
流式输出完整鼠标数据 - 模式：1=原始 2=修改；周期：1-1000ms（四舍五入到 bInterval）；需要波特率 >= 1M；仅在帧变化时输出
参数
() 查询; (mode) 设置模式; (mode,period_ms) 设置模式和周期。mode: 1=原始 2=修改；period: 1-1000ms
响应 (GET)
[0x0C]
Response: [0x0C] [mode:u8] [period:u8]
响应 (SET)
[0x0C] [mode:u8] [period:u8]
Response: [0x0C] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

流格式

设备在鼠标数据变化时发送 8 字节二进制帧：

[0x0C] [buttons:u8] [dx:i16] [dy:i16] [wheel:i8] [pan:i8] [tilt:i8]

keyboard([mode[,period_ms]]) — GET/SET (0xA5)

命令
[0xA5]
描述
流式输出键盘 - 模式：1=原始 2=修改；周期：1-1000ms（四舍五入到 bInterval）；需要波特率 >= 1M；仅在帧变化时输出
参数
() 查询; (mode) 设置模式; (mode,period_ms) 设置模式和周期。mode: 1=原始 2=修改；period: 1-1000ms
响应 (GET)
[0xA5]
Response: [0xA5] [mode:u8] [period:u8]
响应 (SET)
[0xA5] [mode:u8] [period:u8]
Response: [0xA5] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

流格式

设备在键盘数据变化时发送 15 字节二进制帧：

[0xA5] [modifiers:u8] [keys:u8×14]

修饰符字节：ctrl、shift、alt、gui 等的位标志。按键数组：最多 14 个 HID 码。

其他

baud([rate]) — GET/SET (0xB1)

命令
[0xB1]
描述
设置/获取 UART0 波特率 - 0=默认 (115200)
参数
() 查询; (rate) 设置波特率（u32），0=默认 115200，范围：115200-4000000
响应 (GET)
[0xB1]
Response: [0xB1] [rate:u32]

返回当前波特率（uint32，小端序）。

响应 (SET)
[0xB1] [rate:u32]
Response: [0xB1] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。更改是持久的。

bypass([mode]) — GET/SET (0xB2)

命令
[0xB2]
描述
旁路模式 - 0=关闭，1=鼠标，2=键盘；禁用 USB 写入，将原始数据流式传输到 COM2
参数
() 查询; (mode) 设置模式。mode: 0=关闭，1=鼠标，2=键盘；需要波特率 >= 1M
响应 (GET)
[0xB2]
Response: [0xB2] [mode:u8]
响应 (SET)
[0xB2] [mode:u8]
Response: [0xB2] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

echo([enable]) — GET/SET (0xB4)

命令
[0xB4]
描述
切换 UART 回显
参数
() 查询; (enable) 设置回显。enable: 0=禁用，1=启用
响应 (GET)
[0xB4]
Response: [0xB4] [enabled:u8]
响应 (SET)
[0xB4] [enable:u8]
Response: [0xB4] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。当回显禁用时，大多数设置命令不会回显其输入。

hs([enable]) — GET/SET (0xB7)

命令
[0xB7]
描述
USB 高速兼容性 - 0=禁用，1=启用（持久）
参数
() 查询; (enable) 设置高速模式。enable: 0=禁用，1=启用
响应 (GET)
[0xB7]
Response: [0xB7] [enabled:u8]
响应 (SET)
[0xB7] [enable:u8]
Response: [0xB7] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。设置在重启后仍然保留。

led([...]) — GET/SET (0xB9)

命令
[0xB9]
描述
LED 控制 - target: 1=设备 2=主机；mode: 0=关闭 1=开启；state: 0=关闭 1=开启 2=慢闪 3=快闪
参数
() 查询设备; (1) 查询设备; (2) 查询主机; (0) 设备关闭; (1) 设备开启; (target,mode) 控制; (target,times,delay_ms) 闪烁
响应 (GET)
Query device: [0xB9]
Query host:   [0xB9] [0x02]
Response:    [0xB9] [target:u8] [state:u8]

状态：0=关闭，1=开启，2=慢闪，3=快闪

响应 (SET)
Set:    [0xB9] [target:u8] [mode:u8]
Response: [0xB9] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

闪烁
Flash:  [0xB9] [target:u8] [times:u32] [delay_ms:u32]
Response: [0xB9] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。控制 LED 和 RGB。次数：1-255，延迟：100-5000ms

log([level]) — GET/SET (0xBA)

命令
[0xBA]
描述
设置/获取日志级别 - 0-5。设置会持续 3 个电源周期，然后自动禁用
参数
() 查询; (level) 设置日志级别。level: 0-5（0=无，5=调试）。设置会持续 3 个电源周期，然后自动禁用
响应 (GET)
[0xBA]
Response: [0xBA] [level:u8]
响应 (SET)
[0xBA] [level:u8]
Response: [0xBA] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

release([timer_ms]) — GET/SET (0xBC)

命令
[0xBC]
描述
自动释放定时器 - 到期时释放所有活动的锁定/按键/键
参数
() 获取状态; (timer_ms) 设置定时器 500-300000ms（5 分钟），(0) 禁用
响应 (GET)
[0xBC]
Response: [0xBC] [timer_ms:u32]

如果禁用返回 0，否则返回时间（毫秒）。

响应 (SET)
[0xBC] [timer_ms:u32]
Response: [0xBC] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

screen([W,H]) — GET/SET (0xBD)

命令
[0xBD]
描述
设置/获取虚拟屏幕尺寸
参数
() 查询; (width,height) 设置虚拟屏幕尺寸（int16）
响应 (GET)
[0xBD]
Response: [0xBD] [width:i16] [height:i16]
响应 (SET)
[0xBD] [width:i16] [height:i16]
Response: [0xBD] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。

serial([text]) — GET/SET (0xBE)

命令
[0xBE]
描述
USB 序列号操作 - ASCII 字节
参数
() 查询; (0) 重置; (text) 设置清理后的序列号（ASCII 字节数组）
响应 (GET)
[0xBE]
Response: [0xBE] [serial:u8×N]

返回当前序列号（ASCII 字节）。

响应 (SET)
[0xBE] [text:u8×N]
Response: [0xBE] [status:u8]

成功返回 0x00 (OK)，错误返回 0x01 (ERR)。更改在固件更新后仍然保留。

device() — GET (0xB3)

命令
[0xB3]
描述
返回活动设备类型
参数
无参数
响应 (GET)
[0xB3]
Response: [0xB3] [type:u8]

类型：0=无，1=键盘，2=鼠标

fault() — GET (0xB5)

命令
[0xB5]
描述
获取存储的解析故障信息（与 0xE8 相同）
参数
无参数
响应 (GET)
[0xB5]
Response: [0xB5] [parse_fault_t struct]

返回包含 MAC、端点、原因和原始描述符字节的 parse_fault_t 结构。

info() — GET (0xB8)

命令
[0xB8]
描述
系统/设备信息 - 键值格式：MAC1、MAC2、TEMP、RAM、FW、CPU、UP、VID、PID、VENDOR、MODEL、ORIGINAL_SERIAL、SPOOFED_SERIAL、MOUSE_BINT、KBD_BINT、FAULT
参数
无参数
响应 (GET)
[0xB8]
Response: [0xB8] [field_count:u8] [fields...]

返回包含系统/设备信息键值对的结构化二进制数据。设备信息在首次获取后缓存。

reboot() — SET (0xBB)

命令
[0xBB]
描述
响应后重启设备
参数
无参数
响应 (SET)
[0xBB]
Response: [0xBB] [status:u8]

始终返回 0x00（成功）。设备在发送响应后重启。

version() — GET (0xBF)

命令
[0xBF]
描述
获取固件版本信息
参数
无参数
响应 (GET)
[0xBF]
Response: [0xBF] [version:u8×N]

返回固件版本（ASCII 字节）。