feat(hid): Add apple globe keycode

[ReFil]

Adds the globe keycode C_KEYBOARD_LAYOUT_SELECT, This might also act as the Fn key, it's not something I have tested. Should partially or fully solve #947

[caksoylar]

I think you'll need to update a few more spots, see #1386 as an example.

[ReFil]

Sorted, I also added an extra alias to the keycode so it can be called with GLOBE

[caksoylar]

LGTM, one question about the OS support fields.

[petejohanson]

One comment on the naming choice for the long form of the key.

[ReFil]

Yep you're right, all sorted now

[danieleavitabile]

Total newbie here. I don't know if I am misusing this, but I have tried today to test this here, I have just added a GLOBE modifier to line 58 of the https://github.com/danieleavitabile/zmk-config/blob/test-globe-button/config/splitkb_aurora_corne.keymap file. My GitHub Action was not successful. Any ideas about what I'm doing wrong?

[SethMilliken]

Total newbie here. I don't know if I am misusing this, but I have tried today to test this here, I have just added a GLOBE modifier to line 58 of the https://github.com/danieleavitabile/zmk-config/blob/test-globe-button/config/splitkb_aurora_corne.keymap file. My GitHub Action was not successful. Any ideas about what I'm doing wrong?

GLOBE is not (yet?) a full-fledged modifier and does not have a corresponding modifier function, so you can't use it the way you did here (i.e. &kp GLOBE(BSPC)). I think the best you can do right now is either use it in a hold-tap with &kp as both bindings, or define a macro that presses GLOBE, taps the key you want to use with it, and then releases GLOBE.

[SethMilliken]

@danieleavitabile Here is a parameterized macro that you can use like so: &glo BSPC

macros {
    glo: glo {
      compatible = "zmk,behavior-macro-one-param";
      label = "globe pseudo mod func";
      #binding-cells = <1>;
      bindings
          = <&macro_press &kp GLOBE>
          , <&macro_param_1to1>
          , <&macro_tap &kp MACRO_PLACEHOLDER>
          , <&macro_release &kp GLOBE>
          ;
    };
};

Just put this inside your / { node (or add the macro to your existing ones if you have them).

[danieleavitabile]

Thanks! I am just testing this non-parametrised macro, and I'll try to understand how your one works too

      fwd_bspc: fwd_bspc {
          label = "fwd_bspc";
          compatible = "zmk,behavior-macro";
          #binding-cells = <0>;
          bindings
              = <&macro_press &kp GLOBE>
              , <&macro_tap &kp BSPC>
              , <&macro_release &kp GLOBE>
              ;
      };

[danieleavitabile]

Hi @ReFil I have tried both my macro and the one proposed by @SethMilliken, and the GLOBE button does not seem to work for me. The latest working compilation can be seen here: the macro is at line 90 of the da-include file, and it is called in line 58 of the keymap file.

The button behaves as an ordinary backspace. Am I doing something wrong, can I help testing this? I am on a 13inch 2018 MacBook Pro running macOS Ventura.

[caksoylar]

Does sending the combo manually via a dedicated &kp GLOBE key work?

[SethMilliken]

@danieleavitabile Didn't see the forest for the trees for your particular binding. It sounds like you may just want &kp DELETE.

[SethMilliken]

Does sending the combo manually via a dedicated &kp GLOBE key work?

It does not.

[danieleavitabile]

@danieleavitabile Didn't see the forest for the trees for your particular binding. It sounds like you may just want &kp DELETE.

thanks for this, you can't imagine how much time I have spent waiting for the globe function to be implemented... Having said that, anything I can do to help testing the actual GLOBE button? It's also useful for other mappings

[ReFil]

It seems like it doesn't work for all users which is odd

[ReFil]

Have you enabled CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_FULL=y in your defconfig or conf file? You will also need to remove any CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASIC=y line

[SethMilliken]

Here are my findings of the behavior on macOS Sonoma 14.0 with a MacBook Pro 16-inch, 2021 (M1 Pro). For the behaviors that do not work, I verified that they do work correctly using the Globe key on the built-in keyboard.

• ZMK GLOBE does work correctly with various default bindings:
  • Globe-n
  • Globe-q
  • Globe-h
  • Globe-e
  • Globe-f
• Does not work with Globe-Backspace (behaves as BSPC instead of DELETE).
• Similarly, does not transform arrow keys into navigation cluster (PgUp, PgDn, Home, End).
• Karabiner-EventViewer does not show anything in the Main events when GLOBE is pressed; in Unknown Events, shows:

 {
   "value": "1",
   "usagePage": "12 (0x000c)",
   "usage": "669 (0x029d)"
 },
 {
   "value": "0",
   "usagePage": "12 (0x000c)",
   "usage": "669 (0x029d)"
 }

• Changing the VID and PID of the ZMK keyboard to match the internal Apple keyboard did not affect any of this.
  • CONFIG_USB_DEVICE_VID=0x05AC
  • CONFIG_USB_DEVICE_PID=0x0343
• Changing the VID and PID of the ZMK keyboard to match an Apple Magic keyboard did not affect any of this.
  • CONFIG_USB_DEVICE_VID=0x05AC
  • CONFIG_USB_DEVICE_PID=0x0267
• The presence of CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_FULL=y does not affect any of this (and CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASIC not set anywhere).
• Remapping Option key on the ZMK keyboard to Globe in System Settings, Option behaves the same as the ZMK GLOBE key, i.e. works with basic default bindings, but not as a modifier for backspace or arrow keys.

[ReFil]

Thanks for the feedback, It's very unusual that it works for some combinations but not others. Does the built-in globe key show up in karabiner?

[SethMilliken]

Yes, here are the Karabiner-EventViewer down/up events for the built-in keyboard key:

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

[ReFil]

hmm that's the old custom usage page fn key implementation. I wonder if the navigation keys and delete key are fn+key rather than globe+key. I dont know how the standard keyboard can tell when to send fn and when to send globe. I dont think there's anything that can be done on the fn key side as that still has the original issue of having to change the vid and pid.

[SethMilliken]

Another interesting quirk is that if you bring up the system keyboard viewer, it correctly shows the modified keys on the keymap when you press the ZMK GLOBE key:

[ReFil]

Why do Apple do these things haha, how hard would it have been to have a dedicated keycode for their fn key that just does all the fn behaviours. This, their changing Bluetooth settings every other update and trackpad compatibility is just maddening 😅

[caksoylar]

Thank you for the investigation @SethMilliken ! I think given this information (and assuming there isn't a solution from ZMK side) we should document this in the codes section of the documentation.

[ReFil]

Is there a standard place to document keycode specific quirks? happy to write up what this keycode can and can't do on a mac

[nickcoutsos]

There's the footnotes section, e.g.

footnotes: {
      ios: ["iosApplication"],
    }

which seems to involve an entry in https://github.com/zmkfirmware/zmk/tree/main/docs/docs/codes/_footnotes but all of the existing ones and the guidelines in the example suggest that it should probably be kept short. I'm not sure where it would make sense to break out into more detail.

[caksoylar]

@nickcoutsos is right, see the instructions here: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/codes/_footnotes/example.mdx

Looks like a few pieces are needed to get it working:

• Footnote itself at https://github.com/zmkfirmware/zmk/blob/main/docs/docs/codes/_footnotes/macos-power.mdx
• Expose it from footnotes.js https://github.com/zmkfirmware/zmk/blob/main/docs/src/data/footnotes.js
• Refer to it in hid.js https://github.com/zmkfirmware/zmk/blob/main/docs/src/data/hid.js#L2697

I don't think it would be a big deal if it was a few sentences. I think we should mention this:

• It doesn't exactly replicate the key on an Apple keyboard but provides similar functionality to being mapped to another modifier in System Settings. Perhaps we can link to this comments for details: feat(hid): Add apple globe keycode #1938 (comment)

The full consumer page restriction (and NKRO given it seems to be buggy atm) should also be mentioned but I think that should be a separate footnote. I would love to put it in other similar keycodes if we can exactly figure out which don't work with the basic usage page, but that should be a separate change.

[ReFil]

Ace, thank you both very much, I'll try and bash it out asap to prevent lots of user confusion

[ldebritto]

I believe an improvement on this matter could be done if we could use GLOBE as a proper mod in ZMK in keybindings (as in &kp GL(H) to perform GLOBE+h. AFAIK it can only be used as a regular key bind for &kp, &tog, &sk, but will not work in behaviors as a mod (as in mod-morphs).