Bug: Creating a correct local keymap for non-US MacOS keyboard (Finnish/Swedish)

[jussapaavo]

Requirements

• I've searched platform-specific issues, issues and discussions to see if this has been reported before.

Describe the bug

I am trying to setup Kanata but I'm struggling to get the initial defsrc config right on my Finnish/Swedish keyboard layout. When using the key codes based on telemetry from my OS. I don't understand what key codes I should use instead.

I'm using Toptal Key Codes and native Key Codes app on Mac to see what my keyboard broadcasts. Initially I tried to map these key codes by using deflocalkeys-macos but I quickly noticed these are very unintuitive and produces unexpected results.

For example, I have § key under esc and on the left side of 1.

Toptal browser events show it as:

{
 "key": "§",
 "keyCode": 192,
 "which": 192,
 "code": "IntlBackslash",
 "location": 0,
 "altKey": false,
 "ctrlKey": false,
 "metaKey": false,
 "shiftKey": false,
 "repeat": false
}

Native Key Codes app gives:

Character: §
Unicode: 167 & 0xa7
Keys: §
Key Code: 10 / 0xa
Modifiers: 256 / 0x100

I tried setting up (deflocalkeys-macos § 10) and expected it to work, but instead pressing the key produces m. When looking at /parser/src/keys/macos.rs I kinda understand why. Then I copied the keycodes from ISO German QWERTZ localization and somehow (deflocalkeys-macos § 86) works instead.

So using keycode 10 produces m but using the keycode 86 produces §. Where does the 86 come from?

Using the German layout as inspiration, I got the basic layout working. However, when moving to F-row and trying to configure the special keys like volume up and volume down keys, I'm facing the issue again.

When setting up vold as volume down key, it instead launches Mission control. Other F keys don't work either or trigger unexpected results. However, the native Key Codes app doesn't show telemetry for F-row special keys, so I cannot see what my buttons send nor can I figure out what key code should I use instead.

What is the best approach to map these key codes to correct values? When looking at the Kanata´s source code, I kinda understand why I get unexpected results, but I do not get what values I should I use instead.

So what would be the best approach to create a full localization for Swedish / Finnish keyboard layout?

Relevant kanata config

(defcfg
  process-unmapped-keys yes
  macos-dev-names-include (
    "Apple Internal Keyboard / Trackpad"
    "Magic Keyboard with Touch ID"
  )
)
(deflocalkeys-macos
  §    86
  ´    13
  ¨    27
  '    43
  å    26
  ä    40
  ö    39
  <    41
  -    53
)
(defsrc
  esc       f1   f2   f3   f4   f5   f6   f7   f8   f9   f10  f11  f12
  §         1    2    3    4    5    6    7    8    9    0    +    ´    bspc
  tab       q    w    e    r    t    y    u    i    o    p    å    ¨    ret
  caps      a    s    d    f    g    h    j    k    l    ö    ä    '
  lsft <    z    x    c    v    b    n    m    ,    .    -              rsft
  rctl lctl lalt lmet           spc            rmet ralt
)
(defvar
  tap-time 500
  hold-time 200
)
(defalias
  cap (tap-hold $tap-time $hold-time bspc f19)
  spc (tap-hold $tap-time $hold-time spc f19)
)
(deflayer base
  esc       brdn brup f3   f4   f5   f6   f7   f8   f9   mute vold volu
  lrld      1    2    3    4    5    6    7    8    9    0    +    ´    bspc
  tab       q    w    e    r    t    y    u    i    o    p    å    ¨    ret
  @cap      a    s    d    f    g    h    j    k    l    ö    ä    '
  lsft <    z    x    c    v    b    n    m    ,    .    -              rsft
  rctl lctl lalt lmet           @spc           rmet ralt
)

To Reproduce

1. Use Finnish / Swedish keyboard layout on a Macbook Pro
2. Setup deflocalkeys-macos according to Key Codes telemetry from your keyboard
3. Setup defsrc to use the local key map
4. Get unexpected key presses as a result

Expected behavior

Using the system key codes in deflocalkeys-macos would produce the expected key press for the keyboard.

Kanata version

kanata 1.6.1

Debug logs

No response

Operating system

MacOS Sonoma 14.4.1

Additional context

Finnish / Swedish ISO Keyboard layout

[jussapaavo]

Regarding the F-row special keys, I found a solution. It wasn't actually because of key codes, but instead noticed that Use F1, F2, etc. keys as standard function keys setting needs to be true for Kanata to recognize F-keys correctly. Now vold and volu work as expected.

However, I can create a better localization mapping for SWE/FIN keyboard layout and submit a PR, if there's someway to better verify the correct key codes?