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

Please contact after-sales technical support to enable this module

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
/integrated_command	std_msgs/String	Publish mapping control commands

Command format:

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

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

Relocalization

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.

Topic Name	Data Type	Direction	Description
/integrated_command	std_msgs/String	Publish	Publish relocalization control command
/relocalization_pose	geometry_msgs/Pose	Publish	Provide the robot’s initial pose estimate
/slam/lidar_odom	nav_msgs/Odometry	Subscribe	Lidar localization result (BEST_EFFORT QoS)

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.

Programming Examples

For detailed programming examples and code descriptions, see:

• Python example (mapping): Slam

• Python example (relocalization): Relocate

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

• C++ example (mapping): Slam

• C++ example (relocalization): Relocate

• 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)