6. Mapping and Relocalization API Workflow

6.1 Document Description

This document introduces the ROS Service calling methods and typical workflows for Odin1 Lite mapping (SLAM) and relocalization functions.

Relocalization is provided jointly by the ROS Driver matching the firmware version and the manifold-lc-sdk algorithm deb package. When only the ROS Driver is deployed, sensor data can be obtained, but mapping and relocalization algorithms cannot run; see 9. Relocalization User Guide for how to install the algorithm deb package.

6.2 Concept Description

Term Description
Device Odin1 Lite module
Host PC / robot connected to Odin1 Lite and running the ROS driver
Device Mode Device operating mode, switched via the device_mode service
Normal (1) Normal odometry mode; device outputs odom / point cloud etc.
SLAM (3) Mapping mode; algorithm builds loop-closure map while running
Relocation (4) Relocalization mode; loads a saved map for position relocalization
ReMap (5) Relocalization + incremental mapping mode; extends the map on the loaded map
Map file Binary map file (.bin) generated by the algorithm in SLAM / ReMap mode

All service prefixes are /{topic_prefix}/device{N}/ (default /manifold/device0/).

ℹ️ The device model no longer appears in topic/service paths; the model and SN are published in the JSON of /{topic_prefix}/driver/device_online.

Service Type Description
device_mode DeviceMode Switch operating mode: 0=Standby / 1=Normal / 2=Upgrade / 3=SLAM / 4=Relocation / 5=ReMap
save_map SaveMap Save current loop-closure map to the specified path
load_map LoadMap Load a saved map file for relocalization or ReMap
exploy_map ExployMap Export current loop-closure map to a host file (specific format determined by plugin)

Service Definitions

DeviceMode.srv

uint8 mode   # 0=Standby 1=Normal 2=Upgrade 3=SLAM 4=Relocation 5=ReMap
---
bool   success
int32  error_code   # 0=OK, others are SDK OdinResult enumerations
string message

SaveMap.srv

string path   # Output map file path (host local path)
---
bool   success
int32  error_code
string message

LoadMap.srv

string path   # Input map file path (host local path)
---
bool   success
int32  error_code
string message

6.4 Typical Workflows

6.4.1 Mapping Workflow

Step 1: Start the driver

# ROS2
ros2 launch odin_ros_driver_rev1 odin1Lite.launch.py

# ROS1
roslaunch odin_ros_driver_rev1 odin1Lite.launch

Step 2: Switch to SLAM mode (start mapping)

Before execution, enter the ROS workspace and source the environment:

cd ~/catkin_ws
source install/setup.bash   # ROS2
# source devel/setup.bash   # ROS1
# ROS2
ros2 service call /manifold/device0/device_mode \
  odin_ros_driver_rev1/srv/DeviceMode "{mode: 3}"

# ROS1
rosservice call /manifold/device0/device_mode "{mode: 3}"

At this point the device enters SLAM mapping mode; you can move the device to start mapping.

Step 3: Save the map

After mapping is complete, call save_map to save the map to a host local file:

# ROS2
ros2 service call /manifold/device0/save_map \
  odin_ros_driver_rev1/srv/SaveMap "{path: '/tmp/odin_map.bin'}"

# ROS1
rosservice call /manifold/device0/save_map "path: '/tmp/odin_map.bin'"

Saving the map does not stop mapping; you can continue running and save again.

Step 4: Stop mapping (optional)

Switch back to Normal mode:

# ROS2
ros2 service call /manifold/device0/device_mode \
  odin_ros_driver_rev1/srv/DeviceMode "{mode: 1}"

# ROS1
rosservice call /manifold/device0/device_mode "{mode: 1}"

6.4.2 Relocalization Workflow

Prerequisite: A map file has been saved through the above mapping workflow.

Step 1: Switch to Relocation mode

Before execution, enter the ROS workspace and source the environment:

cd ~/catkin_ws
source install/setup.bash   # ROS2
# source devel/setup.bash   # ROS1
# ROS2
ros2 service call /manifold/device0/device_mode \
  odin_ros_driver_rev1/srv/DeviceMode "{mode: 4}"

# ROS1
rosservice call /manifold/device0/device_mode "{mode: 4}"

Step 2: Load the map

# ROS2
ros2 service call /manifold/device0/load_map \
  odin_ros_driver_rev1/srv/LoadMap "{path: '/tmp/odin_map.bin'}"

# ROS1
rosservice call /manifold/device0/load_map "path: '/tmp/odin_map.bin'"

After the map is loaded successfully, the device starts running the relocalization algorithm. Please confirm the relocalization result according to the application-side localization status and pose output.

Step 3: Stop relocalization

# ROS2
ros2 service call /manifold/device0/device_mode \
  odin_ros_driver_rev1/srv/DeviceMode "{mode: 1}"

# ROS1
rosservice call /manifold/device0/device_mode "{mode: 1}"

6.4.3 ReMap Workflow (Incremental Mapping)

ReMap (mode: 5) relocalizes on a saved map while extending the map. It is suitable for scenarios where new areas need to be appended to an existing map.

Step 1: Switch to ReMap mode and load the existing map

# ROS2
ros2 service call /manifold/device0/device_mode \
  odin_ros_driver_rev1/srv/DeviceMode "{mode: 5}"

ros2 service call /manifold/device0/load_map \
  odin_ros_driver_rev1/srv/LoadMap "{path: '/tmp/odin_map.bin'}"

In RViz, set Fixed Frame to device0/map to view the loaded map.

Step 2: Move the device to collect new areas

The algorithm will localize on the old map and incrementally build new map content.

Step 3: Save the extended map

ros2 service call /manifold/device0/save_map \
  odin_ros_driver_rev1/srv/SaveMap "{path: '/tmp/odin_map_extended.bin'}"

The incrementally saved map is usually larger than the original map.

Step 4: Stop ReMap

ros2 service call /manifold/device0/device_mode \
  odin_ros_driver_rev1/srv/DeviceMode "{mode: 1}"

6.4.4 Loop-closure Visualization Topics

In SLAM / Relocation / ReMap mode, the algorithm publishes the following loop-closure visualization topics:

Topic suffix Type Description
loop_closure/optimization_busy std_msgs/Bool Whether the optimizer is running
loop_closure/optimization_status_marker visualization_msgs/Marker Text marker showing IDLE / OPTIMIZATION
loop_closure/optimized_path nav_msgs/Path Optimized trajectory in the local_map frame
loop_closure/optimized_cloud sensor_msgs/PointCloud2 Optimized global point cloud in the local_map frame
loop_closure/map_cloud sensor_msgs/PointCloud2 Loaded map point cloud in the map frame

These topics are produced by the manifold-lc-sdk algorithm package; they appear only when the algorithm deb package is installed and the device is in SLAM / Relocation / ReMap mode.

6.5 Workflow Diagram Summary

┌─────────────────────────────────────────────────────────┐
│                 Start ROS Driver                        │
└───────────────────────┬─────────────────────────────────┘
                        │
      ┌─────────────────┼─────────────────┐
      ▼                 ▼                 ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ SLAM        │  │ Reloc       │  │ ReMap       │
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │
       ▼                ▼                ▼
  device_mode      device_mode      device_mode
    mode: 3           mode: 4          mode: 5
       │                │                │
       ▼                ▼                ▼
  Move to map      load_map         load_map
       │           existing map     existing map
       ▼                │                │
  save_map save         ▼                ▼
       │           Confirm by      Move to extend map
       ▼           application
  device_mode           │                │
    mode: 1             ▼                ▼
 (Back to Normal)  device_mode      save_map save
                    mode: 1       device_mode mode: 1
                 (Back to Normal) (Back to Normal)
└─────────────────────────────────────────────────────────┘

6.6 Notes

  1. The path parameters of save_map and load_map are host local paths; ensure the path is writable / readable.
  2. Empty path returns error_code=2 (kInvalidArgument); device not connected or algorithm session not ready returns error_code=1 (kNotInitialized).
  3. save_map should be called in SLAM (mode: 3) or ReMap (mode: 5) mode; load_map should be called in Relocation (mode: 4) or ReMap (mode: 5) mode.
  4. mode outside the 0~5 range returns kInvalidArgument.
  5. Typical workflows:
    • Mapping: device_mode mode: 3 → save_map → device_mode mode: 1
    • Relocalization: device_mode mode: 4 → load_map → device_mode mode: 1
    • ReMap: device_mode mode: 5 → load_map → save_map → device_mode mode: 1
  6. After a service call succeeds, the driver’s expected mode is updated for state recovery after device reconnection.

← Previous Chapter:Data Output | Next Chapter:Odin1 Lite Quick Start (Ubuntu) →


中文 | EN
This site uses Just the Docs, a documentation theme for Jekyll.