Help me pull together an FAQ

I’m starting to see a number of queries come up repeatedly, so I think an FAQ is in order. Off the top, I think we need to cover:


  • sticky keys
  • ordering additional keycap sets
  • availability of components for hacker projects
  • replacing switches to change the feel of the keyboard


  • pointer to the wiki
  • pointer to the soon-to-be developer docs (Thanks @merlin!)
  • mention of Win 7/8 issues


  • alternate layouts (English language)
  • international layouts

How to contribute

  • documentation
  • firmware
  • Chrysalis

What am I missing?


Transporting your keyboard
Using the stands

I’d probably recommend splitting the ‘hardware’ section up a bit:

  • Hardware problems for which you should just contact Keyboardio
    ** Key chatter
    ** Defective parts
  • Buying stuff
    ** Keycaps, components, etc
  • Voiding your warranty
    ** Changing your keyswitches
    ** What’s inside the keyboard

Maybe a top level section on ‘setup’

Under that, some content we might want

  • macOS
    ** The apple ‘pick a keyboard’ wizard we can’t disable
  • Windows
    ** Driver issues for reprogramming on win7 / win 8
  • Linux
    ** modemmanager interfering with reprogramming

How about the misaligned USB port? Maybe instructions on how to fix or what to do?


I should be able to work through the various options for those. If I can find a way to reliably wipe the cache…

The issue is that it genuinely can’t be disabled without us pretending to be an Apple keyboard. And that would…go over very, very poorly. I’ve gotten confirmation from folks who…know what they’re talking about. has some notes on this issues.

I wonder if it would be worthwhile to include a MagicCombo/Macro in the default firmware that negotiates the Apple “new keyboard” dialog.

Once the customer knows to do something special at that dialog, it’s easier for them to either know to close the dialog or to just hit z/

But you don’t want to hit z/ necessarily. It depends on what you’ve set your firmware layout to. Closing the window will probably be ok, but I’ll need to test.

1 Like

Even if you haven’t changed the firmware, it doesn’t tell the user that the two keys you should press are z and /, and if you follow directions, you’ll hit the wrong keys. It then becomes necessary to refer to an existing keyboard in order to figure out which keys to press.

Now, I’m not saying my idea is great; maybe it’s better to just remember which two keys to press, rather than remembering some other magic combo, but it might be easier for some of us.

Is something about this shipping in the docs with the production boards? We can document it on the wiki, but I expect most people will have already plugged in the keyboard and done something with it before they look for docs.

I dimly recall hitting this when I first got my Model 01 and writing something about it to Kaia, but my memory is hazy. At this point every computer in the house has been introduced to the Model 01, so I can’t observe and document it without clean installs and I’m not doing that. Can someone give me the details? Or is there a way to reset my computer so I can go through it again? and what happens if you select the wrong characters?

You might be able to trigger it by creating a new user account, but I’m not sure.

If you remove /Library/Preferences/, it should trigger on next connect.


You can also (sometimes!) re-run the keyboard setup utility through System Preferences:

If you press a key that it does not expect, it will beep and make you try again.

It appears to support three kinds of keyboard (US, Japan and International), but there are also “standard” and “mac” variants. You can override the autodetected version, but you can’t make it choose a non-Mac version if it detected a Mac version. Mac versions differ in subtle ways from standard - for example the ISO Mac keyboard has the Backtick and NUBAP scancodes physically swapped. I think this is purely historical - when Mac keyboards were first invented the IBM key layout was not yet standardised, not even on IBM PCs.

All my keyboards are standard ISO International, or set up to behave like it. I deliberately tricked my Mac into thinking that they were US ANSI, US Mac, ISO, ISO Mac, and JIS. They functioned the same way every time. I suspect that the keyboard setup tool only modifies how the keyboard is represented on-screen (for example in the soft keyboard or the layout configuration utility) and does not affect the behaviour of the keys at all.

If you choose a Mac keyboard layout, the option to rerun the keyboard setup utility disappears and you have to remove the plist file AND REBOOT to get it back. Otherwise it will let you reconfigure your keyboard ad infinitum.

My Model01 appears as “8961-4617-0” in the plist file. Values appear to be:

  1. ISO
  2. US ANSI
  3. JIS
  4. ISO Mac
  5. US Mac

So I think the keyboard utility can be safely ignored.

1 Like

Here’s a write-up:

I closed the window when it first came up on one of the macs I connected to, and have not seen any negative consequences.