Title: Youpi backend instruction manual
Author: AlphaK - www.alphak.net
Revision: 2011-08-14
Status: Draft



GLOSSARY

An instruction is an order for a motor to start or stop a rotation.

An instructionSet is a set of instructions executed simultaneously.

An instructionChain is a set of instructionSets executed sequentially.

An instructionChainModifier is a request to the backend for the modification of the current instructionChain.

A specialAction is a request to the backend not related to the rotation of a motor.

A command is a set of printable characters sent to the backend to order an instructionChainModifier or a specialAction.



SYNOPSIS

command
	(instructionChainModifier|specialAction)\n
	A command contains exactly one instructionChainModifier or one specialAction, and ends with a carriage return character (byte 0x0A, symbolized with \n in this document for readability).

specialAction
	(I|C|R|D|S)!![integerValue]
	A specialAction contains exactly one of the I, C, R, D characters and ends with a double exclamation mark.
	I: Information request - Asks the backend to report for each motor the number of half-steps executed since the beginning of the program or the last half-step counter reset.
	C: Counter restet - Asks the backend to reset half-step counter. USE WITH CAUTION!
	R: Re-init - Asks the backend to send the re-init instruction to the robot.
	D: Disable - Asks the backend to disable or enable parallel port output. Set integerValue to 1 to disable and to 0 to enable parallel port output. This is typically used for debugging purposes. When parallel port output is disabled, orders are not sent to the robot, but still appears in logs, and instructions are run faster.
	S: Save motor counters to a slot. All motor counters are stored. Slot numbers are from 1 to 99. Slot 0 refers to initial position, it is readable but not writable.

instructionChainModifier
	[action!waitMode!]instructionSet
	An instructionChainModifier contains an action, a waitMode parameter, and an instructionSet, separated by exclamation marks. action and waitMode are optional; instructionChainModifier defaults to C!W!instructionSet when not provided by the frontend.

action
	C|A|M
	An action contains exactly one of the C, A, M characters.
	C: Cancel - The current and all the following instructionSet in the instructionChain are cancelled, and the instructionChain starts executing the provided instructionSet.
	A: Append - The provided instructionSet is appended at the end of the instructionChain.
	M: Merge - The current instructionSet in the instructionChain is merged with the provided instructionSet. Remaining instructionSets in the instructionChain are not altered. If the provided instructionSet contains instructions related to a motor for which there is no instruction in the current instructionSet, provided instructions are added to the current instructionSet. If the provided instructionSet contains instructions related to a motor for which there is already an instruction in the current instructionSet, current instructions are cancelled and replaced by provided instructions.

waitMode
	W|N|D
	A waitMode contains exactly one of the W, N, D characters.
	W: Wait - Sets the instructionSet in wait mode. In that mode, the backend waits the end of all instructions of the instructionSet to consider the last is over and to execute next instructionSet. If the ordered action is M, the waitMode of the current instructionSet is replaced by the waitMode of the provided instructionChainModifier.
	N: Nowait - Sets the instructionSet in nowait mode. In that mode, the backend considers the instructionSet as over as soon as the first instruction has ended. If the ordered action is M, the waitMode of the current instructionSet is replaced by the waitMode of the provided instructionChainModifier.
	D: Default - If the ordered action is C or A, waitMode D defaults to W. If the ordered action is M, waitMode D does not modify the waitMode of the current instructionSet.

instructionSet
	instruction[|instruction...]
	An instructionSet contains one or more instructions. Each instruction is separated by a pipe character. If an instructionSet contains several instructions related to the same motor, the instructionSet is considered invalid.

instruction
	motor,rotation,unit,value,period
	An instruction contains exactly 5 parameters given in an invariable order and separated by a comma.

motor
	0|1|2|3|4|5|A
	A motor contains exactly one of the 0, 1, 2, 3 4, 5, A characters. The provided character is related to a motor of the robot.
	0: Base motor
	1: Shoulder motor
	2: Elbow motor
	3: Wrist motor
	4: Hand motor
	5: Plier motor
	A: All motors

rotation
	L|R|N|I|S|A
	A rotation contains exactly one of the L, R, N, I characters. The provided character is related to a rotation order.
	L: Left rotation
	R: Right rotation
	N: No operation. Asks the motor to stop.
	I: Back to initial state. Order motor to rotate back to its initial position according to motor counters. In that case, unit and value are ignored.
	S: Load slot. In that case, unit is ignored, and value refer to the slot number. If value is greater than the max slot number, or if the slot is empty, the instruction is ignored. By default, only slot 0 is filled with initial position.
	A: Absolute positioning. Order motor to rotate to an absolute position according to motor counters. In that case, unit is ignored and value takes the absolute position to be reached.

unit
	H|D|S|U
	A unit contains exactly one of the H, D, T, U characters. The provided character is related to a unit order. If rotation is I, unit must be U.
	H: Half-step - Provided value represents half-steps, or steps for plier motor.
	D: Degrees - Provided value represents degrees. Not relevant for plier motor.
	S: Seconds - Provided value represents seconds. Note that using seconds as the unit is not accurate, and may not give the same halfsteps value each time.
	U: Unlimited - Ordered rotation has no limit. USE WITH CAUTION!

value
	Float value, greater or equal than zero. Decimal separator is a dot '.'.
	The value is provided according to the provided unit or slot. If unit is U, value must be 0. As there is no physical or logical limits on the robot to ensure the motor does not exceed the maximum rotation angle, the frontend must ensure that provided values and unit will not damage the robot.

period
	Float value, greater or equal than one. Decimal separator is a dot '.'.
	The period affects the rotation speed for each motor. Default period is 1 and represents the maximum motor speed. The provided period is proportional to the interval of low-level orders sent to the motor. For instance a provided period of 2 will make the motor rotate twice as slow as the maximum speed.



EXAMPLES

Cancel all orders and asks the base motor to rotate left over 40 degrees at maximum speed:
	C!W!0,L,D,40,1\n

Appends the order for the shoulder motor to rotate right during 5.2 seconds with 1/3 of maximum speed:
	A!W!1,R,S,5.2,3\n

Immediately cancel all orders, asks all motors to stop for an unlimited duration:
	C!W!A,N,U,0,1\n

Cancel all orders and asks elbow and wrist motors to rotate simultaneously 150 half-steps each:
	C!W!2,R,H,150,1|3,L,H,150,1\n

Adds the order for the base motor to rotate 600 half-steps at half speed meanwhile other motors are already rotating:
	M!D!0,L,H,600,2\n

Puts back base motor into initial position at 1/4 speed:
	C!W!0,I,U,0,4\n
