Post Reply

Lightbulb [TUTORIAL] External keyboard remapping [3.0+]


28th March 2012, 10:01 AM   |  #1  
_TB_TB_'s Avatar
OP Senior Member
Flag Ruda Śląska
Thanks Meter: 156
421 posts
Join Date:Joined: Apr 2006
This short tutorial is based on my own research regarding missing keyboard layout mapping in stock Honeycomb/ICS Android for my Motorola XOOM. It is not intended to be a complete description of the Android input system, please refer to the official documentation for more information. This text should suffice for anyone with a basic knowledge about IT :P Anyway, if you break something, 'aint my fault. Won't take any responsibilities for YOUR actions.

- rooted Android 3.0+ device (3.0, 3.1, 3.2, 4.0)
- text editor
- external keyboard to play with

Background stuff
(simplified, no bashing :P)
Keyboard (connected to any device) sends key codes to the target device. Key codes are just plain numbers, eg. if you press the "A" key on the keyboard, the computer reads "30" number. Since "30" is quite difficult to remember as being the "A" button, it is much more handy to describe keycodes as char codes: in the target software we get a KEY_A instead of 30.

Android uses two files for keyboard key-to-output mapping: .kl (key layout) and .kcm (key character map).
*.kl file describes the mapping between real keyboard codes to their virtual values, eg. 30 => KEY_A.
*.kcm file converts char codes to key events (KEY_A pressed? Send character "a". Shift + KEY_A? Send character "A", etc.)

So if you connect an external keyboard (USB, BT, Ir?) to your Android device, you get the following chain:
[keyboard] => [kl] => [kcm] => [application]
All devices (well, most of them) can be identified by VID (Vendor ID) and PID (product ID). VID and PID are 4 hex symbols each.

Android by default uses /system/usr/keylayout/Generic.kl and /system/usr/keychars/Generic.kcm for keyboard handling. If you look into /system/usr/keylayout/ and /system/usr/keychars/ you may find some more keymaps, including something like Vendor_xxxx_Product_xxxx.* Those files are used for specific devices, eg. Vendor_045e_Product_028e.kl is used for XBox 360 controller. When you connect the keyboard, Android checks the peripherial device VID and PID and looks for matching kl and/or kcm. If there is no matching file found, Generic.kl/Generic.kcm is used instead (disjoint -> you may have a specific kl and generic kcm, generic kl and specific kcm, etc.).
You may get the PID/VID of your external keyboard under for example Windows (in device manager [devmgmt.msc] find your keyboard and check its details [properties->details], for example HID\VID_046D&PID_C312\6&26DA469B&0&0000 => Vendor_046d_Product_C312). So if you would like to prepare a keymap for my USB Logitech keyboard, you will have to provide me with Vendor_046d_Product_C312.[kl|kcm] files

Both KCM and KL files are encoded in ANSI -> no special (national) characters allowed except for 'classic' set! If you want to include any national or extra character, you need to use their unicode hex values in \uXXXX variant. See for a huge list of unicode characters.

Getting hands dirty
- pull Generic.kcm from your device via adb:
adb pull /system/usr/keychars/Generic.kcm
- open it with Notepad++
- scroll through the blahblah about not modifying the file to the section with
key A {
    label:                              'A'
- this is where your work starts!

In general the map is composed as fillows:
# comment starts with a hash
key [keycode] {
    label:                 '[label]'
    base:                  '[key without any modifiers]'
    [modifier]:            '[key with modifier]'
    [modifier]+[modifier]: '[key with both modifiers]'
    [modifier],[modifier]: '[key with any of listed modifiers]'
    [modifier]:            fallback [magic key] # read below
    [modifier],[modifier]: none
Modifiers can be: ralt, lalt, alt (right/left ALT, any ALT), rshift, lshift, shift (right/left SHIFT, any SHIFT), rctrl, lctrl, ctrl (left/right CTRL, any CTRL), capslock (no right CAPSLOCK on the kb, sorry ), rmeta, lmeta, meta (right/left WIN key, any WIN key). There are probably more, but didn't encounter any...

So, let's make the A key work like on Polish (Programmer) keyboard layout (namely a, A, ą, Ą letters):
key A {
    label:                              'A'
    base:                               'a'
    shift, capslock:                    'A'
    ralt:                               '\u0105'
    shift+ralt, capslock+ralt:          '\u0104'
    lalt, meta:                         none  # ctrl omitted - ctrl+a does something...
Polish letters "ą" and "Ą" have their unicode values of 0x0105 and 0x0104 respectively, thus in order to have them available via right alt + A, we use ralt modifier and shift/capslock ralt modifier. Please note, that it is necessary to have 'shift' modifier for capital A.

fallback magic key
is used to map certain key combinations to other commands ("hardware buttons"), such as HOME, SEARCH, MENU, APP_SWITCH, etc. Thus if for example you would like to have lalt+tab for app switching you would have to use the following:
key TAB {
    label:                              '\t'
    base:                               '\t'
    lalt:                               fallback APP_SWITCH # alt + tab :)
    ralt, meta:                   none
And now a Windows+D for desktop shortcut:
key D {
    label:                              'D'
    base:                               'd'
    shift, capslock:                    'D'
    meta:                               fallback HOME # show desktop
    alt:                              none
In short
- in most cases the Generic.kl file is ok, there is no need to prepare .kl for a common keyboard
- either edit Generic.kcm or get VID/PID of your keyboard and prepare a key layout for your language and push it to /system/usr/keychars/

- backup your Generic.kcm file!
- try to be as specific as possible if you do not use a combination, map it into 'none' section; when you map ralt, don't include alt in 'none', include lalt instead. Remember, that some key combinations have special meanings (ctrl+d, ctrl+c, ctrl+v, etc), and it is better not to include them in your map.
- backup your layout - I lost a lot of time re-creating my keymap after ROM upgrade (symbolic link is a better idea!)
- look through the entire Generic.kcm file - there are a lot of fancy key combinations, for example ESCAPE key can !by default! handle MENU, BACK and HOME keys!
- possible fallback keys are listed in .kl file
- use logcat! You can spot information about external input device and a note about applied KCM/KL files

Hit "thanks" if you find it helpful. If you prepare a good (national) key layout, please share it!
The Following 26 Users Say Thank You to _TB_TB_ For This Useful Post: [ View ]
2nd April 2012, 05:15 PM   |  #2  
Junior Member
Thanks Meter: 0
3 posts
Join Date:Joined: Apr 2011
For Polish national characters we can use "Polska Klawiatura Programisty V2" it works very well with external keyboard on MoPho with 2.3.
Last edited by WL_PL; 2nd April 2012 at 05:26 PM.
22nd July 2012, 05:25 PM   |  #3  
Senior Member
Thanks Meter: 9
150 posts
Join Date:Joined: Nov 2008
thanks for the information. I couldnt find the the Android ICS/Honeycomb virtual key for task you know what name is that Task switcher virtual key ?
26th August 2012, 03:38 AM   |  #4  
Junior Member
Thanks Meter: 0
3 posts
Join Date:Joined: Aug 2012
Hi, I am a newbie with android....

I modify the kcm file to (spanish layout, Generic to Vendor both attached):

An I can't make it work, maybe:

Something is missing?
Errors in the kcm file?

Any advice would be appreciated
Attached Files
File Type: zip - [Click for QR Code] (4.4 KB, 142 views)
26th August 2012, 11:41 AM   |  #5  
_TB_TB_'s Avatar
OP Senior Member
Flag Ruda Śląska
Thanks Meter: 156
421 posts
Join Date:Joined: Apr 2006
I am away from my PC, but:
1) run Terminal Emulator before connecting the external keyboard
2) enter superuser mode (su)
3) launch logcat (logcat)
4) launch another Terminal Emulator window
5) enter superuser mode (su)
6) connect external keyboard
7) break logcat feed
8) launch dmesg (dmesg) in other window
9) check logcat and dmesg outputs looking for errors

I'm on vacation till next Sunday. I will help you directly once I'm back

Sent from my Galaxy Nexus using Tapatalk 2
The Following User Says Thank You to _TB_TB_ For This Useful Post: [ View ]
27th August 2012, 02:13 AM   |  #6  
Junior Member
Thanks Meter: 0
3 posts
Join Date:Joined: Aug 2012
Thanks for the help:

Here are fragments of:


Start called p = df8e3820
starting connect time
DWC_OTG : [tcc_set_vbus] vbus_state:1
usb 1-1: new low speed USB device number using dwc_otg
usb 1-1: device v1241 p1503 is not supported
input: USB Keyboard as /devices/platform/dwc_otg.0/usb1/1-1/1-1:1.0/input/input5


D/EventHub( 1114): No input device configuration file found for device ' USB Keyboard'.
E/KeyCharacterMap( 1114): /system/usr/keychars/Generic.kcm:454: Malformed character literal.
E/KeyCharacterMap( 1114): /system/usr/keychars/Generic.kcm:454: Invalid character literal for key.

I will check line 454 and see what I can do.


So I checked the 454 lien an a 'u' was missing, "\00xx" to "\u00xx".
I use the droidedit pro (1.15.2, and god the save file doesn't work unless root mode is enabled), changed in the ext_sd version use the terminal and copy then I connect the keyboard and it work, oh yeah it simply works (just a 'u' for 22kb file)

Anyway thanks for the tip it really, REALLY help me
Last edited by jvmnck; 27th August 2012 at 02:53 AM. Reason: Solution found
27th August 2012, 02:15 AM   |  #7  
Junior Member
Thanks Meter: 0
3 posts
Join Date:Joined: Aug 2012
Thanks for this, will come in handy.
25th October 2012, 06:17 PM   |  #8  
Corias's Avatar
Senior Member
Flag Moscow
Thanks Meter: 8
163 posts
Join Date:Joined: May 2009
Hi everyone! Need some help with character map modding for Jelly Bean. I need to assign multiple letters to one button, e.g. "A" for single tap and "[" for double tap (just an example, don't mention).

What I found on
Originally Posted by

The following keyboard types are recognized:

  • PREDICTIVE: A keyboard with all the letters, but with more than one letter per key.
    This type of keyboard is generally designed for thumb typing.
    Corresponds to KeyCharacterMap.PREDICTIVE.

Seems like the one thing I need, but I haven't found any syntax explanations or charmap examples for that layout type. Neither on AOSP pages, nor via Google. If your device uses such keymap type or you just know the syntax, post here examples, or attach kcm files. Any hint is good.
17th September 2013, 07:26 PM   |  #9  
Junior Member
Thanks Meter: 3
24 posts
Join Date:Joined: Sep 2013
Android 4.2.2 - Virtual
Many thanks for this guides.
On my device Virtual.kcm is used (Acer A1-811, android 4.2.2)
Obviously it is nice to modify some file, rather than to pay 2$ for some application to do such mappings to right characters.

20th February 2014, 02:15 PM   |  #10  
Junior Member
Thanks Meter: 0
6 posts
Join Date:Joined: Jul 2013
Logitech K400
Not sure if this goes here, but I have a Logitech K400 keyboard and it has some "special" keys, like the music player key.

What I want to do is to change the default player that opens when pressing that key, in my case it would be Poweramp.
The keyboard also has some other keys on the function keys, and when pressed some of them just are letters, want to edit this too.
There is also a "lock pc" key that opens S Planner.

I hope someone knows what I mean and can help me.

Post Reply Subscribe to Thread

bt keyboard, external keyboard, keymap, layout, remap
Previous Thread Next Thread
Thread Tools Search this Thread
Search this Thread:

Advanced Search
Display Modes

Top Threads in Android General by ThreadRank