Difference between revisions of "Apple Keyboard"

From ArchWiki
Jump to navigation Jump to search
(→‎Treating Apple keyboards like regular keyboards: Add notes about the differences between un-apple-keyboard and patch to hid-apple)
(Update to reflect changes in hid-apple-patched)
 
(19 intermediate revisions by 13 users not shown)
Line 9: Line 9:
 
== Numlock is on ==
 
== Numlock is on ==
  
You may find that the numlock is on. The symptoms are that only the physical keys 7,8,9,u,i,o,j,k,l and surrounding keys work and output numbers. To fix this hit {{ic|Fn}}+{{ic|F6}} twice.
+
You may find that the numlock is on. The symptoms are that only the physical keys {{ic|7}},{{ic|8}},{{ic|9}},{{ic|u}},{{ic|i}},{{ic|o}},{{ic|j}},{{ic|k}},{{ic|l}} and surrounding keys work and output numbers. To fix this hit {{ic|Fn+F6}} twice.
  
 
Alternatively, set the keycodes manually using [[xmodmap]] to avoid use Numlock:
 
Alternatively, set the keycodes manually using [[xmodmap]] to avoid use Numlock:
Line 30: Line 30:
 
== Function keys do not work ==
 
== Function keys do not work ==
  
If your {{ic|F<num>}} keys do not work, this is probably because the kernel driver for the keyboard has defaulted to using the media keys and requiring you to use the {{ic|Fn}} key to get to the {{ic|F<num>}} keys. To change the behavior temporarily, [[Help:Reading#Append.2C_add.2C_create.2C_edit|append]] {{ic|2}} to {{ic|/sys/module/hid_apple/parameters/fnmode}}. To make the change permanent, [[Kernel_modules#Setting_module_options|set]] the {{ic|hid_apple}} {{ic|fnmode}} option to 2.
+
If your {{ic|F<num>}} keys do not work, this is probably because the kernel driver for the keyboard has defaulted to using the media keys and requiring you to use the {{ic|Fn}} key to get to the {{ic|F<num>}} keys. To change the behavior temporarily, [[append]] {{ic|2}} to {{ic|/sys/module/hid_apple/parameters/fnmode}}.
 +
 
 +
# echo 2 > /sys/module/hid_apple/parameters/fnmode
 +
 
 +
To make the change permanent, [[Kernel_modules#Setting_module_options|set]] the {{ic|hid_apple}} {{ic|fnmode}} option to 2:
 +
 
 +
{{hc|/etc/modprobe.d/hid_apple.conf|2=
 +
options hid_apple fnmode=2
 +
}}
 +
 
 +
To apply the change to your initial ramdisk, in your [[Mkinitcpio#Configuration|mkinitcpio configuration]] (usually {{ic|/etc/mkinitcpio.conf}}), make sure you either have {{ic|modconf}} included in the {{ic|HOOKS}} variable or {{ic|/etc/modprobe.d/hid_apple.conf}} in the {{ic|FILES}} variable. You would then need to [[regenerate the initramfs]].
 +
 
 +
== Switching Cmd and Alt/AltGr ==
 +
 
 +
This will switch the left {{ic|Alt}} and {{ic|Cmd}} key as well as the right {{ic|Alt}}/{{ic|AltGr}} and {{ic|Cmd}} key.
 +
 
 +
Temporary and immediate solution:
 +
 
 +
# echo "1" > /sys/module/hid_apple/parameters/swap_opt_cmd
 +
 
 +
Permanent change, taking place at next reboot:
 +
 
 +
{{hc|/etc/modprobe.d/hid_apple.conf|2=
 +
options hid_apple swap_opt_cmd=1
 +
}}
 +
 
 +
You then need to [[regenerate the initramfs]].
  
 
== < and > have changed place with § and ½ ==
 
== < and > have changed place with § and ½ ==
Line 52: Line 78:
 
With German layout, circumflex/degree symbol and </> are exchanged. With French layout, @/# are exchanged. With the US layout, `/~ and </> are exchanged.
 
With German layout, circumflex/degree symbol and </> are exchanged. With French layout, @/# are exchanged. With the US layout, `/~ and </> are exchanged.
  
To change the behavior temporarily, [[Help:Reading#Append.2C_add.2C_create.2C_edit|append]] {{ic|0}} to {{ic|/sys/module/hid_apple/parameters/iso_layout}}. To make the change permanent, [[Kernel_modules#Setting_module_options|set]] the {{ic|hid_apple}} {{ic|iso_layout}} option to 0.
+
To change the behavior temporarily, [[Help:Reading#Append, add, create, edit|overwrite]] {{ic|/sys/module/hid_apple/parameters/iso_layout}} with {{ic|0}}:
 +
 
 +
# echo "0" > /sys/module/hid_apple/parameters/iso_layout
 +
 
 +
To make the change permanent, [[Kernel_modules#Setting_module_options|set]] the {{ic|hid_apple}} {{ic|iso_layout}} option to 0:
 +
 
 +
{{hc|/etc/modprobe.d/hid_apple.conf|2=
 +
options hid_apple iso_layout=0
 +
}}
 +
 
 +
You then need to [[regenerate the initramfs]].
  
 
== PrintScreen and SysRq ==
 
== PrintScreen and SysRq ==
Line 66: Line 102:
 
=== Use a patch to hid-apple ===
 
=== Use a patch to hid-apple ===
  
While the original {{ic|hid-apple}} module doesn't have options to further customize the keyboard, like swapping {{ic|Fn}} and left {{ic|Ctrl}} keys or having {{ic|Alt}} on the left side of {{ic|Super}}, there is a [https://github.com/free5lot/hid-apple-patched patch] adding this functionality to the module. To install the patch, [[install]] the {{AUR|hid-apple-patched-git-dkms}} package.
+
While the original {{ic|hid-apple}} module does not have options to further customize the keyboard, like swapping {{ic|Fn}} and left {{ic|Ctrl}} keys or having {{ic|Alt}} on the left side of {{ic|Super}}, there is a [https://github.com/free5lot/hid-apple-patched patched version] adding this functionality to the module. To use it, [[install]] the {{AUR|hid-apple-patched-git-dkms}} package. This will install the patched {{ic|hid-apple}} and mask out the original one.
  
In addition to the patched kernel module, a configuration file is also provided by the package at {{ic|/etc/modprobe.d/hid_apple_pclayout.conf}}, which enables PC-like layout by default:
+
The package uses [[DKMS]] to automatically recompile the module during kernel upgrades. While the {{Pkg|dkms}} will be pulled in by dependency. You still need to install an appropriate kernel header package manually. See the DKMS page for more info.
 +
 
 +
In addition to the patched kernel module, a configuration file is also provided by the package at {{ic|/usr/lib/modprobe.d/hid_apple.conf}}, which enables PC-like layout by default:
  
 
* Top-row keys are normally function keys, switchable to media keys by holding Fn key, as in [[#Function keys do not work]].
 
* Top-row keys are normally function keys, switchable to media keys by holding Fn key, as in [[#Function keys do not work]].
 
* Four keys at the lower left corner act as {{ic|Ctrl}}, {{ic|Fn}}, {{ic|Super}}, {{ic|Alt}}, in this order.
 
* Four keys at the lower left corner act as {{ic|Ctrl}}, {{ic|Fn}}, {{ic|Super}}, {{ic|Alt}}, in this order.
* {{ic|Super}} and {{ic|Alt}} keys on the right are swapped.
+
* Two keys at the lower right corner act as {{ic|Alt}}, {{ic|Ctrl}}, in this order.
 
* If you have an {{ic|Ejectcd}} key, it will act as {{ic|Delete}} key.
 
* If you have an {{ic|Ejectcd}} key, it will act as {{ic|Delete}} key.
  
Please refer to https://github.com/free5lot/hid-apple-patched#configuration for exact meaning of each configuration options and tweaking the configuration file to suit your need.
+
If you wish to change the default options, copy the configuration file to {{ic|/etc/modeprobe.d}} and make desired changes:
 +
 
 +
sudo cp {/usr/lib,/etc}/modprobe.d/hid_apple.conf
 +
 
 +
The file under {{ic|/etc/modprobe.d}} will completely override the one with the same name under {{ic|/usr/lib/modprobe.d}}, and the content is '''NOT''' merged.
 +
 
 +
Alternatively, put additional options in a file with a different name if you want to keep default ones,
 +
 
 +
{{Note|Do not forget to update ''initramfs'' after manual changes to configuration files.}}
 +
 
 +
Please refer to the project [https://github.com/free5lot/hid-apple-patched#configuration README] for the exact meaning of each configuration option and tweaking the configuration file to suit your needs. Learn more about {{ic|modprobe.d}} at [[Kernel_module#Using_files_in_/etc/modprobe.d/]].
 +
 
 +
After installation, reboot for the change to take effect, or [[#Change_the_Behavior_Without_Reboot]].
 +
 
 +
==== Troubleshooting configuration not picked up by the module ====
 +
 
 +
First, make sure the patched version is loaded, see what parameters are provided by the module:
 +
 
 +
ls /sys/module/hid_apple/parameters/
  
{{Note| Don't forget to include the configuration file in ''initramfs'' otherwise it won't work automatically after boot. Refer to [[Mkinitcpio#BINARIES and FILES]] or [[Mkinitcpio#HOOKS]] (the hook you might need is called {{ic|modconf}}) about how to do that.}}
+
If you don't see new options like {{ic|swap_fn_leftctrl}}, {{ic|ejectcd_as_delete}}, etc., check your dkms installation.
  
After installation the change is not picked up by the kernel immediately. The simplest way is to just reboot your system and the new behavior should be in effect.
+
Then, check if configuration files are correctly included in ''initramfs'':
 +
 
 +
mkdir inintramfs && lsinitcpio -x /boot/initramfs-linux.img
 +
 
 +
Check the presence and content of {{ic|inintramfs/usr/lib/modprobe.d/hid_apple.conf}} and any other relevant configuration files in {{ic|inintramfs/etc/modprobe.d}}. If they are not there, you should check your {{ic|/etc/mkinitcpio.conf}} to include those. By default, there should
 +
be a {{ic|modconf}} hook that automatically include those files, if not, add it to the {{ic|HOOKS}} array after {{ic|autodetect}}.
 +
 
 +
Alternatively, list those files in {{ic|FILES}} array explicitly:
 +
 
 +
FILES=(/usr/lib/modprobe.d/hid_apple.conf)
 +
 
 +
Refer to [[Mkinitcpio#BINARIES and FILES]] and [[Mkinitcpio#HOOKS]] for more explanation on what this means.
 +
 
 +
Finally, rebuild the ''initramfs'' and reboot.
 +
 
 +
sudo mkinitcpio -P
  
 
=== Use un-apple-keyboard ===
 
=== Use un-apple-keyboard ===
Line 92: Line 163:
 
The first 3 aforementioned features are brought to you using the default linux kernel module {{ic|hid-apple}}.
 
The first 3 aforementioned features are brought to you using the default linux kernel module {{ic|hid-apple}}.
  
The last one is provided by providing a mapping to {{Pkg|keyfuzz}}.
+
The last one is provided by providing a mapping to {{AUR|keyfuzz}}.
  
 
=== Change the Behavior Without Reboot ===
 
=== Change the Behavior Without Reboot ===
 
{{Warning|If the builtin keyboard and touch pad are the only input device, beware that doing so might leave your computer in an inoperable state unless hard reboot when the second command failes.}}
 
{{Warning|If the builtin keyboard and touch pad are the only input device, beware that doing so might leave your computer in an inoperable state unless hard reboot when the second command failes.}}
  
To reload the kernel module without reboot, run {{ic|sudo rmmod hid_apple && sudo modprobe hid_apple}}.
+
To reload the kernel module without reboot, run {{ic|rmmod hid_apple && modprobe hid_apple}}.
 +
 
 +
== Magic Keyboard does not connect ==
 +
 
 +
If you have a magic keyboard that will not connect to the system through the built in tools, such as the Gnome 3 bluetooth menu in settings, install {{Pkg|blueman}} and its dependencies and attempt to connect with it.  If it still fails to connect, make sure you have bluetoothctl and hcitool installed.
 +
 
 +
== Enable dvorak/dvp ==
 +
By default xkb loads translation table (actually called {{ic|xkb_symbols}}) {{ic|macintosh_vndr/us}} for macintosh keyboard:
 +
 
 +
setxkbmap -print -verbose 10 | grep symbols
 +
 
 +
This translation table located in {{ic|/usr/share/X11/xkb/symbols/macintosh_vndr/us}} and don't contains dvorak/dvp layout. You can use default translation table from {{ic|/usr/share/X11/xkb/symbols/us}} and add command {{ic|setxkbmap}} in your {{ic|.profile}} for forced loading layout:
 +
 
 +
sudo mv /usr/share/X11/xkb/symbols/macintosh_vndr/us /usr/share/X11/xkb/symbols/macintosh_vndr/us.back
 +
sudo cp /usr/share/X11/xkb/symbols/us /usr/share/X11/xkb/symbols/macintosh_vndr/us
 +
echo "setxkbmap -v 10 -layout us -variant dvp" >> .xprofile
  
 
== See also ==
 
== See also ==
  
*https://help.ubuntu.com/community/AppleKeyboard
+
* https://help.ubuntu.com/community/AppleKeyboard
*https://github.com/hlechner/xmodmap-aluminium-pt-br
+
* https://github.com/hlechner/xmodmap-aluminium-pt-br
*https://github.com/free5lot/hid-apple-patched
+
* https://github.com/free5lot/hid-apple-patched

Latest revision as of 04:13, 4 April 2020

Some Apple keyboard models may have swapped keys or missing functionality. This article describes how to change the settings for the keyboard so that it behaves as expected.

Numlock is on

You may find that the numlock is on. The symptoms are that only the physical keys 7,8,9,u,i,o,j,k,l and surrounding keys work and output numbers. To fix this hit Fn+F6 twice.

Alternatively, set the keycodes manually using xmodmap to avoid use Numlock:

keycode  90 = KP_0 KP_0 KP_0 KP_0 KP_0 KP_0
keycode  87 = KP_1 KP_1 KP_1 KP_1 KP_1 KP_1
keycode  88 = KP_2 KP_2 KP_2 KP_2 KP_2 KP_2
keycode  89 = KP_3 KP_3 KP_3 KP_3 KP_3 KP_3
keycode  83 = KP_4 KP_4 KP_4 KP_4 KP_4 KP_4
keycode  84 = KP_5 KP_5 KP_5 KP_5 KP_5 KP_5
keycode  85 = KP_6 KP_6 KP_6 KP_6 KP_6 KP_6
keycode  79 = KP_7 KP_7 KP_7 KP_7 KP_7 KP_7
keycode  80 = KP_8 KP_8 KP_8 KP_8 KP_8 KP_8
keycode  81 = KP_9 KP_9 KP_9 KP_9 KP_9 KP_9

Repeating keys on a wireless keyboard

Unpair the keyboard and then re-pair it. The trick is to hold down the power button throughout the entire pairing process.

Function keys do not work

If your F<num> keys do not work, this is probably because the kernel driver for the keyboard has defaulted to using the media keys and requiring you to use the Fn key to get to the F<num> keys. To change the behavior temporarily, append 2 to /sys/module/hid_apple/parameters/fnmode.

# echo 2 > /sys/module/hid_apple/parameters/fnmode

To make the change permanent, set the hid_apple fnmode option to 2:

/etc/modprobe.d/hid_apple.conf
options hid_apple fnmode=2

To apply the change to your initial ramdisk, in your mkinitcpio configuration (usually /etc/mkinitcpio.conf), make sure you either have modconf included in the HOOKS variable or /etc/modprobe.d/hid_apple.conf in the FILES variable. You would then need to regenerate the initramfs.

Switching Cmd and Alt/AltGr

This will switch the left Alt and Cmd key as well as the right Alt/AltGr and Cmd key.

Temporary and immediate solution:

# echo "1" > /sys/module/hid_apple/parameters/swap_opt_cmd

Permanent change, taking place at next reboot:

/etc/modprobe.d/hid_apple.conf
options hid_apple swap_opt_cmd=1

You then need to regenerate the initramfs.

< and > have changed place with § and ½

If the < and > are switched with the § and ½ keys, set the xkb option apple:badmap, for instance by running the following command in your graphical environment:

$ setxkbmap -option apple:badmap

Alternatively, set the keycodes manually using xmodmap:

keycode  49 = less greater less greater bar brokenbar
keycode  94 = section degree section degree notsign notsign

If you use a Canadian multilingual layout (where the "ù" and the "/" is switch) use this:

keycode  94 = slash backslash slash backslash bar brokenbar
keycode  49 = ugrave Ugrave ugrave Ugrave notsign notsign

< and > have changed place with ^ and ° (or @ and #, or ` and ~)

With German layout, circumflex/degree symbol and </> are exchanged. With French layout, @/# are exchanged. With the US layout, `/~ and </> are exchanged.

To change the behavior temporarily, overwrite /sys/module/hid_apple/parameters/iso_layout with 0:

# echo "0" > /sys/module/hid_apple/parameters/iso_layout

To make the change permanent, set the hid_apple iso_layout option to 0:

/etc/modprobe.d/hid_apple.conf
options hid_apple iso_layout=0

You then need to regenerate the initramfs.

PrintScreen and SysRq

Apple Keyboards have an F13 key instead of a PrintScreen/SysRq key. This means that Alt+SysRq sequences do not work, and application actions associated with PrintScreen (such as taking screenshots in many games that work under Wine) do not work. To fix this, you can add setxkbmap -option "apple:alupckeys" to your .xinitrc. This will map PrintScreen/SysRq to F13, as well as Scroll lock to F14 and Pause to F15.

Alternatively, follow the Map scancodes to keycodes article to map the F13 scancode to the PrintScreen/SysRq keycode, where 458856 (0x070068) is the scancode of F13, and sysrq is the keycode of PrintScreen/SysRq.

Treating Apple keyboards like regular keyboards

Depending on the customisations you want to accomplish, there are two solutions available. You need to choose one of the other.

Use a patch to hid-apple

While the original hid-apple module does not have options to further customize the keyboard, like swapping Fn and left Ctrl keys or having Alt on the left side of Super, there is a patched version adding this functionality to the module. To use it, install the hid-apple-patched-git-dkmsAUR package. This will install the patched hid-apple and mask out the original one.

The package uses DKMS to automatically recompile the module during kernel upgrades. While the dkms will be pulled in by dependency. You still need to install an appropriate kernel header package manually. See the DKMS page for more info.

In addition to the patched kernel module, a configuration file is also provided by the package at /usr/lib/modprobe.d/hid_apple.conf, which enables PC-like layout by default:

  • Top-row keys are normally function keys, switchable to media keys by holding Fn key, as in #Function keys do not work.
  • Four keys at the lower left corner act as Ctrl, Fn, Super, Alt, in this order.
  • Two keys at the lower right corner act as Alt, Ctrl, in this order.
  • If you have an Ejectcd key, it will act as Delete key.

If you wish to change the default options, copy the configuration file to /etc/modeprobe.d and make desired changes:

sudo cp {/usr/lib,/etc}/modprobe.d/hid_apple.conf

The file under /etc/modprobe.d will completely override the one with the same name under /usr/lib/modprobe.d, and the content is NOT merged.

Alternatively, put additional options in a file with a different name if you want to keep default ones,

Note: Do not forget to update initramfs after manual changes to configuration files.

Please refer to the project README for the exact meaning of each configuration option and tweaking the configuration file to suit your needs. Learn more about modprobe.d at Kernel_module#Using_files_in_/etc/modprobe.d/.

After installation, reboot for the change to take effect, or #Change_the_Behavior_Without_Reboot.

Troubleshooting configuration not picked up by the module

First, make sure the patched version is loaded, see what parameters are provided by the module:

ls /sys/module/hid_apple/parameters/

If you don't see new options like swap_fn_leftctrl, ejectcd_as_delete, etc., check your dkms installation.

Then, check if configuration files are correctly included in initramfs:

mkdir inintramfs && lsinitcpio -x /boot/initramfs-linux.img

Check the presence and content of inintramfs/usr/lib/modprobe.d/hid_apple.conf and any other relevant configuration files in inintramfs/etc/modprobe.d. If they are not there, you should check your /etc/mkinitcpio.conf to include those. By default, there should be a modconf hook that automatically include those files, if not, add it to the HOOKS array after autodetect.

Alternatively, list those files in FILES array explicitly:

FILES=(/usr/lib/modprobe.d/hid_apple.conf)

Refer to Mkinitcpio#BINARIES and FILES and Mkinitcpio#HOOKS for more explanation on what this means.

Finally, rebuild the initramfs and reboot.

sudo mkinitcpio -P

Use un-apple-keyboard

If you do not need all of these customizations and you do not want to compile a new module manually or using dkms, there is an AUR package un-apple-keyboardAUR which does not rely on a new kernel module, but rather just to mappings. It enables the following features:

  • The keyboard is considered as an ISO keyboard (e.g. < and > located at the right of the Left Shift key are working like expected).
  • The function keys are disabled by default. You need to press the Fn key in combination to trigger them. By default, the behavior are thus keys F1 to F12
  • The Alt and Cmd keys are swapped.
  • F13 is mapped to SYSRQ, F14 to Scroll Lock and F15 to Pause.

The first 3 aforementioned features are brought to you using the default linux kernel module hid-apple.

The last one is provided by providing a mapping to keyfuzzAUR.

Change the Behavior Without Reboot

Warning: If the builtin keyboard and touch pad are the only input device, beware that doing so might leave your computer in an inoperable state unless hard reboot when the second command failes.

To reload the kernel module without reboot, run rmmod hid_apple && modprobe hid_apple.

Magic Keyboard does not connect

If you have a magic keyboard that will not connect to the system through the built in tools, such as the Gnome 3 bluetooth menu in settings, install blueman and its dependencies and attempt to connect with it. If it still fails to connect, make sure you have bluetoothctl and hcitool installed.

Enable dvorak/dvp

By default xkb loads translation table (actually called xkb_symbols) macintosh_vndr/us for macintosh keyboard:

setxkbmap -print -verbose 10 | grep symbols

This translation table located in /usr/share/X11/xkb/symbols/macintosh_vndr/us and don't contains dvorak/dvp layout. You can use default translation table from /usr/share/X11/xkb/symbols/us and add command setxkbmap in your .profile for forced loading layout:

sudo mv /usr/share/X11/xkb/symbols/macintosh_vndr/us /usr/share/X11/xkb/symbols/macintosh_vndr/us.back
sudo cp /usr/share/X11/xkb/symbols/us /usr/share/X11/xkb/symbols/macintosh_vndr/us
echo "setxkbmap -v 10 -layout us -variant dvp" >> .xprofile

See also