diff --git a/README.md b/README.md index 3952be4..c3baeef 100644 --- a/README.md +++ b/README.md @@ -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/.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 -│ ├── .dtsi # matrix transform + kscan -│ ├── .zmk.yml # shield metadata -│ ├── _left.overlay / _right.overlay -│ ├── _left_peripheral.* # optional, unused template -│ └── _dongle_xiao.* / _dongle_pro_micro.* # optional, unused templates -├── config/ -│ ├── west.yml # ZMK manifest (pinned revision, see comment in the file) -│ ├── config_keymap-drawer.yaml -│ └── .keymap / .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/.keymap`, with diagrams auto-generated to `keymap-drawer/.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. diff --git a/build.yaml b/build.yaml index 518bec2..1eea393 100644 --- a/build.yaml +++ b/build.yaml @@ -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 diff --git a/config/corne.keymap b/config/corne.keymap index 225d590..6cc718e 100644 --- a/config/corne.keymap +++ b/config/corne.keymap @@ -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 >; };