Creating a Device Template for a Remote that uses the kernel input subsystem

Criteria for using The Generic HID Interface

The Remote in question must:

• Expose itself as an input device, and have a file entry in /dev/input as eventX where X is the order in which the kernel discovered the device.
• Must emit EV_KEY packets, as specified by the Linux Input subsystem.

Following these criteria, creating a device template is simple.

Adding Support for a new Remote

Before you start

Press Keys on the remote, make note of which keys work, and which ones do not. You will only need to specify keys for the keys that do not work in your template.

Step 1: Plug in device

With orbiter started, plug in the device, and quick reload the router.

Step 2: Find the Device # of the On-Screen Orbiter you are using.

In the web admin, go to Advanced > Configuration > Devices.

Select your media director from the top of the device tree. For the Core Hybrid, select Core/Hybrid under CORE.

Select the On Screen Orbiter child. Get its device #. You will need this.

Step 3: Tail the Orbiter Log looking for Generic HID events

Open a shell on the media director on which you have the remote connected.

Due to the sheer volume of data generated by the Orbiter log, we will need to filter it, looking specifically for GenericHIDInterface messages. This is simple with a grep command.

tail -f /var/log/pluto/XX_LaunchOrbiter.sh.log | grep "GenericHIDInterface"

You will start seeing GenericHIDInterface messages.

Step 4: Press the keys that do not work

Press the keys that do not work. If the Generic HID Interface is able to decode them, you will see messages similar to the following:

10	06/27/09 22:00:33.856		GenericHIDInterface::DecodeEventInFD() Begin <0xb3232b90> 
10	06/27/09 22:00:33.856		GenericHIDInterface::DecodeEventInFD code 20114 value 1. <0xb3232b90>
10	06/27/09 22:00:33.856		GenericHIDInterface::DecodeEventInFD() End <0xb3232b90>
10	06/27/09 22:00:34.048		GenericHIDInterface::DecodeEventInFD() Begin <0xb3232b90>
10	06/27/09 22:00:34.048		GenericHIDInterface::DecodeEventInFD code 20114 value 0. <0xb3232b90>
10	06/27/09 22:00:34.048		GenericHIDInterface::DecodeEventInFD() End <0xb3232b90>

If you recieve the code, Make note of the code. Match this with the button you're intending to press, in your notes.

Repeat this for all the buttons that do not work.

Step 5: Open a notepad and write Configuration Device Data

Open a notepad and take the codes you have written down, and pair them with buttons in the Remote Mapping Table.

The Lines should be like this:

VolUp,20114,R[,Y]

and should be one per line. Where the:

• first value, is the symbol in the Remote Mapping Table
• second value, is the key code you determined by looking at the logs.
• third value is a key state, where:
  • U = Button Up
  • D = Button Down
  • H = Button Held Down
  • R = Button Repeats when Held Down.
• fourth value (optional) means that this key code should be honored even on screens which yield to the OS, examples of this screen include:
  • DVD Menu
  • Web Browser
  • On-Screen navigation (think MythTV menus, etc.)

Step 6: Write the Mapping Device Data

Press enter a few times, and enter the mapping device data.

This device data is used to map one key code, to another.

According to the 1812: Gyration Go Mouse template:

new line delimited list of events to replace with other events in the format: Event Type,ID=EventType,id

To give an example:

The Gyration 3101 emits a key code, 97, when the Windows button is pressed. This needs to be changed so the system interprets it as the key code for F7.

so we add a mapping for it:

2,97=2,73
3,97=3,73

The code, 73, for F7, is coincidentally the xkeysym for F7. X Key symbols can be found using the xev utility, and reading the "code:" value when a key is pressed.

You can also add mappings for mouse buttons. These have a event type of 4 and 5. So mapping mouse button 6 to F7 would be like this:

4,6=2,73
5,6=3,73

Wait, what are the 2, 3, 4 and 5 values?

These are the Event Types.

According to Orbiter.h:

			typedef enum _EventType {
				QUIT,
				NOT_PROCESSED,
				BUTTON_DOWN, // keyboard
				BUTTON_UP, 
				REGION_DOWN, // mouse
				REGION_UP,
				MOUSE_MOVE,
				MOUSE_RELATIVE_MOVE,
				HID,
				NONE
			} EventType;

Since this is an enumerated type, starting from 0, 2 = BUTTON_DOWN, 3 = BUTTON_UP, 4 = REGION_DOWN, 5 = REGION_UP.

Step 7: Make a New template, with all the compiled information

Please read the general information on Device Templates before continuing.

Go to the web admin, Advanced > Configuration > Device Templates.

Select the appropriate Manufacturer. If it does not exist, make one.

Select Remote Controls from the device category, or Gestural Remotes if it is a gyro-mouse. Basically, use an appropriate category.

Select [Add Device]

Select that this is a device that does not require any programming. Name it appropriately.

Controlled By Category

This device needs to be controlled via category Orbiters -> Standard Orbiter. So add that as a controlled via Device Category. Orbiter uses this relation to not only make the remote a child of the on-screen orbiter, but Orbiter expects to find remote controls in this category so it knows to appropriate them.

Configuration Device data

add the following, with the Use Master List Defaults checked for all:

• Configuration. Paste the Configuration device data from your notepad, here.
• Mapping. Paste the Mapping Device data from your notepad, here.
• Only One Per PC, set this to 1
• Auto Assign This to Parents Room, set this to 1
• PNP Create Without Prompting, set this to 1
• Immediate Reload isn't Necessary, set this to 1.

Please be sure to put appropriate comments into the comments field. This is required.

Plug and Play

This is how LinuxMCE will detect the device. Since this is most likely, a USB device, you will need to put 0 in both the beginning and end MAC, as they will not be used.

You will then need to fill out the Vendor/Model ID appropriately. You can grab this information using lsusb

For example: The Gyration Go Mouse and MCR Remote use a USB ID of 0c16:0002, where 0c16 is the vendor number, and 0002 is the model number. Enter this without the colon: 0c160002. Write a suitable comment, and click the add button.

You can then press the Save button, and the device template will be saved. You can then check this in anonymously, by using the sqlCVS functions in the web admin to check in your dce and ir repositories. Use the default credentials for an anonymous check in, and let us know in a trac ticket that you've checked in a template.