summaryrefslogtreecommitdiff
path: root/host/doc/simulator.txt
blob: b5ae1db9bfe9434962485214180db316f7671dd7 (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
211
212
213
214
=================
 Robot simulator
=================
:Author: Ni

This document tries to introduce the APBTeam robot simulator system to
curious and new developers.

Do not try to find a simulator program, there is none.  The simulator system
is assembled from different components communicating together.

What makes this simulator system really useful is that the program which runs
in the simulated environment is really the one running on the real robot.

This document is biased toward our robotic system, but with small
modifications, each component can easily be reused for another system.

Even if you do not reuse any component, the system architecture can be
interesting if you plan to implement a simulator.

Overview
========

The real robotic system is composed of several microcontrollers communicating
directly using hardware buses and indirectly by the environment (for example,
if a microcontroller makes the robot move, an other one may "see" the movement
using a sensor staring at the floor).

In the simulated system, the programs which are supposed to be run on the
microcontrollers are compiled for the host [#]_ computer.  Code accessing the
real world or microcontroller special peripherals is replaced with code
simulating this part.

This replacement should be done at the lowest level.  For example, a code
accessing a distance sensor will be replaced, but the code processing the
distance sensor measures should stay unchanged.  The less is replaced, the
better.  The replacement code is called a stub.

The complexity of this stub will vary.

One of the simplest stub: a switch that the user can manipulate.  The
stub will return the value of an internal variable to the program which
believes to get the real switch state.  This variable must be accessible in
the simulator environment to simulate a person manipulating the switch.

One of the most complicated stub: a motor used in the robot motion.  In this
case, the stub should simulate the electric and mechanical behaviour of the
motor and compute the robot movements resulting from the electric command.

Apart from the microcontroller programs and their replacement code, the
simulated system needs more code to be useful.  This includes test scripts,
user interfaces, environment simulation (other robots, playground, manipulable
elements, etc...).

All those components communicate using *mex*, a message exchange system and
scheduler.

.. [#] The host system, as opposed to the target system, is the system used
   for compilation and simulation.

Details of each component
=========================

Here is a presentation of the components used in the Eurobot 2008 competition.

Asserv
------

This program controls motors used for robot motion or other controlled
actuators.

The ``motor_model`` files contain the code used to simulate a motor, taking
into account electric and mechanical characteristics.  It is an approximated
model anyway, as it models one motor isolated from its environment.  Motors
used for motion will be affected differently if the robot is going forward or
rotating. Other motors may need a variable torque depending of the charge of
the actuator.  Nevertheless, this model is (more than) sufficient to be used
in whole system simulation, or early motor control development.

The ``models`` files defines several robot models which can be simulated with
this code.

The ``simu`` files glue everything together.  It stubs the motors, external
counters, microcontroller timers, micro-switch contacts (depending of the
robot position), it computes robot position, and sends everything as message
to the other components.

As code replacement is done at the lowest level, the simulated system will
really runs the code used to control the motors, as on the real system.

Here are the sent messages formats (see *mex* documentation for more details):

+---------------+-----------+-----------+-----------+
| POS (B: 0xa0) | pos_x (h) | pos_y (h) | pos_a (l) |
+---------------+-----------+-----------+-----------+

The pos_x and pos_y are the coordinates of the robot center, computed by the
simulation code.  This is not connected to position computed by the code which
should run on the real microcontroller.  Unit is millimeter.

The pos_a is the computed robot angle, relative to robot forward direction.
Unit is 1/1024 radian.  Rotation is accumulated over program time.  If the
robot makes ten turns on itself, the angle will be 20 pi radian.

+---------------+--------------+---------------+--------------+
| PWM (B: 0xa1) | pwm_left (h) | pwm_right (h) | pwm_aux0 (h) |
+---------------+--------------+---------------+--------------+

Those are PWM values, in the unit of microcontroller hardware.

+---------------+------------+
| AUX (B: 0xa8) | aux0_a (l) |
+---------------+------------+

The aux0_a is the angle of the first auxiliary motor (the robot arm), which
unit is 1/1024 radian.

Of course, all of this may be slightly modified next year, for example to take
into account an additional motor.

Asserv tools
~~~~~~~~~~~~

In the tools directory, you will find:

step.py:
  to test motor control with a consign step.
inter_asserv.py:
  to manually control asserv using a graphic user interface.
test_goto.py:
  make random goto commands.

All of these can be executed in the simulated environment or on the real
system.  They send commands to the asserv program using the serial line (for
the real robot) or standard input/output (for the simulated one).

IO
--

This program controls actuators and sensors, and contains the artificial
intelligence of the robot.

The ``simu`` files handle simulation of every hardware components: startup
jack, color switch, servo motors, distance sensors, and hardware timers.

Here are the messages formats (see *mex* documentation for more details):

+----------------+--------------+
| JACK (B: 0xb0) | inserted (B) |
+----------------+--------------+

This is sent as request, without the inserted argument.  There must be a
component which responds and sets inserted to 0 for jack not inserted and 1
for jack inserted.

+-----------------+------------+
| COLOR (B: 0xb1) | switch (B) |
+-----------------+------------+

This is sent as request, without the switch argument.  There must be a
component which responds and sets switch to 0 for blue and 1 for red.

+-----------------+------------+------------+-----+
| SERVO (B: 0xb2) | servo0 (B) | servo1 (B) | ... |
+-----------------+------------+------------+-----+

The servoN are the value used to control each servo motor.

+------------------+----------+----------+-----+
| SHARPS (B: 0xb3) | adc0 (H) | adc1 (H) | ... |
+------------------+----------+----------+-----+

This is sent as request without any parameters.  There must be a component
which responds and gives hardware ADC values corresponding to each distance
sensor (Sharps is the brand of our distance sensors).

+----------------+--------+--------+-----+
| PATH (B: 0xb4) | x0 (h) | y0 (h) | ... |
+----------------+--------+--------+-----+

This is sent when the program computes a path to avoid an obstacle.  This is a
list of path coordinates. Unit is millimeter.

As the io program uses requests, it is unable to run without an other program
to respond.

Interface
---------

Today, the user interface and the environment simulation is done in the same
program, this will change.

In the inter directory, you will find:

trans_matrix.py:
  utility to scale, translate and/or rotate vectors.
drawable.py:
  extend TkInter to scale, translate, rotate...
path.py
  draw a path with an arrow.
dist_sensor.py:
  compute distance to an obstacle and draw an arrow to represent this
  distance.
inter.py:
  complete interface to draw the robot, without any control logic.
inter_node.py:
  glue everything together and provide the user interface and the environment
  simulation.

The inter.py can be reused with other programs.  It is used for example in the
inter_asserv.py tool.

The inter_node.py analyses messages from asserv and io, and responds to io
requests.