5.5.2 SLAM (Optional)

The SLAM (Simultaneous Localization and Mapping) module provides interfaces for map building, map retrieval, and relocalization, enabling the robot to create maps in unknown environments and accurately localize itself using existing maps.

Important

This is an optional component. To use the interfaces described on this page, please contact after-sales technical support.

Map Building

Use topics to control the start and stop of the mapping process and specify the name under which the map is saved.

Topic Name	Data Type	Description	QoS	Frequency
/integrated_command	std_msgs/String	Publish mapping control commands	RELIABLE+TRANSIENT_LOCAL	User (on-demand)

Command format:

Command	Description
start_mapping	Start mapping
stop_mapping:<map_name>	Stop mapping and save the map as <map_name>

Note: After sending the stop_mapping command, map saving takes some time. The save may time out (default 120 seconds) if the system encounters an anomaly (e.g. SLAM module unresponsive, slow disk I/O). Use the GetStoredMapByName service to verify whether the map was saved successfully.

Map Retrieval

Service Name	Data Type	Description
/aimdk_5Fmsgs/srv/GetStoredMapByName	GetStoredMapByName	Retrieve stored map data by map name

• GetStoredMapByName ros2-srv @ mm/srv/GetStoredMapByName.srv

  # Retrieve stored map data by map name
  # Service name: /aimdk_5Fmsgs/srv/GetStoredMapByName
  
  # Request
  std_msgs/Header header   # Request header
  string map_name          # Map name
  
  ---
  
  # Response
  uint64 code              # Return code, 0 indicates success
  std_msgs/Header header   # Response header
  nav_msgs/MapMetaData map_info  # Map info (resolution, width, height, etc.)
  uint64 map_version       # Map version number
  string map_path          # Path to the map PNG file
  int8[] data              # Map grid data (-1/0/100)
  NaviPoint[] navi_points  # Navigation point topology
  QRPoint[] qr_points      # QR code point topology
  HRPoint[] hr_points      # High-resolution point topology
  Path[] paths             # Path topology
  Region[] regions         # Region topology (includes virtual walls)
  uint64 map_id            # Map ID
  

  • std_msgs/Header

  • nav_msgs/MapMetaData

  • NaviPoint ros2-msg @ mm/msg/NaviPoint.msg

    int32 point_id                   # Point ID
    geometry_msgs/Pose2D navi_point  # Navigation point 2D pose
    

    • geometry_msgs/Pose2D

  • QRPoint ros2-msg @ mm/msg/QRPoint.msg

    int32 point_id  # Point ID
    QRCode qr_code  # QR code info
    

    • QRCode ros2-msg @ common/QRCode.msg

      int32 code               # QR code value
      geometry_msgs/Pose pose  # QR code pose
      

      • geometry_msgs/Pose

  • HRPoint ros2-msg @ mm/msg/HRPoint.msg

    int32 point_id           # Point ID
    geometry_msgs/Pose pose  # Real-time pose of the high-resolution point
    QRCode[] qr_list         # Associated QR code point list
    bool use_head            # Whether to use the head camera
    

    • geometry_msgs/Pose

  • Path ros2-msg @ mm/msg/Path.msg

    int32 path_id                    # Path ID
    geometry_msgs/Pose2D[] points    # List of 2D path point poses
    

    • geometry_msgs/Pose2D

  • Region ros2-msg @ mm/msg/Region.msg

    uint8 type          # Region type (0: undefined, 1: working space, 2: virtual wall)
    uint8 drawing_type  # Drawing type (0: undefined, 1: closed region, 2: polyline)
    string name                        # Region name
    geometry_msgs/Polygon polygon      # Ordered polygon vertices (first and last do not repeat)
    

    • geometry_msgs/Polygon

When to Relocalize

To localize the robot to a specified position within an existing map, first trigger the relocalization command, then provide an initial pose estimate, and finally confirm success by subscribing to the localization result topic.

When to Relocalize

Relocalization is required in the following scenarios to obtain the robot’s initial pose in the map:

• First use of navigation after robot startup

• Switching to a new map

• Localization lost (e.g. after the robot is moved)

Note: Without relocalization, the localization module will not start and /slam/lidar_odom will not publish data.

Topic Name	Data Type	Description	QoS	Frequency
/integrated_command	std_msgs/String	Publish relocalization control command	RELIABLE+TRANSIENT_LOCAL	User (on-demand)
/relocalization_pose	geometry_msgs/Pose	Provide the robot’s initial pose estimate	BEST_EFFORT+VOLATILE	User (on-demand)
/slam/lidar_odom	nav_msgs/Odometry	Subscribe to laser localization results (frame_id is map, child_frame_id is torso_link, representing the robot’s pose in the global map)	RELIABLE+TRANSIENT_LOCAL	10Hz

Relocalization command format:

Command	Description
start_relocalization:<map_id>	Start relocalization; <map_id> is the target map ID (check it in the mobile app, or read the map_id field from the map table in map.db)

Operation procedure:

1. Publish start_relocalization:<map_id> to /integrated_command

2. After about 1 second delay, publish the robot’s initial pose estimate to /relocalization_pose (recommended: start from the map’s origin point)

3. Subscribe to /slam/lidar_odom; receiving data indicates relocalization succeeded

Note: The coordinates used in /relocalization_pose are pixel coordinates, which can be obtained from the map information file. The map information file path is: /agibot/data/var/MapManagerModule/<map_id>/grid_map_info.txt

The file contains three lines:

• Line 1: Resolution (1m corresponds to 20 pixels)

• Line 2: Map origin coordinates (pixel coordinates of the mapping origin), i.e. the initial pose available for relocalization

• Line 3: Image width and height (pixel)

Obtaining Map Identifiers and Coordinates

Parameters commonly needed when calling the map-retrieval, relocalization, and navigation interfaces can be obtained as follows:

• map_id (required for relocalization and navigation) and map_name (used by GetStoredMapByName to fetch a map by name): check them in the mobile app, or query the map database on the robot and read the corresponding map_id / map_name field from the result:

  sqlite3 /agibot/data/var/MapManagerModule/map.db "SELECT * FROM map;"
  

• Coordinates:

  • The relocalization initial pose (/relocalization_pose) uses pixel coordinates: take the map-building origin origin on line 2 of grid_map_info.txt (see the Relocalization section above), where origin.u maps to position.x and origin.v to position.y.

  • The navigation target (target_pose) uses metric Map world coordinates, which differ from pixel coordinates; for the pixel-to-metric conversion, see Coordinate Conversion in the navigation interface.

Programming Examples

For detailed programming examples and code descriptions, see:

• Python example (mapping): Map Building

• Python example (relocalization): Relocalization Using a Map

• Python example (map retrieval): Retrieve a Stored Map

• C++ example (mapping): Map Building

• C++ example (relocalization): Relocalization Using a Map

• C++ example (map retrieval): Retrieve a Stored Map

Caution

As standard ROS DO NOT handle cross-host service (request-response) well, please refer to SDK examples to use open interfaces in a robust way (with protection mechanisms e.g. exception safety and retransmission)

While the robot is in Stable Standing Mode or Locomotion Mode, DO NOT launch ROS nodes in rapid bulk (no more than 2 nodes per second is recommended), as a large number of nodes joining DDS discovery within a short period causes communication congestion and degrades motion control real-time performance, which may cause the robot to lose balance and fall