Kassadin.moe
中文 ZH English EN 日本語 JA

Note: Setting Up a Keychron Keyboard

Published on

Original language: Chinese . AI translations: English , Japanese .

A quick record of how I set up a Keychron keyboard.

Suddenly Getting Influenced

I saw a Keychron keyboard at a friend’s place. Fully remappable keys, and it can even emulate mouse operations: left click, right click, moving the cursor, all of it.
I previously wrote Note: Configure Magic Trackpad 2 on Linux. Even though the gestures were configured, I still had to move my hand off the keyboard when using them, which is a bit inconvenient.
With a Keychron keyboard, you can do cursor operations directly from the keyboard. Wouldn’t that be convenient?

Instantly got influenced.

Configuring The Keyboard

The keyboard arrived soon. But thinking about having to read docs and learn how to configure it triggered procrastination, and I didn’t even unbox it for a while (
My friend couldn’t stand it anymore and said the setup is very simple, then came over to help configure it.

After finishing: yeah, it’s not complicated. I overthought it.

First: Read The Official Docs

Just search the keyboard model online. Mine is K1 Pro, and the official docs are on Keychron K1 Pro User Guide.
For configuration, you only need the first item under Software Guide: Learn More How to Use VIA.
It links to an official step-by-step tutorial: How To Use VIA To Program Your Keyboard, with detailed steps and GIF demos.
Seems like I don’t need to add anything. End of post

Prerequisites

From the official tutorial, there are a few things to note:

  • Configuration only works via wired connection. You can’t change settings over Bluetooth.
  • use VIA only supports browsers based on Chromium.

So in most cases, you just connect the keyboard via cable, open Chrome/Edge, go to use VIA, and configure it there.

If use VIA recognizes the keyboard, the page will show the current key mapping.
If VIA can’t recognize it, there’s one extra step.

Download The Keymap JSON For Your Keyboard

The official guide says you can download the corresponding keymap JSON from Keychron - Firmware.

For my K1 Pro, the download link is Keychron K1 Pro Firmware.
Scroll down to the bottom of that page, and there’s a section: 2. Download the Keychron K1 Pro keymap JSON file if you haven't. with 4 download options:

  • Download K1 Pro ANSI White Backlight Keymap JSON File
  • Download K1 Pro ANSI RGB Keymap JSON File
  • Download K1 Pro ISO White Backlight Keymap JSON File
  • Download K1 Pro ISO RGB Keymap JSON File

White backlight vs RGB backlight is obvious, but what’s ANSI vs ISO?

From what I looked up: ANSI refers to the American National Standards Institute layout, which is the common US layout (also commonly used in China).
ISO refers to the International Organisation for Standardisation layout, commonly used in Europe.

To tell them apart, look at the Enter key: a regular rectangle is ANSI; the one with a protruding “step” is ISO.

My keyboard is the common ANSI layout, so I just downloaded the corresponding keymap JSON.

Don’t download the Firmware file near the top of Keychron K1 Pro Firmware. That’s not what you want.
The keymap JSON file further down is the one you need.

After downloading the keymap JSON file, open use VIA again.
On the Settings page, enable the first option Show Design tab, and you’ll see an extra Design tab.
Go to Design and drag the keymap JSON file in. Then VIA should recognize the keyboard correctly.

“Full Remap” And “Layers”

Before configuring, a quick intro to full remap and layer on Keychron keyboards.

  • Full remap
    Straightforward: every single key on the keyboard can be reassigned.

  • Layer
    If it were just “full remap”, many other keyboard brands can do it too.
    Keychron’s killer feature is that it comes with 4 layers. So what’s a layer?
    For example, the number row 1234567890 doesn’t only type numbers; combined with shift, it types ！@#¥%……&*（） and other symbols.
    In other words, one physical key can represent 2 characters.
    Keychron goes further: it has 4 layers, and each key can have different functions on each layer. It’s basically multiplying the available key slots by 4.

Full remap + 4 layers can cover pretty much any customization need. No more worrying about not enough keys
Realistically I won’t use that many mappings anyway. Too many shortcuts are impossible to remember. What I actually need is mouse emulation.

Start Configuring

Now we can finally start.

In VIA’s Configure view, you’ll see Layer 0 1 2 3 buttons on the top left. That indicates which layer you’re editing.

In the default factory layout:

  • Layer 0 is the Mac/IOS layout, usable directly on Macs.
  • Layer 1 is the function layer for Mac/IOS. It has some default keys for lighting control.
  • Layer 2 is the Windows/Android layout, usable directly on Windows.
  • Layer 3 is the function layer for Windows/Android. It has some default keys for lighting control.

There’s a physical switch on the keyboard: Windows/Android Mac/IOS.
Switching to Windows/Android uses Layer 2, and switching to Mac/IOS uses Layer 0.
I basically never use Apple devices, so I just stick to Layer 2 under Windows/Android.

Set A Key To Toggle Layer 2 / Layer 3

The mouse emulation I want is basically: put all mouse operations on Layer 3, and type normally on Layer 2. When I need mouse, I switch to Layer 3.

For convenient switching, you need to map a key on Layer 2 to Layer - TG(3).
TG(3) means toggle to layer 3.

To change a key mapping, click the key in the UI. The selected key will blink slowly.
Then choose a function from the panel below to assign (the hollow upside-down triangle means “same as the key on the previous layer”).
Changes apply immediately. After setting it, you can test right away.

I picked a rarely-used corner key and set it to TG(3).
Now when I’m on Layer 2, one press switches to Layer 3, and pressing it again switches back to Layer 2.

There are other ways to switch layers, e.g. Layer - MO(3). The Fn key on the bottom right is MO(3) by default, meaning “temporarily switch to Layer 3 while holding it”.
Controls like brightness/volume on F1-F12 work this way: you set functions for F1-F12 on Layer 3, and use them on Layer 2 together with Fn: MO(3).

Configure Layer 3

After setting the toggle key, move on to configuring Layer 3.

Click the last 3 on the top left. You’ll see the default mappings. On the left there are a bunch of RGB lighting controls.
It’s said RGB improves performance by 300%, but it’s flashy and drains battery, so I turned it all off.

After clearing RGB mappings, the next step is mouse emulation.
I mapped the arrow keys on Layer 3 to move the cursor up/down/left/right, and assigned left click/right click/scroll wheel to keys that felt comfortable.

After messing with it, I basically got what I wanted.

The only issue: the three mouse acceleration keys KC_MS_ACCEL0, KC_MS_ACCEL1, KC_MS_ACCEL2 don’t seem to work.
Cursor movement stays extremely fast, and it’s hard to control.

Advanced Setup

What I configured is just the basics. This keyboard can do a lot more, but… since it works, I’ll stop tinkering for now (
Will look into it later when I have time (miao miao miao

End

That’s it for now. I’ve been using it for a while and keep adjusting the mappings to fit my habits.

After using it, I realized the mouse emulation feature that originally influenced me is used way less than expected. Fell into consumerism again (

But overall the keyboard experience is nice: compact, low-key design, decent battery life, and the feel is obviously much better than a laptop keyboard. Recommended 👍