The Apple Fn Key

[fauxpark]

I've made this an issue instead of a PR because it probably warrants some discussion 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, 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. 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 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 - 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.

[skullydazed]

This is very cool, but I don't know how we possibly include this. Leaving this open to discus the possibility for now.

[drashna]

@skullydazed Short of maybe a feature option that overrides the normal 6KRO code. (eg "APPLE_NKRO", maybe).

But not sure how Apple would feel about us doing that, given that we have to use their VID and PID to get this working.

[fauxpark]

There would have to be some kind of warning if the feature is enabled, reminding users that it won't work unless they change their VID/PID - putting those values into the repo, even for checking, is probably a bad idea. I can see this may not be very "QMK".

I've also found that the PID can determine functionality amongst Apple keyboards - on my 2011 MBP, the F4 key has a little gauge symbol on it and opens the Dashboard. On my 2017 MBP it has a different symbol, and opens Launchpad.

QMK is meant to be customised though, even if you can't push your cool "Apple" keyboard back to the repo, we should at least be able to say that it is technically possible.

[jsoltren]

I noticed that matias keyboards offer a Mac version with an fn key. So I picked up a matias wired aluminum keyboard, plugged it into my Mac, and checked out what happened.

This is really interesting:

`Matias Wired Keyboard:

Product ID: 0x024f
Vendor ID: 0x05ac (Apple Inc.)
Version: 1.91
Serial Number: FK318VUS
Speed: Up to 12 Mb/sec
Manufacturer: Matias Keyboard
Location ID: 0x14210000 / 16
Current Available (mA): 500
Current Required (mA): 100
Extra Operating Current (mA): 0`

Looks like they just straight up lie about their Vendor ID. 0x024f is not a known Apple product ID, in that it doesn't appear in pci.ids:

https://usb-ids.gowdy.us/read/UD/05ac
http://www.linux-usb.org/usb.ids

[Syzygies]

Karabiner Elements can remap arbitrary keys to mission_control, launchpad, or other Mac uses for function keys.

It is good engineering to choose the right layer in which to work. I'm constantly revising VSCode-specific key mappings as I work, by editing a CSV file that updates Karabiner via Goku, and an on-screen crib sheet. One wants one's keyboard firmware to be fully functional in case a software layer like Karabiner isn't present, but it makes no sense to be reflashing a keyboard's firmware all the time. Rather, you're here to design a keyboard you can live with. So involving Karabiner is a good thing. For example, it can implement tap or hold without a timer, so the key fires on key-up no matter what the delay, if it isn't used as a modifier. I haven't figured out how to do this yet in QMK.

I use the Mac function key internally in Karabiner, as a modifier flag for internal use that I can be sure no application is expecting. I won't be using that trick with QMK. However, the Mac also equivalences left and right modifiers, so no app can be looking for both left control and right control, for example. This is another way that QMK can set modifiers to be trapped by Karabiner, without interfering with any downstream app. Karabiner sees the left, right distinctions, but apps don't.

[jsoltren]

Karabiner Elements does its remapping with a kernel driver. It's the "right" way, inasmuch as having to hack the kernel to work around the USB stack is considered right.

Apple is constantly trying to clamp down on kernel development. Karabiner Elements was itself a rewrite of Karabiner. In that regard QMK is more "stable" across OSes.

[Syzygies]

I'm likely to contribute to QMK once I get my sea legs. Yes, there was a lapse without Karabiner, and Apple is warning again of impending changes to kexts.

The "Oryx" key on an ErgoDox EZ or Planck EZ sets up two-way communication with QMK firmware. It would be ideal to continually tweak key macros on the fly, through a program that helped the user as the Oryx trainer does, without having to either reflash the keyboard or rely on kexts. The Proton C, for example, certainly has the memory and processing power. I can live without mission_control, and I'd love not to be worried about the future of kexts.