summaryrefslogtreecommitdiff
path: root/host
diff options
context:
space:
mode:
authorNicolas Schodet2008-11-16 23:55:42 +0100
committerNicolas Schodet2008-11-16 23:55:42 +0100
commit4adc64bffc08fd1aff3370dfb4893f2f1a38dc8e (patch)
tree04517707753f358091104d56f94b51ebd7c1d19f /host
parent680e50567564b1a57038e6bf476fdf8016f83fe7 (diff)
* host/doc:
- added simulator documentation.
Diffstat (limited to 'host')
-rw-r--r--host/doc/simulator.txt214
1 files changed, 214 insertions, 0 deletions
diff --git a/host/doc/simulator.txt b/host/doc/simulator.txt
new file mode 100644
index 00000000..f5aa674d
--- /dev/null
+++ b/host/doc/simulator.txt
@@ -0,0 +1,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.