5.5.3 导航（选装）

导航模块提供路径规划与自主导航接口，支持机器人在已知地图中执行点到点导航任务，并支持暂停、恢复、停止等任务控制操作。

重要

本处为选装组件, 如需使用本页面所述功能接口, 请联系售后技术支持

导航任务话题

话题名称

数据类型

描述

QoS

频率

/aima/te/pnc_task_request

PncTaskRequest

发布导航任务请求（开始/暂停/恢复/停止）

BEST_EFFORT+VOLATILE

用户发送（按需）

/aima/pnc/pnc_task_response

PncTaskResponse

导航任务执行结果反馈

BEST_EFFORT+TRANSIENT_LOCAL

事件驱动（任务状态变化时）

/task_master/state

TaskMasterState

任务引擎状态（主状态、子状态、SLAM 状态、导览/领航任务状态）

BEST_EFFORT+TRANSIENT_LOCAL

1Hz

前置条件

使用导航功能前，需确保以下条件就绪：

  1. 已完成重定位：机器人已在地图中完成定位（通过 start_relocalization:<map_id> 指令触发，详见 SLAM）

  2. 已设置当前工作地图：导航请求中的 map_id 需与重定位所用的地图 ID 一致（重定位流程会自动加载目标地图并建立定位；若导航时指定其他 map_id，PNC 会加载该地图数据但定位坐标系仍停留在重定位地图上，导致导航异常）。map_id 必须为有效已建图的地图 ID

  3. 运动控制模式为稳定站立（STAND_DEFAULT）或走跑（LOCOMOTION_DEFAULT）：机器人需处于可接收走跑指令的模式，否则导航任务将被阻断。稳定站立与走跑模式为一体化设计，导航下发的速度指令会驱动二者内部自动切换（详见 运动模式切换）

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

    # 导航任务请求
# 话题名称: /aima/te/pnc_task_request

MessageHeader header

uint8 task_type                             # 任务类型，见枚举定义 TASK_TYPE
uint8 task_request                          # 任务请求，见枚举定义 TASK_REQUEST
uint8 pnc_mode                              # PNC 模式（0: NORMAL，开启避障；1: NO_PERCEPTION，关闭避障）
uint64 task_id                              # 任务 ID，暂停/恢复/停止时需与开始时保持一致
uint64 map_id                               # 地图 ID
geometry_msgs/PoseStamped target_pose       # 目标位姿
geometry_msgs/Pose2D[] reference_line       # 指引线（仅考虑 x, y），target_pose 设置为目标姿态（yaw）
float64 target_pose_radius                  # 目标范围半径（单位：m），最小有效值 0.25
float32 max_forward_speed                   # 最大运行速度（单位：m/s，默认 0.8）

geometry_msgs/Pose2D[] trajectory_pos       # （预留）群控参数
geometry_msgs/Twist[] trajectory_vel        # （预留）群控参数
uint64 play_timestamp                       # （预留）群控参数
uint64 time_duration                        # （预留）群控参数

# 64 byte 保留字段
char[64] reserve_info

    task_type 可用值（TASK_TYPE 枚举定义）：

    枚举名

    数值

    说明

    TASK_TYPE_PLANNING_NAVI_TO_POSE_2D

    2

    规划导航至二维位姿

    其他枚举值仅供内部使用。

    task_request 可用值（TASK_REQUEST 枚举定义）：

    枚举名

    数值

    说明

    TASK_REQUEST_NONE

    0

    无请求

    TASK_REQUEST_START

    1

    开始导航任务

    TASK_REQUEST_STOP

    2

    停止导航，任务状态清除

    TASK_REQUEST_PAUSE

    3

    暂停导航，机器人原地停止，状态保留

    TASK_REQUEST_RESUME

    4

    恢复已暂停的导航任务

    TASK_REQUEST_STATUS_INQUIRY

    5

    查询当前任务状态

接口说明

开始导航

设置目标位姿、地图 ID、避障模式和速度，发起导航任务。

PncTaskRequest.task_type = TASK_TYPE_PLANNING_NAVI_TO_POSE_2D
PncTaskRequest.task_request = TASK_REQUEST_START
PncTaskRequest.task_id = xxx          // 任务 ID（毫秒时间戳）
PncTaskRequest.map_id = xxxx          // 实际所用地图 ID
PncTaskRequest.pnc_mode = 0           // 0: NORMAL（开启避障），1: NO_PERCEPTION（关闭避障）
PncTaskRequest.max_forward_speed = 0.5 // 最大前进速度（m/s）
PncTaskRequest.target_pose = ...      // 目标点位姿
PncTaskRequest.target_pose_radius = 0.5 // 到点精度控制（m）

暂停导航

暂停当前导航任务，机器人原地停止，任务状态保留。

PncTaskRequest.task_type = TASK_TYPE_PLANNING_NAVI_TO_POSE_2D
PncTaskRequest.task_request = TASK_REQUEST_PAUSE
PncTaskRequest.task_id = xxx          // 与开始导航时一致的任务 ID

恢复导航

恢复已暂停的导航任务，机器人继续执行之前的导航目标。

PncTaskRequest.task_type = TASK_TYPE_PLANNING_NAVI_TO_POSE_2D
PncTaskRequest.task_request = TASK_REQUEST_RESUME
PncTaskRequest.task_id = xxx          // 与开始导航时一致的任务 ID

停止导航

停止当前导航任务，任务状态清除。

PncTaskRequest.task_type = TASK_TYPE_PLANNING_NAVI_TO_POSE_2D
PncTaskRequest.task_request = TASK_REQUEST_STOP
PncTaskRequest.task_id = xxx          // 与开始导航时一致的任务 ID

提醒： map_id 是用户必填字段（获取方式见 地图标识与坐标的获取），暂停/恢复/停止时 task_id 需与开始导航时保持一致。

获取导航任务执行结果

订阅 /aima/pnc/pnc_task_response 话题，获取导航任务的执行结果。该话题仅在任务状态变化时发布一次（如 RUNNING/FAILED/FINISHED/PAUSED）。

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

    # 导航任务执行结果
# 话题名称: /aima/pnc/pnc_task_response

MessageHeader header

uint8 task_type                             # 任务类型，见枚举定义 TASK_TYPE
uint64 task_id                              # 任务 ID（同请求时的 task_id）
uint64 map_id                               # 地图 ID
uint8 task_status                           # 任务状态，见枚举定义 TASK_STATUS

# 64 byte 保留字段
char[64] reserve_info

    task_status 可用值（TASK_STATUS 枚举定义）：

    枚举名

    数值

    说明

    TASK_STATUS_UNKONW

    0

    未知状态

    TASK_STATUS_RUNNING

    1

    任务执行中

    TASK_STATUS_FAILED

    2

    任务失败

    TASK_STATUS_PAUSED

    3

    任务已暂停

    TASK_STATUS_FINISHED

    4

    任务已完成

    TASK_STATUS_RECOVERY_TIMEOUT

    22

    恢复超时

    其他状态

    10-31

    详见 PncTaskResponse.msg 定义

警告

导航任务可能被自动中断

当机器人检测到严重系统故障时（如摔倒、系统故障等），导航任务可能被自动中断。机器人会播放 TTS 语音提示：“抱歉，检测到系统存在故障，不能进行自主导航任务了。请前往客户端查看故障原因。”

如需程序化获知导航任务是否被中断，可通过以下方式：

  • 订阅 /aima/pnc/pnc_task_response 话题，观察 task_status 是否变为 FAILED

  • 订阅 /task_master/state 话题，观察 main_state 是否从 PILOT 变为 IDLE

获取任务引擎状态

订阅 /task_master/state 话题，获取任务引擎的整体状态。该话题为周期发布，持续更新任务引擎的状态机状态。

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

    # 任务引擎状态
# 话题名称: /task_master/state

uint8 main_state                          # 主状态，见枚举定义 TM_MAIN_STATE
uint8 sub_state                           # 子状态，见枚举定义 TM_SUB_STATE
uint8 slam_state                          # SLAM 状态，见枚举定义 SLAM_STATE
uint64 loc_map_id                         # 当前定位地图 ID（仅 slam_state=LOCALIZATION 时有效）
string loc_map_name                       # 当前定位地图名称（仅 slam_state=LOCALIZATION 时有效）

FixLineIntroState fix_line_intro_state    # 导览任务状态（仅 main_state=FIX_LINE_INTRO 时有效）
PilotState pilot_state                    # 领航任务状态（仅 main_state=PILOT 时有效）

# 保留信息
string reserve_info

    main_state 可用值（TM_MAIN_STATE 枚举定义）：

    枚举名

    数值

    说明

    TM_MAIN_STATE_IDLE

    0

    空闲状态

    TM_MAIN_STATE_RELOCALIZATION

    1

    重定位中

    TM_MAIN_STATE_MAPPING

    2

    建图中

    TM_MAIN_STATE_FIX_LINE_INTRO

    3

    导览任务执行中

    TM_MAIN_STATE_RECORDING_PATH

    4

    录制路径中

    TM_MAIN_STATE_PILOT

    5

    领航任务执行中

    sub_state 可用值（TM_SUB_STATE 枚举定义）：

    枚举名

    数值

    说明

    TM_SUB_STATE_NONE

    0

    无子状态

    TM_SUB_STATE_RESUME

    1

    长程任务运行中

    TM_SUB_STATE_PAUSE

    2

    长程任务暂停中

    slam_state 可用值（SLAM_STATE 枚举定义）：

    枚举名

    数值

    说明

    SLAM_STATE_IDLE

    0

    SLAM 空闲

    SLAM_STATE_RELOCALIZATION

    1

    SLAM 重定位中

    SLAM_STATE_MAPPING

    2

    SLAM 建图中

    SLAM_STATE_LOCALIZATION

    3

    SLAM 定位中

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

      # 导览任务状态
uint8 fix_line_intro_state              # 导览任务状态，见枚举定义 TM_FIX_LINE_INTRO_STATE
uint64 set_task_id                      # 用户预设置任务的 ID（若未设置过则为 0）
string set_task_name                    # 用户预设置任务的别名（若未设置过则为空）
string task_name                        # 任务别名
uint64 task_id                          # 任务 ID（创建任务时生成）
string map_name                         # 地图别名（仅任务依赖地图时有效）
uint64 map_id                           # 地图 ID（创建地图时生成）
uint32 rest_site_number                 # 剩余讲解点数量（不包含当前讲解点）
uint64 cur_target_id                    # 当前目标点位 ID

      fix_line_intro_state 可用值（TM_FIX_LINE_INTRO_STATE 枚举定义）：

      枚举名

      数值

      说明

      TM_FIX_LINE_INTRO_STATE_NAVI_TO_NEXT_SITE

      0

      导航到下一个讲解点

      TM_FIX_LINE_INTRO_STATE_SITE_ACTIONS

      1

      执行当前讲解点动作

      TM_FIX_LINE_INTRO_STATE_NAVI_RETURN

      2

      导航返回待机点

      TM_FIX_LINE_INTRO_STATE_NAVI_TO_TARGET_POI

      3

      导航到目标 POI

      TM_FIX_LINE_INTRO_STATE_POI_ACTIONS

      4

      执行 POI 动作

      TM_FIX_LINE_INTRO_STATE_STANDBY_ACTIONS

      5

      待机动作

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

      # 领航任务状态
uint8 pilot_state                       # 领航任务状态，见枚举定义 TM_PILOT_STATE
string target_name                      # 目标点别名（导航至 POI 时为 POI 别名，导航至讲解点时为讲解点别名）
uint64 target_id                        # 目标点 ID
string intro_task_name                  # 讲解任务别名（仅导航至讲解任务创建的讲解点时有效）
uint64 intro_task_id                    # 讲解任务 ID
string map_name                         # 地图别名（仅任务依赖地图时有效）
uint64 map_id                           # 地图 ID（创建地图时生成）

      pilot_state 可用值（TM_PILOT_STATE 枚举定义）：

      枚举名

      数值

      说明

      TM_PILOT_STATE_NAVI_TO_TARGET

      0

      导航到目标点

      TM_PILOT_STATE_TARGET_ACTIONS

      1

      执行目标点动作

      TM_PILOT_STATE_NAVI_RETURN

      2

      导航返回

      TM_PILOT_STATE_STANDBY_ACTIONS

      3

      待机动作

编程示例

详细的编程示例和代码说明请参考：

  • Python 示例（导航）：导航

  • C++ 示例（导航）：导航

小心

ROS的服务(service)机制在跨板通信时存在一些待优化问题, 二次开发时请参考例程添加异常处理、快速重试等保护机制

机器人处于稳定站立 / 走跑模式时, 请勿批量快速启动 ROS 节点(建议不超过 2 个/秒), 短时间内大量节点参与 DDS 发现会造成通信拥塞、影响运控实时性, 存在机器人失稳摔倒风险