copilot2ctrl

English | 日本語

A Linux kernel module to remap the Copilot key to a "RightCtrl" key.

Overview

This is a Linux kernel module that remaps the Copilot key found on "Copilot+ PCs" (sold since 2024) to the RightCtrl key.

Hardware-wise, the Copilot key simultaneously sends the keycodes LeftMeta + LeftShift + F23. Major Linux key remapping tools (such as keyd) may not correctly handle simultaneous key presses combined with other modifier keys (like LeftShift or LeftMeta) when processing this specific sequence.

copilot2ctrl accurately detects and replaces this sequence at the kernel level, achieving full RightCtrl functionality, including simultaneous presses with other modifiers.

Features

• Replaces only the input originating from the Copilot key with RightCtrl.
• Supports shortcuts such as LeftShift + Copilot (RightCtrl) + V.
• No user-space processes required.

Usage

Install Build Tools

To build the module, you need headers for the running kernel and build tools. On Ubuntu or Debian, you can install them as follows:

sudo apt update
sudo apt install build-essential linux-headers-$(uname -r)

Build the Kernel Module

Clone the repository and compile the kernel module using the following commands:

git clone https://github.com/penguin2716/copilot2ctrl.git
cd copilot2ctrl
make

Test the Module

Loading the kernel module will make the Copilot key function as RightCtrl (this is not persistent; it will revert to the original state after a reboot).

sudo insmod copilot2ctrl.ko

You can verify the status with sudo dmesg. You should see logs similar to the following. copilot2ctrl virtual keyboard is the virtual device used internally by this module.

[195385.876102] copilot2ctrl: connected
[195385.876172] input: copilot2ctrl virtual keyboard as /devices/virtual/input/input74
[195385.876241] copilot2ctrl: module loaded

To revert to the original behavior, unload the kernel module:

sudo rmmod copilot2ctrl

Checking sudo dmesg should show logs indicating the module has been unloaded:

[196447.947218] copilot2ctrl: disconnecting
[196447.985456] copilot2ctrl: module unloaded

Install the Module (Persistent)

Running the following command installs the built kernel module to /lib/modules/$(uname -r)/extra and creates /etc/modules-load.d/copilot2ctrl.conf so the module loads automatically at boot.

sudo make install

Uninstall the Module

To uninstall, run the following command. This removes /lib/modules/$(uname -r)/extra/copilot2ctrl.ko and /etc/modules-load.d/copilot2ctrl.conf.

sudo make uninstall

If you are currently running a different kernel version than the one used during installation, please manually remove the /lib/modules/<version>/extra/copilot2ctrl.ko file.

How it works

The Copilot key sends LeftMeta + LeftShift + F23. copilot2ctrl captures all events sent from the physical keyboard and sends them to the OS via a virtual keyboard provided within the module (this mechanism is similar to keyd). If the captured sequence matches the Copilot key combination, it issues a key event as RightCtrl from the virtual keyboard.

flowchart TD
   kbd[Physical Keyboard]
   module[copilot2ctrl.ko]
   vkbd[Virtual Keyboard]
   os[Operating System]

   kbd -- LeftMeta + LeftShift + F23 --> module
   module -- RightControl --> vkbd
   vkbd --> os[Operating System]

Loading

Notes

Secure Boot

Secure Boot is enabled by default on many modern PCs, including Copilot+ PCs. With Secure Boot enabled, attempting to load an unsigned kernel module will result in an error. You must either disable Secure Boot in the BIOS/UEFI settings or create a MOK (Machine Owner Key) to sign the module and register it with the system.

Kernel Updates

When the kernel version is updated, the kernel module needs to be rebuilt (make and sudo make install).