CloudSLAM Wrapper Modular Resource

SLAM Algorithms can have varying levels of resource requirements in order to run effectively. Cartographer in particular can require a significant amount of CPU resources to build and manage large maps. In order to better support running SLAM on resource limited machines, Viam provides a service to run SLAM algorithms for machines in the cloud as well as management of the maps generated in their location.

CloudSLAM can be used with both a live machine or with previously captured data in your location. In live mode using the data management service and the cloudslam-wrapper module, Viam takes your LiDAR camera and movement sensor data from your local machine and sends it to the cloudslam server. The CloudSLAM server will then process that data and produce a map that can then be used on any machine in your location. When using an offline machine, you can select data from specific sensors over a period of time to build a map with.

You can view and delete maps built in a location by going to the SLAM library, which provides a summary of active jobs in the location as well as a list of all maps built in that location.

If you have your own SLAM algorithm that we do not currently support or if you built a map on your local machine already and want to skip running CloudSLAM, you can upload a locally built map to your location using the cloudslam-wrapper module.

Supported algorithms

Currently CloudSLAM only supports the cartographer module as a SLAM algorithm.

The SLAM library page

On one of your location pages in the Viam app, change the tab from Machines to SLAM Library. From here, you can find:

1. A list of all maps generated in that location. The list shows the name and version of the map, which machine was used for mapping, and when the map was created. You can also view previous versions of a map, if a map has been updated multiple times.

2. You can create or update a map using a previously collected dataset by clicking the Make new map on the top right and specify a map name or click Update map next to an existing map. See using previously captured data for more information on how to do this.

3. A table showing active and failed CloudSLAM sessions. The table highlights the name of the map, which machine is currently mapping, and whether the map is in progress or has failed. You can also use the table view to stop active mapping sessions.

4. You can view maps in more detail in a dynamic pointcloud viewer by selecting the View Map button on one

5. You can delete maps by clicking on the trash can icon in the upper right-hand corner of a map’s card.

Mapping with a live machine (Online Mode)

To run SLAM in the cloud, configure the cloudslam-wrapper module and data capture on your machine.

Requirements

To use CloudSLAM on a live machine, you must meet the following requirements:

1. A cloudslam supported algorithm must be configured on the machine. Currently only the cartographer module is supported. Please configure a supported algorithm on the machine before continuing.

2. A location owner API key or higher.

Configuration

To use CloudSLAM you must enable data capture and configure your cloudslam-wrapper SLAM service:

• Config Builder
• JSON Example

1. Add the data management service to your machine:

   Navigate to the CONFIGURE tab of your machine’s page in the Viam app. Click the + icon next to your machine part in the left-hand menu and select Service. Choose Data Management as the type and either use the suggested name or specify a name for your data management service, for example data_manager-1. Click Create.

   On the panel that appears, you can manage the capturing and syncing functions. You can also specify the directory, the sync interval, and any tags to apply to captured data. See the data management service for more information.

2. Enable data capture for your camera, and for your movement sensor if you would like to use IMU data, odometry data, or both:

   Find the component’s card on your machine’s CONFIGURE tab. Click Add Method, then select the method type and specify the capture frequency.

   • For the required LiDAR camera, choose the NextPointCloud method. Then set the capture frequency. 5 Hz is a good starting place for most applications.

     

   • To capture data from one or more movement sensors:

• IMU only
• Odometry only
• Both (merged)

For an IMU, choose the AngularVelocity and LinearAcceleration methods and set the capture frequency. 20 Hz is a good starting place for most applications.

For a movement sensor that supports odometry, choose the Position and Orientation methods and set the capture frequency. 20 Hz is a good starting place for most applications.

For a merged movement sensor, choose all four methods (AngularVelocity, LinearAcceleration, Position, and Orientation) and set the capture frequency. 20 Hz is a good starting place for most applications. You do not need to configure data capture on the individual IMU and odometer.

3. Set up the cloudslam-wrapper module on your machine:

   Navigate to the CONFIGURE tab of your machine’s page in the Viam app.

   Click the + icon next to your machine part in the left-hand menu and select Service. Select SLAM, then select cloudslam-wrapper. You can also search for “cloudslam”.

   Click Add module, give your service a name of your choice, then click Create.

   In the resulting SLAM service configuration pane, add the following Attributes:

   {
     "slam_service": "<slam-service-name>",
     "api_key": "<location-api-key>",
     "api_key_id": "<location-api-key-id>",
     "organization_id": "<organization_id>",
     "location_id": "<location_id>",
     "machine_id": "<machine_id>"
   }
   

   where

   • slam_service is the name of the slam service that you want to run with cloudslam.
   • api_key and api_key_id are for the location owner API key described in the requirements.
   • organization_id, location_id, and machine_id describe which location and organization you want to run cloudslam in. These are needed so we can fully tie the map you make to the machine running cloudslam.

4. (Optional) configure the cloudslam-wrapper to use updating mode. If you want cloudslam to update a slam_map rather than create a new map, do the following:

   • configure the slam_map on your wrapped SLAM service
   • add a machine_part_id to your cloudslam-wrapper config.

   This informs the module to use the configured slam_map on your machine.

5. Configure Cartographer to use cloudslam.

   In your cartographer config card, click the {} button to switch to advanced views and set the use_cloud_slam field to true. This setting disables local mapping to limit cpu usage in favor of using cloudslam.

This example JSON configuration:

• adds the viam:rplidar, viam:cartographer, and viam:cloudslam-wrapper modules

• configures the viam:slam:cartographer, viam:cloudslam-wrapper:cloudslam, and the data management services

• adds a viam:lidar:rplidar camera with data capture configured

  {
    "components": [
      {
        "name": "rplidar",
        "namespace": "rdk",
        "type": "camera",
        "model": "viam:lidar:rplidar",
        "attributes": {},
        "service_configs": [
          {
            "type": "data_manager",
            "attributes": {
              "capture_methods": [
                {
                  "method": "NextPointCloud",
                  "capture_frequency_hz": 5,
                  "additional_params": {}
                }
              ]
            }
          }
        ]
      }
    ],
    "services": [
      {
        "name": "carto",
        "namespace": "rdk",
        "type": "slam",
        "model": "viam:slam:cartographer",
        "attributes": {
          "enable_mapping": true,
          "use_cloud_slam": true,
          "existing_map": "",
          "camera": {
            "data_frequency_hz": "5",
            "name": "rplidar"
          }
        }
      },
      {
        "name": "data_manager-1",
        "namespace": "rdk",
        "type": "data_manager",
        "attributes": {
          "capture_dir": "",
          "capture_disabled": false,
          "sync_disabled": false,
          "tags": [],
          "additional_sync_paths": [],
          "sync_interval_mins": 0.1
        }
      },
      {
        "name": "cloudslam",
        "namespace": "rdk",
        "type": "slam",
        "model": "viam:cloudslam-wrapper:cloudslam",
        "attributes": {
          "slam_service": "carto",
          "api_key": "<location-api-key>",
          "api_key_id": "<location-api-key-id>",
          "organization_id": "<organization_id>",
          "location_id": "<location_id>",
          "machine_id": "<machine_id>",
          "machine_part_id": "<machine-part-id>"
        }
      }
    ],
    "modules": [
      {
        "type": "registry",
        "name": "viam_rplidar",
        "module_id": "viam:rplidar",
        "version": "0.1.16"
      },
      {
        "type": "registry",
        "name": "viam_cartographer",
        "module_id": "viam:cartographer",
        "version": "0.3.45"
      },
      {
        "type": "registry",
        "name": "viam_cloudslam-wrapper",
        "module_id": "viam:cloudslam-wrapper",
        "version": "0.0.3"
      }
    ]
  }
  

For more information about the configuration attributes, see Attributes.

Running CloudSLAM

Navigate to the CONTROL tab on your machine’s page. Then check the following things:

• (optional) change the refresh frequency on the cartographer card to Manual Refresh. Since you want to use CloudSLAM, you do not need to refresh the underlying SLAM algorithm’s map.
• the cloudslam-wrapper card should be displaying its default map.

To start the mapping session, do the following:

1. Scroll down to the DoCommand card

2. Select your cloudslam-wrapper service name from the Selected component dropdown

3. In the Input section, enter the following command:

   { "start": "<MAPPING-SESSION-NAME>" }
   

   where <MAPPING-SESSION-NAME> is the name you want to give the map you wish to generate.

4. Click the Execute button.

   If everything is configured correctly, you should receive a success message. The DoCommand card should look something like:

5. After roughly 1 minute, your map should appear on the cloudslam-wrapper card. The displayed map will now update roughly every 5 seconds with the current progress of the mapping session.

You have now successfully built your map using CloudSLAM. Please review the tips for making good maps.

Stopping cloudslam

To stop a CloudSLAM mapping session, do the following:

1. Scroll down to the DoCommand card

2. Select your cloudslam-wrapper service name from the Selected component dropdown

3. In the Input section, enter the following command:

   { "start": "<MAPPING-SESSION-NAME>" }
   

   You do not need to specify the map name or job id here, as the module is already aware of any active mapping sessions for the machine.

4. Click the Execute button. If everything is configured correctly, you will receive a success message. The DoCommand card should look something like:

Once completed, you can view the final map in the cloudslam-wrapper card, or view the map in the SLAM library.

Using previously captured data (Offline mode)

You can specify a range of previously captured LiDAR and optional IMU data to create a map or update an existing map in the cloud. You can browse your previously captured data from the Data page under the Point clouds tab (for LiDAR data) and Sensors tab (for IMU data).

Requirements

To create a map, you must have already captured LiDAR data in the location in which you would like to create the map.

The following example shows the previously-captured LiDAR data under the Point clouds tab for a machine named test. Selecting a row opens a pane to the right that contains more information, such as the Machine ID of the machine the component belongs to:

Example of previously captured IMU data:

Create or update a map

Navigate to the SLAM library tab on your location page, and click Make new map on the top right and specify a map name or click Update map next to an existing map.

1. Enter the Machine name, Camera name, and optionally the Movement Sensor name of the components whose previously captured data you want to use to create or update a map. If your machine has been deleted, you can alternatively specify the machine ID.
2. Select the timeframe of the data you’d like to use.
3. At the bottom, you can see the total number of PCD files and movement sensor data points that will be processed.
4. Click Generate map.

End a session with previously captured data

Unlike in Online mode, you cannot see the map being created while the slam session is in progress, but similar to when creating or updating a map in Online mode, you can see that your cloud slam session is in progress from your Location page’s SLAM library tab. When all the data has been processed (or 45 minutes have passed, whichever occurs first), the map will be saved to your Location page’s SLAM library tab.

Upload a locally built map

If you want to skip using CloudSLAM and build the map on your local machine, the cloudslam-wrapper module also allows you to upload a locally built map to your Location. This lets you share locally built maps across machines in a location easily.

This feature can also be used with SLAM algorithms that CloudSLAM does not currently support. As long as the algorithm implements the SLAM API, you can upload your maps.

Requirements

• A SLAM algorithm must be configured on the machine. This algorithm does not need to be supported by cloudslam to work.

• A location owner API Key or higher. See Add an API key to learn how to create a key!

Configuration

Add the cloudslam-wrapper module to your machine. You do not need data management configured on the machine. Configuring the module will not affect any currently running local SLAM maps. Add the following Attributes:

{
  "slam_service": "<slam-service-name>",
  "api_key": "<location-api-key>",
  "api_key_id": "<location-api-key-id>",
  "organization_id": "<organization_id>",
  "location_id": "<location_id>",
  "machine_id": "<machine_id>",
  "machine_part_id": "<machine_part_id>"
}

Upload the map

Navigate to the CONTROL tab on your machine’s page.

1. Scroll down to the DoCommand card

2. Select your cloudslam-wrapper service name from the Selected component dropdown

3. In the Input section, enter the following command:

   { "save-local-map": "<MAP-NAME>" }
   

   where <MAP-NAME> is the name you want to give the map you wish to generate. 4. Click the Execute button. If everything is configured correctly, you should receive a success message. The DoCommand card should look something like:

   

   Once completed, you can view the final map in the SLAM library.

Attributes

The following attributes are available for viam:cloudslam-wrapper:cloudslam