HID 报告描述符生成工具说明

在前文 HID 报告描述符 中提到过 USB 官网提供的 HID 报告描述符生成工具，https://www.usb.org/document-library/hid-descriptor-tool 该工具提供以下功能：

  • 创建新的 HID 报告描述符。
  • 编辑已存在的 HID 报告描述符
  • 验证描述符
  • 导出不同格式 ( .hid、.dat、 .txt、.inc、.h)

通过本文你可以获取下面知识

  • 使用 HID 报告描述符生成工具
  • 增加 USAGE 内容

使用 链接到标题

该工具只能在 windows 上工作，下载后解压缩，双击 dt.exe 看到如下界面

dt

创建报告描述符 链接到标题

在 dt.exe 的界面左侧 HID Items 栏中是一系列的 Item，通过双击需要的 Item 添加到右侧 Report Descriptor 中。添加过程中该工具会根据不同的 Item 让你选择或者填入值。以HID 报告描述符 一文为例

USAGE_PAGE ( Consumer Devices)
USAGE ( Consumer Control)
COLLECTION ( Application)
    REPORT_ID ( 1)
    LOGICAL_MINIMUM ( 0)
    LOGICAL_MAXIMUM ( 1)
    REPORT_SIZE ( 1)
    REPORT_COUNT ( 1)
    USAGE ( Play/Pause)
    INPUT ( Data,Var,Abs)
    USAGE ( Volume Up)
    INPUT ( Data,Var,Abs)
    USAGE ( Volume Down)
    INPUT ( Data,Var,Abs)
    USAGE ( Scan Next Track)
    INPUT ( Data,Var,Abs)
    USAGE ( Scan Previous Track)
    INPUT ( Data,Var,Abs)
    REPORT_COUNT ( 1)
    REPORT_SIZE ( 3)
    INPUT ( Cnst,Var,Abs)
END_COLLECTION

选择有代表性的进行说明： USAGE_PAGE ( Consumer Devices), 双击 USAGE_PAGE，在弹出的对话框中双击 Consumer Devices usage_page

USAGE ( Consumer Control), 双击 USAGE，在弹出的对话框中双击 Consumer Control page dt.exe 会根据你最近一次的 USAGE PAGE 给出 PAGE ID，此时也可以点击 Change Page 按钮选择所需 USAGE_PAGE change

COLLECTION ( Application), 双击 COLLECTION，在弹出的对话框中选中 Application 后点 OK collection

REPORT_ID ( 1), 双击 REPORT_ID，在弹出的对话框中输入 REPORT_ID 的值后点 OK. LOGICAL_MINIMUM, LOGICAL_MAXIMUM, REPORT_SIZE, REPORT_COUNT 这些都一样，通过填值完成。 reportid

INPUT ( Data,Var,Abs)，双击 INPUT，在弹出的对话框中对不同的 bit 进行选择配置，完成后点 OK input

END_COLLECTION, 不存在可选数据，直接双击 END_COLLECTION 即可完成 按照上面的方法将所有的 Item 加完后的结果如下： show

校验 链接到标题

点击 Parser Descriptor 就会显示解析的结果 verify 如果描述符有错，会给予提示，例如把例子中的 END_COLLECTION 去掉，再进行校验就会有如下提示： verify_fail

编辑 链接到标题

通过 File->Open 打开已存在的。hid 文件，然后在 Report Discriptor 中进行编辑。注意该软件只能打开。hid 文件

  • 修改：双击要修改的 Item，在弹出的对话框中修改值
  • 删除：选中要删除的 Item，按键盘的 Delete 按建
  • 插入：选中要插入条目的位置，再双击左侧 HID Items 栏位中想要插入的 Item。注意插入的位置是选中条目的前面。
  • 复制：选中要复制的 Item，做 Ctrl+C
  • 粘贴：选中要插入条目的位置，做 Ctrl+V。注意粘贴的位置是选中条目的前面。

保存和导出 链接到标题

不同的情况的处理方式如下：

  • 新建的报告描述符: 只能通过 File->Save As 保存为 hid，将来可以再次打开编辑
  • 被打开的 hid 文件：修改后通过 File->Save 保存
  • 导出文件：通过 File->Save As，按照需要选择要保存的格式 save

增加 Usage 内容 链接到标题

该工具从官网的信息看是 2001 年发布的，已经非常"老"了， 这导致后面更新的 USB hud Spec 描述的 Usage 通过该软件无法加入，不过该软件做了很好的扩展，可以对其进行修改。

增加 Usage ID 链接到标题

在我创建 consumer 设备时，要加入 USAGE ( Play/Pause) ，发现工具中无该选项，通过下面方式进行添加: 在 hut 中查找 Play/Pause 的 Usage ID，可以知道 Usage ID=CC 对应的是 Play/Pause id 在 dt.exe 所在的目录下打开 consume.upg, 可以看到老的 spec 中 CC-DF 都是保留字段

CA    Tracking Increment
CB    Tracking Decrement
CC-DF    Reserved
E0    Volume
E1    Balance

将下面内容加入到该文件，重开 dt.exe 就可以看到 USAGE ( Play/Pause) 了

CA    Tracking Increment
CB    Tracking Decrement
CC    Stop/Eject
CD    Play/Pause
CE    Play/Skip
CF    Voice Command
D0-DF    Reserved
E0    Volume

注意 Page ID 和描述之间是 Tab，用空格将无法显示在软件中

增加 Usage Page 链接到标题

如果你需要有自定义的 Usage Page，可以通过添加。upg 文件来完成，例如我要增加一个 Frank Device 的 Usage Page, Usage Page 值为 65281，方法如下：

修改 dt.ini 文件，最后增加一项 UP21=65281,Frank Device,frank.upg,将 Count 总数从 21 变成 22

[UsagePages]
Count=22
UP0=01,Generic Desktop,desktop.upg
UP1=02,Simulation Controls,sim.upg
UP2=03,VR Controls,vr.upg
UP3=04,Sports Controls,sports.upg
UP4=05,Gaming Controls,gaming.upg
UP5=07,Keyboard,kbd.upg
UP6=08,LEDs,leds.upg
UP7=09,Button,button.upg
UP8=10,Ordinals,ordinal.upg
UP9=11,Telephony Devices,tele.upg
UP10=12,Consumer Devices,consume.upg
UP11=13,Digitizers,digit.upg
UP12=16,Unicode,unicode.upg
UP13=20,Alphnumeric Display,andisp.upg
UP14=128,Monitor,monitor.upg
UP15=129,Monitor Enumerated Values,mon_enum.upg
UP16=130,VESA Virtual Controls,VESAVC.upg
UP17=131,VESA Command,VESACmnd.upg
UP18=132,Power Device,pwrdev.upg
UP19=133,Battery System,batsys.upg
UP20=65280,Vendor Defined Page 1,vendor1.upg
UP21=65281,Frank Device,frank.upg

增加 frank.upg 文件，该 Usage Page 下有 Run/Skip/Stop 三个 Usage，内容如下：

Frank Device
NORMAL
00    Run
01    Skip
02    Stop
03-FFFF    Reserved

注意 frank.upg 中第一行的内容 Frank Device，一定要和 ini 文件中的一致。 添加完后重开 dt.exe 就可以选择新添加的 USAGE_PAGE 和 USAGE 了： add