Configure a Macro Keyboard on macOS

End-to-end workflow for cheap 3-key USB-C/Bluetooth macro pads (Jieli, Realtek, CH57x, AliExpress-class): identify the device, figure out what each button actually emits, write a Karabiner rule scoped to that device only, and handle USB + Bluetooth in one rule even when the pad's BT firmware emits different keycodes than its USB side.

Just want the turnkey recipe? references/09-turnkey-walkthrough.md is a copy-paste-ready 30-minute walkthrough that replicates the "MacroKeyBot" setup used as this plugin's worked example — tap/double-tap on all three buttons: top (Fn for Typeless toggle / Cmd+V paste), middle (Shift+Return / Return), bottom (up_arrow / down_arrow), across USB + Bluetooth. The bottom button uses two different mechanisms (USB: software discrimination; BT: pad-firmware discrimination via separate equal_sign / Option+Z keycodes) — see 03-patterns.md. Start there if you know what you want; come back here when you need the reusable workflow or deeper pattern references.

Self-Evolving Skill: If a step breaks on a new pad, fix this file immediately. Every dead-end discovered belongs in references/04-anti-patterns.md.

When to Use This Skill

• User mentions "macro pad", "macro keyboard", "3-key pad", "Stream Deck alternative" on macOS
• User wants to remap a cheap HID pad they bought from AliExpress / Amazon
• User wants buttons to emit Fn, Return, media keys, or custom shortcuts
• User hits a wall with BetterTouchTool (BTT can't emit real Fn — see sibling skill emit-fn-key-on-macos)
• User asks about dual USB + Bluetooth configuration for the same pad
• User mentions Jieli, Free3-P, or any pad with "USB Composite Device" as its product string

Prerequisite Check