Tunney
April 10, 2025, 2:40pm
1
Is there a scancode for the apple language key?
0xTJ
April 10, 2025, 5:10pm
2
I don’t personally use a Mac, and it’s been a long time since I looked much at USB HID, and I can’t personally verify anything here, but it seems that the Globe key (same as Fn, depending on the layout) is special and not just a normal scancode. From:
opened 12:11PM - 20 Dec 17 UTC
closed 03:45PM - 22 Oct 18 UTC
enhancement
discussion
_I've made this an issue instead of a PR because it probably warrants some discu… ssion on whether or not to add this feature into QMK, but either way I think it's a good idea to at least put it in the documentation in the event that it's not implemented, so that anyone sufficiently determined can at least get some pointers on how to do so on their own. Anyway..._
I wanted to see if I could get QMK to send the infamous "Apple Fn" key. It turns out I can, and it's fairly simple.
First of all, I discovered this interesting Xcode project called [HID Explorer](https://github.com/shiroholloway/HID-Explorer), which details all of the usage pages and usages of all your HID devices, and shows their current values. You may want to be somewhat familiar with Xcode and Objective-C to use it, though -- I had to do a little fiddling to get it to compile. Someone should really fork this and patch it up!
If you look at an Apple keyboard in HID Explorer, you can see that right at the bottom of the list is a strange entry: page `0xFF`, usage `0x03`. This just so happens to correspond to the usage page `AppleVendorTopCase` and the usage `KeyboardFn`, which Apple has kindly [documented for us](https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-870.60.4/IOHIDFamily/AppleHIDUsageTables.h.auto.html). Sure enough, pressing the Fn key causes the value of this usage to become `1`.
You can also see the keyboard is indeed 5KRO as has been mentioned in [previous discussions](https://deskthority.net/workshop-f7/host-computer-s-awareness-of-layer-keys-t5768.html) on this key. The reason for this is because the keyboard report has an extra field for the Fn key, which _replaces_ the sixth keycode:
|Byte|0 |1 |2 |3 |4 |5 |6 |7 |
|----|----|--------|--|--|--|--|--|--|
| |Mods|Reserved|1 |2 |3 |4 |5 |Fn|
But it doesn't _have_ to take up a keycode slot. Because the report descriptor tells the host how to interpret the report, we can just repurpose the reserved byte for the Fn key field and it will work perfectly fine, at least within macOS. I don't know why Apple didn't just do this considering it doesn't have to deal with old BIOSes.
So, I set about replacing the declaration of the reserved byte with the Fn key descriptor elements. Then, I created a new action, `ACT_APPLE_FN`, and a new keycode `KC_APPLE_FN` and glued it all together, with an additional check in `add_key_to_report()` and `del_key_from_report()` so that they modify `keyboard_report->reserved` instead. In my keymap I added `KC_APFN` and `KC_F3`, compiled & flashed, and wouldn't you know it, I can toggle Exposé!
[Here is the diff](https://gist.github.com/fauxpark/010dcf5d6377c3a71ac98ce37414c6c4) - it's only a proof of concept, but IMO it's pretty minimal.
**But there's a catch. And it's a big one.** The keyboard's vendor and product ID need to match those of a real Apple keyboard -- probably only ones with a Fn key. The product ID also seems to determine whether certain F-keys work eg. Launchpad/Mission Control and keyboard backlighting. The Manufacturer and Product strings can still be whatever you like, but this explains why there are no third-party keyboards with Apple Fn keys, and most likely rules out QMK compatible PCB/keyboard sellers from shipping boards with the key available out of the box too. I can imagine that being a bit of a dealbreaker.
Lastly, something funny I discovered: with my WASD V2 in Mac mode, it shows up in HID Explorer with the Fn key usage. When you press 6 keys at once, the value of this "Fn key" becomes the keycode of the sixth key! It looks as if WASD simply copied and pasted the report descriptor from a real Apple keyboard, but kept the same report format. So you still only get 5KRO in Mac mode, and the Fn key also does not trigger, because the vendor and product IDs are not Apple's.
it takes up a special place in the 6th scancode slot, while also having a vendor-specific HID page for it.
And the biggest killer is that it apparently will only work with an appropriate VID/PID for the Apple keyboards.
It does seem like the Globe can be remapped to another key, so picking some existing scancode and mapping it to that seems like an option (though I can’t verify that).
1 Like