The WHAT and WHY of JP1
The WHAT and WHY of JP1
by Don Grovestine (March 22, 2004)
A few months ago, my coffee table was littered with remote controls. The one most used was a Millenium 4 provided by my cable company to control the DCT-2000 digital cable converter. The "Mil 4" (without JP1) was capable of controlling three other devices, and I had programmed it to do so - sort of. But, many of the functions on my TV still weren't available. It was the same with the VCR. And, every time I pressed one of several number keys on the remote while in the Audio mode, my receiver would switch to another input. Something had to change.
Then one day I stumbled across "remotecentral.com" and, from there, "hifi-remote.com". It wasn't long before I discovered the JP1 Forums (Forums) and the Yahoo! Groups JP1. I had found Nirvana.
Within hours, I'd ordered a JP1 cable, downloaded every file in sight and, over the next few days, read just about every post to the Forums - learning about other peoples' problems. But where was the "system documentation"? I had read and re-read Tommy Tyler's "JP1 for Beginners" and found it very helpful. It told me what tools to use and how to use them. But, with my programming and system engineering (and other things) background, I felt I needed more. I wanted to better understand what I was trying to do - from a system perspective - and why it was necessary. For a "newbie", having to infer everything from descriptions in the Forums of other peoples' problems and the experts' solutions was not ideal. There had to be a better way!
To make a long story short, after programming my Mil 4 using JP1 and still finding it wanting, I purchased a new One-For-All URC 8911. With the extender, my 8911 allowed me to do everything I wanted in controlling my expanding home theater system - but implementation was not without difficulty as several of my early posts to the Forums will attest.
Then, I started looking "behind the scenes" to learn the "whats" and "whys" of JP1. And that's what I would like to pass along.
Before going on to that, however, I want to offer my thanks to the current set of JP1 experts and, presumably, a few of their predecessors, who have "hacked" their way to the present state of JP1 and who patiently "held my hand" as I found my way through Nirvana. This manual is my way of giving back a little. I also want to thank the experts who took the time to read this manual and offer constructive criticism - in particular Jon Armstrong, who reviewed two draft versions in detail and made a number of suggestions for improvement. "The WHAT and WHY of JP1" is a better document because of them.
JP1 Remote Controls
Regardless of what label is on the front of your JP1 remote control, it was made by Universal Electronics Inc. (UEI). UEI markets its remotes to consumers under the "One-for-All" (OFA) brand name. The individual model numbers are usually preceded by "URC", presumably standing for "universal remote control". Radio Shack JP1-enabled remotes and those sold under other names are somewhat different in appearance from the OFA remotes. In some cases, they are also electronically different (e.g., some of the Radio Shack models have two IR LEDs (transmitters) while OFA remotes have only one). But, these remotes too are manufactured by UEI. UEI also markets another series of remotes, called OEM remotes, to manufacturers and marketers of cable converters, satellite receivers and other home theater components. These remotes generally will bear the name of, and may have otherwise been customized by, the component manufacturer/marketer.
Codes and Protocols
"Out of the box", a JP1 remote control is pre-programmed with a variety of manufacturer's codes and protocols.
A manufacturer's code defines:
- the infrared (IR) signal that the remote is to send to the associated equipment when a button on the remote is pressed, and
- the protocol, or signalling scheme, to be used.
A manufacturer's code has two specifiers:
- device type, e.g., TV, Cable, DVD, etc., which selects a particular button configuration on the remote, and
- a four-digit identifier known as the setup code.
Each device button on the remote, i.e., one of a set buttons that determines the home theater equipment component with which the remote communicates at any point in time (the active device) may be assigned a specific manufacturer's code. The device type is inherent in the name of the device button to which the manufacturer's code is assigned (though remotes often have provisions for changing the device type of a button). So, assigning a manufacturer's code to a device button involves pressing the remote's "Setup" key (sometimes designated the "P" key) until the remote gives a specific response, followed by a device button, thereby selecting a device type, and then entering the numeric setup code. This sequence is one of a series known as long-Setup-keypresses.
It should be noted that, while UEI refers to the stored data pertaining to specific devices as manufacturer's codes and, generally, that the term is so used in this manual, in the JP1 "world", the term setup code is sometimes used synonymously with manufacturer's code as well as referring just to the numeric identifier of a manufacturer's code .
A protocol is a program that momentarily takes control of the remote while it transmits (over the IR link) the button code specified in the manufacturer's code for the pressed key. Such protocols are sometimes called executors by UEI and in the Forums. The term protocol is also used to refer to the characteristics, or signature, of the IR signal. Consequently, one must be aware of the context in which the term is used.
Different home theater equipment requires the information transmitted by the protocol to be presented in different ways. There are one-byte protocols and two-byte protocols, i.e., protocols where all the information required to control a particular device operation (the command) is stored in a single byte and others where two bytes are transmitted . Some protocols transmit the least significant bit (LSB) of the command first, others transmit the most significant bit (MSB) first. Still others transmit in one's complement form, i.e., a binary 1 is replaced by a binary 0, and vice versa. Some protocols address a single device, others address multiple devices. And, of course, there are various information signalling schemes. The topic is so diverse that proper coverage is well beyond the scope of this manual.
Fortunately, so long as your equipment uses standard protocols, most of this complexity will be transparent. For example, each manufacturer's code completely specifies the protocol to be used in dealing with the physical device. So, when you program the manufacturer's code for a piece of equipment, you are inherently specifying the associated protocol - without having to worry about all its idiosyncrasies. If the setup code has been pre-programmed in the remote, the required protocol also will be pre-programmed. Even if you add to or replace the pre-programmed manufacturer's codes using device upgrades (see Section 5.5), in many cases, you will still make use of pre-programmed protocols. Should it be necessary to add a protocol to your remote, the JP1 tools make this a relatively painless affair.
Generally, the difficult part is in determining which protocol(s) and variants are required for a new piece of equipment, i.e., one not yet in broad use. (Learning remotes are very handy for this purpose.) However, for their own benefit, (and, also, fortunately for ours) home theater equipment manufacturers tend to be consistent in their use of protocols and key code schemes. Once a manufacturer selects a protocol for its equipment, it generally will use that same protocol and, often, the same key code arrangement across its then-current range of products of the same type. For example, most current Panasonic TVs use the TV/0250 setup code. Most new Toshiba home entertainment products (and a number of others) make use of the standard NEC1 protocol; but, the setup code number may vary between equipment types.
Nonetheless, from time to time this manual will remind you of the complexity noted above - but usually as a means to demonstrate some capability of JP1. For those who are interested in more detail, there are a number of articles on the web addressing the topic of IR generally and signalling schemes for home theater equipment. A good place to start is the Infrared section at hifi-remote.com.
A JP1 remote control, like any other universal remote, is a microprocessor-controlled device. Its main program, the operating system, responds to button presses, decodes the information in the remote's memory associated with the buttons that are pressed, including the codes to be sent to the physical device being controlled, and sends those codes to the appropriate device via an infrared (IR) signal.
In a remote's most basic operation, when a button other than a device button is pressed, the operating system:
- accesses the manufacturer's code assigned to the active device (generally, the device whose device button was pressed most-recently)
- determines from the manufacturer's code the information to be sent for the button that was pressed and the protocol that is to send it
- calls (prepares to execute) the program associated with the specified protocol, passing that information to the program and
- turns control over to the program which, using the IR transmitter, sends the information to the equipment using the specified protocol.
Once the protocol has done its job, it relinquishes control to the operating system which then idles, awaiting the next button press.
That's all there is to it! Of course, LEDs flash and LCDs get updated and backlights go on and off, but that's all incidental.
Programming the Remote Directly
Without JP1, the operation of JP1-enabled remotes may be altered in three main ways, other than by assigning setup codes to device buttons (as discussed above) and by learning as described in the manual (for those remotes that support that capability):
- by using a 9-9-4 long-Setup-keypress to enter an advanced code that will alter the code transmitted to the equipment from that specified in the manufacturer's code
- by using a 9-9-5 long-Setup-keypress to enter a macro, i.e., a series of keystrokes, on certain keys other that device keys; (when the key to which the macro is assigned is later pressed, it will effectively repeat the series of entered keystrokes)
- by having UEI upgrade the remote either by returning the remote to the factory or, in the case of present-day remotes, via telephone using the remote's built-in acoustic adapter.
Depending on the remote, other 9-x-x long-Setup-keypresses may be documented in the manual, but these are the main ones.
In the OFA manuals, at least, the 9-9-4 long-Setup-keypress is not documented at all and the 9-9-5 entry is noted as being applicable only to setting-up FAV lists and "Tune-In" keys. So, it's clear that UEI never intended for users to perform these expanded functions - perhaps for fear of the product support burden it would generate.
JP1 - The System
JP1 builds on the 9-9-4 and 9-9-5 long-Setup-keypress capabilities described in the previous section to allow the development of advanced code entries (also known as keymoves), macros and, indeed, complete device upgrades on a personal computer and their uploading into a JP1-enabled remote control.
Several weeks after this manual was first introduced, Rob Crowe published his "JP1 - Just How Easy is It?", in which he also deals with getting started with JP1.
JP1 is a system comprising:
- a JP1-enabled remote control
- a JP1 cable (parallel, serial and USB versions supported) for communication between computer and remote, and
- a personal computer on which the following programs/files are available:
- RDF files, which defines the characteristics of the remote controls of interest
- IR.exe program to format the data to be uploaded to the remote and handle the communications between computer and remote
- either Keymap-Master (a MS Excel-based tool commonly referred to as "KM") or the still-under-development RemoteMaster (a Java-based tool referred to as "RM"), both of which support the development of device and protocol upgrade files
- Devices4, another MS Excel-based tool that provides, for a given device setup code, the associated protocol details and the enhanced function codes and
- if planning to use an extender:
- ExtenderCodeCalc, a MS-Excel-based tool that is useful in setting up and debugging some of the features useable with extenders and
- ExtInstall, a special installation program that will consolidate your remote's existing configurations, i.e., keymoves, macros, etc. with an extender and its special protocols.
All these software tools are available from the Files section of Yahoo! Groups JP1. ExtInstall can be downloaded from the Files|Extenders subsection; most of the others can be found in the Files|Tools subsection. Note that the actual names of the program files stored at Yahoo! Groups JP1 may include a version number.
Each of these programs has one or more ReadMe files which, among other things, describe the installation and operating procedures and identifies other special requirements. As well, "JP1 for Beginners", available from the Files|Help subsection includes detailed downloading and operating instructions for IR.exe, KM and Devices4.
The JP1 tools are continually being enhanced and otherwise upgraded. To minimize preventable difficulties, you should always use the most recent version.
There are also a number of other utility programs that have been developed for specialized use in JP1 programming, including:
- ProtocolBuilder, for experienced JP1 users who wish to create new protocols, e.g., for IR controlled appliances around the home and home theater equipment not pre-programmed in the remote or supported by KM or RM
- ccf2efc - decodes Pronto ccf files into device, protocol and OBC/EFC, and provides Pronto hex useful for manual decoding by advanced users
- cml2efc - decodes RTI TheatreTouch files
- DecodeCCF - decodes a ccf file into a formatted text file that can be pasted into a spreadsheet. This is the most useful decoder of Pronto ccf files since it eliminates much of the information that would be returned by ccf2efc. It also works with all versions of ccf files
- IRTool - decodes Pronto hex text files typical of those found at remotecentral.com in that website's Files|Pronto|Discrete section.
The latter four programs require DecodeIR.dll to be present in the Windows\system directory. These tools also are available from the Files section of Yahoo! Groups JP1.
If you are simply programming a JP1 remote to manage devices for which you have, or can learn, the advanced codes and that use protocols already pre-programmed in the remote or supported by KM/RM, you will have no need for these specialized utilities.
The JP1 Cable
A JP1 cable is available from a number of mail-order sources (see hifi-remote.com). Being a relatively simple device, the cable can also be built "from scratch" with a minimum of parts. Full instructions are available from Yahoo! Groups JP1, in the Files|Interface Designs subsection.
The JP1 Connector
Most JP1-enabled remotes will have a six-pin connector mounted on the printed circuit board. The connector is accessible once the battery compartment cover is removed. However, some recently-introduced OFA remotes are no longer equipped at the factory with the connector (presumably to make hackers' lives more difficult) and instead, have only the six holes in the PCB where the connector would be mounted.
If a ready-made JP1 cable is purchased, it will probably be delivered with a pin header plugged into the cable - to avoid the pin header getting lost in the packing material. (If you don't look carefully, the header together with the connector at the remote end of the cable appears to be a male connector, rather than the female type required for connection to the remote, and you may assume that "they" sent the wrong cable.) If your remote already has a connector on its PCB, simply remove the header and set it aside. If your remote does not have a JP1 connector, you may either solder the pin header onto the PCB - if you or a friend are appropriately skilled (the Robman says you must use flux) - or simply leave it plugged into the cable and, when you want to upload or download data to/from the remote, press the (effectively male) connector into the mating holes in the PCB. Unfortunately, this latter practice sometimes does not result in a good electrical connection. An alternative is a "pogo pin adapter", which will allow better contact and which may be purchased from the same sources as JP1 cables.
Where Does the Uploaded Data Go?
The JP1 connection on the PCB allows direct access to the remote's eeProm - the non-volatile memory where keymoves, macros, learned instructions, and protocol and device upgrades are stored. Using the JP1 connection, keymoves and macros may be entered directly from a computer, rather than by long-Setup keypresses on the remote. Pre-programmed manufacturer's codes can be effectively modified using device upgrades and entirely new codes can be entered into the remote - all without reference to EUI.
RDF stands for remote definition file. As the name implies, a RDF describes the characteristics of a particular JP1-enabled remote. Among other things, a RDF declares a remote's eeProm memory allocations, identifies the key numbers assigned to every button on the remote, specifies the mapping of groups of buttons (the button map), and lists the IR protocols pre-programmed on the remote and the standard digit maps (sequences of codes for the numeric keys) supported by the remote.
The MSWord file "RDF3Spec.doc", available from the Files|Tools subsection of Yahoo! Groups JP1, provides a detailed description of the contents of current (version 4) RDF files. An important (and unalterable, unless you really want to make your life difficult) feature of each RDF is its name which, in part, is the signature of the remote it defines. The signature, which is stored in eeProm in the remote, is how JP1 identifies which remote it is dealing with.
While "RDF3Spec.doc" goes into great detail on certain aspects of the RDF, it is somewhat brief in two areas, i.e., button maps and digit maps.
A button map is a series of key numbers. Some of these key numbers are collected together between parenthesis, indicating keys that are treated as a group. On the URC 8911, the first set of key numbers is the numeric keys. These are followed by two more groups: the Vol+, Vol- and Mute keys and then the Ch+ and Ch- keys. The remaining keys in the series are treated individually. A RDF file may include several button maps, the button map to be used for any particular device being based on the device type assigned to the equipment. (This is one of the purposes of the [DeviceTypes] section of the RDF file.) A button map:
- defines the keys that may be programmed
- as will be described later, establishes the sequence of the data in setup codes and device upgrades.
Button maps may differ from remote to remote.
Digit maps are predefined, popular sequences of OBCs for the number keys. Instead of individually specifying the OBCs for the number keys in manufacturer's codes and device upgrades for every device, only the index of the appropriate sequence for the particular device need be provided. Of course, if the device doesn't conform to any of the predefined sequences for number keys, the OBCs must be specified individually in the device upgrade.
JP1 DATA FORMATS, DATA STRUCTURES AND OTHER ENTITIES
JP1 allows a very significant expansion in the "native" capabilities of JP1-enabled remotes. But, to be able to implement and those addition capabilities, some appreciation of JP1's data structures and terminology is necessary.
Each key on a JP1 remote is assigned a key number. This is the number used for internal (to the remote) references to that key. The association between key and key number is defined in hardware and is unalterable. Key numbers are reflected in a remote's RDF file. If a remote supports shifted and/or x-shifted keys (see Section 5.10), each shifted and x-shifted key will also have an assigned key number, but that assignment will be handled via software. The key number of the unshifted key is often referred to as the base key number. When a macro or keymove is assigned to a key, it is not assigned to the physical key directly; it is really assigned to that key's key number. A physical keypress causes the operating system to search for a function assigned to the associated key number.
Advanced Codes, EFCs, OBCs and Hex
There are three fundamental data formats in JP1:
- extended function codes (EFC)
- original button codes (OBC)
- hex codes.
Extended function codes and original button codes are frequently confused and misused. The relationship between them is shrouded in mystery. However, the next few paragraphs should help lift that shroud.
An original button code, as the name implies, is the number, or code, that is transmitted to a home theater device over the IR link when a button in pressed on the remote control that was supplied by the manufacturer with that device. Each button on that remote will be associated with a specific OBC. In order for the device to respond properly to the press of a button on your JP1 remote, the JP1 remote must transmit the same code that the original remote (now in your bottom drawer) would have transmitted.
OBCs, when entered into or displayed by JP1 software tools, will be in decimal form, with a maximum value of 255. That requires eight bits, or one byte, in hex form. The OBCs for some HT devices use fewer than eight bits; however, most devices use them all.
Extended function code is simply another name for advanced code. Those two terms are interchangeable. OK, but, what are they? Extended function codes are a series of numbers developed by UEI from which the corresponding OBC may be derived. Why do that? Why not just use the OBCs? Presumably (since UEI isn't telling), the reason has to do with implementing a common system of function numbering that would work across all manufacturers' devices (TV's, DVDs, etc). Bottom line, that's how UEI did it and we're stuck with it.
Generally, keymoves and device upgrades (both described in detail in the following section) are specified using EFCs, which are then converted to OBCs by the JP1 software - although some of the JP1 tools allow OBCs to be entered directly. Like OBCs, EFCs are generally expressed as decimal numbers. A tool for converting between EFCs and OBCs, called "OBC-to-EFC" is available in the Files|Spreadsheets subsection of Yahoo! Groups. IR.exe's Tools|EFC Calculator will also perform those conversions.
Since, like OBCs, EFCs are held in a single 8-bit byte, there are a maximum of 256 unique EFCs. Often, in the setup code sheets made available by UEI, EFCs are shown as numbers greater than 256 (some suggest to confuse "hackers"). If an EFC is encountered whose value is greater than 255 but less than 512, simply subtract 256 from it. Similarly, if the number is between 512 and 767, subtract 512. And so on. Further details on advanced codes and EFCs are available at http://www.hifi-remote.com/ofa/adv-search.shtml.
When looking for hidden or discrete commands, it may be useful to convert the EFCs you know to their OBC equivalents, since the commands often "line up" in OBC numerical sequence. For example, Panasonic uses OBC=0 for Tuner, 1 for Video 1, 2 for Video 2, etc. Panasonic's Power toggle OBC is 61, Power On discrete is 62 and Power Off discrete is 63. There may be a valid EFC where you see a "hole" in the known-OBC line-up.
"Hex" data is the expression of JP1 data in hexadecimal notation, i.e., base 16 format. The decimal system uses digits from 0 to 9. The hexadecimal system also uses 0 to 9, but it also needs to represent the values 10 thru 15, for which it uses the alphabetic characters "a" thru "f". Hexadecimal notation may be shown in any of several formats. The one typically used with JP1, which is based on 8-bit bytes, is "$xy", where "$" indicates hexadecimal notation, "x" is the hexadecimal representation for the first (most significant) four bits, (sometimes called the high-order nibble) and "y" represents the least significant four bits (or low-order nibble) - a byte being made up of two nibbles. Some of the JP-1 tools do not use or display the preceding "$", although they may accept it in inputs.
Most hex data in JP1 is a straightforward, hexadecimal representation of the underlying value - whether a key number, a byte count, device type, setup code, etc. The exception is the OBC and protocol characteristics - whether stored in the last one or two bytes of keymoves, in the body of upgrades or as displayed by the various JP1 software tools. This is due to the vagaries in the protocol requirements of certain home theater equipment as noted earlier. In one-byte protocols, that byte will represent an OBC plus, in the case of fewer-than-eight-bit OBCs, perhaps a single-or multiple bit device-selection flag. For two-byte protocols, one byte will represent the OBC while the second will contain protocol-specific data, such as device or sub-device selection.
Depending on the protocol used by the device, the OBC and, if provided, the protocol-specific data may be stored in ones-complement form. That is, all the 1's are represented as 0s and vice versa. In such cases, an OBC whose value is, say, 64, and whose hex representation normally is $40, would be stored and shown as $BF.
A final variation in these data forms is that the bits may be sent in reverse order, i.e., LSB (least significant bit)-first. A value of 1 is normally represented by the bit pattern 00000001, i.e., MSB, (most significant bit),-first. The LSB-first value of 1 would be 10000000, so that our OBC of value 64 would appear as 00000010 or $02. Unless you are familiar with the characteristics of the device protocol, that byte, or those two bytes containing the OBC and other data, may bear little resemblance to the OBC corresponding to the data you entered. That being said, the EFC Calculator tool in IR.exe will calculate/show the relationship between EFC, OBC and Hex.
Keymoves allow for a user-specified code to be sent to HT (Home Theatre) equipment in place of the code specified for the particular key in the manufacturer's code or device upgrade (see Section 5.5) assigned to the active device on the remote. That replacement code will be the OBC (and, perhaps, associated protocol information) corresponding to an advanced code, or EFC, specified by the user.
A keymove is executed only when the device to which it is bound is the active device on the remote.
Kemoves are stored in five- or six-byte data blocks in the advanced code section of the remote's eeProm - comprised of a four-byte header plus one or two bytes of data. The first item in the header is the key number of the key to which the keymove is assigned or bound, i.e., the bound key. A keymove is always bound to one of the device keys on the remote, i.e., the bound device. A bit flag in the middle of the second byte is set to 0 for a keymove; that is how the remote knows that the data structure is a keymove. Also contained in the second byte is the number of bytes in the keymove remaining after byte 2 (i.e., the total number of bytes in the keymove - 2). While basic keymoves will be only five or six bytes long, special types of keymoves (discussed later) may be longer - up to 17 bytes long (2 plus 15 - the maximum number that may be held in the four bits representing keymove length). In order that the remote may determine which protocol to use when the keymove is triggered, the data block also contains a device type and setup code reference. (The setup code in turn specifies the protocol to be used). The fifth (and sixth if necessary) byte of the keymove contains the replacement OBC (which may have been entered directly by the user or converted from a user-entered EFC) and relevant protocol parameters. The form of a basic keymove is shown below.
|byte 1||key number of bound key|
|byte 2||bound device (3 bits)||0||# of following bytes in keymove|
|byte 3||keymove device type||MSBs of the keymove setup code|
|byte 4||remaining bits of the setup code|
|byte 5||OBC (in hex form) corresponding to the keymove advance code/EFC|
|byte 6||for 2-byte IR protocols only, protocol sub-device information|
Depending on the protocol, the fifth and sixth bytes may be swapped.
The second fundamental data structure in JP1 is the macro. A macro comprises of a two-byte header and a sequence of up to fifteen key numbers. When the key to which the macro is assigned is pressed, each key whose key number if included in the macro will be "pressed" in sequence, rapidly, by the operating system. Of course, the keys are not physically pressed, but the result is as if they were.
Macros are executed irrespective of which device on the remote is active.
The data block for a macro is between three and seventeen bytes long. As with a keymove, the first byte of the header identifies the bound key and the low order nibble of byte 2 specifies how many bytes follow - in this case, the number of steps in the macro. Since a macro is effective for all devices, no bound device specification is included. The bit flag in the second byte will be 1 in the case of a macro. Since the macro length is specified by a single nibble, macros are limited to 15 steps. The form of a macro is shown below.
|byte 1||key number of bound key|
|byte 2||$01||length of macro|
|byte 3||key number for the first step of macro|
|byte 4+||key numbers for up to 14 additional steps|
JP1-enabled remotes provide a capability to upload device upgrades - either by way of a JP1 connector on the PCB or, in the case of newer versions, an acoustic coupler into the upgrade section of the remote's eeProm. A device upgrade specifies all the key-to-OBC relationships for the device and identifies the protocol to be used in IR communications with that device. Once loaded into the remote, a device upgrade effectively overwrites the corresponding pre-programmed manufacturer's code for that device, if any (i.e., the one specified by the device type and setup code number assigned to the upgrade). The term "effectively overwrites" is used because device upgrades, like keymoves and macros, are stored in eeProm, while the original pre-programmed manufacturer's codes are store elsewhere in the remote and are, in fact, unaffected by the upgrade.) The general format of a device upgrade (and, of course, of the manufacturer's code it replaces) is as follows:
|byte 1||device type||MSBs of device setup code|
|byte 2||remaining bits of setup code|
|byte 3||IR Protocol identifier|
|byte 4||index into table of digitmaps (see RDF File)|
|bytes 5-8|| bit-flags associated with each key or group of keys in the button map for the|
specified device type defining whether or not the key/group is programmed
|next 0-4 bytes|| fixed data for the IR protocol|
(dependant on the specified protocol)
|next n bytes|| OBC in hex form, which may be complemented, and which may be of either|
one-or two-byte form, indicating the code assigned to/programmed on each
button on the remote that is included in the relevant for button map
A device upgrade is not constrained in length. It is as long as it needs to be. Each group of keys and each other individual key in the button map in the RDF corresponding to the selected device type will have an associated single-bit flag in bytes 5-8, in the order set out in the button map. If a flag pertains to a group of keys, it will be set if any member of the group has been programmed. Otherwise, a flag indicates whether or not an individual key has been programmed. The following bytes contain the codes to be sent to the physical device when the buttons to which they are assigned are pressed - in the same order as the bit-flags and, hence, the button map. Where a bit-flag pertains to a group of keys, if the flag is set, the code for every key in the group follows in button-map sequence. Any keys in the group that have not been programmed will have a value of 0. Conversely, if the bit-flag is not set, it indicates that the key, or group of keys, has not been programmed and no memory is wasted on unassigned keys. This leads to very efficient usage of memory for this type of data.
Since button maps are defined in the RDF file and since all major JP1 software tools refer to the RDF file, consistent treatment of the variable-format data structure is possible. In the remote's eeProm, device and protocol upgrades are accessed by means of a table of pointers - due to their variable length format - pointers calculated by IR.exe when the upgrade is applied.
Only keys defined in the ButtonMap for the specified device type may be included in device upgrades. None of the special purpose keys (e.g., macro keys, keys to which learned commands may be assigned, the FAV/Scan, Setup and backlight keys) nor shifted or x-shifted key will be included in a button map. Hence, functions assigned to these keys must be implemented using keymoves.
Other Data Structures
There is one other data entity, a special form of the macro, worthy of note at this time. That is, the FAV list. A FAV list also is an-up-to-17-byte entity assigned to a particular key (the bound key) that can hold up to five 3-button macros. While any key numbers can be entered into these macros, they are intended to be for 3-digit channel numbers. On every press of the bound key, the next 3-button macro is executed. When the last of the macros programmed into a FAV list have been executed, the first macro will be the next executed. A FAV list has the following form:
|byte 1||key number of bound key|
|byte 2||$03||length of FAV list|
|byte 3-5||first FAV list entry|
|byte 6+|| up to 4 more 3-byte|
FAV list entries
Note the value $03 in byte two. The "1" bit will identify the structure type as being a macro, the "2" bit will differentiate between a standard macro and a FAV list.
As well, many newer remotes have a learning capability. That is, they can receive and interpret IR signals from other remotes. When one remote learns a command from another, it stores a digital image of the entire IR signal associated with that command. Learned commands are also stored in eeProm, but in a space referred to as learning memory, separate from keymoves, macros, upgrades and FAV lists. Due to the amount of data involved in a learned command, a large portion of the eeProm is devoted to learning memory. At the time a command is learned, the user selects a device and key (i.e., a bound device and a bound key) to which the command is to be assigned. Thereafter, from a user's perspective, a learned command is equivalent to a keymove - but will override a keymove assigned to the same key/device.
FAV lists and learned commands may only be assigned to specific buttons on the remote.
Section 2.2 described the basic keypress processing by a JP1 remote. However, for simplicity at the time, an important step was omitted. That is, when a button (other than FAV or a learned command key) on the remote is pressed, the operating system checks if a keymove and, if not, then a macro, has been assigned to that button. If a keymove or macro has been assigned, it, not the pre-programmed manufacturer's code, will control what action the remote takes. If no keymove or macro has been assigned, the remote will check for a device upgrade covering the active device. If there has been a device upgrade, that upgrade will also override the pre-programmed manufacturer's code. FAV and learned command keys will, of course, perform the assigned function, if any.
Hence, a keymove "trumps" a macro (and a learned command "trumps" a keymove) on the same key. So, if one wants to program a function that would be common for most devices but yet permit individual treatment for one or two devices, one could program a macro on an appropriate key to take care of the general case and then place one or more keymoves on the same key to address the special cases. Since the special cases, being keymoves, would be encountered first, the keymoves and not the macro would be executed when the devices requiring special treatment were active.
Some JP1 remotes are capable of controlling more devices than for which they provide device keys. For example, URC 8911 and RS 15-2117 are eight-device remotes, i.e., they provide eight device keys. But, internally, these remotes are capable of controlling 15 devices. URC 6131 is a six-device remote but is capable of controlling 8 devices. Even the venerable Millenium 4, a four-device remote, will control a fifth device. These additional devices are called logical devices, since they have no corresponding dedicated device key. Typically, logical devices are not accessible without JP1. But, with JP1, a logical device can have a manufacturer's code or device upgrade assigned to it, with any key on the remote capable of supporting a macro may be set up as a device key for that logical device. With an extender (see Section 10), logical devices are programmed in the same manner as physical devices.
Logical devices are not without restrictions, however. The bound device in keymoves is restricted to 3 bits, i.e., devices 0-7. On remotes that support more than eight physical devices, logical device numbers, by necessity are 8 or higher, and, hence, cannot be used as the bound device in keymoves.
The number of keys that may be accommodated within the range of base key numbers, generally, is greater than the number of physical keys on the remote. Thus, there may be "holes" throughout the numbering scheme or there may be unused key numbers at the end. Some remotes use some of these extra key numbers for special purposes. However, if not a special case, such key numbers are handled by the remote just as if they represented physical keys. These are phantom keys - key numbers without keys. Key numbers available for use as phantom keys are identified in the RDF file as "Phantom 1", ‘Phantom 2", etc. Phantom keys have shifted and x-shifted counterparts - just like physical keys.
A phantom key may be used as the bound key in both macros and keymoves. However, it cannot be included in a device upgrade - other than as an associated keymove.
When might a phantom key be used? In non-extended remotes, phantom keys are mostly used to hold keymoves that are accessed only from macros, e.g., to put a TV into a mode to accept a new input selection under control of a macro. However, the possibilities with extended remotes are almost endless. Consider that macros are limited to fifteen steps. Not infrequently, you'll want to program functions that require more than fifteen steps, e.g., turning on all the components in your HT system and selecting the proper inputs. Or, for memory efficiency, you may want to set up subroutines, i.e., series of commands that are used by more than one function - particularly with an extender that supports nested macros. These extra commands and subroutines would be incorporated into one or macros and/or, with extenders, (device specific) keymoves. A physical key is required only to start the process, i.e., for the first macro or keypress. The remaining macros or keymoves also must be assigned to keys, and they would be assigned to phantom keys. By using phantom keys in this way, physical keys can be reserved for functions that must be associated directly with physical keypresses.
Shifted and X-Shifted Keys
A shifted key, generally, is a keypress immediately following the shift key being pressed. Unless the user specifies a different key (not all remotes support this capability), the shift key is the remote's Setup key, sometimes called the "P" key. Shifted keys have different key numbers from their unshifted counterparts and, hence, can be assigned different functions. So, the POWER key might be programmed, using a macro to, say, turn on the power to all devices in the system, while shift-POWER, i.e., pressing the POWER key within a short period after pressing the shift key, may have assigned to it a keymove (one for each device) that toggles the power for the currently-selected (active) device. The shift function effectively doubles the number of keys available to be programmed.
A keyboard shift remains in effect for only a short, often user- programmable, period. (Usually, the shift timer is also the backlight timer.) The first key pressed after the shift key (while the keyboard remains shifted) assumes its shifted state and cancels the keyboard shift. Hence, the shift key must be pressed immediately before any other key that is intended to be shifted.
Some remotes also support an x-shift function, which is simply a second shift function. If x-shifting is implemented, a second shift key, the x-shift key, will be designated (which may be a second press of the first shift key). The x-shift key must be pressed immediately before the key that is to be x-shifted. X-shifted keys also have unique key numbers and, so, the function effectively triples the number of buttons available for programming.
However, due to the inconvenience of physically using the shift and x-shift functions, shifted and x-shifted keys are more likely to be used like phantom keys than to initiate ordinary keyboard functions. As well, the number of phantom keys is limited and the available phantom keys may be quickly consumed. Macros and keymoves that don't need to be directly associated with a keypress usually are then assigned to shifted and x-shifted keys that are unlikely ever to be required to generate keypresses.
IR.exe (currently version 4.02), among other things:
- receives device and protocol upgrades from KM or RM
- relates those upgrades and pre-programmed manufacturer's codes to physical devices
- allows the user to program keymoves and macros
- using the RDF as reference, assembles all this data into an eeProm image and
- controls the uploading and downloading of the data to/from the remote's eeProm.
"JP1 for Beginners" provides exhaustive, (though now somewhat dated) instructions on how to use IR.exe. This section will concentrate, instead, on what actually gets put in the eeProm by IR.exe.
In an unextended remote, eeProm is partitioned into:
- basic data, which includes:
- a checksum of the data in eeProm
- the remote's signature, which IR.exe uses to select the correct RDF
- the device table, which defines for each device the remote can manage the corresponding device type and setup code, and
- home theater keypad device assignments
- advanced code memory, which holds the keymoves and macros (but usually only has room for a few)
- upgrade memory which, as the name implies, is where IR.exe stores any protocol and device upgrades and, finally
- in those remotes supporting the feature, learning memory - which IR.exe will read and interpret, but not modify (unless the user specifically requires it to).
As with most projects, JP1 programming requires compromises - especially when it comes to memory consumption. In an unextended remote (extenders are discussed in Section 10), advanced code memory is usually quite limited, whereas there is usually adequate upgrade memory. Unfortunately, simple keymoves, which are stored in advanced code memory, require five or six bytes each (four bytes of overhead and one or two bytes for the code to be sent to the device). So, advanced code memory may be quickly consumed. (Remember, UEI never intended for the user to be entering keymoves with such ease from a computer.) On the other hand, if a key is handled in an upgrade, the cost may be as little as one byte. So, given the particular circumstances, it may be preferable to install a complete upgrade even if only a few keymoves would otherwise be required.
IR.exe monitors the use of the advanced code and upgrade of memory and displays the number of bytes remaining in each.
Keymap-Master's job is to facilitate the development of device and protocol upgrades. Those upgrades are then transferred to IR.exe using the computer's copy/paste facility. As noted earlier, KM is a MS Excel application (keymap-master-v8.16.xls at time of last update). As for IR.exe, "JP1 for Beginners" provides exhaustive instructions on KM's use.
KM permits users to create entirely new device upgrades and to modify upgrades previously created by others. (Users are encouraged to store any unique upgrades they develop in Yahoo! Groups JP1, subsection Files|Device Codes so as to make them available to others.) If you plan to create an upgrade for one of your devices, rather than starting from scratch, you should scan that Yahoo! subsection first to see if someone else has already done the hard part. If you must start from scratch, hifi-remote.com provides basic advanced code information for a wide variety of devices, as does Devices4.
As noted earlier, button maps control which keys on the remote may be assigned using JP1. Several button maps are included in each RDF file, each associated with a specific device types. In a device upgrade, the applicable button map is not selected directly. Instead, it is determined by the device type assigned to the upgrade.
Device types bear the names of common types of home theater equipment, e.g., TV, DVD, Cable, etc. The button map associated with a given device type generally includes all the keys typically required by the HT equipment of the type implied by the device type. But, there is no other correlation between the device type of an upgrade and the type of HT equipment to which the upgrade applies and it is not necessary that the device type reflect the nature of the physical equipment. There may be instances where more keys are required than are made available through this association. Generally, device type "Cable" allows programming of the most buttons. ("Amp" and Tuner" offer the least.) So, if you're developing a device upgrade for your TV using device type "TV" and you want to use a button on the remote that is not included for device type "TV", change the device type to "Cable". This will, almost magically, make additional buttons available. The remote won't care - so long as you tell it your TV uses a setup code of device type "Cable".
Keys which are excluded from device upgrades (see Section 5.5), other than x-shifted keys, may also be programmed with KM. However, KM will implement those assignments as keymoves. The names of the keys so affected are preceded by the symbol "@" in KM's Button sheet. While such keymoves will seem to be an integral part of the device upgrade, IR.exe will segregate them from the upgrade and thereafter handle them like any other keymove. X-shifted keys cannot be programmed with KM; they must be programmed with IR.exe.
In some unextended remotes, certain buttons cannot be programmed using JP1. The remote treats these buttons specially and will ignore any custom programming. KM will "gray-out" buttons that cannot be programmed at all. (In an extended remote, generally, every button can be programmed.)
KM supports the specification of externally triggered functions i.e., the ability to have a function on the device to which the upgrade applies be "triggered" by a keypress when another device is active. This capability is labelled, simply, "KeyMoves". It permits, for example, when creating an upgrade for a receiver that has a variety of signal input selections, the specification of a key on another device that will select the appropriate input on the receiver when that other device is the active device on the remote.
Finally, KM also supports a rudimentary external functions capability, i.e., the ability for a function on a device other than the one being upgraded to be triggered by a keypress on the device to which upgrade applies - essentially the converse of a Keymove described in the preceding paragraph. Using a similar example to that above, KM's external functions capability allows a function, and hence a key, to be specified in, say, a TV upgrade that would select the appropriate input source on the Audio device. This is accomplished by specifying the external device type/setup code in place of the KM function name and, in the EFC column, specifying the EFC of the relevant function on the external device. Subsequently, this external function would be assigned to a button in the upgrade. Full details are provided in the KM ReadMe file.
RemoteMaster is a Java-based program currently still under development. Its capabilities at time of writing (pre-release version RemoteMaster.v0.96) were generally equivalent to those of KM, with the exception that:
- RM supports the programming of x-shifted keys, whereas KM does not
- certain device protocols supported by KM are not yet supported by RM (KM tends to lead RM in implementation of new protocols)
- while RM supports the specification of external functions, it does not yet offer functionality equivalent to KM's KeyMove capability (but that latter feature is currently under consideration).
Why choose RM over KM or move from KM to RM? Unless you happen to need external keymoves or one of the recently added protocols, RM's functionality is at least equal to KM's. RM's user interface is more elegant than KM's. It is intended that RM will eventually provide the capability of the entire JP1 toolset. So, RM likely will evolve to a much greater extent than KM. As well, the more RM is used, the more quickly any "bugs"/ design deficiencies will be discovered and, hence the better tool it likely will become. However, if you're concerned about the potential instability of RM as it evolves or if you're just plain happy with KM, stay with KM for a while. RM can read KM's output files, so you can easily move to KM at any time in the future. So, take your pick.
Full user instructions for RemoteMaster are included in its ReadMe files.
When planning to create an upgrade "from scratch", Devices4.xls should be run to obtain basic information for the setup code on which the upgrade is to be based. The setup code is entered in the "Type" and "Code" fields below the instructions "Select here:". Please note that Devices4 was developed for use with a RS-1994 remote. Therefore, it may not support some of the manufacturer's codes pre-programmed into other remotes, particularly newer remotes.
Devices4.xls, another MS Excel application, will identify the required IR protocol, its device, sub-device and other parameters and the basic EFCs (i.e., extended function codes - another name for advanced codes) for that particular setup code. Note, however, that where a protocol is not pre-programmed into a remote, it will be necessary to "paste" a protocol upgrade from KM or RM into IR.exe. Both KM and RM will flag this requirement.
JP1 with unextended remotes will fulfill the needs of many users. An extender goes much further.
An extender takes over the main processing loop of the remote from the operating system, in effect, becoming the operating system. (However, extenders still makes extensive use of the remote's subroutines.) In doing so, an extender enables a variety of features and a level of sophistication not otherwise possible, including most notably (all described in the extender ReadMe files):
- keymoves and faster, nested macros on any key
- ToadTogs, allowing discrete control over a toggle-only device operation
- the ability to differentiate between short key presses and long or double key presses
- DSM or device-specific macros (normally, macros are applicable to all devices)
- special FAV list processing
- custom name display on remotes with an LCD, and
- additional macro/advanced code memory.
While every extender may not support this full feature complement, these features are available only with an extender.
All this extra capability and additional memory comes at a cost. That is, some of the features of the unextended remote are disabled. (Remember the compromises?) In every case, learning will have been disabled. So will be SCAN support and long-Setup keypress capability. But what do you need those features for once your JP1 remote has all the capabilities of your individual remotes? If you purchase a new component for your home theater system for which your remote doesn't provide a manufacturer's code, you can temporarily restore the remote to its original (learning) configuration by disabling the extender, learn the necessary keys, upload to IR.exe where they will be decoded, create an appropriate upgrade (if necessary) and finally, add the upgrade with IR.exe and reconfigure the remote to its extended form.
An extender is divided into two parts. In the case of the 8910/9910 extender, when it is initialized, Part 1 is loaded into RAM (the memory in the remote where the programs execute), initiated by a special key move. That keymove, which is stored in the area where the unextended remote expects to find keymoves, is triggered by the user pressing the button(s) defined in the extender ReadMe file. (The remote thinks it's loading another IR protocol - except this one never relinquishes control.)
The extender then enters a processing loop waiting for another keypress. When that keypress arrives, Part 1 manages things like the shift key, backlighting, the LED and the LCD. Then, if the key that was pressed has a keymove, macro or FAV list assigned to it, Part 1 relinquishes control to Part 2 which is then loaded into RAM on top of Part 1. Part 2 processes the keymove, macro or FAV list, during which, if necessary, an IR protocol will be called. Once the keymove or macro has been fully executed, control of the remote is returned to Part 1 (which is once again loaded into RAM).
By taking complete control of the remote, the extender removes all previous restrictions about what each button can be used for and provides much more useful macro-processing.
It must be pointed out, however, that other extenders may be partitioned differently. Nonetheless, the above example is representative of the general operation of extenders.
In eeProm, one part of the extender "lives" in the old advanced code (keymove/macro) area, immediately following the special keymove that initializes it. The other part "lives" at the top of memory, i.e., at the end of the eeProm memory previously devoted to the learning function. The balance of the learning area is available for the storage of keymoves, macros and the FAV list - which is much larger than the old advanced code area.
Several of the new features enabled by the extender are integral to the design of the extender (e.g., faster, nested macros, special FAV list processing and more advanced code memory). The others are implemented as special protocols (see Section 11). The advantage of using special protocols is that, if one of these features is not required, it can be removed by deleting the associated special protocol and the memory occupied by it is thereby freed for other uses, e.g., upgrades.
One feature of extenders that is often a source of confusion is shift-cloaking. In an effort to keep button assignments logical, one may want to put a macro on a button but have that macro still be able use the button's "basic" function(s), i.e., the function(s) assigned to the button by an upgrade(s) or in the manufacturer's code(s). But, in doing this, the macro would, in effect, be calling itself, since, in the remote's control hierarchy, the macro would be encountered first and, thus, "get in the way" of the basic keycode. This will result in the remote "hanging", i.e., going into an endless loop - unless that basic function was re-implemented with a keymove (which would take precedence over the macro but which would consume additional keymove/macro memory). Shift-cloaking gets around this difficulty. With shift-cloaking, the macro does not call itself. Rather, it calls its shifted-self, e.g., a macro on the POWER key would call Shift-POWER to have the basic function of the POWER key performed. When an extender encounters a call to a shifted key and the shifted key is unassigned, the "basic" function assigned the key will be performed. Of course, then, for this to work you must not assign a keymove or another macro to the shifted key - but you can assign a keymove or macro to the x-shifted key.
Extender Execution Delays
Extenders provide a great deal of flexibility. However, in configurations that make extensive use of the additional macro/keymove memory made available by extenders, execution time of complex functions may become excessive. For example, with shift-cloaking, in order to determine that a shifted function is not assigned, it is necessary for the remote to scan the entire list of macros and keymoves - in addition to whatever other scans of the list are necessary for the particular command. All this scanning can introduce a noticeable delay. Hence, for time-critical functions, such as when using double/long keypresses on the cursor up and down keys for line/page up/down with online cable guides, shift-cloaking may not be appropriate.
These execution delays can be minimized to some extent. First, as noted above, avoid using shift cloaking for time-critical functions. Also, where time-critical functions are implemented using extended keymoves (e.g., those for special protocols), collect all the keymoves at the top of the keymove list. Minimize the number of keymoves and macros; where extended keymoves call macros (device specific or otherwise), incorporate the macros right into the keymove whenever possible - after debugging. As a last resort, execution delays may be minimized by defining (otherwise unnecessary) keymoves for the affected keys and putting those keymoves near or at the top of the keymove list.
Nested Macros and Pending Buffer Overflow
While on the topic of macros, many extenders permit nesting of macros. Nested macros are otherwise normal macros that are called by other macros and that, following their execution, return control to the macro that called them. Nesting effectively removes the fifteen-step limit of macros and almost (but not quite) permits macros of unlimited length. The ReadMe files of the extenders give a good account of how nesting works.
What the ReadMe files don't tell you, though, is that there is no warning upon overflow of the macro pending buffer - which is where the then-unexecuted steps are collected. In the 8910 extender, the effect is that certain macro steps are not executed - leading to strange, and unexplainable (in the context of the macros being executed) remote operation. The effect with other extenders is likely to be similar. The only way to discover what is going on is to determine, for every step of the macro, what would be in the pending buffer at the time. (The ReadMe file illustrates how this can be done.) Complicating matters is that the length of the macro pending buffer is not always disclosed in the documentation. If you're using long, nested macros (that you are certain are OK) and you're not getting the results you anticipate, you should be suspicious of macro pending buffer overflow. Putting calls to other macros as late as possible in the calling macro (so as to minimize the number of pending, i.e., unexecuted, steps) will help avoid the situation.
Both Keymap-Master and RemoteMaster support external functions of one form or another. However, these external functions are handled as keymoves and, hence, are memory-inefficient. Depending on circumstances, extenders may offer an alternative.
Suppose, for example, you want to automate audio input source selection. Using KM's Keymove function, this would be accomplished with external functions (keymoves) - at a cost of at least 5 bytes/device plus the call to actually select the input. Device type AMP includes transport keys. Most receiver/amps won't make use of these keys directly. But, since the transport keys are inherent in the device type, they may be programmed at a cost of only one byte/key (for a one-byte protocol). So, if the transport keys aren't otherwise required, using them to hold the discrete codes for audio source selection could save 4 bytes/device. Even though a two-byte call will be necessary to select the input source for a device, i.e., DEV_RCVR/AMP (or X_RCVR/AMP) plus the key number of the key to which the discrete code is assigned, this method still offers at least a 3 byte/call savings over external function keymoves. Of course, you'll want to make sure the transport keyset is disabled (assigned to a dummy device) or assigned elsewhere when RCVR/AMP is the active device so that, should you inadvertently press a transport key while in the RCVR/AMP mode, you won't inadvertently change the audio input selection.
There are similar opportunities with other unused keysets (PIP, Menu, Vol, Channel) and device types, and for other types of function (e.g., TV input source or wide-screen-size selection if discrete codes are available). Even if one has to use a "larger" device type, say CABLE rather than TV, in order to make sufficient additional base keys available, the memory penalty will still be significantly less than with using keymoves. But, you will want to dedicate an entire keyset to such functions so that the keyset can be disabled or assigned elsewhere to avoid strange things happening.
Some remotes have several versions of extenders. Each is generally an upgrade to its predecessor and so, under normal circumstances, the latest version should be downloaded. However, sometimes there are differences between early versions of a remote and their latter-day successors. A current case in point is the URC 8810. Some of the early remotes do not operate reliably on Version 3 of the extender. But 8810 remotes purchased recently do not experience the same difficulty. Why? It's not yet known. In a hackers' world, everything is not always clear!
An extender is not available for every remote. In some cases, this is due to limitations in the remote. In others, it's due to the lack of sufficient eeProm memory; i.e., once the memory required for the extender is taken up, there's not sufficient left for enough keymoves, macros and upgrades to make the extender worthwhile. And in yet others, especially older remotes, there's just not enough users to justify the level of effort in creating an extender.
Generally, special protocols are protocols that do something other that control a remote's IR transmitter. Features using special protocols are packaged as extended keymoves attached to a dummy device, i.e., a device upgrade with no keys encoded. A dummy device does nothing but specify a protocol to be called. Using a keymove to initiate special protocols takes advantage of the remote's habit of calling a protocol to control the IR transmitter whenever a keymove (among other things) is encountered. Once the protocol specified in the dummy device takes control of the remote, it's not restricted to IR processing.
Extended keymoves for special protocols, being keymoves, are device specific. That is, they will only be executed if the device to which they are bound is the active device. But, often, one wants functions provided by special protocols not to be device specific. This can be accomplished by putting the extended keymove on a phantom, or other unused key and calling that key from a macro - which is not device specific.
Device Specific Macro
The basis of several of the special protocols is the device specific macro, or DSM, i.e., a macro that will be executed only if the device to which it is bound is the active device when the associated key is pressed. In the case of the DSM special protocol, each byte in the body of the keymove specifies a key to be automatically "pressed", i.e., a macro. A DSM has the form:
|byte 1||key number of bound key|
|byte 2||bound device (3 bits)||0||remaining length of keymove|
|byte 3||DSM device type||MSBs of the DSM setup code|
|byte 4||remaining bits of the DSM setup code|
|bytes 5+|| 1 - 13 key numbers (in hex) defining the buttons to|
be "pressed" sequentially (i.e., a macro)
Unlike a regular macro, a DSM is limited to thirteen steps, i.e., the 17 byte maximum length of a keymove data block less the four bytes of keymove overhead.
The DSM special protocol under an extender should not be confused with what is referred to as a device-specific-macro in an unextended remote. In an unextended remote, one or more macros in hex form, each with a unique identifier, are appended to a special protocol. That special protocol is called by way of a keymove (which, of course, is device specific) that, instead of an advanced code, specifies the identifier of the macro to be executed.
While the latter capability was developed for use in unextended remotes, it may also have application in extended remotes where upgrade/macro memory is scarce, since it effectively allows macros to be transferred to upgrade memory, albeit in a rather cumbersome fashion.
ToadTog, reputedly, the hardest to understand of the special protocols, manages device toggle functions, e.g., i.e., on/off, yes/no. A device that uses toggle functions is known as a Toad - Toggle Only Actuated Device - hence, the name "ToadTog" - to toggle a Toad. A device that supports discrete functions, i.e., "on" is a different command from "off", is known as a Dude - Device Utilizing Discrete Extensions . . . or so it is reported in the Forums. The special protocol ToadTog allows one of a set of eight bits to be tested, toggled, set or reset at the direction of the user. In the latter two cases (i.e., set or reset), action is only taken if the bit is not in the desired state already. The ToadTog bit to be tested together with the command to test/toggle/set/reset the bit is encoded in byte 5 of the keymove (the command byte). This leaves up to twelve bytes to specify the actions to be taken (which may be no action whatsoever) depending on whether the ToadTog bit was previously set or reset. A ToadTog keymove has the following form:
|byte 1||key number of bound key|
|byte 2||bound device (3 bits)||0||# of following bytes in keymove|
|byte 3||ToadTog device type||MSBs of the ToadTog setup code|
|byte 4||remaining bits of the DSM setup code|
|byte 5||a||ToadTog bit # (0-7)||b||# steps in Action 1 (max 7)|
|byte 6||Action 1, i.e., 0 to 7 key numbers (in hex) defining the buttons to be "pressed" sequentially if the ToadTog bit was previously set|
|byte 7+||Action 2, i.e., 0 to (12 - # steps in Action 1) key numbers (in hex) defining the buttons to be "pressed" sequentially if the bit was reset|
|0||0||toggle ToadTog bit||set||1|
|0||1||reset ToadTog bit||set||1|
|1||0||test ToadTog bit||set||1|
|1||1||set ToadTog bit||set||-|
The most obvious use of ToadTog is to handle power on-off for devices without discrete inputs. However, ToadTog bits are useable in other ways. For example, the author uses three ToadTog bits to record which of the eight home theater modes (0 - 7) of the remote is currently active. As well, where a device such as a TV needs a significant time after turn-on before it will accept further input, using ToadTog for power on/off, even if discretes are available, allows for the delay to occur when the device is initially turned on but skipped if the device is already on. Basic ToadTog allows control of only eight bits. A recently-introduced-but-not-yet-generally-available enhancement to this special protocol provides for the user to specify one of several sets of eight bits by using a different dummy device.
Double/Long Keypress (D/LPK)
The format of D/LPK is similar to that of ToadTog, with one exception. That is, instead of a bit-specifier, the D/LPK command byte (i.e., the fifth byte of the keymove) includes a keypress-time parameter that, when examined by that special protocol, will cause one action, i.e., a device specific macro sequence, if the key is held for a shorter time than that specified and another action if it is held for an equal or longer period. From the existing documentation on Yahoo! Groups JP1, it seems that the command byte format for all remotes may not be identical. For the URC 8911 and a number of other remotes, a D/LPK keymove has the following form:
|byte 1||key number of bound key|
|byte 2||bound device (3 bits)||0||remaining length of keymove|
|byte 3||ToadTog device type||MSBs of the ToadTog setup code|
|byte 4||remaining bits of the ToadTog setup code|
|byte 5||Time parameter (1 - 255)||D/L||# steps in Action 1 (max 7)|
|byte 6||Action 1, i.e., 0 to 7 key numbers (in hex) defining the buttons to be "pressed" sequentially for a short keypress|
|byte 7+||Action 2, i.e., 0 to (12 - # steps in Action 1) key numbers (in hex) defining the buttons to be "pressed" for long/double keypress|
where "D/L" is 1 for double key press and 0 for a long keypress.
If your remote's configuration contains a lot of keymoves and macros, you may find the remote's responses to D/LPKs more uniform if all the D/LPK keymoves are collected together as the first keymoves in the configuration.
The remaining special protocols that operate with an extender perform a variety of functions not involving macros/DSMs. Please refer to their ReadMe files.
Currently, IR.exe requires that extended keymoves, such as are used with special protocols, be specified entirely in hex format. (Macros are coded from IR.exe by selecting from a table of key names in order to specify the key numbers - with IR automatically doing the conversion to hex. Fortunately, while at time of last update there was no equivalent capability in IR.exe for use with keymoves, a new version of IR.exe which includes a new tool for encoding extended keymoves for special protocols was in beta testing.) To "ease that pain", a MS Excel-based tool called ExtenderCodeCalc is available that allows such keymoves to be specified using key names, which it then converts them into a hex string that can be "pasted" into IR. ExtenderCodeCalc also structures the command byte of the keymove.
Conversely, extended keymoves from IR (in hex format) may be pasted into ExtenderCodeCalc, which then decodes the command byte and displays the key names corresponding to the (hex) key numbers.
At time of writing, work on IR.exe is underway to allow programming of extended keymoves in the same manner as macros.
Other Special Protocols
Not all special protocols require an extender. The Pause special protocol, for example, may be used with or without an extender. It provides for a pause of user-specified duration to be inserted in the processing stream, most frequently to allow a physical device to accept and process an IR transmission before sending it another.
Several other special protocols have been developed to compensate for the limited number of device buttons on some of the older remotes. Two such special protocols, Device Multiplexer and Device Toggler, allow two or more physical devices, i.e., setup codes, to be assigned to a single device key on the remote, with a second, user-specified key selecting from among the available devices. Other special protocols address shortcomings of unextended remotes. All the special protocols have ReadMe files in the Yahoo! Groups JP1 Files|Special Protocols subsection.
Device Combiner is not a "special protocol" in that it does control the remote's IR transmitter. Nonetheless, it is a very special protocol.
Many remotes that are shipped with home theater equipment control two or more devices, such as two VCRs or a TV, a DVD and a VCR, etc. In general, they do this using a protocol that can address each device individually. In some protocols, this is further refined into devices and sub-devices. Unfortunately, due to the complexity of modern HT equipment, control of the physical device may require the capacity of two or more protocol-devices. As well, some manufacturers split the control of their equipment along sub-device lines. For example, in a receiver, one protocol-device may be used to control the tuner while another controls the amplifier functions.) A few manufacturers have developed combined protocols to cover these situations. With a combined protocol, as the name suggests, all the required protocols are treated as one in the remote with the protocol-device specification being incorporated in the hex code assigned to each key and transmitted over the IR link to the physical device. Where a combined protocol does not exist, all the keys assigned in a device upgrade (or manufacturer's code) must use the same protocol-device. (The term protocol-device is not likely to be found outside this manual. It is used here to refer to the device or sub-device addressed by a protocol, as opposed to the physical device, i.e., HT equipment, that responds to the protocol. Typically, in the JP1 world, both are referred to simply as "devices" with the context determining what is intended.)
Where a physical device utilizes two or more protocol-devices and no suitable combined protocol is available, JP1ers have two alternatives:
- build a device upgrade covering the keys that use one of the protocol-devices (preferably the one covering the most keys) and then define one or more dummy devices which use the other required protocol-devices and create keymoves bound to those dummy devices to assign the remaining functions; however, this is not only cumbersome and complex but, because keymoves are involved, may consume an inordinate amount of macro/keymove memory, or
- use the Device Combiner protocol which, among other things, will move the memory burden to the upgrade memory.
Device Combiner allows up to sixteen single-byte-protocol-devices to be managed with one two-byte protocol. Function assignment requires two bytes, one to hold the usual key code to be sent by the protocol, the other to specify the protocol-device identifier. Further details can be found in the Protocol Help sections of both KM and RM.
Device Combiner has another feature that may be useful from time to time. Some HT devices require the duration of their IR signals to be longer than that which is standard on a JP1 remote. Device Combiner allows user to specify the duration of the IR signal transmitted by the remote. If only this capability is required, one would identify the usual protocol for the equipment as the only protocol to be used by Device Combiner and specify the required signal duration for each function on the remote. This duration value is also accommodated in the second byte of function assignment.
Of course, Device Combiner can handle both features simultaneously.
Some Helpful JP1 Programming Notes for "Newbies"
JP1 is a hackers' world. Not only that, it is a hackers' world that is constrained by decisions made independently, some time ago by UEI - who certainly wasn't considering the hackers' needs when it made those decisions. As a result, things don't always appear to be (and aren't) logical from a JP1er's perspective. Further, the level of integration of the software tools is not as complete as we have come to expect from commercial packages. Nonetheless, the JP1 software tools are comprehensive. There at least is documentation for each of the tools. And, there's a loosely-knit group of experts standing by waiting to offer assistance - often in a timeframe that couldn't be matched by a commercial organizational. Best of all, it's all free!
It's tempting when one first gets a JP1 cable to start programming immediately. But, like any other project, the chances of success are much higher if there's been some planning. This doesn't mean you shouldn't experiment. As has been said so many times in response to various posts, "You can't hurt the remote". So, sure, try writing macros or programming keymoves to see what you can do with JP1. But, recognize that's what you're doing - experimenting.
Before doing any experimenting, however, you are well-advised to download the contents of the remote's eeProm into IR.exe and save that file with a conspicuous filename so you won't erase it accidentally. That way, if the remote stops working following an upload of your changes, you can always revert to the initial configuration in order for your wife (or "hubby") to continue to watch TV while you're trying to figure out what's wrong.
Think about what you want your remote to do in detail. Decide what function(s) each button is to perform. With planning, you're more likely to end up with your remote doing something useful. Most important, try and keep things logical, so that operation of the remote will be almost "second nature" - to you and others. Where two or more devices support a similar or related function that isn't specifically provided for on the remote, say Door Open on the DVD and Eject on the VCR, try to assign both functions to the same button. And, that button should seem like a logical place for such function(s); for the example functions, perhaps a long keypress on the STOP button would be appropriate.
There are some obvious things you'll want your remote to do. For example, having one button turn on all the devices you need for a particular home theater mode is pretty common. But, will you use discretes or ToadTogs? Maybe a simple power toggle is all that's necessary. The choice is not always obvious. As pointed out earlier, if you've got a device that needs a lot of time after power-on before it can accept another command, you may want to use a ToadTog for that device's power, even if discretes are available. That way, you can program a pause in the ToadTog and not have to worry later about whether that device is on or off when selecting a HT mode that requires that device. Simply turn the device on whenever it's required. If it's already on, the ToadTog processing will skip the delay.
Another intuitive feature is turning off unneeded devices. But, that may not be as simple as it sounds. Sure, the coding probably is straightforward. But, you may not want to turn off a device if you're selecting another for only a short time, e.g., switching to TV mode while taking a bathroom break during a DVD movie. So, how do you differentiate between a temporary switch to different device and a more-or-less permanent one? Think about it. When will you, for sure, want the device off? There may be no answer that you can reasonably automate.
Another point in this regard to consider is that set-top boxes (STB), DSS receivers, cable boxes, etc. use very little power. Indeed, even when turned off, they often consume almost as much power as when turned on (in order, for example, to keep program guides updated - instantly ready for you to view when you turn the "box" on). As well, most cable boxes do not have discrete power commands; the more often you turn them on/off with toggles, the greater the risk of a power-out-of-sync condition. Finally, if you plan to make use of timed-recording using a VCR or PVR, the desired program will be missed if the STB, etc. is turned off. So, for these devices, it may be better just to leave them on all the time.
Incidentally, there's little more frustrating in the world of JP1 than having a device's power out-of-sync, e.g., a device that turns on when it's supposed to turn off, or that ToadTog won't then turn on (or off) because the remote "thinks" it's already in that state. This happens as a result of a power toggle command to a device not being received - perhaps because someone walked in front of the remote while the power-up or -down macro was executing. An untracked power toggle, i.e., one with no ToadTog involvement, will allow you to correct out-of-sync conditions. Of course, so will walking across the room to physically put the device in the power mode the remote thinks it's already in, or trying to "trick" the remote by having it send a power off (on) command while holding your finger over the IR transmitter so the device doesn't receive that command either. However, of the three, the untracked power toggle seems the most elegant.
Next consider the need for multi-purpose buttons, i.e., a button that does one thing if pressed quickly and that does another if the button is held down or pushed twice in quick succession. That's what the double/long keypress (D/LPK) special protocol is for. But, once again, think about what buttons you plan to make multi-purpose. If the layout is not logical, you'll quickly forget what the buttons are for.
Once you've decided what you want your remote to do and generally how you're going to program it, start with small steps. Don't try to implement a full home-theater configuration as a first step. Program one device; get that one working the way you want it; then program the rest. While the learning curve for JP1 is not steep, it's still there.
Use macros to simplify multi-step keymoves during development. For the time being at least, IR.exe requires extended keymoves (of the type used with special protocols) to be entered in hex format. ExtenderCodeCalc will do the key-name-to-hex, and vice versa, conversions. But, ExtenderCodeCalc is inconvenient to use - especially when debugging. When something doesn't work, you'll likely find it frustrating to have to paste a keymove from IR into ExtenderCodeCalc in order to see what it really does and, then (if there's an error) have to copy/paste it between ExtenderCodeCalc worksheets, make the necessary changes and finally paste it back into IR. Once that new capability in IR.exe is available, multi-step keymoves will be much easier to use. But, for the time being, instead of storing all the steps of a DSM or ToadTog, for example, in the keymove, store the "action" steps in a macro and program the keymove to refer to the macro(s). Then, a DSM would be a single step, i.e., a simple key number reference to a macro. The macro will be displayed in plain language by IR.exe. A ToadTog or LPK would be only two or three bytes long, i.e., the command byte and one or two macro key numbers. Otherwise, you'll likely spend more time using ExtenderCodeCalc trouble-shooting strings of hex codes than you will anything else.
Another thing that is really helpful is to extract all the key numbers from the RDF file and make two tables on paper, one ordered by button - alphabetically or based on the physical position of the buttons on the remote or whatever other sequence makes sense to you - the other by key number. Include not only the base key number, but also their shifted and x-shifted counterparts in both tables. You'll be amazed at how that cuts down the need to use ExtenderCodeCalc.
As possible starting points for you, the author - and many others - have stored their remote configuration files (IR.exe memory dumps) at Yahoo! Groups JP1 User Files|Configurations subsection. Many of these files are accompanied by a brief description of their intended functionality. As part of your experimentation, you may want to download one of them (one that applies to your remote and that is designed to manage a home theater configuration similar to yours), make minimal modifications and use IR.exe to upload it into your remote. To that end, the author's remote configuration file stored at Yahoo! Groups JP1 is entitled "URC8911 - Extended (RM).txt" and the last chapter of this manual describes the configuration in some detail.
Debugging for "Newbies"
After you upload to your remote from IR.exe, be prepared for the remote not to work as you planned.
If nothing at all works with a particular device and you created a device upgrade for that device, check to ensure that you specified the right protocol. If some things work but others don't, don't get frustrated; review your macros and keymoves to see if the things that don't work have something in common. If they do, that should help you isolate the problem. If the features that don't work include special protocols, check that you've used the right dummy device in the keymoves.
If your remote supports logical devices (the ability of a remote to support more devices than can be accommodated on the device buttons) and you have some unused logical device names, you'll find it useful to assign one or more of the dummy devices to logical devices. Once that is done, change the logical device name(s) in the RDF file to something that is meaningful in the context of the assigned dummy device, e.g. db_ToadTog. That way, IR.exe will display the name of the corresponding logical device when you set up a keymove that utilizes the dummy device. This will make faulty dummy-device assignments much more apparent.
The rest is up to you. Remember, the remote is just a computer; it only knows "1s" and "0s". Generally, it will do exactly as you've programmed it. (I say generally, because once in a while, there'll be a problem related to the extender or the hardware, but they get discovered fairly quickly.) If the remote's not doing the right thing, don't blame the remote - at least not right away. Instead, check what you've told it to do. Try to find patterns in the remote's behaviour. Remember what buttons you pressed when it did the wrong thing. It's far easier to isolate a problem you can duplicate than one you can't.
If all else fails, post your problem to the applicable Forum and hope an expert responds. But, in doing so, make sure you identify the symptoms in sufficient detail that an expert can reasonably understand first of all what you've done and secondly, what you're experiencing. (Too often, posts seeking assistance say little more than "I have a problem".) Make sure to include:
- remote control model number
- tools/software being used ; e.g., Extender 3
- setup code being used
- make and model of the equipment that you are trying to control.
An expert may suggest, or you may think it appropriate anyway, that you post your IR.exe memory dump (".txt" file) and/or upgrades from KM/RM to the Yahoo! Groups JP1 Files|Diagnosis Area - from which an expert can download your specific configuration. When posting multiple files, you should "Zip" them before uploading. Also, please delete all files from Yahoo! after a day or so to avoid the area becoming cluttered with files no longer of interest to anyone.
Good luck and, remember, programming JP1 is supposed to be fun.
Frequently Asked Questions
Following are frequently asked questions in the JP1 Forums and their answers, in part, have been gleaned from the experts' replies.
How do I add a missing command or create a device upgrade?
The first step in adding a missing command is to determine the EFC or OBC for the missing command(s). EFCs are available from setup code sheets or upgrades for the particular device posted by other JP1ers in the Files|Device Codes subsection at Yahoo! Groups, by using Devices4 or by experimentation. EFCs and OBCs may also be learned with the remote, together with the relevant IR protocol information.
Next comes the decision as to whether to implement the new command by keymove or device upgrade. If only a few keys are affected, if you haven't previously created an upgrade for the device of interest and if you've got sufficient keymove/macro memory available, then the keymove "route" using IR.exe is the simplest approach. On the other hand, if the device to which the missing commands are to be added has already been upgraded in the remote, modification of that upgrade would be the logical approach - using KM or RM as you choose.
But, be aware that not all keys can be programmed directly in a device upgrade. Shifted and x-shifted keys are always implemented as keymoves - even with KM and RM. As well, certain other keys on the remote can only be programmed through keymoves. So, depending on what keys are to be used, keymoves (which can be made part of the device upgrade or implemented separately using IR.exe) may be the only alternative.
Detailed instructions can be found at http://www.hifi-remote.com/jp1/help/#s2.
What are Pronto, RTI, ccf and cml files and how do I convert from them?
Pronto is a family of LCD touch-screen-based universal remote controls manufactured by Philips Electronics. RTI, standing for Remote Technologies Incorporated, is another manufacturer of LCD touch-screen universal remotes. Both families of remote controls have PC-based editors that store files generally of content similar to IR.exe's text files. ".ccf" is the file name suffix the Pronto editor attaches to its configuration files and ".cml" is the file name suffix the RTI editor uses.
Both these manufacturers make available up-to-date databases on a wide variety of home theater devices. If you have an older, non-North American or otherwise uncommon device not supported by your JP1 remote, the data necessary to program that device may be available from the Pronto or RTI websites, as are their editors. So, by creating or otherwise accessing the right "ccf" or "cml" file, the information you are missing may be found.
Stored in the Yahoo! Groups Files|Programs subsection are a number of files that will be useful in gleaning IR protocol and device information from "ccf" and cml" files. Most are in ".zip" format hand and a ReadMe file is included.
THE AUTHOR'S HOME THEATER SYSTEM
The author's home theater configuration is relatively simple. It includes:
|8911 Device||Equipment Manufacturer/Model||Upgrade Device Type||Protocol|
|TV||Toshiba 30HF83 widescreen TV||Cable||NEC1|
|CABLE||Motorola DCT-2000 digital cable converter||Cable||GI|
|DVD||Toshiba SD-3950 DVD||DVD||NEC1|
|RCVR/AMP||Denon AVR-1604/684 receiver||Tuner||Denon Combo (Official)|
In addition to these five physical devices, the following additional devices are programmed:
|CD||CDs on the DVD player|
|AUX||digital music from DCT-2000|
There are four HT video modes (TV, CABLE, VCR, DVD) and three HT Music-only modes (RCVR/AMP, CD and AUX). By handling these music-only modes as separate devices, it was much simpler to automatically turn off unused equipment e.g., TV, VCR.
Key features of the author's remote configuration are:
|POWER||LKP|| if system on (RCVR/AMP power used as analog for system on/off), turns off all devices|
if system off, turns system on in last HT configuration
|SKP||tracked (by ToadTog) power toggle|
|Shift-POWER||untracked power toggle|
|device key||LKP|| sets up system in the HT configuration for the device by:
For power control, DVD and VCR are mutually exclusive. If in a music-only HT mode (i.e., CD, AUX or RCVR/AMP), power for TV and VCR is turned off and except in CD mode, also the DVD power.
|SKP||momentarily selects device as active for all relevant keysets. Other keysets disabled. A custom "timed-callback" special protocol has been implemented that "presses" a user-specified key upon expiry of the backlight timer. By calling-back a SKP on the HT key, the system automatically reverts to the previous HT mode (see HOME THEATER SKP below)|
|HOME THEATER||LKP||turns on system in CABLE mode, selecting Ch. 33 on TV (CNN)|
|SKP||system reverts to most recent HT configuration|
PIP punch-through is always to the TV. When in an HT mode, volume punch-through is always to the RCVR/AMP. But, when in a particular device mode (see device key in the table above), the volume keys control the particular device if it has a volume capability. In any mode, keysets not relevant to the active device are disabled (e.g., Transport keys are always disabled in the TV mode). Generally, other keys perform their expected function.
The total implementation involves some 19 macros, 88 keymoves (including DSMs, ToadTogs and D/LPKs), seven device upgrades and one protocol upgrade. Except for those called directly upon a keypress, the macros and keymoves reside on x-shifted keys (which are never pressed in this configuration) and phantom keys. Device upgrades for the two music-only devices were made in order to easily disable all keys not applicable in those modes (e.g., number keys and video-related functions for DVD and Transport and on-screen menu functions for CABLE). The remote uses all the special protocols available for the extender plus the custom “timed-callback” special protocol described above. And, finally, it consumes nearly 1500 bytes of upgrade and keymove/macro memory combined. Incidentally, that’s down to 1500 bytes of memory, after running out of keymove/macro memory twice during development.