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