Fix keyboard name, BSPC combo, hub thumbs, add flash guide

- Fix: build.yaml was overriding keyboard name to Corne_Oled_RGB
- Fix: BSPC combo positions <8 9> (I+O on QWRT, U+B on CARP)
- Fix: HUB thumb row ALT/RET order to match other layers
- Rewrite README with step-by-step flash guide and settings reset
This commit is contained in:
afiqzudinhadi 2026-06-20 14:43:09 +08:00
parent 1c177d1a22
commit 603066de73
3 changed files with 229 additions and 99 deletions

320
README.md
View file

@ -1,126 +1,256 @@
# zmk-config
# Corne Keyboard Custom Keymaps (ZMK)
ZMK firmware configuration for a Corne, Lily58, Sofle, and Sweep, built via GitHub Actions.
This repository contains the custom keymaps for the Corne split keyboard. It also contains the guide on how to set up the keymaps.
- [Quick start](#quick-start)
- [Repo layout](#repo-layout)
- [Keyboards](#keyboards)
- [Display](#display)
- [RGB underglow](#rgb-underglow)
- [Dongle / peripheral templates](#dongle--peripheral-templates)
- [ZMK Studio](#zmk-studio)
- [Modules](#modules)
- [Useful tips](#useful-tips)
- [Credits](#credits)
# 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)
## Quick start
# Hardware Info
1. Fork this repository.
2. Edit the keymap for your board in `config/<keyboard>.keymap` (or use the online [keymap-editor] / [ZMK Studio Web](https://zmk.studio/)).
3. Commit and push.
4. On GitHub, go to **Actions → Build → (latest run) → Artifacts** and download the firmware zip for your board.
5. Flash the `.uf2` files to each half:
- `nice_corne_left_oled_rgb.uf2` / `nice_corne_right_oled_rgb.uf2`
- `nice_lily58_left_oled.uf2` / `nice_lily58_right_oled.uf2`
- `nice_sofle_left_rgb_oled.uf2` / `nice_sofle_right_rgb_oled.uf2`
- `nice_sweep_left.uf2` / `nice_sweep_right.uf2`
- `nice_settings_reset.uf2` — flash to both halves if they ever desync; see [Useful tips](#useful-tips).
6. Connect each half to the PC and drag-and-drop the corresponding `.uf2` onto the drive that appears after double-tapping reset.
| 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) |
Disable any board you don't need by commenting out its block in [build.yaml](./build.yaml).
## Repo layout
# Current Keymap
Key positions reference:
```
zmk-config
├── build.yaml # GitHub Actions build matrix
├── boards/
│ ├── nice_nano.overlay # RGB underglow (WS2812 over SPI) for nice!nano v1
│ ├── nice_nano_v2.overlay # same, for nice!nano v2
│ └── shields/
│ ├── corne/
│ ├── lily58/
│ ├── sofle/
│ └── sweep/
│ ├── Kconfig.shield / Kconfig.defconfig
│ ├── <name>.dtsi # matrix transform + kscan
│ ├── <name>.zmk.yml # shield metadata
│ ├── <name>_left.overlay / <name>_right.overlay
│ ├── <name>_left_peripheral.* # optional, unused template
│ └── <name>_dongle_xiao.* / <name>_dongle_pro_micro.* # optional, unused templates
├── config/
│ ├── west.yml # ZMK manifest (pinned revision, see comment in the file)
│ ├── config_keymap-drawer.yaml
│ └── <keyboard>.keymap / <keyboard>.conf
├── keymap-drawer/ # auto-generated keymap diagrams (svg + yaml)
└── snippets/
└── rgb-config/ # shared RGB underglow Kconfig, used by corne/sofle/lily58
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
```
## Keyboards
### 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
| Keyboard | Shields | Display | RGB | Notes |
|----------|---------------------------|---------------|-----|-------|
| Corne | `corne_left`, `corne_right` | 128x32 OLED | yes | |
| Lily58 | `lily58_left`, `lily58_right` | 128x32 OLED | no | encoders supported in `lily58.dtsi`, not wired up in the default keymap |
| Sofle | `sofle_left`, `sofle_right` | 128x32 OLED | yes | encoders supported |
| Sweep | `sweep_left`, `sweep_right` | none | no | 34-key direct-pin board (same PCB as the upstream ZMK `cradio` shield) |
Combos: top+home row = 1-0, shift+combo = ! @ # $ % ^ & * ( )
U+B = BSPC (I+O on QWERTY)
```
Each keyboard's keymap lives at `config/<keyboard>.keymap`, with diagrams auto-generated to `keymap-drawer/<keyboard>.svg` on every push that touches a `.keymap` file (see [.github/workflows/keymap-drawer.yaml](./.github/workflows/keymap-drawer.yaml)). Sweep doesn't have a diagram yet — its custom physical layout isn't recognized by the keymap-drawer auto-detection.
### 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
```
`settings_reset` is ZMK's built-in shield for clearing a half's Bluetooth bonds — flash it to fix desynced halves (see [Useful tips](#useful-tips)).
### 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
## Display
Combos: same as CARP (top+home = 1-0, I+O = BSPC)
```
Corne, Lily58, and Sofle each use a standard 128x32 SSD1306 OLED per half, driven by the [zmk-nice-oled] module pulled in via `config/west.yml` and enabled with the `nice_oled` shield in `build.yaml`. Sweep has no display.
### 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 _
```
## RGB underglow
### 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 | _ _ _
```
Corne and Sofle build with WS2812 underglow enabled via the `rgb-config` snippet (`snippets/rgb-config/rgb-config.conf`), which is applied through the `snippet:` field in their `build.yaml` entries. The actual LED strip wiring lives in `boards/nice_nano.overlay` / `boards/nice_nano_v2.overlay`.
### Layer 5: Reserved
Lily58 and Sweep don't enable this snippet, so they build without RGB.
# Related Resources
## Dongle / peripheral templates
- [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)
`boards/shields/{corne,lily58,sofle}/` each include `_dongle_xiao`, `_dongle_pro_micro`, and `_left_peripheral` shield variants, and `config/west.yml` pulls in three more modules for them (`zmk-dongle-display`, `zmk-dongle-display-view`, `zmk-oled-adapter`). None of these are wired up in `build.yaml` right now — they're kept as a starting point if you want to build a dongle setup later, not something this repo currently builds or tests.
# Pre-requisites
## ZMK Studio
- 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)
ZMK Studio is enabled on every active build (`CONFIG_ZMK_STUDIO=y`, `CONFIG_ZMK_STUDIO_LOCKING=n`, and the `studio-rpc-usb-uart` snippet), so you can remap keys live from [zmk.studio](https://zmk.studio/) without recompiling:
1. Flash the firmware as usual.
2. Connect the central/master half to your PC.
3. Open [zmk.studio](https://zmk.studio/) and connect to your keyboard.
# Clone Repository
## Modules
```bash
git clone git@github.com:afiqzudinhadi/zmk-config.git
```
Declared in `config/west.yml`:
# Editing the Keymap
| Module | Status | Purpose |
|--------|--------|---------|
| [zmk-nice-oled] | active | OLED display widgets, used by Corne/Lily58/Sofle's `nice_oled` shield |
| [zmk-dongle-display] | optional, unused | dongle battery/status display — only needed by the dongle template variants |
| [zmk-dongle-display-view] | optional, unused | nice!view-style version of the above |
| [zmk-oled-adapter] | optional, unused | adapter for 128x32/64/128 OLEDs without modifying shield files |
### Option 1: ZMK Studio (No Flashing Required)
## Useful tips
ZMK Studio is enabled on this keyboard. You can edit the keymap live:
- If both halves desync (won't pair), flash `nice_settings_reset.uf2` to **both** halves, then reflash the actual firmware to each.
- To re-flash a half, double-tap its reset button — it should mount as a USB drive — then drag the `.uf2` onto it.
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)
## Credits
**Limitations:** Cannot add combos, custom behaviors, or change display/RGB config.
This config was originally based on [mctechnology17/zmk-config](https://github.com/mctechnology17/zmk-config). General ZMK config inspiration also drawn from:
- [englmaxi/zmk-config](https://github.com/englmaxi/zmk-config)
- [caksoylar/zmk-config](https://github.com/caksoylar/zmk-config)
- [urob/zmk-config](https://github.com/urob/zmk-config)
- [infused-kim/zmk-config](https://github.com/infused-kim/zmk-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.
Keymap diagrams generated with [keymap-drawer](https://github.com/caksoylar/keymap-drawer).
### Option 2: Edit Config Files
[keymap-editor]: https://nickcoutsos.github.io/keymap-editor/
[zmk-nice-oled]: https://github.com/mctechnology17/zmk-nice-oled
[zmk-dongle-display]: https://github.com/englmaxi/zmk-dongle-display
[zmk-dongle-display-view]: https://github.com/mctechnology17/zmk-dongle-display-view
[zmk-oled-adapter]: https://github.com/mctechnology17/zmk-oled-adapter
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.

View file

@ -57,13 +57,13 @@ include:
### CORNE START ###
- board: nice_nano_v2
shield: corne_left nice_oled
cmake-args: -DCONFIG_ZMK_KEYBOARD_NAME=\"Corne_Oled_RGB\"
cmake-args: -DCONFIG_ZMK_KEYBOARD_NAME=\"AfiqZudinCorne42\"
artifact-name: nice_corne_left_oled_rgb
snippet: rgb-config studio-rpc-usb-uart
# nice_nano_v2 + nice_oled + RGB (RIGHT)
- board: nice_nano_v2
shield: corne_right nice_oled
cmake-args: -DCONFIG_ZMK_KEYBOARD_NAME=\"Corne_Oled_RGB\" -DCONFIG_NICE_OLED_WIDGET_ANIMATION_PERIPHERAL_CAT=n -DCONFIG_NICE_OLED_WIDGET_ANIMATION_PERIPHERAL_KM=y
cmake-args: -DCONFIG_ZMK_KEYBOARD_NAME=\"AfiqZudinCorne42\" -DCONFIG_NICE_OLED_WIDGET_ANIMATION_PERIPHERAL_CAT=n -DCONFIG_NICE_OLED_WIDGET_ANIMATION_PERIPHERAL_KM=y
artifact-name: nice_corne_right_oled_rgb
snippet: rgb-config

View file

@ -33,7 +33,7 @@
combo_9 { key-positions = <9 21>; bindings = <&kp N9>; layers = <0 2>; };
combo_0 { key-positions = <10 22>; bindings = <&kp N0>; layers = <0 2>; };
// I+P = BSPC (reduce right pinky usage)
combo_bspc { key-positions = <8 10>; bindings = <&kp BSPC>; layers = <0 2>; };
combo_bspc { key-positions = <8 9>; bindings = <&kp BSPC>; layers = <0 2>; };
};
keymap {
@ -62,7 +62,7 @@
&bt BT_CLR &bt BT_SEL 0 &bt BT_SEL 1 &bt BT_SEL 2 &bt BT_SEL 3 &bt BT_SEL 4 &kp PLUS &kp LBKT &kp UP &kp RBKT &kp ASTRK &kp EQUAL
&out OUT_TOG &none &none &none &none &none &kp MINUS &kp LEFT &kp DOWN &kp RIGHT &kp FSLH &kp BSLH
&kp LSHFT &kp Z &kp X &kp C &kp V &none &to 2 &to 3 &to 4 &to 5 &none &kp RSHFT
&kp ESC &kp LCTRL &kp LGUI &kp SPACE &kp RET &kp RALT
&kp ESC &kp LCTRL &kp LGUI &kp SPACE &kp RALT &kp RET
>;
};