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).
2026-06-24 17:54:51 +08:00 · 2026-06-24 17:54:51 +08:00 · bd20351075
commit bd20351075
parent 9d21b8ff1e
6 changed files with 291 additions and 9 deletions
--- a/README.md
+++ 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).
--- 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>;

--- 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>;

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