Remapping keys with `hidutil` on MacOS

readme.md

Remapping keys with hidutil

My keyboards fn key is on the right side rather than the left, and my mac isn’t registering my right-fn key presses at all, so I basically don’t have a fn key. I hardly use my right-ctrl key, so I remapped it to fn with hidutil:

# Get current key mapping
$ hidutil property --get "UserKeyMapping"
(null)

# Remap right_control --> fn
$ hidutil property --set '{"UserKeyMapping":[{"HIDKeyboardModifierMappingSrc": 0x7000000E4, "HIDKeyboardModifierMappingDst": 0xFF00000003}]}'

# Now we see a populated mapping
$ hidutil property --get "UserKeyMapping"
(
        {
        HIDKeyboardModifierMappingDst = 1095216660483;
        HIDKeyboardModifierMappingSrc = 30064771300;
    }
)

# You can clear any mappings with:
$ hidutil property --set '{"UserKeyMapping":[]}'

And now I have a working fn key 🎉

Persisting it through reboots

The above won't last through a reboot, however. To make it stick, I created a launch agent that runs at load. See attached plist definition.

# Load definition into launchd
$ launchctl bootstrap gui/${UID}/ ~/Library/LaunchAgents/com.${USER}.reMapRightCtrl

# Turn it on
$ launchctl enable gui/${UID}/com.${USER}.reMapRightCtrl

# Run it once, immediately
$ launchctl kickstart gui/${UID}/com.${USER}.reMapRightCtrl

Finding the key codes

• https://developer.apple.com/library/archive/technotes/tn2450/_index.html
• https://gist.github.com/MightyPork/6da26e382a7ad91b5496ee55fdc73db2
• https://github.com/amarsyla/hidutil-key-remapping-generator/blob/52b3ab9e/src/helpers/keys.js
• https://hidutil-generator.netlify.app

com.andelink.reMapRightCtrl.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.andelink.reMapRightCtrl</string>

    <!-- launchctl print gui/${UID}/com.${USER}.reMapRightCtrl -->
    <!-- launchctl enable gui/${UID}/com.${USER}.reMapRightCtrl -->
    <!-- launchctl bootstrap gui/${UID}/ ~/Library/LaunchAgents/com.${USER}.reMapRightCtrl -->
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/hidutil</string>
        <string>property</string>
        <string>--set</string>
        <string>{
            "UserKeyMapping": [
                {
                    "HIDKeyboardModifierMappingSrc":0x7000000E4,
                    "HIDKeyboardModifierMappingDst":0xFF00000003
                }
            ]
        }</string>
    </array>

    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>