vcs.maemo.org Git - pierogi/blob - www/index.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   4 <title>
   5 Pierogi Universal Infrared Remote Control
   6 </title>
   7 </head>
   8 <body>
   9
  10 <h1 align="center">
  11 <img src="PierogiIcon.png">
  12 Pierogi
  13 <img src="PierogiIcon.png">
  14 </h1>
  15
  16 <h2 align="center">A Universal Infrared Remote Control App for the Nokia N900</h2>
  17
  18 <p>Welcome to the Pierogi website!  This web page and the app itself are
  19 still under active construction.  Until I have time to construct a proper
  20 home page, I'll just place a copy of the app's internal documentation below.
  21 If you have any questions or comments, please post a note on the
  22 <a href="https://garage.maemo.org/forum/?group_id=2286">Pierogi forum boards</a>
  23 or send a message to
  24 <a href="mailto:jpietrzak8@gmail.com">jpietrzak8@gmail.com</a>.  Also, a thread
  25 has been set up on
  26 <a href="http://talk.maemo.org/showthread.php?t=82243">talk.maemo.org</a>,
  27 containing a great deal of information.
  28 </p>
  29
  30 <h3>A note on licensing and such</h3>
  31 <p>
  32 I have placed Pierogi under the GNU General Public License, version 2.0 or
  33 later.  (Here is a
  34 <a href="http://www.gnu.org/licenses/gpl-2.0.html">link</a> to the terms of
  35 that license.)  In short, this places certain restrictions on how you can use
  36 the source code for this program (which you can find
  37 <a href="https://garage.maemo.org/plugins/ggit/browse.php/?p=pierogi">here</a>;
  38 if that link is not working for you, please send me a note).  The program
  39 itself is free for use, in whatever manner you wish to use it.
  40 </p>
  41
  42 <p>
  43 However, some kind folks have asked about donations, and I've decided I will
  44 go ahead and set up a Paypal donation site.  Any funds received will be put
  45 towards the purchase of a second N900 I can devote fully towards development
  46 work.  Thank you for your support!
  47 </p>
  48
  49 <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
  50 <input type="hidden" name="cmd" value="_s-xclick">
  51 <input type="hidden" name="hosted_button_id" value="K697WUWYDLNJA">
  52 <input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
  53 <img alt="" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
  54 </form>
  55
  56 <h1>Pierogi Documentation</h1>
  57
  58 <p>
  59 The Pierogi universal infrared remote controller is a single self-contained
  60 app capable of sending IR commands to a wide variety of devices.
  61 At the moment, it is oriented towards television, VCR, DVD, and Blu-ray
  62 devices, but a few other types of device have had their command sets entered.
  63 </p>
  64
  65 <p>
  66 In this app, each family of related infrared commands is collected into a
  67 "keyset".  As manufacturers commonly reuse a given set of commands rather
  68 than re-invent the wheel each time they come out with a new product, many
  69 devices can share the same keyset.
  70 </p>
  71
  72 <p>
  73 Pierogi also follows the classic concept of a universal remote, by having
  74 a common set of buttons that are reused for each device.  So, for example,
  75 the "power" button has the same name and is located in the same position,
  76 no matter what keyset is currently in use -- even if that keyset has a
  77 different name for "power", or has no "power" command at all.  (Check out
  78 the <a href="http://en.wikipedia.org/wiki/Universal_remote">Universal
  79 Remote wiki</a> for a description of universal remote controls, which
  80 includes a special mention of the N900!)
  81 </p>
  82
  83 <p>
  84 So in short, to use Pierogi, you first select an appropriate keyset, then
  85 press the appropriate buttons to control the target device.  More detail on
  86 the features of Pierogi is provided below.
  87 </p>
  88
  89 <h2>Using Pierogi</h2>
  90
  91 <p>
  92 The current Pierogi design is built around a tabbed window, each tab containing
  93 a group of related buttons.  Depending on the keyset that has been selected,
  94 some of these buttons will be active, others inactive.  Active buttons are ones
  95 which have been associated with a command in the current keyset.  Pressing an
  96 active button will begin repeating the associated command; letting up on the
  97 button will stop the command.
  98 </p>
  99
 100 <p>
 101 Keysets can be chosen using the "Select Keyset" option in the drop-down menu.
 102 If you have a particular keyset you use often, it can be stored in the
 103 "favorites" tab for quick access.
 104 </p>
 105
 106 <h3>Main Window</h3>
 107
 108 <h4>Main Tab</h4>
 109
 110 <img src="MainTab.png">
 111
 112 <p>The Main tab contains just the power, volume, mute, and channel buttons.
 113 It is intended to be a quick way to get to the most important, commonly used
 114 controls.  The name of the current keyset is also provided in this tab.</p>
 115
 116 <h4>Utility Tab</h4>
 117
 118 <img src="UtilityTab.png">
 119
 120 <p>The Utility tab contains a selection of commonly useful controls, such as
 121 "Sleep", "Input", "Closed Captions / Subtitles", and the color buttons.
 122 This tab is intended to be a quick way to reach the most frequently used
 123 buttons; as such, the selection may be updated in future versions of Pierogi.
 124 </p>
 125
 126 <h4>Keypad Tab</h4>
 127
 128 <img src="KeypadTab.png">
 129
 130 <p>This tab provides a numeric keypad and a handful of associated commands,
 131 intended mainly for use with televisions.  The "Prev Channel" button should
 132 take you to the previously selected channel, if any.  The "Dash" button
 133 should allow you to specify a digital subchannel, as in "16-4".  The "+100"
 134 button is used for television sets which normally expect only two digits
 135 per channel; using this button allows you to enter a third digit.  The "-/--
 136 Double Digit" button is used on very old televisions that normally expect
 137 channels to be represented by just a single digit; pressing this should
 138 allow you to enter a second digit.</p>
 139
 140 <h4>Menu Tab</h4>
 141
 142 <img src="MenuTab.png">
 143
 144 <p>This tab contains buttons used to enter and exit a menu, navigate within
 145 a menu, and select menu entries.  The "Menu" button is meant to enter the
 146 main system menu of a given device; "Guide" is a content-related menu available
 147 on many modern devices; and "Disc Menu" is used to access the menu interface
 148 provided with DVD and Blu-Ray media.</p>
 149
 150 <h4>Media Tab</h4>
 151
 152 <img src="MediaTab.png">
 153
 154 <p>Many of the most important playback commands are represented on this tab.
 155 "Play", "Pause", and "Stop" are the most common ones, along with "Reverse"
 156 (often called rewind) and "Fast Forward".  A variety of other less common
 157 navigation controls are included, along with the "Eject" command.</p>
 158
 159 <h4>Favorite Tab</h4>
 160
 161 <img src="FavoriteTab.png">
 162
 163 <p>As there are numerous keysets available in Pierogi, a "Favorite" tab has
 164 been implemented.  To add a favorite keyset to the tab, first select that
 165 keyset from the "Select Keyset" window.  Then, navigate to the Favorite tab
 166 and press "Add Current Keyset".</p>
 167
 168 <p>Once you have added some keysets to the favorites list, you can tell
 169 Pierogi to use one by simply selecting that keyset from the list.</p>
 170
 171 <p>A keyset can be removed from the list by selecting it and pressing
 172 "Remove Selected Keyset".</p>
 173
 174 <p>
 175 Also note that the volume control keys on the top left side of the N900 can
 176 also be used to step through the list of favorite keysets, no matter what tab
 177 you are currently on.
 178 </p>
 179
 180 <h3>Select Keyset Window</h3>
 181
 182 <img src="SelectKeysetWindow.png">
 183
 184 <p>The Select Keyset window presents a list of all the keysets currently
 185 available in Pierogi.  As this list is fairly long, buttons have been added
 186 at the top of the window to choose the make and/or type of device for
 187 the product you are trying to control; all keysets not associated with
 188 the chosen values will be hidden.  To use a keyset,
 189 simply select it from the list, and close the window (by pressing the
 190 return arrow at the top right of the screen).</p>
 191
 192 <h3>Secondary Buttons Window</h3>
 193
 194 <h4>TV Tab</h4>
 195
 196 <img src="TVTab.png">
 197
 198 <p>This page contains several more TV-oriented buttons, including controls for
 199 picture-in-picture, teletext, and some graphics and audio controls.  The
 200 content of this page is subject to change.</p>
 201
 202 <h4>Media2 Tab</h4>
 203
 204 <img src="Media2Tab.png">
 205
 206 <p>This is another page of media buttons, containing a mix of commands useful
 207 for DVD players, VCRs, audio devices, and possibly other devices.  The content
 208 of this page may change in the future.</p>
 209
 210 <h4>Input Tab</h4>
 211
 212 <img src="InputTab.png">
 213
 214 <p>
 215 Many devices have multiple sources for their data, whether it be television
 216 signals piped in over the air or through a cable, or audio from a variety of
 217 stereo components.  It is unlikely that Pierogi will ever be able to list all
 218 of the various possible input buttons, but this tab contains a few of them.
 219 </p>
 220
 221 <h4>Adjust Tab</h4>
 222
 223 <img src="AdjustTab.png">
 224
 225 <p>
 226 A handful of the various audio and video adjustment buttons are placed on
 227 this tab.  Actual volume controls will likely remain on the main window,
 228 however.
 229 </p>
 230
 231 <h2>Design Rationale</h2>
 232
 233 <p>Here I collect my thoughts on the how and why of creating Pierogi.</p>
 234
 235 <h3>Hasn't this been done before?</h3>
 236
 237 <p>Yes, remote control software has already been written for the N900.  In
 238 particular, the
 239 <a href="http://irreco.garage.maemo.org/">Irreco / QtIrreco</a> project
 240 creates beautiful virtual remote controls.  I've also used the
 241 <a href="http://thp.io/2010/raemote/">Raemote</a> widget to control my Apple
 242 computers.  But these programs have their shortcomings; in particular, they
 243 are not universal.  Each simulated remote control in QtIrreco is a completely
 244 separate animal.  I would like to have a standard set of buttons that I can
 245 use on all sorts of different hardware.</p>
 246
 247 <h3>What's up with LIRC?</h3>
 248
 249 <p>Just as QtIrreco and Raemote do, I want to leverage the work of the
 250 <a href="http://www.lirc.org/">Linux Infrared Remote Control</a> project.
 251 The LIRC project is by far the most influential open-source effort working
 252 with consumer IR.  And the N900 comes with a device driver made
 253 specifically for their server!  But, you see, I have a problem.  I
 254 don't want to do things the way LIRC wants to do things.</p>
 255
 256 <p>The N900 is different from other Linux systems using IR -- rather than
 257 being the machine at which you point a remote control, this machine <i>is</i>
 258 the remote control.  This is not what LIRC was designed for; the heart of the
 259 LIRC project is a server that will sit and wait for messages to arrive from
 260 the IR system.  Although it can also broadcast IR data back out (when using
 261 hardware that supports 2-way IR communication), that is not its primary
 262 purpose.</p>
 263
 264 <p>I believe there are three disadvantages to using the LIRC server as it
 265 currently exists.  First, there isn't much point to running a daemon on
 266 the N900 to manage the IR device; no messages are ever going to come in from
 267 the output-only hardware on the N900, so why sit and listen for them?</p>
 268
 269 <p>The second problem is somewhat larger.  LIRC uses configuration files to
 270 describe the command set for each remote control.  And there are a lot of them.
 271 A whole lot.  We're talking thousands of files here, and each file can describe
 272 many remote controls.  This is not a problem for Raemote or Irreco, as they
 273 only need to deal with one config file at a time.  But if you're aiming to
 274 manage the whole lot of them, you need to find a way to deal with the
 275 multitudes.</p>
 276
 277 <p>The third problem is more subtle, but really tough to crack.  You see, the
 278 whole point of LIRC is to take the commands it receives from the IR port and
 279 translate them into something recognizable.  As such, each config file provides
 280 a mapping from numeric commands to human-readable strings.  This is a
 281 serious problem, if your interest is in finding similar commands in
 282 different config files!  Take, for example, the "power"
 283 button found on most remote controls.  In some config files, the string for
 284 this is "power".  Others have "Power", or "POWER".  You can also find "pwr",
 285 "PWR", "ON/OFF", "ON-OFF", "ONOFF", "POWER_ON_OFF", "KEY_POWER", "Operate",
 286 "Standby", and who knows what else.  And, you've gotta be careful not to get
 287 confused by strings like "SUBTITLE_ON/OFF" or "TV_ON_TIMER".  How is an app to
 288 know which key to map all these strings to?</p>
 289
 290 <h3>So how is Pierogi different?</h3>
 291
 292 <p>
 293 Pierogi attempts to answer these problems.  First, it talks directly to the
 294 /dev/lirc0 device, no server middleman needed.  Yes, you can use Pierogi
 295 without the LIRC daemon running; in fact, there's no need to ever install it.
 296 Second, Pierogi is built
 297 around the concept of the "keyset"; all IR codes that can share the same
 298 protocol without interfering with one another are combined into a single
 299 family of related commands.  In short, this reduces the quantity of data
 300 available from LIRC config files to something much more manageable.</p>
 301
 302 <p>The third problem mentioned above is a bit harder to solve; I'm currently
 303 mapping each LIRC string to a corresponding Pierogi key by hand.  Naturally,
 304 this process will be fraught with errors; I intend to keep updating Pierogi
 305 as these errors are found and fixed.
 306 </p>
 307
 308 <h2>Internal Design Notes</h2>
 309
 310 <p>If you're interested in the ugly details of the code, read on!</p>
 311
 312 <h3>What's up with the name of this app?</h3>
 313
 314 <p>Lately I've been naming my projects after tasty foods.  In particular,
 315 I've been working my way through the pasta-oriented dishes.  (My previous
 316 project, "Linguine", has gotten bogged down, so I moved on to this one...)</p>
 317
 318 <h3>Why use Qt?</h3>
 319
 320 <p>I'm a C++ kind of guy, it just makes sense to me to use a C++ kind of
 321 interface.  The Qt classes have everything you need to set up a decent UI,
 322 and Qt Creator makes coding up a project for the N900 relatively
 323 painless.  Check it out for yourself at
 324 <a href="http://qt.nokia.com/">the Qt webpage</a>.
 325 </p>
 326
 327 <h3>The simplest device ever!</h3>
 328
 329 <p>If you ever wanted to learn how to work with device drivers on Linux, the
 330 N900's infrared port is the device you want to start with.  It's not
 331 much more than a flashlight: You turn it on.  You turn it off.  You turn it on
 332 again.  You turn it off again.  You really can't get much simpler than that.
 333 Interaction with the "/dev/lirc0" device involves no more than handing
 334 it an array of integers: the first integer being an amount of time to keep the
 335 light lit (in microseconds), the second being an amount of time to leave it
 336 switched off, the third on, the fourth off, and so on.</p>
 337
 338 <p>Well, ok, so it involves just a little bit more than that.  You don't want
 339 to leave the light stuck in the "on" state when you are finished, so the driver
 340 demands that the last item in every array be an "on" amount -- after finishing
 341 that timer, the IR will stay off until the next command arrives.
 342 </p>
 343
 344 <p>
 345 Also, in an attempt to weed out any confusing signals from natural IR sources
 346 in the environment, consumer IR devices are "pulsed" at a particular
 347 frequency.  So you're really turning a strobelight on and off, not just a
 348 flashlight.  When the receiver sees that the light is coming from a strobelight
 349 pulsing at the desired frequency, it can be assured that that signal came from
 350 an actual remote control.  The N900's device driver allows you to set the
 351 frequency anywhere between 20000 Hz and 500000 Hz.  38000 Hz seems to the most
 352 popular frequency used by modern remote controls, at least from what you find
 353 in LIRC config files.  Also, you can set how long each pulse needs to be held,
 354 in terms of a percentage: 25% means turning the light on for just one quarter
 355 of the pulse, 33% means leaving it on for one third, etc.  This is called the
 356 "duty cycle", and can be anywhere between 0 and 100 percent.  LIRC's default
 357 duty cycle is 50 percent.
 358 </p>
 359
 360 <p>And that's about it.  I've been using a
 361 <a href="http://svn.jacekowski.org/host_mode/trunk/drivers/input/lirc/lirc_rx51.c">web page</a>
 362 that lists the source code for the IR device driver.  I'm not sure if there's
 363 a better location out there for N900 source code, but this seems accurate
 364 so far.</p>
 365
 366 <h3>You did <i>what</i> to the LIRC daemon?</h3>
 367
 368 <p>
 369 Well, ok, yeah, I've cannibalized the transmission code out of the LIRC
 370 server and dumped it into my app.  Sort of.  I can't really keep my hands off
 371 of code once I've seen it, so I've rewritten it in C++, reorganizing it in
 372 an object-oriented manner along the way.</p>
 373
 374 <p>
 375 As I have progressed in adding support for additional IR protocols, I'm
 376 beginning to see why the authors of the LIRC made the attempt to compress
 377 every possible IR protocol into a straightforward count of individual IR
 378 pulses.  The total number of IR protocols in use is amazing, and many of them
 379 (through oversight or due to the longevity of their use) are mind-numbingly
 380 complicated to deal with.  Still, I believe that separating the major protocols
 381 into their own code paths results in code that is easier to understand and
 382 maintain; I'm slowly moving away from the LIRC's system to my own as time
 383 goes on.
 384 </p>
 385
 386 <p>
 387 In any case, I owe the LIRC authors a deep debt of gratitude for their
 388 efforts.  If you are one such author, thank you.  As Pierogi is more-or-less
 389 derived directly from their work, it is also licensed under the same terms,
 390 the GNU General Public License (GPL) version 2 or later.
 391 </p>
 392
 393 <h2>Attribution</h2>
 394
 395 <p>I've fallen in love with the Gentleface Mono Icon Set.  Of the creative
 396 commons icon sets available, theirs stands head and shoulders above the rest.
 397 Find their work at <a href="http://www.gentleface.com">www.gentleface.com</a>.
 398
 399 <h2>References</h2>
 400
 401 <p>A set of links to some resources I've used while writing the code.</p>
 402
 403 <ul>
 404 <li>The center of the Linux infrared world, the
 405 <a href="http://www.lirc.org/">Linux Infrared Remote Control</a> project.
 406
 407 <li>A <a href="http://en.wikipedia.org/wiki/Consumer_IR">Wiki page</a> with
 408 general info on consumer IR
 409
 410 <li>A <a href="http://www.sbprojects.com/knowledge/ir/index.php">good introduction</a>
 411 to the theory and practice behind consumer IR devices
 412
 413 <li>A <a href="http://en.wikipedia.org/wiki/RC-5">Wiki for the RC-5 protocol</a>
 414
 415 <li>Some <a href="http://www.sbprojects.com/knowledge/ir/nec.php">Info on the NEC protocol</a>
 416
 417 <li>Some <a href="http://www2.renesas.com/faq/en/mi_com/f_com_remo.html">More info on the NEC protocol</a>
 418
 419 <li>An introduction to the <a href="http://www.sbprojects.com/knowledge/ir/sirc.php">Sony SIRC protocol</a>
 420
 421 <li>An excellent collection of <a href="http://www.hifi-remote.com/sony/">Sony command codes</a>
 422
 423 <li>Link to (what appears to be) source code for the N900's
 424 <a href="http://svn.jacekowski.org/host_mode/trunk/drivers/input/lirc/lirc_rx51.c">/dev/lirc0 device driver</a>.
 425
 426 <ul>
 427
 428 </body>
 429 </html>