This changed completely in .28. Soon the following how-to will make it to the main website. In the meantime, here are the instructions from the revised how-to page:
Programmer's guide
Be sure to read the How To Use It section above first. As you can see, Pluto provides a highly intelligent interpretation of infrared remote buttons, that automatically change their function based on what the user is doing, what type of remote control layout exists, and where the infrared codes are going. If you have ever worked with infrared remote controls, such as LIRC, you know that there is no standard, and all the remote controls have different buttons with different names. Therefore we had to create a database structure that allows for interpreting the different button names into commands which can change depending upon the context and the layout of the remote.
The DCE Devices (ie the Pluto binary that is run to handle i/r reception) are all of the category Peripherals, Infrared Receivers. In Pluto Admin choose Advanced, Device Templates, and you can see the categories and devices in them. There is a separate folder for the LIRC drivers. In addition to a device for the i/r receiver, there is also a device for the i/r remote. The remote controls are of the type Peripherals, Remote Controls. Since the definition of the infrared codes for a remote control is stored within the remote control device, and that definition varies depending upon the type of receiver, you will see there is a separate subcategory for each type of receiver. For example there is a folder "LIRC Remote Controls" that has all of the remote controls and definition files for the LIRC project. We also created our own DCE devices for other infrared receivers, such as IRTrans and Tira. Although these are supported within the lirc project, we found that we had better control and greater accuracy when we used the native SDKs for these receivers. So, for example, if you have an IRTrans receiver, and an XPMC remote, you have two possibilities. First you could add the LIRC receiver device, and the XPMC remote device that is within the LIRC remote category. In this case the remote control will be using an LIRC config file. Secondly you could add Pluto's native IRTrans receiver device, and then pick the XMPC remote device that is within the IRTrans remotes category, which stores the button codes in a different format, that is in IRTrans' native format. When you are adding your infrared receiver and remote control using the Pluto Admin Wizard/Devices/Media Directors page, the wizard automatically ensures that when you add a remote control it is the correct category.
For each remote control there is a device data "#59 Configuration" which has the remote controls configuration file, which defined all the infrared codes at each button will send and gives each code, or button, a name. So the XPMC remote within the LIRC category has a device data #59 that is the LIRC config file. The XPMC remote within the IRTrans category has a device data #59 that is the same buttons/codes, but in IRTrans format.
When the framework starts an IR receiver device, iIn general this device will first scan for all sister devices within the category remote control, and write out a configuration file. So, for example, when LIRC_DCE runs it finds all LIRC remote controls on that machine, grabs the device data "#59 Configuration" for every one of them and writes that out to a lirc.conf file, and then starts LIRC.
All the logic is in a base class called IRReceiverBase. All of Pluto's infrared receiver devices use this same base class. So the actual code that is specific to each type of receiver is very small, usually around 20 lines. It only needs to write out the configuration file at start up, and then call the member function ReceivedCode within IRReceiverBase when a button is pushed. This function takes the name of the button as a parameter, and converts this into a message.
Since all of the receivers use a common base class to handle the logic, that also means that all of the translation between buttons and actions is also in a shared database. It does not matter whether you are using LIRC or some other infrared receiver, the translation is the same. There is no unified standard for what the buttons are called. The button "SkipFwd" may be called "Fwd", "Skip+", "Jump->", etc. The table RemoteMapping in the main mysql database, pluto_main, has a field Mapping which lists all the button aliases, followed by the command to be executed when any of those buttons is pushed. For example: chup;skipfwd;ChanUp;SkipNext;|0 -106 1 65 5 +1
Whenever any infrared receiver reports any of those button presses, the message "0 -106 1 65 5 +1" gets fired. The format of the message is the same as if you typed it with the MessageSend utility: ie from device, to device message type, message id, followed by parameters.
So if the user presses a button called ChanUp, a message will be sent to device -106 (media plugin) of type 1 (command) id 65 (Jump Position In Playlist) with parameter 5 (Value To Assign) set to "+1". This table is shared amongst all Pluto users, and is updated every time your system upgrades versions. If you make your own manual changes to this table then the next time your core upgrades it will not upgrade the rows in that table that you modified, because SQL CVS does not, by default, overwrite your local changes with global ones. Therefore, if you have a new remote control with some new buttons that we have not yet mapped, it is recommended that you e-mail us or post us a message in the forum, with the button name and the message and then we can add it to our master database and then your system can remain in sync with other users enhancements. If you want to do some mapping that is just for you, you can change the table and know your changes will not be overwritten.
You'll note that the RemoteMapping table has 2 optional fields: ScreenType and RemoteLayout. When the IRReceiverBase base class is deciding what message to send in response to button press, it first looks for a more specific entry where the screen type matches the type of screen currently visible on the orbiter, and the remote layout matches the layout. The on-screen orbiters regularly send messages to the infrared receiver telling them what type of screen is currently visible, using the following codes: M=Main Menu, m=other menu, R=Pluto Remote, r=Non-pluto remote, F=File Listing. This allows for buttons to behave differently depending upon what type of screen is visible. For example when the main menu is visible, the arrows on a remote control should send a message to the on-screen orbiter to move the highlight pointer around on the screen. However when the user is controlling an external piece of AV equipment, like a DVD player, the arrows should pass through to the DVD player so the user can control its own on-screen menu. Also the type of functionality can vary depending upon the layout of the remote. For example, Bang & Olufsen remotes are quite simple, there is only a single up/down/left/right buttons which are used both to navigate on-screen menus as well as to handle rewind fast-forward and skip. Other remotes have dedicated arrows and media navigation buttons. So one remote layout can be created for Bang & Olufsen-style remote, where the arrows control the menu when there is a menu on screen, and adjust the media when there is not. The remote layout is a device data "#110 Remote Layout" stored with the remote control
When IRReceiverBase looks for a mapping it first looks for records that match the current screen type and remote layout, and then revert to standard records (ie ScreenType and RemoteLayout are null) only if there are no matching results.
