# Adding the Apple 🌐︎ key to QMK keyboards Apple keyboards have a funky `fn` key with a `🌐︎` globe symbol on them. In most ways this behaves as any other `fn` key, and I've never missed it using a third-party keyboard. 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 using `Application Shortcuts` in `System Preferences`. However, you cannot add 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 this is not ideal. But if you do, the shortcuts will still break. macOS knows the input is coming from software and not the keyboard. So I needed a way to add the key to the keyboard firmware. ## Using QMK My Keychron V10 runs on open-source QMK firmware. QMK usually makes situations like this easy to solve. There's very rarely an original idea in this space and someone has probably already done what you're trying to do. 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. 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](https://gist.github.com/fauxpark/010dcf5d6377c3a71ac98ce37414c6c4) available as a gist but it is now out of date. I tried finding a revision of the `qmk_firmware` repo that I could apply the patch but it never seemed to work. I tried patching it myself manually but again, no luck. ## GitHub code search to the rescue Whenever I find myself stuck solving a niche problem, I turn to GitHub's code search. It's almost guaranteed that someone has solved the problem before. I found a [fork](https://github.com/Thunderbird2086/qmk_firmware) of `qmk_firmware` maintained by `thunderbird2086` with various patches maintained. This includes the `🌐︎` key patch by `fauxpark`. I forked the repo and cloned it to my machine. In the cloned repo, I found the default key-map for keyboard in `keyboards/keychron/v10/ansi_encoder/keymaps/default` and added the rules to apply the patch to `rules.mk`: ```makefile 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: ```c 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: ```c #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. ## Links - [QMK](https://qmk.fm/) - [Karabiner-Elements](https://karabiner-elements.pqrs.org/) - [fauxpark's gist](https://gist.github.com/fauxpark/010dcf5d6377c3a71ac98ce37414c6c4) - [Thunderbird2086's fork](https://github.com/Thunderbird2086/qmk_firmware)