This tutorial describes how to create a customized keylayout for any USB or Bluetooth keyboard. You will need to be rooted to be able to do this. These instructions were developed using dalepl's Thrive 10.1 inch 002 OOM Rooted rom.
If you don't understand these instructions or don't feel comfortable doing them, DON'T DO IT. I only represent that they work on my Thrive. As with any such tutorial,
I AM NOT RESPONSIBLE FOR ANY DAMAGE OR LOSS THAT MAY RESULT FROM ATTEMPTING TO FOLLOW THIS TUTORIAL. USE AT YOUR OWN RISK.
Some settling may occur. Objects may be closer than they appear. Do not eat.
Basically the procedure is as follows:
- Copy /system/usr/keylayout/Generic.kl to /system/usr/keylayout/Vendor_<vendorID>_Product_<productID>.kl where <vendorID> and <productID> are the four digit hex IDs of your keyboard.
- Edit Vendor_<vendorID>_Product_<productID>.kl to assign the desired key actions to the scancodes of the keys you want to modify.
Searching the net, you may find the suggestion of editing
Generic.kl or
qwerty.kl directly. I do not recommend this.
qwerty.kl is no longer used.
Generic.kl is used for anything that does not have a specific keylayout, so any changes you make to it will apply to all keyboards and if you mess it up you can make your Thrive fail to respond properly to any keyboard input
DETERMINING THE KEYBOARD'S VENDOR AND PRODUCT ID
In an ADB shell or terminal emulator:
Code:
sh-4.1# cat /proc/bus/input/devices
...
I: Bus=0005 Vendor=099a Product=0540 Version=011b
N: Name="Bluetooth Keyboard"
P: Phys=E0:B9:A5:A0:9F:DE
S: Sysfs=/devices/virtual/bluetooth/hci0/hci0:12/input7
U: Uniq=00:18:A3:03:0C:A3
H: Handlers=sysrq event7
B: EV=12001b
B: KEY=10000 2000007 ff9f387a d94157ff febeffdf ffefffff ffffffff fffffffe
B: ABS=f00 0
B: MSC=10
B: LED=1f
find the entry for your keyboard, and note the Vendor and Product IDs. This example is from my Azio mini-bluetooth keyboard, the vendorID is 099a and the productID is 0540.
The
dmesg command can also be used. The format in the keyboard's entry is:
bbbb:vvvv:pppp:rrrr
where:
bbbb is the Bus
vvvv is the VendorID
pppp is the ProductID
rrrr is the Version
For USB keyboards, the
lsusb command can also be used. This will show an entry for each attached USB device, including the internal ones, so compare the list before and after attaching the USB keyboard. The format for this entry is:
Bus bbb Device ddd: ID vvvv:pppp
DETERMINING THE SCANCODE OF THE DESIRED KEYS
Download the
KeyTest.apk from:
https://github.com/chrisboyle/keytest/downloads
and sideload it into your Thrive. I know of no other way to reliably identify the scancodes of the keys of interest on an arbitrary keyboard. If you don't want to install this, I can understand, but you will have to identify the desired scancodes in some other way.
To sideload the KeyTest apk:
- Ensure that Settings/Applications/Development/Unknown sources is checked
- Copy KeyTest.apk to your Thrive in a location that you can access from the File Manager. I had to disable Settings/Applications/Development/USB Debugging to get the Thrive to show up as My Computer/AT100 in Windows(tm) Explorer. I also could not copy KeyTest.apk to the top level of either Internal Storage or SD Card, so in Windows(TM) Explorer I created the directory My Computer/AT100/Internal Storage/MyApps, and copied KeyTest.apk there.
- On your Thrive, in File Manager, locate KeyTest.apk and tap on it.
- Select Install on the Package installer dialog that appears.
Attach your keyboard and run the KeyTest app.
Press the keys you desire to modify, and note the scancode that the app reports for each. You want the scancode value, not the keycode value.
MODIFYING THE KEYLAYOUT FILE
Android is based on Linux, which is derived from Unix. Linux and MS Windows(tm) use different conventions as to what constitutes the end of a line. If you edit your new keylayout file in MS Windows(tm), you will need to use an editor that can handle Unix formatted files. Notepad will NOT work. I use PsPad (
editor PSPad - freeware HTML editor, PHP editor, XHTML, JavaScript, ASP, Perl, C, HEX editor), although there are many others that are suitable. With the keylayout file open in PsPad, look at the status bar at the bottom of the window. It should say UNIX just to the left of the Code page: notice. If it says DOS or MAC, click on the mode name until it says UNIX
This link:
Key Layout Files | Android Open Source
describes the syntax of a keylayout file and the meaning of the modifiers. The syntax is basically:
key <scancode> <Android key> <modifier>
where <scancode> is the scancode returned by the KeyTest app. Examine your copy of the
Generic.kl to get some idea of the Android keys that are available. A list of them and their meanings can be found here, although this list does not entirely agree with what is in the 3.2.1
Generic.kl, and so may be somewhat outdated:
KeyEvent | Android Developers
You will need to scroll down a ways.
For my desktop PS/2 keyboard, connected through an IO Gear PS2-USB adapter, I wanted to put Back on the left Windows(tm) key (scancode 125), Home on the right Windows(tm) key (126), and Menu on the Menu key (127). It turns out that the Menu key is already configured for the Android menu function, but the two Windows(tm) keys needed modification. I adjusted the keymap as follows:
key 125 BACK WAKE_DROPPED
key 126 HOME WAKE_DROPPED
key 127 MENU WAKE_DROPPED
My Azio mini-bluetooth keyboard does not have a right Windows(tm) key, so I put Home on the right alt key instead:
key 125 BACK WAKE_DROPPED
key 100 HOME WAKE_DROPPED
key 127 MENU WAKE_DROPPED
Note: the Android key that represents the traditional home action of "move to the begining of the line" is called MOVE_HOME.
On my Azio mini-bluetooth keyboard, with dalepl's 002 OOM rom and the stock media player, the keys that map to MEDIA_PLAY_PAUSE, MEDIA_NEXT, and MEDIA_PREVIOUS work, while VOLUME_MUTE, VOLUME_UP, and VOLUME_DOWN appear to have no effect, although some other media player might respond to them.
USING ADB TO DO THIS
My preferred way to create and install a custom keymap is to use ADB (Android Debug Bridge) to pull the files to my PC and edit them there.
You need to have ADB set up and working such that issuing the command:
Code:
E:\Thrive>adb devices
List of devices attached
2804049441f8057 device
works. See this forum's ADB Drivers thread:
[Drivers] USB ADB Driver Installation Package for information on setting up ADB. I have my PC set up so that the adb command's directory is in my path environment variable. That way I can run adb commands from any directory that I happen to be in. If you don't know how to do this on your system, you probably should not mess with it, since screwing up the path environment variable can cause a lot of things to not work. Simply open your Command Prompt window in a directory where the adb command will work.
When using ADB, there are two contexts you need to be aware of, the command prompt and the ADB shell. The command prompt is the level you are in when you open a Command Prompt window. Commands that you enter at this level are executed on your local PC, although they may have actions that affect the attached Thrive. The ADB shell is entered from the command prompt level as follows:
Code:
E:\Thrive>adb shell
sh-4.1# <shell commands>
sh-4.1# exit
exit
E:\Thrive>
Note that while you are in the ADB shell, the prompt changes from "E:\Thrive>" (the current directory on the local PC) to "sh-4.1#". You exit the ADB shell and return to the command prompt level by entering the shell command "exit". Commands that you enter in the ADB shell execute on your Thrive.
- Retrieve a copy of Generic.kl to your PC. At the command prompt level:
Code:
E:\Thrive>adb pull /system/usr/keylayout/Generic.kl
293 KB/s (9389 bytes in 0.031s)
E:\Thrive>
- On your local PC, copy Generic.kl to Vendor_<vendorID>_Product_<productID>.kl and modify it as desired.
- The Thrive's /system partition is normally mounted as read-only. You must remount it as read-write before you can modify its contents. From the command prompt level:
Code:
E:\Thrive>adb remount
remount succeeded
E:\Thrive>
On my phone, adb remount does not work, but the method described below under "Doing This Entirely In The Thrive" does, so if this step does not work using ADB, try that method of making the system partition writable.
- Upload the modified keylayout to the Thrive. From the command prompt level:
Code:
E:Thrive>adb push Vendor_0557_Product_2221.kl /system/usr/keylayout/Vendor_0557_Product_2221.kl
576 KB/s (9221 bytes in 0.015s)
E:\Thrive>
- Enter the ADB shell, and update the permissions of your new keylayout file:
Code:
E:\Thrive>adb shell
sh-4.1# chmod 644 /system/usr/keylayout/Vendor_0557_Product_2221.kl
chmod 644 /system/usr/keylayout/Vendor_0557_Product_2221.kl
sh-4.1# ls -l /system/usr/keylayout
ls -l /system/usr/keylayout
-rw-r--r-- root root 894 2008-08-01 05:00 AVRCP.kl
-rw-r--r-- root root 9389 2008-08-01 05:00 Generic.kl
-rw-r--r-- root root 1293 2008-08-01 05:00 Vendor_045e_Product_028e.kl
-rw-r--r-- root root 1027 2008-08-01 05:00 Vendor_046d_Product_c216.kl
-rw-r--r-- root root 1325 2008-08-01 05:00 Vendor_046d_Product_c294.kl
-rw-r--r-- root root 1392 2008-08-01 05:00 Vendor_046d_Product_c299.kl
-rw-r--r-- root root 2793 2008-08-01 05:00 Vendor_046d_Product_c532.kl
-rw-r--r-- root root 1458 2008-08-01 05:00 Vendor_054c_Product_0268.kl
-rw-r--r-- root root 9221 2012-03-20 14:18 Vendor_0557_Product_2221.kl
-rw-r--r-- root root 2409 2008-08-01 05:00 Vendor_05ac_Product_0239.kl
-rw-r--r-- root root 9152 2012-03-15 15:01 Vendor_099a_Product_0540.kl
-rw-r--r-- root root 1994 2008-08-01 05:00 Vendor_22b8_Product_093d.kl
-rw-r--r-- root root 263 2008-08-01 05:00 gpio-keys.kl
-rw-r--r-- root root 2577 2008-08-01 05:00 qwerty.kl
sh-4.1# exit
exit
E:\Thrive>
- Shut down and re-boot your Thrive in order to restore the /system partition to its normal read-only state.
DOING THIS ENTIRELY IN THE THRIVE
You will need to install the Terminal Emulator or something equivalent from the Play Store:
https://play.google.com/store/apps/d...al.androidterm
I found that I had to go into preferences and change the font size to 20pt in order to make the text big enough to see.
I also recommend Hacker's Keyboard:
https://play.google.com/store/apps/d...ion.pckeyboard
In order to use the vi editor, you will need a keyboard that supports the <ESC> and directional arrow keys, which the default keyboard does not. You can also use a USB or Bluetooth keyboard, which will allow using the full screen of the Terminal Emulator. In the Hacker's Keyboard settings, I set:
- Keyboard height, landscape = 40%
- Keyboard mode, portrait = Full 5-row layout
In the Terminal Emulator:
- Become superuser
- Remount the /system partition as read-write
Code:
sh-4.1# mount -o rw,remount -t yaffs2 /dev/block/mtdblock3 /system
sh-4.1#
- Change directory to the keylayout directory
Code:
sh-4.1# cd /system/usr/keylayout
sh-4.1#
- Make a copy of the Generic keylayout to you new keylayout
Code:
sh-4.1# cp Generic.kl Vendor_0557_Product_2221.kl
sh-4.1#
- Edit the new keylayout
Code:
sh-4.1# vi Vendor_0557_Product_2221.kl
The vi editor is not very intuitive and you will need to be familiar with the basics of it before you even try to use it. Teaching vi is well beyond the scope of this tutorial. Googling "vi" will provide a number of useful references.
- Shut down and re-boot your Thrive in order to restore the /system partition to its normal read-only state.
You will need to disconnect / unplug your keyboard and reattach it, or shutdown and reboot your Thrive, in order to begin using the new modified keylayout.
REFERENCES
How to map android keys to your usb/bluetooth keyboard - MobileRead Forums
Android keymaps - Chris Boyle