Help

Why don't my keymaps work outside the app but they do work when the app is open?

Disable all battery and memory optimisation features on your device. If you have a Xiaomi device enable "no battery restrictions" for this app.

Why aren't buttons on my Bluetooth device detected?

Many Bluetooth devices (like headphones) don't work unfortunately. Bluetooth keyboards work most of the time.

Why doesn't the app open in DEX mode?

Samsung Dex doesn't allow apps with a 3rd party keyboard to open while in Dex mode. You can still configure key maps while out of Dex mode and your key maps which don't require the Key Mapper keyboard will still work in Dex mode.

Why don't my volume buttons work when I press them?

Give the app Do Not Disturb access in your device settings. At the top of the homescreen in the Key Mapper app there is a "Fix" button to do this.

Why aren't my mappings working?

If you have made sure they are enabled and they have a trigger, restart the accessibility service by turning it off and on again (help below). If that doesn't work, report an issue (bottom of this page) to the developer describing your configuration (e.g the chosen action, trigger, Android version and your device/ROM).

Why doesn't the app uninstall?

You have probably enabled the app's device administrator in your device's settings. To uninstall the app, you must turn it OFF. The location of the device admin settings page varies widely on devices but on skins close to stock-Android it is under "Security" -> "Device admin apps".

How do I enable the accessibility service?

Open the Key Mapper app and click “Fix”, where it says, “the accessibility service must be enabled”. If that doesn’t work…

1. Open your device Settings app.
2. Find and open the “Accessibility” section. On some devices it might not be on the main screen and is sometimes under “System”.
3. Click the Key Mapper listing.
4. Press the switch to enable the Key Mapper accessibility service.

If there isn't an Accessibility settings page on your device, follow the instructions below to give the app permission to write to secure settings.

How do I give the app WRITE_SECURE_SETTINGS permission?

If your device is rooted, Key Mapper can grant itself the permission by enabling the "Key Mapper has root permissions" toggle in the settings.

If your device isn't rooted...

1. Enable developer options on your device by going to device Settings -> About Phone and tapping Build Number many times until it says you've enabled developer options. The location of the Build Number may vary between devices.
2. Enable USB Debugging in developer options and plug your device into your PC.
3. Download the Android SDK platform tools from here and unzip it.
4. Open a terminal/command prompt in the unzipped folder.
5. Type adb devices and your device should show up in the list after you click the prompt on your phone to allow USB debugging from your PC.
6. Type adb shell pm grant io.github.sds100.keymapper android.permission.WRITE_SECURE_SETTINGS. The package name is io.github.sds100.keymapper.ci for CI builds.
7. You can now enable the accessibility service and choose the Key Mapper keyboard without going into the Android settings. This permission persists across reboots and needs to be granted everytime you install the app. More features which rely on this permission will come in the future. 😀

Why can't I use the on screen keyboard with the Key Mapper keyboard?

Some users have wondered why they can't use the on-screen keyboard while using the Key Mapper keyboard and this is why... I originally made the app so I could map the keys on my Bluetooth keyboard to the correct characters since it was made for an iPad. A limitation of Android is an app can only input characters and keys if it is the SELECTED input method, which is why the Key Mapper keyboard needs to be chosen to use the Keycode, Key and Text actions. I didn't design it to have an on-screen keyboard since I would be using the physical keyboard anyway. But after multiple requests and suggestions I have decided to implement the AOSP keyboard into the Key Mapper keyboard at some point. This is also why there are a few settings controlling when to show the keyboard, since I wanted to make switching between the on-screen keyboard and the Key Mapper keyboard seamless.

Why aren’t the “Keycode”, “Key” and “Text” actions working?

The Key Mapper keyboard must be enabled in your device settings and chosen as the active keyboard.

To enable the keyboard:

Open the Key Mapper app and click "Fix" where it says, "the keyboard must be enabled". If that doesn't work…

1. Open your device Settings app.
2. Find and open the “Languages and Input” section. On some devices it might not be on the main screen and is sometimes under “System”.
3. Click on “Key Mapper Keyboard” to enable the keyboard. The toggle may be hidden under sub-menus on some devices.

To choose Key Mapper as the active keyboard: ⌨️

1. Click on the “Choose keyboard” (“Choose input method” on older devices) notification. Or you can click "Choose Keyboard" by opening the menu at the bottom of the home screen within the app.
2. Click “Key Mapper Input Method”.

How do I go back to my default keyboard?

Change the active keyboard as described above to your preferred keyboard.

Why isn’t the Key Mapper “choose keyboard” notification working?

For Android 8.1 and newer root is required since Google has blocked the ability for apps to open the input method picker outside of the app. If your device isn’t rooted, Use the Android system's “Change keyboard” notification instead.

Volume increases to max/minimum when pressing power and the respective volume button when the phone is off

This seems to be a bug with accessibility services on Android Pie and newer for some devices. It happens with the Macrodroid app as well when you only enable their accessibility service which filters keyevents. I tested Key Mapper with no code in the onKeyEvent function in the accessibility service and it still happens. I've tested it on a rooted OOS Android 10 OnePlus 6T, rooted stock Android Pie custom ROM on the OnePlus 6t, non-rooted OOS Android 10 OnePlus 7 Pro. It doesn't seem to happen with Android 10 on the Pixel 2.

Why can't I remap some of my Joy Con buttons?

Not all the Joy Con buttons are visible to accessibility services. There isn't anything the developer can do.

We tested the app on SwitchRoot Android and this is what works...

Working:

• Button (name in app)
• ZL (Button L2)
• L (Button L1)
• • (Select)
• • (Start)
• Left analog stick button (unknown keycode 0)
• ZR (Button R2)
• R (Button R1)
• X (Button X)
• Y (Button Y)
• B (Button B)
• A (Button A)
• Home (Home)
• Volume up (Vol up)
• Volume down (Vol down)

Not working:

• Screenshot button
• All D-Pad buttons (used by OS)
• Both analog sticks (used by OS)
• Right analog stick button
• SR and SL (left joycon)
• SR and SL (right joycon)
• Power button

How can I report an issue?

The preferred way is to create a Github issue. If you can't do that then leave a review on the Google Play store or go to the XDA thread, Discord server linked in the README and About activity. 😀

Nothing here helps. I need even more help!

Head over to the Discord server and someone will probably help you! If you don't have Discord, politely email the developer at [email protected].