3 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
10 <h1>Pierogi Documentation</h1>
13 The Pierogi universal infrared remote controller is a single self-contained
14 app capable of sending IR commands to a wide variety of devices.
15 At the moment, it is oriented towards television, VCR, DVD, and Blu-ray
16 devices, but a few other types of device have had their command sets entered.
20 In this app, each family of related infrared commands is collected into a
21 "keyset". As manufacturers commonly reuse a given set of commands rather
22 than re-invent the wheel each time they come out with a new product, many
23 devices can share the same keyset.
27 Pierogi also follows the classic concept of a universal remote, by having
28 a common set of buttons that are reused for each device. So, for example,
29 the "power" button has the same name and is located in the same position,
30 no matter what keyset is currently in use -- even if that keyset has a
31 different name for "power", or has no "power" command at all.
35 So in short, to use Pierogi, you first select an appropriate keyset, then
36 press the appropriate buttons to control the target device. More detail on
37 the features of Pierogi is provided below.
40 <h2>Using Pierogi</h2>
43 The current Pierogi design is built around a series of control panels, with
44 each panel containing a group of related buttons. Depending on the keyset
45 chosen, some of these buttons will be active, others inactive. Pressing an
46 active button will begin repeating the associated command; letting up on the
47 button will stop the command.
51 Keysets can be chosen using either the "Select Keyset by Name" or "Select
52 Keyset by Device" options in the drop-down menu. If you have a particular
53 keyset you use often, it can be stored in the "favorites" panel for quick
61 <p>The Main panel contains just the power, volume, mute, and channel buttons.
62 It is intended to be a quick way to get to the most important, commonly used
63 controls. The name of the current keyset is also provided in this panel.</p>
65 <h4>Utility Panel</h4>
67 <p>The Utility panel contains a selection of commonly useful controls, such as
68 "Sleep", "Input", "Closed Captions / Subtitles", and the color buttons.
69 This panel is intended to be a quick way to reach the most frequently used
70 buttons; as such, the selection may be updated in future versions of Pierogi.
75 <p>This panel provides a numeric keypad and a handful of associated commands,
76 intended mainly for use with televisions. The "Prev Channel" button should
77 take you to the previously selected channel, if any. The "Dash" button
78 should allow you to specify a digital subchannel, as in "16-4". The "+100"
79 button is used for television sets which normally expect only two digits
80 per channel; using this button allows you to enter a third digit. The "-/--
81 Double Digit" button is used on very old televisions that normally expect
82 channels to be represented by just a single digit; pressing this should
83 allow you to enter a second digit.</p>
87 <p>This panel contains buttons used to enter and exit a menu, navigate within
88 a menu, and select menu entries. The "Menu" button is meant to enter the
89 main system menu of a given device; "Guide" is a content-related menu available
90 on many modern devices; and "Disc Menu" is used to access the menu interface
91 provided with DVD and Blu-Ray media.</p>
95 <p>Many of the most important playback commands are represented on this panel.
96 "Play", "Pause", and "Stop" are the most common ones, along with "Reverse"
97 (often called rewind) and "Fast Forward". A variety of other less common
98 navigation controls are included, along with the "Eject" command.</p>
100 <h4>Media2 Panel</h4>
102 <p>This is another panel of media buttons, containing a mix of commands useful
103 for DVD players, VCRs, audio devices, and possibly other devices. The content
104 of this page may change in the future.</p>
108 <p>This panel contains several more TV-oriented buttons, including controls for
109 picture-in-picture, teletext, and some graphics and audio controls. The
110 content of this page is subject to change.</p>
115 Many devices have multiple sources for their data, whether it be television
116 signals piped in over the air or through a cable, or audio from a variety of
117 stereo components. It is unlikely that Pierogi will ever be able to list all
118 of the various possible input buttons, but this panel contains a few of them.
121 <h4>Adjust Panel</h4>
124 A handful of the various audio and video adjustment buttons are placed in
128 <h4>Air Conditioner Panel</h4>
131 This panel includes several controls commonly found on remotes used for
135 <h4>Favorites Panel</h4>
138 As there are numerous keysets available in Pierogi, a "Favorites" panel has
139 been implemented. To add a favorite keyset to the panel, first select that
140 keyset from either the "Select Keyset by Name" or "Select Keyset by Device"
141 windows. Then, navigate to the Favorites panel and press "Add Current Keyset".
145 Once you have added some keysets to the favorites list, you can tell
146 Pierogi to use one by simply selecting that keyset from the list. You can
147 also switch between keysets on the favorites list by pressing either of the
148 volume control keys on the top left side of the N900; this allows you to
149 change the keyset regardless of which panel is currently visible.
153 A keyset can be removed from the list by selecting it and pressing
154 "Remove Selected Keyset".
158 <h3>Select Keyset by Name Window</h3>
161 The Select Keyset by Name window presents a list of all the keysets currently
162 available in Pierogi. As this list is fairly long, a button has been added
163 at the top of the window that allows you to filter the list by the make of the
164 device you are trying to control; all keysets not associated with the chosen
165 make will be hidden. To use a keyset, simply select it from the list,
166 and then close the window (by pressing the return arrow at the top right of
171 <h3>Select Keyset by Device Window</h3>
174 Similar to the Select by Name window, this window provides a list of the
175 devices known to work with Pierogi. This list can be filtered either by
176 the make or the type of device. Choosing an entry from this list will
177 activate the keyset associated with the chosen device.
181 Please note that this is nowhere near an exhaustive list of the devices
186 <h3>Manage Panels Window</h3>
189 Each of the panels available in Pierogi can be switched on or off using this
190 window. Simply set a check in the panel's checkbox to make it available in
191 the main window, and un-check it to make the panel go away.
195 <h2>Design Rationale</h2>
197 <p>Here I collect my thoughts on the how and why of creating Pierogi.</p>
199 <h3>Hasn't this been done before?</h3>
201 <p>Yes, remote control software has already been written for the N900. In
203 <a href="http://irreco.garage.maemo.org/">Irreco / QtIrreco</a> project
204 creates beautiful virtual remote controls. I've also used the
205 <a href="http://thp.io/2010/raemote/">Raemote</a> widget to control my Apple
206 computers. But these programs have their shortcomings; in particular, they
207 are not universal. Each simulated remote control in QtIrreco is a completely
208 separate animal. I would like to have a standard set of buttons that I can
209 use on all sorts of different hardware.</p>
211 <h3>What's up with LIRC?</h3>
213 <p>Just as QtIrreco and Raemote do, I want to leverage the work of the
214 <a href="http://www.lirc.org/">Linux Infrared Remote Control</a> project.
215 The LIRC project is by far the most influential open-source effort working
216 with consumer IR. And the N900 comes with a device driver made
217 specifically for their server! But, you see, I have a problem. I
218 don't want to do things the way LIRC wants to do things.</p>
220 <p>The N900 is different from other Linux systems using IR -- rather than
221 being the machine at which you point a remote control, this machine <i>is</i>
222 the remote control. This is not what LIRC was designed for; the heart of the
223 LIRC project is a server that will sit and wait for messages to arrive from
224 the IR system. Although it can also broadcast IR data back out (when using
225 hardware that supports 2-way IR communication), that is not its primary
228 <p>I believe there are three disadvantages to using the LIRC server as it
229 currently exists. First, there isn't much point to running a daemon on
230 the N900 to manage the IR device; no messages are ever going to come in from
231 the output-only hardware on the N900, so why sit and listen for them?</p>
233 <p>The second problem is somewhat larger. LIRC uses configuration files to
234 describe the command set for each remote control. And there are a lot of them.
235 A whole lot. We're talking thousands of files here, and each file can describe
236 many remote controls. This is not a problem for Raemote or Irreco, as they
237 only need to deal with one config file at a time. But if you're aiming to
238 manage the whole lot of them, you need to find a way to deal with the
241 <p>The third problem is more subtle, but really tough to crack. You see, the
242 whole point of LIRC is to take the commands it receives from the IR port and
243 translate them into something recognizable. As such, each config file provides
244 a mapping from numeric commands to human-readable strings. This is a
245 serious problem, if your interest is in finding similar commands in
246 different config files! Take, for example, the "power"
247 button found on most remote controls. In some config files, the string for
248 this is "power". Others have "Power", or "POWER". You can also find "pwr",
249 "PWR", "ON/OFF", "ON-OFF", "ONOFF", "POWER_ON_OFF", "KEY_POWER", "Operate",
250 "Standby", and who knows what else. And, you've gotta be careful not to get
251 confused by strings like "SUBTITLE_ON/OFF" or "TV_ON_TIMER". How is an app to
252 know which key to map all these strings to?</p>
254 <h3>So how is Pierogi different?</h3>
257 Pierogi attempts to answer these problems. First, it talks directly to the
258 /dev/lirc0 device, no server middleman needed. Yes, you can use Pierogi
259 without the LIRC daemon running; in fact, there's no need to ever install it.
260 Second, Pierogi is built
261 around the concept of the "keyset"; all IR codes that can share the same
262 protocol without interfering with one another are combined into a single
263 family of related commands. In short, this reduces the quantity of data
264 available from LIRC config files to something much more manageable.</p>
266 <p>The third problem mentioned above is a bit harder to solve; I'm currently
267 mapping each LIRC string to a corresponding Pierogi key by hand. Naturally,
268 this process will be fraught with errors; I intend to keep updating Pierogi
269 as these errors are found and fixed.
272 <h2>Internal Design Notes</h2>
274 <p>If you're interested in the ugly details of the code, read on!</p>
276 <h3>What's up with the name of this app?</h3>
278 <p>Lately I've been naming my projects after tasty foods. In particular,
279 I've been working my way through the pasta-oriented dishes. (My previous
280 project, "Linguine", has gotten bogged down, so I moved on to this one...)</p>
284 <p>I'm a C++ kind of guy, it just makes sense to me to use a C++ kind of
285 interface. The Qt classes have everything you need to set up a decent UI,
286 and Qt Creator makes coding up a project for the N900 relatively
287 painless. Check it out for yourself at
288 <a href="http://qt.nokia.com/">the Qt webpage</a>.
291 <h3>The simplest device ever!</h3>
293 <p>If you ever wanted to learn how to work with device drivers on Linux, the
294 N900's infrared port is the device you want to start with. It's not
295 much more than a flashlight: You turn it on. You turn it off. You turn it on
296 again. You turn it off again. You really can't get much simpler than that.
297 Interaction with the "/dev/lirc0" device involves no more than handing
298 it an array of integers: the first integer being an amount of time to keep the
299 light lit (in microseconds), the second being an amount of time to leave it
300 switched off, the third on, the fourth off, and so on.</p>
302 <p>Well, ok, so it involves just a little bit more than that. You don't want
303 to leave the light stuck in the "on" state when you are finished, so the driver
304 demands that the last item in every array be an "on" amount -- after finishing
305 that timer, the IR will stay off until the next command arrives.
309 Also, in an attempt to weed out any confusing signals from natural IR sources
310 in the environment, consumer IR devices are "pulsed" at a particular
311 frequency. So you're really turning a strobelight on and off, not just a
312 flashlight. When the receiver sees that the light is coming from a strobelight
313 pulsing at the desired frequency, it can be assured that that signal came from
314 an actual remote control. The N900's device driver allows you to set the
315 frequency anywhere between 20000 Hz and 500000 Hz. 38000 Hz seems to the most
316 popular frequency used by modern remote controls, at least from what you find
317 in LIRC config files. Also, you can set how long each pulse needs to be held,
318 in terms of a percentage: 25% means turning the light on for just one quarter
319 of the pulse, 33% means leaving it on for one third, etc. This is called the
320 "duty cycle", and can be anywhere between 0 and 100 percent. LIRC's default
321 duty cycle is 50 percent.
324 <p>And that's about it. I've been using a
325 <a href="http://svn.jacekowski.org/host_mode/trunk/drivers/input/lirc/lirc_rx51.c">web page</a>
326 that lists the source code for the IR device driver. I'm not sure if there's
327 a better location out there for N900 source code, but this seems accurate
330 <h3>You did <i>what</i> to the LIRC daemon?</h3>
333 Well, ok, yeah, I've cannibalized the transmission code out of the LIRC
334 server and dumped it into my app. Sort of. I can't really keep my hands off
335 of code once I've seen it, so I've rewritten it in C++, reorganizing it in
336 an object-oriented manner along the way.</p>
339 As I have progressed in adding support for additional IR protocols, I'm
340 beginning to see why the authors of the LIRC made the attempt to compress
341 every possible IR protocol into a straightforward count of individual IR
342 pulses. The total number of IR protocols in use is amazing, and many of them
343 (through oversight or due to the longevity of their use) are mind-numbingly
344 complicated to deal with. Still, I believe that separating the major protocols
345 into their own code paths results in code that is easier to understand and
346 maintain; I'm slowly moving away from the LIRC's system to my own as time
351 In any case, I owe the LIRC authors a deep debt of gratitude for their
352 efforts. If you are one such author, thank you. As Pierogi is more-or-less
353 derived directly from their work, it is also licensed under the same terms,
354 the GNU General Public License (GPL) version 2 or later.
359 <p>I've fallen in love with the Gentleface Mono Icon Set. Of the creative
360 commons icon sets available, theirs stands head and shoulders above the rest.
361 Find their work at <a href="http://www.gentleface.com">www.gentleface.com</a>.
365 <p>A set of links to some resources I've used while writing the code.</p>
368 <li>The center of the Linux infrared world, the
369 <a href="http://www.lirc.org/">Linux Infrared Remote Control</a> project.
371 <li>A <a href="http://en.wikipedia.org/wiki/Consumer_IR">Wiki page</a> with
372 general info on consumer IR
374 <li>A <a href="http://www.sbprojects.com/knowledge/ir/index.php">good introduction</a>
375 to the theory and practice behind consumer IR devices
377 <li>A <a href="http://en.wikipedia.org/wiki/RC-5">Wiki for the RC-5 protocol</a>
379 <li>Some <a href="http://www.sbprojects.com/knowledge/ir/nec.php">Info on the NEC protocol</a>
381 <li>Some <a href="http://www2.renesas.com/faq/en/mi_com/f_com_remo.html">More info on the NEC protocol</a>
383 <li>An introduction to the <a href="http://www.sbprojects.com/knowledge/ir/sirc.php">Sony SIRC protocol</a>
385 <li>An excellent collection of <a href="http://www.hifi-remote.com/sony/">Sony command codes</a>
387 <li>An in-depth investigation of the <a href="http://www.adrian-kingston.com/IRFormatPioneer.htm">Pioneer IR Protocol</a>
389 <li>Link to (what appears to be) source code for the N900's
390 <a href="http://svn.jacekowski.org/host_mode/trunk/drivers/input/lirc/lirc_rx51.c">/dev/lirc0 device driver</a>.
projects / pierogi / blob