ros2gams

TOOL AND FEATURE TEMPORARILY UNAVAILABLE

As of 1.3.0 of the GAMS middleware, ROS support is temporarily removed. With the removal of the Any type and capnproto, especially, in order to support Windows and UE4 builds, we have removed direct ROS support. You can still technically bridge GAMS and MADARA by creating new platforms that manipulate ROS directly, but there is no longer a functional rosbridge or ros2gams tool that translates between the standards implicitly. We do plan to readd this feature as soon as we have the time and manpower. It will just no longer use the Any type.

You can access these features in the final version of 1.2.2.

---

ros2gams

ros2gams is a tool which converts rosbag files to madara checkpoints. The tool will create a checkpoint with each ROS message in the rosbag (default). It is also possible to create checkpoints with a given frequency (see option -y). The conversion process is defined in a mapfile which assigns a madara variable name to each rostopic.

---

Commandline arguments

  [-r|--rosbag]                        Path to the rosbag file
  [-rp|--ros-robot-prefix prfx]        Topic prefix of each robot
                                       (default: '/robot_')
  [-scp|--save-checkpoint-prefix prfx] filname prefix to save
                                       for checkpoint
  [-sb|--save-binary]                  save the resulting knowledge 
                                       base as a binary checkpoint
  [-sj|--save-json]                    save the resulting knowledge 
                                       base as a json checkpoint
  [-sk|--save-karl]                    save the resulting knowledge 
                                       base as a karl checkpoint(default)
  [-m|--map-file file]                 File with filter information
  [-y|--frequency hz]                  Checkpoint frequency
                                       (default:checkpoint with each
                                        message in the bagfile)
  [-d|--differential]                  differential checkpoints
                                       only for binary checkpoints
  [-c|--continuous]                    differential checkpoints
                                       continuously stored in the same 
                                       file - only for binary checkpoints
  [-ss|--save-size bytes]              size of buffer needed for file saves
  [-stk|--stream file]                 stream checkpoints to file
  [-de|--delete-existing]              delete existing output files

---

Output format

ros2gams supports three output formats - binary, karl and json. It is possible to convert to a single or multiple formats in one run. Simply add the corresponding commandline arguments (-sb, -sk, -sj). On top of the standard checkpoint formats it is also possible to use checkpoint streaming (-stk). If no output format is specified the file is stored in the karl-format by default.

---

Mapfile

The mapfile defines the conversion process and selects the topics which should be converted. Here is an example mapfile:

frames:
  base_frame: p1/base_link
  world_frame: geo

topics:
  mavros/local/pose:
    name: .sensors.px4.location
    circular_buffer_size: 10

capnp_schemas:
  - $(GAMS_ROOT)/tests/capnfiles/Odometry.capnp.bin
  - $(GAMS_ROOT)/tests/capnfiles/PoseStamped.capnp.bin

schema_map:
  nav_msgs/Odometry: tests/capnfiles/Odometry.capnp:Odometry
  geometry_msgs/Point: tests/capnfiles/Point.capnp:Point
  geometry_msgs/PoseStamped: tests/capnfiles/PoseStamped.capnp:PoseStamped

Agent position and orientation

To calculate the agent's position and orientation it is necessary to define the base_frame and world_frame in the frames namespace.

Topics

The topics namespace defines all ROS topics which will be selected for conversion. The keys of the topics dictionary are the ROS names. Each element needs to have at least a name member which defines the Madara variable name. The value circular_buffer_size is optional and defines if this variable has to be stored in a CircularBuffer and the size of this buffer. The example from above converts the ROS topic mavros/local/pose to the variable .sensors.px4.location. This variable uses a CircularBuffer with a buffersize of 10 elements. The minimal setup for a variable mapping is defined as:

ros_name:
    name: madara_name

Capnproto Schemas

ROS topics can be mapped to capnproto schemas. To provide ros2gams with the schemas the necessary files can be defined in capnschemas. These files are loaded and all the schemas and underlying subschemas are available during the parsing.

Schema Map

The schema map defines which ROS message types are mapped to capnproto schemas and stored in Any types. The example configuration from above results in checkpoints with all Odometry, Point and PoseStamped messages mapped to capnproto schemas. Please keep in mind that all messages with the specified type will be mapped to the capnproto schema defined in this map.

Name Substitutions

To change the name of ros topic type members you are able to specify this in a type-specific mapping. Example:

name_substitution:
  sensor_msgs/LaserScan:
    /angle_min: /a_min
    /angle_max: /a_max
  general:
    /header/stamp: /header/tov

This example would result in the members /angle_min and /angle_max of a sensor_msgs/LaserScan message to be renamed to /a_min and /a_max. On top of that it is also possible to define rules which are applied to all ros types by using the section general.

TOI

If you want to use the ros receive time as toi instead of the current madara time you have to compile with the simtime parameter enabled. This means you have to build by calling: ./scripts/linux/base_build.sh ros gams madara simtime

Known limitations

• Topic types which are non ROS standard types are converted via topic introspection. Due to limitations in this process the size of arrays for these types is limited to 100 elements. This may change in future.
• Only capnproto Any elements can be stored in CircularBuffers
• Name substitution works only for Any types
• Capnproto schemas need to be in the binary format

Plugins

To be able to also handle more complex conversions between ROS messages and madara variables it is possible to develop plugins for ros2gams. An example implementation can be found in https://github.com/jredmondson/gams/tree/master/src/gams/plugins/ros2gams

See https://github.com/jredmondson/gams/blob/1e0a0e96c0726e09416740b87ce7d07b4d30b1ee/gams.mpc#L266 for the buildscript.

The basic principle for that is to define external C functions which are then callable from ros2gams. The function has to have the following signature. The function name is choosable freely.

extern "C" void parse(const rosbag::MessageInstance* m,
  madara::knowledge::KnowledgeBase * kb, 
  std::string container_name)

This allows plugin developers to have complete access to the KnowledgeBase as well as the rosbag MessageInstance. It is allowed to have multiple different functions in one plugin. In the map file the section plugin_map can be used to configure plugins:

plugin_map:
  sensor_msgs/PointCloud2:
    lib: "$(GAMS_ROOT)/lib/libpcl_plugin.so"
    func: "parse"

This configuration would convert sensor_msgs/PointCloud2 by calling the function parse in the external library.