From c33f806bf22dabf7596b98937173c923993205c3 Mon Sep 17 00:00:00 2001 From: rootiest Date: Mon, 13 Apr 2026 14:13:38 -0400 Subject: [PATCH] docs: initial wiki for Q5 Max custom firmware Complete reference documentation covering all firmware features: - Home.md: overview, quick-reference tables, encoder summary - Layers.md: all 6 layers with ASCII key maps and navigation guide - Custom-Keys.md: CAPS_MOD, BSP_DEL, layer locks, ALT_TAB, CHORD_KEY - Chord-Unicode.md: how chord mode works + full 100+ entry reference - Features.md: Caps Word, Autocorrect, Combos, Tap Dance, NKRO, VIA - LED-Indicators.md: Esc layer indicator, CapsLock multi-state indicator, Win/Mac DIP switch white overlay, wireless status LEDs - Wireless-and-Control.md: BT pairing, 2.4G, KEEB_CTL layer reference, EEPROM reset, DIP switch behaviour - RGB-Controls.md: all KEEB_CTL RGB keys, Launcher integration, default colour scheme --- Chord-Unicode.md | 223 ++++++++++++++++++++++++++++++++++++++++ Custom-Keys.md | 86 ++++++++++++++++ Features.md | 102 ++++++++++++++++++ Home.md | 67 +++++++++++- LED-Indicators.md | 67 ++++++++++++ Layers.md | 184 +++++++++++++++++++++++++++++++++ RGB-Controls.md | 101 ++++++++++++++++++ Wireless-and-Control.md | 106 +++++++++++++++++++ 8 files changed, 935 insertions(+), 1 deletion(-) create mode 100644 Chord-Unicode.md create mode 100644 Custom-Keys.md create mode 100644 Features.md create mode 100644 LED-Indicators.md create mode 100644 Layers.md create mode 100644 RGB-Controls.md create mode 100644 Wireless-and-Control.md diff --git a/Chord-Unicode.md b/Chord-Unicode.md new file mode 100644 index 0000000..5b2b740 --- /dev/null +++ b/Chord-Unicode.md @@ -0,0 +1,223 @@ +# Chord Unicode + +The Chord Unicode system lets you type special characters, symbols, and emoji by typing a short mnemonic sequence — no copy-paste or OS character picker needed. + +--- + +## How to Use + +### Step 1 — Activate + +Hold `FN1`, then press `Left Alt` (`CHORD_KEY`). You are now in chord mode. + +There are two sub-modes: + +| Mode | How to activate | How it works | +|------|----------------|--------------| +| **Hold mode** | Keep `FN1`+`Alt` held down | Type the sequence while holding; output fires on release or exact match | +| **Tap mode** | Tap `FN1`+`Alt` and release | Type the sequence within 2 seconds; output fires on exact match | + +### Step 2 — Type the sequence + +Type the mnemonic letters (always lowercase — capitalisation does not matter). For example, type `d`, `e`, `g` for the degree sign `°`. + +- **Backspace** deletes the last character of the sequence (does not go to the host). +- **Enter** forces output of the current buffer even if it could be a prefix of a longer sequence. +- **Escape** cancels chord mode without sending anything. +- Any key that is not a letter, digit, Backspace, Enter, or Escape cancels chord mode silently. + +### Step 3 — Output fires automatically + +As soon as the buffer matches a chord entry exactly **and** no longer sequence with different output starts the same way, the character is sent and chord mode exits. If there is ambiguity (the buffer matches one entry but is also the start of a longer one that outputs something different), a 300 ms timer fires after the last keypress and commits the shorter match. + +--- + +## Unicode Input Method + +Characters are sent using the **Linux unicode input method**: `Ctrl+Shift+U`, then the hex code point, then `Enter`. This works natively on most Linux desktops (X11 and Wayland with GTK apps). If you are using a different OS, you may need to configure QMK's unicode input mode in the firmware. + +--- + +## Complete Chord Reference + +### Math & Science + +| Sequence | Also accepts | Character | Name | +|----------|-------------|-----------|------| +| `deg` | | ° | Degree sign | +| `sqrt` | | √ | Square root | +| `sqrd` | | ² | Superscript 2 | +| `cubd` | | ³ | Superscript 3 | +| `aprx` | `apx` | ≈ | Almost equal to | +| `neq` | | ≠ | Not equal to | +| `lteq` | `lte` | ≤ | Less than or equal | +| `gteq` | `gte` | ≥ | Greater than or equal | +| `pm` | | ± | Plus-minus | +| `div` | | ÷ | Division sign | +| `times` | `mult` | × | Multiplication sign | +| `infty` | `inf` | ∞ | Infinity | +| `pi` | | π | Pi | +| `micro` | | µ | Micro sign | +| `sigma` | | Σ | Capital sigma | +| `delta` | | Δ | Capital delta | +| `theta` | | θ | Theta | +| `omega` | | Ω | Capital omega | +| `alpha` | | α | Alpha | +| `beta` | | β | Beta | + +### Currency + +| Sequence | Character | Name | +|----------|-----------|------| +| `euro` | € | Euro | +| `pound` | £ | Pound sterling | +| `yen` | ¥ | Yen / Yuan | +| `cent` | ¢ | Cent sign | + +### Fractions + +| Sequence | Character | | +|----------|-----------|--| +| `half` | ½ | One half | +| `qtr` | ¼ | One quarter | +| `3qtr` | ¾ | Three quarters | + +### Legal / IP + +| Sequence | Character | Name | +|----------|-----------|------| +| `copy` | © | Copyright | +| `reg` | ® | Registered trademark | +| `tm` | ™ | Trademark | + +### Arrows + +| Sequence | Character | Direction | +|----------|-----------|-----------| +| `arrl` | ← | Left | +| `arrr` | → | Right | +| `arru` | ↑ | Up | +| `arrd` | ↓ | Down | +| `arrh` | ↔ | Left ↔ right | +| `arrv` | ↕ | Up ↕ down | +| `dbl` | ⇒ | Double right arrow | + +### Typography + +| Sequence | Character | Name | +|----------|-----------|------| +| `bull` | • | Bullet | +| `mdash` | — | Em dash | +| `ndash` | – | En dash | +| `ellip` | … | Horizontal ellipsis | + +### Emoji — Faces + +| Sequence | Emoji | Name | +|----------|-------|------| +| `smile` | 🙂 | Slightly smiling | +| `grin` | 😁 | Beaming / grinning | +| `lol` | 😂 | Tears of joy | +| `cry` | 😭 | Loudly crying | +| `sad` | 🙁 | Slightly frowning | +| `wink` | 😉 | Winking | +| `cool` | 😎 | Sunglasses | +| `think` | 🤔 | Thinking | +| `shrug` | 🤷 | Shrugging | +| `ugh` | 😤 | Steam from nose | +| `wow` | 😮 | Open mouth | +| `zip` | 🤐 | Zipper mouth | +| `nerdy` | 🤓 | Nerd | + +### Emoji — Gestures + +| Sequence | Emoji | Name | +|----------|-------|------| +| `thup` | 👍 | Thumbs up | +| `thdn` | 👎 | Thumbs down | +| `wave` | 👋 | Waving hand | +| `clap` | 👏 | Clapping | +| `fist` | ✊ | Raised fist | +| `pray` | 🙏 | Folded hands | +| `ok` | 👌 | OK hand | +| `point` | 👉 | Pointing right | + +### Emoji — Symbols + +| Sequence | Emoji | Name | +|----------|-------|------| +| `heart` | ❤ | Heart | +| `check` | ✓ | Check mark | +| `cross` | ✗ | Ballot X | +| `warn` | ⚠ | Warning | +| `stop` | 🛑 | Stop sign | +| `yes` | ✅ | Heavy check mark | +| `nope` | ❌ | Cross mark | +| `ques` | ❓ | Question mark | +| `excl` | ❗ | Exclamation mark | +| `help` | ℹ | Information | +| `fire` | 🔥 | Fire | +| `star` | ⭐ | Star | +| `tada` | 🎉 | Party popper | +| `100` | 💯 | Hundred points | +| `zzz` | 💤 | Sleeping / zzz | +| `skull` | 💀 | Skull | +| `poop` | 💩 | Pile of poo | +| `eyes` | 👀 | Eyes | +| `bell` | 🔔 | Bell | +| `mute` | 🔇 | Muted speaker | +| `loud` | 🔊 | Loud speaker | +| `bulb` | 💡 | Light bulb | +| `tack` | 📌 | Pushpin | +| `key` | 🔑 | Key | +| `lock` | 🔒 | Lock | +| `robot` | 🤖 | Robot | +| `alien` | 👽 | Alien | + +### Emoji — Nature + +| Sequence | Emoji | Name | +|----------|-------|------| +| `sun` | ☀ | Sun | +| `moon` | 🌙 | Crescent moon | +| `snow` | ❄ | Snowflake | +| `rain` | 🌧 | Rain cloud | +| `bolt` | ⚡ | Lightning | +| `cat` | 🐱 | Cat face | +| `dog` | 🐶 | Dog face | +| `fox` | 🦊 | Fox face | +| `bear` | 🐻 | Bear face | + +### Emoji — Food & Objects + +| Sequence | Emoji | Name | +|----------|-------|------| +| `coffee` | ☕ | Hot beverage | +| `beer` | 🍺 | Beer mug | +| `pizza` | 🍕 | Pizza | +| `cake` | 🎂 | Birthday cake | +| `gift` | 🎁 | Wrapped gift | +| `mike` | 🎤 | Microphone | +| `mus` | 🎵 | Musical note | +| `phone` | 📱 | Mobile phone | +| `pc` | 💻 | Laptop | +| `book` | 📖 | Open book | +| `mail` | 📧 | E-mail | +| `money` | 💰 | Money bag | +| `gem` | 💎 | Gem stone | +| `sword` | ⚔ | Crossed swords | +| `shield` | 🛡 | Shield | +| `rocket` | 🚀 | Rocket | +| `tools` | 🔧 | Wrench / tools | +| `trash` | 🗑 | Wastebasket | +| `clock` | 🕐 | Clock | +| `hour` | ⏳ | Hourglass | + +--- + +## Tips + +- **Aliases:** Some characters have multiple valid sequences (e.g. `inf` and `infty` both produce `∞`). Both sequences work equally well. +- **Disambiguation timer:** If your sequence is both a complete match and the start of a longer one with different output (e.g. hypothetically `lte` and `lteq`), just wait 300 ms after your last keypress and the shorter match fires. Or press `Enter` to confirm immediately. +- **Timeout:** In tap mode, chord input is cancelled if you stop typing for 2 seconds. +- **Mistakes:** Press `Backspace` to delete the last character, or `Escape` to cancel completely. diff --git a/Custom-Keys.md b/Custom-Keys.md new file mode 100644 index 0000000..7d8eb88 --- /dev/null +++ b/Custom-Keys.md @@ -0,0 +1,86 @@ +# Custom Keys + +This page documents every custom keycode implemented in the firmware. + +--- + +## CAPS_MOD + +**Location:** CapsLock key (BASE layer and all FN layers) + +`CAPS_MOD` replaces the standard CapsLock key with a context-sensitive multi-function key. Its behaviour depends on which modifier (if any) is held when you press and release it. + +| Action | Output | +|--------|--------| +| **Tap** (no modifier) | `Escape` | +| **Hold** (no modifier, past tapping term) | `Left Ctrl` — acts as a regular Ctrl while held | +| **`Shift` + Tap** | Toggle CapsLock | +| **`Alt` + Tap** | Toggle [Caps Word](Features#caps-word) | +| **`GUI` + Tap** | Toggle [Autocorrect](Features#autocorrect) on/off | + +> **How "hold = Ctrl" works:** If you press CAPS_MOD and hold it past the tapping term without releasing, it registers Left Ctrl. Any keys typed while it is held are Ctrl-modified normally. Releasing CAPS_MOD unregisters Ctrl. + +> **Modifier detection:** When you press CAPS_MOD with a modifier already held, a harmless dummy keystroke (`F24`) is sent first so the OS does not interpret the modifier release as a bare tap (which would, for example, open the Windows Start menu on a GUI press). + +--- + +## BSP_DEL + +**Location:** Not currently assigned to any key by default — available for mapping via VIA. + +`BSP_DEL` is a dual-function Backspace/Delete key. + +| Action | Output | +|--------|--------| +| **Tap** | `Backspace` | +| **`Shift` + Tap** | `Delete` (Shift is temporarily removed so the OS sees a plain Delete) | + +--- + +## Layer Lock Keys + +These keys are found on the **number row** when FN1, FN2, FN3, or FN4 is active. + +| Key | Position | Action | +|-----|----------|--------| +| `LCK_FN1` | `1` key (FN1/FN2/FN3) | Toggle-lock FN1 | +| `LCK_FN2` | `2` key (FN1/FN2/FN3) | Toggle-lock FN2 | +| `LCK_FN3` | `3` key (FN1/FN2/FN3) | Toggle-lock FN3 | +| `LCK_FN4` | `4` key (FN1/FN2/FN3) | Toggle-lock FN4 | +| `LCK_CTL` | `5` key (FN1/FN2/FN3) | Toggle-lock KEEB_CTL | +| `LCK_BASE` | `0` key (FN1/FN2/FN3) | Clear all locks, return to BASE | + +**How locking works:** + +- Press `LCK_FN1` while FN1 is active → FN1 stays on even after you release the FN1 key. +- Press `LCK_FN1` again while FN1 is locked → unlocks FN1 and returns to BASE. +- Only one layer can be locked at a time. Pressing a different `LCK_*` key unlocks the current one. +- `LCK_BASE` clears all locks unconditionally. +- The **`, + . + /` combo** also clears all locks and returns to BASE as an emergency fallback. See [Features — Combos](Features#combos). + +> **TT() vs LCK:** The `FN1` and `FN2` keys on the bottom row use QMK's `TT()` (tap-toggle). A **single tap + hold** activates momentarily; a **double-tap** locks the layer on. The `LCK_*` keys are an additional explicit locking mechanism that works from inside any layer. + +--- + +## ALT_TAB_FWD / ALT_TAB_BWD + +**Location:** Encoder (rotate right/left) while on **FN2 layer** + +These keys implement a smart Alt+Tab window switcher: + +| Key | Action | +|-----|--------| +| `ALT_TAB_FWD` | Press Alt+Tab (cycle forward through windows) | +| `ALT_TAB_BWD` | Press Alt+Shift+Tab (cycle backward) | + +**Smart Alt-hold behaviour:** The first rotation press registers and holds `Left Alt`. Each subsequent rotation tap sends another `Tab` (or `Shift+Tab`). Alt is **automatically released** 750 ms after the last rotation event, committing the window selection. + +This means you can spin the encoder multiple notches to skip several windows, and the moment you stop turning for ¾ of a second the switcher closes — no need to press anything to confirm. + +--- + +## CHORD_KEY + +**Location:** Left Alt key, **FN1 layer only** + +Activates [Chord Unicode](Chord-Unicode) mode. While FN1 is held, pressing Left Alt enters (or exits) the chord input subsystem. See the [Chord Unicode](Chord-Unicode) page for full documentation. diff --git a/Features.md b/Features.md new file mode 100644 index 0000000..0484e5f --- /dev/null +++ b/Features.md @@ -0,0 +1,102 @@ +# Features + +--- + +## Caps Word + +**Activate:** `Alt` + `CAPS_MOD` (tap) +**Deactivate:** Same combination, or press any non-word key, or complete a word (Space, Enter, etc.) + +Caps Word is a "smart" uppercase mode. Once active, every letter key you press is automatically capitalised — but Caps Word turns itself **off** the moment you press a key that doesn't belong in a word, such as Space, Enter, Tab, or punctuation. This makes it ideal for typing `ALL_CAPS_CONSTANTS` or `MY_VARIABLE_NAME` without fumbling with Shift. + +**Keys that keep Caps Word active** (do not terminate it): +- Letters (`A`–`Z`) +- Digits (`0`–`9`) +- `Backspace` +- `-` and `_` (useful for `SCREAMING_SNAKE_CASE`) + +**Keys that terminate Caps Word:** +- Space, Enter, Tab, Escape +- Most punctuation + +**[LED indicator](LED-Indicators#caps-key-led-55):** The CapsLock key LED lights **green** while Caps Word is active. + +--- + +## Autocorrect + +**Toggle:** `GUI` + `CAPS_MOD` (tap) + +QMK's built-in autocorrect silently fixes common typos as you type. It uses a dictionary of known mistyped sequences and replaces them on the fly as soon as the full misspelling is detected. + +Autocorrect runs entirely on the keyboard — no software is needed on the host computer. It works in any application that accepts keyboard input. + +**[LED indicator](LED-Indicators#caps-key-led-55):** The CapsLock key LED lights **purple** while autocorrect is **disabled**. When autocorrect is on (default), the LED is off (or shows CapsLock/CapsWord state if those are active). + +--- + +## Combos + +Combos trigger an action when multiple keys are pressed simultaneously (within a short window). + +### Fallback to BASE + +| Keys | Action | +|------|--------| +| `,` + `.` + `/` | `TO(BASE)` — immediately switch to the BASE layer, clearing all layer state | + +This is an emergency escape: if you get stuck in an unexpected layer state and don't remember how to get back, just mash the three bottom-right keys of the main cluster at the same time. + +> The combo is defined to trigger from any layer — the keycodes are resolved against BASE, so it fires regardless of what layer is currently active. + +--- + +## Tap Dance — Home/End + +**Location:** The Home/End key in the right navigation cluster (numpad row) + +| Taps | Output | Tapping term | +|------|--------|--------------| +| Single tap | `Home` | 175 ms | +| Double tap | `End` | 175 ms | + +The 175 ms tapping term for this key is deliberately shorter than the global tapping term so the double-tap feels snappy and natural. + +> On FN1 layer, the Home/End key outputs a plain `End` instead of the tap-dance, and the arrow keys map to Home/End directly. + +--- + +## N-Key Rollover (NKRO) + +**Toggle:** `NK_TOGG` key on the KEEB_CTL layer (`FN1`+`5`, then `N` key) + +By default the keyboard operates in 6KRO (6-key rollover) mode for compatibility. Pressing `NK_TOGG` switches to full NKRO mode, which allows any number of simultaneous keypresses to be registered. Press `NK_TOGG` again to revert to 6KRO. + +--- + +## VIA / Keychron Launcher + +The firmware is built with VIA support enabled. This means you can remap any key, adjust lighting, and manage macros **live** without reflashing the firmware, using either: + +- **Keychron Launcher** — Keychron's own browser-based configuration tool +- **VIA** — the universal QMK configurator at `usevia.app` + +Changes made through VIA/Launcher are saved to the keyboard's EEPROM and persist across power cycles. The firmware's 6 layers are all editable through VIA. + +--- + +## Raw HID Host Bridge + +The keyboard maintains a bidirectional communication channel with a host-side application over USB HID. This allows: + +- **Layer sync:** The host app receives the current active layer whenever it changes, and can also push layer changes to the keyboard. +- **Volume / brightness reporting:** The host can report system volume and screen brightness to the keyboard for future RGB indicator use. +- **Active app detection:** Planned for a future update. + +This feature is transparent during normal use — it only activates when the companion host application is running. + +--- + +## Debounce + +The firmware uses QMK's `sym_defer_pk` debounce algorithm (symmetric, per-key, deferred). This algorithm reduces false keypresses from switch bounce while minimising input latency compared to the default symmetric eager approach. It is particularly effective for the Q5 Max's Gateron mechanical switches. diff --git a/Home.md b/Home.md index 5d08b7b..17ab172 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,66 @@ -Welcome to the Wiki. \ No newline at end of file +# Keychron Q5 Max — Custom Firmware Documentation + +This wiki covers the custom QMK firmware built for the **Keychron Q5 Max ANSI Encoder** keyboard. It is intended as a complete reference for anyone who wants to use, understand, or extend the firmware without reading the source code. + +--- + +## Navigation + +| Page | What it covers | +|------|----------------| +| [Layers](Layers) | All six layers with visual key maps | +| [Custom Keys](Custom-Keys) | CAPS_MOD, layer locks, BSP_DEL, Alt-Tab keys | +| [Chord Unicode](Chord-Unicode) | How to enter symbols and emoji with short mnemonics | +| [Features](Features) | Caps Word, Autocorrect, Combos, Tap Dance | +| [LED Indicators](LED-Indicators) | What every RGB indicator means | +| [Wireless & Control](Wireless-and-Control) | Bluetooth, 2.4 GHz, USB, battery, KEEB_CTL layer | +| [RGB Controls](RGB-Controls) | How to adjust lighting effects and colours | + +--- + +## Quick Overview + +The firmware is based on Keychron's `wireless_playground` QMK fork with extensive customisation layered on top. + +### Hardware + +| Feature | Detail | +|---------|--------| +| Keyboard | Keychron Q5 Max, ANSI layout, 101 keys | +| Encoder | Rotary knob — top-right corner | +| DIP switch | Side switch selects **Mac** (left) or **Win** (right) backlight mode | +| Wireless | Bluetooth 5.1 (3 hosts) + 2.4 GHz USB dongle + wired USB-C | +| MCU | STM32F401 | + +### Layers at a Glance + +| Layer | Number | How to reach it | Primary use | +|-------|--------|-----------------|-------------| +| BASE | 0 | Default | Normal typing | +| FN1 | 1 | Hold / lock `FN1` key | Media, chording, navigation shortcuts | +| FN2 | 2 | Hold / lock `FN2` key | Mouse keys, F13–F24 | +| FN3 | 3 | Accessed from FN1 | Media + extended navigation | +| FN4 | 4 | Accessed from FN3/FN2 | Media + extended navigation | +| KEEB_CTL | 5 | One-shot from FN1, or locked | Wireless, RGB, keyboard settings | + +> **Layer indicator:** The **Escape key** LED changes colour to show which layer is active. See [LED Indicators](LED-Indicators). + +### Encoder Summary + +| Layer | Turn left | Turn right | +|-------|-----------|------------| +| BASE | Volume down | Volume up | +| FN1 | Rewind | Fast-forward | +| FN2 | Alt+Shift+Tab (prev window) | Alt+Tab (next window) | +| FN3 | Rewind | Fast-forward | +| FN4 | Rewind | Fast-forward | +| KEEB_CTL | RGB brightness down | RGB brightness up | + +--- + +## Firmware Build Info + +- **QMK fork:** Keychron `wireless_playground` +- **Keymap:** `keyboards/keychron/q5_max/ansi_encoder/keymaps/via` +- **VIA support:** Yes — keys can be remapped live in Keychron Launcher or VIA +- **Unicode method:** Linux (`Ctrl+Shift+U` → hex → `Enter`) diff --git a/LED-Indicators.md b/LED-Indicators.md new file mode 100644 index 0000000..8bbaec4 --- /dev/null +++ b/LED-Indicators.md @@ -0,0 +1,67 @@ +# LED Indicators + +The firmware uses two specific keys as dedicated status indicators, plus a full-keyboard overlay for the Win/Mac DIP switch. + +--- + +## Escape Key LED (LED 0) — Layer Indicator + +The Escape key LED shows which layer is currently active at a glance. + +| Layer | ESC LED colour | Layer name | +|-------|---------------|------------| +| BASE (0) | **Off** (dark) | Normal typing | +| FN1 (1) | **Blue** | Media / chord / shortcuts | +| FN2 (2) | **Green** | Mouse / F13–F24 | +| FN3 (3) | **Orange** | Media + extended navigation | +| FN4 (4) | **Purple** | Media + reset path | +| KEEB_CTL (5) | **Red** | Keyboard settings | + +> When BASE is active the Escape key LED is always off — it blends into the background effect and does not distract during normal typing. + +--- + +## Caps Key LED (LED 55) — CapsLock / Caps Word / Autocorrect + +The key physically labelled CapsLock (which is mapped to [CAPS_MOD](Custom-Keys#caps_mod)) doubles as a multi-state status indicator for the three Caps-related features. The states are checked in priority order: + +| Priority | Condition | LED colour | Meaning | +|----------|-----------|-----------|---------| +| 1 (highest) | [Caps Word](Features#caps-word) is active | **Green** | Temporary uppercase mode | +| 2 | [Autocorrect](Features#autocorrect) is **disabled** | **Purple** | Typo correction is off | +| 3 | System CapsLock is on | **White** | Traditional uppercase lock | +| 4 (lowest) | None of the above | **Off** | Normal state | + +**Reading the indicator:** + +- **Green** → Caps Word is active. The next word will be typed in uppercase, then it will turn off automatically. +- **Purple** → You have disabled Autocorrect (via `GUI`+`CAPS_MOD`). Re-enable it the same way to clear the purple light. +- **White** → Standard OS CapsLock is on (toggled via `Shift`+`CAPS_MOD`). +- **Off** → Everything is normal: Autocorrect is running, CapsLock is off, Caps Word is off. + +--- + +## Win/Mac DIP Switch — Full-Keyboard White Overlay + +The side DIP switch selects between **Mac mode** (switch toward the keyboard) and **Win mode** (switch away from the keyboard). + +When **Win mode** is active: +- **All LEDs** are overridden to **solid white**, regardless of which RGB effect or colour scheme is configured. +- The underlying RGB effect continues to run in the background — it is not changed or reset. +- Layer indicators (Escape key, CapsLock key) are still painted **on top of** the white background, so they remain visible. +- Switching back to **Mac mode** instantly restores the configured RGB effect exactly as it was. + +> This is purely a visual indicator. Neither the RGB effect settings nor EEPROM are modified by the DIP switch. + +--- + +## Bluetooth / Wireless Indicators + +Keychron's firmware displays wireless status using the dedicated indicator LEDs built into the keyboard's PCB (separate from the per-key RGB matrix). These are driven by Keychron's own indicator system and show: + +- **BT host selection** (hosts 1–3 indicated by their respective indicator LEDs) +- **2.4 GHz mode** indicator +- **Battery level** animation when `BAT_LVL` is pressed +- **Low battery** warning + +See [Wireless & Control](Wireless-and-Control) for details on selecting wireless modes. diff --git a/Layers.md b/Layers.md new file mode 100644 index 0000000..c421ed6 --- /dev/null +++ b/Layers.md @@ -0,0 +1,184 @@ +# Layers + +The firmware has **6 layers**. Lower-numbered layers are always active as the base; higher-numbered layers take priority over them when activated. A key shown as `———` (transparent) falls through to the next active layer below. + +--- + +## Physical Layout Reference + +The Q5 Max is a full-size 100% keyboard with an integrated side numpad and a rotary encoder in the top-right corner. + +``` + ┌───────┐ ┌────┬────┬────┬────┐ ┌────┬────┬────┬────┐ ┌────┬────┬────┬────┐ ┌──────┬───────┬───────┐ ╔═════╗ + │ ESC │ │ F1 │ F2 │ F3 │ F4 │ │ F5 │ F6 │ F7 │ F8 │ │ F9 │F10 │F11 │F12 │ │ Del │ PrtSc │ Calc │ ║ Enc ║ + └───────┘ └────┴────┴────┴────┘ └────┴────┴────┴────┘ └────┴────┴────┴────┘ └──────┴───────┴───────┘ ╚═════╝ + ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───────┐ ┌─────┐ ┌─────┬─────┬─────┬─────┐ + │ ` │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ 8 │ 9 │ 0 │ - │ = │ Bspc │ │PgUp │ │ Num │ / │ * │ - │ + ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬───┤ ├─────┤ ├─────┼─────┼─────┼─────┤ + │ Tab │ Q │ W │ E │ R │ T │ Y │ U │ I │ O │ P │ [ │ ] │ \ │ │PgDn │ │ 7 │ 8 │ 9 │ │ + ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴────┤ ├─────┤ ├─────┼─────┼─────┤ + │ + │ CAPS │ A │ S │ D │ F │ G │ H │ J │ K │ L │ ; │ ' │ Enter │ │ H/E │ │ 4 │ 5 │ 6 │ │ + ├──────┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┴──┬───┤ ├─────┤ ├─────┼─────┼─────┼─────┤ + │ Shift │ Z │ X │ C │ V │ B │ N │ M │ , │ . │ / Shift│ ↑ │ │ │ │ 1 │ 2 │ 3 │ │ + ├────┬───┴┬──┴──┬─┴───┴───┴───┴───┴───┴──┬┴──┬┴──┬────┬┴──┬┴──┐ └─────┘ ├─────┴─────┼─────┤Ent │ + │Ctrl│GUI │ Alt │ Space │FN2│FN1│Ctrl│ ← │ ↓ │ → │ │ 0 │ . │ │ + └────┴────┴─────┴─────────────────────────┴───┴───┴────┴───┴───┴───┘ └───────────┴─────┴─────┘ +``` + +> **Note:** `CAPS` = [CAPS_MOD](Custom-Keys#caps_mod) — a multi-function key, not a plain CapsLock. +> `H/E` = [Home/End tap-dance](Features#tap-dance-homeend). +> `FN1` / `FN2` are tap-toggle keys — see [Layer Navigation](#layer-navigation) below. + +--- + +## Layer Navigation + +### Momentary vs Locked + +| Action | Result | +|--------|--------| +| **Hold** `FN1` | FN1 active while held; returns to BASE on release | +| **Double-tap** `FN1` | FN1 locked on (toggle) | +| **Hold** `FN2` | FN2 active while held; returns to BASE on release | +| **Double-tap** `FN2` | FN2 locked on (toggle) | +| **`LCK_FN1`–`LCK_CTL`** keys | Hard-lock a specific layer; press again to unlock | +| **`LCK_BASE`** | Clear all locks and return to BASE | +| **Combo `,` + `.` + `/`** | Emergency return to BASE from any state | + +> `FN1` and `FN2` use QMK's `TT()` (tap-toggle) behaviour with the default tapping term. See [Custom Keys — Layer Locks](Custom-Keys#layer-locks) for the `LCK_*` keys. + +--- + +## BASE Layer (0) + +Normal typing layer. Nothing unusual except: +- **CAPS key** → [CAPS_MOD](Custom-Keys#caps_mod) (multi-function) +- **Right-side numpad Home/End key** → [Tap-Dance Home/End](Features#tap-dance-homeend) +- **`FN2`/`FN1`** bottom-right → tap-toggle layer access + +``` + ESC F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 Del PrtSc Calc Find [Vol] + + ` 1 2 3 4 5 6 7 8 9 0 - = Bspc PgUp Num / * - + Tab Q W E R T Y U I O P [ ] \ PgDn 7 8 9 +CAPS* A S D F G H J K L ; ' Ent H/E* 4 5 6 + +Shift Z X C V B N M , . / Shift ↑ 1 2 3 +Ctrl GUI Alt Space FN2 FN1 Ctrl ← ↓ → 0 . Ent +``` + +--- + +## FN1 Layer (1) + +Activated by holding or double-tapping `FN1`. + +**Key changes from BASE:** + +| Key position | BASE value | FN1 value | Notes | +|---|---|---|---| +| ESC | Esc | Sleep | Put computer to sleep | +| F1–F12 | F1–F12 | Brid/Briu/MCtrl/LnPad/RGB±/Media | macOS media & brightness | +| `1` | 1 | `LCK_FN1` | Lock/unlock FN1 | +| `2` | 2 | `LCK_FN2` | Lock/unlock FN2 | +| `3` | 3 | `LCK_FN3` | Lock/unlock FN3 | +| `4` | 4 | `LCK_FN4` | Lock/unlock FN4 | +| `5` | 5 | `LCK_CTL` | Lock/unlock KEEB_CTL | +| `0` | 0 | `LCK_BASE` | Return to BASE, clear locks | +| Left Alt | Alt | **CHORD_KEY** | Enter [Chord Unicode](Chord-Unicode) mode | +| Right Ctrl | Ctrl | `OSL(KEEB_CTL)` | One-shot: next key from KEEB_CTL | +| Right FN1 | TT(FN1) | `TG(FN1)` | Toggle FN1 on/off | +| Right FN2 | TT(FN2) | `TT(FN3)` | Tap-toggle FN3 | +| `←` | Left | Home | | +| `→` | Right | End | | +| Numpad H/E | Home/End | End | Plain End key | +| Encoder | Vol ± | Rewind / Fast-forward | | + +``` +Sleep Brid Briu MCtr LnPd VAD VAI Prv Ply Nxt Mute Vold Volu Del PrtSc Calc Find [FF] + + ` L1 L2 L3 L4 L5 6 7 8 9 L0 - = Bspc PgUp Num / * - + Tab Q W E R T Y U I O P [ ] \ PgDn 7 8 9 +CAPS* A S D F G H J K L ; ' Ent End 4 5 6 + +Shift Z X C V B N M , . / Shift ↑ 1 2 3 +Ctrl GUI CHORD Space TT3 TG1 CTL* Home ↓ End 0 . Ent +``` +> `L1`–`L5` = layer lock keys. `L0` = LCK_BASE. `CHORD` = Chord Unicode key. `CTL*` = one-shot KEEB_CTL. + +--- + +## FN2 Layer (2) + +Activated by holding or double-tapping `FN2`. Turns the keyboard into a **mouse and extended-function** layer. + +**Key changes from BASE:** + +| Key position | FN2 value | Notes | +|---|---|---| +| F1–F12 | Power / F13–F24 | ESC = Power off; F-row = F13–F24 | +| `1`–`5`, `0` | Layer locks | Same as FN1 | +| PgUp | Mouse Wheel Up | | +| PgDn | Mouse Wheel Down | | +| Numpad H/E | Mouse Button 3 (middle click) | | +| Arrow keys | Mouse movement (↑↓←→) | | +| Right FN2 | `TG(FN2)` | Toggle FN2 | +| Right FN1 | `TT(FN4)` | Tap-toggle FN4 | +| Numpad `0` | Mouse Button 1 (left click) | | +| Numpad `.` | Mouse Button 2 (right click) | | +| Encoder | Alt+Shift+Tab / Alt+Tab | Window switcher (Alt held 750 ms) | + +``` + PWR F13 F14 F15 F16 F17 F18 F19 F20 F21 F22 F23 F24 Del PrtSc Calc Find [ATab] + + ` L1 L2 L3 L4 L5 6 7 8 9 L0 - = Bspc WhlUp Num / * - + Tab Q W E R T Y U I O P [ ] \ WhlDn 7 8 9 +CAPS* A S D F G H J K L ; ' Ent MBtn3 4 5 6 + +Shift Z X C V B N M , . / Shift MsUp 1 2 3 +Ctrl GUI Alt Space TG2 TT4 Ctrl MsLft MsDn MsRgt MBtn1 MBtn2 Ent +``` + +> The **Alt+Tab** encoder in FN2 keeps Alt held for 750 ms after the last turn, then releases it automatically. You can keep cycling without lifting a finger. + +--- + +## FN3 Layer (3) + +Accessed from FN1 via `TT(FN3)` (right FN2 key while FN1 is active). Media row and navigation, same lock keys, standard arrow/numpad behaviour. + +Identical to BASE except: +- **F-row** → brightness, media controls (same mapping as FN1 F-row) +- **Number row** → layer locks (same as FN1/FN2) +- **Right FN2** → `TG(FN3)` (toggle FN3) +- **Right FN1** → `TT(FN4)` (tap-toggle FN4) +- **Encoder** → Rewind / Fast-forward + +--- + +## FN4 Layer (4) + +Accessed from FN3 or FN2 via `TT(FN4)`. Identical to FN3 except: +- **Right FN2** → `TO(BASE)` — go directly back to BASE (clears all layers) +- **Right FN1** → `TG(FN4)` (toggle FN4) + +> Use FN4 as a "reset to base" escape hatch when you've navigated deep into layers. + +--- + +## KEEB_CTL Layer (5) + +The keyboard control layer. Reached via: +- `OSL(KEEB_CTL)` on Right Ctrl while FN1 is held — one-shot (affects next key only) +- `LCK_CTL` (`FN1` + `5`) — locks KEEB_CTL on + +See [Wireless & Control](Wireless-and-Control) for full details. + +``` + ——— Brid Briu Task File VAD VAI Prv Ply Nxt Mute Vold Volu ——— ——— ——— ——— [RGB±] + + ——— BT1 BT2 BT3 2.4G ——— ——— ——— ——— ——— L0 ——— ——— ——— ——— ——— ——— ——— +RGBt RGBm VAI+ HUI+ SAI+ SPI+ ——— ——— ——— ——— ——— ——— ——— ——— ——— ——— ——— ——— + ——— RGBr VAD- HUD- SAD- SPD- ——— ——— ——— ——— ——— ——— ——— End ——— ——— ——— + ——— ——— ——— ——— ——— BAT NKro ——— ——— ——— ——— ——— ——— ——— ——— + ——— ——— ——— ——— ——— ——— ——— ——— ↓ ——— EECLR ——— ——— +``` + +> `BT1`–`BT3` = Bluetooth host 1–3. `2.4G` = 2.4 GHz wireless dongle. `BAT` = show battery level. `NKro` = toggle N-key rollover. `EECLR` = clear EEPROM. `RGBt` = RGB toggle. See [Wireless & Control](Wireless-and-Control) and [RGB Controls](RGB-Controls). diff --git a/RGB-Controls.md b/RGB-Controls.md new file mode 100644 index 0000000..e9aa8b1 --- /dev/null +++ b/RGB-Controls.md @@ -0,0 +1,101 @@ +# RGB Controls + +The Q5 Max has a full per-key RGB matrix with Keychron's extended effect system (PER_KEY_RGB and MIXED_RGB) manageable through both the KEEB_CTL layer and Keychron Launcher. + +--- + +## Accessing RGB Controls + +RGB keys are on the **KEEB_CTL layer**. Get there with: +- **One-shot:** Hold `FN1`, tap Right Ctrl → press one RGB key +- **Locked:** `FN1`+`5` (LCK_CTL) → use RGB keys freely → `FN1`+`0` or `LCK_BASE` to exit + +--- + +## RGB Key Reference + +### On/Off + +| Key | Location | Action | +|-----|----------|--------| +| `RGB_TOG` | `Tab` key (KEEB_CTL) | Toggle RGB on/off | +| `RGB_TOG` | Encoder press (KEEB_CTL) | Toggle RGB on/off | + +### Effect & Mode + +| Key | Location | Action | +|-----|----------|--------| +| `RGB_MOD` | `Q` | Next effect mode | +| `RGB_RMOD` | `A` | Previous effect mode | + +### Brightness + +| Key | Location | Action | +|-----|----------|--------| +| `RGB_VAI` | `W` | Brightness up | +| `RGB_VAD` | `S` | Brightness down | +| Encoder CW | (KEEB_CTL layer) | Brightness up | +| Encoder CCW | (KEEB_CTL layer) | Brightness down | +| `RGB_VAI` / `RGB_VAD` | `F5` / `F6` in F-row | Brightness ± | + +### Hue (Colour) + +| Key | Location | Action | +|-----|----------|--------| +| `RGB_HUI` | `E` | Hue up (shift colour) | +| `RGB_HUD` | `D` | Hue down | + +### Saturation + +| Key | Location | Action | +|-----|----------|--------| +| `RGB_SAI` | `R` | Saturation up (more vivid) | +| `RGB_SAD` | `F` | Saturation down (toward white) | + +### Animation Speed + +| Key | Location | Action | +|-----|----------|--------| +| `RGB_SPI` | `T` | Speed up animation | +| `RGB_SPD` | `G` | Slow down animation | + +--- + +## Summary Layout (KEEB_CTL layer, main cluster) + +``` +RGBt RGBm VAI+ HUI+ SAI+ SPI+ ··· ··· ··· ··· ··· ··· ··· + RGBr VAD- HUD- SAD- SPD- ··· ··· ··· ··· ··· ··· +``` + +> `RGBt` = toggle, `RGBm` = next mode, `RGBr` = previous mode, `VAI/VAD` = brightness, `HUI/HUD` = hue, `SAI/SAD` = saturation, `SPI/SPD` = speed. + +--- + +## Keychron Launcher / VIA Integration + +Keychron's extended RGB effects (**PER_KEY_RGB** and **MIXED_RGB**) are configured through Keychron Launcher. These effects allow: + +- **PER_KEY_RGB:** Assign a unique colour to every individual key. +- **MIXED_RGB:** Divide keys into regions, each playing a different animated effect simultaneously, with optional timed transitions between effects. + +Settings configured in Launcher are saved to EEPROM and survive: +- Power cycles +- Bluetooth/2.4 GHz transport changes (wireless reconnect) + +> If RGB reverts to the default heatmap after a transport change or power cycle, it indicates an EEPROM issue. The custom firmware specifically fixes this — see the [firmware changelog](https://git.rootiest.dev/rootiest/qmk_firmware/pulls) for details. + +--- + +## Default Colour Scheme (Per-Key RGB defaults) + +When EEPROM is cleared (`QK_CLEAR_EEPROM`) the per-key colours reset to the firmware defaults: + +| Key group | Default colour | +|-----------|---------------| +| Escape | Red | +| CapsLock | Red | +| Alpha keys (Q–P, A–L, Z–M, Space) | Blue | +| All other keys (modifiers, F-row, numpad, etc.) | Yellow | + +These defaults are set by the `default_per_key_led[]` array in the board source code and can be overridden at any time through Keychron Launcher. diff --git a/Wireless-and-Control.md b/Wireless-and-Control.md new file mode 100644 index 0000000..7240689 --- /dev/null +++ b/Wireless-and-Control.md @@ -0,0 +1,106 @@ +# Wireless & Control + +--- + +## Connection Modes + +The Q5 Max supports three wireless/wired connection modes. You switch between them using the keys on the **KEEB_CTL layer** (hold `FN1`, tap Right Ctrl, then press the target key — or lock KEEB_CTL with `FN1`+`5`). + +| Key | Mode | Notes | +|-----|------|-------| +| `BT_HST1` | Bluetooth host 1 | Pairs/connects to the first saved Bluetooth device | +| `BT_HST2` | Bluetooth host 2 | Pairs/connects to the second saved Bluetooth device | +| `BT_HST3` | Bluetooth host 3 | Pairs/connects to the third saved Bluetooth device | +| `P2P4G` | 2.4 GHz USB dongle | Switches to the included 2.4 GHz wireless receiver | +| *(plug in cable)* | Wired USB-C | Wired mode is selected automatically when a cable is plugged in | + +### Bluetooth Pairing + +To pair with a new device on a BT slot: +1. Make sure the keyboard is not currently connected on that slot (or the existing pairing is out of range). +2. Press `BT_HST1`, `BT_HST2`, or `BT_HST3` on the KEEB_CTL layer. +3. The keyboard will begin advertising. Find it on your device's Bluetooth settings and pair normally. + +### Forgetting a Pairing + +Hold the `BT_HST*` key for approximately 3 seconds to clear the pairing for that slot. + +--- + +## Battery + +| Key | Action | +|-----|--------| +| `BAT_LVL` | Display current battery percentage using the keyboard's indicator LEDs | + +Pressing `BAT_LVL` (on the KEEB_CTL layer, mapped to the `B` key position) triggers a brief LED animation that shows approximate battery level. + +The keyboard also has a **low battery warning**: when the battery drops below a threshold, a dedicated indicator LED pulses to alert you. + +--- + +## KEEB_CTL Layer — Full Reference + +The KEEB_CTL layer is the keyboard's settings panel. Reach it by: + +- **One-shot:** While FN1 is held, tap Right Ctrl (`OSL(KEEB_CTL)`) — the next keypress comes from KEEB_CTL, then the keyboard returns to normal. +- **Locked:** Press `LCK_CTL` (`FN1`+`5`) to stay on KEEB_CTL. + +### Wireless Keys (number row) + +| Key | KEEB_CTL position | Action | +|-----|------------------|--------| +| `BT_HST1` | `1` | Bluetooth host 1 | +| `BT_HST2` | `2` | Bluetooth host 2 | +| `BT_HST3` | `3` | Bluetooth host 3 | +| `P2P4G` | `4` | 2.4 GHz dongle | +| `LCK_BASE` | `0` | Return to BASE | + +### RGB Keys (Tab row and home row) + +See [RGB Controls](RGB-Controls) for a full breakdown of the RGB keys. + +### Utility Keys + +| Key | Position | Action | +|-----|----------|--------| +| `BAT_LVL` | `B` | Show battery level | +| `NK_TOGG` | `N` | Toggle N-key rollover (NKRO) on/off | +| `QK_CLEAR_EEPROM` | Numpad `0` position | **Reset all EEPROM to factory defaults** | +| `KC_END` | Numpad H/E position | End key | +| `RGB_TOG` | Encoder press / `Tab` | Toggle RGB lighting on/off | + +### F-row (KEEB_CTL) + +| Key | Action | +|-----|--------| +| F1 | `Brid` — Screen brightness down (macOS) | +| F2 | `Briu` — Screen brightness up (macOS) | +| F3 | `Task` — Task manager / Mission Control | +| F4 | `File` — File manager | +| F5–F6 | RGB brightness down / up | +| F7–F9 | Previous / Play-Pause / Next track | +| F10 | Mute | +| F11–F12 | Volume down / up | +| Encoder | RGB brightness down / up | + +--- + +## EEPROM Reset + +> ⚠️ **Warning:** This permanently erases all EEPROM data: VIA keymaps, RGB settings, wireless pairings (some may survive — depends on Keychron's implementation), and keyboard configuration. Use only as a last resort. + +`QK_CLEAR_EEPROM` is located at the **numpad `0`** position on KEEB_CTL. After pressing it, the keyboard will restart with factory-default settings. You will need to re-pair Bluetooth devices and reconfigure your layout in VIA/Launcher. + +--- + +## DIP Switch + +The physical DIP switch on the side of the keyboard selects the **backlight preset**: + +| Position | Effect | +|----------|--------| +| Mac side (toward keyboard) | Normal RGB effect as configured | +| Win side (away from keyboard) | All LEDs white (see [LED Indicators](LED-Indicators#winmac-dip-switch--full-keyboard-white-overlay)) | + +> The DIP switch does **not** change the OS layout, key behaviour, or wireless mode on the Q5 Max — it is purely a visual indicator preset.