KeyMapping

This howto describes how to map any special keys on your device to normal keys. This howto was written specifically for mapping the Samsung Q1 Ultra arrow keys to behave as arrows, instead of the function keys that they are mapped to by default in Ubuntu Mobile.

When a key is pressed, the kernel reads the key scan code from the keyboard controller. This is mapped by the kernel keyboard driver to a key code, which is what programs (such as X11) receive from the kernel. You can use the 'showkey' utility from the console to see the key codes for the various buttons/keys, or if the key is not mapped you can look in dmesg for errors reporting an unmapped key, the errors are generated every time an unmapped key is pressed/released. If your device already has a key mapped, you can look at the fdi files in /usr/share/hal/fdi/information/10freedesktop/ to see the key scan code, if you know what it is being mapped to.

Once you know what keys you want to map, and what they are being mapped to, you need to create a .fdi to configure the mapping. The proper place for a custom fdi file is in /etc/hal/fdi/policy and should be named something like '99-Samsung-Q1U-Keys.fdi'. The fdi files are XML, and can control many aspects of X configuration, key mappings, etc. More information about this file format is available in the hal spec. We are only concerned with the key mapping portion of the file, an example for the Q1U is below:

<?xml version="1.0" encoding="ISO-8859-1"?> <!-- -*- SGML -*- -->

<deviceinfo version="0.2">
  <device>
      <match key="/org/freedesktop/Hal/devices/computer:system.hardware.vendor" prefix_ncase="samsung">
        <!-- Samsung Q1 Ultra -->
        <match key="/org/freedesktop/Hal/devices/computer:system.hardware.product" string="SQ1US">
          <append key="input.keymap.data" type="strlist">e054:f4</append> <!-- Menu: F4 -->
          <append key="input.keymap.data" type="strlist">e058:up</append> <!-- Up arrow: Up -->
          <append key="input.keymap.data" type="strlist">e059:right</append> <!-- Right arrow: Right -->
          <append key="input.keymap.data" type="strlist">e056:down</append> <!-- Down arrow: Down -->
          <append key="input.keymap.data" type="strlist">e057:left</append> <!-- Left arrow: Left -->
          <append key="input.keymap.data" type="strlist">e064:f5</append> <!-- Shutter key: F5 -->
          <append key="input.keymap.data" type="strlist">e06e:f11</append> <!-- UDF key: F11 -->
          <append key="info.capabilities" type="strlist">input.keymap</append>
        </match>
      </match>
    </device>
</deviceinfo>

The important parts of the file are the two matches to make sure the keys are only applied to the correct machine, and then the key mappings themselves. To find the values for 'system.hardware.vendor' and 'system.hardware.product', you can use the 'lshal' utility. For example, to find the product you would do this:

ume@q1u:~$ lshal | grep system.hardware.product
  system.hardware.product = 'SQ1US'  (string)

The key mapping are done with the key scan code first, followed by what key code they are being mapped. The scan code is a hex value, while the key code is a human readable string for the key (f5, up, etc).

Once the fdi file is created it will be used on the next restart of the device.

MobileTeam/Mobile/HowTo/KeyMapping (last edited 2008-10-12 03:45:02 by 68)