ToadTog Special Protocol
========================

Because the 1K extender needs to be kept as small as possible,
this special protocol is not pre-installed with the extender as
is done with most other extenders. If you want to use it, you
must install the device (VCR/1800) and protocol (181) upgrades
below in IR.EXE after the extender has been installed.

This version of the ToadTog special protocol is specific to the
Atlas DVR 1K extender.

Upgrade Code 0 = 1F 08 (VCR/1800)
 81 00 01
End

Upgrade Protocol 0 = 01 81 (S3C8+)
 00 00 01 28 03 F0 C2 1C 01 56 C2 07 90 C1 2A F9
 28 03 56 03 07 38 3A 26 C3 03 74 B0 C1 6B 04 38
 03 B0 03 A4 03 C3 2B 0D 87 43 2D A6 7F 80 3B 05
 82 7F C4 3A EE 37 26 03 44 C1 B0 37 2F 03 B4 C1
 B0 AF
End


This is an enhanced of the ToadTog special protocol.

ToadTog lets you construct toggle functions from discrete functions, and/or
construct discrete functions from toggle functions, and/or track the state of
device toggles so that other functions may be sent differently depending on
that state.

To use ToadTog, you define KeyMoves for VCR/1800 with hex commands that are
1 to 13 bytes long.

The first byte of the hex command tells ToadTog which of eight independant
toggles to use, whether and how to change that toggle, and how many keycodes
to execute if the toggle was ON before that change.

The remaining bytes of the hex command consist of two sequences of
keycodes.  The "ON" sequence is first and is zero to seven keycodes long.  The
"OFF" sequence directly follows it and is zero to twelve keycodes long (the
total length of ON plus OFF cannot exceed twelve).  The ON sequence is sent
if the toggle was ON before any change made by the current command.  The OFF
sequence is sent if the toggle was OFF before any change made by the current
command.

To construct the keycode sequences, you must translate each key into its
two digit hex equivalent.  See the attached KeyCodes.htm file for help.  You
can include any key codes in the sequences, including macros and/or nested
uses of ToadTog.

If you find it hard to look up the hex values of a large number of keys,
you may find it easier to make each of the ON sequence and OFF sequence be a
single phantom code.  Then you can define a macro for each of those phantom
codes, so IR.EXE is doing the rest of the key to hex translations for you as
you define the macros.

 In the first byte, the left digit is the selection of which toggle to use
(0 to 7).  The right digit is the length of the ON sequence (0 to 7).

For example, imagine shift-0 (9F) was an existing discrete OFF function
and shift-1 (A2) was an existing discrete ON function and you wanted to use
toggle number 5 to contruct a toggle function.  The hex command would be:
51 A2 91
The "5" means we want to use toggle 5.  The "1" means the ON sequence is one
code long.    The A2 will be sent (to turn the item off) if it was previously
on.  The 91 will be sent if it was previously off.

For another example, imagine shift-power (82) is an existing toggle
function (maybe the "shift cloaked" version of an ordinary power button).  You
want a key that sends that toggle function, but remembers the current state
(in toggle 0) so that other functions can use that information.
01 82 82
The "0" means we want to use toggle 0.  The "1" means the ON sequence is one
code long.  Both sequences are 82 because we always want to do the simple
toggle function, the point here is just to track having done it.

For more advanced uses of ToadTog, you need to add 8 to one or both of the
two digits of the first byte.  If you don't know hex addition, use this table
-----------------------------------------
| digit | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
-----------------------------------------
|   +8  | 8 | 9 | A | B | C | D | E | F |
-----------------------------------------

If you add 8 to the left digit, Toadtog will only test the toggle and not
change it.  If you add 8 to the right digit, Toadtog will turn the toggle OFF
regardless of its previous state.  If you add 8 to the both digits, ToadTog 
will turn the toggle ON regardless of its previous state.

Assume 82 is an existing toggle function and you want to build two new
functions, a discrete ON and a discrete OFF, sharing toggle 1.  These are:

19 82
98 82

"19 82" acts as a discrete off.  "1" means to use toggle number one.
"9" = 1+8 means we want to do 1 keycode if the item was previously ON.  The
fact that we added 8 to the right digit means regardless of the previous
state, at the end of this operation the toggle will be OFF.  The 82 is sent to
turn the item off if it was previously on.  Nothing is sent if it was
previously off (because nothing follows the 1 byte ON sequence within the hex
command).

"98 82" acts as a discrete on.  "98" is 1+8 and 0+8 meaning we are using
toggle number one and the ON sequence is zero codes long.  The fact that we
added 8 to both digits means regardless of the previous state, at the end of
this operation the toggle will be ON.  Nothing is sent if it was previously
on.  The 82 is sent to turn the item on if it was previously off.

To get a certain desired behavior from my cable tuner, I want to use the
sequence MENU, RIGHT, SELECT to turn it off and the sequence SELECT, CH+,
LAST to turn it on.  Also, if the user presses CH+ when the cable tuner is
off I want to send SELECT, CH+, LAST, CH+ (which also turns it on);  But if
it was already on I just want to send CH+.  On the power key I put
03 17 08 0D 0D A9 2B
That means use toggle 0 and 3 codes are in the ON sequence (17 08 0D = MENU,
RIGHT, SELECT), the off sequence is 0D A9 2B = SELECT, shift-CH+, LAST (I
shift-cloaked the CH+ so the setup code's CH+ will be used, not the following
KeyMove).  On the CH+ key I put
81 A9 02 A9
"8" = 0+8 meaning use toggle 0.  "1" means we send 1 keycode (A9 = shift-CH+)
if the device was already on.  If the device was previously off, send 02
(which is power, which is the nested ToadTog command described above) followed
by A9.  Note that I added 8 to the left digit to say this command should not
change the toggle.  That may be confusing because this command is always
leaving the device on.  The detail to understand is that nested commands are
put in the extender's pending buffer and not really executed until this
command thinks it's done.  When the previous state was off, this command must
leave it off, so the 02 command will turn it on.  If that is too confusing, I
could have used
89 A9 0D A9 2B A9
That means to send only A9 if it was previously on, but send 0D A9 2B A9 if
it was off (exactly what the 02 A9 in the other version actually sends) and
I added 8 to both digits so it is clear that the toggle is being turned on
unconditionally.


If you want to re-assemble the extender with this protocol built-in,
copy the source code below and paste into the extender .asm file
in the area indicated.

;-----------------------------------------------------------
; ---- Device/Protocol upgrades for ToadTog
					xorg	D_addr
					org	$$
VCR_1800:
	db	81	;Protocol = 0x181
	db	0	;No digit map
	db	1	;No defined keys
	
					D_addr = $$
					xorg	P_addr
					org	$$
Protocol_181:
	db	00,00,01
					org	Ram
	LD	W2, R03		;Get the "HEX command" from the KeyMove
	SWAP	RC2		;Top digit selects bit number
	LD	W1, 1		;Start with bit 0
L181_1:	AND	RC2, 7		;Use low three bits as bit number, also handle
				; overflow when rotating 8 times for bit 0
	RL	RC1		;Rotate bit into position
	DJNZ	W2, L181_1	;Do it N time for 1 to 7, and 8 times for 0
	LD	W2, R03		;Get the "HEX command" from the KeyMove
	AND	R03, 7		;Length of TRUE side
	LD	W3, R3A		;Body length of keymove
	SUB	RC3, 3		;keylist length
	TM	RC1, R_ToadTog	;Is the bit set?
	JREQ	L181_3		;No
	LD	W3, R03		;Length of TRUE side
	CLR	R03
L181_3:	CP	RC3, R03	;Selected side empty?
	JRLE	L181_4		;Yes
	LD	W4, R2D[W3]	;Get a key code
	CP	R_Mac, AR_MacBuf ;Buffer full?
	JRULE	L181_4		;Yes
	PUSHUD	@R_Mac, RC4	;Insert KeyCode into pending keys
	DJNZ	W3, L181_3
	
L181_4:	BTJRF	L181_5, W2.3	;Set requested?
	OR	R_ToadTog, RC1	;Yes: do it
L181_5:	BTJRT	L181_6, W2.7	;Toggle requested?
	XOR	R_ToadTog, RC1	;Yes: do it
L181_6:	RET
					P_addr = $$
					xorg	D_table+2+DT_index+DT_index
					org	$$
	dw	1F08		;Type=VCR, Protocol>255, setup code = 0x708 = 1800
					xorg	D_table2+DT_index+DT_index
					org	$$
	dw	VCR_1800
					xorg	P_table+2+DT_index+DT_index
					org	$$
	dw	181		;Protocol ID
					xorg	P_table2+DT_index+DT_index
					org	$$
	dw	Protocol_181
					DT_index = DT_index+1

;-----------------------------------------------------------
