Issues with Keychron Keyboards in VIA

[wilba]

The usual way VIA works is for keyboard definitions to be added to the Github repository the-via/keyboards allowing the VIA client to automatically download and use a definition when matching firmware is detected.

For whatever reason, Keychron has not added definition for some of their keyboards to the Github repository, and is instructing users to a) enable the "Design" tab in Settings, b) use the "Load Draft Definition" to load a definition. This is essentially instructing users to use a "developer's back-end" every time they want to use VIA, which is not what the VIA developers intended.

Maybe the recent change from V2 to V3 definitions is related to people's issues. The toggle button that was previously "Use V3 Definitions" has now changed to "Use V2 Definitions", since V3 is now the latest and current, and V2 is the previous. Maybe people should try using that toggle button and loading the definition and see if that fixes things.

As far as I know, Keychron firmware was built and installed before the change from V2 to V3 (because their "VIA Guide" refers to an old version of VIA), so most likely VIA needs a V2 definition loaded in order to recognize a device with that V2-compatible firmware.

Technical details: If VIA detects QMK firmware built with VIA_PROTOCOL_VERSION of 11+ it will require a V3 definition, otherwise it requires a V2 definition. All keyboards in QMK master branch should have both V2 and V3 definitions in the Github repository, thus VIA will work with old firmware and newly built firmware.

[nicos68]

Q1 v2 & Linux (Fedora 37) user here. I did use the "Use V2 definition" toggle, and it did make things better as I was able to load the definition and have the "configure" tab show the keyboard layout. However, whatever change I made in the app had no impact on the keyboard itself. I have made tests on window, which did not bring any improvement.

So I decided to go through the QMK path. I followed the tutorial and compiled the firmware myself, but couldn't use the flash utility, because it's not available on Linux. The firmware of the v2 version of the Q1 is not available yet, because the v2 is based on a new chip. It can be found on this pull request by Keychron's staff though. So if you checkout the branch, you can fully use QMK to configure the Q1 v2. It is a bit of a hassle and involves many manual tasks, but it is fully functional, and with some luck it will soon be mainlined so things will be 100% functional with QMK and VIA.

[davidhaley]

I shared this link with Keychron support.

[adophoxia]

For whatever reason, Keychron has not added definition for some of their keyboards to the Github repository, and is instructing users to a) enable the "Design" tab in Settings, b) use the "Load Draft Definition" to load a definition. This is essentially instructing users to use a "developer's back-end" every time they want to use VIA, which is not what the VIA developers intended.

This is mostly because of both, how it came as a surprise out of nowhere for manufacturers like KC and how people either don't know that there's a new version of VIA that they have to use instead of 1.3.1 that they might be on, or they don't know or don't care about updating the firmware on their boards to be able to take advantage to that, both sides that I've seen more and more of. In which case, they'd have to do one or both of these 2 options regardless.

For the "developer's back-end" method, in the case of the K Pro, which was spawned from the-via/releases#221, this series will still need this (albeit, with the V3 definition. That bit's true) since it'll be a long time until the K Pro series is in mainline QMK due to how KC did BT support for these boards compared to how the QMK team wants it done, so until a compromise is reached, it'll be like this for now.

Maybe the recent change from V2 to V3 definitions is related to people's issues. The toggle button that was previously "Use V3 Definitions" has now changed to "Use V2 Definitions", since V3 is now the latest and current, and V2 is the previous. Maybe people should try using that toggle button and loading the definition and see if that fixes things.

This. Even with the "developer's back-end" method since people didn't understand that this toggle was needed for loading the JSONs that KC currently has. (V2 Definitions)

As far as I know, Keychron firmware was built and installed before the change from V2 to V3 (because their "VIA Guide" refers to an old version of VIA), so most likely VIA needs a V2 definition loaded in order to recognize a device with that V2-compatible firmware.

For other KC boards that weren't in mainline QMK and any boards people got before Nov 26, that used to be the case, but now the bluetooth_playground has the VIA V3 changes and even now, qmk:master has all of the Q/V boards (except Q1v2), so it's just a matter of flashing the firmware from either these two branches.

[jrgiacone]

It doesn't look like the q1v2 has been pushed to master yet correct, been trying to find a way to use the new VIA version 3, but I have not found any documentation on how to do it

[calebmeyer]

It did take a lot of tinkering and a support page from keychron to get VIA able to do anything with my k8 pro. It does work once I enable the v2 toggle, import the json, and switch to the configure tab.

[rigtorp]

I've follow the instructions here of toggle v2, import json and then switch to configure tab. But I only get this error instead:

21:45:23.511
Received invalid protocol version from device
Device: Keychron Keychron K7 Pro
Vid: 0x3434
Pid: 0x0273

This is on Fedora.

[michaelyfan]

Does there exist a current working solution for Keychron keyboards? Looks like V3 auto-detection doesn't work for the reasons OP mentioned, and "Use V2 Definitions" doesn't fix the issue (in my case, getting "Object: should NOT have additional properties" error message when using V2).

Windows 10, VIA v3 desktop app, Keychron Q1 v2 w/ knob ANSI

[Syphdias]

I just received the Keychron Q1 Pro ISO and have the exact same issue @rigtorp described.

Device: Keychron Keychron Q1 Pro
Vid: 0x3434
Pid: 0x0611

This is only under Linux (ArchLinux + Google Chrome). I get the error when not providing a JSON as well as when providing the JSON with forcing the version to v2. It works perfectly fine under Windows 10 (also Google Chrome).
This might be a separate issue, but I cannot be sure. Is know to be related or should I open another issue?

[hofheinz]

@Syphdias This might be an access rights issue (it was in my case). Chrome is trying to access /dev/hidraw*, which may be restricted to root. You could try running as root, or adjusting the access rights of those files (although this doesn't seem optimal).

[Syphdias]

@hofheinz I am not convinced that this the case. I tried to chown all Keychron /dev/event/input* files which didn't change anything. Also the authorization pop-up does work. I also tried a Ubuntu live boot to verify that it did not work there either.

[rigtorp]

@Syphdias It worked when I used the electron release here from GitHub. So I'm pretty sure that @hofheinz is on the right track. Maybe because of flatpak?

[hofheinz]

Hmm, sorry it didn't work for you, @Syphdias . For the record, in my case (Alpine Linux, Chromium installed from package, i.e., non-flatpak), I got these messages:

Failed to open the device. Device: Keychron Keychron K8 Pro Vid: 0x3434 Pid: 0x0281

and then

Received invalid protocol version from device Device: Keychron Keychron K8 Pro Vid: 0x3434 Pid: 0x0281

Looking at chrome://device-log in Chromium showed an HID "failed to open /dev/hidraw*" error message, so I thought that this may have been an access rights issue. In my case, running Chromium (non-flatpak) as root resolved the issue.

[Syphdias]

Thank you for the hint. It was indeed the hidraw device missing the permissions. Looking at chrome://device-log showed which one it was.
I might fix this with a udev rule adding the proper mode and group (uaccess tag did not work for me), but I had trouble filtering by ID_VENDOR_ID and ID_MODEL_ID. Alternatively, I might do it manually, for the time I need to make changes to my config. This is not an issue of VIA, obviously.

[wlarch]

Received invalid protocol version from device Device

The logs shown in chrome://device-log explained the errror : HID "failed to open /dev/hidraw2".
I temporarily changed the permissions sudo chown $USER:$USER /dev/hidraw2 and changed my keyboard layout using the VIA app. You can then change the permissions back to root : sudo chown root:root /dev/hidraw2.

[Syphdias]

I temporarily changed the permissions sudo chown $USER:$USER /dev/hidraw2 and changed my keyboard layout using the VIA app.

Same. Remember that a reboot will also reset the permissions.

[liquiddandruff]

So I just visited https://usevia.app/ and noticed the UI changed.

The interface still recognizes my keyboard, Keychron Q5 ANSI KNOB, and I can set keymaps fine.

Apparently from https://www.keychron.com/pages/how-to-use-via-to-pair-with-keychron-q-series-keyboard the right keymaps should be used, so are things resolved now?

I only found this ticket because when I tried to export my configuration, the file generated is empty and via reports 16 errors:

timestamp, productName, vendorId, productId, message
13:12:20.493, Keychron Q5, 0x3434, 0x0151, "Command Name: DYNAMIC_KEYMAP_GET_ENCODER
Command: 20 0 0 0
Response: 255 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0"
13:12:20.500, Keychron Q5, 0x3434, 0x0151, "Error: Receiving incorrect response for command
    at KeyboardAPI._hidCommand (https://usevia.app/assets/index-57542d2d.js:3:9407)
    at async KeyboardAPI.flushQueue (https://usevia.app/assets/index-57542d2d.js:3:8661)"
13:12:20.521, Keychron Q5, 0x3434, 0x0151, "Command Name: DYNAMIC_KEYMAP_GET_ENCODER
Command: 20 0 0 1
Response: 255 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0"
13:12:20.532, Keychron Q5, 0x3434, 0x0151, "Error: Receiving incorrect response for command
    at KeyboardAPI._hidCommand (https://usevia.app/assets/index-57542d2d.js:3:9407)
    at async KeyboardAPI.flushQueue (https://usevia.app/assets/index-57542d2d.js:3:8661)"
13:12:20.556, Keychron Q5, 0x3434, 0x0151, "Command Name: DYNAMIC_KEYMAP_GET_ENCODER
Command: 20 1 0 0
Response: 255 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0"
13:12:20.563, Keychron Q5, 0x3434, 0x0151, "Error: Receiving incorrect response for command
    at KeyboardAPI._hidCommand (https://usevia.app/assets/index-57542d2d.js:3:9407)
    at async KeyboardAPI.flushQueue (https://usevia.app/assets/index-57542d2d.js:3:8661)"
13:12:20.588, Keychron Q5, 0x3434, 0x0151, "Command Name: DYNAMIC_KEYMAP_GET_ENCODER
Command: 20 1 0 1
Response: 255 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0"
13:12:20.594, Keychron Q5, 0x3434, 0x0151, "Error: Receiving incorrect response for command
    at KeyboardAPI._hidCommand (https://usevia.app/assets/index-57542d2d.js:3:9407)
    at async KeyboardAPI.flushQueue (https://usevia.app/assets/index-57542d2d.js:3:8661)"
13:12:20.615, Keychron Q5, 0x3434, 0x0151, "Command Name: DYNAMIC_KEYMAP_GET_ENCODER
Command: 20 2 0 0
Response: 255 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0"
13:12:20.621, Keychron Q5, 0x3434, 0x0151, "Error: Receiving incorrect response for command
    at KeyboardAPI._hidCommand (https://usevia.app/assets/index-57542d2d.js:3:9407)
    at async KeyboardAPI.flushQueue (https://usevia.app/assets/index-57542d2d.js:3:8661)"
13:12:20.638, Keychron Q5, 0x3434, 0x0151, "Command Name: DYNAMIC_KEYMAP_GET_ENCODER
Command: 20 2 0 1
Response: 255 2 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0"
13:12:20.643, Keychron Q5, 0x3434, 0x0151, "Error: Receiving incorrect response for command
    at KeyboardAPI._hidCommand (https://usevia.app/assets/index-57542d2d.js:3:9407)
    at async KeyboardAPI.flushQueue (https://usevia.app/assets/index-57542d2d.js:3:8661)"
13:12:20.660, Keychron Q5, 0x3434, 0x0151, "Command Name: DYNAMIC_KEYMAP_GET_ENCODER
Command: 20 3 0 0
Response: 255 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0"
13:12:20.665, Keychron Q5, 0x3434, 0x0151, "Error: Receiving incorrect response for command
    at KeyboardAPI._hidCommand (https://usevia.app/assets/index-57542d2d.js:3:9407)
    at async KeyboardAPI.flushQueue (https://usevia.app/assets/index-57542d2d.js:3:8661)"
13:12:20.681, Keychron Q5, 0x3434, 0x0151, "Command Name: DYNAMIC_KEYMAP_GET_ENCODER
Command: 20 3 0 1
Response: 255 3 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0"
13:12:20.686, Keychron Q5, 0x3434, 0x0151, "Error: Receiving incorrect response for command
    at KeyboardAPI._hidCommand (https://usevia.app/assets/index-57542d2d.js:3:9407)
    at async KeyboardAPI.flushQueue (https://usevia.app/assets/index-57542d2d.js:3:8661)"

[emsi]

For other KC boards that weren't in mainline QMK and any boards people got before Nov 26, that used to be the case, but now the bluetooth_playground has the VIA V3 changes and even now, qmk:master has all of the Q/V boards (except Q1v2), so it's just a matter of flashing the firmware from either these two branches.

The qmk:master lacks K5 Pro, which is here: https://github.com/Keychron/qmk_firmware/tree/bluetooth_playground/keyboards/keychron/k5_pro

[h3krn]

@Syphdias This might be an access rights issue (it was in my case). Chrome is trying to access /dev/hidraw*, which may be restricted to root. You could try running as root, or adjusting the access rights of those files (although this doesn't seem optimal).

Thnx. This solved it for me! I have a Keychron K7 Pro on Linux Mint 21.2 (Ubuntu 22.04 LTS). and was getting the same error.

Failed to open the device.
Device: Keychron Keychron K7 Pro
Vid: 0x3434
Pid: 0x0270

Received invalid protocol version from device
Device: Keychron Keychron K7 Pro
Vid: 0x3434
Pid: 0x0270

To make the solution permanent, I've created a new system group, added my user to it and created a udev rule allowing the group access to /dev/hidraw*.

$ sudo groupadd -r qmkvia
$ sudo usermod -aG qmkvia <username>
$ echo 'KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0660", GROUP="qmkvia"' | sudo tee /etc/udev/rules.d/99-hidraw-qmkvia.rules
$ sudo udevadm control --reload-rules
$ sudo udevadm trigger

Logout and back in to make your users qmkvia group membership effective.

[martin-braun]

Just tried to pair the K7 Pro on MacOS (clean Google Chrome). It says "Paired", but I cannot proceed:

But device log says: USB device added: vendor=13364 "Keychron", product=625 "Keychron K7 Pro", serial="", guid=666a56e7-c9ef-471e-ba93-8b64eac098c5

What am I doing wrong here?

EDIT: Sorry, should've read their help closely:

Please download the keymap JSON file below. Connect your keyboard and device with the provided cable, and toggle the switch to cable mode. Open VIA, click on the "Show Design tab" on the "Settings" tab, and drag the JSON file into the “Design” tab on VIA to get the K7 Pro keymap working on VIA.

[seanwessmith]

Just tried to pair the K7 Pro on MacOS (clean Google Chrome). It says "Paired", but I cannot proceed:

But device log says: USB device added: vendor=13364 "Keychron", product=625 "Keychron K7 Pro", serial="", guid=666a56e7-c9ef-471e-ba93-8b64eac098c5

What am I doing wrong here?

EDIT: Sorry, should've read their help closely:

Please download the keymap JSON file below. Connect your keyboard and device with the provided cable, and toggle the switch to cable mode. Open VIA, click on the "Show Design tab" on the "Settings" tab, and drag the JSON file into the “Design” tab on VIA to get the K7 Pro keymap working on VIA.

@martin-braun mind providing a link to this page? I'm not sure what to download for keychron q3 pro

[martin-braun]

@seanwessmith Text-search for "please" on their product page, which is https://www.keychron.com/products/keychron-q3-pro-qmk-via-wireless-custom-mechanical-keyboard for the q3 pro.

[lindhe]

I've noticed that the text is all wonky and hard to read:

Does that belong here or in a separate issue?

[AlexanderProd]

Maybe the recent change from V2 to V3 definitions is related to people's issues. The toggle button that was previously "Use V3 Definitions" has now changed to "Use V2 Definitions", since V3 is now the latest and current, and V2 is the previous. Maybe people should try using that toggle button and loading the definition and see if that fixes things.

@martin-braun Same for me with macOS and K7 Pro, have you figured it out?

Edit: Got it working by downloading this json file and loading it as draft in the via design tab.

[conorf50]

Is it possible to add the json files from Keychron's bluetooth-playground branch without having support for this board merged to QMK master? I can see that having the keyboard in the master branch of QMK is a listed as a requirement for the files to be added to VIA. How much will things break if the files are added here before the board is added to mainline QMK? I don't know if the firmware for the K Pro series is gonna get mainlined as Keychron maintain their own fork of QMK for these boards.

Here are the JSON files: https://github.com/Keychron/qmk_firmware/tree/bluetooth_playground/keyboards/keychron/k3_pro/via_json

[IO42630]

I just received the Keychron Q1 Pro ISO and have the exact same issue @rigtorp described.

Device: Keychron Keychron Q1 Pro
Vid: 0x3434
Pid: 0x0611

This is only under Linux (ArchLinux + Google Chrome). I get the error when not providing a JSON as well as when providing the JSON with forcing the version to v2. It works perfectly fine under Windows 10 (also Google Chrome). This might be a separate issue, but I cannot be sure. Is know to be related or should I open another issue?

Tested with Keychron K6 Pro -> usevia.app works on Windows (not on Linux).

[igorsantos07]

Since this issue got quite long with the discussion and side-tracked with unrelated problems (Linux permissions, wonky 2D letters, etc), I opened a specific issue explaining the perms problem and possible workarounds, in case it helps the devs to look into it 🙏

[PeterMortensen]

@seanwessmith Text-search for "please" on their product page, which is https://www.keychron.com/products/keychron-q3-pro-qmk-via-wireless-custom-mechanical-keyboard for the q3 pro.

Case insensitive. Or "Please".

[SunRed]

$ sudo groupadd -r qmkvia
$ sudo usermod -aG qmkvia <username>
$ echo '"KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0660", GROUP="qmkvia"' | sudo tee /etc/udev/rules.d/99-hidraw-qmkvia.rules
$ sudo udevadm control --reload-rules
$ sudo udevadm trigger

I added such a udev rule for an ansi Q10 (Max) I received today but after authorising the device it still doesn't load the app with no error displayed on chrome://device-log/. Obviously this is on Linux, haven't tried in on Windows yet.
But fixing this permission problem via the udev rule made the site at https://launcher.keychron.com/ work (that you use for firmware updates e.g.) so I figured it's some issue with via.

[SunRed]

I now solved this issue by downloading the definition json file from https://www.keychron.com/pages/firmware-and-json-files-of-the-keychron-qmk-keyboards for my keyboard and loading it via the Design tab.

[illnesse]

$ sudo groupadd -r qmkvia
$ sudo usermod -aG qmkvia
$ echo '"KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0660", GROUP="qmkvia"' | sudo tee /etc/udev/rules.d/99-hidraw-qmkvia.rules
$ sudo udevadm control --reload-rules
$ sudo udevadm trigger

there is a typo in here so it won't work (first double quote in the rules file), please use this:

sudo groupadd -r qmkvia
sudo usermod -aG qmkvia <username>
echo 'KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0660", GROUP="qmkvia"' | sudo tee /etc/udev/rules.d/99-hidraw-qmkvia.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

[fulldecent]

Are the JSON files on the Keychron website licensed in a permissible way that I can copy them into this project?

If not, can I do a black box implementation of the same files and would that be accepted as a PR here to solve the problem for millions of people ?