Navigation Interfaces

Draft for website testing. This is a condensed English draft, not a complete translation. Both language versions await final content-owner updates. Original technical details, code comments, tables, and illustrations are retained in Chinese in the expandable reference below.

Read the Chinese source

1. Scope

This reference covers eight navigation interfaces used by the WebSocket bridge. Topics use HYBRID channels; services use hybrid_rpc. For the state machine, battery, and diagnostics, see Core Function Interfaces.

2. Topic interfaces

Topic	Purpose
/navi/state	Subscribe to a combined snapshot of localization, SLAM health, navigation progress, teleoperation mode, and navigation-node state.
/initialpose	Publish an initial pose estimate with frame, timestamp, and covariance.
/joystick_info	Publish remote-control input and obstacle-handling policy.

/navi/state uses reliable, transient-local QoS with keep-last depth 1. The source describes event changes, pose thresholds, and a default 1 Hz heartbeat. For decisions, use current_pose from the localization source rather than the downstream pnc.robot_pos, which may lag or differ. SLAM error codes are valid only in the ERROR state. nav_node_state is for observation, not task admission.

3. Service interfaces

Service	Method	Purpose
/navi/get_teleop	get_teleop	Query the teleoperation mode.
/navi/mission	mission	Start, pause, resume, or stop a navigation mission.
/navi/set_teleop	set_teleop	Set the teleoperation mode.
/navi/start_docking_mission	start_docking_mission	Start docking or undocking.
/task/status	status	Query a task by ID; an empty ID queries the currently executing task.

The listed configurations disable automatic routing and use a 2000 ms service timeout. Teleoperation modes are 0 (off), 1 (default), and 2 (obstacle avoidance); mode 2 is explicitly marked unsupported in the source comments.

4. Result semantics

A successful docking-service response means the task started, not that movement finished. A successful task-status query means retrieval succeeded, not that the task itself succeeded. For the navigation mission service, the source leaves acceptance-versus-completion semantics for maintainer clarification.

Task states are 0 idle, 1 pending, 2 running, 3 paused, 4 succeeded, 5 failed, 6 canceled, and 7 timed out. The source leaves several frame, unit, historical-retention, and request-handling details pending; they must not be inferred from message types alone.

5. JSON configurations and Schemas

The complete original appendix below preserves every configuration, explicit anchor, message field, enum, and comment for comparison and link testing.

6. Original technical reference (Chinese)

Expand the original chapters, tables, code, and illustrations

范围：本页仅列出 WS 桥接使用的导航接口，共 8 条。状态机、电池与故障诊断接口见《状态信息接口清单》。

Topic 使用 HYBRID Channel，Service 使用 hybrid_rpc Channel；概览表中的“查看”可跳转到对应 JSON 配置。

接口概览表

订阅 topic（1）

Topic	介绍	类型	通路	配置要点	配置详情
/navi/state	获取定位、SLAM健康、导航任务进度、遥控模式和导航节点状态的聚合快照。	navigation_msgs/msg/NaviState	Hybrid.ros2（订阅）	auto_route=false；QoS reliable + transient_local + keep_last(1)	JSON / Schema

发布 topic（2）

Topic	介绍	类型	通路	配置要点	配置详情
/initialpose	发布带参考坐标系、时间戳及协方差的初始位姿估计。	geometry_msgs/msg/PoseWithCovarianceStamped	Hybrid.ros2（发布）	auto_route=false	JSON / Schema
/joystick_info	发布遥控输入及避障策略，支持不避障、遇障停止和尝试绕障。	navigation_msgs/msg/JoystickInfo	Hybrid.ros2（发布）	auto_route=false	JSON / Schema

service（5）

Service	介绍	service_type	调用 method	配置要点	配置详情
/navi/get_teleop	查询当前遥控模式：关闭、默认遥控或避障遥控。	navigation_msgs/srv/GetTeleopMode	get_teleop	auto_route=false；超时 2000ms	JSON / Schema
/navi/mission	控制导航任务开始、暂停、继续或停止，并传入目标位置。	navigation_msgs/srv/NavigationMission	mission	auto_route=false；超时 2000ms	JSON / Schema
/navi/set_teleop	设置遥控模式，返回设置成功与否及结果消息。	navigation_msgs/srv/SetTeleopMode	set_teleop	auto_route=false；超时 2000ms	JSON / Schema
/navi/start_docking_mission	启动对接充电桩或下桩移动任务，返回是否成功启动。	navigation_msgs/srv/StartDockingMission	start_docking_mission	auto_route=false；超时 2000ms	JSON / Schema
/task/status	按任务ID查询任务类型、执行状态、动作及起止时间；空ID查询当前执行任务。	task_msgs/srv/QueryTask	status	auto_route=false；超时 2000ms	JSON / Schema

附录：JSON 配置

每条配置对应概览表中的一行，键为实例名。

订阅 topic（1）

/navi/state

{
  "navi_state": {
    "type": "hybrid",
    "topic": "/navi/state",
    "handler": "reader",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "navigation_msgs/msg/NaviState",
      "qos": {
        "reliability": "reliable",
        "durability": "transient_local",
        "history": "keep_last",
        "depth": 1
      }
    }
  }
}

类型 Schema

类型：navigation_msgs/msg/NaviState

来源：RTypes develop：ros2_types/navigation_msgs/msg/NaviState.msg

###############################################################################
# NaviState.msg
#
# 导航聚合状态 —— 由 navi_node 发布到 /navi/state。
#
# QoS：KEEP_LAST(1) + RELIABLE + TRANSIENT_LOCAL
#      新订阅者一连接 DDS 直接给最后一帧，不必等心跳。
#
# 发布策略（事件型 + 心跳 + 位移阈值，不跟随 pnc 帧率）：
#   - pnc.state / pnc.error_code 变化
#   - slam_mode / slam_state / slam_error_code 变化
#   - slam_confidence 变化超过 ±navi_state_slam_confidence_threshold
#   - task_status / task_id 变化
#   - teleop_mode 变化
#   - current_pose 相对上次发布超过 xy/theta 阈值
#   - 心跳（默认 1Hz）
#
# 高频实时位姿请订阅 /slam_state；
# 系统状态机请订阅 /system_state；
# 建图进度请订阅 /map/save_info；
# 异常自恢复细节走日志 + RDiag 诊断。
###############################################################################

std_msgs/Header header                     # navi_node 发布该快照的时刻

# =============================================================================
# 当前定位（来源：slam_msgs/msg/SlamState.robot_pos —— 定位源头）
# 注意：pnc 自带的 pnc.robot_pos 是 pnc 链路下游的处理后位姿，可能与 current_pose
# 有微小延迟/差异；做决策请使用本字段，不要用 pnc.robot_pos。
# =============================================================================
geometry_msgs/Pose2D current_pose          # x, y, theta，来源 slam_state.robot_pos

# =============================================================================
# 底层 pnc 状态（提供 state / error_code / seq；pnc.robot_pos 字段保留但不推荐使用）
# pnc.header.stamp 为 pnc 上报时间，可与本消息 header.stamp 比较得到端到端延迟。
# =============================================================================
navigation_msgs/PncState pnc

# =============================================================================
# SLAM / 定位健康（语义与 slam_msgs/msg/SlamState 一致）
# =============================================================================

# slam mode
int32 SLAM_MODE_IDLE         = 0
int32 SLAM_MODE_MAPPING      = 1
int32 SLAM_MODE_LOCALIZATION = 2

# slam state
int32 SLAM_STATE_ERROR             = 0
int32 SLAM_STATE_RUNNING           = 1
int32 SLAM_STATE_RELOCATING        = 2
int32 SLAM_STATE_MAP_SAVING        = 3
int32 SLAM_STATE_RELOCATE_TIMEOUT  = 4

# slam error code（仅 slam_state == ERROR 时有效）
int32 SLAM_ERROR_CODE_NO_LIDAR            = 0
int32 SLAM_ERROR_CODE_NO_VISUAL           = 1
int32 SLAM_ERROR_CODE_NO_CHASSIS_FEEDBACK = 2
int32 SLAM_ERROR_CODE_NO_IMU              = 3

int32 slam_mode                            # SLAM_MODE_*
int32 slam_state                           # SLAM_STATE_*
int32 slam_error_code                      # SLAM_ERROR_*（仅 slam_state == ERROR 时有效）
int32 slam_confidence                      # 0–100，定位置信度

# =============================================================================
# 任务维度
# =============================================================================

# task type（仅声明 navi_node 实际会产生的类型）
int16 TASK_TYPE_NONE       = 0
int16 TASK_TYPE_NAVIGATION = 1

# task status（值与 task_msgs/srv/QueryTask Response 保持一致）
int16 TASK_STATUS_IDLE      = 0
int16 TASK_STATUS_PENDING   = 1
int16 TASK_STATUS_RUNNING   = 2
int16 TASK_STATUS_PAUSED    = 3
int16 TASK_STATUS_SUCCEEDED = 4
int16 TASK_STATUS_FAILED    = 5
int16 TASK_STATUS_CANCELED  = 6
int16 TASK_STATUS_TIMEOUT   = 7

string task_id                             # 当前任务 ID（无任务时为空）
int16  task_type                           # TASK_TYPE_*
int16  task_status                         # TASK_STATUS_*
string task_failed_msg                     # 失败/超时原因（仅 FAILED/TIMEOUT 时有效）
geometry_msgs/Pose2D task_target           # 任务目标点（无任务时各分量为 0）
builtin_interfaces/Time task_start_time    # 任务开始时刻（无任务时 0）
builtin_interfaces/Time task_end_time      # 任务结束时刻（终态时有效）

# =============================================================================
# 遥控模式（值与 navigation_msgs/srv/GetTeleopMode 一致）
# =============================================================================
uint8 TELEOP_MODE_IDLE     = 0
uint8 TELEOP_MODE_HEADLESS = 1
uint8 TELEOP_MODE_AVOID    = 2

uint8 teleop_mode

# =============================================================================
# navi_node 自维护的对外状态（observability-only，非任务准入门）
# =============================================================================

int16 NAV_NODE_STATE_UNKNOWN     = 0    # pnc/slam 尚未上报，状态未知
int16 NAV_NODE_STATE_NOT_READY   = 1    # 系统状态机不允许接受导航任务
int16 NAV_NODE_STATE_IDLE        = 2    # 空闲
int16 NAV_NODE_STATE_NAVIGATING  = 3    # 正在执行导航任务
int16 NAV_NODE_STATE_PAUSED      = 4    # 任务暂停
int16 NAV_NODE_STATE_STUCK       = 5    # 卡住（pnc 报 STUCK，非 sticky）
int16 NAV_NODE_STATE_RECOVERING  = 6    # navi_node 正在执行 PNC reset 自恢复
int16 NAV_NODE_STATE_FAILED      = 7    # 任务失败 / 不再自恢复（sticky，至 startTask 或者切换遥控 清除）
int16 NAV_NODE_STATE_TELEOP      = 8    # 遥控模式
int16 NAV_NODE_STATE_MAP_SWITCHING = 9  # 正在切换地图状态

int16 nav_node_state

嵌套类型 Schema：PncState

类型：navigation_msgs/msg/PncState

对应字段：NaviState.pnc。此类型嵌套的 Header、Pose2D 均为 ROS 2 标准类型。

来源：RTypes develop（d323923），定义文件 PncState.msg。

# 导航状态上报
## pnc state info
# topic name: /pnc_state

int16 STATE_RESET = 0      ## Temporary state for handling the reset command
int16 STATE_IDLE = 1       ## Ready to start, waiting for external command
int16 STATE_PLANNING = 2   ## Actively planning
int16 STATE_FAILED = 3     ## Planning failed
int16 STATE_PAUSED = 4     ## Planner is paused by external command
int16 STATE_CONTINUE = 5   ## Temporary state for handling the start command when paused
int16 STATE_EXIT = 6       ## Temporary state for handling the exit command
int16 STATE_JOYSTICK = 7   ## User is controlling the robot using the remote/joystick
int16 STATE_STOPPING = 8   ## Temporary state while changing from other states to idle state
int16 STATE_TUNE = 9       ## when reach the target with tolerance, tune the position/orientaion to exactly reach it.
int16 STATE_STUCK = 10     ## when stuck

std_msgs/Header header

int16 state
geometry_msgs/Pose2D robot_pos # x, y, and theta
int32 seq
int16 error_code

PncState 语义说明：state 表示规划控制状态：0处理重置的临时状态、1空闲等待外部指令、2规划中、3规划失败、4外部指令暂停、5暂停后处理启动的临时状态、6处理退出的临时状态、7遥控控制、8切换到空闲的停止过渡、9进入目标容差后精调位置或朝向、10受阻。robot_pos 为 x、y、theta；在 NaviState 中，头部注释要求决策使用 current_pose，因为 pnc.robot_pos 属于下游处理位姿，可能有延迟或差异。NaviState 注释将 pnc.header.stamp 说明为 PNC 上报时间。error_code 字段类型为 int16，代码未限制连续取值范围；navi_node 当前按 pncErrorToString 映射为：10（ERR_PLAN_FAILED）全局路径规划失败；11（ERR_START_IN_OBSTACLE）起始位置存在障碍物；12（ERR_GOAL_IN_OBSTACLE）目标点存在障碍物；33（ERR_ODOM_FAIL）定位丢失；34（ERR_PERCEPTION_LOST）感知异常；35（ERR_POSE_JUMP）定位跳变；36（ERR_TIME_GOES_BACK）时间跳变；55（ERR_NO_ENOUGH_FREE_SPACE）遇障；75（ERR_TOO_CLOSE_TO_OBSTACLES）起步阶段离障碍物太近；其他未匹配值统一按 ERR_MOTION_FAILED（导航异常）处理。

语义说明：header 表示快照发布时间；current_pose 来自定位源头，决策应使用该字段，不应使用可能有延迟的 pnc.robot_pos。slam_mode/state/error_code 分别描述定位模式、状态与错误，错误码仅在 ERROR 状态有效；slam_confidence 为 0–100。task_id 无任务时为空，task_failed_msg 仅在失败或超时时有效，结束时间在终态有效。任务状态为 0空闲、1等待、2执行、3暂停、4成功、5失败、6取消、7超时。teleop_mode 为 0未启用、1默认遥控、2避障遥控；相关服务注释标注避障遥控暂不支持。nav_node_state 用于观测，不作为任务准入条件。头部约定以状态变化、位移阈值和默认1Hz心跳发布，可靠且保留最近一帧。

发布 topic（2）

/initialpose

{
  "initialpose": {
    "type": "hybrid",
    "topic": "/initialpose",
    "handler": "writer",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "geometry_msgs/msg/PoseWithCovarianceStamped"
    }
  }
}

类型 Schema

类型：geometry_msgs/msg/PoseWithCovarianceStamped

来源：ROS 2 Humble 标准模块 geometry_msgs（由 RTypes 声明为依赖）

# This expresses an estimated pose with a reference coordinate frame and timestamp

std_msgs/Header header
PoseWithCovariance pose

语义说明：消息描述带参考坐标系与时间戳的估计位姿，header 携带时间及坐标系信息，pose 包含位姿和协方差。待维护者补充：本接口接受的 frame_id、位姿与协方差填写约定，以及发布后定位重置的确认方式；当前外层 Schema 注释没有定义这些业务行为。

/joystick_info

{
  "joystick_info": {
    "type": "hybrid",
    "topic": "/joystick_info",
    "handler": "writer",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "navigation_msgs/msg/JoystickInfo"
    }
  }
}

类型 Schema

类型：navigation_msgs/msg/JoystickInfo

来源：RTypes develop：ros2_types/navigation_msgs/msg/JoystickInfo.msg

# 遥控信息
# JoystickInfo.msg

## topic name /joystick_info

uint16 AVOID_TYPE_NO_AVOID = 0      ## don't consider obstacle 
uint16 AVOID_TYPE_STOP = 1          ## stop in front of the obstacle 
uint16 AVOID_TYPE_AVOID = 2         ## go around if possible 

std_msgs/Header header
float32[] axes ## two types: 1. linear_x, linear_y, and omega 2. direct: x, y, z

uint16 avoid_type

语义说明：axes 注释列出两种表示：linear_x、linear_y、omega，或直接 x、y、z；avoid_type 为 0不考虑障碍、1在障碍前停止、2尽可能绕行。待维护者补充：两种 axes 表示的选择方式、长度、单位、坐标系及 header 时间约定。

service（5）

/navi/get_teleop

{
  "navi_get_teleop_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/navi",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false,
      "default_timeout_ms": 2000
    },
    "ros2": {
      "service_prefix": "/navi",
      "service_type": "navigation_msgs/srv/GetTeleopMode"
    }
  }
}

类型 Schema

类型：navigation_msgs/srv/GetTeleopMode

来源：RTypes develop：ros2_types/navigation_msgs/srv/GetTeleopMode.srv

# 获取遥控状态

---
uint8 TELEOP_MODE_IDLE = 0                 # 未启用遥控模式
uint8 TELEOP_MODE_HEADLESS = 1             # 默认遥控模式
uint8 TELEOP_MODE_AVOID = 2                # 避障遥控模式（暂不支持）

uint8 teleop_mode                          # 遥控模式

语义说明：请求为空；响应 teleop_mode 为 0未启用遥控、1默认遥控、2避障遥控。Schema 注释明确标注模式2暂不支持，不能仅根据枚举存在认为该能力已可用。

/navi/mission

{
  "navi_mission_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/navi",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false,
      "default_timeout_ms": 2000
    },
    "ros2": {
      "service_prefix": "/navi",
      "service_type": "navigation_msgs/srv/NavigationMission"
    }
  }
}

类型 Schema

类型：navigation_msgs/srv/NavigationMission

来源：RTypes develop：ros2_types/navigation_msgs/srv/NavigationMission.srv

# 导航任务
# NavigationMission.srv

# Request

uint8 NAVI_COMMAND_START = 0	    # 开始导航
uint8 NAVI_COMMAND_PAUSE = 1	    # 暂停导航
uint8 NAVI_COMMAND_RESUME = 2	    # 继续导航
uint8 NAVI_COMMAND_STOP = 3		    # 停止导航

uint8 navi_command	                # 导航指令
geometry_msgs/Pose2D target_pos     # 目标位置

---

# Response

bool success                        # 导航任务是否成功
string message                      # 导航任务结果描述

语义说明：navi_command 为 0开始、1暂停、2继续、3停止导航；target_pos 为目标位置。响应 success 表示导航任务结果，message 给出结果描述。待维护者补充：目标坐标系及单位、非开始指令如何处理 target_pos，以及响应成功代表受理还是最终完成；现有注释未明确这些约束。

/navi/set_teleop

{
  "navi_set_teleop_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/navi",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false,
      "default_timeout_ms": 2000
    },
    "ros2": {
      "service_prefix": "/navi",
      "service_type": "navigation_msgs/srv/SetTeleopMode"
    }
  }
}

类型 Schema

类型：navigation_msgs/srv/SetTeleopMode

来源：RTypes develop：ros2_types/navigation_msgs/srv/SetTeleopMode.srv

# 遥控模式设置接口

uint8 TELEOP_MODE_IDLE = 0                 # 不启用遥控模式
uint8 TELEOP_MODE_HEADLESS = 1             # 默认遥控模式
uint8 TELEOP_MODE_AVOID = 2                # 避障遥控模式（暂不支持）

uint8 teleop_mode                          # 遥控模式

---
bool success                               # 设置成功/失败
string message                             # 设置结果消息

语义说明：teleop_mode 为 0关闭遥控、1默认遥控、2避障遥控；模式2在注释中标为暂不支持。响应 success 表示设置成功或失败，message 为设置结果消息。

/navi/start_docking_mission

{
  "navi_start_docking_mission_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/navi",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false,
      "default_timeout_ms": 2000
    },
    "ros2": {
      "service_prefix": "/navi",
      "service_type": "navigation_msgs/srv/StartDockingMission"
    }
  }
}

类型 Schema

类型：navigation_msgs/srv/StartDockingMission

来源：RTypes develop：ros2_types/navigation_msgs/srv/StartDockingMission.srv

# 启动充电桩对接相关移动任务
# StartDockingMission.srv

int16 MISSION_TYPE_DOCK   = 0   # 启动对桩移动
int16 MISSION_TYPE_UNDOCK = 1   # 启动下桩移动

# Request
int16 mission_type

---

# Response
bool success                    # 是否成功启动任务
string message                  # 结果或错误信息

语义说明：mission_type 为 0启动对桩移动、1启动下桩移动。success 明确表示是否成功启动任务，message 为结果或错误信息；成功启动不等于已完成移动。

/task/status

{
  "task_status_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/task",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false,
      "default_timeout_ms": 2000
    },
    "ros2": {
      "service_prefix": "/task",
      "service_type": "task_msgs/srv/QueryTask"
    }
  }
}

类型 Schema

类型：task_msgs/srv/QueryTask

来源：RTypes develop：ros2_types/task_msgs/srv/QueryTask.srv

string task_id                       # 任务id，用于查询，若为空，返回当前正在执行任务

---

# Response

# 任务获取结果信息
bool success                                 # 任务获取是否成功
string error_message                         # 任务获取错误信息

string task_id                               # 任务唯一ID

# 任务类型
int16 TASK_TYPE_NONE             = 0         # 无任务
# 基础任务 0-99
int16 TASK_TYPE_NAVIGATION      = 1          # 导航
int16 TASK_TYPE_CHARGING        = 2          # 充电

# 业务相关
# 药房业务 100-199
int16 TASK_TYPE_PHARMACY_PICKUP = 100        # 取药任务

int16 task_type                              # 任务类型


int16 TASK_STATUS_IDLE        = 0           # 空闲，无任务
int16 TASK_STATUS_PENDING     = 1           # 等待执行
int16 TASK_STATUS_RUNNING     = 2           # 执行中
int16 TASK_STATUS_PAUSED      = 3           # 已暂停
int16 TASK_STATUS_SUCCEEDED   = 4           # 执行成功
int16 TASK_STATUS_FAILED      = 5           # 执行失败
int16 TASK_STATUS_CANCELED    = 6           # 已取消
int16 TASK_STATUS_TIMEOUT     = 7           # 超时

int16 task_status                           # 任务状态

builtin_interfaces/Time start_time          # 任务开始时间
builtin_interfaces/Time end_time            # 结束时间


# 动作类型，待扩展
int16 ACTION_TYPE_NONE              = 0      # 无动作
int16 ACTION_TYPE_NAVIGATE          = 1      # 导航（底盘动作）
int16 ACTION_TYPE_MANIPULATION      = 2      # 上半身动作
int16 ACTION_TYPE_CHARGE            = 3      # 充电

int16 action_type                            # 动作类型
string task_failed_msg                       # 任务失败信息， task_status == TASK_STATUS_FAILED时填充

语义说明：请求 task_id 为空时查询当前正在执行的任务；响应 success/error_message 描述获取任务是否成功，不能把 success 当作任务执行成功。task_status 为 0空闲、1等待、2执行、3暂停、4成功、5失败、6取消、7超时。task_type 包含无任务、导航、充电及药房取药；action_type 包含无动作、导航、上半身操作、充电。start_time/end_time 为任务起止时间；task_failed_msg 在 TASK_STATUS_FAILED 时填写。待维护者补充：历史任务保留周期及不存在ID的具体返回约定。