slam_toolbox

slam_toolbox – definition

slam_toolbox is an open-source ROS 2 package for 2D simultaneous localization and mapping (SLAM). It estimates a mobile robot’s pose while building, updating, and storing a 2D occupancy-grid map from planar laser scan data. In ROS 2 navigation systems, it commonly provides the map -> odom transform, publishes nav_msgs/msg/OccupancyGrid map data, and maintains a pose graph that can be optimized after loop closures.

The package is intended for robots operating with a 2D LiDAR in environments that can be represented adequately in two dimensions. This makes it suitable for wheeled UGV platforms such as Leo Rover and Raph Rover when they are equipped with a laser scanner, wheel odometry, and a correctly configured TF tree. It is not a complete autonomy stack. Path planning, obstacle avoidance, recovery behaviours, and goal execution are normally handled by Nav2.

Source: ROS 2 package documentation for slam_toolbox; Navigation2 documentation.

How slam_toolbox works in ROS 2

slam_toolbox subscribes primarily to a planar laser scan stream. It uses TF2 to determine the relationship between the laser, robot base, and odometry frames, then matches scans against nearby scans or the current map. The resulting constraints form a pose graph. When the robot revisits an observed area, scan matching can create a loop-closure constraint. Graph optimization then reduces accumulated pose error and updates the generated map.

For a differential-drive or skid-steer UGV, the expected transform chain follows ROS coordinate-frame conventions defined by REP 105. The robot state estimator or wheel-odometry source publishes odom -> base_link. slam_toolbox estimates map -> odom. Static transforms define sensor placement, for example base_link -> laser.

map
 └── odom
      └── base_link
           └── laser

REP 105 distinguishes the locally continuous odom frame from the globally corrected map frame. The map -> odom transform may change after loop closure, while odom -> base_link should remain locally continuous.

Source: ROS REP 105 – Coordinate Frames for Mobile Platforms; tf2_ros documentation.

Operating modes and ROS 2 interfaces

slam_toolbox provides different execution modes for different timing and mapping requirements. Synchronous operation queues and processes every valid scan. Asynchronous operation processes the most recent scan once the previous update has finished and may skip scans, which can be useful when scan processing time varies. Localization mode loads an existing serialized pose graph and localizes the robot against it rather than building a new pose graph.

The package is commonly configured around the following ROS 2 interfaces and data types:

sensor_msgs/msg/LaserScan – input from a 2D LiDAR, usually on /scan.
nav_msgs/msg/Odometry – may be published by a wheel-odometry or state-estimation node, but slam_toolbox normally obtains the robot motion estimate through the odom -> base_frame TF transform rather than subscribing directly to an odometry topic.
nav_msgs/msg/OccupancyGrid – generated map, commonly published on /map.
geometry_msgs/msg/PoseWithCovarianceStamped – initial-pose input, commonly published through /initialpose.
tf2_msgs/msg/TFMessage – transport used for dynamic transforms on /tf.

Map persistence is a practical distinction between slam_toolbox and simpler scan-to-map pipelines. It can serialize pose-graph state in addition to saving a raster occupancy map. A serialized graph preserves scan and constraint information needed for later pose-graph operations. A PNG/PGM map image with YAML metadata does not preserve that graph.

Configuration example for a UGV

The example below shows selected parameters for a Leo Rover or Raph Rover equipped with a 2D LiDAR. Values such as map resolution, scan range limits, and update intervals must be derived from the LiDAR specification, expected environment scale, processor capacity, and required navigation accuracy. They are configuration choices, not universal hardware limits.

slam_toolbox:
  ros__parameters:
    use_sim_time: false
    mode: mapping
    scan_topic: /scan
    base_frame: base_link
    odom_frame: odom
    map_frame: map
    resolution: 0.05
    max_laser_range: 12.0
    minimum_travel_distance: 0.10
    minimum_travel_heading: 0.10
    map_update_interval: 2.0
    transform_publish_period: 0.05
    use_scan_matching: true
    do_loop_closing: true

A resolution of 0.05 represents 5 cm per occupancy-grid cell. It does not guarantee 5 cm localization accuracy. Actual pose accuracy depends on scan geometry, wheel slip, LiDAR timing, TF timestamp consistency, odometry quality, and the presence of loop closures.

ros2 launch slam_toolbox online_async_launch.py \
  slam_params_file:=/home/robot/slam_params.yaml

Source: slam_toolbox ROS 2 API documentation; sensor_msgs/LaserScan message definition; nav_msgs/OccupancyGrid message definition.

Sensor integration on Leo Rover and Raph Rover

Leo Rover can run ROS 2 distributions supported by its installed operating system and compute hardware. Its four-wheel skid-steer chassis can provide wheel-derived motion estimates, but wheel odometry alone drifts when tyres slip, traverse uneven surfaces, or move over loose material. slam_toolbox reduces long-term drift when the LiDAR observes stable geometric features and loop closures are available.

A practical Leo Rover mapping configuration requires a rigidly mounted 2D LiDAR, a measured static transform between the LiDAR and base_link, and mutually consistent scan and TF timestamps. An IMU can improve the odometry estimate when fused with wheel odometry in an estimator such as robot_localization, but slam_toolbox itself remains a 2D laser-SLAM system. A depth camera may support obstacle perception or 3D reconstruction, yet it does not replace the required planar LaserScan input unless another node converts suitable depth data into a scan.

Raph Rover may be appropriate when a larger sensor payload, additional compute hardware, or longer field-operation time is required. The same frame conventions apply. Regardless of platform size or payload capability, LiDAR mounting, wheel geometry, odometry scaling, and the navigation footprint must be calibrated.

Limitations and validation

slam_toolbox is best suited to indoor corridors, laboratories, warehouses, construction interiors, and structured outdoor areas with persistent LiDAR features. It can be unreliable in long featureless passages, heavy rain or dust, dense vegetation, reflective glass, or environments that change substantially between mapping and localization runs. GPS or RTK can provide global georeferencing, but it is not a direct substitute for local laser-SLAM constraints.

Before deploying Nav2, validate the following items on the target UGV:

TF timestamps are current and the frame tree contains no duplicate publishers.
The LiDAR scan plane is stable and does not intersect the chassis or payload.
Wheel odometry direction, wheel separation, and velocity scaling are correct.
The occupancy map aligns with measured walls and known landmarks after loop closure.
The Nav2 robot footprint and inflation settings reflect the actual Leo Rover or Raph Rover geometry.