Apple "Globe key" modifier (Fn key) #947

dxmh · 2021-09-21T08:50:30Z

Apple now use an additional modifier key: "Globe"

The Globe key can be seen in the bottom left of this MacBook Air keyboard:

(The Globe key is now also standard on iPad keyboards, and Apple's new external keyboards for other Macs.)

The problem

It's not possible to send the Globe key with ZMK, but the Globe key is used heavily in recent versions of Apple operating systems.

Here are some keyboard shortcuts in iPadOS 15 that use the Globe key:

Go to Home Screen: Globe + H
Show App Library: Shift + Globe + A
Quick Note: Globe + Q
Siri: Globe + S
Control Center: Globe + C
Notification Center: Globe + N
App Switcher: Globe + Up Arrow
Next App: Globe + Left Arrow
Tile Window Left: Control (^) + Globe + Left Arrow
Tile Window Right: Control (^) + Globe + Right Arrow
Show Slide Over: Globe + Backslash
Move to Left Slide Over: Option (⌥) + Globe + Left Arrow
Move to Right Slide Over: Option (⌥) + Globe + Right Arrow
Source: https://www.imore.com/all-global-keyboard-shortcuts-ipad-ipados-15

I believe the Globe key is a repurpose/rebrand of Apple's own "Fn key" which has been around for a while. Apple's Fn key has its own keycode which is not usually available in custom keyboard firmware:

Unlike most Fn keys, the one on Apple keyboards actually has its own keycode... sort of. It takes the place of the sixth keycode in a basic 6KRO HID report -- so an Apple keyboard is in fact only 5KRO.

More information about the Apple Fn key can be found at https://beta.docs.qmk.fm/faqs/faq_keymap#fn-key-on-macos.

Workaround

Previously, when this key was purely Fn, it was possible to work around the inability to send Fn+8 for "Play/Pause" by instead sending the desired C_PLAY_PAUSE. However, these kinds of workarounds do not apply to Globe as there's no keycode for the desired result (e.g. "Tile Window Left").

Fortunately, Apple provides the ability to remap modifiers at the Operating System level on all their devices - it is possible for ZMK to send Caps Lock (&kp CAPS) and for the Apple OS to treat it as the Globe key.

Note that on an iOS/iPadOS device, accessing this settings pane can be troublesome (but not impossible) as discussed in #378.

The text was updated successfully, but these errors were encountered:

minjaep · 2021-09-25T15:01:10Z

So it is not an 'issue' as Apple wants to make it a proprietary key (maybe you need a license to implement it, as it seems like OS checks if the keyboard supports globe or not). I also have no problem using caps lock instead of globe.

dxmh · 2021-11-13T08:21:45Z

I also have no problem using caps lock instead of globe.

I find the main problem with this workaround is the inability to use capslock in modifier functions in the keymap.

For example: &kp LC(A) in the keymap sends LEFT_CONTROL+A, but I don’t believe it’s possible to do the equivalent for CAPSLOCK+A (GLOBE+A).

daaaaaaaaaniel · 2022-03-16T00:22:28Z

In QMK, there's a patch that enables the Apple fn key. https://gist.github.com/fauxpark/010dcf5d6377c3a71ac98ce37414c6c4. How far off are we from being able to do the same sort of thing in ZMK?

petejohanson · 2022-03-16T00:44:32Z

I am in full agreement with the QMK devs, we won't ever imitate a company's VID to enable a feature.

We would need to petition Apple to somehow add the VID we use to their allowed list, before bothering enhancing ZMK's HID layer to support this.

eytanhanig · 2022-09-23T05:20:09Z

we won't ever imitate a company's VID to enable a feature

They're over 15% of the market. Is there any legal reason we can't support this? It'd be unfortunate to punish users just because the OS vendor doesn't play well with others.

Hello9999901 · 2022-09-23T12:33:23Z

You can work around this by binding an unused key and remapping using hidutil on macOS. You can't do this on iPadOS, however.

petejohanson · 2022-09-24T15:09:16Z

we won't ever imitate a company's VID to enable a feature

They're over 15% of the market. Is there any legal reason we can't support this? It'd be unfortunate to punish users just because the OS vendor doesn't play well with others.

Users are welcome to override the VID and PID for their local builds. The project itself won't ever do this by default, that would open us up to lawsuits from Apple or the USB-IF, in theory.

The better way is to petition Apple to add our IDs, or change their software.

spencerthayer · 2023-02-05T20:04:29Z

How does Keychron get away with this?

tinydogio-joshua · 2023-02-15T13:45:29Z

How does Keychron get away with this?

Seems to be fn2 on all my Keychron devices.

mtskf · 2023-03-24T05:43:04Z

Not yet sorted?

or-agami · 2023-05-28T15:27:57Z

I find the main problem with this workaround is the inability to use capslock in modifier functions in the keymap.

For example: &kp LC(A) in the keymap sends LEFT_CONTROL+A, but I don’t believe it’s possible to do the equivalent for CAPSLOCK+A (GLOBE+A).

There is a workaround for using capslock in modifier functions?

marzelwidmer · 2023-07-30T16:59:14Z

I facing the same issues...my workaround to use F1 etc. (my default are on my MacBooks F1 with FN key) to switch it on the OS

macOS Ventura
Choose Apple menu  > System Settings.
Click Keyboard in the sidebar.
Click the Keyboard Shortcuts button on the right.
Click Function Keys in the sidebar.
Turn on “Use F1, F2, etc. keys as standard function keys”.

LandonSchropp · 2023-08-04T19:31:25Z

I'm using the function key workaround as well, but I wish we could support the globe character so that I could set consistent keyboard shortcuts between my laptop's keyboard and my Desktop keyboard.

Hello9999901 · 2023-08-04T21:47:22Z

Hey all, as Pete stated a year ago – "The project itself won't ever do this by default, that would open us up to lawsuits from Apple or the USB-IF, in theory."
Keychron shows up as an Apple keyboard (at least with lsusb), so I'm assuming they have some deal with Apple itself. Unfortunately, the tldr is that the Globe key will not be supported anytime soon (or ever). There are a variety of workarounds. My workaround uses hidutil and a little ways up the thread.
Just wanted to conclude some points of the discussion so far.

arabshapt · 2023-08-11T13:17:11Z

@petejohanson
Could you tell where and what needs to be changed? I am using zmk on kinesis360. Do I have to change some VID and PID in zmk project(build(docker image) of this project gets used by kinesis 360 repo) or kinesis360(where i have my layout)

ldebritto · 2023-09-13T13:49:25Z

I find the main problem with this workaround is the inability to use capslock in modifier functions in the keymap.
For example: &kp LC(A) in the keymap sends LEFT_CONTROL+A, but I don’t believe it’s possible to do the equivalent for CAPSLOCK+A (GLOBE+A).

There is a workaround for using capslock in modifier functions?

One could use a macro for that:

  caps_a: caps_a {
            label = "CAPS+A";
            compatible = "zmk,behavior-macro";
            wait-ms = <0>;
            tap-ms = <0>;
            #binding-cells = <0>;
            bindings
                = <&macro_press &kp CAPS>
                , <&macro_tap &kp A>
                , <&macro_release &kp CAPS>
                ;
        };

eytanhanig · 2023-09-14T04:34:00Z

The better way is to petition Apple to add our IDs, or change their software.

@petejohanson What are the next steps for starting this petition?

petejohanson · 2023-09-14T04:41:18Z

The better way is to petition Apple to add our IDs, or change their software.

@petejohanson What are the next steps for starting this petition?

Figure out how best to contact Apple,
Write up the petition, including a link to this issue,
Send it to Apple.

This issue is definitely not high on my list of priorities, so whoever is motivated to do the above is welcome to.

ReFil · 2023-09-20T18:48:21Z

I've successfully made globe key work on a zmk powered board. It doesn't use the fn key approach in that QMK patch, and doesn't require any changing of the VID/PID, it is simply a rarely used consumer keycode.

orand · 2023-09-20T20:16:23Z

Really? Are you the first person in the world to figure this out? If so, could you please elaborate? If not, where did you find how to do this?

ldebritto · 2023-09-20T21:03:11Z

I've successfully made globe key work on a zmk powered board. It doesn't use the fn key approach in that QMK patch, and doesn't require any changing of the VID/PID, it is simply a rarely used consumer keycode.

So you’re using this key code? C_AL_KEYBOARD_LAYOUT? Or have you created a new one to post this Usage ID?

ReFil · 2023-09-20T23:09:42Z

It's the 0x29D usage ID, I just added it to keys.h. it is specified in the apple accessory device specifications. There is no mention of the Fn key in said specification. It either uses the same code as the globe key or a proprietary method apple don't publish

arabshapt · 2023-09-20T23:17:01Z

I just added that line and then used it in my config(kinesis360). the key did not register in karabiner eventviewer

ReFil · 2023-09-20T23:43:22Z

Did you enable CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_FULL=y in adv360_left_defconfig

ldebritto · 2023-09-21T00:17:17Z

While it still does not register in Karabiner Event Viewer as fn, it does work with my keymap after also changing my .conf to include the CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_FULL=y line.

Should anyone want to reproduce, follow these steps:

Edit your .conf file in the config folder to include the following line

CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_FULL=y

Create a file in your config folder with the key definition. I've created the apple_globe.h file in my keymap folder with this single #define command:

/* Apple Globe key */
#define C_KEYBOARD_LAYOUT_SELECT (ZMK_HID_USAGE(HID_USAGE_CONSUMER, 0x029D))
#define GLOBE C_KEYBOARD_LAYOUT_SELECT
// As per PR 1938

Add the GLOBE key code to your keymap (mine is a &mt in the Z key)

&mt GLOBE Z

However it only seems to work if I have the keyboard connected via cable. When I use the keyboard connected via bluetooth, it just doesn't work.

So I guess there's still something else to change in keyboard settings.

Still, many thanks for that, @ReFil ! I guess that we're getting closer to a solution.

arabshapt · 2023-09-21T00:32:32Z

I tried with CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_FULL=y , still it did not work. It does not get registered... with wire or bluetooth

lesshonor · 2023-09-21T01:37:40Z

I tried with CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_FULL=y , still it did not work. It does not get registered... with wire or bluetooth

Complete shot in the dark: do you have NKRO enabled?

danieleavitabile · 2023-10-02T01:00:54Z

Thanks, if I understand correctly, I can just use the GLOBE code if I use GitHub actions for building the firmware

caksoylar · 2023-10-02T01:06:15Z

Yes, unless you changed config/west.yml file, it will always build using the latest version of ZMK.

LeonB · 2023-10-02T08:49:33Z

@ReFil very cool! Will this also be added to the Adv360 repo?

ReFil · 2023-10-02T09:04:45Z

Yes, this fix will be merged in with the 360 pro's next minor update

arabshapt · 2023-10-02T13:48:20Z

On Ipad the globe gets registered, but on mac it does nothing for me... When I disable "modify events" in karabiner for my external keyboard(kinesis 360) then I see in unknown events in karabiner something(see image). The actual fn-key on my mac gets registered as

{
  "type": "up",
  "name": {"apple_vendor_top_case_key_code":"keyboard_fn"},
  "usagePage": "255 (0x00ff)",
  "usage": "3 (0x0003)",
  "misc": ""
},

using 0x0003 instead of 029d did not help...

ReFil · 2023-10-02T13:50:55Z

What version of macOS are you using? It seems that your fn key is using the older custom usage page method

arabshapt · 2023-10-02T13:52:24Z

latest

updated yesterday

ReFil · 2023-10-02T13:57:08Z

That's odd, is the hardware recent too? I was able to get it to bring up the emoji screen on an m1 macbook pro which was the same thing the globe key on the integrated keyboard did. If your hardware is older it might explain it

arabshapt · 2023-10-02T13:58:50Z

m2 macbook. Does the following help?

arabshapt · 2023-10-02T14:00:11Z

That's odd, is the hardware recent too? I was able to get it to bring up the emoji screen on an m1 macbook pro which was the same thing the globe key on the integrated keyboard did. If your hardware is older it might explain it

that makes me hopeful

ReFil · 2023-10-02T14:01:06Z

Must admit i'm not too versed in apple stuff, I dont own or use a mac myself so had to borrow one for testing this. Everything there looks correct so i'm not sure why it wouldn't work, especially when it works on iPads

ReFil · 2023-10-02T14:06:18Z

Is it doing anything in the OS? as per this comment karabiner might not be able to detect it. Bear in mind it's possible the key is disabled in the MacOS keyboard settings

arabshapt · 2023-10-02T14:11:47Z

my normal built in keyboard opens emoji panel, but kinesis does not open anything. On my second mac(macbook 16 2019) the fn keycode is the same

{
  "type": "up",
  "name": {"apple_vendor_top_case_key_code":"keyboard_fn"},
  "usagePage": "255 (0x00ff)",
  "usage": "3 (0x0003)",
  "misc": ""
},

arabshapt · 2023-10-02T14:12:29Z

is replacing 0x029d with 0x00ff enough? how can I add this myself to test whether it works?

ReFil · 2023-10-02T14:16:17Z

Implementing the dedicated usage apple fn key is not trivial, are you trying this over USB or bluetooth?

arabshapt · 2023-10-02T14:18:05Z

both. I could do the same thing you did in your PR or do you mean even more work than that?

ReFil · 2023-10-02T14:20:24Z

It would be a lot more work to implement, where's your config repo? I can have a look to ensure the keyboard is correctly configured?

arabshapt · 2023-10-02T14:24:01Z

here it is: https://github.com/arabshapt/Adv360-Pro-ZMK/tree/v3.0/config

ReFil · 2023-10-02T14:26:15Z

at first glance this line shouldn't be there, if you're using full consumer usage it supercedes basic https://github.com/arabshapt/Adv360-Pro-ZMK/blob/1f5cc43ae89a16c9079f128913104f81f2520c9a/config/boards/arm/adv360/adv360_left_defconfig#L64C27-L64C27

arabshapt · 2023-10-02T14:41:58Z

thank you, I commented it out)

ReFil · 2023-10-03T10:07:33Z

It seems like the GLOBE keycode does not provide the full functionality of the globe/fn keys present on official apple keyboards, but does provide some of the functionality, With this in mind it might be worth reopening the issue or opening a new issue specifically about the Fn functionality

zmkfirmware/zmk#947 (comment)

ickc · 2023-10-24T20:20:31Z

I can confirm that the GLOBE keycode here is more limited than actual GLOBE key from Apple. I tried it on iPad Pro 12.9" 6th gen model with iPadOS 17.0.3, and it is working as expected (e.g. GLOBE key changes input sources.) But on the Macbook Pro 16" 2021 model with macOS Sonoma 14.0 (23A344), the GLOBE has no effects (e.g. it does not change input sources.)

Remapping in System Preferences > Keyboard > Keyboard Shortcuts... > Modifer Keys > Caps Lock to Globe gives full Globe/Fn functionality instead.

Also, in order to use the GLOBE keycode on Advantage 360, you need to follow #947 (comment) and set CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASIC=n. I don't think it is documented yet in the Adv360 repo.

r4zendev · 2023-11-26T21:57:44Z

Facing this problem on Monterey 12.5, Air m2 2023, Glove80, configuring via their online tool. Any suggestions? The key seems totally unresponsive, even fn+bksp does not work. Combinations like fn+c, fn+e obviously don't work as well.

ReFil · 2023-11-26T21:59:48Z

The keycode only works for the globe function, not the fn function of the key

r4zendev · 2023-11-26T22:08:59Z

@ReFil FWIW globe function does not work for me as well. It does not toggle the languages either.
Are there any currently available solutions for the fn key though? That's what I'm looking for primarily.

FOR ANYONE ELSE STOPPING BY:
I've found a solution by remapping the globe key through Karabiner-Elements (a piece of software I use for a bunch of other things) to F13 or whichever key that is not used in your main layout, and then using this key for globe key functionality. Works good for me, might work for others.

vodrazka · 2024-04-10T18:33:11Z

Just to confirm, i've did what @r4zendev suggested, this works to have "fn" on any custom keyboard.
In karabiner-elements I set "capslock" to "fn".

dxmh mentioned this issue Sep 21, 2021

iOS Crashes in Modifier Keys page in Settings App #378

Open

dxmh changed the title ~~Apple "Globe key" modifier~~ Apple "Globe key" modifier (Fn key) Nov 27, 2021

ReFil mentioned this issue Sep 20, 2023

feat(hid): Add apple globe keycode #1938

Merged

caksoylar closed this as completed Oct 2, 2023

ReFil mentioned this issue Oct 2, 2023

Add GLOBE to keymap KinesisCorporation/Adv360-Pro-ZMK#240

Closed

ickc added a commit to ickc/Adv360-Pro-ZMK that referenced this issue Oct 24, 2023

CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASIC=n

fd50605

zmkfirmware/zmk#947 (comment)

u1735067 mentioned this issue Oct 31, 2023

[BadUSB Feature Request] Is there a way use the iPadOS "globe" key? flipperdevices/flipperzero-firmware#3089

Open

Apple "Globe key" modifier (Fn key) #947

Apple "Globe key" modifier (Fn key) #947

Comments

dxmh commented Sep 21, 2021 • edited

The problem

Workaround

minjaep commented Sep 25, 2021 • edited

dxmh commented Nov 13, 2021 • edited

daaaaaaaaaniel commented Mar 16, 2022

petejohanson commented Mar 16, 2022

eytanhanig commented Sep 23, 2022

Hello9999901 commented Sep 23, 2022

petejohanson commented Sep 24, 2022

spencerthayer commented Feb 5, 2023

tinydogio-joshua commented Feb 15, 2023

mtskf commented Mar 24, 2023

or-agami commented May 28, 2023

marzelwidmer commented Jul 30, 2023

LandonSchropp commented Aug 4, 2023 • edited

Hello9999901 commented Aug 4, 2023

arabshapt commented Aug 11, 2023 • edited

ldebritto commented Sep 13, 2023

eytanhanig commented Sep 14, 2023

petejohanson commented Sep 14, 2023

ReFil commented Sep 20, 2023

orand commented Sep 20, 2023

ldebritto commented Sep 20, 2023

ReFil commented Sep 20, 2023

arabshapt commented Sep 20, 2023 • edited

ReFil commented Sep 20, 2023

ldebritto commented Sep 21, 2023

arabshapt commented Sep 21, 2023 • edited

lesshonor commented Sep 21, 2023

danieleavitabile commented Oct 2, 2023

caksoylar commented Oct 2, 2023

LeonB commented Oct 2, 2023

ReFil commented Oct 2, 2023

arabshapt commented Oct 2, 2023

ReFil commented Oct 2, 2023

arabshapt commented Oct 2, 2023

ReFil commented Oct 2, 2023

arabshapt commented Oct 2, 2023 • edited

arabshapt commented Oct 2, 2023

ReFil commented Oct 2, 2023 • edited

ReFil commented Oct 2, 2023

arabshapt commented Oct 2, 2023

arabshapt commented Oct 2, 2023

ReFil commented Oct 2, 2023

arabshapt commented Oct 2, 2023

ReFil commented Oct 2, 2023

arabshapt commented Oct 2, 2023

ReFil commented Oct 2, 2023

arabshapt commented Oct 2, 2023

ReFil commented Oct 3, 2023

ickc commented Oct 24, 2023

r4zendev commented Nov 26, 2023

ReFil commented Nov 26, 2023

r4zendev commented Nov 26, 2023 • edited

vodrazka commented Apr 10, 2024

dxmh commented Sep 21, 2021 •

edited

minjaep commented Sep 25, 2021 •

edited

dxmh commented Nov 13, 2021 •

edited

LandonSchropp commented Aug 4, 2023 •

edited

arabshapt commented Aug 11, 2023 •

edited

arabshapt commented Sep 20, 2023 •

edited

arabshapt commented Sep 21, 2023 •

edited

arabshapt commented Oct 2, 2023 •

edited

ReFil commented Oct 2, 2023 •

edited

r4zendev commented Nov 26, 2023 •

edited