Repository navigation
Why Keyboards May Have Multiple Device Names
One physical keyboard usually appears in Linux as several input devices, each with a slightly different name. Toshy decides the keyboard type (Apple, Windows, IBM or Chromebook) from the name of the device your keypresses are actually coming from. If the keyboard starts sending its keypresses through a different one of its devices, the name Toshy sees changes too.
This matters if you have added your keyboard to keyboards_UserCustom_dct in the config file. An entry there has to be the whole device name, so an entry that worked for months can suddenly stop matching, and the modifier keys end up in the "wrong" place again.
The fix is to add every keyboard-like name your keyboard has to the dictionary. See Fixing the Keyboard Type Override below.
- Why One Keyboard Has Several Names
- Why the Active Name Can Change
- Finding All of the Names
- Fixing the Keyboard Type Override
- Notes
This has nothing to do with a keyboard being a "split" model, or with anything being wrong. It is how USB input devices describe themselves.
A USB keyboard presents one or more interfaces to the computer. Each interface describes the controls it carries: an ordinary keyboard, media keys, power and sleep keys, sometimes a mouse (for firmware "mouse keys"). The Linux kernel creates a separate input device for each kind of control it finds.
The kernel builds the base name from what the device reports about itself: the manufacturer name, a space, then the product name. That is why some names look doubled. A manufacturer of "Keychron" with a product of "Keychron Q11" becomes "Keychron Keychron Q11".
When an interface carries only one kind of control, the input device gets just that base name. When an interface carries several kinds, the kernel adds a suffix to each device's name to tell them apart. The common ones are:
- "Keyboard"
- "Keypad"
- "Mouse"
- "System Control" (power, sleep and wake keys)
- "Consumer Control" (media and volume keys)
So a keyboard can easily produce a list like this, all from one USB cable:
Keychron Keychron Q11
Keychron Keychron Q11 Mouse
Keychron Keychron Q11 System Control
Keychron Keychron Q11 Consumer Control
Keychron Keychron Q11 Keyboard
Two of those are keyboards as far as the kernel is concerned: the one with no suffix, and the one that ends in "Keyboard".
The same thing happens with other devices. A gaming mouse with programmable buttons will often have a "Keyboard" device of its own, so that its buttons can send key presses.
All of the devices are normally present all the time. What changes is which one the keyboard uses to send ordinary keypresses.
Keyboards running QMK firmware (many enthusiast and Keychron models, among others) are a good example. By default QMK sets up two keyboard-capable interfaces:
- A basic keyboard that reports up to six keys at once. This is the "boot" keyboard that works in a BIOS or UEFI setup screen. It is the only thing on its interface, so its name has no suffix.
- A "shared" interface that combines the N-key rollover (NKRO) keyboard with the media keys, system keys and mouse keys. Because it carries several kinds of controls, each one gets a suffix, and the keyboard part is the device ending in "Keyboard".
QMK sends keypresses through the NKRO keyboard when NKRO is switched on and the computer allows it, and through the basic keyboard otherwise. So the name Toshy sees depends on the state of the keyboard:
- NKRO can be toggled from the keyboard itself, and the setting is saved in the keyboard. Many boards have a key combination for it.
- If the computer has put the keyboard into the simpler "boot" mode, QMK falls back to the basic keyboard even when NKRO is switched on.
- A firmware update on the keyboard can change the default.
It is not always clear what triggered the switch. One user saw it happen after a round of system and firmware updates followed by a reboot. The important part is that it can happen, and that the override should be written so it doesn't matter.
Keyboards with other firmware can behave in a similar way, for example when switching between wired, Bluetooth and wireless dongle connections, each of which usually has its own device name.
Run this command in a terminal:
toshy-devices
It lists every input device the keymapper can see. Devices that belong to the same physical keyboard share the first part of their "Bus Path", up to the final /input and number. In this example both devices are on usb-0000:80:14.0-2, so both are the same keyboard:
Device Path: /dev/input/event3
Bus Path: usb-0000:80:14.0-2/input0
Device Name: Keychron Keychron Q11
Device Path: /dev/input/event7
Bus Path: usb-0000:80:14.0-2/input2
Device Name: Keychron Keychron Q11 Keyboard
To see which name is in use right now, run the command below, press a few keys, and look for lines with KBTYPE:. They show the device name and the keyboard type Toshy chose for it.
toshy-debug
When you are done, restart the Toshy services from the tray icon menu, or with this command:
toshy-services-restart
Open the config file (~/.config/toshy/toshy_config.py) and find keyboards_UserCustom_dct. It sits between a pair of "slice" markers, so your changes there are kept when Toshy is upgraded or reinstalled.
Add each keyboard-like name, with the same type for all of them:
keyboards_UserCustom_dct = {
'Keychron Keychron Q11': 'Apple',
'Keychron Keychron Q11 Keyboard': 'Apple',
}Save the file and restart the Toshy services. The override now keeps working no matter which of the two devices the keyboard decides to use.
You only need the names that send ordinary keypresses, which usually means the one with no suffix and the one ending in "Keyboard".
- An entry in
keyboards_UserCustom_dctmust be the whole device name. Upper and lower case don't matter, but a partial name will not match. - The valid types are
Apple,Windows,IBMandChromebook, and those are case sensitive. - For the general procedure when a keyboard is identified as the wrong type, see the FAQ entry My keyboard is not recognized as the correct type.