summaryrefslogtreecommitdiffhomepage
path: root/digital/io/doc/proto_asserv.txt
blob: 259b09053d3aaefec1cd75821e1eed2c77b07d90 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
=========================================
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.