m m -
d e v

Android Bluetooth Keyboard Mapping

3 minute read

Finding and editing `keylayout` files on modern Android (with root).

I use Bluetooth keyboards with Android a lot, and often want to remap keys (eg swapping CAPS_LOCK to CTRL_LEFT).

Maybe it’s a failing in my search technique or I’m doing something that nobody else does nowadays, but whenever I search for info about this I find really old articles with out-of-date info, or just links to apps. To be fair Key Mapper is good and I do use it, but sometimes I just want to be able to do it at a system level without requiring extra apps.

To remap keys in Android, you need to edit a particular keylayout *.kl file, specific to the device (eg Bluetooth keyboard) you want to re-map. The files have names like Vendor_04e8.kl. The name is derived from various properties of the device, such as vendor ID, product ID and other things as explained here in the Android docs.

The sticking point for me, for ages, was that I had trouble finding the vendor and product codes and, consequently, the correct file to edit. In Linux I’d use lsusb or bluetoothctl or something like that, but on Android even in the wonderful Termux, these things don’t work properly for reasons I haven’t completely wrapped my head around, related to security and/or the way Android and its underlying Linux kernel inter-relate.

Problem 1: Finding which keylayout file needs to be edited

  • In Termux or whichever shell/terminal you use, do su to log in as superuser
  • Do dumpsys and wait for it to finish. It can take a while (couple of minutes on some of my devices)…
    If I don’t do this step, on some devices the next step doesn’t work… I hate this kind of situation as I have no idea why this should work and it feels nonsensical, but all I know is it fixed the problem when I encountered it.
  • Do dumpsys input to narrow the output
    Even this input-specific command outputs quite a lot. I tend to just take my time and scroll through it, but you can make it easier by trying something like:
    dumpsys input | grep -i -A12 bluetooth
    • The -i means case-insensitive
    • The -A12 means show the matching line plus the 12 lines After it
    • You may want to tweak the number but for me 12 was good
  • In the output, look for a description for your device (mine is Device 45: Bluetooth 3.0 Keyboard), and soon after that you’ll find a line like KeyLayoutFile: /system/usr/keylayout/Vendor_04e8.kl — that’s the *.kl file you need to edit to remap your keyboard

Problem 2: Editing system files on modern Android

On modern versions of Android, even if you have root, it’s not possible to directly edit files in the /system/ directory (it is mounted as read-only).

The way around this is to make a Magisk module. This is simpler than it might sound. The basic idea is that you create a folder in /data/adb/modules, (eg in my case I use mm, so /data/adb/modules/mm/). Inside that folder, you can create files and folders which Magisk will overlay onto the system at boot time, eg:

/data/adb/modules/mm/system/usr
# becomes
/system/usr

/data/adb/modules/mm/system/usr/keylayout/Vendor_04e8.kl
# becomes
/system/usr/keylayout/Vendor_04e8.kl

Now you can edit the keylayout file to make your changes, eg to change CAPS_LOCK to CTRL_LEFT on my keyboard it’s:

# key 58    CAPS_LOCK
key 58    CTRL_LEFT

Other apps which might be useful

Depending on your Android device and software version, it can be difficult/confusing to find the right key codes. I find that one or another of the apps below usually gets me what I need: