# 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 | `AfiqZudinCorne42` |
| 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
TAB    D  S  T  N  R  |  I  A  E  O  H    '
LSHFT  Z  X  C  V  J  |  K  P  ,  .  /    RSHFT
          ESC  CTRL GUI | SPC  ALT  ENTER

Combos: top+home row = 1-0, shift+combo = ! @ # $ % ^ & * ( )
        U+B = BSPC (I+O on QWERTY)
```

### Layer 1: HUB
```
BT_CLR BT0  BT1  BT2  BT3  BT4  | +     [     UP    ]    *    =
USB/BT _    _    _    _    _    | -     LEFT  DOWN  RIGHT /    \
LSHFT  Z    X    C    V    _    | ->QWRT ->STEN ->FPS ->L5 _   RSHFT
          ESC  CTRL GUI         | SPC   ALT   ENTER
```

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

Combos: same as CARP (top+home = 1-0, I+O = BSPC)
```

### Layer 3: STEN (Plover keyboard mode)
```
_      #  #  #  #  #  |  #  #  #  #  #    ->HUB
_      S  T  P  H  *  |  *  F  P  L  T    D
_      S  K  W  R  *  |  *  R  B  G  S    Z
          _  A  O      |  E  U  _
```

### Layer 4: FPS (Gaming, TBD)
```
ESC    1     Q   W   E   R   |  5  6  7  8  9    ->HUB
TAB    SHFT  A   S   D   F   |  _  _  _  _  _    _
CTRL   G     Z   X   C   V   |  _  _  _  _  _    _
              T   B   SPC     |  _  _  _
```

### Layer 5: Reserved

# 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 `AfiqZudinCorne42` 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 `AfiqZudinCorne42`

# Settings Reset

### When to reset

Do a settings reset when:
- 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.
