• Introducing XDA Computing: Discussion zones for Hardware, Software, and more!    Check it out!
  • Fill out your device list and let everyone know which phones you have!    Edit Your Device Inventory

[TUTORIAL] External keyboard remapping [3.0+]

Search This thread

_TB_TB_

Senior Member
Apr 5, 2006
449
176
Ruda Śląska
suzume.pl
Disclaimer
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.

Requirements
- 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:
Code:
[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 http://www.tamasoft.co.jp/en/general-info/unicode.html for a huge list of unicode characters.

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

- this is where your work starts!

In general the map is composed as fillows:
Code:
# 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):
Code:
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.

Code:
fallback [i]magic key[/i]
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:
Code:
key TAB {
    label:                              '\t'
    base:                               '\t'
    lalt:                               fallback APP_SWITCH # alt + tab :)
    ralt, meta:                   none
}

And now a Windows+D for desktop shortcut:
Code:
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/

Hints
- 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

Finally
Hit "thanks" if you find it helpful. If you prepare a good (national) key layout, please share it!
 

WL_PL

Member
Apr 3, 2011
6
0
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:

hmanxx

Senior Member
Nov 15, 2008
169
9
thanks for the information. I couldnt find the the Android ICS/Honeycomb virtual key for task switcher..do you know what name is that Task switcher virtual key ?
 

jvmnck

New member
Aug 26, 2012
3
0
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::confused:

Something is missing?
Errors in the kcm file?

Any advice would be appreciated :crying:
 

Attachments

  • kcms.zip
    4.4 KB · Views: 401

_TB_TB_

Senior Member
Apr 5, 2006
449
176
Ruda Śląska
suzume.pl
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
 
  • Like
Reactions: jvmnck

jvmnck

New member
Aug 26, 2012
3
0
Thanks for the help:

Here are fragments of:

dmesg
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
logcat
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.

UPDATE

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 fu..ing 'u' for 22kb file)


Anyway thanks for the tip it really, REALLY help me :highfive: :highfive: :good: :good: :cool:
 
Last edited:

Corias

Senior Member
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 source.android.com:
http://source.android.com/tech/input/key-character-map-files.html said:
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.
 

spljaa

Member
Sep 10, 2013
43
3
Android 4.2.2 - Virtual

Hi
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.

Regards
 

PINCHO93

Member
Jul 3, 2013
9
0
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.
 

Jeffpoohill

New member
May 21, 2014
1
0
Mapping an external keyboard

In attempting to re-map an external keyboard, i have succesfully found and edited the P1_keyboard.kl file for instance changing the function of the voice search button from performing that function to performing an "Enter" or typing a letter "B" . However what i am trying to do is to use that button to do a combination of Both Letter B and then ENTER, i have tried "+" space etc but with no luck... Is this possible to do in any way?
 

injola

Member
Aug 9, 2013
33
8
kcm file has no effect

I create this file for the logitech K810

/system/usr/keylayout/Vendor_046d_Product_b319.kl

This successfully remaps keys.

However creating and editing this has no effect:

/system/usr/keychars/Vendor_046d_Product_b319.kcm

The generic behavior also does not match Generic.kcm

One example is Alt-Tab which switches actually switches applications on my device. It is not mentioned anywhere in anything in /system/usr. Redefining
Alt-Tab in the kcm file has no effect.

I am running KitKat on a Galaxy Note 10.1 2014.
 
  • Like
Reactions: zyguo

tamuin

Senior Member
Nov 23, 2011
79
20
file permissions

I create this file for the logitech K810

/system/usr/keylayout/Vendor_046d_Product_b319.kl

This successfully remaps keys.

However creating and editing this has no effect:

/system/usr/keychars/Vendor_046d_Product_b319.kcm

The generic behavior also does not match Generic.kcm

One example is Alt-Tab which switches actually switches applications on my device. It is not mentioned anywhere in anything in /system/usr. Redefining
Alt-Tab in the kcm file has no effect.

I am running KitKat on a Galaxy Note 10.1 2014.

Just a guess, are the file permission set appropriately? (chmod 644 /system/usr/keychars/*.kcm)
 

aont

New member
May 4, 2012
1
0
Ctrl+SPACE does not work

On my nexus7 2012 4.4.4, chroot debian wheezy is running.
When I use emacs with Apple Wireless Keyboard (JIS).
Ctrl-SPACE does not allow me to set mark,
although keep pressing them for about one second just makes it work.
(but keep pressing makes flickering "Mark activated", "Mark deactivated"...)

In the kcm file, CTRL+SPACE is specified as "fallback LANGUAGE_SWITCH".
I tried changing it to none, or commenting out the line, but these doesn't affect.

I also used keytest.apk to inspect the behavior.
It seems just when CTRL+SPACE is pressed, no event happens...?

Does anyone know how to make Ctrl+SPACE (without keep pressing) function as setting mark ?

thank you in advance.
 

stevens_kenneth

Senior Member
Feb 11, 2011
71
8
Genius luxepad 9100 keyboard

Hi i have this keyboard and android 4.2.2 i want the keyboard with spanish layout without pay an app, i want to choose the language on the system. Thanks in advance
 

fbxdadev

Member
Mar 29, 2012
48
9
Keycodes not recognised

Hi there,
I have a problem where I can't remap a key because it's not showing any keycode.

That is: standard keys like A, B, C, etc are ok: I can see their scan code and change it if I want to, but I don't.
Keys like Volume_up, play_pause, etc I would like to have them changed, but I cannot as I can't see any scan code when I press them.

I know all keys work as I tested the remote on windows and it works properly, and I can see keycodes there (but they are not the same as in android, so I can't use windows' keycodes)

Thank you if you can help :)
 

-creo-

Member
Aug 20, 2009
17
7
r-c
ya.ru
enter to send message

hello everyone! does anyone solve question about ENTER key to sending message insdeat of new line command? combination of buttons not works too for the sending messages....

android 4.4.2 + universal external keyboard (with comand buttons)
 

NumanZahid

New member
Mar 4, 2015
1
0
Toggle Languages

Thanks for this helpful and specific tutorial. :good: :D
I am trying to map keys for Urdu language. :angel:
My question is, will it work properly with lollipop?
Will it be able to toggle between language. :confused:
...
Thanks in advance for you kind information :)
 

jeffreylec

Member
Apr 14, 2015
23
11
Atlanta
Code:
adb push move /system/usr/
push: move/keychars/Virtual.kcm -> /system/usr/keychars/Virtual.kcm
failed to copy 'move/keychars/Virtual.kcm' to '/system/usr/keychars/Virtual.kcm': Read-only file system
Should I change permissions to put back onto system/usr?
 

Top Liked Posts

  • There are no posts matching your filters.
  • 34
    Disclaimer
    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.

    Requirements
    - 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:
    Code:
    [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 http://www.tamasoft.co.jp/en/general-info/unicode.html for a huge list of unicode characters.

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

    - this is where your work starts!

    In general the map is composed as fillows:
    Code:
    # 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):
    Code:
    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.

    Code:
    fallback [i]magic key[/i]
    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:
    Code:
    key TAB {
        label:                              '\t'
        base:                               '\t'
        lalt:                               fallback APP_SWITCH # alt + tab :)
        ralt, meta:                   none
    }

    And now a Windows+D for desktop shortcut:
    Code:
    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/

    Hints
    - 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

    Finally
    Hit "thanks" if you find it helpful. If you prepare a good (national) key layout, please share it!
    1
    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
    1
    kcm file has no effect

    I create this file for the logitech K810

    /system/usr/keylayout/Vendor_046d_Product_b319.kl

    This successfully remaps keys.

    However creating and editing this has no effect:

    /system/usr/keychars/Vendor_046d_Product_b319.kcm

    The generic behavior also does not match Generic.kcm

    One example is Alt-Tab which switches actually switches applications on my device. It is not mentioned anywhere in anything in /system/usr. Redefining
    Alt-Tab in the kcm file has no effect.

    I am running KitKat on a Galaxy Note 10.1 2014.