old Apple keyboard

Old macs never die…​. at least in my house where, when they get a bit too long in the tooth to handle the latest versions of OSX, I usually install Debian linux on them [often sans GUI], as that’s what I run on my webservers, so it’s nice to have a Debian box or three lying round the house, so I can practice my l33t *nix skills, without breaking the internet.

The maintainers of Debian proudly boast that it’s the “run anywhere operating system” and that’s pretty much true [although I am still waiting for someone to port it to iPhone!] --I’ve managed to get Debian running on a couple of old iBooks, an old macbook and a G4 desktop.

All finey and dandy and having a bare-bones operating system like Debian installed gives these old comps a new lease of life when they would otherwise end up in the skip, but there’s one area where I’ve always had problems and that’s with getting Debian to play well with Apple keyboards. Running

sudo dpkg-reconfigure keyboard-configuration

gives you a series of menus, where [theoretically!] you can pin down what keyboard you’re using and let Debian work out the rest. In practice however, I’ve never found it to work. Although there are about 5 or 6 options listed under Apple, none of them seemed to work for me. Most of them are fine for typing yer everyday numbers and letters, but the lesser used characters [and even some fairly common ones such as @ and "] seem to always be hiding where I cannae find them, or are typable only through convoluted key combinations.

The same is true for accented characters. It seemed to take a long time for the English speaking world to realise that other languages exist and some of them use accents on letters --one of my ongoing bugbears is when online forms tell me I haven’t spelled my name properly when I use the í character. On my mac in OSX, I can select Irish as a keyboard layout on the OSX menubar and type áéíóú simply by holding down the ALT key, and hitting the appropriate vowel.

the easy way

In Debian I can get a couple of these accented characters by holding down ALT then hitting ' then typing the vowel. But, it only works for á and é. Doing the same with o and u gives you Nordic letters which I don’t mind on my Motorhead t-shirts, but which aren’t much use to me in every day typing.

So, I decided to search out a way to ‘fix’ my keyboard, so that it would behave in Debian the same way it did in OSX. As with most things linuxy, this turned out to be a mightier quest than you might suppose --especially when using a GUI-less version. I had vaguely hoped that there’d be some kind of repository where I could download a proper working layout for my Apple Pro Keyboard [for that was the beast in question], or that there’d be some kind of simple utility that would let me say “when I hit this key, type this character”, but there wasn’t.

---

sidenote: You can identify the exact hardware ID of your USB keyboard in Debian, by using the lsusb command which lists connected USB devices. As you can see, even though the label on the bottom of my keyboard identifies it as an Apple Pro keyboard, Debian actually identifies it as a Mitsumi Apple Extended USB Keyboard. I just throw that into the mix in case it helps anyone properly ID an obscure keyboard.

lsusb --it’s like ls…​ but for USB!

---

My searching didnae turn up anything which might allow me to carry out a five minute ‘quick fix’ but what I did eventually discover, after reading at least a quarter of the intarwebs was a solution which, while involving more work on my part, was also a more powerful one than I had thought might exist. For, lo’, it is in fact possible to completely configure whatever keyboard you have to hand to make it work properly with Debian. It’s not for the faint-hearted but, it’s not really that onerous and I ended up spending barely an hour configuring and customising my keyboard so it behaved on Debian as it used to on OSX.

For the benefit of anyone out there who runs into a similar problem, here’s how I did it. There may be other methods and YMMV, but this worked for me:

1: First of all use the command dumpkeys to dump the existing keyboard mapping to a text file somewhere you can tinker with it, without fucking up the original. I tend to use my home ~ folder as my virtual garden shed:

dumpkeys > ~/madrakeymap`

2: Debian identifies each key on the keyboard by a Keycode number. So, next you need to find out what Keycode each key on your keyboard sends out. To do this you can use the showkey utility. When you run this, it will display on screen the Keycode number for each key you press on the keyboard. To return to your normal shell, just don’t press any keys for ten seconds and showkey will automatically quit.

To keep track of all the Keycode numbers, I printed out a picture of an old Apple keyboard similar to mine and went through the keyboard, pressing each key individually, finding out what keycode it was mapped to and then writing the Keycode on the print out.

there’s not an app for that!

3: Once that was done, it was time to start mapping the keys on the keyboard to the things I wanted them to do.

Once I’d done that, I mapped ALT+vowel to the acute accented version of that vowel, ALT+SHIFT+vowel to the upper case acute accented version of that vowel, ALT+n to ñ and ALT+c to ç [and likewise with their upper case versions], which pretty much gave me all the ‘foreign’ characters in the same places as they reside on the Irish keyboard layout in OSX. I have far too much muscle memory invested in those to start pissing about with apostrophes and suchlike in Linux.

sidenote: Incidentally, I used another handy OSX utility, Keyboard Viewer, which also lives under the keyboard selector menu, to help me remember where all the alternate characters lived under OSX, so I could set them up in the same places on the Apple keyboard I was customising for Debian. It’s a wee window that floats on top of all other applications and highlights what keys you press. If you hold down keys like ALT CONTROL or SHIFT, the floaty keyboard changes to show you what those modifiers will cause the other keys to produce. Really handy! Here I’m holding down ALT

keyboard viewer --really handy!

4: The procedure for customising each key turned out to be pretty straightforward. Time to fire up Vim and edit the keymap I saved right at the beginning:

vim ~/madrakeymap

When you first open the keymap file, it looks pretty daunting. I didn’t count exactly but I’d estimate it has roughly eleventy billion!!!111!! lines. A closer look however reveals that [in what must be a first for Linux!] the configuration file is actually very straightforward to read for human beings, as opposed to machines. Here’s an example for the number 2 on the keyboard [which typically confusingly maps to keycode 3!]

inside the madrakeymap file

The above screngrab shows the number 2 key, after I had tweaked it to put the @ symbol on SHIFT+2 and the € Euro sign on ALT+2 (altgr --is how the ALT is designated)

Each key has a dozen or more mappings listed for it, covering every possible combination, even seemingly impossible ones such as pressing the key while holding down CTRL, both ALTs, SHIFT and possibly the gear lever on a 1963 Humber Sprite. Fortunately, most of them are so obscure you can just leave them as they are.

5: One problem I ran into was that, although listing the characters by name like this makes the keymap pretty easy to read and edit, it does depend quite heavily on you knowing what a character is called. For example, my keyboard layout was completely bereft of a double quotation mark " [SHIFT+clicking the apostrophe key produced an @ symbol!] and I had no idea what the " symbol would be called, as all the symbol names seemed to be only one word long. Searching for “quote” in the file, to see if it had been mapped to another key turned up nothing. So, eventually I hit on the idea of opening up the default US keyboard layout and searching there. So copied that to ~ too, so I could investigate:

cp /usr/share/keymaps/mac/mac-us.kmap.gz ~/yank.kmap.gz

and opened it with Vim. [Chuffed to find that Vim can edit a gzipped file without having to uncompress it first]. Hoking around inside the yank.kmap.gz copy I found that the double quotation mark was actually called quotedbl so, armed with that knowledge, I was able to fix my recalcitrant apostrophe key, so it produced a quotation mark when SHIFTed.

sidenote: I found a list of UTF–8 character names on this page, which helped a bit, although there was still a lot of judicious guesswork involved as I tried to work out from some of the longish unicode names what the succinct short version used in the keymap file might be. Here are a few examples:

± is called plusminus, § is called section, ` is not backtick, but grave, á is called +aacute, é is called +eacute …​and so forth.

I also discovered subsequently that, if you don’t know the linux keymap name of a symbol, you can use the Unicode Code Point identifier instead. eg: U+00A9 is the copyright symbol ©. However, if we all did that, then the keymap file would soon become the same unreadble mass of gibberish that it notably avoids being at present!

6: Trying out each altered keymapping to see if it produced the desired results would have been a laborious process, were it not for the fact that you can temporarily load a keymap into memory using the loadkeys command [as root]

sudo loadkeys ~/madrakeymap

and also the fact that you can execute shell commands from within Vim, without leaving the editor by prefixing them with ! in command mode. This allowed me to make edits to the keymap file, use loadkeys from within Vim to reload the updated keymap file and thus be able to try out the new keys straight away. Once I got into the swing of it, it was relatively painless and easy and I ended up mapping even a load of obscure key combos from the Apple keyboard into my custom keymap --just coz I could!

using shell commands from within Vim

7: Once I’d got bored with my board and decided I’d added enough obscure symbols to they keyboard map, it was time to make the changes permanent. Using loadkeys is all very well, but it only causes Debian to use the amended keymap for the current session. If you reboot your comp, you’ll have the old keymap back again. In order to make the changes permanent, you need to install your new keymap, using the install-keymap command:

sudo install-keymap ~/madrakeymap

This moves [not copies! --so you may want to make a backup first] your custom keymap file into:

/etc/console/boottime.kmap.gz

which, according to the word on the internets should have been that…​. Except, of course, being linux, it wasn’t. After rebooting the comp:

sudo shutdown -r now

I found that my keyboard was just as confused as ever. I had to use sudo loadkeys on my backup keymap to get things working again. And that was very nearly that. I must have spent at least an hour or two,searching the intarwebs and trying different suggestions to try and make the keyboard changes stick through a reboot --none of which worked. Then, just as I was about to throw in the towel and resign myself to having to create some sort of crappy startup script that invoked loadkeys after I logged in, I came across this page, on the Debian Wiki, which said that

So, I thought I’d take a look at this /etc/default/keyboard file and see if there was anything useful in there.

sudo vim /etc/default/keyboard

When I opened that file up, I found the following:

This looked hopeful, since I’d been led to believe from what I’d read elsewhere that the /etc/console/boottime.kmap.gz keymap was supposed to load on startup --which was obviously not happening, since my keyboard kept reverting to the default again, every time I rebooted. This comment seemed to suggest that I needed to explicitly tell Debian if I wanted it to read in an alternate keymap at boot time. So I added a line referring to my custom boottime.kmap.gz:

KMAP=/etc/console/boottime.kmap.gz

then saved the changes and issued another sudo shutdown -r now.

This time we were on the money. when the comp rebooted, I found to my delight and delectation that this time all my hard-tweaked keyboard customisations had finally stuck. The job…​ as my old tutor Steve Marland used to say …​was a good ’un!

And there you have it!

footnote: All in all, this experience pretty much sums up what Linux is all about for me. Trying to do the simplest thing all-too-often turns into a major mind-fuck, where in OSX, you would just open a preference pane or [for example] select a different keyboard from a popup menu. Once you’ve gone through the pain barrier however and worked out HOW the feck to do what it is you want to do, Linux does give you more control over your computer than you likely know what to do with. With the tricks I learned here today, I can now customise any keyboard I want to use with any Linux box, so every single key does exactly what I want it to do. Now that’s what I call user control!

footnote: While I was searching for the answer as to why my changes weren’t sticking through reboots, I came across this page which I wish I’d found earlier, as it give the ‘official’ names for lots of the obscure keys featured in the keymap files. That would have saved me a lot of guesswork, earlier on!