jd.industries

Adding the Apple 🌐︎ key to QMK

Reposted from old blog.

Apple keyboards have a funky fn key with a 🌐︎ globe symbol on it. In most ways this behaves like any other fn key. I've never missed it using a third-party keyboard on macOS. Generally, you could just ignore it unless you really wanted quick access to the emoji picker.

This changed with macOS Sequoia. The 🌐︎ key is now the default modifier for most window management shortcuts. These can be remapped in System Settings but you use an fn modifier and, without it, you often clash with common shortcuts in other applications. There's no way to avoid this and macOS will give priority to the application shortcut.

The fn key on third-party keyboards will not work as the 🌐︎ key. This is because the 🌐︎ key is proprietary and exclusive to Apple keyboards. You can remap it using software like Karabiner-Elements but if you do, the window shortcuts will still break. macOS knows the input is coming from software and not the keyboard.

So to get the shortcuts working, I'd need to modify my keyboard's firmware.

Using QMK

My Keychron V10 runs on open-source QMK firmware. QMK usually makes situations like this easy to solve. However, as with most things Apple, it's a little more complicated.

The 🌐︎ key is not on any standard key-map and is not supported by QMK. This is why most macOS-specific third-party keyboards have a fn key in the place of the 🌐︎ key.

There were pull requests in the QMK repo to add the 🌐︎ key. But they didn't go anywhere (legal reasons). Some code related to the key was later merged into the QMK repo but seems to have been removed again.

QMK contributor fauxpark made a patch available as a gist but it is now out of date. I tried finding a revision of QMK that I could apply the patch but no luck. I tried patching it myself but failed.

GitHub code search to the rescue

Whenever I find myself stuck solving a niche coding problem, I turn to GitHub's code search. Nine times out of ten, you'll find the work has already been done for you. I found a fork of QMK maintained by thunderbird2086 with various patches maintained. This includes the 🌐︎ key patch by fauxpark.

I cloned the repo, found the default key-map for my keyboard at keyboards/keychron/v10/ansi_encoder/keymaps/default and added the rules to apply the patch to rules.mk:

APPLE_FN_ENABLE = yes
KEYBOARD_SHARED_EP = yes

Then I had to add the key to the keymap.c file. From what I can tell, you can't just make the key a modifier with LM() or MO() as it doesn't send the key code to the OS. So I had to make it a normal key. I replaced MO(MAC_FN) with just AP_FN, and handled the layer switching in the process_record_user function, like so:

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
    if (keycode == AP_FN) {
        if (record->event.pressed) {
            layer_on(MAC_FN);
        } else {
            layer_off(MAC_FN);
        }
    }
    return true;
}

With that done, I flashed the firmware. Checking Karabiner-EventViewer I could see that the key registered the same as on my MacBook. I tried out some key combinations:

🌐︎ + ⌃ - F to make an app full screen; 🌐︎ + ⌃ - C to centre an app; and double-tapping 🌐︎ to dictate text all worked. But, 🌐︎ + ⇧ - arrow key to move applications between window 'tiles' and 🌐︎ + ⌃ + ⇧ - arrow key to 'arrange tiles' didn't work.

It seems something weird is going on with certain shortcuts. Particularly ones with more than two modifiers. I went back and re-read the pull request and gist comments. I had missed the important part required to make the patch work. I needed to trick macOS into thinking my Keychron V10 was a genuine Apple keyboard.

Thankfully, this is easy in QMK. In the top-level directory for my keyboard, in my case keyboards/keychron/v10/ansi_encoder, I added a config.h file with the following:

#undef VENDOR_ID
#undef PRODUCT_ID
#define VENDOR_ID  0x05AC // Apple
#define PRODUCT_ID 0x029C // Aluminum Keyboard (ANSI)

I flashed again and it worked! System Information identifies my Keychron as an Apple keyboard and all of the shortcuts now work as expected.

Drawbacks

There are still some quirks. The screen brightness up/down key seemed to break on my external monitor (unless my MacBook screen was open?). This shouldn't be the case, as my monitor is supported natively by macOS. I likely need to change how that key is handled in QMK. A job for another day.

VIA is also broken, likely as my firmware and keyboard are not recognised as a Keychron V10. I don't use VIA so this isn't a big deal for me.