USB HID devices communicates with the host computer by sending
binary reports. Unfortunately, some devices do not provide enough
information for the Linux `hiddev` driver to parse those reports.
In order to communicate with those devices, `hid_mapper` use the
low level `hidraw` driver as well as a user provided map file to
translate "raw reports" to keys.
`hid_mapper` was specifically designed in order to use
"non-compliant" USB HID IR remote receiver with XBMC, but should work
with any USB HID device and for any other application.
This README is based on http://forum.xbmc.org/showthread.php?tid=88560
 This software is distributed in the hope that it will
 be useful, but WITHOUT ANY WARRANTY; without even the
 implied warranty of MERCHANTABILITY or FITNESS FOR A
 PARTICULAR PURPOSE. See the LICENSE file for more
 details.
Build hid_mapper:
=================
 cd /path/to/hid_mapper
 ./make
(see `INSTALL` for other build options)
List recognized devices:
========================
 ./hid_mapper --list-devices
If necessary, blacklist the device in Xorg so it does not conflict
with the mapper. Create a new file in /usr/share/X11/xorg.conf.d/.
For example `50-remote.conf` containing:
 Section "InputClass"
 Identifier "Remote blacklist"
 MatchProduct "PHILIPS MCE USB IR Receiver- Spinel plusf0r ASUS"
 Option "Ignore" "on"
 EndSection
Capture HID events (traditional way):
=====================================
 ./hid_mapper --learn \
 --manufacturer 'PHILIPS' \
 --product 'MCE USB IR Receiver- Spinel plusf0r ASUS'
This will log events recieved while pressing buttons on the remote.
As an example, pressing "OK" on the Philips MCE USB IR Receiver will
produce:
 Found HID device at /dev/hidraw0
 01 00 00 28 00 00 00 00 00
 01 00 00 00 00 00 00 00 00
The first event (line `01 00 00 28 00 00 00 00 00`) is the _key down_
event corresponding to the pressed button.
Based on the info gathered by pressing the various buttons of your
remote, and using keys defined in `/usr/include/linux/input.h`, write
(yourself!) a map file consisting of <key code>:<key symbol> pairs:
 010000280000000000:KEY_ENTER
 030000000000020000:KEY_KP1
 030000000000040000:KEY_KP2
 030000000020000000:KEY_C
 030000000000008000:KEY_TAB
(see the maps/ directory for user contributed examples)
Capture HID events (learn+map way):
===================================
It is somehow annoying (well, error prone ... well, no, annoying)
to first collect the HID event (`--learn`) and then write the
corresponding map.
If you want to do that in "one pass", you might use the new learn+map
feature. This will require first an "empty" map containing all the
keys you want to learn. In that map, keys to "learn" must have
the value `00` as HID event hexdump, like in that example (from
`maps/xbmc-base.map`):
 00:KEY_RECORD
 00:KEY_PAUSE
 00:KEY_STOP
 00:KEY_REWIND
 00:KEY_PLAY
 00:KEY_FORWARD
 00:KEY_LEFTSHIFT
 00:KEY_RIGHTSHIFT
When fed with such a map with both `--learn` and `--map` options set,
`hid_mapper` will ask you to press each key in its turn, producing a
valid key map on standard output:
 ./hid_mapper --learn \
 --manufacturer 'PHILIPS' \
 --product 'MCE USB IR Receiver- Spinel plusf0r ASUS' \
 --map maps/xbmc-base.map > maps/asus-spinnel.map
 # ^^^^^^^^^^^^^^^^^^^^^^^
 # This redirection will send the command
 # output directly to the given file
 # Note: old content is lost!
 # (use `>>` to append -- if you are not
 # accustomed to shell redirections it might
 # be a good time to learn)
Depending your needs/your HID device/your software you might have to
manually tweak the output map (i.e.: on XBMC Eden, I had to rename
some keys afterward: KEY_INFO -> KEY_I, and so on), but it is usually
a very good starting point.
Run the mapper:
===============
The final step is to actually run the mapper:
 ./hid_mapper \
 --manufacturer 'PHILIPS' \
 --product 'MCE USB IR Receiver- Spinel plusf0r ASUS' \
 --map 'maps/asus-spinel.map'
At this point the remote should work and emit the keys specified in
the map file.
Since the hidraw driver is generic, this mapper should work with any
HID receiver, even if it is not a remote. HID is used for keyboard,
mouses, joysticks...