Ceux qui ont déjà fait un peu de code savent à quel point il peut être tentant de se lancer tête baissée dans un développement sans avoir pris le temps de réfléchir un minium au préalable. Et à quel point cela peut s’avérer une fausse bonne idée lorsque le développement est démarré depuis longtemps et qu’il faut reconsidérer la moitié de l’implémentation à cause d’une erreur de conception.

Pour une fois, j’ai décidé de suivre la voie de la sagesse, si l’on peut dire, en choisissant de poser avec soin les bases de la communication avec le futur backend du robot Youpi, et de ne pas commencer à coder à la hâte.

Je dévoile donc dans la suite de cet article le draft de communication frontend-backend imaginé ce week-end pendant quelques moments perdus. Il permet déjà d’avoir un bon aperçu de la manière d’implémenter ces exigences dans le code.

Pour ceux qui auraient tendance à trouver ce formatage quelque peu indigeste (et je les comprends), une version RTF avec quelques couleurs est disponible ici : Youpi backend instruction manual (RTF).

Title: Youpi backend instruction manual
Author: AlphaK - www.alphak.net
Revision: 2011-08-01
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)!!
A specialAction contains exactly one of the I, C, R 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.
R: Re-init - Asks the backend to send the re-init instruction to the robot.
.
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 instructionSet.
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 instructionSet.
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
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 motors to rotate back to their initial position according to motor counters. USE WITH CAUTION!
.
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.
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. 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 same 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° 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
.

Quelques explications supplémentaires en plus du pavé ci-dessus :

Le backend s’attend à recevoir une commande par ligne. Une commande permet de mettre en mouvement ou arrêter un seul ou plusieurs moteurs. Grâce aux différents en-têtes des instructionChainModifiers, le robot sera pilotable en mode temps réel (interactions directes avec l’utilisateur via le frontend), ou scripté (une floppée de commandes fournie au démarrage ou graduellement, et le robot exécute le tout). J’ai également prévu un léger reporting afin que l’utilisateur puisse connaitre la position de chaque moteur depuis une origine et ainsi établir plus facilement ses commandes si un pilotage scripté est désiré.

Le diagramme suivant permet d’avoir un meilleur aperçu des possibilités théoriques du backend. Chaque ligne correspond à un moteur. En abscisses, le temps. Chaque subdivision correspond à une seconde. Une barre horizontale bleue située sur une ligne indique la rotation du moteur correspondant. En bleu figurent également les commandes, ainsi que le moment où elles sont envoyées au backend. Les instructionSets qui composent l’instructionChain sont encadrés en rouge.

Diagramme de commandes

Voila l’état d’avancement actuel. Il s’agit de ce que je considère actuellement comme un ensemble « idéal » de fonctionnalités. Ces exigences sont encore à l’état de draft et pourront évoluer dans le futur en fonction des différents commentaires et remarques. Pour ce qui est de l’implémentation, j’imagine que ça se fera par étapes en fonctions des priorités.