Set up a hyperkey and globe key on iPadOS with a QMK keyboard

Last updated Jul 30, 2024 | Originally published Jul 30, 2024

I really wanted the experience this person is having, but with an iPad:

So I recently picked up a Nuphy Air75 v2 keyboard (Wisteria switches) with the Nufolio case/stand.

For a quick review of the experience: it’s pretty great! The keyboard itself sounds and feels excellent — much better than the iPad Pro’s Magic Keyboard, which I used begrudgingly with my previous iPad Pro. It has all kinds of great features that I’d consider basic at this point:

• multi-device pairing (so I switch between using it with my phone and my iPad, a feature that has already been helpful when I needed to type a message on an app I don’t have installed on the iPad)
• built-in kickstand feet at adjustable levels
• F-row keys
• customizable backlighting

But most importantly, the iPad doesn’t need to be attached to it for it to work. Thus I can sketch and layout diagrams with typing, touch, and stylus, all at once, while the iPad is in my hands or lying flat. It’s quite nice.

However, the keyboard’s layout is not what I’m used to. On the Mac, I’ve conventionally customized my keyboard with BetterTouchTool and other third-party services. Unfortunately, the iPad is a “console computer” and iPadOS isn’t a real operating system. So, iPadOS doesn’t allow developers to develop cross-system customization tools, and iPadOS only offers a very limited set of keyboard customization options. You can use Settings → General → Keyboard to change a few modifier keys around, but that’s about it unless you want to turn on full “accessibility mode”-customization. (Accessibility → Keyboard and Typing → Hardware Keyboard → Full Keyboard Access, IIRC.) This gives the keyboard all kinds of power over what you can select and act on in the OS, but it’s a bit intrusive and not necessary for my use-cases. Regardless, even the “Full Keyboard Access” options fail to let you do the really fancy keyboard customizations I’ve come to rely upon, such as setting up capslock as a hyperkey: changing the capslock key to function as esc when tapped and shift+alt+ctrl+cmd when held.

Fortunately, the Air75, like most modern mechanical keyboards, is a QMK keyboard. That means that the keyboard itself is customizable on a firmware level: you can use tools like the VIA keyboard customization console to fundamentally change what the keys on the keyboard do. So, that’s what I did! Now, even on iPadOS, tapping capslock enters esc, and holding capslock gives me the shift+ctrl+alt+cmd modifiers all at once. This functionality is now just how my particular keyboard works, so it will work the same way on any device I connect the keyboard to, no operating system-level customizations or third-party services (such as BetterTouchTool or Hyperkey) required.

Here’s a quick guide for you to do it, too (provided without warranties, guarantees, or support):

• Purchase a QMK VIA-compatible keyboard
• Follow the manufacturer’s instructions to set up the keyboard to work with VIA, if necessary (Nuphy’s instructions are here)
• Open VIA and connect your keyboard (again following the manufacturer’s/VIA’s/QMK’s instructions to make sure it’s connected and authorized properly)
• In VIA’s configuration tab, select the capslock key
• In the customization options available at the bottom of the screen, choose the “Special” tab, then select ANY
• Enter MT(MOD_HYPR, KC_ESC).¹ This translates to:
  • MT: Modifier-tap, as in “act as the modifiers I specify when held, enter the keycode I specify when tapped”
  • MOD_HYPR: shift+control+alt+GUI, where “GUI” means cmd on macOS and win on Windows and… something on Linux, presumably (I avoid the warren of rabbitholes that is Linux for reasons that should be obvious if you’re reading this post)
  • KC_ESC: the esc key.

Now, what about the “Globe” key? It has become increasingly useful on iPadOS in recent years, but for complicated reasons, it is currently not possible to add a globe key to a keyboard via VIA/QMK. Fortunately, iPadOS allows you to modify your modifier keys (as mentioned before: General → Keyboard → Hardware Keyboard → Modifier Keys). We can remap capslock to the globe key! Never mind that you just got rid of the capslock key: just use VIA to place capslock elsewhere, e.g., on your now-redundant escape key. Then, change your capslock to globe on your iPad, and you now have a globe key on your keyboard, too.

Here’s my final layout: