qmk/layouts/community/ergodox/audax_osx/readme.md

audax_osx - neo2 for macOS via the software neo2 layout + Karabiner-Elements

This is a neo2 ErgoDox layout for macOS that relies on the software neo2 keyboard layout installed on the Mac, rather than emulating neo2 in firmware.

It is the software-neo2 counterpart of the sibling audax_osx_neo2 layout. The key arrangement, thumb clusters, home-row mods and macOS shortcuts are the same; the difference is who produces the neo2 characters:

	audax_osx_neo2 (old)	audax_osx (this)
macOS input source	US / ABC Extended	neo2 (installed on the Mac)
neo2 letters	faked in firmware	produced by the OS
umlauts, ß, €, „ …	Option dead-key macros in firmware	produced by the OS
layer 3 (symbols)	firmware layer	produced by the OS
layer 4 (cursor/numpad)	firmware layer	firmware layer (so its keys auto-repeat)
firmware sends	US scancodes + macros	positional neo2 scancodes (NE_*)

Base layer, shift and Mod3 live in the OS neo2 layout, so the firmware stays small: a neo2 base layer, a Mod4 cursor/numpad layer, a media/function layer, and two small custom keys.

Required macOS setup

1. Install the neo2 macOS keyboard layout (.keylayout / .bundle): https://github.com/jgosmann/neo2-layout-osx and select it as the active input source. It provides the base layer, shift and Mod3.
2. Optional: install Karabiner-Elements and import https://github.com/jgosmann/Karabiner-Elements-Neo only if you want the OS-side neo2 layer 6 (math symbols). Mod4 (cursor/numpad) is handled by the firmware in this layout, so Karabiner is not required for it.

References: Neo auf dem Apple Macintosh einrichten.

Layer switching

Mod3 (layer 3, symbols) is handled by the OS neo2 .keylayout. Both Mod3 keys send # (KC_NUHS), which the .keylayout treats as Mod3.

Role	Keycode	Sends	Notes
Mod3-left	NE_L3R	# (KC_NUHS)	held = Mod3
Mod3-right	NEO_L3R_SS	# (KC_NUHS)	held = Mod3, tap = ß

Why both Mod3 keys send #: the canonical neo2 Mod3-left is CapsLock, but macOS intercepts CapsLock and it does not register as a live Mod3 modifier unless Karabiner explicitly remaps caps_lock to the # key. Sending # from both keys makes the left Mod3 work out of the box. If you prefer true CapsLock semantics, add that Karabiner remap and use NE_L3L for the left Mod3 key.

Mod4 (layer 4, cursor + numpad) is a firmware layer (NEO_4), held via the right-thumb Enter key. It is kept in firmware - not the OS neo2 Mod4 - so the cursor keys auto-repeat when held, matching the Linux audax layout. The neo2 Mod4 special characters are omitted; add them to NEO_4 in keymap.c if wanted.

Layer 6 (Mod3+Mod4 math symbols) is not available, because Mod4 is not an OS modifier in this layout. Enable it through Karabiner if you need it.

Behaviour worth knowing

• Right Mod3 key (tap = ß): in neo2 the right-hand Mod3 key is a pure modifier. To keep the muscle memory from audax_osx_neo2, tapping it alone sends ß (neo2's native NE_SS position); holding it acts as Mod3 (NEO_L3R_SS in keymap.c).
• Enter thumb key (tap = Enter, hold = Mod4, +Backspace = Delete): the right-thumb Enter is the custom NEO_ENT_M4 key. A tap types Enter; a hold turns on the NEO_4 firmware layer (cursor + numpad, all auto-repeating). On that layer the Backspace thumb key is KC_DEL, so holding Enter and pressing Backspace produces Delete - the Enter+Backspace convenience from the Linux audax layout.
• Dedicated Mod4 key: the right inner bottom key (row 4, the big 1.5u key by the thumb cluster) is MO(NEO_4) - a real momentary Mod4. Hold it with the right hand and work the cursor block on the left. The Enter thumb is a second Mod4 (on hold). Left Option remains on the left outer Alt key.
• Home-row mods: left home row is LCTL_T/LALT_T/LGUI_T on U/I/A.
• FKEYS layer (media + F-keys) is firmware-only; it is not part of neo2 and lights the first right-hand LED while active.

Building

qmk compile -kb ergodox_ez -km audax_osx

(Use the appropriate ErgoDox keyboard target for your board.)