zmk-config-archive/README.md

# Corne Keyboard Custom Keymaps (ZMK)

This repository contains the custom keymaps for the Corne split keyboard. It also contains the guide on how to set up the keymaps.

# Table of Contents

- [Corne Keyboard Custom Keymaps (ZMK)](#corne-keyboard-custom-keymaps-zmk)
- [Table of Contents](#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)
    - [Option 1: ZMK Studio (No Flashing Required)](#option-1-zmk-studio-no-flashing-required)
    - [Option 2: Edit Config Files](#option-2-edit-config-files)
- [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)

# 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) |
| BLE Address | `E8:9F:65:F3:75:D5` |
| USB Vendor ID | `0x1D50` (OpenMoko) |
| USB Product ID | `0x615E` (ZMK default) |
| Device Name | `Afiq Zudin Corne42` |
| Display | SSD1306 OLED 128x32 (nice_oled module) |
| LEDs | WS2812 RGB underglow, 27 LEDs |
| BT Profiles | 5 (BT0-BT4) |
| ZMK Studio | Enabled (unlocked) |
| 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)
[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 2: STEN (Plover keyboard mode)
```
_      #  #  #  #  #  |  #  #  #  #  #    ->HUB
[HUB]  S  T  P  H  *  |  *  F  P  L  T    D
_      S  K  W  R  *  |  *  R  B  G  S    Z
        [RGB]  A  O  |  E  U  MUTE/PP
```

### 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
- [Vendor Config (KeebMaker)](https://github.com/KeebMaker/zmk-config)
- [Vendor README](./VENDOR_README.md)

# 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

### Option 1: ZMK Studio (No Flashing Required)

ZMK Studio is enabled on this keyboard. You can edit the keymap live:

1. Go to [zmk.studio](https://zmk.studio/) in Chrome
2. Connect to `Afiq Zudin Corne42` via USB or BLE
3. Edit layers visually — changes apply instantly
4. Changes persist on the keyboard (survives power cycle)

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

**Warning:** ZMK Studio saves changes to flash storage. These saved changes override compiled keymap. If you flash new firmware and layers behave unexpectedly, do a [Settings Reset](#settings-reset) first.

### Option 2: Edit Config Files

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

Keymaps and config are located in the following directory:

```
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.