87 lines
4.3 KiB
Markdown
87 lines
4.3 KiB
Markdown
|
# 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.)
|