Key Maps
Refer to the Quick Start Guide for help with creating key maps. This page gives more detail about every option.
Make sure to save your key map after applying these changes.
Trigger¶
A trigger is a combination of keys that must be pressed in a certain way to 'trigger' the key map. A key map can only have one trigger. You can change the order of the keys by holding down on one and then dragging it into a new position.
This is the page to create a trigger for a key map. You will usually want to 'record' a custom trigger that is a combination of physical buttons/keys. There are also 'advanced triggers' that need to be set up slightly differently.
Trigger modes¶
A trigger with one key doesn't have a mode. Triggers with more than one key can be one of two trigger modes: 'parallel' and 'sequence'. The button for a parallel trigger says 'at the same time' because this is more descriptive. The plus symbol between the keys will change to an arrow if the trigger is a sequence trigger. The developer has called them "parallel" triggers because you press it is one word and you press the keys in parallel.
Parallel¶
You must press the keys down at the same time to trigger the key map and the must be pressed down in the order as displayed from top to bottom. E.g For the trigger screenshot you must press volume up first and then volume down and not the other away around.
Sequence¶
You must press the keys down and up one after another to trigger the key map in a specified amount of time. This timeout is 1000ms by default and this default can be changed in the app settings. You can change the timeout for a specific key map by going to the options page for the key map as explained further down this page.
Key click type¶
There are 3 click types: short press, long press and double press.
Parallel triggers can only be short pressed or long pressed. The click type can be customised for each key in a sequence trigger by pressing on the 3 dot button on each key.
Short press¶
This is a simple press of the key and there are no restrictions to how you press it. The key map is triggered when this key is pressed down and doesn't need to be released to activate it. There are no options for this click type.
Long press¶
You need to hold down the key for at least some amount of time for it to trigger the key map. This is 500ms by default and this default can be changed in the app settings. You can change the long press delay for all keys in a key map by going to the options page for the key map as explained further down this page.
Double press¶
You need to press down and release the key in rapid succession for it to trigger the key map. You must do this within 300ms by default and this default can be changed in the app settings. You can change the double press timeout for all keys in a key map by going to the options page for the key map as explained further down this page.
Key device¶
Tap the button on a key so that Key Mapper only detects the key when it comes from a specific device. The default device is 'this device', which means the Android device that you've installed Key Mapper on.
External devices are only listed if they are connected to your Android device when you configure the key map. If you have multiple devices with the same name then turn on the setting to show the first 5 characters of the device ID in the app settings. This will help you distinguish between them.
Key options¶
This menu pops up if you press the 3 dot button on a key.
Do not remap¶
Do not override default action
This is turned off by default. If this is turned on for a key then the key will still do it's normal thing even though it is remapped. E.g a volume down key with this option will still turn the volume down.
This option doesn't remap the trigger key, which means it will continue do its normal thing when clicked as well as your action. This will be automatically
Click type¶
This will change the click type for a key in a sequence trigger. A parallel trigger key will not have the click type option because all the keys have the same click type. You will find the buttons to change a parallel trigger's click type above the trigger mode buttons as shown in the image at the top of this Trigger section.
Advanced triggers¶
These triggers can be purchased so that the Key Mapper project has a little financial support and the developer is able to invest time maintaining and working on the project. You can see the list of advanced triggers below by tapping 'advanced triggers' on the trigger page.
Assistant trigger¶
This trigger allows you to remap the various ways that your devices trigger the 'assistant' such as Google Assistant, Bixby, Alexa etc.
There are 3 assistant options you can choose:
- Device assistant: This is the assistant usually triggered from a long press of a power button or a dedicated button.
- Voice assistant: This is the assistant launched from the hands-free voice button on keyboards/headsets.
- Any assistant: This will trigger the key map when any of the above are triggered.
Note
It is not possible to create long-press key maps with this trigger! But you can do double press. You also can not use multiple assistant triggers in a parallel trigger because there is no way to detect them being pressed at exactly the same time.
Setting up¶
There are multiple ways of triggering the assistant on different devices.
Long press power button, Pixel squeeze
This works on most Android devices. Android devices now have the option for remapping a long press of the power button to the assistant app. Older Pixels, such as the Pixel 2, also had a feature called "Active Edge" that allowed you to squeeze the bottom half of the phone to trigger the assistant. If you select Key Mapper as the 'device assistant' app then your key map will be triggered with both of these methods.
You can set up the long-press of the power button by going to Android Settings System Gestures Press and hold power button. Then choose the digital assistant instead of showing power menu when you long press the power button. Key Mapper will prompt you to select it as the default digital assistant app.
Bixby button
This should work on Samsung devices that have a dedicated Bixby button but also devices that have the option of remapping the power button to another app when you double press it. You can use the assistant trigger for double pressing the Bixby or power button by picking the 'Assistant trigger' app/activity that shows in your list of apps.
Note
The developer does not have a Samsung device with a Bixby button so there is no guarantee that it works. If it does, please let the developer know so we can be more confident about support in the future 😄.
Voice assistant button on keyboards and Bluetooth headphones
Many external devices such as headsets and keyboards have a button for launching the voice assistant so you can control your phone hands-free. This also works with Key Mapper.
Warning
Some headphones have hardcoded the assistant apps that they support and will not work with Key Mapper. The developer has Sony WH1000XM3 headphones that only support Alexa and Google Assistant and refuse to launch Key Mapper when it is selected as the default assistant app.
Customising actions¶
You can tap the pencil icon to the right of the action's name to bring up the following menu.
Here you can customise a lot of the operation of your key map, including timing and multipliers. There are two buttons to 'replace' and 'edit' the action. The 'edit' button isn't shown for all actions because you can't configure what they do.
Delay before next action (ms)
Key Mapper 2.2.0+
This option takes effect if you have multiple actions in your mapping. The slider sets the amount of time between this action and the next.
How many times
Key Mapper 2.1.0+
On Key Mapper 2.2.0 and 2.1.0 this is called "action count".
This option serves as a multiplier. If this is equal to 5 when your mapping is triggered then your action will be performed 5 times. If this is used with the 'repeat' option then this will perform the action this many times every time it repeats.
Repeating actions¶
Repeat
When this is turned on, Key Mapper will execute your actions repeatedly. This is particularly useful when emulating a keyboard key press, where in most applications holding down the key would result in a repeating output. The default settings in Key Mapper are designed to emulate that behaviour when 'Repeat' is turned on.
Repeat every... (ms)
This option sets the time period for your repeating action. If this is set to 200, your action will repeat every 200ms, or in terms of frequency, 5 times per second. Some people prefer to think about this setting as a repeat rate, commonly measured in 'clicks' per second or cps. To calculate the appropriate time period for this option from a desired frequency, use this equation:
Delay until repeat... (ms)
This option sets the amount of time between the first action and the second action (or the first repeat). This is part of the keyboard key behaviour simulation. If you want your repeating action to begin straight away, you can make this 0.
Repeat limit
Key Mapper 2.3.0+
Changing this will change how many times the action will repeat. By default this is set to "no limit".
Stop repeating when...
Trigger is released Trigger is pressed again Limit reached
-
Trigger is released. You will need to hold down the trigger in order for the keys to repeat. If you let go of the trigger, the repeating will stop.
-
Trigger is pressed again. Pressing your trigger once will be sufficient to start your repeating key map. To stop the key map, you will need to press the trigger a second time.
-
Limit reached. (Key Mapper 2.3.0+). Your key map will stop repeating once the limit has been reached regardless of whether the trigger is being held down.
Hold down actions¶
Hold down
Key Mapper 2.1.0+
This setting provides the ability to simulate holding down a key or tapping a coordinate (Android 8.0+). With this turned on (and repeat turned off), the default behaviour is that holding down your trigger will translate to holding down the action, for as long as you hold down the trigger.
Hold down until trigger is...
Released Pressed again
Key Mapper 2.2.0+
This setting allows you to choose from two behaviours. If 'Released' is selected, holding down your trigger key(s) will translate to holding down the action, for as long as you hold down the trigger key(s).
If you choose 'Pressed again', pressing your trigger key(s) once will be sufficient to start holding down the action. To stop the key map, you will need to press the trigger key(s) a second time.
Using 'Hold down' and 'Repeat' together¶
Key Mapper 2.2.0+
You can use turn on both of these settings to unlock an additional setting. A repeating hold down action behaves like a normal 'Repeat' action in that the action repeats itself with a given frequency. It also behaves like a 'Hold down' action in that each individual action will be held for a certain amount of time in each cycle.
Hold down duration (ms)
This allows you to set how long the action is held down for before repeating.
Special options¶
There are options for a key map under the 'Options' or 'Constraints and more' tab. Here are explanations of each option.
Allow other apps to trigger this key map (2.3.0+)¶
This allows you to trigger the key map by using a shortcut or by sending an Intent to Key Mapper. Turning this off will stop any shortcuts or Intents for this key map from working.
Home screen (launcher) shortcut¶
You can create a home screen shortcut by tapping "create launcher shortcut" or by adding the shortcut to your home screen in the same way as a widget. You can also use this shortcut from automation apps like Tasker and Automate without having to create a home screen shortcut.
Note
This button will be disabled if your launcher doesn't let 3rd party apps tell it to create shortcuts so you'll have to create it manually.
Intent¶
There are many apps that can automate broadcasting Intents such as Tasker and Automate.
Intent action¶
Intent string extra¶
The extra value is the UUID of the key map. You can copy the UUID in Key Mapper by turning on the "Trigger from other apps" option.
Intent package name¶
The component for the intent must be sent so that the intent is sent specifically to Key Mapper and not any other apps. Android enforces this and will not send the intent to Key Mapper if it is not specified. If you are using a .debug or .ci build then add .debug or .ci to the end of the package name below only and not the class name.
ADB command¶
This adb command tests this feature.
adb shell am broadcast -n io.github.sds100.keymapper/io.github.sds100.keymapper.api.TriggerKeyMapsBroadcastReceiver -a io.github.sds100.keymapper.ACTION_TRIGGER_KEYMAP_BY_UID --es io.github.sds100.keymapper.EXTRA_KEYMAP_UID $KEYMAP_UID$
Show an on-screen message
When this is turned on, the following notice will come up at the bottom of the screen when ever you trigger your mapping.
You can have your device vibrate instead of an on-screen message if you want. This option is below.
Vibrate
Vibrate duration (ms)
Tapping 'Vibrate' will cause your device to vibrate whenever you trigger your mapping. You can change how long your device vibrates with the slider.
Vibrate when keys are initially pressed and again when long pressed
This is only shown if the 'at the same time' trigger mode is selected and the trigger needs to be long pressed.
This behaves similarly to the on-screen message option above.
Detect trigger when screen is off. ROOT only.
These are the buttons which can be detected when the screen is off. Let the developer know about any buttons you would also like to be supported.
Note
Please send the output of pressing the buttons while running the adb shell getevent -lq command so the
developer knows which key event name they need to add.
- Volume Up
- Volume Down
- Headset button
- Camera focus button
- Camera button
- Bixby button - on some ROMs the Bixby button is mapped to the Menu or Assist key code in Android so it will appear as these buttons in the trigger.
- Search button
Long press delay (ms)
This is only shown if a trigger has at least one key that needs to long pressed. This option will change for how long these keys need to be held down.
Double press timeout (ms)
This is only shown if a trigger has at least one key that needs to double pressed. This option will change the maximum amount of time that a button needs to be double pressed so that it is detected as a double press.
Sequence trigger timeout (ms)
This is only shown if you've chosen the 'in sequence' trigger mode. This option will change the time limit for how fast you need to complete the trigger.
Adding constraints¶
Constraints allow you to restrict your mappings to only work in some situations.
To add a constraint fron the 'Constraints and more' or 'Options' tab, tap 'Add constraint'.
Go here to see how you can configure constraints.