SLAM Service

Introduction

Simultaneous Localization And Mapping (SLAM) allows your robot to create a map of its surroundings and find its location within that map. SLAM is an important area of ongoing research in robotics, particularly for mobile applications such as drones, boats, and rovers.

The Viam SLAM Service supports the integration of SLAM as a service on your robot. The following SLAM libraries are integrated:

• Cartographer
• ORB-SLAM3

Requirements

Install the binaries required to utilize these libraries on your machine by running the following commands:

Cartographer:

sudo curl -o /usr/local/bin/carto_grpc_server http://packages.viam.com/apps/slam-servers/carto_grpc_server-stable-aarch64.AppImage
sudo chmod a+rx /usr/local/bin/carto_grpc_server

sudo curl -o /usr/local/bin/carto_grpc_server http://packages.viam.com/apps/slam-servers/carto_grpc_server-stable-x86_64.AppImage
sudo chmod a+rx /usr/local/bin/carto_grpc_server

brew tap viamrobotics/brews && brew install carto-grpc-server

ORB-SLAM3:

sudo curl -o /usr/local/bin/orb_grpc_server http://packages.viam.com/apps/slam-servers/orb_grpc_server-stable-aarch64.AppImage
sudo chmod a+rx /usr/local/bin/orb_grpc_server

sudo curl -o /usr/local/bin/orb_grpc_server http://packages.viam.com/apps/slam-servers/orb_grpc_server-stable-x86_64.AppImage
sudo chmod a+rx /usr/local/bin/orb_grpc_server

Configuration

You can configure your robot to use SLAM on the Viam app. Navigate to the CONFIG tab on your robot’s page, and from there, navigate to the SERVICES subtab.

Add a service with type slam, whatever name you want, and the model of the library you want to use.

Use this JSON template to configure the service with the ORB-SLAM3 library, and this JSON template to configure the service with the Cartographer library. Then, adjust general attributes and library-specific config-params.

General Attributes

config_params

The config_params attribute is populated with parameters that are unique to the SLAM library being used.

You can use these parameters to fine-tune the algorithms these libraries utilize in aspects like submap size, mapping update rate, and feature matching details.

To see library-specific config_params available, navigate to these sections:

• Integrated Library: ORB-SLAM3
• Integrated Library: Cartographer

data_dir: Data Directory

A running SLAM Service saves the sensor data it uses and the maps and config files it produces locally on the device in the directory path specified by the General Attribute data_dir.

To recap, the directory must be structured as follows:

.
└──\(The Directory Defined in Config as `data_dir`)
    ├── data
    ├── map
    └── config

• data contains all the sensor data collected from the sensors listed in sensors, saved at data_rate_msec.
• map contains the generated maps, saved at map_rate_sec.
• config contains all SLAM library specific config files.

Mapping Modes

These modes dictate SLAM’s mapping behavior at runtime, but are not configured as a part of the SLAM service’s JSON configuration. The mode utilized by the SLAM service is determined by the information found in the data directory at runtime.

Integrated Library: Cartographer

Cartographer performs dense SLAM using LIDAR data.

Specify whether this LIDAR data is preloaded or collected live by a Rplidar device with the attribute use_live_data.

Example Configuration

Live Mode

To run Cartographer in live mode, follow these instructions to add your Rplidar device as a modular component of your robot, and refer to this example configuration:

{
  "modules": [
    {
      "name": "rplidar_module",
      "executable_path": "/home/<YOUR_USERNAME>/rplidar-module-local-aarch64.AppImage"
    }
  ],
  "components": [
    {
      "namespace": "rdk",
      "type": "camera",
      "depends_on": [],
      "model": "viam:lidar:rplidar",
      "name": "rplidar"
    }
  ],
  "services": [
    {
      "type": "slam",
      "attributes": {
        "config_params": {
          "min_range": "0.3",
          "max_range": "12",
          "mode": "2d"
        },
        "data_rate_msec": 200,
        "delete_processed_data": false,
        "use_live_data": true,
        "sensors": [
          "rplidar"
        ],
        "port": "localhost:8083",
        "data_dir": "/home/<YOUR_USERNAME>/<CARTOGRAPHER_DIR>",
        "map_rate_sec": 60
      },
        "model": "cartographer",
        "name": "run-slam"
    }
  ]
}

{
  "components": [
    {
      "namespace": "rdk",
      "type": "camera",
      "depends_on": [],
      "model": "viam:lidar:rplidar",
      "attributes": {
        "device_path": "/dev/tty.SLAB_USBtoUART"
      },
      "name": "rplidar"
    }
  ],
  "services": [
    {
      "attributes": {
        "map_rate_sec": 60,
        "data_rate_msec": 200,
        "use_live_data": true,
        "sensors": [
          "rplidar"
        ],
        "config_params": {
          "mode": "2d",
          "min_range": "0.3",
          "max_range": "12"
        },
        "port": "localhost:8083",
        "data_dir": "/Users/<YOUR_USERNAME>/<CARTOGRAPHER_DIR>",
        "delete_processed_data": false
      },
      "model": "cartographer",
      "name": "run-slam",
      "type": "slam"
    }
  ],
  "modules": [
    {
      "executable_path": "/Users/<YOUR_USERNAME>/rplidar/bin/rplidar-module",
      "name": "rplidar_module"
    }
  ]
}

Offline Mode

Refer to this example configuration for running Cartographer SLAM in offline mode:

    {
      "services": [
        {
          "attributes": {
            "config_params": {
              "min_range": "0.3",
              "max_range": "12",
              "mode": "2d"
            },
            "data_dir": "/home/<YOUR_USERNAME>/<CARTOGRAPHER_DIR>/data",
            "map_rate_sec": 60,
            "data_rate_msec": 200,
            "delete_processed_data": false,
            "use_live_data": false,
            "sensors": []
          },
          "model": "cartographer",
          "name": "run-slam-offline",
          "type": "slam"
        }
      ]
    }

For more information about running Cartographer in Offline Mode, see this tutorial.

Cartographer config_params

Integrated Library: ORB-SLAM3

ORB-SLAM3 can perform sparse SLAM using monocular or RGB-D images.

Example Configuration

Live Mode

An example configuration for running ORB-SLAM3 in live mode, with rgbd image data, with two camera streams available (color for RGB images and depth for depth data):

"services": [
  {
    "name": "testorb",
    "model": "orbslamv3",
    "type": "slam",
    "attributes": {
      "data_dir": "/home/<YOUR_USERNAME>/<ORBSLAM_DIR>",
      "sensors": ["color", "depth"],
      "use_live_data": true,
      "map_rate_sec": 60,
      "data_rate_msec": 200,
      "config_params": {
        "mode": "rgbd"
      }
    }
  }
]

Offline Mode

An example configuration for running ORB-SLAM3 in offline mode:

"services": [
  {
    "name": "testorb",
    "model": "orbslamv3",
    "type": "slam",
    "attributes": {
      "data_dir": "/home/<YOUR_USERNAME>/<ORBSLAM_DIR>",
      "sensors": [],
      "use_live_data": false,
      "map_rate_sec": 120,
      "data_rate_msec": 100,
      "config_params": {
        "mode": "mono"
      }
    }
  }
]

ORB-SLAM3 config_params