Using a Controller with Flat4

Overview

In Flat4, the robot controller(s) run in external processes and send commands to the Flat Simulator via a TCP socket. This document describes the commands that should be sent to the simulator, and the input received from the simulator.

Each simulation step, Flat sends information to the controller, and waits for input from the controller. In standard simulation mode, no matter how much actual time the controller takes to compute a response, the same amount of simulated time (usually 100ms) occurs between each output/input step. In real time mode the simulator will wait for input from the controller, but will use wall clock time to determine how much time has passed during the last simulation step.

Connecting to the Simulator

When the Flat Simulator starts, it reads a configuration file which specifies what TCP port the controller should use to contact it. The Flat Simulator will echo this port number to the console when it starts. The controller, acting as a client, should open a connection to the specified port.

Upon succesfully connecting to Flat, several windows will appear on the screen. The Flat control panel contains a START button. Upon pressing this button, the simulator will immediately begin to send data to the controller. Subsequently, the user can press STOP to temporarily stop the simulation. Press START again to restart the simulation.

The STEP mode is useful for debugging. First, press STOP to stop the simulation. Then, each time STEP is pressed, the simulator will advance one time interval (usually 100ms). Press START again to resume the simulation.

Input to the Flat Simulator

The controller, which may consist of one or more control laws, controls the simulated robot through two parameters, linear velocity and angular velocity. The parameters are embedded in a text string that is sent to the simulator. via the TCP stream.

The simulator parses the input using the C function sscanf with the format "%c %lf %lf %lf %s". The parameters are explained below.
Table 1. Input to the Flat Simulator
Variable Units Description
command - Normally, send c to continue processing.
Send e to end the Flat program (not recommended).
linear velocity mm/second Send the desired linear velocity. The robot will accelerate or decelerate until it reaches the desired velocity. The linear acceleration is constant in Flat: +/- 500 mm/sec2.
angular velocity deg/second Send the desired angular velocity. The robot will accelerate or decelerate until it reaches the desired angular velocity. The angular acceleration is constant in Flat: +/- 50 deg/sec2.
applicability [0.0..1.0] The applicability of the control law. Currently ignored.
message - A message to be displayed in a Flat window.
Note: the constants for acceleration are set in the file "flat.c", in the function init_simulator().

Additional queries to Flat

Normally the controller client sends control commands as shown above. However, the client may also request information from Flat as shown by the commands below.

Table 2. Additional commands to the Flat Simulator
Command Argument Types Description
b min-inter-blob-distance max-intra-blob-distance max-blob-distance min-blob-size max-blob-size char double double double double double Returns a list of blobs found in laser data.
A blob is a cluster of points separate from other points. The definition can be adjusted using the parameters. All blobs returned are closer than max-blob-distance. min-blob-size and max-blob-size are numbers of points. Other values are in mm.
Returns: (time :BLOB (x y r numPoints) (x y r numPoints) ...)
d min-theta max-theta min-jump-size char double double double Get doorways in the laser data.
(time :DOORWAYS door1 door2 ...) for doorways that match the given parameters. Each doorway has the form (theta jump-size).
j min-jump-size char double Returns all jumps in the data of the given minimum size.
Return form is (time :JUMPS jump1 jump2 ...)
Each jump has the form (jump-size (angle1 value1) (angle2 value2)).
l char Returns the robot-centric laser readings.
Returns (time (:LEFT reading1 reading2 ...) (:RIGHT reading1 reading2 ...)
Each reading has the form: (x y r theta).
m map-file new-x new-y new-theta char string double double double Tells Flat to use a new environment file. Flat will notify the Flat Display.
Returns (time :MAP-CHANGED new-map-file).
o min-theta max-theta min-distance min-width char double double double int Returns (time :OPEN-SPACE 1|0) depending on whether open space exists.
t command char string Causes a map transition as defined in a Flat World file.
Returns (time :MAP-CHANGED map-file) or
(time :MAP-CHANGED :NO-TRANSITION-MATCH).
See the Flat World definition.
s min-theta max-theta max-distance discontinuity-threshold
squid-window-size squid-window-std-dev collinear-range-threshold collinear-theta-threshold
collinear-contig-threshold min-segment-length use-filter filter-window-size		 char double double double double
int double double double
double double int int		 Return the line segments in the laser data: (time seg1 seg2 ...).
Each segment is in the form ((x1 y1) (x2 y2)). The coordinates of the segments are in Yet Another Coordinate system. This one is a "standard" coordinate system with the y-axis pointing straight ahead from the robot and the x-axis extending to the right of the robot.
x char Return default sensor data.

Output from the Flat Simulator

Every simulation step, the simulator sends the controller a set of data consisting of sensor readings and other information as described below. The data are contained in a LISP-like list as follows: 
   ( ([n1 n2 ... n12])       -- sonar readings, in mm
     (X Y theta)             -- robot location/orientation in mm and degrees
     simulation-time         -- milliseconds
     ( [laser-data] )        -- laser readings, see below
     )
The Flat configuration file specifies whether the simulated robot uses sonars, and whether the simulated robot uses 0, 1 or 2 laser rangefinders.

Sonar data

If the sonars are not used, the list of sonar readings is empty (but the surrounding parentheses are still there). If the readings are present, there are 12 values, which represent distances measured in millimeters (mm). The first sonar faces directly forward on the robot, and successive readings are taken in a clockwise direction.

Laser data

If the lasers are not used, the list of laser data is empty. Otherwise, it consists of 1 or 2 sets of laser data. The laser readings are distances relative to the laser.

Each set of laser data has the following format: 

  (laser-name laser-angle n1 n2 ... n180)
The number of readings is always 180 (one per degree over a 180 degree scan). The position and angle of each laser can be adjusted using parameters in the Flat configuration file.

Laser-name is TOP if only one laser is in use. Otherwise, two data sets are sent, with one labeled LEFT and one labeled RIGHT. The lasers are always symmetrically located on the robot. The locations are set using parameters read from the Flat configuration file. Normally, laser-angle is -45 on the LEFT laser and 45 on the RIGHT laser.

A Simple Controller

Here is an example of starting Flat with a dummy controller that simply reads input from the simulator and sends back no commands. 

  % # Start the display
  % java -classpath /u/robot/flat-root/flat5 flat.Flat 1085

  % # Start the simulator
  % /u/robot/flat-root/flat4/flat /u/robot/flat-root/flat5/env/taylor-level-4.env -config $HOME/.flat
  % # waits on port 1095

  % # Start the controller
  % /u/robot/flat-root/flat4/flat_client -port 1095
If the three programs are succesfully communicating, you will be able to move the robot by clicking the left button on the Flat environment display. You can click the right button at a location to rotate the robot to face that location.

[FLAT home]

Author: Micheal S. Hewett
Email: hewett@cs.utexas.edu
Last Updated: Tuesday, November 9, 1999