'>Hxtr2-Doc.bsx					D Buckley 20-11-01
'==============================================================
'Meta Commands and Program Headers - Hxtr
'==============================================================
'Meta Commands overview
'----------------------
'
'Ultrasonic behaviour rules
'  I	if selected by the test then includes a Prog/Option,
'	first parameter is prognumber, second is Option. 
'	Return address is stacked.
'	"I" can be used to run any program + option including
'	US behaviours, however yawn variables values will be
'	inherited.
'  X	if action ="X" then ignore that result.
'  J	if action ="J" then jump to new program, no stack action
'	first parameter is prognumber, second is option
'	so we can even run another US behaviour.
'	If the Option is 0 then the jumped to Prog will be forced
'	to check the stack and so acts as RETURN.
'  Yawn 
'  ----
'	The yawn rules are special in that when an outcome of 
'	other rules is activated scanning through the rule set is
'	terminated, however the "Y" rule only tests whether the 
'	next rule should be used, and the "y" rule only resets 
'	the "yawn" variable before the rule following it is used. 
'	The first parameter byte for "Y" or "y" is the index to 
'	the yawn variable, 0=>usyawn0, 1=>usyawn1.
'	The second parameter byte is the threshold
'  Y	if selected by the test increments 'usyawnX'.
'	If 'usyawnX'> threshold then skip the following rule.
'  y	if selected then resets 'usyawnX' to 0
'  so select same parameters for rule to be skipped for both Y, y
'Sequences
'	z - terminator for sequences
'	J - Jump to another Program, where option is selected 
'		from Program's name table
'		"J",<prog>,<option>	jump to Prog with Option
'		eg	"J",7,U_LcdCon would jump to LCDKeys routine
'			"J",2,US_wander would jump to US_wander
'	j - jump, used in sequences, acts as a GOTO
'		eg "FBRLj",A_wiggle,"FROP..
'		jumps to the sequence 'A_wiggle' 
'		and ignores the rest of the original sequence,
'		use for endless sequences or for joining sequences
'		eg "FBRLj",A_wiggle
'		jumps to the sequence 'A_wiggle' instead of ending.
'		eg
'			wiggle DATA "FBRLj",A_wiggle
'		will do A_wiggle forever (or until battery goes flat)
'		Note the name is from the name table not a data pointer. 
'	i - include, use in sequences, acts as a GOSUB
'		eg "FBRLi",A_wiggle,"FROP.. 
'		does the sequence 'A_wiggle' and then returns.
' 	x - eXecute a Basic subroutine, used in sequences
'		"x",<routine number>,<argument>
'		eg "FBRLx",xleds,n,"FROP...
'		where xleds is the name of a constant used to 
'		control a Branch command in the subroutine Xecute
'		and 'n' is the parameter for the routine. 
'	e - Evaluate, do a test in Basic and branch on the result
'	"e",<branch index to ename>,<argument>,<test{<,=,>}>,<activity>
'		eg "FBRLe",ebump,%01,"=",A_avoid,"FFBB...
'		where ebump is the name of a constant used to 
'		control a Branch command in the subroutine doeval.
'		In this case if the test was true then the sequence
'		A_avoid would be GOTOed.
'	u - do USrulename in Ultrasonic behaviour program
'		"u",<USrulename>
'		if the US-rules result in A then the the activity 
'		will be returned to
'	I - Indicators, change LEDs state
'		"I",<newLEDstate>	change LED state
'	b - bump, test feelers
'		"b",<bumpcode=0,1,2,3>,<activity>
'		if feelers=bumpcode then do <activity>
'		(bumpcode is logical value, feelers are active low)
'		bumpcode=0	no bump	
'		bumpcode=1	bumped left
'		bumpcode=2	bumped right
'		bumpcode=3	bumped both
'
'	A_null - running the Activity Sequencer program with 
'		A_null in CommonRAM as the activity to do causes 
'		the program to look in the CommonRAM stack for the
'		place to resume sequencing. If there is no 
'		suspended activity then the program runs pgm0.
'
'Using BOS commands in sequences
'	The ascii BOS commands with decimal arguments, 
'	ie hmlrsw with one argument
'	and vng with two arguments
'	when used from a terminal are sent as 
'	<character><decimal value>CR(<decimal value>)CR but when used in a
'	sequence are written as 
'		DATA ... <character>,<byte value>,(<byte value>)
'	without the CR, ie the decimal value is stored in DATA as
'	a byte, this made it easier to read the sequence.
'	(note CR could be space or other non-numeric text)
'--------------------------------------------------------------
'BOS Commands overview - BOS chip firmware
'---------------------
'On reset the pgm prints a msg:- 
'	"Bug Commander BC x.x - Milford Instruments",cr
'  and waits for a serial ascii command, ready prompt is '>'.
'Control of the Behavioural Operating System BOS is by serial
'  commands from another processor or a terminal.
'A command may be halted by:-
'  raising the 'cmndhalt' pin until the 'busypin' goes low or
'  by sending "H" continuously until ">" is received,
'  It is not possible to interupt "h","V","v".
'dec arguments must be ended by CR or other non-numeric code
'
'Main Commands:-
'	Can be used manually from a terminal.
'	Commands ignored if cmndhalt pin is high or if no prompt.
'	'busypin' goes high as soon as the first byte of a command
'	  is received and should be ignored for further bytes of
'	  multibyte commands.
'single character:-
'	F - Forward one step
'	B - Backward one step
'	R - Rightturn one step
'	L - Leftturn one step
'	H - Halt
'	S - Sit
'	U - Up
'	M - step so feet are in Midposition
'	N - goto Neutral position, current values held in EEPROM
'	K - Kill servo power,
'		jumper selectable to exclude gripper,
'		power turned on by any movement command
'		or by jumping to direct Control.
'	Z - Zzzz 	all servos to sleep
'	Q - Quick,	legs move in Trapezoid path, 
'			smooth but can stub toes
'	T - Tall,	legs move in Rectangular path, 
'			leg up/down is vertical
'	p - pickup Gripper by 1/16 range
'	P - Pickup Gripper by 1/4 range
'	d - down Gripper by 1/16 range
'	D - Down Gripper by 1/4 range
'	o - open Gripper by 1/16 range
'	O - Open Gripper by 1/4 range
'	c - close Gripper by 1/16 range
'	C - Close Gripper by 1/4 range
'	W - Wait until all servos finish moving, 
'		only useful after gripper commands 
'		and direct control
'	V - Voice, beep 1KHz for 0.1sec
'one argument:-							defaults
'	s<dec Sspeed>  - speed,     	update variable Sspeed	  4	                  (0-15)
'	r<dec legdown> - rideheight 	update variable legdown	170 down from neutral     (0-255)
'	m<dec swing>   - move	 	update variable swing	 40 +- about neutral      (0-255)	
'	l<dec lift>    - lift 	 	update variable lift	 90 up from down position (0-255)
'		updates to s,r,m,l are not remembered during power off
'	h<dec sec*10>  - halt for time, 1=0.1sec
'		BOS deaf to HALT during this time,
'		useful for direct control and voice etc
'	w<dec servo>   - wait until servo is finished moving
'		only useful after gripper commands 
'		and direct control
'   individual control of Legs or Body, used for Wave-Gait:-
'       <0,1,2,3,4,5,6>,<f,m,b>
'       <0=body, 1-6=legs>,<forward,midposition,back>
'       1f => Leg 1 steps forwards
'       1m => Leg 1 steps to mid position
'       1b => Leg 1 steps backwards
'       similarly for Legs 2,3,4,5,6
'       0f => Body moves forwards, ie all Legs move backwards without steping
'       0m => Body moves to mid position, ie all Legs move to mid position without steping
'       0b => Body moves backwards, ie all Legs move forwards without steping
'two argument:-
'	n<dec servo,dec position>	- new neutral position
'		servos 0 - 11, new values stored in BOS eeprom
'		if servo >11 then return to main command prompt
'	g<dec glift,dec ggrip>	 	- gripper lift and grip
'		0 => no change, 255 - relax servo
'		(easy to type a 0 for no change 
'			or wait for 5sec timeout)
'	v<dec Hz/10,dec ms/10>		- voice, beep,Hz/10,ms/10
'Requests - one argument:-
'	?g - arm and grip positions 	-> <dec glift,cr,dec grip,cr>
'	?s - Sspeed			-> <dec Sspeed,cr> 
'	?r - rideheight			-> <dec legdown,cr>
'	?m - move			-> <dec swing,cr>
'	?l - lift			-> <dec lift,cr>
'	?n - neutral positions, 
'		get EEPROM data for neutral position
'		for servos 0 - 11 -> <dec servo," ",dec tox,cr>
'Low level Direct Control
'------------------------
'3 byte:-
'	- direct control of servos
'	not suitable for human use from terminal, 
'		byte values and 100ms timeout
'	turns on servo power and exits with servo power on
'	first byte 	- control byte (non printing) character (<6) 
'	second byte	- $speed;$servo	- high nibble and low nibble respectively
'	third byte	- argument
'	X		- any value - ignored
'	commands:-
'	0,$speed;$servo,position
'	1,$X;$servo,X 	->P	return byte P is actual servo position 
'	2,$X;$servo,X 	->S	return byte S is servo status, 
'				bit1	0=>servo off
'					1=>on, ie being pulsed
'				bit0	0=moving to requested position 
'					1=at requested position 
'	3,X,X	->hiF,then loF	two bytes all servo moved status
'					bitX=servoX, 1=>finished
'					bit15 is set to 1
'					so all finished=$FFFF
'	4,X,X	->hiR,then loR	two bytes all servo on/off status
'				bitX=servoX, 1=>being pulsed, ie on
'				bit15 always 1
'	5,$X;$servo,X		stop pulsing servo
'The servos are refered to by their logical positions,
'
'-------- Legs & Logical-Servos --------
'
' Plan view of Hextor	S - Servo(0 - 13)	L - Legs(1 - 6)
'	 S    L   L    S
'	       ( )	gripper 13
'	       | |	lift    12
'	    L---F---R		LEG NUMBERS
'	1,0 | 1   2 | 6,7	1=LF	2=RF	,L - left, R - Right
'	3,2 | 3   4 | 8,9	3=LM	4=RM	,M - mid,  F - Front
'	5,4 | 5   6 | 10,11	5=LB	6=RB	,B - Back
'	    \-------/
'
'-------- Servo values and leg positions -------
'	f - forward	m - middle	b - backward
'Left	Lf=255		Lm=127		Lb=0
'Right	Rf=0		Rm=127		Rb=255
'
'	d - Down	u - Up
'Left	Ld=0		Lu=255
'Right	Rd=255		Ru=0
'
'-------- Arm and Gripper positions -------
'Arm up 255
'Arm down 0
'Gripper open 255
'Gripper closed 0
'==============================================================



'**************************************************************
'		Program Headers - Hxtr2-0 to Hxtr2-7
'**************************************************************
'>Hxtr2-0.BSx
debug "prog0"
'==============================================================
'{$stamp BS2sx,Hxtr2-1,Hxtr2-2,Hxtr2-3,Hxtr2-4,Hxtr2-5,Hxtr2-6,Hxtr2-7}
'Unfortunately that was a long line, ask Parallax.
'==============================================================
'Hxtr2-0.BSx	- main 
'Hxtr2-1.BSx	- Activity sequencer
'Hxtr2-2.BSx	- US Behaviour
'Hxtr2-3.BSx	- Direct Control
'Hxtr2-4.BSx	- Prog4
'Hxtr2-5.BSx	- Prog5
'Hxtr2-6.BSx	- Prog6
'Hxtr2-7.BSx	- Utils- LCD menu and IR remote
'Hxtr2-Doc.BSx	- Meta Commands and Program Headers
'==============================================================
'Parallax bug fix for Windoz Editor ver1.1
'must have a debug stmnt as first executable stmnt in page0
'otherwise editor will not always load some higher pages.
'debug cls
'==============================================================
'New
'---
'flags written to eeprom3 to make non volatile
'flags initialised to default after download, 
'	Fflagsvalid=flags.7 tested
'
'Required knowledge:
'
'Common RAM:
'Constants:	Fdefaults
'Variables:	Fflagsvalid
'Routine:	mopt3 and mopt4 BRANCH used instead of repeated IFs	
'Subroutine:
'Labels:	
'LCD text:	dms0 messages added to for Fokus Fokleds Fokfeel
'Behaviours:
'==============================================================
'Activities name-table program1
'------------------------------
A_null		`con 0
A_chirp1	con 1
A_beep2		con 2
A_wiggle1	con 3
A_wiggle2	con 4
A_wiggle3	con 5
A_Qs4r170	con 6
A_Ts0r200	con 7
A_tround	con 8
A_beg		con 9
A_Rface		con 10
A_Lface		con 11
A_F5		con 12
A_R5		con 13
A_L5		con 14
A_BR		con 15
A_BL		con 16
A_L3		con 17
A_R3		con 18
A_L2		con 19
A_R2		con 20
A_Iflash	con 21
A_Fbump		con 22
A_FbumpRI1	con 23
A_FbumpLI2	con 24
A_FbumpBI3	con 25
A_last		con 25	'last routine

'Ultrasonic-behaviour name-table program2
'----------------------------------------
US_null		con 0
US_sitby	con 1
US_beg		con 2
US_hello	con 3
US_wander	con 4
US_user1	con 5
US_user2	con 6
US_user3	con 7
US_user4	con 8
US_last		con 8	'last routine

'Utilities name-table  program7
'------------------------------
U_KlcdCon	con 1
U_KirCon	con 2
U_last		con 2	'last routine
'--------------------------------------------------------------
'common RAM
'0	program to return to	- all
'1	Program option - Activity to do, USrules to do, Options
'2	current Utility routine
'3	usyawn0		- US-behaviour
'4	usyawn1		- US-behaviour
'5	irin			- current IR value on change of pgm
'6	oldbtn		- current button on change of pgm
'7	menc			- last menu code
'8	mopts			- menu option OAUIP
'9	flags			- various flag bits
'		bit0=irwatch 	- 0=>ignore IR signal, 1=>act on it
'		bit1=useLEDs	- 0=>ignore LED cmnds, 1=>enable LEDs
'					(if pins remapped)
'		bit2=usefeelers	- 0=>ignore feelers
'		bit3=useUS	- 0=>don't run US routines
'		bit4=warmIR	- 1=>IR chip needs no warmup time
'		bit7=flagsvalid	- 0 after download, 1->ok
'Note there is no test for the stack being too big, beware of
'the stack growing down through 9!   
'60 down	sequence stack
'61		sequence stack pointer
'62		letterbox for push and pop
'63		active program number used by BS2Sx
'--------------------------------------------------------------
'LCD commands.
'For more detailed information see the ILM-216 User Manual.
'Function						ASCII
'--------						-----
'Null							0
'Cursor home						1
'Hide cursor						4
'Show underline cursor					5
'Show blinking-block cursor				6
'Bell (not implemented with Hextor LCD)			7
'Backspace						8
'Horezontal tab (4 columns)				9
'Smart linefeed (cursor down one line)			10
'Vertical tab (cursor up one line)			11
'Formfeed (clear screen)				12
'Carriage return					13
'Backlight on						14
'Backlight off						15
'Accept cursor position entry				16
'	64 is the start of the first line
'	80 is the start of the second line
'Format right aligned text				18
'Escape (ESC; start multipart instruction)		27
'		 -------------------
'		|	  LCD	    |
'		 -------------------
'LCD keys -      bit0 bit1 bit2 bit3
'**************************************************************
'>Hxtr2-1.BSx
'==============================================================
'{$stamp BS2Sx}
debug "prog1"
'==============================================================
'Hxtr2-0.BSx	- main 
'Hxtr2-1.BSx	- Activity sequencer
'Hxtr2-2.BSx	- US Behaviour
'Hxtr2-3.BSx	- Direct Control
'Hxtr2-4.BSx	- Prog4
'Hxtr2-5.BSx	- Prog5
'Hxtr2-6.BSx	- Prog6
'Hxtr2-7.BSx	- Utils- LCD menu and IR remote
'Hxtr2-Doc.BSx	- Meta Commands and Program Headers
'==============================================================
'
'New
'---
'
'CommonRam: 
'Meta command: 
'Constants:	
'Variables: 
'Routine:
'Sequences:
'==============================================================
'Direct Control
'turns on servo power and exits with servo power on
'BOSbusy goes low immediately, doesn't wait for move to finish
'$speed;$servo - high nibble and low nibble respectively
'  	BOScmnd,arg1.arg2
'	0,$speed;$servo,position
'	1,$XX,$servo,X 	->P	actual servo position 
'	2,$XX,$servo,X 	->S	servo status, bit1-on bit0-done 
'	3,X,X	->hiF,then loF	two bytes all servo moved status
'	4,X,X	->hiR,then loR	two bytes all servo on/off status
'	5,$XX;$servo,X		stop pulsing servo
'
'-------- Legs & Logical-Servos --------
'
' Plan view of Hextor	S - Servo(0 - 13)	L - Legs(1 - 6)
'	 S    L   L    S
'	       ( )	gripper 13
'	       | |	lift    12
'	    L---F---R		LEG NUMBERS
'	1,0 | 1   2 | 6,7	1=LF	2=RF	,L - left, R - Right
'	3,2 | 3   4 | 8,9	3=LM	4=RM	,M - mid,  F - Front
'	5,4 | 5   6 | 10,11	5=LB	6=RB	,B - Back
'	    \-------/
'
'-------- Servo values and leg positions -------
'	f - forward	m - middle	b - backward
'Left	Lf=255		Lm=127		Lb=0
'Right	Rf=0		Rm=127		Rb=255
'
'	d - Down	u - Up
'Left	Ld=0		Lu=255
'Right	Rd=255		Ru=0
'
'-------- Arm and Gripper positions -------
'Arm up 255
'Arm down 0
'Gripper open 255
'Gripper closed 0
'**************************************************************
'>Hxtr2-2.BSx
'==============================================================
'{$stamp BS2Sx}
debug "prog2"
'==============================================================
'Hxtr0-2.BSx	- Main 
'Hxtr1-2.BSx	- Activity sequencer
'Hxtr2-2.BSx	- US Behaviour
'Hxtr3-2.BSx	- Direct Control
'Hxtr4-2.BSx	- Prog4
'Hxtr5-2.BSx	- Prog5
'Hxtr6-2.BSx	- Prog6
'Hxtr7-2.BSx	- Utils- LCD menu and IR remote
'HxtrDoc-2.BSx	- Meta Commands and Program Headers
'==============================================================
'New
'---
'
'Required knowledge:
'
'Meta command: 
'BOS Commands:	
'Common RAM:   
'Constants:		
'Variables:
'Routine:	
'Subroutine:
'Labels:
'		
'usRules:	
'Behaviour:	 
'**************************************************************
'>Hxtr2-3.BSx
'==============================================================
'{$stamp BS2Sx}
debug "prog3"
'==============================================================
'Hxtr2-0.BSx	- main 
'Hxtr2-1.BSx	- Activity sequencer
'Hxtr2-2.BSx	- US Behaviour
'Hxtr2-3.BSx	- Direct Control
'Hxtr2-4.BSx	- Prog4
'Hxtr2-5.BSx	- Prog5
'Hxtr2-6.BSx	- Prog6
'Hxtr2-7.BSx	- Utils- LCD menu and IR remote
'Hxtr2-Doc.BSx	- Meta Commands and Program Headers
'==============================================================
'New
'---
'
'Required knowledge:
'
'Meta command:
'BOS Commands:	
'Common RAM: 
'Constants:	
'Variables:
'Routine:	 	
'Subroutine:
'Labels:		
'Sequence:		
'usRules:	
'Behaviour: 
'**************************************************************
'>Hxtr2-4.BSx
'==============================================================
'{$stamp BS2Sx}
debug "prog4"
'==============================================================
'Hxtr2-0.BSx	- main 
'Hxtr2-1.BSx	- Activity sequencer
'Hxtr2-2.BSx	- US Behaviour
'Hxtr2-3.BSx	- Direct Control
'Hxtr2-4.BSx	- Prog4
'Hxtr2-5.BSx	- Prog5
'Hxtr2-6.BSx	- Prog6
'Hxtr2-7.BSx	- Utils- LCD menu and IR remote
'Hxtr2-Doc.BSx	- Meta Commands and Program Headers
'==============================================================
'Put your program here, when finished do RUN 0

RUN 0			'so we get back to program 0
'**************************************************************
'>Hxtr2-5.BSx
'==============================================================
'{$stamp BS2Sx}
debug "prog5"
'==============================================================
'Hxtr2-0.BSx	- main 
'Hxtr2-1.BSx	- Activity sequencer
'Hxtr2-2.BSx	- US Behaviour
'Hxtr2-3.BSx	- Direct Control
'Hxtr2-4.BSx	- Prog4
'Hxtr2-5.BSx	- Prog5
'Hxtr2-6.BSx	- Prog6
'Hxtr2-7.BSx	- Utils- LCD menu and IR remote
'Hxtr2-Doc.BSx	- Meta Commands and Program Headers
'==============================================================
'Put your program here, when finished do RUN 0

RUN 0			'so we get back to program 0
'**************************************************************
'>Hxtr2-6.BSx
'==============================================================
'{$stamp BS2Sx}
debug "prog6"
'==============================================================
'Hxtr2-0.BSx	- main 
'Hxtr2-1.BSx	- Activity sequencer
'Hxtr2-2.BSx	- US Behaviour
'Hxtr2-3.BSx	- Direct Control
'Hxtr2-4.BSx	- Prog4
'Hxtr2-5.BSx	- Prog5
'Hxtr2-6.BSx	- Prog6
'Hxtr2-7.BSx	- Utils- LCD menu and IR remote
'Hxtr2-Doc.BSx	- Meta Commands and Program Headers
'==============================================================
'Put your program here, when finished do RUN 0

RUN 0			'so we get back to program 0
'**************************************************************
'>Hxtr2-7.BSx
'==============================================================
'{$stamp BS2Sx}
debug "prog7"
'==============================================================
'Hxtr2-0.BSx	- main 
'Hxtr2-1.BSx	- Activity sequencer
'Hxtr2-2.BSx	- US Behaviour
'Hxtr2-3.BSx	- Direct Control
'Hxtr2-4.BSx	- Prog4
'Hxtr2-5.BSx	- Prog5
'Hxtr2-6.BSx	- Prog6
'Hxtr2-7.BSx	- Utils- LCD menu and IR remote
'Hxtr2-Doc.BSx	- Meta Commands and Program Headers
'==============================================================
'New
'---
'
'CommonRam: 
'Variables:
'Routines:
'==============================================================
'IRremote - trained on keys 1,2,3,4,5,6,7,8
'The trained keys are numbered from 1,
'but in the program the commands and command pages are numbered
'from 0  
'on powerup cmndpge=0
'pages are indicated by the two LEDs, red,green = 00,01,10,11 
'
'	cmnd	cmndpge=0	cmndpge=1	cmndpge=2	cmndpge=3
'key1	0	Forward		Sit		Grip Pick	RUN0  *
'key2	1	Backward	Up		Grip Down
'key3	2	Rightturn	Midd		Grip Open
'key4	3	Leftturn	Kill		Grip Close	uswander
'
'	LEDs		
'key5	00	cmndpge=0
'key6	01	cmndpge=1
'key7	10	cmndpge=2
'key8	11	cmndpge=3
'**************************************************************