Difference between revisions of "Extra keyboard keys"

From ArchWiki
Jump to: navigation, search
m (Asus M series: rm link to unrelated article)
(Cooler Master CM Storm QuickFire TK)
 
(43 intermediate revisions by 15 users not shown)
Line 1: Line 1:
 
[[Category:Keyboards]]
 
[[Category:Keyboards]]
[[zh-CN:Extra Keyboard Keys]]
+
[[ja:特別なキーボードキー]]
{{Article summary start}}
+
[[ru:Extra keyboard keys]]
{{Article summary text|A general overview of how to assign actions to extra keyboard keys.}}
+
[[zh-cn:Extra keyboard keys]]
{{Article summary heading|Related}}
+
{{Related articles start}}
{{Article summary wiki|Xorg}}
+
{{Related|Extra keyboard keys in Xorg}}
{{Article summary wiki|Xmodmap}}
+
{{Related|Extra keyboard keys in console}}
{{Article summary wiki|Extra Keyboard Keys in Xorg}}
+
{{Related|Keyboard configuration in Xorg}}
{{Article summary wiki|Extra Keyboard Keys in Console}}
+
{{Related|Keyboard configuration in console}}
{{Article summary end}}
+
{{Related|Map scancodes to keycodes}}
Many keyboards include some "special keys" (also called hotkeys, such as HP Quickplay), which are supposed to execute an application or print special characters (not included in the standard national keymaps). The lack of specification for these extra keys makes it impossible for the kernel to know what to do with them and that is why we need to map the keys to actions. There are 3 ways of doing that:
+
{{Related|Xmodmap}}
* The most portable way using low level tools, such as [[acpid]]. Not all keys are supported, but configuration in uniform way is possible for keyboard keys, power adapter connection and even headphone jack (un)plugging events.
+
{{Related articles end}}
* The universal way using [[Xorg]] utilities (and eventually your desktop environment tools)
+
Many keyboards include some ''special keys'' (also called ''hotkeys'' or ''multimedia keys''), which are supposed to execute an application or print special characters (not included in the standard national keymaps). [[udev]] contains a large database of mappings specific to individual keyboards, so common keyboards usually work out of the box. If you have very recent or uncommon piece of hardware, you may need to adjust the mapping manually.
* The quicker way using a third-party program to do everything in GUI, such as the Gnome Control Center or [[Keytouch]]
+
  
Before starting you need to learn some vocabulary.
+
Prerequisite for modifying the key mapping is knowing how the keys are identified on the system. There are multiple levels:
  
A '''scancode''' is the lowest identification number for a key. If a key does not have a scancode then we cannot do anything because it means that the kernel does not see it.
+
* A [[Wikipedia:Scancode|scancode]] is the lowest identification number for a key, it is the value that a keyboard sends to a computer.
 +
* A '''keycode''' is the second level of identification for a key, a ''keycode'' corresponds to a function.
 +
* A '''keysym''' is the third level of identification for a key, it corresponds to a ''symbol''. It may depend on whether the Shift key or another [[Wikipedia:Modifier key|modifier key]] was also pressed.
  
A '''keycode''' is the second level of identification for a key, a keycode corresponds to a function.
+
''Scancodes'' are mapped to ''keycodes'', which are then mapped to ''keysyms'' depending on used keyboard layout. Most of your keys should already have a ''keycode'', or at least a ''scancode''. Keys without a ''scancode'' are not recognized by the kernel; these can include additional keys from 'gaming' keyboards, etc.
  
A '''symbol''' is the third level of identification for a key, it is the way Xorg refers to keys.
+
In Xorg, some ''keysyms'' (e.g. {{ic|XF86AudioPlay}}, {{ic|XF86AudioRaiseVolume}} etc.) can be mapped to actions (i.e. launching an external application). See [[Extra keyboard keys in Xorg#Mapping keysyms to actions]] for details.
  
== Step 1: Check for keycodes ==
+
In Linux console, some ''keysyms'' (e.g. {{ic|F1}} to {{ic|F246}}) can be mapped to certain actions (e.g. switch to other console or print some sequence of characters). See [[Extra keyboard keys in console]] for details.
  
Most of your keys should already have a keycode, or at least a scancode. Keys without a scancode are not recognized by the kernel.
+
== Identifying key codes ==
  
=== Using xev ===
+
=== Scancodes ===
  
Use the graphical X program "xev" (without having to switch to a console environment).
+
==== Using showkey ====
[[pacman|Install]] {{Pkg|xorg-xev}}.
+
  
With the following line you can start xev and directly grep the important parts:
+
The traditional way to get a ''scancode'' is to use the ''showkey'' utility. ''showkey'' waits for a key to be pressed, or exits if no keys are pressed within 10 seconds. For ''showkey'' to work you need to be in a [[Wikipedia:Virtual console|virtual console]], not in a graphical environment or logged in via a network connection. Run the following command:
  
  $ xev | grep -A2 --line-buffered '^KeyRelease' | sed -n '/keycode /s/^.*keycode \([0-9]*\).* (.*, \(.*\)).*$/\1 \2/p'
+
  # showkey --scancodes
  
In the example below I pressed the "a", "r", "c" and "h" keys and two of the media keys on my Dell keyboard. This gives me the following output:
+
and try to push keyboard keys; you should see ''scancodes'' being printed to the output.
38 a
+
27 r
+
54 c
+
43 h
+
153 NoSymbol
+
144 NoSymbol
+
This means that the "a", "r", "c" and "h" keys have the keycodes 38, 27, 54 and 43 and are properly bound while the media keys with the keycodes 153 and 144 have no function yet, which is indicated by "NoSymbol". If you press a key and nothing appears in the terminal, this means that the kernel does not see that key or that it is not mapped.
+
  
=== Using showkey ===
+
==== Using evtest ====
  
The universal way to know if a key has a keycode is to use the kernel {{ic|showkey}} program. showkey waits for a key to be pressed and if none is during 10 seconds it quits, note that this is the only way to exit the program. To execute showkey you need to be in a real console, it means not in a graphical environment so switch using {{ic|Ctrl+Alt+F2}} ({{ic|Ctrl+Alt+F1}} returns to the graphical environment).
+
For USB keyboards, it is apparently necessary to use ''evtest'' from the {{Pkg|evtest}} package instead of ''showkey'':[https://ask.fedoraproject.org/en/question/46201/how-to-map-scancodes-to-keycodes/]
# showkey
+
and try to push your hotkeys. If a keycode appears the key is mapped, if not it can mean either that the kernel does not see the key or that the key is not mapped.
+
  
=== 2.6 kernels ===
+
# evtest /dev/input/event12
 +
...
 +
Event: time 1434666536.001123, type 4 (EV_MSC), code 4 (MSC_SCAN), value 70053
 +
Event: time 1434666536.001123, type 1 (EV_KEY), code 69 (KEY_NUMLOCK), value 0
 +
Event: time 1434666536.001123, -------------- EV_SYN ------------
  
{{Out of date|Now we have 3.x kernel, is it still relevant?}}
+
Use the "value" field of {{ic|MSC_SCAN}}. This example shows that NumLock has scancode 70053 and keycode 69.
  
According to the keymap man page:
+
==== Using dmesg ====
  
{{Note|In  2.6  kernels  raw  mode, or scancode mode, is not very raw at all.  Scan codes are first translated to key codes, and when scancodes are desired the key codes are translated  back...there is no guarantee at all that the final result corresponds to what the keyboard hardware did send. To change behavior back to the old raw mode, add the parameter {{ic|1=atkbd.softraw=0}} to your kernel while booting. This can be removed for later boots when the old raw functionality is not required.}}
+
{{Note|This method does not provide ''scancodes'' for all keys, it only identifies the unknown keys.}}
  
This is relevant if the keymaps obtained from showkey and the ones set by [[setkeycodes]] differ from the ones obtained by xev in X. Keep this in mind when translating the keymaps into keysyms using xmodmap (See [[Extra Keyboard Keys in Xorg]]).
+
You can get the ''scancode'' of a key by pressing the desired key and looking the output of {{ic|dmesg}} command. For example, if you get:
  
If all your keys have a keycode you can go directly to the second step. If not keep reading below:
+
Unknown key pressed (translated set 2, code 0xa0 on isa0060/serio0
  
=== Check for scancodes ===
+
then the ''scancode'' you need is {{ic|0xa0}}.
  
If a key does not have a keycode you can know if it has a scancode by looking at the kernel log using the dmesg command:
+
=== Keycodes ===
$ dmesg|tail -5
+
If when you press the key something like that appears:
+
atkbd.c: Unknown key pressed (translated set 2, code 0xf1 on isa0060/serio0).
+
atkbd.c: Use 'setkeycodes e071 <keycode>' to make it known.
+
then your key has a scancode which can be mapped to a keycode. See [[Map scancodes to keycodes]].
+
  
If nothing new appears in dmesg then your key does not have a scancode, which means that it is not recognized by the kernel and cannot be used.
+
{{Warning|Note that the ''keycodes'' are different for Linux console and Xorg. Use the appropriate tool to determine the desired value.}}
  
== Step 2: map keycodes ==
+
==== In console ====
  
=== In console ===
+
The ''keycodes'' for [[Wikipedia:Virtual console|virtual console]] are reported by the ''showkey'' utility. ''showkey'' waits for a key to be pressed and if none is during 10 seconds it quits, which is the only way to exit the program. To execute ''showkey'' you need to be in a virtual console, not in a graphical environment. Run the following command
  
''See the dedicated article: [[Extra Keyboard Keys in Console]].''
+
# showkey --keycodes
  
When in console, hotkeys can be used to print sequences of characters, including escape sequences. Thus, printing the sequence of characters constituting a command followed by the escape sequence for a new will execute the command.
+
and try to push keyboard keys, you should see ''keycodes'' being printed to the output.
 +
 
 +
==== In Xorg ====
 +
 
 +
The ''keycodes'' used by [[Xorg]] are reported by a utility called ''xev'', which is provided by the {{Pkg|xorg-xev}} package. Of course to execute ''xev'', you need to be in a graphical environment, not in the console.
 +
 
 +
With the following command you can start ''xev'' and show only the relevant parts:
 +
 
 +
  $ xev | awk -F'[ )]+' '/^KeyPress/ { a[NR+2] } NR in a { printf "%-3s %s\n", $5, $8 }'
 +
 
 +
Here is an example output:
 +
 
 +
38  a
 +
55  v
 +
54  c
 +
50  Shift_L
 +
133 Super_L
 +
135 Menu
 +
 
 +
If you press a key and nothing appears in the terminal, it means that either the key does not have a ''scancode'', the ''scancode'' is not mapped to a ''keycode'', or some other process is capturing the keypress. If you suspect that a process listening to X server is capturing the keypress, you can try running xev from a clean X session:
 +
 
 +
$ xinit /usr/bin/xterm -- :1
 +
 
 +
== Mapping scancodes to keycodes ==
 +
 
 +
See the main article: [[Map scancodes to keycodes]].
 +
 
 +
== Mapping keycodes to keysyms ==
 +
 
 +
=== In console ===
 +
 
 +
See the main article: [[Extra keyboard keys in console]].
  
 
=== In Xorg ===
 
=== In Xorg ===
  
''See the dedicated article: [[Extra Keyboard Keys in Xorg]].''
+
See the main article: [[xmodmap]].
  
 
== Laptops ==
 
== Laptops ==
Line 91: Line 112:
 
In order to have control over the light sensor and the multimedia keys on your Asus machine, you should use the following command:
 
In order to have control over the light sensor and the multimedia keys on your Asus machine, you should use the following command:
  
  # echo 0 > /sys/devices/platform/asus-laptop
+
  # echo 1 > /sys/devices/platform/asus_laptop/ls_switch
  
 
To have it run on boot create a [[Systemd#Temporary_files|Systemd tmpfile]]:
 
To have it run on boot create a [[Systemd#Temporary_files|Systemd tmpfile]]:
 
{{hc|/etc/tmpfiles.d/local.conf|
 
{{hc|/etc/tmpfiles.d/local.conf|
w /sys/devices/platform/asus-laptop/ls_switch - - - - 0
+
w /sys/devices/platform/asus_laptop/ls_switch - - - - 1
 
}}
 
}}
  
Line 102: Line 123:
 
=== Asus N56VJ (or possibly others) ===
 
=== Asus N56VJ (or possibly others) ===
  
if most of your special keys don't work, try loading the asus-nb-wmi kernel module with
+
If most of your special keys do not work, try loading the asus-nb-wmi kernel module with
 
  # modprobe asus-nb-wmi
 
  # modprobe asus-nb-wmi
  
then check xev again. if you combine this with the acpi_osi="!Windows 2012" boot option, you may get weird results in xev, so try not using it. If this did fix things, make sure to make the module load at boot with methods described [[Kernel Modules|here]]
+
then check xev again. If you combine this with the acpi_osi="!Windows 2012" boot option, you may get weird results in xev, so try not using it. If this did fix things, make sure to make the module load at boot with methods described [[Kernel modules|here]].
 +
 
 +
== Gaming Keyboards ==
 +
 
 +
Gaming keyboards have some special features which may cause them to "misbehave" in Linux.
 +
 
 +
===Cooler Master CM Storm QuickFire TK===
 +
 
 +
This keyboard has two features that could cause confusion in Linux: N-Key Rollover and the Win-Lock Key.
 +
 
 +
N-Key Rollover can [https://bbs.archlinux.org/viewtopic.php?id=170877 cause problems with the Function keys]. To disable N-key rollover, hold down the FN lock key (next to right-ctrl) until it lights up, then hold Escape and press 6 to switch to 6-key rollover. Hold down the FN lock key to disable the Fn lock.
 +
 
 +
The Win-Lock Key completely disables the Super (Windows) keys. Simply press the FN lock key and F12 together to toggle Win-Lock on and off.
 +
 
 +
== See also ==
 +
 
 +
* [http://wiki.linuxquestions.org/wiki/Configuring_keyboards#Enabling_Keyboard_Multimedia_Keys Enabling Keyboard Multimedia Keys] - guide on LinuxQuestions wiki
 +
* [http://www.gentoo-wiki.info/HOWTO_Use_Multimedia_Keys Multimedia Keys] on [http://www.gentoo-wiki.info/ Gentoo Wiki Archives]

Latest revision as of 06:50, 23 October 2015

Many keyboards include some special keys (also called hotkeys or multimedia keys), which are supposed to execute an application or print special characters (not included in the standard national keymaps). udev contains a large database of mappings specific to individual keyboards, so common keyboards usually work out of the box. If you have very recent or uncommon piece of hardware, you may need to adjust the mapping manually.

Prerequisite for modifying the key mapping is knowing how the keys are identified on the system. There are multiple levels:

  • A scancode is the lowest identification number for a key, it is the value that a keyboard sends to a computer.
  • A keycode is the second level of identification for a key, a keycode corresponds to a function.
  • A keysym is the third level of identification for a key, it corresponds to a symbol. It may depend on whether the Shift key or another modifier key was also pressed.

Scancodes are mapped to keycodes, which are then mapped to keysyms depending on used keyboard layout. Most of your keys should already have a keycode, or at least a scancode. Keys without a scancode are not recognized by the kernel; these can include additional keys from 'gaming' keyboards, etc.

In Xorg, some keysyms (e.g. XF86AudioPlay, XF86AudioRaiseVolume etc.) can be mapped to actions (i.e. launching an external application). See Extra keyboard keys in Xorg#Mapping keysyms to actions for details.

In Linux console, some keysyms (e.g. F1 to F246) can be mapped to certain actions (e.g. switch to other console or print some sequence of characters). See Extra keyboard keys in console for details.

Identifying key codes

Scancodes

Using showkey

The traditional way to get a scancode is to use the showkey utility. showkey waits for a key to be pressed, or exits if no keys are pressed within 10 seconds. For showkey to work you need to be in a virtual console, not in a graphical environment or logged in via a network connection. Run the following command:

# showkey --scancodes

and try to push keyboard keys; you should see scancodes being printed to the output.

Using evtest

For USB keyboards, it is apparently necessary to use evtest from the evtest package instead of showkey:[1]

# evtest /dev/input/event12
...
Event: time 1434666536.001123, type 4 (EV_MSC), code 4 (MSC_SCAN), value 70053
Event: time 1434666536.001123, type 1 (EV_KEY), code 69 (KEY_NUMLOCK), value 0
Event: time 1434666536.001123, -------------- EV_SYN ------------

Use the "value" field of MSC_SCAN. This example shows that NumLock has scancode 70053 and keycode 69.

Using dmesg

Note: This method does not provide scancodes for all keys, it only identifies the unknown keys.

You can get the scancode of a key by pressing the desired key and looking the output of dmesg command. For example, if you get:

Unknown key pressed (translated set 2, code 0xa0 on isa0060/serio0

then the scancode you need is 0xa0.

Keycodes

Warning: Note that the keycodes are different for Linux console and Xorg. Use the appropriate tool to determine the desired value.

In console

The keycodes for virtual console are reported by the showkey utility. showkey waits for a key to be pressed and if none is during 10 seconds it quits, which is the only way to exit the program. To execute showkey you need to be in a virtual console, not in a graphical environment. Run the following command

# showkey --keycodes

and try to push keyboard keys, you should see keycodes being printed to the output.

In Xorg

The keycodes used by Xorg are reported by a utility called xev, which is provided by the xorg-xev package. Of course to execute xev, you need to be in a graphical environment, not in the console.

With the following command you can start xev and show only the relevant parts:

 $ xev | awk -F'[ )]+' '/^KeyPress/ { a[NR+2] } NR in a { printf "%-3s %s\n", $5, $8 }'

Here is an example output:

38  a
55  v
54  c
50  Shift_L
133 Super_L
135 Menu

If you press a key and nothing appears in the terminal, it means that either the key does not have a scancode, the scancode is not mapped to a keycode, or some other process is capturing the keypress. If you suspect that a process listening to X server is capturing the keypress, you can try running xev from a clean X session:

$ xinit /usr/bin/xterm -- :1

Mapping scancodes to keycodes

See the main article: Map scancodes to keycodes.

Mapping keycodes to keysyms

In console

See the main article: Extra keyboard keys in console.

In Xorg

See the main article: xmodmap.

Laptops

Asus M series

In order to have control over the light sensor and the multimedia keys on your Asus machine, you should use the following command:

# echo 1 > /sys/devices/platform/asus_laptop/ls_switch

To have it run on boot create a Systemd tmpfile:

/etc/tmpfiles.d/local.conf
w /sys/devices/platform/asus_laptop/ls_switch - - - - 1
Note: This may work also for other Asus notebook models.

Asus N56VJ (or possibly others)

If most of your special keys do not work, try loading the asus-nb-wmi kernel module with

# modprobe asus-nb-wmi

then check xev again. If you combine this with the acpi_osi="!Windows 2012" boot option, you may get weird results in xev, so try not using it. If this did fix things, make sure to make the module load at boot with methods described here.

Gaming Keyboards

Gaming keyboards have some special features which may cause them to "misbehave" in Linux.

Cooler Master CM Storm QuickFire TK

This keyboard has two features that could cause confusion in Linux: N-Key Rollover and the Win-Lock Key.

N-Key Rollover can cause problems with the Function keys. To disable N-key rollover, hold down the FN lock key (next to right-ctrl) until it lights up, then hold Escape and press 6 to switch to 6-key rollover. Hold down the FN lock key to disable the Fn lock.

The Win-Lock Key completely disables the Super (Windows) keys. Simply press the FN lock key and F12 together to toggle Win-Lock on and off.

See also