Adding support for Apple fn/Globe key to QMK

Readme.md

What this does

This allows you to define a key for your QMK keyboard which has some of the same functionality as the fn/Globe key on an Apple keyboard. Applying the following patch to your qmk repository creates a new keycode KC_GLOBE which can then be used in your keymaps.

Where is this from

This commit is updating @drashna's code from Nov 2023 to work with the Nov 2024 files.

How to

1. Apply the changes from this commit in full
2. Make sure rules.mk for your keyboard has KEYBOARD_SHARED_EP = yes or else Globe-E, Globe-Q etc. will not work.
3. Use KC_GLOBE in your keymap to define a key as the fn/Globe key and compile as normal.

Alternatively if you want to avoid patching the generated header file, replace step 1. above with:

1. Create thre new JSON file data/constants/keycodes/keycodes_0.0.4_basic.hjson from the commit above
2. Run qmk generate-keycodes -v 0.0.5 -o quantum/keycodes.h in the root of the repo to update the keycodes
3. Apply the change to tmk_core/protocol/report.h from the commit above

Caveats

This will not make the key behave fully like the key on an Apple keyboard. Specifically more is required if you want it to toggle between F1–F12 and controlling brightness etc. See @fauxpark's gist for the long details.

I have not upgraded to Seqoia yet so I am afraid I cannot say if Ctrl-Globe does anything for me. In general it seems like some features do not work unless you also change the ids of your keyboard to pretend to be one made by Apple (see @fauxpark link above).

As for your other question, GLB_T() would only be possible with substantial code changes to QMK I think. Well beyond my current level of understanding it.

Thanks for your answer. Yeah, we are far away from fully QMK-supported Apple fn/Globe modifiers. Let's hope that someday it will be done, but like you, this is well beyond my current knowledge.

Why could not it be part of qmk_firmware? or at least some PR?

It could be but I have no experience with what it takes to get QMK to accept changes.

That's a great feature, and I hope it will find its way into the main QMK branch. Now, a question: With MacOS Sequoia, I was able to successfully use some of the window management shortcuts, namely CTRL-GLOBE-F, CTRL-GLOBE-C, and CTRL-GLOBE-R, but I had no success with CTRL-GLOBE arrows and CTRL-SHIFT-GLOBE arrows.

Do you have the same experience, or is it just me?

I just upgraded and can confirm I see the same behavior as you. It is so puzzling that some work and some don't.

Another thing that works is getting the emoji dialog on a single Globe press.
I have created a branch with the change on my local fork, but of course, as soon as something changes in the upstream code, I'll have to re-apply it. (I had the same experience when trying to get the Fn to work. I ended up giving up and setting MacOS to recognize only the F-keys instead of the usual Apple key function.)

Why could not it be part of qmk_firmware? or at least some PR?

I've read somewhere that it is a matter of copyright, and QMK does not want to get involved in any legal dispute with Apple, which I can also understand. After all, it is a way for Apple to differentiate from the competition 😮‍💨

The key code being used is documented in Apple's official documentation. Nothing to worry about there. Going a step further and copying Apple's vendor or keyboard ids would potentially upset them but this patch does not do that.

Well, that's an idea. Let me consider how much effort that would require (there's documentation to be updated as much as code). If we don't go up to faking Apple's IDs but just implement a key, I could try to publish the fix in a pull request. But no promises and the maintainers could also object.

I've created a pull request with @lordpixel23 changes, only added a compilation flag and updated the documentation. Credit goes to @lordpixel23 and other contributors such as @fauxpark.
Now that it is done, I'll try to resolve all the kinks that will likely pop up with the pull request.

After all, it is a way for Apple to differentiate from the competition
Microsoft is also trying to introduce new key on the keyboard (as if Windows logo is not enough on the most keyboards in the world)

https://blogs.windows.com/windowsexperience/2024/01/04/introducing-a-new-copilot-key-to-kick-off-the-year-of-ai-powered-windows-pcs/

Lovely! I see there will be new keycodes to map in the future...

I followed the gist to modify my Keyboard(Keychron K10 Pro)'s config and it works in cable mode, but the globe key just failed in Bluetooth mode, that's strange.

@Ostrichbeta - I just ran into the same thing. I've mapped the globe key to a key on my Nuphy Halo96v2, it works as expected when it's connected via wire... but fails w/ Bluetooth or 2.4Ghz RF. Have you had any luck with this?

I've downloaded the Key Codes app from the Mac App Store to see the logged keypresses and they look identical between the Nuphy key in BT mode, the Nuphy key in wired mode, and when I press the real globe key on my MacBook Pro:

@Ostrichbeta - I just ran into the same thing. I've mapped the globe key to a key on my Nuphy Halo96v2, it works as expected when it's connected via wire... but fails w/ Bluetooth or 2.4Ghz RF. Have you had any luck with this?

I've downloaded the Key Codes app from the Mac App Store to see the logged keypresses and they look identical between the Nuphy key in BT mode, the Nuphy key in wired mode, and when I press the real globe key on my MacBook Pro:

I have the same problem with my nuphy air75_V2🙈

I followed the gist to modify my Keyboard(Keychron K10 Pro)'s config and it works in cable mode, but the globe key just failed in Bluetooth mode, that's strange.

I've modified the Keychron firmware for my Q60 Max, and the globe key works for both wired and bt (I just rechecked now to make sure). To be complete, I'm using their firmware on their wireless_playground branch which is my basis for the Q60.