configure-macro-keyboard

macOSでマクロキーボードを設定する

低価格の3キーUSB-C／Bluetoothマクロパッド（Jieli、Realtek、CH57x、AliExpressクラス）を使うためのエンドツーエンドのワークフローです。デバイスを特定し、各ボタンが実際に何を出力するかを調べ、そのデバイスだけを対象とするKarabinerルールを作成します。また、パッドのBluetoothファームウェアがUSB側と異なるキーコードを出力する場合でも、1つのルールでUSBとBluetoothの両方に対応する方法を説明します。

すぐに使える手順だけをお探しですか？ references/09-turnkey-walkthrough.mdには、このプラグインの実例である「MacroKeyBot」の設定を再現する、コピーしてすぐ使える30分の手順があります。3つすべてのボタンでタップ／ダブルタップを設定します。上部（Typeless切り替え用のFn／Cmd+V貼り付け）、中央（Shift+Return／Return）、下部（up_arrow／down_arrow）に対応し、USBとBluetoothの両方で使えます。下部のボタンでは2つの異なる仕組みを使います（USB：ソフトウェアによる判別、BT：equal_sign／Option+Zという別々のキーコードを使ったパッドのファームウェアによる判別）。詳しくは03-patterns.mdを参照してください。必要な設定が決まっている場合は、まずこちらをご覧ください。再利用可能なワークフローや、より詳しいパターンを参照する必要があれば、こちらに戻ってきてください。

自己進化型スキル：新しいパッドで手順がうまくいかない場合は、このファイルをすぐに修正してください。発見した行き詰まりはすべて、references/04-anti-patterns.mdに記録してください。

このスキルを使う場面

• ユーザーがmacOSで「マクロパッド」「マクロキーボード」「3キーパッド」「Stream Deckの代替品」について話している
• ユーザーがAliExpressやAmazonで購入した低価格のHIDパッドをリマップしたい
• ユーザーがボタンからFn、Return、メディアキー、またはカスタムショートカットを出力したい
• BetterTouchTool（BTTでは本物のFnを出力できません。「emit-fn-key-on-macos」姉妹スキルを参照してください）で行き詰まっている
• 同じパッドのUSBとBluetoothを併用する設定について質問している
• Jieli、Free3-P、または製品名に「USB Composite Device」と表示されるパッドについて話している

前提条件の確認

# 1. Karabiner-Elements installed?
test -d /Applications/Karabiner-Elements.app && echo OK || brew install --cask karabiner-elements

# 2. Input Monitoring + Accessibility granted?
#    System Settings → Privacy & Security → Input Monitoring → Karabiner = ON
#    System Settings → Privacy & Security → Accessibility → Karabiner = ON

# 3. On macOS Sequoia+: Login Items toggle for privileged daemon
#    System Settings → General → Login Items → Allow in the Background → Karabiner-Elements Privileged Daemon = ON

3つのうち1つでも一致しないと、リマップ時にデバイスの取得が失敗しても通知されません。

ワークフロー（5ステップ）

ステップ1 — デバイスを特定する（USB）

# USB product string, VID, PID, serial, interface layout
ioreg -p IOUSB -l -w 0 | grep -B 2 -A 40 "USB Composite Device" | head -80

# Or system_profiler for a human-readable dump
system_profiler SPUSBDataType | grep -A 15 "USB Composite"

記録する項目：idVendor（16進数）、idProduct（16進数）、製品名、シリアル番号、インターフェース数。

VID／PIDを10進数に変換する（KarabinerのJSONでは10進数を使います）。

python3 -c "print(int('0x4c4a', 16), int('0x4155', 16))"
# → 19530 16725

Jieliパッドの完全なデコード例（HIDレポート記述子やチップファミリーの推定方法を含む）については、references/01-hardware-identification.mdを参照してください。

ステップ2 — デバイスを特定する（該当する場合はBluetooth）

「システム設定」→「Bluetooth」からペアリングして接続します。次に：

# Pad's BT address + VID/PID + firmware
system_profiler SPBluetoothDataType | grep -A 20 "Free3-P\|<pad-name>"

# Confirm Karabiner sees it as a grabbable device
karabiner_cli --list-connected-devices | jq '.[] | select(.product == "<pad-name>")'

USBとは異なるVID／PIDが表示されることを想定してください。低価格のパッドは、macOSのHID互換性のためにSamsungの0x04E8 VIDを借用しています。Karabinerルールでは、2つの識別子を指定する1つのdevice_ifを使って、両方のVID／PIDを対象にする必要があります。

Jieli／Free3-Pの実例については、references/08-bluetooth-configuration.mdを参照してください。

ステップ3 — 各ボタンが実際に何を出力するかを調べる

標準の割り当てを想定しないでください。低価格のパッドには任意のキーコードが設定されています（Jieli／Free3-PではCtrl+C／Ctrl+V／Ctrl+Xが割り当てられており、カット／コピー／ペーストの慣例とは異なります。ボタンの順序はハードウェアによって異なります）。

ignore: trueの診断ルールを使います（イベントを無効化せずに、生のイベントを記録するリマップです）。詳しい手順については、姉妹スキルのdiagnose-hid-keycodesを参照してください。簡単な手順：

1. デバイスに対して"conditions": [{"type": "device_if", "identifiers": [{...}]}]と"ignore": trueを指定した無効化済みルールを追加します
2. Karabiner-EventViewerを開き、「Main」タブを表示します
3. 各ボタンを押し、出力されたキーコードのスクリーンショットを撮ります
4. Bluetoothでも繰り返します（パッドに複数のファームウェアモードがある場合は、それぞれのモードで実施します）

ステップ 4 — Karabiner ルールを記述する

場所：~/.config/karabiner/karabiner.json → プロファイル 0 → complex_modifications.rules → 新しいルールを追加します。

まずバックアップします：

cp ~/.config/karabiner/karabiner.json ~/.config/karabiner/karabiner.json.bak.$(date +%Y%m%d-%H%M%S)

ルールのひな形（1 つのルール、マニピュレーター数 N ＝ボタン数 × 接続方式数）：

{
  "description": "<pad-name>: Top → Fn, Middle → Return, Bottom → Command+Delete",
  "manipulators": [
    {
      "type": "basic",
      "from": {
        "simultaneous": [{ "key_code": "left_control" }, { "key_code": "c" }],
        "simultaneous_options": {
          "detect_key_down_uninterruptedly": true,
          "key_down_order": "strict_inverse",
          "key_up_order": "strict_inverse",
          "to_after_key_up": []
        },
        "modifiers": { "optional": ["any"] }
      },
      "to": [{ "apple_vendor_top_case_key_code": "keyboard_fn" }],
      "conditions": [
        {
          "type": "device_if",
          "identifiers": [
            { "vendor_id": 19530, "product_id": 16725 },
            { "vendor_id": 1256, "product_id": 28705 }
          ]
        }
      ]
    }
  ]
}

(ミドル、ボトム、BT モードのバリエーションについて、マニピュレーターブロックを繰り返します。3 キーのパッド × 2 種類の接続方式のみの場合は6 個のマニピュレーターです。Karabiner 側でタップとダブルタップを判別するボタンごとに、各接続方式あたりマニピュレーターを 2 個追加します（references/03-patterns.md を参照）。Jieli/Free3-P の実際のサンプルでは、3 つすべてのボタンでタップとダブルタップを判別するため、合計 12 個のマニピュレーターを使用します。注：ボトムボタンは USB のみ Karabiner 側で判別します（どちらの押し方でも Ctrl+X）。BT ではパッドのファームウェアが異なる 2 つのキーコードを出力するため（シングルは equal_sign、ダブルは Option+Z）、BT 用の 2 個のマニピュレーターは判別／処理のペアではなく、単純な即時変換です。いずれの場合も合計は 12 個です。8 個（トップ＋ミドル、両方の接続方式、ソフトウェアによる判別）＋2 個（ボトム USB、ソフトウェアによる判別）＋2 個（ボトム BT、ファームウェアが決定するキーコードの変換）。JSON は // コメントに対応していないため、コメント行を設定に貼り付けないでください。

覚えておくべき 5 つのルール：

1. detect_key_down_uninterruptedly: true を指定した simultaneous — パッドが 1 つの HID レポートで修飾キーとキーを出力する場合に必要です。デフォルトの mandatory マッチャーでは検出できません。
2. 実際の Fn を出力するには apple_vendor_top_case_key_code: keyboard_fn のみ使用できます。key_code: fn は何もせず、modifiers: ["fn"] も何もしません。
3. 複数の識別子を指定した device_if — USB の VID/PID と BT の VID/PID の両方を、同じ identifiers 配列に指定します。1 つのルールで両方の接続方式に対応できます。
4. すべてのマニピュレーターをデバイスに限定します。device_if がないと、MacBook 内蔵キーボードまで再割り当てされ、Apple の標準キーが使えなくなります。
5. modifiers: {"optional": ["any"]} — ルールをブロックせずに、ファームウェアからの修飾キーのレポートを通過させます。

実際の完全なサンプル（Jieli + Free3-P、3 つすべてのボタンでタップ／ダブルタップに対応する 12 個のマニピュレーター。ボトムボタンでは非対称な方式を使用：USB ではソフトウェアによる判別、BT ではファームウェアが決定するキーコードの変換）：references/raw/karabiner-rule.json。

ステップ 5 — デバイスの認識を確認してテストする

# Karabiner sees and grabs the device
karabiner_cli --list-connected-devices | jq '.[] | select(.product == "<pad-name>") | {product, is_grabbed}'

# Should return {"product": "...", "is_grabbed": true}

# Live event test
open -a "Karabiner-EventViewer"
# Press buttons → should see your TARGET keycode, not the SOURCE

is_grabbed: false の場合は、入力監視＋アクセシビリティ＋ログイン項目を再確認します（前提条件の確認ステップ）。

認識されているのにボタンの入力がそのまま通過する場合は、simultaneous マッチャーが間違っている可能性があります。パッドは組み合わせを 1 つのレポートで出力するのに、mandatory を記述しています。ステップ 3 を再確認してください。

ルールを読み込んだ後、システム全体で実際の Fn が機能しなくなった場合は、直ちに元に戻してください。keyboard_fn をターゲットにした to_if_held_down は設定しないでください。システム全体で Fn を出力できなくなります（障害を確認済み）。references/04-anti-patterns.md →「タップとホールドによる Fn の出力」を参照してください。

決定ツリー：どのターゲットキーコードを使うか？

ボタンから出力させたい内容…	ターゲット JSON
Return / Enter	{"key_code": "return_or_enter"}
Shift+Return（送信せずに改行）	{"key_code": "return_or_enter", "modifiers": ["left_shift"]}
Fn（Typeless、ディクテーション用）	{"apple_vendor_top_case_key_code": "keyboard_fn"}
Command+Delete（行頭まで削除）	{"key_code": "delete_or_backspace", "modifiers": ["left_command"]}
Option+Delete（単語を削除）	{"key_code": "delete_or_backspace", "modifiers": ["left_option"]}
メディアの再生／一時停止	{"consumer_key_code": "play_or_pause"}
音量を上げる／下げる	{"consumer_key_code": "volume_increment"} / volume_decrement
アプリを起動する	{"shell_command": "open -a 'App Name'"}
シェルコマンドを実行する	{"shell_command": "/path/to/script.sh"}
タップ = A、ダブルタップ = B（単一ボタン）	パターンは references/03-patterns.md →「タップとダブルタップの判別」を参照（set_variable + to_delayed_action）

複数の BT ファームウェアモードへの対応

安価なパッドの多くは、モードごとに異なるキーコードを出力する 2～4 個のファームウェアモードを備えています。Jieli/Free3-P には 4 つのモードがあります。

モード	上	中央	下
1	volume_increment	volume_decrement	spacebar（再生／一時停止）
2	（未調査）	—	—
3	（未調査）	—	—
4	page_up	page_down	equal_sign

使用頻度が最も低いキーのモードを選びます（Free3-P ではモード 4。page_up/page_down はノートパソコンではあまり使われません）。次に、それらのキーコードに一致するマニピュレーターをそのまま追加します（単一キーのファームウェアモードでは simultaneous は不要です）。

モード切り替えの組み合わせは、説明書に記載されていないことがよくあります。よく試される方法は、3 つのキーすべてを 5 秒以上長押しする、上のキーだけを 5 秒以上長押しする、上と下のキーを同時に押す、などです。うまくいく方法が見つかったら記録してください。

モード 4 の設定全体については、references/08-bluetooth-configuration.md を参照してください。

詳細なリファレンス（必要に応じて読み込み）

トピック	ファイル
すぐに始められる一連の手順	references/09-turnkey-walkthrough.md
デバイスの概要（TL;DR 表）	references/overview.md
ハードウェアの識別	references/01-hardware-identification.md
ライブ USB 設定（Jieli）	references/02-usb-wired-configuration.md
再利用可能なパターン	references/03-patterns.md
アンチパターン／行き詰まり	references/04-anti-patterns.md
BT ペアリングのロードマップ（履歴）	references/05-bluetooth-roadmap.md
BT エコシステムの調査	references/06-bluetooth-landscape-survey.md
BT ツールボックス（評価済みツール）	references/07-bluetooth-toolbox.md
ライブ BT 設定（Jieli モード 4）	references/08-bluetooth-configuration.md
生データダンプ	references/raw/

関連スキル

• emit-fn-key-on-macos — 実際の Fn キーを送出できるのは Karabiner だけである理由を詳しく解説します（ロックされたファームウェアでは BTT／hidutil／QMK はすべて失敗します）
• diagnose-hid-keycodes — 正体不明のボタンが何を送出するかを調べるための、ignore: true + EventViewer + Quartz を使ったフォーカス不要のスクリーンキャプチャワークフロー

実行後の振り返り

このスキルの実行が完了したら、タスクを終了する前に振り返ってください。

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

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