diagnose-hid-keycodes

HID キーコードを診断する

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある場合、パラメーターにずれが生じた場合、または回避策が必要になった場合は、先延ばしにせず、このファイルをすぐに修正してください。実際に再現可能な問題がある場合にのみ更新してください。

未知のマクロパッド、マウスボタン、フットペダル、または HID ガジェットについて、各ボタンが OS レベルで実際に何を送信するかを、ラベル、ベンダーのドキュメント、写真から推測せずに特定します。安価な HID パッドでは、任意のキーコードや誤ったラベルが付けられていることがよくあります（Jieli/Free3-P は、上・中・下とラベルが付いたボタンから Ctrl+C／Ctrl+V／Ctrl+X を送信します。これは切り取り／コピー／貼り付けの慣例とは異なり、ハードウェアによってランダムに割り当てられています）。

このスキルを使う場面

• 新しい HID デバイスが届き、ボタンが何を送信するのかわからない場合
• パッドに複数のファームウェアモードがあり、各モードのキーコードをマッピングする必要がある場合
• ルールが動作せず、誤った from.key_code を指定したのではないかと疑われる場合
• 再現可能なセットアップのために、デバイスの情報を記録する必要がある場合

3 つのツールを使うワークフロー

ツール	目的
Karabiner ignore: true	デバイスを横取りせず、Karabiner にデバイスを_監視_させます
Karabiner-EventViewer	生の HID イベントをテキストで表示します
Quartz screencapture -l	フォーカスを奪わずに EventViewer のウィンドウをキャプチャします

重要なのは ignore: true です。これを有効にすると、Karabiner は何もリマップしませんが、デバイスのイベントは引き続き記録するため、ファームウェアが送信する生のキーコードを確認できます。

ワークフロー

ステップ 1 — デバイスの VID/PID を特定する

# USB
ioreg -p IOUSB -l -w 0 | grep -B 2 -A 6 "<product name or partial>"

# Bluetooth (after pairing)
system_profiler SPBluetoothDataType | grep -A 15 "<pad name>"

VID/PID は10 進数で記録してください（Karabiner の JSON 形式）。

ステップ 2 — 何もしない診断ルールを追加する（Karabiner にデバイスを確保させる）

devices[] に単に "ignore": true を設定しないのはなぜですか？ これを設定すると、Karabiner はデバイスに一切干渉しなくなり、EventViewer もそのイベントを認識できません。ignore: true は「このデバイスに触れない」という設定であり、「このデバイスを調査する」という設定ではありません。

正しい方法：デバイスに適用範囲を限定した、何もしない complex_modifications ルールを追加します。Karabiner がデバイスを確保するため、EventViewer はすべての HID レポートを取得できますが、ルール自体は何もしません。~/.config/karabiner/karabiner.json → プロファイル 0 → complex_modifications.rules を編集し、次を挿入します。

{
  "description": "[DIAGNOSTIC] Grab <pad> (no remap)",
  "manipulators": [
    {
      "type": "basic",
      "from": { "key_code": "vk_none" },
      "to": [{ "key_code": "vk_none" }],
      "conditions": [
        {
          "type": "device_if",
          "identifiers": [{ "vendor_id": 19530, "product_id": 16725 }]
        }
      ]
    }
  ]
}

vk_none は、実際の入力には決して一致しない Karabiner の仮想キーなので、マニピュレーターは何もしません。device_if の適用範囲指定により、Karabiner は調査のためにデバイスを確保します。

Karabiner を再読み込みします。メニューバーの Karabiner-Elements アイコン → Restart Karabiner-Elements を選択してください。

ステップ 3 — EventViewer を開き、各ボタンを押す

open -a "Karabiner-EventViewer"

• Main タブ：デコードされたキーコード名（c、left_control、page_up など）とともに、key_down／key_up を表示します
• Devices タブ：各イベントを送信したデバイスを表示します。正しい VID/PID のデバイスを確保しているか確認できます
• Unknown Events タブ：Karabiner がデコードできなかったイベントを表示します。コンシューマーキーやカスタム HID 記述子に関連します

各ボタンをゆっくり押します。1 つの HID レポートで送信される修飾キーの組み合わせ（安価なパッドでよく見られます）では、複数の key_down イベントが短い間隔で表示されます。

13:44:02.123  key_down  left_control
13:44:02.123  key_down  c
13:44:02.198  key_up    c
13:44:02.198  key_up    left_control

left_control と c のタイムスタンプが同じマイクロ秒なら、1 つの HID レポートで送信されています。その場合は simultaneous マッチャーが必要です。

ステップ 4 — フォーカスを奪わずにキャプチャする

EventViewer を前面に表示して内容を読むと、テストウィンドウ上でボタンを押せなくなります。回避策として、ウィンドウ ID を指定してキャプチャします。

# List windows; find EventViewer's window ID
python3 -c '
from Quartz import CGWindowListCopyWindowInfo, kCGWindowListOptionAll, kCGNullWindowID
for w in CGWindowListCopyWindowInfo(kCGWindowListOptionAll, kCGNullWindowID):
    if "EventViewer" in w.get("kCGWindowOwnerName", "") or "EventViewer" in w.get("kCGWindowName", ""):
        print(w["kCGWindowNumber"], w.get("kCGWindowName"))
'

# Screenshot that window without focusing it
screencapture -l <WID> -o -x /tmp/eventviewer.png

-l <WID> は特定のウィンドウをキャプチャし、-o は影を除外し、-x はキャプチャ音を無効にします。ウィンドウを前面に表示する必要はありません。

ステップ 5 — ファームウェアモードごとに繰り返す（Bluetooth パッド）

安価な Bluetooth パッドの多くには、ボタンの組み合わせ（3 つのキーをすべて 5 秒間長押しする、上部のキーを 10 秒間長押しするなど）で切り替わる、ドキュメントに記載されていないファームウェアモードがあります。モードごとに、まったく異なるキーコードが出力されることがあります。見つかったモードごとに、次の手順を行います。

1. パッドをそのモードに切り替えます
2. ステップ 3 を繰り返し、各ボタンのキーコードを記録します
3. 表にまとめます

例（Jieli/Free3-P）：

モード	上部	中央	下部
1	volume_increment	volume_decrement	spacebar（再生／一時停止）
4	page_up	page_down	equal_sign

ステップ 6 — 後片付け

complex_modifications.rules から [DIAGNOSTIC] ルールを削除し、Karabiner を再読み込みします。または、vk_none を実際の from／to バインディングに置き換えて、実際に使うリマップルールに変換します。

Touch ID を作動させる監査を避ける

このワークフローでは、「アクセス権を監査する」ために /Library/Application Support/com.apple.TCC/ 内の TCC.db や SQLite ファイルを照会しないでください。こうした照会には sudo が必要で、実行のたびに Touch ID のプロンプトが表示されます。代わりに、次の方法を使います。

# Non-sudo audit: is Karabiner actually grabbing the device?
karabiner_cli --list-connected-devices | jq '.[] | select(.product == "<pad-name>")'
# Returns { ..., "is_grabbed": true/false } — same info, no biometric prompt

作業に使うツール自体が監査になります。これは実際に試してわかったことです。詳しくは ../configure-macro-keyboard/references/04-anti-patterns.md →「Sudo-based TCC.db audits trigger Touch ID」を参照してください。

詳細リファレンス

• ../configure-macro-keyboard/references/03-patterns.md — 「ignore: true diagnostic」と「Quartz window-ID capture」のパターンの詳細
• ../configure-macro-keyboard/references/04-anti-patterns.md — トップレベルの {"any": "key_code"} はエラーを出さずに失敗すること、位置推定の誤り
• ./references/diagnostic-workflow.md — スクリーンショット付きの詳細な手順

関連スキル

• configure-macro-keyboard — ボタンから出力されるキーコードがわかったら、このスキルを使ってデバイス専用の Karabiner ルールを作成します。ここで使うステップ 2 の vk_none ノーオペレーションルールは、from／to バインディングを入れ替えるだけで実際のルールに変換できます。
• emit-fn-key-on-macos — 見つかったキーコードのいずれかを実際の Fn（Typeless、音声入力、Globe キー用）にリマップする場合、この関連スキルで、Karabiner で正しく設定する方法を説明します。

実行後の振り返り

このスキルの実行後、タスクを終了する前に振り返ります。

0. 現在位置を確認します。 — 編集前に、この SKILL.md が正式なファイルであることを確認します。
1. 何が失敗しましたか？ — 失敗の原因となった指示を修正します。
2. 予想以上にうまくいったことは何ですか？ — 推奨するプラクティスに加えます。
3. 何が古くなっていますか？ — 実際の状況とドキュメントが異なる場合は、ベンダー ID、キーコード、FOSS ツールのバージョンを更新します。
4. 記録します。 — 発生条件、修正内容、根拠を含めて、進化ログのエントリー（または 04-anti-patterns.md の行）を追加します。

先送りしないでください。次回の実行では、ここに残した内容が引き継がれます。