Guideline to Change Keymaps in Real-Time Using ZMK Studio

Guideline to Change Keymaps in Real-Time Using ZMK Studio

Overview

ZMK Studio allows you to modify your keyboard’s keymap in real-time without re-flashing firmware. Changes take effect immediately after modification.

  • Important: Auto-saving may fail, causing keymaps to revert after closing the software. Always click "Save" in the top-right corner before exiting.

Tools for Keymap Changes

  1. Web Version:
    • URL: https://zmk.studio/
    • Supported Browsers: Chrome, Edge, Firefox
    • Limitation: Some operating systems only support wired connections (Bluetooth may not work).
  2. PC/ Version:

Steps to Change Keymaps

  1. Connect the Keyboard to Your Computer:
    • Connect only the left half of the keyboard via:
      • Bluetooth: Pair it with your computer.
      • Wired: Use a USB-A to USB-C or USB-C to USB-C cable.
    • The right half does not need to be connected.
    • Port Selection:
      • Mac (Wired):
        • Use the third port in the PC app.
        • If Bluetooth is also connected, use the fourth port (first port is Bluetooth).
        • Web version: Select the second port (excluding Bluetooth).
      • Windows (Wired):
        • Use the second USB port.
      • Troubleshooting:
        • If connection fails, close the app or browser, then reopen and try a different port. Incorrect port selection can lock the connection.
  2. Open ZMK Studio and Modify Keymap:
    • Launch ZMK Studio (web or PC version).
    • Select your keyboard from the detected devices.
    • Unlock the Device (if needed):
      • Use the “ZMK Studio Unlock” behavior to enable editing.
  3. Edit Key Behaviors:
    • ZMK Studio supports basic behavior modifications. Custom behaviors (e.g., encoders, mouse emulation) set in the firmware can be used but not edited—firmware reflashing is required for those changes.
    • Common Behaviors:
      Behavior Description
      Key Press Sends a keycode when pressed (e.g., “A”).
      Mod Tap Tap for one keycode, hold for another (e.g., tap = “A”, hold = “Ctrl”).
      Transparent Uses the key from the layer below.
      None No action (empty key).
      Momentary Layer Switches to a layer while held, reverts when released.
      Layer-tap Tap for a keycode, hold to switch layers.
      Mouse Button Press Simulates a mouse click.
      Mouse Move Simulates mouse movement.
      Bluetooth Manages Bluetooth actions (e.g., device switching).
      RGB Underglow Controls RGB lighting under the keyboard.
    • For more behaviors, visit
  4. Assign Keycodes:
    • After selecting “Key Press” in the Behavior menu, choose a keycode from the Key menu.
    • Modifiers: Check options on the right to combine with modifiers (e.g., “Ctrl + A” or “Ctrl + Alt + Delete”).
    • Reference: Use the ZMK studio keycode categories below to find keycodes. Copy and paste them into the Key menu for auto-matching.
  5. Save Your Changes:
    • After editing, click "Save" in the top-right corner to ensure your keymap persists after closing ZMK Studio.

Default Keymapping

Key Press Categories

  1. Letters
    • Keyboard A: a and A
    • Keyboard B: b and B
    • Keyboard C: c and C
    • Keyboard D: d and D
    • Keyboard E: e and E
    • Keyboard F: f and F
    • Keyboard G: g and G
    • Keyboard H: h and H
    • Keyboard I: i and I
    • Keyboard J: j and J
    • Keyboard K: k and K
    • Keyboard L: l and L
    • Keyboard M: m and M
    • Keyboard N: n and N
    • Keyboard O: o and O
    • Keyboard P: p and P
    • Keyboard Q: q and Q
    • Keyboard R: r and R
    • Keyboard S: s and S
    • Keyboard T: t and T
    • Keyboard U: u and U
    • Keyboard V: v and V
    • Keyboard W: w and W
    • Keyboard X: x and X
    • Keyboard Y: y and Y
    • Keyboard Z: z and Z
  2. Numbers (Top Row Above QWERTY)
    • Keyboard 1 and Bang: 1 and ! (Exclamation)
    • Keyboard 2 and At: 2 and @ (At Sign)
    • Keyboard 3 and Hash: 3 and # (Hash/Pound)
    • Keyboard 4 and Dollar: 4 and $ (Dollar)
    • Keyboard 5 and Percent: 5 and % (Percent)
    • Keyboard 6 and Caret: 6 and ^ (Caret)
    • Keyboard 7 and Ampersand: 7 and & (Ampersand)
    • Keyboard 8 and Star: 8 and * (Asterisk/Star)
    • Keyboard 9 and Left Bracket: 9 and ( (Left Parenthesis)
    • Keyboard 0 and Right Bracket: 0 and ) (Right Parenthesis)
  3. Symbols / Punctuation
    • Keyboard Equals and Plus: = (Equal) and + (Plus)
    • Keyboard Dash and Underscore: - (Minus) and _ (Underscore)
    • Keyboard Forward Slash and Question Mark: / (Forward Slash) and ? (Question Mark)
    • Keyboard Backslash and Pipe: \ (Backslash) and | (Pipe)
    • Keyboard Semicolon and Colon: ; (Semicolon) and : (Colon)
    • Keyboard Left Apos and Double: ' (Apostrophe) and " (Double Quote)
    • Keyboard Comma and Less Than: , (Comma) and < (Less Than)
    • Keyboard Period and Greater Than: . (Period) and > (Greater Than)
    • Keyboard Left Brace: [ (Left Bracket) and { (Left Brace)
    • Keyboard Right Brace: ] (Right Bracket) and } (Right Brace)
    • Keyboard Grave Accent and Tilde: ` (Grave Accent) and ~ (Tilde)
  4. Control & Whitespace
    • Keyboard Escape: Escape (ESC)
    • Keyboard Return Enter: Return (Enter)
    • Keyboard Spacebar: Space
    • Keyboard Tab: Tab
    • Keyboard Delete: Backspace
    • Keyboard Delete Forward: Delete
    • Keyboard Insert: Insert
  5. Navigation
    • Keyboard Home: Home
    • Keyboard End: End
    • Keyboard Page Up: Page Up
    • Keyboard Page Down: Page Down
    • Keyboard Up Arrow: ↑ (Up Arrow)
    • Keyboard Down Arrow: ↓ (Down Arrow)
    • Keyboard Left Arrow: ← (Left Arrow)
    • Keyboard Right Arrow: → (Right Arrow)
  6. Locks
    • Keyboard Caps Lock: Caps Lock
    • Keyboard Scroll Lock: Scroll Lock
  7. Function Keys (F Keys)
    • Keyboard F1: F1
    • Keyboard F2: F2
    • Keyboard F3: F3
    • Keyboard F4: F4
    • Keyboard F5: F5
    • Keyboard F6: F6
    • Keyboard F7: F7
    • Keyboard F8: F8
    • Keyboard F9: F9
    • Keyboard F10: F10
    • Keyboard F11: F11
    • Keyboard F12: F12
  8. Miscellaneous
    • Keyboard Print Screen: Print Screen
    • Keyboard Pause: Pause / Break
  9. Modifiers
    • Keyboard Left Shift: Left Shift (⇧)
    • Keyboard Right Shift: Right Shift (⇧)
    • Keyboard Left Control: Left Control
    • Keyboard Right Control: Right Control
    • Keyboard Left Alt: Left Alt
    • Keyboard Right Alt: Right Alt
    • Keyboard Left GUI: Left GUI (Windows/Command/Meta)
    • Keyboard Right GUI: Right GUI (Windows/Command/Meta)
  10. Keypad (Numeric Keypad)
    • Keypad Num Lock and Clear: Num Lock and Clear
    • Keypad Enter: Enter
    • Keypad 1 and End: 1
    • Keypad 2 and Down Arrow: 2
    • Keypad 3 and Page Down: 3
    • Keypad 4 and Left Arrow: 4
    • Keypad 5: 5
    • Keypad 6 and Right Arrow: 6
    • Keypad 7 and Home: 7
    • Keypad 8 and Up Arrow: 8
    • Keypad 9 and Page Up: 9
    • Keypad 0 and Insert: 0
    • Keypad Plus: + (Plus)
    • Keypad Dash: - (Minus)
    • Keypad Star: * (Multiply)
    • Keypad Forward Slash: / (Divide)
    • Keypad Period and Delete: . (Dot)

Note: When setting a Key Press value, you can also select modifier keys (e.g., Left Ctrl, Left Alt) on the right side. This outputs the set key value along with the selected modifiers when pressed. Multiple modifiers can be combined.
Examples: Left Ctrl + A, Left Ctrl + Left Alt + Delete

Layer Types

  1. Momentary Layer
    • Description: Enables a layer while a key is pressed. The layer activates immediately when the key is pressed and deactivates when released, returning to the default layer.
  2. To Layer
    • Description: Switches to a specified layer and disables all other layers except the default layer. The switch persists after the key is released.
  3. Toggle Layer
    • Description: Toggles a layer on or off. If the layer is disabled, pressing the key enables it; if enabled, pressing the key disables it and returns to the default layer.
  4. Layer-Tap
    • Description: Enables a layer when the key is held; outputs a predefined Key Press value when tapped briefly. Reverts to the default layer when released after holding.

Bluetooth Controls

  • Next Profile: Switches to the next Bluetooth channel.
  • Previous Profile: Switches to the previous Bluetooth channel.
  • Clear All Profiles: Clears pairing data for all Bluetooth channels.
  • Clear Selected Profile: Clears pairing data for the current Bluetooth channel.
  • Select Profile (Profile 0–5): Selects a Bluetooth channel (0 is the first channel).
  • Disconnect Profile (Profile 0–5): Disconnects the specified Bluetooth channel (0 is the first channel).

Underglow (RGB Lighting)

  • Toggle On/Off: Turns the RGB lighting on or off.
  • Turn On: Activates the RGB lighting.
  • Turn Off: Deactivates the RGB lighting.
  • Hue Up: Increases the hue of the RGB lighting.
  • Hue Down: Decreases the hue of the RGB lighting.
  • Saturation Up: Increases the saturation of the RGB lighting.
  • Saturation Down: Decreases the saturation of the RGB lighting.
  • Brightness Up: Increases the brightness of the RGB lighting.
  • Brightness Down: Decreases the brightness of the RGB lighting.
  • Speed Up: Increases the animation speed of the RGB lighting effect.
  • Speed Down: Decreases the animation speed of the RGB lighting effect.
  • Next Effect: Cycles forward to the next RGB lighting effect.
  • Previous Effect: Cycles backward to the previous RGB lighting effect.

 

Additional Notes

  • Left-Only Connection: Keymap changes only require the left half to be connected, as it communicates changes to the right half wirelessly.
  • Custom Behaviors: Pre-existing firmware settings (e.g., encoder actions) remain intact after keymap changes via ZMK Studio.
  • Port Conflicts: Always close and reopen the software if you select the wrong port to free up the connection.
Back to blog