Remote Control 100 Version 1.0
		      ------------------------------

Introduction

Rc converts your HP-100LX into a universal remote control.  The output
of most remote control units can be captured by pointing them from a
distance of about 1-2 inches to the plastic opening on the right of the
"/" key.  The remote control signal can then be sent back to the device 
to be controlled.  Remote control definition files allow you to program 
complicated interfaces to control a number of devices.


0. Package Contents

The package contains the following files.  As a minimum only rc.exm 
needs to be installed on the system (possibly with the rc.icn icon 
file).

readme			This file
rc.icn			Program icon
rc.exm			Program executable (System Manager compliant)
rc.exe			Program executable (DOS version)
bitconv.exe		Recording format conversion program
keycode.exe		Keyboard scan code program
rc.rcf			Example definition file (7-bit compatible)
rc.rc8			Example definition file (8-bit)

1. Program Usage

There are two versions of the program.  A DOS version and a System
Manager compliant version.  The DOS version is to be run from the
DOS prompt, while the system manager version is  run from within
the system manager.  In addition there are two ways to represent
the remote control signals.  One way uses 7-bit characters and is
compatible with all ASCII editors (appart from line length problems),
while the other method uses a more compact 8-bit representation.
The "memo" editor that comes with the 100LX can use both formats,
so you will probably want to use the 8 bit representation to save
space (8 bit files are about half the size of the 7 bit equivalent
files).  The program can read both forms without any additional
specifications.  When recording, the user can specify which recording
mode is to be used.  An external DOS program is provided to convert
betweem the two recording formats.

The DOS version of the remote control (rc.exe) is used as follows:

rc definition-file [entry-routine]

rc -r[c] recording-file

The first form starts the remote control with a given remote command
definition file.  The optional second argument can specify the
program's entry point.  The program will execute the contents of
the defintion file.

The second form starts the remote control program in recording
operation.  In this mode the program will enter a loop and accept
key strokes and associated remote control signals.  These will then
be recorded in the recording file in the form of a trivial remote
control program.  Any previus contents of the recording file will
be erased. If the -rc option is used in place of the -c, the
recording is done using the 7 bit compatible format.

In order to use the system manager compliant version (rc.exm) the
program is added to the list of programs using the "Application
Manager" (&..., File, Application, Add).  The program is started
using a hot-key, or via the Application Manager.  The files used
by the program can not be specified, and are hard coded as follows:

Definition file:c:\_dat\rc.rcf
Recording file:	c:\dat_\record.rcf

In order to start recording in the system manager compliant version,
press ALT-R to generate an 8-bit program or ALT-C to generate a 7-bit
compatible file.

2. Definition Files

The program's operation is based on the remote control definition
files.  These files contain commands to draw the screen and key
bindings to send the appropriate remote control codes.  The following
paragraphs contain more details on the definition files.

2.1. Lexical Structure
A remote-100 definition file consists of a set of commands.  Every
command must start on a new line.  Blank lines and white-space is
ignored.  Lines that begin using the '#' character are regarded as
comments and are ignored.

2.2. Program Structure
The commands inside a remote-100 definition file are organised as
procedure definitions.  No other commands are allowed outside the
scope of a procedure definition.  A procedure definition is structured
as follows:

define <procname>
	<command>
	...
end

This construct defines a procedure named <procname>.  The commands
are executed when the procedure is invoked using the "call <procname>"
command.  The procedure "main" is the starting point for the
interpretation of the definition file.

A minimal file for the control of a simple on/off device could be
the following:

# Minimal remote control file
define main
	print 0 0 "+):On   -):Off   ESC):Quit"
	key 0x1b exit
	key '+ send "##'##[##'#%+##'##X##'##X"
	key '- send "##'##[##'#%+##'##X##'##Y"
end

A remote control file for controling two devices with a mode change
can be implemented as follows:

define main
	cls
	clkey
	print 0 0 "t) TV  v) Video  ESC) Quit"
	key 't call tv
	key 'v call video
	key 0x1b exit
end

define tv
	print 0 0 "ESC) Main"
	cls
	clkey
	key 0x1b call main
	# TV commands are place here
end

defive video
	...

The remote control files can be used to create new features that
are not available in the original products.  As an example the
following sequence implements a "zap" command that cycles through
three tv stations:

define z1
	send "##'##[##'#%+##'##X##'##Y"
	key 'z call z2
end

define z2
	send "##'##[##'#%+##'##A##'##B"
	key 'z call z3
end

define z3
	send "##'##[##'#%+##'##M##'##N"
	key 'z call z1
end

main
	key 'z call z1
	...

A complete, sophisticated control file with mode changes 
and global key definitions is provided in the file rc.rcf.

2.3. Command Description
- define <procname>
Begins a procedure definition.  Following this command other commands
except for the "define" command can be placed.

- end
Terminates a procedure 

- call <procname>
Uppon execution of this command control is transfered to the procedure
<procname>.  When the "end" statement is reached in <procname> control
is transfered back to the command after the "call" command.

- clkey
Clears all key bindings.  The key binding table is entirely cleared.
As a minimum a key binding that results in the program's termination
(via an "exit" command) needs to be installed.

- cls
Clears the screen contents.

- print <row> <column> "<string>"
Prints a string is the row and column specified.  The size of the
screen can be changed when the program is started using the Fn-Zoom
key combination.  Rows and columns are numbered from (0,0).

- exit
Terminates the program.

- key '<character> <command>
  key <number> <command>
Installs a key binding for the specified key.  ASCII keys are
specified using the '<character> notation.  Other keys (arrows,
ALT combinations etc.) are specified by giving the key's scan code
in the top byte of the <number> as in 0x2e00.  (The 0x prefix is
used to specify hexadecimal numbers).  The scan codes can be found
using the "keycode" program or in a technical reference manual for
PC computers.  The scan codes are also automaticaly generated during
the record operation.  The command specified can be any command
appart from "define" and "end".

- send "<string>"
Sends the code signals specified by the string to the infrared
control port.  There are two possible string encodings depending
on the amount of portability desired.  The fully portable 7-bit
format encodes 16-bit integers as three ASCII characters with values
ranging from 0-63 with 0 represented as '#'.

The compact format is represented as follows:

Values 0-127 are represented by a single character where 0 is '\x80'
up to 126 being '\xfe'.  127 is represented by '~'.

Values 128-3711 are represented by two characters using base 128
notation.  The value of the first character is given by representing
1 with 'c', while the value of the second character is represented
as above.

Values 3712 and above are represented using the three byte 7-bit
portable encoding.

Both kinds of encoding can contain embedded spaces to allow for a
bug in the HP 100-LX Memo program which introduces spaces inside
very long strings.

2.4. Run-time Semantics
Program execution normaly starts from the procedure called "main".
Control proceeds serialy from that point transfering control when
a "call" command is encountered.  When the called procedure has
been executed (i.e. the "end" command has been reached) control is
transfered back to the command immediately following the "call"
command.  As the language does not provide any imperative input
statements the "main" procedure normaly terminates after some
initial processing.  After that stage the system enters an event
loop (yes they do crop up everywhere) which transfers control based
on keyboard input events and the corresponding key definitions.
The program terminates when the "exit" command is executed.

All execution is performed directly from the file.  The file is
not read into memory and thus occupies no additional storage.  A
16 element cache stores the last 16 procedures that have been used.
For this reason any initial slugish performance will smooth as the
cache is filled in.  Keys are also directly associated with file
position.  A maximum of 200 key bindings can be stored in the table.
The definition file must not be modified while the program is
running.

3. The Record Format Conversion Program
Bitconv converts definition files from the 8-bit format to the 7-bit
compatible format.

To convert from 8-bit to 7-bit run the program as follows:

bitconv -c <input_file >output_file

To convert from 7-bit to 8-bit run the program as follows:

bitconv <input_file >output_file

4. The keyboard scan code program
In order to find out the scan code of a key run the "keycode" program.
Press any key to see its scan code definition printed out.  Terminate
the program by pressing CTRL-BREAK.

5. Author Contact
The programs have been written by:

	Diomidis Spinellis
	Myrsinis 1
	GR-145 62 Kifissia
	GREECE

	E-mail: dds@doc.ic.ac.uk

Many thanks to Steve Loughran and Gilles Kohl for their assistance.

6. Copyright and Disclaimer

  Copyright (c) 1993, 1994 Diomidis Spinellis.  All rights reserved.
 
  Redistribution and use in binary form, without modification, is 
  permitted provided that the following conditions are met:
  1. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the distribution.
  2. The name of the author may not be used to endorse or promote products 
     derived from this software without specific prior written permission.
  3. Redistribution for profit is not allowed.

  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
  OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
  OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  IN PARTICULAR, NOTE THAT SENDING INCORRECT CODES TO THE REMOTE
  CONTROL LED OF THE HP-100LX MAY PERMANENTLY DAMAGE THE DEVICE.