From bd2035107538655d8ba08028d0da2ca4053c56cf Mon Sep 17 00:00:00 2001 From: afiqzudinhadi Date: Wed, 24 Jun 2026 17:54:51 +0800 Subject: [PATCH] Disable ZMK Studio, add full README, fix LED chain-length Studio commented out in config with re-enable instructions in README. LED chain-length corrected to 27 (6 underglow + 21 per-key per half). --- README.md | 284 ++++++++++++++++++ boards/shields/corne/boards/nice_nano.overlay | 2 +- .../shields/corne/boards/nice_nano_v2.overlay | 2 +- boards/shields/corne/corne.zmk.yml | 2 +- build.yaml | 2 +- config/corne.conf | 8 +- 6 files changed, 291 insertions(+), 9 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8cd99d0 --- /dev/null +++ b/README.md @@ -0,0 +1,284 @@ +# 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) +- [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. + +# 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). diff --git a/boards/shields/corne/boards/nice_nano.overlay b/boards/shields/corne/boards/nice_nano.overlay index 424a617..4c546e6 100644 --- a/boards/shields/corne/boards/nice_nano.overlay +++ b/boards/shields/corne/boards/nice_nano.overlay @@ -31,7 +31,7 @@ spi-max-frequency = <4000000>; /* WS2812 */ - chain-length = <10>; /* arbitrary; change at will */ + chain-length = <27>; /* 6 underglow + 21 per-key per half */ spi-one-frame = <0x70>; spi-zero-frame = <0x40>; diff --git a/boards/shields/corne/boards/nice_nano_v2.overlay b/boards/shields/corne/boards/nice_nano_v2.overlay index 424a617..4c546e6 100644 --- a/boards/shields/corne/boards/nice_nano_v2.overlay +++ b/boards/shields/corne/boards/nice_nano_v2.overlay @@ -31,7 +31,7 @@ spi-max-frequency = <4000000>; /* WS2812 */ - chain-length = <10>; /* arbitrary; change at will */ + chain-length = <27>; /* 6 underglow + 21 per-key per half */ spi-one-frame = <0x70>; spi-zero-frame = <0x40>; diff --git a/boards/shields/corne/corne.zmk.yml b/boards/shields/corne/corne.zmk.yml index c496aef..08bfc3d 100644 --- a/boards/shields/corne/corne.zmk.yml +++ b/boards/shields/corne/corne.zmk.yml @@ -9,7 +9,7 @@ features: - keys - display - underglow - - studio + siblings: - corne_left - corne_right diff --git a/build.yaml b/build.yaml index 9f747d7..e3ba1d3 100644 --- a/build.yaml +++ b/build.yaml @@ -5,7 +5,7 @@ include: - board: nice_nano_v2 shield: corne_left nice_oled artifact-name: nice_corne_left_oled_rgb - snippet: rgb-config studio-rpc-usb-uart + snippet: rgb-config - board: nice_nano_v2 shield: corne_right nice_oled cmake-args: -DCONFIG_NICE_OLED_WIDGET_ANIMATION_PERIPHERAL_CAT=n -DCONFIG_NICE_OLED_WIDGET_ANIMATION_PERIPHERAL_KM=y diff --git a/config/corne.conf b/config/corne.conf index 0d04489..11983be 100644 --- a/config/corne.conf +++ b/config/corne.conf @@ -65,12 +65,10 @@ CONFIG_ZMK_EXT_POWER=y # https://github.com/zmkfirmware/zmk/blob/main/docs/docs/keymaps/behaviors/mouse-emulation.md # CONFIG_ZMK_MOUSE=y -### ZMK STUDIO -# MC: 2. zmk-studio test START +### ZMK STUDIO (disabled — enable if needed) # https://github.com/zmkfirmware/zmk/blob/main/docs/docs/config/studio.md -CONFIG_ZMK_STUDIO=y -CONFIG_ZMK_STUDIO_LOCKING=n -# MC: zmk-studio test END +# CONFIG_ZMK_STUDIO=y +# CONFIG_ZMK_STUDIO_LOCKING=n ### RGB UNDERGLOW # uncomment to enable RGB Underglow or backlight