Hardware Keyboard Remapper(OS に依存しないキーボードのキー入れ替え)を作った

pi0w の RNDIS 通信を有効にしている場合、 以下を /boot/cmdline.txt に追加していると思います。

modules-load=dwc2,g_ether

この指定は外してください。 これを設定していると、 pi0w を HID キーボード化できません。

後のステップで、別の方法で RNDIS を有効化します。

なお、 以下の作業は RNDIS 経由の ssh ではなく、 WiFi 経由の ssh か、あるいは pi0w のコンソールで直接作業してください。

また、RNDIS 経由の ssh で作業していた場合は、 一旦 raspberry pi を再起動してください。

まずは、以下を実行し「input event デバイス名のリスト出力」して、 デバイス名をメモっておきます。

sudo ./hw-keyboard-remapper -mode list

なお以下の場合、Keyboard のデバイス名がリストに出力されないので注意してください。

• BT Keyboard がペアリングされていない
• BT Keyboard が省電力モードに入って接続が切れている

なお、 vc4 がリストされますが、それはキーボードではなく VideoCoreIV チップです。

以下を実行し、キー入力を取得できているか確認します。

$ sudo ./hw-keyboard-remapper -mode scan -kb "XXXXXXXXXXXXXXX"

ここで、 "XXXXXXXXXXXXXXX" には先程メモしたキーボード名を指定します。

キーボードでキーを押すと、そのキー情報が出力されます。 例えば m j と入力すると、以下のような出力がされます。

DEBU[0002] [event] press key 50(0x32) KEY_M -> Keyboard m and M 
INFO[0002] data [0 0 16 0 0 0 0 0]                      
DEBU[0003] [event] release key 50(0x32) KEY_M -> Keyboard m and M 
INFO[0003] data [0 0 0 0 0 0 0 0]                       
DEBU[0003] [event] press key 36(0x24) KEY_J -> Keyboard j and J 
INFO[0003] data [0 0 13 0 0 0 0 0]                      
DEBU[0004] [event] press key 36(0x24) KEY_J -> Keyboard j and J 
INFO[0004] data [0 0 13 0 0 0 0 0]

ここで、 press key 50(0x32) KEY_M は "m" の押下イベントが発生したことを示し、 50(0x32) は linux 側の "m" のキーコードを示します。 data [0 0 16 0 0 0 0 0] は HID コードの変換結果を示し、 3 バイト目の 16 は、 HID の "m" のコードを示します。

キーのカスタマイズは、この HID コードが重要になります。

この HID コードの詳細は、次の USB の規格書を参照してください。

• 各キーのコード情報は、以下の資料の 「10 Keyboard/Keypad Page (0x07)」 を参照

  • https://usb.org/document-library/hid-usage-tables-122

• Ctl, Alt 等の modifier キー情報は、以下の資料の「8.3 Report Format for Array Items」を参照

  • https://www.usb.org/document-library/device-class-definition-hid-111

なお、 linux のキーコードから HID コードへの変換がバグっている可能性は否定できません。 ローカルで修正するか、 issue で報告するか、 pull request してください。

pi0w に ssh でアクセスしている場合、 Ctrl-C すればプログラムは終了します。

しかし、 pi0w のコンソールから実行している場合、 全てのキー入力がこのプログラムに取られて効かないため、 Ctrl-C も無効です。

この状態からプログラムを終了させる場合、 pi0w に接続しているキーボードから以下(qwe を4回)を入力してください。

qweqweqweqwe

これで終了します。

なおこの文字列は、 「偶然のキータイプでは発生せずに、簡単に入力できる文字列」として使用しています。

qweqweqweqwe が「普通に使う文字列だ」というのであれば、 適宜コードを変更してください。 (もしかしたら、 steam でゲームしてたら qwe を使うこともあるのかも？)

接続する BT Keyboard 名を指定します。

コマンドラインに -kb オプション指定がある場合、-kb オプションを優先します。

置き換える HID キーコードのペアを指定します。

• Src

  • 置き換え元の HID キーコード。 integer。

• Dst

  • 置き換え先の HID キーコード。 integer。

• Comment

  • コメントです。変換には関係ありません。

• On

  • この置き換え情報が有効かどうかを示します。 bool。
  • このキーが存在しないか、 true を指定した場合、有効として扱います。
  • 一時的に off にしたい場合に false を指定することを想定しています。

これは、単純にキーそのものを置き換えます。 例えば、 Ctrl と CapLock の置き換えのような時に利用します。

単純にキーそのものを置き換えるので、 「Shift を押しながら A を押した場合に、他のキーに置き換えたい」と いうような用途には使えません。

その場合は、 ConvKeyMap で指定します。

ConvKeyMap は、 Ctrl や Shift などの modifier キーを押しながら他のキーを押した時の、 キーコード変換方法を定義します。

例えば C-f を押下したら → キーのコードを送る、なんてことも可能です。

ConvKeyMap は、次の要素からなります。

"ConvKeyMap": {
    "key1": [ {info}, ... ],
    "key2": [ {info}, ... ],
    ...
}

• key

  • 変換元の HID キーコードを文字列で指定します。
  • 例えば f を押下した場合の動作を定義する場合、 "0x9" を指定します。
  • キーコードの表現は、16進数か 10 進数です。

• info

  • 変換条件を次の配列で指定します。

    • modMask

      • modifier のマスク値を指定します。

    • modResult

      • modifier のマスク結果を指定します。

    • Code

      • 条件成立時の HID コードを指定します。

    • modXor

      • 条件成立時の modifier の XOR 値を指定します。

    • Comment

      • SwitchKeys と同じです。

    • On

      • SwitchKeys と同じです。

ConvKeyMap で指定すると、次の条件が成り立つ時に動作します。

(modMask & modifier) == modResult

例えば Left-Ctrl が押下されていることを条件にするには、 modMask と modResult 両方に 1 を指定します。

以下のサンプルは、 C-f が押下された場合、 → に変換することを示します。

"0x9": [ { "modMask": 1, "modResult": 1, "Code": 79, "modXor": 1,
           "Comment": "C-f -> right arrow" } ],

ここで、modXor が 1 なので modifier に 1 が xor され、 結果的に出力される modifier の Left-Ctrl ビットが 0 になっていることに注意してください。

Shift キーが押された時のキーの入れ替えも同じように行ないます。

なお、 C-f を → に変換すると、 emacs では C-x C-f が C-x → になってしまうので、変換はオススメしません。

前述の通り、このプログラムを実行していると pi0w のコンソール上でキー入力が効かなくなる。 当然ログインも出来ない。

ssh 経由であれば作業できるが、 ssh を接続できないケースがある。 その時、 qweqweqweqwe を入力すればキーボードが使えるようになるが、 そんな事は絶対に忘れるので、 pi0w の login プロンプトに警告を表示するように設定しておく。

/etc/issue に以下を設定しておくことで、メッセージが表示される。

=====> Keyboard is invalid now. To available the keyboard, enter "qweqweqweqwe".

Raspbian GNU/Linux 11 \n \l

なお、/etc/issue を編集する場合、 元のメッセージよりも上の行に設定せずに下の行に設定すると、 ssh 接続の鍵認証が出来なくなって、パスワード認証に切り替わってしまったので、 メッセージを編集する際は気を付けてください。