Attend XDA's Second Annual Developer Conference, XDA:DevCon 2014!
5,768,772 Members 52,242 Now Online
XDA Developers Android and Mobile Development Forum

[TUTORIAL] External keyboard remapping [3.0+]

Tip us?
 
_TB_TB_
Old
#1  
_TB_TB_'s Avatar
Senior Member - OP
Thanks Meter 152
Posts: 421
Join Date: Apr 2006
Location: Ruda Śląska
Lightbulb [TUTORIAL] External keyboard remapping [3.0+]

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 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:
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!
The Following 26 Users Say Thank You to _TB_TB_ For This Useful Post: [ Click to Expand ]
 
WL_PL
Old
(Last edited by WL_PL; 2nd April 2012 at 05:26 PM.)
#2  
Junior Member
Thanks Meter 0
Posts: 3
Join Date: 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.
 
hmanxx
Old
#3  
Senior Member
Thanks Meter 9
Posts: 149
Join Date: Nov 2008
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
Old
#4  
Junior Member
Thanks Meter 0
Posts: 3
Join Date: 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 kcms.zip - [Click for QR Code] (4.4 KB, 132 views)
 
_TB_TB_
Old
#5  
_TB_TB_'s Avatar
Senior Member - OP
Thanks Meter 152
Posts: 421
Join Date: Apr 2006
Location: Ruda Śląska
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: [ Click to Expand ]
 
jvmnck
Old
(Last edited by jvmnck; 27th August 2012 at 02:53 AM.) Reason: Solution found
#6  
Junior Member
Thanks Meter 0
Posts: 3
Join Date: Aug 2012
Thanks for the help:

Here are fragments of:

dmesg
Quote:
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
Quote:
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
 
Instynct
Old
#7  
Junior Member
Thanks Meter 0
Posts: 3
Join Date: Aug 2012
Thanks for this, will come in handy.
 
Corias
Old
#8  
Corias's Avatar
Senior Member
Thanks Meter 8
Posts: 163
Join Date: May 2009
Location: Moscow
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:
Quote:
Originally Posted by http://source.android.com/tech/input/key-character-map-files.html
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
Old
#9  
Junior Member
Thanks Meter 1
Posts: 13
Join Date: Sep 2013
Default 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
Old
#10  
Junior Member
Thanks Meter 0
Posts: 6
Join Date: Jul 2013
Default 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.

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

Advanced Search
Display Modes


Intel Partners with Unity to Support Android on Intel-Based Devices

Intel, largely known for their long-standing reputation as the king of … more

Device Review: Samsung Gear Live

Recently, Google announced Android Wear to the world. Android Wear is the Android-based initiative from … more

Forums Added for the Nvidia Shield Tablet and Sharp Aquos Crystal

Just a few days ago, wetook an in depth look at theNvidia Shield Tabletand … more

[OTA Captured] Android 4.4.3 Lands on European HTC One M7

The secound release of the Android L Developer Previewmay be the new hotness for … more