Linux / MythTV driver for Sapphire TheatriX remote control

September/2022: Fixed compile/build to work with Linux kernel 5.6 and newer. Thanks to Pavel and Jeremy for their help.

September/2020: Added new MED_REPEAT speed for buttons. Implemented RAMP_RATE, SLOW_RATE, MED_RATE, and FAST_RATE keywords for the keymap file to set button repeat speeds.

September/2019: Tweaked Makefile to try and link /lib/modules/$KVER/build when missing. Not perfect, and doesn't deal with .0 kernel versions.

Also note for Raspberry Pi builds you'll to install the build-essential and raspberrypi-kernel-headers packages first.

February/2019: Tweaked sapphire_startup.sh courtesy of Andrew Ruthven.

I have a few of these remotes (new/unused) on hand that I no longer need. If you want one, you can have it for CAD$10+postage. I will ship by CanadaPost from Ottawa (should be much quicker than from China). Email me if interested.

November/2018: The driver now supports multiple simultaenous receivers (USB dongles) when used with a single remote. This can improve receiption/reliability, especially in larger rooms.

November/2018: These remotes are still available from a few sellers, but are getting more and more difficult to find. Here are some such eBay listings:
https://www.ebay.com/itm/172412033430
https://www.ebay.com/itm/292377960014
https://www.ebay.com/itm/401197076036

And here is another for replacment receivers (no control, just the USB dongle):
https://www.ebay.com/itm/172412044262

The thought was that this would be an excellent remote control for use with MythTV, particularly among friends and family who want to clone my small/simple ZBOX HD-ID41 based MythTV setup. Note that this remote control is NOT a true Windows MCE USB Remote, so it does not use the existing mceusb drivers from Linux and/or LIRC.

The Linux kernel does have a basic input driver for this device, called hid-topseed, but that is lacking in many ways. Most buttons don't work, auto-repeat is poor and inconsistent, some buttons behave as mouse functions while others act as keyboard keys, and customization for use with MythTV is not easy.

So.. I have written a replacement standalone driver to make this device extremely easy to use with MythTV. Installation is as simple as doing make install. Auto repeat works on the buttons for which it is useful, and different repeat rates can be configured for different buttons. Buttons can perform different functions when held down than when pressed/released more quickly. And the driver comes with most buttons already configured for use with MythTV's PVR functionility.

The driver consists of a pair of source files, sapphire.c and sapphire.h, which are easily edited (even by non-programmers) to customize button functionality. This driver is the only thing required --> no config files, no LIRC, no complexity.

As of version 3.0 and beyond, one may choose to maintain an external keymap file, and load it after each boot using the new sapphire_keymap.sh utility script. This provides better protection against the default keymap changing from release to release. A sample keymap file (keymap.default) is included in the tarball for use as a starting point for customization.

With this remote, the Power button can be used to wake up a system from "suspend-to-RAM" state, provided one first enables this via appropriate magic in /proc/acpi/wakeup. I use it here, and it works quite well.

Here is the package for download/install:

sapphire-7.5.tar.gz (tarball with source and Makefile).

Just download the tarball, and build/install it with these commands:

     tar xvf sapphire-7.5.tar.gz
     cd sapphire-7.5
     sudo make
     sudo make install

     /usr/local/bin/sapphire_startup.sh

If you really prefer the complexity of LIRC, then this remote control does also work with LIRC, using the original in-kernel driver (but probably not with my driver). I don't know much about that myself, but these links are reputed to provide some guidance:
http://www.minimyth.org/forum/viewtopic.php?f=1&t=2029&hilit=giarc
http://www.lirc.org/html/configure.html
https://wiki.archlinux.org/index.php/LIRC
http://www.hifi-remote.com/forums/viewtopic.php?p=34345#34345

Click on the image below for a larger view of the buttons available. The driver allows mapping every one of these to whatever function you like, with the tiny exception that the Enter and OK buttons are wired together in hardware, and cannot be programmed separately.

Still reading? This remote control really prefers alkaline (1.5V) AA cells for power, which give it a total of 3.0 volts internally. When using rechargeables, the voltage will be about 2.5-2.7 volts instead, which reduces the range of the transmitter.

To get some of that range back, one can crack open the transmitter, and short out the tiny "1R0" resistor located near the IR LED. I have done this mod to a few of my remotes here, and the effect is quite noticeable.

Also, I had one of these remotes here which was somewhat "flakey." Button repeats were not smooth or predictable. So, while I had it open for the resistor mod, I also wiped down the internal button contact surfaces with very pure alcohol, and doing so totally cured the problem.

Release History:

2018-12-10: Version 7.1 released: Internal tidy-ups; removed (unused) XAPPHIRE_* key definitions.

2018-11-19: Version 7.0 released: Support multiple simultaenous receivers for better reception from a single remote.

2018-02-19: Version 6.9 released: Removed leftover debug printk() from the new debounce logic, and updated Makefile to grok ko.xz suffix.

2018-02-19: Version 6.8 released: Updated for compatibility with Linux kernel 4.15, and added debounce logic for NO_REPEAT keys.

2017-07-23: Version 6.7 released: Fixed Makefile issue for systems that use gzipped kernel modules.

2016-04-24: Version 6.6 released: Updated scripts to cope with KEY_* definitions being moved from /usr/include/linux/input.h to /usr/include/linux/input-event-codes.h on Ubuntu-16.04.

2016-03-18: Version 6.5 released: Fixed installation issue where the scripts would complain that 'gawk' could not be found.

2016-03-18: Version 6.4 released: Added code to prevent system scripts from re-enabling USB autosuspend on the IR receiver.

2016-03-17: Version 6.3 released: Really solved the USB autosuspend issue this time!

2015-11-17: Version 6.2 released: Minor internal fussing to make the key timer slightly more robust.

2015-11-06: Version 6.1 released: Some tidying up, and a possible bug fix.

2015-10-16: Version 6.0 released: Tried (incorrectly, it seems) to disable USB autosuspend for the device.

2015-09-16: Version 5.9 released: Internal tweaks for better interworking with "glue" module. Also, /proc/sapphire now begins with elapsed_secs=0.

2014-08-26: Version 5.8 released: Fixed rmmod/insmod ordering in sapphire_startup.sh script -- Ubuntu/Debian users may benefit most.

2014-02-02: Version 5.7 released: Added RAWKEY flag to pass key press/release events directly to the Linux kernel input layer for repeat processing, rather than handling repeats within sapphire itself. Example: ## Numeric Keypad "cursor" control: SAPPHIRE_2 KEY_KP8 RAWKEY ## Let the kernel handle repeats/whatever SAPPHIRE_8 KEY_KP2 RAWKEY ## Let the kernel handle repeats/whatever SAPPHIRE_4 KEY_KP4 RAWKEY ## Let the kernel handle repeats/whatever SAPPHIRE_6 KEY_KP6 RAWKEY ## Let the kernel handle repeats/whatever

2014-01-29: Version 5.6 released: Added KEY_DELAY for use within macros -- inserts a half-second pause before continuing.

2014-01-21: Version 5.5 released: Improved workarounds for Ubuntu/Mint kernels: looking pretty solid now.

2014-01-21: Version 5.4 released: Check that the user has installed the required development libraries before building. Remove the driver workaround for b0rked Ubuntu kernels, and instead rely upon the improved build/startup scripts. This means that Ubuntu/Mint users will need to unplug/replug the dongle after the first install of the sapphire driver.

2014-01-20: Version 5.3 released: Work around an on-again / off-again kernel bug which was affecting Ubuntu-13.10 and Mint-16 users (among others). The sapphire_startup.sh script should now work on those systems. Also work around the "Can't read private key" error thrown by Ubuntu and Mint systems which attempt (badly) to implement MS-Windows style "signed modules" support for Linux (ugh).

2014-01-05: Version 5.2 released: Added a call to /usr/local/bin/sapphire_keymap.sh into sapphire_startup.sh to ensure that the local keymap file (/etc/sapphire.keymap) always gets loaded at startup. Also added an interlock to the keypress timer to prevent rare mis-repeats.

2013-12-14: Version 5.1 released: Fixed problem of erratic/unwanted repeats with newer Linux kernels (3.11+). Tested with linux-3.12.6.

2013-09-28: Version 5.0 released: Fixed issue with "sapphire_keymap.sh" failing due to multiple "gawk" binaries in $PATH.

2013-09-04: Version 4.9 released: Fixed compiler warnings / bug on 64-bit systems.

2013-08-18: Version 4.8 released: Added compatibility wrappers for the new /proc/ interfaces in Linux kernel 3.10.x. So the driver should now build/work again on the latest kernels.

2013-04-26: Version 4.7 released: Changed Makefile to check for absence of gawk in $PATH and print message if not found. This (missing gawk binary) may be the reason why the installer has been failing on some systems.

2013-04-08: Version 4.6 released: Changed permissions on /proc/sapphire to be world-writable, so that ordinary users can more easily change keymaps on the fly.

2013-04-07: Version 4.5 released: Added a new keymap command REPEAT_RATE to enable local customization of the ramping repeat timings. See the README.txt file for details.

2012-12-08: Version 4.4 released: Added a new script, /usr/local/bin/sapphire_startup.sh, to handle unbinding the device from hid-topseed before modprobing sapphire.ko. This permits use with newer distro kernels that have the hid-topseed driver built-in rather than as a (un)loadable kernel module. To use it, just add a call to the script into /etc/rc.local

2012-06-11: Version 4.3.1 released: Slight changes to the Makefile only; no change to the driver.

2012-05-16: Version 4.3 released: Changed default mapping for Music button to send "A" (Adjust Time Stretch).

2012-05-05: Version 4.2 released: Take two: Fixed a bug from v4.0/4.1 which was preventing macros from working.

2012-05-05: Version 4.1 released: Tried to fix a bug from v4.0 which was preventing some macros from working.

2012-05-03: Version 4.0 released: Lots of internal rework, new XAPPHIRE_* virtual button codes, much faster sapphire_keymap.sh script.

2012-04-27: Version 3.6 released: Fixed a glitch in the Makefile, to stop it reporting "Error 1" at the end.

2012-04-22: Version 3.5 released: Slight tweaks to the button repeat rates and inital pre-repeat delays. General code cleanups.

2012-04-22: Version 3.4 released: Makefile fixed to re-run sapphire_keymap.sh after modprobe. Fixed (benign) bug in sapphire_init(). Added a hook for using the sapphire driver/features with other IR receivers.

2012-04-22: Version 3.3 released: Updated sapphire_keymap.sh to no longer need source code access at runtime. Reduced execution time for sapphire_keymap.sh to under a second on most systems.

2012-04-15: Version 3.2 released: Fixed a bug in sapphire_keymap.sh whereby it would sometimes map the wrong keys. Changed default for "Teletext/CC" button to "T", matching the default MythTV key for "Toggle Closed Captions". Fixed repeat for macro keys. Added capability to inject a button press from shell scripts using "echo SENDKEY 0x00000000 > /proc/sapphire" (replace 0x00000000 with actual hex code for the desired KEY_* keycode). Added -v / --verbose flag to the sapphire_keymap.sh script.

2012-04-12: Version 3.1 released. Now allows use of modifiers (ALT,CTRL,SHIFT,META) within macros. Plus code cleanups, comments, Makefile improvements, and general housekeeping.

2012-04-11: Version 3.01 released. No driver changes, just some minor improvements to the sapphire_keymap.sh script.

2012-04-11: Version 3.0 released. This version adds macro capability, and also introduces a method for changing the key mappings on the fly via the included sapphire_keymap.sh script. Please see the included README.txt and sample keymap.default files for details on both features. There is also now a new RAMP_REPEAT option for buttons, whereby auto-repeat starts slowly but speeds up gradually over a couple of seconds if a button is held down.

2012-04-04: Version 2.2 released, which simply adds a mapping for the heretofore missed STOP button. The new default is for it to send a DASH/MINUS sign, for use with entering DTV subchannel numbers.

2012-04-04: Version 2.1 is now capable of distinguishing between short and long presses of a button. This allows the MUTE button to function normally as "Mute", but when held for one second it instead activates the "Adjust Audio Sync" pop-up. Other keys could also be defined in this fashion if desired.

2012-03-30: Version 2.0 now has new support for CTRL, SHIFT, ALT, and META modifiers. This allows for better out-of-the-box compatibility with the default MythTV key bindings, as well as more options for customization.