Start-up Instructions

Docker Installation

We provide a Dockerfile to build an image to easily run Swarm-SLAM on your device. Look here for the files and documentation: https://github.com/lajoiepy/cslam_experiments/tree/main/docker

Quick instructions:

git clone https://github.com/lajoiepy/cslam_experiments.git
cd cslam_experiments/docker
make build
make gpu_run
make swarmslam-lidar

We offer other run options and take inspiration from our makefile to introduce new ones.

Installation steps (from scratch)

• Install ROS 2
• Install Swarm-SLAM packages:

  sudo apt install python3-vcstool
  cd $YOUR_ROS2_REPO
  mkdir src
  vcs import src < cslam.repos

• Install python packages

  sudo apt install python3-pip
  pip install -r requirements.txt # The requirements file is in the main Swarm-SLAM repo.You don't need torch if you are only using lidar.

• Install gtsam: https://github.com/borglab/gtsam . We tested version 4.1.1:

  git checkout 4.1.1

• If you are using lidar, install teaser++ with python bindings: https://teaser.readthedocs.io/en/latest/installation.html#installing-python-bindings
• Install ROS 2 dependencies:

  sudo apt install python3-rosdep python3-colcon-common-extensions
  source /opt/ros/$ROS_DISTRO/setup.bash
  sudo rosdep init
  rosdep update
  rosdep install --from-paths src -y --ignore-src --rosdistro $ROS_DISTRO

Build and tests

• Build the repo:

  source /opt/ros/$ROS_DISTRO/setup.bash
  colcon build

• Run tests:

  colcon test

• For images, download CosPlace model ResNet-18 dimension 64 : https://github.com/gmberton/CosPlace . Other models can be used by modifying frontend.cosplace.descriptor_dim and frontend.cosplace.backbone params accordingly. Place the model file in src/cslam/models/ Set frontend.nn_checkpoint accordingly
• For deployment on real robots, I strongly advise to use the Zenoh DDS Bridge with ROS_DOMAIN_ID to avoid flooding the network with discovery messages. For example, on :

  ROS_DOMAIN_ID=$ROBOT_ID ros2 launch cslam_experiments experiment_realsense.launch.py robot_id:=$ROBOT_ID
  zenoh-bridge-dds -d $ROBOT_ID --allow /cslam/.*

Running your experiments

• To adapt Swarm-SLAM to your specific system: take inspirations from the various launch and config files in cslam_experiments.
• Many datasets are only available in ROS 1. To convert them to ROS 2, I suggest to run the bag in ROS 1, along with the ros1_bridge (https://github.com/ros2/ros1_bridge), while recording the bag in ROS 2. In separate terminals run:

  rosbag play bag.bag
  ros2 run ros1_bridge dynamic_bridge --bridge-all-1to2-topics
  ros2 bag record -a

Development

Debugging instructions for ROS 2 nodes

Troubleshoot

If the instructions do not work, please look at our Docker Setup or the automated build setup.

Important details

• Robot IDs should not be greater then the max_nb_robots parameter.
• Technically you can set the robot IDs as you wish, but it might require slight code modifications to fix the topics. The current system expects robot IDs to start from 0 (e.g. robot 0, robot 1, robot 2, etc.)
• The odometry and sensor data (images, pointclouds) topics given as inputs must be synchronized, otherwise we can't associate which odometry message correspond to which sensor data frame.

Known issues

• Sometimes, disabling logs causes failures (see https://github.com/MISTLab/Swarm-SLAM/issues/38), I had trouble reproducing the bug, but if you experience something similar, try enabling the logs which should introduce an insignificant overhead.