5.5.3 Navigation (Optional)

The navigation module provides path planning and autonomous navigation interfaces, supporting robots to perform point-to-point navigation tasks within known maps, and also supports task control operations such as pause, resume, and stop.

Important

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

Navigation Task Topic

Topic Name	Data Type	Description	QoS	Frequency
/aima/te/pnc_task_request	PncTaskRequest	Publish a navigation task request (start/pause/resume/stop)	BEST_EFFORT+VOLATILE	User (on-demand)
/aima/pnc/pnc_task_response	PncTaskResponse	Navigation Task Execution Result Feedback	BEST_EFFORT+TRANSIENT_LOCAL	Event-driven (on task state change)
/task_master/state	TaskMasterState	Task engine status (main state, sub state, SLAM state, tour/pilot task state)	BEST_EFFORT+TRANSIENT_LOCAL	1Hz

Prerequisites

Before using navigation, ensure the following conditions are met:

1. Relocalization completed: The robot has been localized in the map (triggered via the start_relocalization:<map_id> command, see SLAM)

2. Working map set: The map_id in the navigation request must match the map ID used for relocalization (the relocalization process automatically loads the target map and establishes localization; if a different map_id is specified during navigation, PNC will load that map’s data but the localization frame remains on the relocalization map, causing navigation errors). map_id must be a valid, already-built map ID.

3. Motion control mode is stable stand (STAND_DEFAULT) or locomotion (LOCOMOTION_DEFAULT): The robot must be in a mode that can accept locomotion velocity commands, otherwise navigation tasks will be blocked. Stable stand and locomotion mode are unified; the velocity commands sent by navigation drive automatic internal switching between the two (see Motion Mode Switching).

• PncTaskRequest ros2-msg @ task_engine/msg/PncTaskRequest.msg

  # Navigation task request
  # Topic name: /aima/te/pnc_task_request
  
  MessageHeader header
  
  uint8 task_type                             # Task type, see enum definition TASK_TYPE
  uint8 task_request                          # Task request, see enum definition TASK_REQUEST
  uint8 pnc_mode                              # PNC mode (0: Enable obstacle avoidance, 1: Disable obstacle avoidance)
  uint64 task_id                              # Task ID; must match the one used when starting the task when pausing/resuming/stopping
  uint64 map_id                               # Map ID
  geometry_msgs/PoseStamped target_pose       # Target pose
  geometry_msgs/Pose2D[] reference_line       # Reference line (only considers x, y); target_pose holds the target orientation (yaw)
  float64 target_pose_radius                  # Target range radius (unit: m); minimum effective value is 0.25
  float32 max_forward_speed                   # Maximum forward speed (unit: m/s, default 0.8)
  
  geometry_msgs/Pose2D[] trajectory_pos       # (reserved) group-control parameter
  geometry_msgs/Twist[] trajectory_vel        # (reserved) group-control parameter
  uint64 play_timestamp                       # (reserved) group-control parameter
  uint64 time_duration                        # (reserved) group-control parameter
  
  # 64-byte reserved field
  char[64] reserve_info
  

  Available values for task_type (defined by the TASK_TYPE enumeration):

  Enumeration Name	Value	Description
  TASK_TYPE_PLANNING_NAVI_TO_POSE_2D	2	Plan and navigate to a 2D pose

  Other enum values are for internal use only.

  Available values for task_request (defined by the TASK_REQUEST enumeration):

  Enumeration Name	Value	Description
  TASK_REQUEST_NONE	0	No request
  TASK_REQUEST_START	1	Start navigation task
  TASK_REQUEST_STOP	2	Stop navigation, clear task status
  TASK_REQUEST_PAUSE	3	Pause navigation, robot stops in place, status retained
  TASK_REQUEST_RESUME	4	Resume the paused navigation task
  TASK_REQUEST_STATUS_INQUIRY	5	Query current task status

Interface Specification

Start Navigation

Set the target pose, map ID, obstacle-avoidance mode, and speed to initiate a navigation task.

PncTaskRequest.task_type = TASK_TYPE_PLANNING_NAVI_TO_POSE_2D
PncTaskRequest.task_request = TASK_REQUEST_START
PncTaskRequest.task_id = xxx          // Task ID (millisecond timestamp)
PncTaskRequest.map_id = xxxx          // Actual map ID in use
PncTaskRequest.pnc_mode = 0           // 0: Enable obstacle avoidance, 1: Disable
PncTaskRequest.max_forward_speed = 0.5 // Maximum forward speed (m/s)
PncTaskRequest.target_pose = ...      // Target pose
PncTaskRequest.target_pose_radius = 0.5 // Reach accuracy (m)

Pause Navigation

Pause the current navigation task. The robot stops in place and the task state is preserved.

PncTaskRequest.task_type = TASK_TYPE_PLANNING_NAVI_TO_POSE_2D
PncTaskRequest.task_request = TASK_REQUEST_PAUSE
PncTaskRequest.task_id = xxx          // Same task ID used when starting navigation

Resume Navigation

Resume the paused navigation task; the robot continues toward the previous navigation goal.

PncTaskRequest.task_type = TASK_TYPE_PLANNING_NAVI_TO_POSE_2D
PncTaskRequest.task_request = TASK_REQUEST_RESUME
PncTaskRequest.task_id = xxx          // Same task ID used when starting navigation

Stop Navigation

Stop the current navigation task and clear the task state.

PncTaskRequest.task_type = TASK_TYPE_PLANNING_NAVI_TO_POSE_2D
PncTaskRequest.task_request = TASK_REQUEST_STOP
PncTaskRequest.task_id = xxx          // Same task ID used when starting navigation

Reminder: map_id is a required field (see Obtaining Map Identifiers and Coordinates for how to obtain it); task_id must match the one used at the start when pausing/resuming/stopping.

Get Navigation Task Execution Result

Subscribe to the /aima/pnc/pnc_task_response topic to get the navigation task execution result. This topic is published only once when the task state changes (e.g. RUNNING/FAILED/FINISHED/PAUSED).

• PncTaskResponse ros2-msg @ task_engine/msg/PncTaskResponse.msg

  # Navigation task execution result
  # Topic: /aima/pnc/pnc_task_response
  
  MessageHeader header
  
  uint8 task_type                             # Task type, see TASK_TYPE enum
  uint64 task_id                              # Task ID (same as in request)
  uint64 map_id                               # Map ID
  uint8 task_status                           # Task status, see TASK_STATUS enum
  
  # 64 byte reserved
  char[64] reserve_info
  

  Available values for task_status (defined by the TASK_STATUS enumeration):

  Enumeration Name	Value	Description
  TASK_STATUS_UNKONW	0	Unknown status
  TASK_STATUS_RUNNING	1	Task running
  TASK_STATUS_FAILED	2	Task failed
  TASK_STATUS_PAUSED	3	Task paused
  TASK_STATUS_FINISHED	4	Task completed
  TASK_STATUS_RECOVERY_TIMEOUT	22	Recovery timeout
  Other statuses	10-31	See PncTaskResponse.msg definition

Warning

Navigation tasks may be automatically interrupted

When the robot detects a serious system fault (e.g. fall, system fault), the navigation task may be automatically interrupted. The robot plays a TTS prompt: “Sorry, a system fault has been detected and autonomous navigation tasks cannot be performed. Please check the fault cause in the client app.”

To programmatically detect whether a navigation task has been interrupted, use the following methods:

• Subscribe to the /aima/pnc/pnc_task_response topic and observe whether task_status changes to FAILED

• Subscribe to the /task_master/state topic and observe whether main_state changes from PILOT to IDLE

Get Task Engine Status

Subscribe to the /task_master/state topic to get the overall task engine status. This topic is periodically published and continuously updates the task engine state machine.

• TaskMasterState ros2-msg @ task_engine/msg/TaskMasterState.msg

  # Task engine status
  # Topic: /task_master/state
  
  uint8 main_state                          # Main state, see TM_MAIN_STATE enum
  uint8 sub_state                           # Sub state, see TM_SUB_STATE enum
  uint8 slam_state                          # SLAM state, see SLAM_STATE enum
  uint64 loc_map_id                         # Current localization map ID (valid only when slam_state=LOCALIZATION)
  string loc_map_name                       # Current localization map name (valid only when slam_state=LOCALIZATION)
  
  FixLineIntroState fix_line_intro_state    # Tour task status (valid only when main_state=FIX_LINE_INTRO)
  PilotState pilot_state                    # Pilot task status (valid only when main_state=PILOT)
  
  # Reserved information
  string reserve_info
  

  Available values for main_state (defined by the TM_MAIN_STATE enumeration):

  Enumeration Name	Value	Description
  TM_MAIN_STATE_IDLE	0	Idle
  TM_MAIN_STATE_RELOCALIZATION	1	Relocalizing
  TM_MAIN_STATE_MAPPING	2	Mapping
  TM_MAIN_STATE_FIX_LINE_INTRO	3	Tour task running
  TM_MAIN_STATE_RECORDING_PATH	4	Recording path
  TM_MAIN_STATE_PILOT	5	Pilot task running

  Available values for sub_state (defined by the TM_SUB_STATE enumeration):

  Enumeration Name	Value	Description
  TM_SUB_STATE_NONE	0	No sub state
  TM_SUB_STATE_RESUME	1	Long-running task active
  TM_SUB_STATE_PAUSE	2	Long-running task paused

  Available values for slam_state (defined by the SLAM_STATE enumeration):

  Enumeration Name	Value	Description
  SLAM_STATE_IDLE	0	SLAM idle
  SLAM_STATE_RELOCALIZATION	1	SLAM relocalizing
  SLAM_STATE_MAPPING	2	SLAM mapping
  SLAM_STATE_LOCALIZATION	3	SLAM localizing

  • FixLineIntroState ros2-msg @ task_engine/msg/FixLineIntroState.msg

    # Tour task status
    uint8 fix_line_intro_state              # Tour task status, see TM_FIX_LINE_INTRO_STATE enum
    uint64 set_task_id                      # User-preset task ID (0 if not set)
    string set_task_name                    # User-preset task alias (empty if not set)
    string task_name                        # Task alias
    uint64 task_id                          # Task ID (generated on task creation)
    string map_name                         # Map alias (valid only when task depends on map)
    uint64 map_id                           # Map ID (generated on map creation)
    uint32 rest_site_number                 # Remaining tour sites (excluding current)
    uint64 cur_target_id                    # Current target point ID
    

    Available values for fix_line_intro_state (defined by the TM_FIX_LINE_INTRO_STATE enumeration):

    Enumeration Name	Value	Description
    TM_FIX_LINE_INTRO_STATE_NAVI_TO_NEXT_SITE	0	Navigate to next tour site
    TM_FIX_LINE_INTRO_STATE_SITE_ACTIONS	1	Execute current tour site action
    TM_FIX_LINE_INTRO_STATE_NAVI_RETURN	2	Navigate back to standby point
    TM_FIX_LINE_INTRO_STATE_NAVI_TO_TARGET_POI	3	Navigate to target POI
    TM_FIX_LINE_INTRO_STATE_POI_ACTIONS	4	Execute POI action
    TM_FIX_LINE_INTRO_STATE_STANDBY_ACTIONS	5	Standby action

  • PilotState ros2-msg @ task_engine/msg/PilotState.msg

    # Pilot task status
    uint8 pilot_state                       # Pilot task status, see TM_PILOT_STATE enum
    string target_name                      # Target point alias (POI alias when navigating to POI, tour site alias when navigating to tour site)
    uint64 target_id                        # Target point ID
    string intro_task_name                  # Tour task alias (valid only when navigating to a tour site created by a tour task)
    uint64 intro_task_id                    # Tour task ID
    string map_name                         # Map alias (valid only when task depends on map)
    uint64 map_id                           # Map ID (generated on map creation)
    

    Available values for pilot_state (defined by the TM_PILOT_STATE enumeration):

    Enumeration Name	Value	Description
    TM_PILOT_STATE_NAVI_TO_TARGET	0	Navigate to target point
    TM_PILOT_STATE_TARGET_ACTIONS	1	Execute target point action
    TM_PILOT_STATE_NAVI_RETURN	2	Navigate back
    TM_PILOT_STATE_STANDBY_ACTIONS	3	Standby action

Coordinate Conversion

The target_pose used by the navigation interface is in Map world coordinates (unit: meters). If the target originates from map pixel coordinates, convert pixel coordinates to world coordinates first.

Pixel coordinates can be obtained from the map info file at: /agibot/data/var/MapManagerModule/<map_id>/grid_map_info.txt

This file contains three lines:

• Line 1: resolution (pixels per 1 meter, e.g. 20)

• Line 2: origin pixel coordinates of the map (origin.u, origin.v of the mapping origin)

• Line 3: image width and height (in pixels)

Pixel → world coordinate conversion formula:

x = (pixel_u - origin_u) / resolution
y = -(pixel_v - origin_v) / resolution

Here resolution is from line 1, and origin_u/origin_v are from line 2. The resulting (x, y) can be used as target_pose.pose.position.

Programming Examples

Refer to the following detailed programming examples and code explanations:

• Python example (navigation): Navigation

• C++ example (navigation): Navigation

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