Configuring CARMEN Parameters

Contents

• Introduction
• Parameter Descriptions
  • Robot-Type
  • Robot
  • Localize
  • Navigator
• The Parameter Server
• Changing Parameters from the Command Line
• Changing Parameters on the Fly
• The ini File Format
• The Map File Format
  • Filenames
  • Overall File Format
  • Chunk Descriptions
    • Creator Chunk Description
    • Gridmap Chunk Description
    • Offlimits Chunk Description
    • Places Chunk Description
    • Expected Chunk Description
    • Laserscans Chunk Description
• The Map Editor program (separate webpage)

1  Introduction

The many programs of CARMEN work together to accomplish the tasks of navigating a robot from place place, mapping new environments, and others. Because much of the information required by one program to perform its task is required by another program to perform a different task. If the information is different between programs, it is possible for one program to prevent another from accomplishing its task, which brings about a situation which is potentially dangerous to the robot, it's environment, and even the people in it.

CARMEN programs use the param_server, a repository or registry of values for parameters to be used during the operation of a robot. The intention of the parameter server is to ensure that all modules are using the same parameters definitions, such as maximum allowable velocity, robot size, etc. Many robot code suites require that each separate process reads the parameter values directly from a file. We have chosen the parameter server approach because different processes frequently reside on different computer, which would entail having copies of the same file on each such computer. This often leads to having copies of different files on each computer, with undesirable results. Secondly, the parameter server facilitates dynamic updating of parameter values; for instance, the maximum speed of the robot can be changed during the operation of the robot, without restarting any processes. This necessitates some additional overhead on the part of each process, to ensure that each process is subscribed to changes in each variable. This document will describe how best to do this.

The parameter server is intended to serve parameters that can vary across robots, or across execution runs. Parameters that cannot change should not be served by the parameter server. For example, the maximum preferred translational velocity for a particular deployment is served as robot_max_t_vel. However, each robot (such as the scout) has a practical maximum wheel velocity; this value should be hard-coded in the base module for that robot, instead of being served. Similarly, for rflex robots, the odometry conversion factor from wheel tics to metres is hard-coded, as this is a hardware dependent value and cannot change.

Finally, the parameter server can also be used as a map server. This ensures that all processes are using the same map, with the same resolution, etc.. The does entail a performance penalty in terms of bandwidth loss at the start up of each process, but we believe that resultant the ease of use, in terms of needing only one copy of the map and ensuring consistency, is an acceptable bargain.

2  Parameter Descriptions

This is not necessarily a complete list of all of the parameters used in CARMEN.

2.1  Robot-type Parameters used in the pioneer, rflex, scout, and other programs based on the type of robot used.

Parameter Options:

• dev sets the serial port used by the computer to communicate with the robot hardware.
• version sets the type of Pioneer in the Pioneer program. This should be the integer 1 or 2.
• wheel_diameter is the wheel diameter, used to calculate distance a robot moves.
• use_sonar sets sonar to be on or off. Carmen has not fully integrated sonar at this time, so this should be set to zero for off.
• sensor_angle The angle subtended by one sonar transducer, in radians. This is not used if use_sonar is off.
• sonar_offsets sets the position of each sonar relative to the center of the robot, and its facing relative to forward. Each sonar has three numbers associated: distance forward of center in meters, distance right of center in meters, and facing in radians measuring clockwise from forward. This is not used of use_sonar is off.
• num_sonars sets the number of sonar detectors on the robot. This is not used of use_sonar is off.

2.2  Robot

Parameter Options are:

• max_t_vel sets the maximum translational (forward-backward) speed of the robot in meters per second. If this is set higher than the maximum allowable speed the base can support, then the behaviour is undefined.
• max_r_vel sets the maximum rotational (spinning) speed in radians per second. If this is set higher than the maximum allowable speed the base can support, or, if the base is differential drive and this is set higher than the translation speed can support, then the behaviour is undefined.
• min_approach_dist sets the closest the robot should get to a stationary object toward which it is moving. Current speed and programmed accelerations are taken into account, so the actual distance between the robot and object should be the same if the robot is moving fast or slow. The value is in meters.
• min_side_dist sets the closest the robot will approach a stationary object as it passes the object. The value is in meters.
• length is the front-to-back measure of the robot in meters.
• width is the side-to-side measure of the robot in meters. Even is the robot is round, this parameter should be set.
• acceleration and deceleration sets how fast the robot should accelerate and decelerate, in m/s^2. If the base does not support different acceleration and deceleration parameters (e.g., nomadic technologies bases), then base_services tries to mimic this support by changing the acceleration value to the deceleration value once the robot is moving and no commands are pending.
• reaction_time is how long it takes for the base to react to a command, in seconds. If you want to know how quickly the robot can stop, you have to know how far it will travel while it is reacting to the command.
• curvature is how much the robot will veer to the right or left as it is travelling in a straight line. Nominally used by the conventional planner, but mostly ignored.
• theta_gain is used to control the p-term of the bearing part of a pd control loop that can be used to drive the robot to an arbitrary point at range d and bearing theta. The correct value of this term is related to the dynamic characteristics of particular bases, and can be altered if the robot is oscillating widely, or not turning fast enough, etc. Determing the correct value is usually done experimentally.
• theta_d_gain controls the d-term of bearing part of the control loop. Again, determined experimentally for each base.
• displacement_gain controls the p-term of the range part of the control loop. Determined experimentally for each base. There is no parameters for the d-term of the range part -- the current value is set to 0.5. A displacement_d_gain parameter should probably be added.
• allow_rear_motion sets whether or not to allow the robot to back up.
• converge determines whether or not robot should start publishing robot_laser/robot_sonar messages immediately, or wait until enough messages have been received that the timestamp offset between the odometry and the laser_laser/base_sonar messages can be reliably estimated, for good timestamp-based interpolation of the laser odometry.
• use_laser sets whether or not to use a laser device (Sick LMS or PLS). This affects robot only, in terms of whether it will subscribe to laser_laser messages, and then publish robot_laser messages.
• timeout sets the maximum time the robot program will continue moving the physical robot without receiving a command. This value is in seconds.

2.3  Localize

Parameter Options are:

• frontlaser_offset is the distance in meters forward of robot center the front laser scans.
• rearlaser_offset is the distance in meters behind robot center the rear laser scans.
• robot_particles is number of particles to be used for localization. More particles results in more robust localization, but more computation
• max_range is maximum range to incorporate laser readings.
• min_wall_prob Laser range values are either incorporated into every particle in the particle filter, or they are thrown out as outliers. If a laser reading receives a probability of less than min_wall_prob in at least outlier_fraction percent of the particles, the reading is called an outlier and disregarded by all particles.
• outlier_fraction see min_wall_prob.
• update_distance If the robot does not move, successively resampling the particle filter would result in only the single most-likely particle surviving. In order to insure that the observations incorporated into the filter are reasonably independent, resampling is only done if the robot translates by an amount update_distance, or rotates by an amount update_angle.
• update_angle see update_distance.
• laser_skip The localizer will only process every nth laser reading. This is to increase the likelihood of independent readings and to decrease the computational requirement of the localizer.
• use_rear_laser sets whether data from the rear laser should be incorporated. The lasers must be relatively well aligned. Use at your own risk.

  The following four parameters describe the robot's motion model. Start with non-zero a1 and a3, and add some a2 and a4 if you have trouble localizing.

• odom_a1 controls the contribution of rotational motion to rotational error.
• odom_a2 controls the contribution of translational motion to rotational error.
• odom_a3 controls the contribution of translational motion to translational error.
• odom_a4 controls the contribution of rotational motion to translational error.
• occupied_prob probability of a map cell to be considered occupied.
• lmap_std standard deviation of map likelihood function. This can be thought of as the "fuzziness" of the map. The higher the value, the more tolerant the localizer will be to map errors, and the higher the pose variance will be.
• global_lmap_std This is the same as lmap_std, but for when the robot is in global localization mode. In general, this should be higher than lmap_std.
• global_evidence_weight During global localization, evidence is counted less heavily than normal. This weight specifies what the fraction of a normal reading that a global localization reading should be considered as.
• global_distance_threshold The localizer uses the global localization parameters if there is a large spread of particles. If any particle is farther than global_distance_threshold from the mean, than global localization is used.

  The following parameters control integrated localization and people tracking. They are somewhat difficult to use. Email mmde+carmen@cs.cmu.edu if you need help tuning them.

• people_tracking turns people tracking on or off.
• person_particles
• max_people_range
• max_people_std
• person_average_width This parameter is not in any standard units.
• person_average_prob
• person_distance_std
• person_distance_std

2.4  Navigator

Parameter Options are:

• max_t_vel sets maximum translational (forward or backward) velocity in meters per second.
• max_r_vel sets maximum rotational (turning) velocity in radians per second
• min_approach_dist sets how close to subgoals the robot much reach before proceding to the next subgoal or how close to the final goal before deciding it has been reached.
• min_side_dist sets the minimum distance the robot side will approach a stationary object.
• length is the length of the robot in meters.
• width is the width of the robot in meters.
• acceleration sets the accelleration rate of the robot in meters per second squared.
• reaction_time is how long it takes for the base to react to a command, in seconds. If you want to know how quickly the robot can stop, you have to know how far it will travel while it is reacting to the command.
• curvature sets how much the robot will curve while moving forward during turns in radians per meter.
• planner chooses one of two path planners available in Carmen.
• ant chooses to use an ANT server.
• port specifies a port for an ANT server.
• num_lasers specifies how many lasers are being used.
• update_map If this is on, laser data is integrated into the map (based on the current estimate of the position provided by localize and odometry), and the planner replans in the new map.
• max_laser_range If update_map is on, then laser_data is integrated into the map only up to max_laser_range, in metres. Changes to the map further than max_laser_range are ignored. If update_map is off, this parameter has no effect.
• max_collision_range specifies the distance an obstical should be before replanning a path to avoid it.
• replan_frequency specifies how often the planner will replan the robot path based on its current position
• smooth_path If this parameter is off, then the conventional planner generates plans that consist of sequences of adjacent grid cells that the robot should travel through. If this smooth_path is on, then the sequences of grid cells are smoothed into sequences of waypoints joined by straight lines. This parameter should almost always be on for the conventional planner.
• goal_theta_tolerance controls how close the navigator will get the robot to a desired orientation. Suggested starting value is 0.08 (about 5 degrees).

3  The Parameter Server

Usage: param_server -robot <robot name> [map file] [ini file]

The parameter server reads parameter definitions from the ini file, or, if no ini file name is provided on the command line, then attempts to load parameters from ./carmen.ini, ../carmen.ini, and finally ../src/carmen.ini. If no parameter file can be found, then the process exits with an error.

To make life easier, multiple robot definitions can be contained in a single ini file. Therefore, the parameter server requires a robot name to select a set of parameters, using the required argument -robot <robot name>. At start up, the parameter server loads all the parameter definitions listed under the generic [*] parameter set, and also all the parameters listed under the matching robot name.

The parameter server can also serve maps, subsuming the functionality of the map server.

Finally, the parameter server also performs sanity checks, to make sure that all running CARMEN processes are the same version, to ensure consistency among message formats, etc. All programs are expected to call carmen_param_check_version() immediately after initializing the IPC connection.

4  Specifying Parameters from the Command Line

Parameter values can be temporarily over-ridden from the command line of a given process, for that process only. For example:

% robot -max_t_vel 0.1

This parameter specification method is not advised, is a convenience only, and may be removed from future versions of carmen. Command-line parameters are assumed to have no module name, and attempts are made to find a parameter with any module name and matching parameter name. If a process uses multiple parameters with different module names and the same parameter name, the behaviour of command-line specification is undefined.

5  Change Parameters on the Fly

Using param_edit, you can change parameters served by param_server as you operate your robot, or within the simulator. You can save the new parameters to a file with the Save option of the File menu. Before opening param_edit, you must be running central and param_server. When you open the module, you will get a new window that looks like this:

To change an On/Off parameter, simply click the button and param_server will immediately note the change. To change a text ot numerical parameter, click on the appropriate section on the left, then click on the white box of the parameter to change. Once you change the text, you must hit [enter] on your keyboard for the change to register in param_server.

Note that some parameters are related to others. For instance, if a rear laser is added to the robot simulator as decribed above, the use_rear_laser button on the "simulator" set would be switched to "on," and rear_laser_dev on the "laser" set would have to be entered. To see the input from the laser on the robot_graph display, then the rear_laser button on the "robotgraph" set needs to be set to "on."

6  The ini File Format

The ini file format is ASCII, intended to be human readable and editable using emacs. Given the somewhat hierarchical nature of the file, a markup language such as XML may have been preferable, but this seems like overkill for a fairly simple IO task.

The file consists of robot definition sections, delimited at the start by

[<section name>]

Each section consists of parameter definitions, given by:

<module name>_<parameter name> <value>

The module name can contain any characters except white space and the underscore (`_') character. The parameter name can contain any characters except whitespace. The parameter value can contain any characters at all, but the value ends with the end of line. There is no mechanism for writing parameter values across multiple lines. Trailing whitespace is trimmed from parameter values.

Comment lines must have `#' at the first character of each line.

Parameter values can be no longer than 2048 characters, and the concatenation of module names and parameter names can also be no longer than 255 characters. There is a limit of 128 unique module names.

If a variable is specified twice, then only the last value is retained.

6.1  A Very Short Example ini File

[*]
navigator_update_map on

[scout]
base_type         scout
scout_dev         /dev/ttyS0
robot_width       0.39
robot_rectangular 0

[pioneer]
base_type         pioneer
pioneer_dev       /dev/ttyS0
pioneer_vesion    1
robot_rectangular 1
robot_width       0.48
robot_length      0.54

7  The Map File Format

A program for editing and creating maps is available with the CARMEN software.

Map files in CARMEN store evidence grid representations of 2-D worlds as well as other information related to robot navigation and localization. The format of these data files is a tagged file format, similar in spirit to the TIFF standard for image files. This is the official description of the CARMEN map file format.

7.1  Filenames:

All CARMEN map files must end with the extension ".map". Map files may be compressed using gzip, but they must end with the extension ".map.gz".

7.2  Overall file format:

The map file may start with a arbitrary number of lines beginning with a # (hash). These lines are comments and are disregarded by programs that read the maps. They should be used to make basic information about the map human-readable.

The first line of the file that does not start with a # (hash) signifies the beginning of the binary map data. This data consists of an arbitrary number of tagged "chunks".

A given CARMEN program may not know how to interpret every type of chunk in a map file. Programs should simply skip over any chunks that have types they cannot recognize. This will minimize problems with compatibility of different programs and maps.

7.3  Chunk Description:

Byte 1 : Chunk type - unsigned byte

This byte describes the type of the next chunk. Here are the currently recognized chunk types:

0 - file creation information
1 - evidence grid map
2 - off limits area description
3 - named positions
4 - expected distances
5 - laser scans

Byte 2-5 : Chunk size - unsigned int

This is the number of bytes of the chunk, not including the chunk type and the chunk size variables.

Byte 6-15: ASCII chunk description - 10 ASCII chars

This is an ASCII description of the chunk type. It was added to make the files easier to debug in an editor.

The following ASCII descriptions correspond with the standard chunk types.

0 - "CREATOR "
1 - "GRIDMAP "
2 - "OFFLIMITS "
3 - "PLACES "
4 - "EXPECTED "
5 - "LASERSCANS"

Bytes 16 - ??: (length specified by chunk size above)

This is the binary data that makes up the individual chunk.

The format of the binary data for each chunk type will be described in turn.

7.3.1  Creator Chunk Description:

Bytes 1 - 10 : userid - ASCII chars

This is the userid of the account which created the map file.

Bytes 11 - 18 : creation date - long int

This is time / date of creation stored as a number of seconds. This is easy to change into a real date using UNIX functions.

Bytes 19 - 98 : map description - 80 ASCII chars

General description of the map.

7.3.2  Gridmap Chunk Description:

Bytes 1 - 4 : map columns - 1 unsigned byte

Number of columns in the map

Bytes 5 - 8 : map rows - 1 unsigned bytes

Number of rows in the map

Bytes 9 - 12 : map resolution - 1 float

Number of meters per grid cell. The resolution must be the same in x and y.

Bytes 13 - ?? : map data - rows * columns floats

The values of all evidence grid cells. The cells vary between 0 for empty to 1 for occupied, and -1 for unknown. The data is in row order. (i.e. the first row values followed by the second row values, etc)

7.3.3  Offlimits Chunk Description:

The off-limits areas can be either off-limits points, or off-limits rectangles. The points are specified first, then the rectangles.

Bytes 1 - 4 : number of off-limits points N - unsigned int
Bytes 5 - ?? : off-limits points - N * 4 * 2 unsigned ints
x1 y1 x2 y2 .... Each x and y are unsigned int representing the off-limits cell coordinates.

4 more bytes : number of off-limits rectangles M - unsigned int
Bytes ?? - ?? : off-limits rectangles - M * 4 * 4 unsigned ints
r1x1 r1y1 r1x2 r1y2 r2x1 r2y1 r2x2 r2y2 ... Each x and y are unsigned ints representing the coordinates of the off-limits rectangle.

7.3.4  Places Chunk Description:

Bytes 1 - 4: number of named points in the map - unsigned int

Bytes 5 - ?? : description of each location

location bytes 1 - 4 : position type - unsigned int

Type 0 - named position (x and y)
Type 1 - named pose (x, y, and theta)
Type 2 - localization initialization position (x, y, theta, uncertainties)

location bytes 5 - 8 : number of bytes for the position - unsigned int

Type 0 - 8 bytes
Type 1 - 12 bytes
Type 2 - 24 bytes

location bytes 9 - ?? : position data

Type 0 - 8 bytes - float x, float y
Type 1 - 12 bytes - float x, float y, float theta
Type 2 - 24 bytes - float x, float y, float theta, float xstd, float ystd, float zstd

7.3.5  Expected Chunk Description:

This has not yet been implemented and will be filled in later.

7.3.6  Laserscans Chunk Desription:

Bytes 1 - 4 : Number of laser scans in the chunk - unsigned int

Laser scan

Bytes 1 - 4 : x position of laser - float
Bytes 5 - 8 : y position of laser - float
Bytes 9 - 12 : theta position of laser - float
Bytes 13 - 16 : number of laser readings
Bytes 17 - ?? : laser readings - N floats
Laser readings are all in m.