Configuring CARMEN Parameters

Mailing Lists
Data Sets


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:

2.2  Robot

Parameter Options are:

2.3  Localize

Parameter Options are:

2.4  Navigator

Parameter Options are:

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

will specify a max_t_vel of 0.1 m/s for the robot process only.

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>]

and delimited at the end by the start of another section, or by the end-of-file. The section name should either be * (for all robots) or be the name of a robot to be specified on the command line when starting the parameter server.

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

base_type         scout
scout_dev         /dev/ttyS0
robot_width       0.39
robot_rectangular 0

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:

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.

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

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

location bytes 9 - ?? : position data

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

Greg Armstrong.....Site Map..... Last modified: Wed Jun 11 10:04:41 EDT 2003