zmk-config/README.md

# Corne Keyboard Custom Keymaps (ZMK)

Custom keymaps for a Corne 42-key split keyboard running ZMK firmware with on-board stenography.

# Table of Contents

- [Hardware Info](#hardware-info)
- [Current Keymap](#current-keymap)
- [Related Resources](#related-resources)
- [Pre-requisites](#pre-requisites)
- [Clone Repository](#clone-repository)
- [Editing the Keymap](#editing-the-keymap)
- [Building Firmware](#building-firmware)
- [Flashing the Keyboard](#flashing-the-keyboard)
    - [1. Download the firmware](#1-download-the-firmware)
    - [2. Connect the keyboard half via USB](#2-connect-the-keyboard-half-via-usb)
    - [3. Enter bootloader mode](#3-enter-bootloader-mode)
    - [4. Flash the firmware](#4-flash-the-firmware)
    - [5. Repeat for the other half](#5-repeat-for-the-other-half)
    - [6. Re-pair Bluetooth](#6-re-pair-bluetooth)
- [Settings Reset](#settings-reset)
  - [When to reset](#when-to-reset)
  - [How to reset](#how-to-reset)
- [Issues](#issues)
    - [Bluetooth pairing issues](#bluetooth-pairing-issues)
    - [Layers not switching correctly](#layers-not-switching-correctly)
    - [Keyboard name not changing after flash](#keyboard-name-not-changing-after-flash)
- [RGB Underglow](#rgb-underglow)
- [Enabling ZMK Studio](#enabling-zmk-studio)

# Hardware Info

| Property | Value |
|----------|-------|
| Keyboard | Corne (crkbd) 6-column split |
| Keys | 42 (3x6 + 3 thumbs per side) |
| MCU | nRF52840 (nice!nano v2 compatible) |
| Firmware | ZMK |
| Connection | Bluetooth Low Energy (BLE) |
| Device Name | `Afiq Zudin Corne42` |
| Display | SSD1306 OLED 128x32 (nice_oled module) |
| LEDs | WS2812 underglow (6/half) + per-key (21/half) — 54 total |
| BT Profiles | 5 (BT0-BT4) |
| ZMK Studio | Disabled (see [Enabling ZMK Studio](#enabling-zmk-studio)) |
| Steno Engine | Javelin (Lapwing dictionary) |
| Vendor | KeebMaker |
| Vendor Config | [KeebMaker/zmk-config](https://github.com/KeebMaker/zmk-config) |

# Current Keymap

Key positions reference:
```
 0  1  2  3  4  5  |  6  7  8  9 10 11
12 13 14 15 16 17  | 18 19 20 21 22 23
24 25 26 27 28 29  | 30 31 32 33 34 35
         36 37 38  | 39 40 41
```

### Layer 0: CARP (Carpalx QGMLWY)
```
`      Q  G  M  L  W  |  Y  F  U  B  ;    ->HUB
[HUB]  D  S  T  N  R  |  I  A  E  O  H    '
LSHFT  Z  X  C  V  J  |  K  P  ,  .  /    RSHFT
        [RGB]  CTRL  GUI | SPC  ALT  MUTE/PP

Combos (layers 0+1):
  top+home row same col = 1-0, shift+combo = ! @ # $ % ^ & * ( )
  G+M (W+E on QWRT) = ESC
  S+T (S+D on QWRT) = TAB
  U+B (I+O on QWRT) = BSPC
  E+O (K+L on QWRT) = ENTER
[HUB] = hold opens HUB layer, release goes back
[RGB] = tap-dance: 1×=toggle, 2×=effect fwd, 3×=effect rev
MUTE/PP = tap mute, hold play/pause
```

### Layer 1: QWRT (QWERTY)
```
`      Q  W  E  R  T  |  Y  U  I  O  P    ->HUB
[HUB]  A  S  D  F  G  |  H  J  K  L  ;    '
LSHFT  Z  X  C  V  B  |  N  M  ,  .  /    RSHFT
        [RGB]  CTRL  GUI | SPC  ALT  MUTE/PP

Combos: same as CARP (top+home = 1-0, W+E = ESC, S+D = TAB, I+O = BSPC, K+L = ENTER)
```

### Layer 2: STEN (Javelin Steno — Lapwing)
```
_      #  #  #  #  #  |  #  #  #  #  #    ->HUB
[HUB]  S  T  P  H  *  |  *  F  P  L  T    D
_      S  K  W  R  *  |  *  R  B  G  S    Z
              _  A  O  |  E  U  _
```

### Layer 3: FPS (WASD shifted right for ortho)
```
1/ESC  2     Q  [W]  E/3   R/4  | 5    6    7    8    9    ->HUB
TAB    SHFT [A] [S] [D]    F    | _    _    _    _    _    _
M/ALT  Z     X   C   V     G    | _    _    _    _    _    _
              T     CTRL  SPC   | _    _    _

Hold-taps: 1=tap/ESC=hold, E=tap/3=hold, R=tap/4=hold, M=tap/ALT=hold
```

### Layer 4: HUB (Utility — BT, RGB, Media, Nav)
```
BT_CLR BT0    BT1    BT2    BT3     BT4     | +      [     UP    ]     *    =
OUT_TOG HUE+  SAT+   BRT+   SCRN+   VOL+    | -      LEFT  DOWN  RIGHT /    \
LSHFT  HUE-   SAT-   BRT-   SCRN-   VOL-    | ->CARP ->QWRT ->STEN ->FPS [CLR] RSHFT
             [RGB]    CTRL   GUI              | SPC    ALT   MUTE/PP

OUT_TOG = toggle USB/BLE output
HUE/SAT/BRT = RGB underglow hue, saturation, brightness
SCRN = display brightness (C_BRI_UP/DN)
VOL = volume up/down
[RGB] = tap-dance: 1×=toggle, 2×=effect fwd, 3×=effect rev
[CLR] = tap-dance color presets: 1×=purple, 2×=white, 3×=red, 4×=blue, 5×=green
MUTE/PP = tap mute, hold play/pause
```

# Related Resources

- [ZMK Firmware Documentation](https://zmk.dev/docs)
- [ZMK Keycodes Reference](https://zmk.dev/docs/codes)
- [ZMK Studio](https://zmk.studio/) - Live keymap editor (no flashing needed)
- [Keymap Editor](https://nickcoutsos.github.io/keymap-editor/) - Visual keymap editor for GitHub repos
- [Javelin Steno Engine](https://github.com/jthlim/javelin-steno) - On-board steno engine
- [Vendor Config (KeebMaker)](https://github.com/KeebMaker/zmk-config)

# Pre-requisites

- Corne Keyboard (KeebMaker variant)
- macOS
- USB-C cable
- GitHub account (for building firmware via Actions)
- This Repository - [Custom Corne Keymaps](https://github.com/afiqzudinhadi/zmk-config)

# Clone Repository

```bash
git clone git@github.com:afiqzudinhadi/zmk-config.git
```

# Editing the Keymap

### Edit Config Files

For full customization (combos, steno layer, behaviors):

```
config/
├── corne.keymap          <- Edit this for keymap changes
├── corne.conf            <- Edit this for feature toggles (RGB, display, BLE)
└── west.yml              <- ZMK module dependencies (usually no changes needed)
```

Keymap guide can be found [here](https://zmk.dev/docs/codes).

# Building Firmware

1. Push changes to GitHub
2. Go to **Actions** tab → latest workflow run
3. Wait for the build to complete (green checkmark)
4. Download the `firmware` artifact (zip file)
5. Extract — contains `.uf2` files for left and right halves

If Actions is disabled on your fork: go to **Actions** tab → click "I understand my workflows, go ahead and enable them".

# Flashing the Keyboard

### 1. Download the firmware

Download the `firmware.zip` from the GitHub Actions artifacts and extract it.

The zip contains:
- `nice_corne_left_oled_rgb-nice_nano_v2-zmk.uf2` — left half
- `nice_corne_right_oled_rgb-nice_nano_v2-zmk.uf2` — right half
- `nice_settings_reset-nice_nano_v2-zmk.uf2` — settings reset (see [Settings Reset](#settings-reset))

### 2. Connect the keyboard half via USB

Plug in the **left** half of the keyboard with a USB-C cable.

### 3. Enter bootloader mode

Double-tap the reset button on the keyboard. The keyboard will appear as a USB drive (e.g. `NICENANO`).

- The reset button is on the PCB (check underneath the keyboard or through the case hole).
- The LEDs on the keyboard will turn off.
- If the drive doesn't appear, try double-tapping faster or slower.

### 4. Flash the firmware

Drag the **left** `.uf2` file onto the USB drive. The keyboard will automatically reboot and the drive will disappear.

### 5. Repeat for the other half

1. Plug in the **right** half via USB-C
2. Double-tap the reset button
3. Drag the **right** `.uf2` file onto the USB drive

### 6. Re-pair Bluetooth

If you changed the keyboard name or did a settings reset:

1. Open **System Settings → Bluetooth** on macOS
2. Remove the old keyboard entry (e.g. `Corne_Oled_RGB`)
3. Put the keyboard in pairing mode (it should be discoverable automatically)
4. Pair with `Afiq Zudin Corne42`

# Settings Reset

### When to reset

Do a settings reset when:
- **Layer structure changed** (layers added, removed, or reordered) — ZMK Studio saved state stores the old layer layout and will override the new compiled keymap
- Layers are not switching correctly after flashing new firmware
- Keyboard name didn't change after flash
- Both halves won't pair with each other
- ZMK Studio saved changes are interfering with your compiled keymap
- Bluetooth pairing issues after firmware update

### How to reset

1. Download `nice_settings_reset-nice_nano_v2-zmk.uf2` from the firmware artifacts
2. Connect the **left** half via USB
3. Double-tap the reset button to enter bootloader mode
4. Drag `nice_settings_reset-nice_nano_v2-zmk.uf2` onto the USB drive
5. **Immediately** double-tap reset again to put it back in bootloader mode (to avoid accidental bonding)
6. Repeat steps 2-5 for the **right** half
7. Now flash the actual firmware to both halves (left `.uf2` to left, right `.uf2` to right)
8. After flashing both halves, reset both at the same time to pair them together
9. Remove old Bluetooth entry from macOS and re-pair

# Issues

### Bluetooth pairing issues

If the keyboard won't pair after flashing:

1. Clear the BT profile: go to HUB layer → press `BT_CLR`
2. Remove the device from macOS Bluetooth settings
3. Re-pair

If issues persist, do a full [Settings Reset](#settings-reset).

### Layers not switching correctly

If `->STEN`, `->FPS`, or other layer switches go to CARP instead of the expected layer, ZMK Studio's saved state is overriding your compiled keymap. Do a [Settings Reset](#settings-reset) to clear it.

### Keyboard name not changing after flash

The BLE name is cached in device settings. Do a [Settings Reset](#settings-reset) and re-pair.

# RGB Underglow

### Hardware

54 WS2812 LEDs total — 6 underglow + 21 per-key per half. Chain length set in `boards/shields/corne/boards/nice_nano_v2.overlay`.

### Config

RGB settings are in `config/corne.conf`:

| Setting | Value | Description |
|---------|-------|-------------|
| `CONFIG_ZMK_RGB_UNDERGLOW` | `y` | Enable RGB |
| `CONFIG_ZMK_RGB_UNDERGLOW_ON_START` | `n` | Off on boot |
| `CONFIG_WS2812_STRIP` | `y` | WS2812 LED driver |
| `CONFIG_ZMK_RGB_UNDERGLOW_EFF_START` | `3` | Default effect: 0=Solid, 1=Breathe, 2=Spectrum, 3=Swirl |
| `CONFIG_ZMK_RGB_UNDERGLOW_BRT_STEP` | `1` | Brightness step (%) |
| `CONFIG_ZMK_RGB_UNDERGLOW_AUTO_OFF_IDLE` | `y` | Turn off when idle |
| `CONFIG_ZMK_RGB_UNDERGLOW_EXT_POWER` | `n` | Don't toggle external power with RGB |

Optional tuning (commented out in config):
- `HUE_STEP` / `SAT_STEP` — hue and saturation adjustment step
- `HUE_START` / `SAT_START` / `BRT_START` — initial color values

### Effects

| `EFF_START` | Effect |
|-------------|--------|
| 0 | Solid color |
| 1 | Breathe |
| 2 | Spectrum |
| 3 | Swirl |

Cycle at runtime with `RGB_EFF` (next) / `RGB_EFR` (previous).

### Keycodes

| Keycode | Action |
|---------|--------|
| `RGB_TOG` | Toggle on/off |
| `RGB_EFF` | Next effect |
| `RGB_EFR` | Previous effect |
| `RGB_HUI` / `RGB_HUD` | Hue up/down |
| `RGB_SAI` / `RGB_SAD` | Saturation up/down |
| `RGB_BRI` / `RGB_BRD` | Brightness up/down |
| `RGB_SPI` / `RGB_SPD` | Speed up/down |
| `RGB_COLOR_HSB(h,s,b)` | Set specific color |

Docs: [zmk.dev/docs/keymaps/behaviors/underglow](https://zmk.dev/docs/keymaps/behaviors/underglow) · [zmk.dev/docs/config/underglow](https://zmk.dev/docs/config/underglow)

### Runtime Controls (HUB Layer)

| Key | Action |
|-----|--------|
| `[RGB]` | Tap-dance: 1×=toggle, 2×=effect fwd, 3×=effect rev |
| `[CLR]` | Tap-dance color presets: purple → white → red → blue → green |
| `HUE+` / `HUE-` | Adjust hue |
| `SAT+` / `SAT-` | Adjust saturation |
| `BRT+` / `BRT-` | Adjust brightness |

# Enabling ZMK Studio

ZMK Studio is disabled by default in this config. To enable live keymap editing:

1. In `config/corne.conf`, uncomment:
   ```
   CONFIG_ZMK_STUDIO=y
   CONFIG_ZMK_STUDIO_LOCKING=n
   ```

2. In `build.yaml`, add `studio-rpc-usb-uart` to the left half snippet:
   ```yaml
   snippet: rgb-config studio-rpc-usb-uart
   ```

3. In `boards/shields/corne/corne.zmk.yml`, add `studio` to features:
   ```yaml
   features:
     - keys
     - display
     - underglow
     - studio
   ```

4. Push and flash.

5. Go to [zmk.studio](https://zmk.studio/) in Chrome → connect via USB or BLE → edit layers visually.

**Limitations:** Cannot add combos, custom behaviors, or change display/RGB config.

**Warning:** ZMK Studio saves changes to flash storage. These override the compiled keymap. If layers behave unexpectedly after flashing, do a [Settings Reset](#settings-reset).