========================================= Communication between io and asserv cards ========================================= :Author: djerem Introduction ============ At the present time, the TWI module does not support multi-master mode. The *io* card is the master and the *asserv* and *motor power* cards are the slaves ones. This documents describes the exchange between the *io* and the *asserv* cards. Protocol ======== From io to asserv ~~~~~~~~~~~~~~~~~ General description ------------------- The *io* card send the *asserv* one a message of instruction to pilot it. This message has a variable length. It looks like:: 0 1 2 ... <-- byte position +- - -+- - -+- - - - - -+ | seq | cmd | param ... | +- - -+- - -+- - - - - -+ Here is the complete description of the instruction message: seq a sequence number of 1 byte length. It is a *unique identifier for each command* (this is not perfectly true as the possibilities are limited to 256). It is incremented by one for each new command. When the sequence number reach 255, it is reseted to 1. cmd an identifier for the command we want the *asserv* card to do. It is 1 byte length. parameter It is an optional list of parameters. It depends on the command we want to send to the *asserv* card. Its length can be 0 or more bytes. This is the variable length part of the message. List of supported commands -------------------------- This table describe the list of supported commands by the *asserv* card: +---------+-------+-----------------+------------------------------------------+ | Command | Class | Parameters list | Description | | (cmd) | | (param) | | +=========+=======+=================+==========================================+ | 'z' | Other | None | Reset | +---------+-------+-----------------+------------------------------------------+ | 'w' | Other | None | Free motor (useful for end match) | +---------+-------+-----------------+------------------------------------------+ | 's' | Other | None | Stop | +---------+-------+-----------------+------------------------------------------+ | 'l' | Move | - distance (3b) | Linear move (in step (3/100 mm) | +---------+-------+-----------------+------------------------------------------+ | 'a' | Move | - angle (2b) | Angular move (0 <=> 0° ; 65536 <=> 360) | +---------+-------+-----------------+------------------------------------------+ | 'f' | Move | - direction (b) | Go to the wall | | | | | - direction: 0 = forward, 1 = backward | +---------+-------+-----------------+------------------------------------------+ | 'g' | Move | - direction (b) | Go to the wall, using center sensor | | | | - delay (b) | - direction: 0 = forward, 1 = backward | | | | | - delay: center sensor trigger delay | +---------+-------+-----------------+------------------------------------------+ | 'F' | Move | None | Go to a distributor (forward movement) | +---------+-------+-----------------+------------------------------------------+ | 'x' | Move | - x (3b) | Go to an absolute position | | | | - y (3b) | | +---------+-------+-----------------+------------------------------------------+ | 'r' | Move | - x (3b) | Go to an absolute position, backward | | | | - y (3b) | movement allowed | +---------+-------+-----------------+------------------------------------------+ | 'y' | Move | - a (2b) | Go to an absolute angle | +---------+-------+-----------------+------------------------------------------+ | 'X' | Move | - x (3b) | Go to an absolute position, then an | | | | - y (3b) | absolute angle | | | | - a (2b) | | +---------+-------+-----------------+------------------------------------------+ | 'R' | Move | - x (3b) | Go to an absolute position, then an | | | | - y (3b) | absolute angle, backward movement | | | | - a (2b) | allowed | +---------+-------+-----------------+------------------------------------------+ | 'b' | Mot0 | - position (2b) | Move the motor0 to a desired position | | | | - speed (1b) | at a specific speed | | | | | - position: x steps by x | | | | | - speed: in step by cycle (4.44ms) | +---------+-------+-----------------+------------------------------------------+ | 'B' | Mot0 | - speed (1b) | Find the zero position of the motor0 | | | | | - speed: in step by cycle (4.44ms) | +---------+-------+-----------------+------------------------------------------+ | 'c' | Mot1 | - position (2b) | Move the motor1 to a desired position | | | | - speed (1b) | at a specific speed | | | | | - position: x steps by x | | | | | - speed: in step by cycle (4.44ms) | +---------+-------+-----------------+------------------------------------------+ | 'C' | Mot1 | - speed (1b) | Find the zero position of the motor1 | | | | | - speed: in step by cycle (4.44ms) | +---------+-------+-----------------+------------------------------------------+ | 'p' | Other | See next table | Change setting values | +---------+-------+-----------------+------------------------------------------+ The *'p'* command take different sub-parameters to configure the settings. +-----+-------------------------------+-------------------------------------+ | 'X' | X position (3b) | Set current x position | +-----+-------------------------------+-------------------------------------+ | 'Y' | Y position (3b) | Set current y position | +-----+-------------------------------+-------------------------------------+ | 'A' | angular position (2b) | Set current angular position | +-----+-------------------------------+-------------------------------------+ | 's' | - linear high speed (1b) | Set the speed setting | | | - angular high speed (1b) | | | | - linear low speed (1b) | | | | - angular low speed (1b) | | +-----+-------------------------------+-------------------------------------+ | 0 | None | End of sub-parameters | +-----+-------------------------------+-------------------------------------+ The classes of the commands are used for the responses of the *asserv* card that can only confirm some commands. From asserv to io ~~~~~~~~~~~~~~~~~ General description ------------------- The *asserv* card maintains a buffer than can be retrieved by the *io* card. This buffer contains the status of the last command transmitted by the *io* card. It is used to know if the last command sent by the *io* card is currently executed, is finished or has failed (i.e. we are blocked) and also to retreive the current position (X, Y, alpha) of the bot and its motors. The buffer is a static 12 bytes length one:: 0 1 2 3 .. 5 6 .. 8 9 10 11 12 13 14 <-- byte position +--------+------+-----+- - - -+- - - -+-------+----------+----------+ | status | PINC | seq | X pos | Y pos | angle | mot0 pos | mot1 pos | +--------+------+-----+- - - -+- - - -+-------+----------+----------+ Status value ------------ Status contains flag bit to know the status of movement and motors commands: if they have finished with success or with an error (i.e. blocked). Here is a list of the bits used and their definitions: 0. Movement finished with success (MF); 1. Movement finished with failure: the bot is blocked (MB); 2. Movement is going forward: the current linear speed is greater than 0 (FWD); 3. Movement is going backward: the current linear speed is smaller than 0 (BCK); 4. Motor0 movement finished with success (A0F); 5. Motor0 movement finished with failure: it should not happen (A0B); 6. Motor1 movement finished with success (A1F); 7. Motor1 movement finished with failure: it should not happen (A1B). The others bits are unused. An example of communication =========================== We now have the theory and the details, but to better understand, let's make a concrete example. The *io* card send the command for going to the wall (10, 'f') to the *asserv* card and internally stores the sequence number used for the command. If the *io* card read the buffer from the *asserv*, it can see: 1. the sequence number is not the one of the command sent. The *asserv* card has not received and started the command yet. Nothing has to be done, we need to wait. 2. the sequence number is the one of the command sent but the status bits MF and MB are zero. The command has started to be executed but is not finished yet. We can not sent another command. 3. the sequence number is still the one of the command sent and the status bits MF or MB are set to one. The command is now finished and another one can be started. The state machine can evolve.