コンテンツにスキップ

HID 機器設定 (/etc/hid_devices.toml)

USB 機器が必ず動くとは限りません。そもそも認識されないものと、認識はされるが汎用の処理が 読み違える形式で報告してくるものがあります。試した機器は 動作確認済み機器 にあります。

このファイルは後者を直します。機器ごとに、報告のどのビットがボタンでどれが軸かを明示します。 効くのは、カーソルが飛ぶ、違う向きに動く、ボタンは効くのに動かない、といった症状です。 そもそも認識されない機器はドライバの問題なので、これでは直りません。

どの配置が使われるか

システムはこの順に試します。

  1. このファイル。ベンダ ID と製品 ID が一致する [[mouse]] か [[gamepad]] の記述が あれば、それが無条件で使われます
  2. ブートプロトコル。一致が無ければ、対応しているマウスには標準の 3 バイトの報告を 要求します
  3. 自動判別。届いた報告がブートの形に見えないとき (3 バイトより長く、マウスの報告 ID で 始まっているとき) は、12 ビットに詰めた軸を持つ Report Protocol の配置へ自分で切り替え ます。安価なマウスの一群がこれに当たります

つまり、この 3 つが全部外れたときだけ、このファイルへの記述が必要になります。

パソコンなしで記述を作る

HID Inspector が実機だけで対話的にやってくれます。このアプリはファームウェアに 組み込まれていて /app には無いので、ランチャーには出ません。デスクトップで I を 押すと起動します。

  1. LIST — つながっている機器から、おかしいものを選ぶ
  2. INSPECT — 動かしたり押したりしながら、生の報告バイトを見る
  3. WIZARD — 軸を 1 つずつ動かすよう案内され、各項目の位置を割り出す
  4. RESULT — 生成された [[mouse]] の記述が出るので、S で /etc/hid_devices.toml に 追記する

以下の形式は、書かれたものを読んだり手で直したりするための説明です。

[[mouse]]

[[mouse]]
vid = 0x046D
pid = 0xC534
name = "Logitech Unifying"
report_id = 0x02
report_len = 7
buttons = { offset = 0,  size = 8,  min = 0,     max = 1,    relative = false }
x       = { offset = 16, size = 12, min = -2048, max = 2047, relative = true }
y       = { offset = 28, size = 12, min = -2048, max = 2047, relative = true }
キー 意味
vid / pid USB のベンダ ID と製品 ID。16 進で書きます
name 自由な文字列。ログに出るので記述を見分けるのに使います
report_id 報告 ID のバイト。送ってこない機器では省くか -1 にします
report_len 報告の長さ (バイト)。報告 ID は数えません
skip_control_transfer true にすると、この機器への USB 制御転送を省きます。制御転送で固まる機器がわずかにあります
buttons ボタンのビット位置
x / y 軸の位置

各項目の表には次を書きます。

キー 意味
offset 報告データの先頭からのビット位置 (報告 ID があればその後から)
size 項目の幅 (ビット)
min / max 値の範囲。min が負なら符号つきとして扱われます
relative マウスのように移動量を報告するなら true、タッチパッドやタブレットのように位置を報告するなら false

位置はバイトではなくビットです。2 バイト目の途中から始まる 12 ビットの軸は offset = 20 になります。汎用の処理が間違えるのは、まさにこの形です。

[[gamepad]]

[[gamepad]]
vid = 0x0F0D
pid = 0x0009
name = "HORI PAD 3 TURBO"
report_len = 19
buttons = { offset = 0,  size = 16 }
hat     = { offset = 16, size = 4 }
left_x  = { offset = 24, size = 8, center = 128 }
left_y  = { offset = 32, size = 8, center = 128 }
right_x = { offset = 40, size = 8, center = 128 }
right_y = { offset = 48, size = 8, center = 128 }
キー 意味
vid / pid / name 上と同じ
report_len 報告の長さ (バイト)
buttons ビットマスクの項目。offset と size。第 n ビットがボタン n になります
hat 十字キー (ハットスイッチ)。offset と size。省略可
left_x, left_y, right_x, right_y, l2, r2 軸。offset、size、center

center はその軸が中立のときの値です (0〜255 を返すスティックなら 128)。これでどちら向きに 倒されたかが分かります。

ボタン番号はアプリに :gamepad_down / :gamepad_up の ev[:button] として届き、GP_* 定数が名前を与えています。定数・システム情報 を参照してください。

注意

  • 記述の照合は vid と pid だけで行われます。モードによって別の製品 ID を名乗る機器は、 モードごとに記述が要ります
  • 同梱のファイルには、Logitech Unifying レシーバ、Logickeyboard TITAN のタッチパッド、 Sipeed NanoKVM-USB、HORI PAD 3 TURBO の動く記述が入っています。どれも持っていなくても、 書き方の見本として読む価値があります
  • ファームウェアを書き込むと、/etc の他のファイルと一緒にこのファイルも置き換わります。 苦労して割り出した記述は控えを取っておいてください

関連