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-sdkalgorithm 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 |
6.3 Related ROS Services
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-sdkalgorithm 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
- The
pathparameters ofsave_mapandload_mapare host local paths; ensure the path is writable / readable. - Empty path returns
error_code=2(kInvalidArgument); device not connected or algorithm session not ready returnserror_code=1(kNotInitialized). save_mapshould be called in SLAM (mode: 3) or ReMap (mode: 5) mode;load_mapshould be called in Relocation (mode: 4) or ReMap (mode: 5) mode.modeoutside the0~5range returnskInvalidArgument.- 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
- Mapping:
- 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) →