#MoonHID

#预期使用场景

1. 自制键盘：检查按键数组、修饰键和 LED 输出报告的布局。
2. 鼠标与手柄：解释按钮、相对位移、摇杆轴和带 Report ID 的报告。
3. 通用设备工具：在 CI 或浏览器中检查保存的描述符与报告样例，复现解析问题。

#当前状态

#快速运行

git clone https://github.com/We1chan/moonhid.git
cd moonhid
moon run cmd/main

#文件命令行工具

moon run cmd/moonhid --target native -- inspect descriptor.hex
moon run cmd/moonhid --target native -- decode --kind input descriptor.hex report.hex
moon run cmd/moonhid --target js -- inspect descriptor.hex

#浏览器检查器

node scripts/build-web.mjs
python3 scripts/serve-web.py

#WebHID 实时输入

#API 示例

///|
test "README: decode one relative axis" {
  let descriptor = b"\x05\x01\x09\x30\x15\x81\x25\x7f\x75\x08\x95\x01\x81\x06"
  let layout = match @moonhid.compile_descriptor(descriptor) {
    Ok(layout) => layout
    Err(_) => fail("descriptor rejected")
  }
  let report = match @moonhid.decode_report(layout, @moonhid.Input, b"\xff") {
    Ok(report) => report
    Err(_) => fail("report rejected")
  }
  assert_eq(report.values[0].value, -1L)
  assert_eq(report.values[0].usage, Some({ page: 1, id: 0x30, }))
}

#支持范围与边界

• 支持 Input / Output / Feature、Usage / Usage 范围 / 32 位扩展 Usage、 Logical / Physical 范围、Unit / Unit Exponent、Report Size / Count / ID、Global Push / Pop， 并保留 Collection 的类型、Usage、父索引与字段所属集合。
• 零长度短项的数据按 0 解释；零长度 Collection 表示 Physical，零长度 Main flags 表示 0。 Report ID 0 和 Report Count 0 仍拒绝；Report Size 0 不能用于定义字段。
• 变量字段按声明顺序对应 Usage，数量不足时重复最后一个 Usage。 Usage 按区间保留，不展开大范围；数组值按 value - logical_min 索引 Usage 序列；未映射的值保留原值。
• 保留填充字段的布局，解码输出省略 Constant 字段；超宽值存入 opaque_values，不进行整数或 Usage 索引解释；保留超出逻辑范围的值， 通过 in_logical_range 和 is_null 区分异常值与声明的 Null State。
• 字段位偏移从报告载荷的第 0 位计算，不含 Report ID 字节；解码输入必须包含 描述符要求的 ID 前缀，并且长度必须精确匹配，不能带额外传输层前缀或尾部字节。
• String / Designator 索引和区间保存为字段与 Collection 元数据，随后清空本地状态； Delimiter 按 Linux 的公共 Usage + 第一个集合规则解码，后续集合保存在 alternate_usages。 嵌套、无开启的关闭和未闭合返回 delimiter；索引范围错误返回 local_range， 每类索引最多 1024 段（local_limit），优选与备选 Usage 合计最多 1024 段（usage_limit）。 长项仅支持原始分词，布局编译会拒绝；保留字也明确报错；Buffered Bytes 返回 buffered_bytes。Physical 范围和 Unit 全局项允许存在， 解码返回原始整数，不进行物理单位换算。核心保留数字 Usage；页面只补充常见 Usage 名称， 不是完整 HID Usage Tables 数据库。
• 限制：描述符最多 65536 字节，最多 4096 个 Main 报告字段，整数每值 1..32 位，超过 32 位的 Data Variable 字段按原始字节解码， Constant 字段也允许超宽；Data Array 位宽仍限 1..32。 每报告最多 65536 位，字段元素数量由报告总位数约束（最多 65536 个值），Usage 最多 1024 个区间，单区间可覆盖同一 page 的全部 65536 个 ID， Collection 最多 4096 项，Collection 与 Global 栈深度最多 64。Global Push/Pop 要求平衡。 Unit Exponent 支持 -8..7 的四位编码及常见符号扩展编码；保留 Unit 的系统与保留位。 Physical 缺少任一端点或两端均为 0 时，有效范围采用 Logical 范围，原声明仍可查询。
• 核心库处理离线字节；网页可选 WebHID 只接收 Input，不发送 Output/Feature。 不提供驱动安装或 Boot Protocol 切换；合成样例测试不能代表已兼容所有 HID 设备。

#开发

moon check --target all --deny-warn
moon build
moon test
moon test --target native
moon test --target js # 需要 Node.js
node scripts/build-web.mjs
node scripts/test-web.mjs
moon info
moon fmt --check

#协议与参考

• USB-IF HID 1.11
• Linux 内核：HID report descriptors