Adding Apple’s Globe key to a QMK-powered keyboard

I don’t remember when Apple quasi-promoted the Globe 🌐︎ key to act as a modifier that can be used much like Control, Option, and Command, but it’s becoming increasingly useful to have it handy nowadays.

With macOS Sequoia reaching GA back in September, a treasure trove of sorely overdue windowing commands have been introduced:

A lot of these can also be achieved with the mouse, much in the same vein as Aero Snap. I also recently discovered that if you fill the screen with two perfectly adjacent windows, you can effortlessly adjust the division by hovering over the middle of the boundary—it summons a little handle that you can grab. Accordingly, the “Left & Right” and “Right & Left” commands (⌃⇧🌐︎←, ⌃⇧🌐︎→) arranges your last two windows into this exact configuration. It’s all very neat!

Alongside the updated iMacs released last October also came refreshed Mac accessories, finally outfitted with USB-C ports. I have been waiting for this for months. On the Magic Keyboard with Touch ID and Numeric Keypad, the Globe key was moved from the nav cluster to be adjacent to Control, shrinking the surrounding keys. In its place is a new Menu key, which does as you expect. It’s probably equivalent to pressing ⌃↩ (Control-Enter), a functionality that is also new in Sequoia.

The Globe key has migrated to the southwest corner, resulting in a shrinkage of the adjacent modifier keys. This has required some retraining of my muscle memory, which kinda sucks.

These new windowing commands and the moving of the Globe key leads me to conclude that Apple would like us to take advantage of these spiffy shortcuts involving Globe. (There’s also some lesser known ones—🌐︎C opens Control Center, 🌐︎N summons Notification Center, etc. More here and here.)

That all being said, I own several bespoke mechanical keyboards that weren’t made by Apple¹, so they lack this key out of the box. But it’s fortunately possible to add this key by compiling custom firmware…!

Adding the Globe key to your QMK keymap#

I won’t go into bootstrapping a custom keymap in this blog post, so check the QMK docs for that. However, my instructions are hopefully serviceable after getting set up.

In qmk/qmk_firmware#16651, someone pointed out that in Apple’s Accessory Design Guidelines document, they describe Usage ID 0x029D (“AC Keyboard Layout Select”) as corresponding to the Globe key.

I then found this GitHub Gist about the “Apple FN” key in QMK, in which the same user posted concrete instructions to enable the Globe key. (What I’m referring to as the “Globe key” is also the “fn key”, I think. Said key used to only have “fn” as the legend, and then the Globe was added later. I’m not sure if the fn key is a conceptually different thing or whatever, but it’s probably important to point out this naming discrepancy.)

After trudging through the comments in that Gist, I determined a relatively straightforward way to add the Globe key to your QMK keymap, seemingly without applying any patches to the core QMK code itself, nor having to pretend to be an Apple keyboard.

(Fair warning: I don’t know if this constitutes misuse of QMK’s API surface, or if this is Bad. But it seems to work perfectly fine for me.)

1. Define a new keycode representing the globe key. I do this in my keymap.c file:

   enum my_keycodes {
    // apple globe key
    AP_GLOB = SAFE_RANGE,
   };
   

   (= SAFE_RANGE is only necessary for the first custom keycode. Subsequent ones are merely separated by commas.)

2. As described in this Gist comment, program the custom keycode by overriding the process_record_user function, calling the host_consumer_send function to report the Consumer Usage ID over USB. (Or something. I don’t really know how USB actually works and I don’t intend to find out.)

   I’m also doing this in my keymap.c:

   bool process_record_user(uint16_t keycode, keyrecord_t *record) {
     switch (keycode) {
     case AP_GLOB:
       host_consumer_send(record->event.pressed ? AC_NEXT_KEYBOARD_LAYOUT_SELECT : 0);
       return false;
     }
   
     return true;
   }
   

   You may also add additional custom keycodes and handle them here. For example, AC_DESKTOP_SHOW_ALL_WINDOWS invokes Mission Control, AL_KEYBOARD_LAYOUT toggles iPadOS’s onscreen keyboard, etc. These are all described in Apple’s Accessory Design Guidelines.

3. The previous two steps are enough to get the Globe key working for e.g. bringing up the character picker. To use Globe as a modifier in conjunction with other keys (🌐︎Q), I had to set KEYBOARD_SHARED_EP = yes in my rules.mk:

   KEYBOARD_SHARED_EP = yes
   

   Depending on your keyboard’s microcontroller, this might not work, as its USB endpoints are a finite resource. This is described in the QMK docs here. Also, for posterity, I was hinted by this comment.

After specifying AP_GLOB as a key in my keymap, I’m able to use the Globe key as if it were a Globe key on an Apple keyboard. It seemingly behaves identically, too; I haven’t ran into any hiccups so far. I don’t even have to override the USB vendor ID nor the product ID. 🎉

It even appears as a remappable key in System Settings:

System Settings > Keyboard > Keyboard Shortcuts… > Modifier Keys

A Cupertino miracle. In my case, I’m doing this with the Mode Loop, a snazzy TKL (tenkeyless; everything but the numpad) keyboard. Since I can’t resist showing it off, here it is:

A Mode Loop, wearing GMK Purple-ish keycaps. Above it is a Tofu65 2.0 sporting Mode Obscura keycaps.

There’s also some alternate instructions here in case mine don’t work out for whatever reason.

Thank you, team who implemented this#

These windowing commands are great, and it’s nice to have first-party functionality for forcing a window to fill the screen. (Zoom, which can also be accessed by Option-clicking the green² traffic light, is somewhat deceptive in that it’s supposed to resize the window to naturally encompass its contents. If the app doesn’t specify a size, it defaults to “nearly” the entire screen—but Finder, Safari, and some others override this. Meanwhile, “Fill” always fills the screen with the window, and is probably what most people want.)