Architecture and Customization

Version 27 (christian, 01/01/2015 03:31 pm)

1 18 christian
h1. +*Architecture & Tools*+
2 17 christian
3 2 christian
{{toc}}
4 2 christian
5 18 christian
h2. Background
6 2 christian
7 2 christian
LinHES 7 introduced a number of changes to the way remotes and associated devices are handled. This is largely being picked up from changes in the Linux base. The way remotes are now handled is significantly different and also requires a different tool set to build and diagnose an implementation. In general this new implementation is a significant improvement in what was previously a rather adhoc structure.
8 2 christian
9 2 christian
This guide will attempt to introduce you to the new architecture and tool sets relevant to LinHES.
10 2 christian
11 18 christian
h2. Architecture
12 7 christian
13 5 christian
The following picture is a logical representation of how various blocks in LinHES are connected.
14 8 christian
15 26 christian
!LinHES-Remote-ArchV8.1.jpg!
16 5 christian
17 27 christian
As of LinHES 7, many of the remote drivers are included in the kernel whereas previously they were part of the lirc subsystem. However not all remote receiver devices have been ported to the kernel so some of these drivers still reside within lirc as before. Those drivers follow the "Legacy Remote Driver" path instead of the "In Kernel Remote Driver" path. The Legacy Remote Drivers follow the same debugging procedures and lirc related files as before.
18 1
19 27 christian
For the in kernel drivers, if Lircd is not running then by default the In Kernel Remote Driver will issue keyboard and/or mouse events. These events will be seen by higher level applications such as X and MythTV as if normal keyboard and mouse events occurred. Thus if you do not require certain lirc functions such as irexec and irxevent then you can quite happily not use lirc at all. Note, some remotes actually do issue mouse events such as certain imon remotes.
20 27 christian
21 18 christian
h3. Remote Receiver
22 9 christian
23 9 christian
Each Remote Receiver will be identified by a unique device ID which will be associated by a driver that recognizes that ID. In most cases this should automatically make the needed associations. In some rare cases more than one driver may try to associate with the device which can cause conflicts. In these exceptional cases, this device can be blacklisted from the driver or the driver itself can be blacklisted.
24 9 christian
25 9 christian
The device ID can normally be found using tools such "lsusb" where you may see an entry similar to:
26 1
<pre>Bus 003 Device 002: ID 15c2:0043 SoundGraph Inc.</pre>
27 9 christian
28 27 christian
h3. In Kernel Remote Driver
29 9 christian
30 9 christian
The driver does not actually know about the remote, it only sees the IR codes received by and translated by the Remote Receiver. The Remote Receiver may use any number of protocols (e.g. RC6, imon, etc) and its associated driver will normally understand all of the protocol variants that the Remote Receiver supports.
31 9 christian
32 1
The Remote Driver will interact with the Remote Receiver in order to maintain the device and of course receive information from the remote itself. Depending on the Remote Receiver and associated Remote, the driver may separate the events as keyboard and mouse events. In this case you may see entries in "/dev/input/by-id" with entries such as "usb-15c2_0043-event-if00" and "usb-15c2_0043-event-mouse". Note in customization it is generally safer to specify a driver using its "/dev/input/by-id" path rather than the "/dev/input" path as the "/dev/input" path can change.
33 1
34 27 christian
h3. Legacy Remote Driver
35 27 christian
36 27 christian
The function is similar to the "In Kernel Remote Driver" however it exists within the LIRC domain and follows the implementation described at lirc.org. This type of driver will not create anything in the /dev/input hierarchy and does not use the ir-keytable functionality. Instead you can use mode2 to see the output from this driver before it is modified by lircd.conf.
37 27 christian
38 18 christian
h3. ir-keytable
39 9 christian
40 27 christian
ir-keytable interacts with the In Kernel Remote Driver and normalizes its output. It utilizes a keymap file normally found in "/etc/rc_keymaps" and the default association with the driver will be defined by "/etc/rc_maps.cfg"
41 9 christian
42 9 christian
There are a number of things that you can do with ir-keytable including:
43 9 christian
* Identify the driver and its protocols (eg. ir-keytable)
44 9 christian
* Monitor the driver output of received events from the Remote Receiver (eg. ir-keytable -t)
45 9 christian
* configure the driver for items such as protocols (eg. ir-keytable -p RC6, LIRC, etc)
46 9 christian
* Load a specific or custom keymap for a driver (eg. ir-keytable -w /etc/rc_keymaps/imon_mce)
47 9 christian
48 9 christian
For example, in one of my systems ir-keytable returns:
49 9 christian
<pre># ir-keytable
50 9 christian
Found /sys/class/rc/rc0/ (/dev/input/event7) with:
51 9 christian
        Driver imon, table rc-imon-pad
52 9 christian
        Supported protocols: RC-6 other
53 9 christian
        Enabled protocols: RC-6
54 9 christian
        Repeat delay = 500 ms, repeat period = 33 ms</pre>
55 9 christian
56 10 christian
I also force my imon receiver (to generate the above) to use the RC6 protocol and the imon_mce keytable instead of the default imon protocol and imon keymap using:
57 1
<pre>/usr/bin/ir-keytable -c -p RC6 -w /etc/rc_keymaps/imon_mce</pre>
58 10 christian
59 10 christian
I test the output of my driver using "ir-keytable -t" which yields output such as:
60 10 christian
<pre># ir-keytable -t
61 10 christian
Testing events. Please, press CTRL-C to abort.
62 10 christian
1330396066.132941: event MSC: scancode = 800ff418
63 10 christian
1330396066.132950: event key down: KEY_PAUSE (0x0077)
64 10 christian
1330396066.132951: event sync</pre>
65 10 christian
66 10 christian
*NOTE:* for "ir-keytable -t" to work, lirc must not be running. Disable lirc using *"sv stop lircd"*.
67 10 christian
68 10 christian
If your keymap file does not match the input protocol from the driver then you will only see output similar to:
69 10 christian
<pre># ir-keytable -t
70 10 christian
Testing events. Please, press CTRL-C to abort.
71 10 christian
1330396066.132941: event MSC: scancode = 800ff418
72 10 christian
1330396066.132951: event sync</pre>
73 10 christian
74 10 christian
It is important to note that if you use lirc then the code numbers (such as (0x0077)) are used by lircd.conf.
75 18 christian
76 1
h3. Remote Driver Event interface
77 10 christian
78 23 christian
The Remote Driver will output events to only one of the standard keyboard/mouse interface, /dev/lirc?, or devinput. If you do not enable lirc then the driver will default to the standard keyboard/mouse event interface. In most cases this will be fine for mythtv and will be the simplest way to implement your system.
79 10 christian
80 27 christian
If however, you want to use some of lirc's higher functions such as irexec (I use this to have my remote shutdown the system) then you will want to use one of the other interfaces. In most cases there is nothing to do to create *devinput* but to use */dev/lirc?* you will need to specifically tell ir-keytable to use the lirc protocol in addition to any other protocols if it does not do so already. Use "ir-keytable" to see which protocols are enabled and see of LIRC is one of them. If not you can try "ir-keytable -p lirc" plus any other protocol such rc-6 to add it in.
81 10 christian
82 23 christian
If the lirc protocol is enabled and the driver supports it, you will see a file such as /dev/lirc0 or /dev/lirc1 etc. From here you can have lirc set up the way you always have in the past with your standard lircd.conf file. If the driver does not create */dev/lirc?* then chances are it only uses *devinput*. If you have to use *devinput* then you will likely not be able to use your normal lircd.conf file but instead you will need to use the standard *devinput* version of lircd.conf which is in "/usr/share/lirc/remotes/devinput/lircd.conf.devinput".
83 10 christian
84 23 christian
Normally all of the current driver to lirc associations are handled in */etc/sv/lircd/run* with a default to using */dev/lirc?*
85 10 christian
If the run file does not already do this then to hook lirc into the *devinput* interface you will need to create a file called */etc/runit/lirc.sh* which contains a line similar to:
86 10 christian
<pre>/usr/sbin/lircd -r -n --driver devinput -d /dev/input/by-id/usb-15c2_0043-event-if00 --output /var/run/lirc/lircd</pre>
87 10 christian
88 18 christian
h3. LIRC
89 10 christian
90 1
In LinHES, LIRC is normally running and is initiated and configured by */etc/sv/lircd/run*. To customize the lirc config files please refer to the "Remotes":http://linhes.org/projects/linhes/wiki/Remotes wiki entry.
91 11 christian
92 11 christian
Note if you are using *devinput* you will need to use the *devinput* version of lircd.conf. Depending on the driver this may still require some minor modification. The lircd.conf entries must match the number output (e.g. 0x0077) that you saw using "ir-keytable -t". If it does not then you will not see any output from lirc.
93 11 christian
94 11 christian
To test the output of lirc, you should use *irw*. If you have everything configured properly then you will see output similar to:
95 11 christian
<pre># irw
96 11 christian
0000000080010077 00 KEY_PAUSE devinput
97 1
0000000080010077 00 KEY_PAUSE_UP devinput</pre>
98 1
99 21 christian
More detailed information on LIRC, though somewhat outdated, can be found at: http://lirc.org/html/index.html
100 21 christian
101 18 christian
h3. lircrc
102 1
103 12 christian
Finally you need to map the key code maps from lircd.conf to specific execution. Lircrc takes these commands and applies specific rules such as what keyboard command to send based on the application calling it (eg. mythtv, irexec, mplayer, xine, etc). It also allows you to add rules such as absorb excessive key presses (eg. repeat=3) or insert delay (e.g. delay=1). Of course each lircrc entry must match the label output from lircd.conf. Using the examples above an entry might look like:
104 12 christian
<pre># Pause
105 12 christian
begin
106 12 christian
       prog = mythtv
107 12 christian
       button = KEY_PAUSE
108 12 christian
       config = P
109 12 christian
end</pre>
110 1
111 1
If this is configured properly then mythtv (and irexec, etc) will behave as you expect.
112 1
113 21 christian
For more information on lircrc see also: http://lirc.org/html/configure.html#lircrc_format
114 21 christian
115 19 christian
h3. MythTV Key Bindings
116 19 christian
117 19 christian
In most cases people do not modify the MythTV key bindings and thus the output of lircrc will normally map fine and in a consistent fashion. If for some reason you are convinced that the mapping up to lircrc is correct yet certain keys are not doing what you expect then you can verify the values assigned to the key bindings in the MythTV setup menu.
118 19 christian
119 19 christian
See Service Menu -> MythTV Configuration -> Edit Keys
120 19 christian
121 19 christian
In this menu you will see a list of "Contexts" in the left pane and the various key "Actions" in the right pane. Assigned keys are in the boxes at the bottom. Note you can add more than one key to the action you want and the defaults do that in some cases.
122 19 christian
123 1
Using the earlier example of *KEY_PAUSE* mapping to *P*, you can verify that Context of *TV Playback* -> *PAUSE* has a value of *P*.
124 19 christian
125 21 christian
For more information on MythTV keybindings see also: http://www.mythtv.org/wiki/Keybindings
126 19 christian
127 24 christian
h2. LinHES Important Remote Related Files
128 24 christian
129 24 christian
The following list of files & directories are used in LinHES to connect everything together.
130 24 christian
131 24 christian
h3. /etc/rc_keymaps
132 24 christian
133 25 christian
This directory contains the various keymaps for each type of remote. This keymap is used by ir-keytable and a default set of tables will be loaded based on the driver which gets loaded. This can be overridden as described in [[Architecture_and_Customization#ir-keytable]].
134 24 christian
135 24 christian
h3. /etc/sv/lircd/run
136 24 christian
137 25 christian
This file should NOT BE MODIFIED. This file contains the logic that starts lircd for each type of remote and links lircd to the relevant config files and sockets (connectors to other processes such as drivers). However you can look at it to determine the logic used for your remote. If you want to modify how lircd starts then see [[Architecture_and_Customization#/etc/runit/lirc.sh]].
138 24 christian
139 24 christian
h3. /etc/runit/lirc.sh
140 24 christian
141 24 christian
You can create this file and enter your custom lircd start up commands. If this file exists then /etc/sv/lircd/run will execute this file instead of its normal processing. Using the iMon example, lirc.sh would contain:
142 24 christian
<pre>/usr/sbin/lircd -r -n --driver devinput -d /dev/SoundGraph --output /var/run/lirc/lircd</pre>
143 24 christian
144 24 christian
h3. ~/remotes
145 24 christian
146 24 christian
Typically ~/remotes is /home/mythtv/remotes.
147 24 christian
148 24 christian
This directory contains any custom remotes you have defined. In ~/remotes you would create a sub-directory with the name of the remote you want to create. Inside this sub directory you can create your own custom lircd.conf and lircrc files. You can also include a picture. Once this is created your new remote will be available from the LinHES service menu for selection among all of the standard remotes.
149 24 christian
150 24 christian
h3. /usr/MythVantage/templates
151 24 christian
152 24 christian
This directory contains all of the standard files for remotes, LCD, transmitters, etc.
153 24 christian
* remotes - LinHES remotes and associated lircrc and lircd.conf files.
154 24 christian
* LCD - LCD configuration files for various LCD and VFD types
155 24 christian
* transmit - LinHES transmitters (e.g. IR)
156 24 christian
157 24 christian
h3. /etc/lircd.conf
158 24 christian
159 24 christian
Sometimes also in /etc/lirc/lircd.conf
160 24 christian
161 24 christian
This file should NOT BE MODIFIED. If you used the service menu then this file should contain one or more UNIQUE includes from either /usr/MythVantage/templates or ~/remotes. These includes will reference either the standard or your custom definitions.
162 24 christian
163 24 christian
h3. /etc/lircrc
164 24 christian
165 24 christian
Sometimes also in /etc/lirc/lircrc
166 24 christian
167 24 christian
This file should NOT BE MODIFIED. If you used the service menu then this file should contain one or more UNIQUE includes from either /usr/MythVantage/templates or ~/remotes. These includes will reference either the standard or your custom definitions.
168 24 christian
169 21 christian
170 18 christian
h2. Tools
171 1
172 1
With the changes to the architecture in LinHES 7 (and linux in general) usage of tools related to remotes has changed to some degree. For example, *mode2* which used to test the output of the Remote Driver is now replaced by *ir-keytable -t*. Below is a list of the common tools used to trace your message flow:
173 18 christian
174 12 christian
h3. lsusb
175 12 christian
176 12 christian
Lists USB devices including Remote Receivers attached via USB. You can use this to find the device type which the Remote Driver will find and map to.
177 1
178 18 christian
h3. ir-keytable -t 
179 12 christian
180 14 christian
*NOTE:* for "ir-keytable -t" to work, lirc must not be running. Stop lirc using *"sv stop lircd"*. After testing you can start lirc using "sv start lircd".
181 14 christian
182 27 christian
Shows the output of the In *Kernel Remote Driver* before it enters lirc. 
183 12 christian
* If you get no output then it could be any of the following:
184 1
** the driver is not set to a protocol that is actually being used by the Remote Receiver (e.g. RC-6, imon);
185 1
** the driver and Remote Receiver device are not connected;
186 1
** the wrong driver is mapped to the device;
187 1
* If you get only raw translated codes then your keymap file does not match the Remote Receiver and Remote. 
188 12 christian
* If you get translated output (e.g. KEY_PAUSE (0x0077)) then  the driver and keymap is working.
189 27 christian
190 27 christian
h3. mode2
191 27 christian
192 27 christian
This tool is part of the *Legacy Remote Driver* tool chain. It will show you the raw output of the Legacy Remote Driver before it is transformed by lircd.conf. The output codes should match the entries in lircd.conf. Note that in this case lircd.conf may be using maps and truncating part of the code to simplify the lircd.conf format. These masks, truncations and data size are defined at the beginning of the lircd.conf file.
193 12 christian
194 18 christian
h3. irw
195 12 christian
196 12 christian
Shows the output from lirc after being mapped through lircd.conf.
197 12 christian
198 12 christian
If you get no output from irw but ir-keytable worked then it may be any of the following:
199 1
* lirc is not connected through the correct event interface from the driver
200 1
* the output codes from ir-keytable do not match the entries in lircd.conf
201 21 christian
202 21 christian
h2. Reference Material