# 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](https://karabiner-elements.pqrs.org/)
   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](https://old-wiki.neo-layout.org/neowiki/wiki/Neo%20auf%20dem%20Apple%20Macintosh%20einrichten).

## 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.)