基础功能接口清单

1. 状态信息接口清单

范围：本页集中列出 WS 桥接使用的状态信息接口，共 4 条。电池信息属于状态信息。导航接口见《导航接口清单》。

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

1.1. 接口概览表

1.1.1. 订阅 topic（2）

Topic	介绍	类型	通路	配置要点	配置详情
`/battery_state`	获取电池电量、充放电状态、健康度、电压电流、温度及单体数据。	`sensor_msgs/msg/BatteryState`	Hybrid.ros2（订阅）	auto_route=false；QoS best_effort	JSON / Schema
`/diagnostic`	获取整机最高故障等级及逐条故障的代码、来源、描述和发生时间。	`rdiagnostic_msgs/msg/HealthState`	Hybrid.ros2（订阅）	auto_route=false；QoS best_effort + keep_last(5)	JSON / Schema

1.1.2. service（2）

Service	介绍	service_type	调用 method	配置要点	配置详情
`/change_state`	请求切换系统主/子状态，返回结果、错误信息及实际状态。	`state_machine_msgs/srv/ChangeState`	`change_state`	auto_route=false；超时 2000ms	JSON / Schema
`/get_sm_state`	查询系统当前、前一及目标主/子状态，同时返回状态开始时间和切换原因。	`state_machine_msgs/srv/GetSMState`	`get_sm_state`	auto_route=false；超时 2000ms	JSON / Schema

1.2. 附录：JSON 配置

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

1.2.1. 订阅 topic（2）

1.2.1.1. /battery_state

{
  "battery_state": {
    "type": "hybrid",
    "topic": "/battery_state",
    "handler": "reader",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "sensor_msgs/msg/BatteryState",
      "qos": {
        "reliability": "best_effort"
      }
    }
  }
}

1.2.1.1.1. 类型 Schema

类型：sensor_msgs/msg/BatteryState

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

# Constants are chosen to match the enums in the linux kernel
# defined in include/linux/power_supply.h as of version 3.7
# The one difference is for style reasons the constants are
# all uppercase not mixed case.

# Power supply status constants
uint8 POWER_SUPPLY_STATUS_UNKNOWN = 0
uint8 POWER_SUPPLY_STATUS_CHARGING = 1
uint8 POWER_SUPPLY_STATUS_DISCHARGING = 2
uint8 POWER_SUPPLY_STATUS_NOT_CHARGING = 3
uint8 POWER_SUPPLY_STATUS_FULL = 4

# Power supply health constants
uint8 POWER_SUPPLY_HEALTH_UNKNOWN = 0
uint8 POWER_SUPPLY_HEALTH_GOOD = 1
uint8 POWER_SUPPLY_HEALTH_OVERHEAT = 2
uint8 POWER_SUPPLY_HEALTH_DEAD = 3
uint8 POWER_SUPPLY_HEALTH_OVERVOLTAGE = 4
uint8 POWER_SUPPLY_HEALTH_UNSPEC_FAILURE = 5
uint8 POWER_SUPPLY_HEALTH_COLD = 6
uint8 POWER_SUPPLY_HEALTH_WATCHDOG_TIMER_EXPIRE = 7
uint8 POWER_SUPPLY_HEALTH_SAFETY_TIMER_EXPIRE = 8

# Power supply technology (chemistry) constants
uint8 POWER_SUPPLY_TECHNOLOGY_UNKNOWN = 0
uint8 POWER_SUPPLY_TECHNOLOGY_NIMH = 1
uint8 POWER_SUPPLY_TECHNOLOGY_LION = 2
uint8 POWER_SUPPLY_TECHNOLOGY_LIPO = 3
uint8 POWER_SUPPLY_TECHNOLOGY_LIFE = 4
uint8 POWER_SUPPLY_TECHNOLOGY_NICD = 5
uint8 POWER_SUPPLY_TECHNOLOGY_LIMN = 6

std_msgs/Header  header
float32 voltage          # Voltage in Volts (Mandatory)
float32 temperature      # Temperature in Degrees Celsius (If unmeasured NaN)
float32 current          # Negative when discharging (A)  (If unmeasured NaN)
float32 charge           # Current charge in Ah  (If unmeasured NaN)
float32 capacity         # Capacity in Ah (last full capacity)  (If unmeasured NaN)
float32 design_capacity  # Capacity in Ah (design capacity)  (If unmeasured NaN)
float32 percentage       # Charge percentage on 0 to 1 range  (If unmeasured NaN)
uint8   power_supply_status     # The charging status as reported. Values defined above
uint8   power_supply_health     # The battery health metric. Values defined above
uint8   power_supply_technology # The battery chemistry. Values defined above
bool    present          # True if the battery is present

float32[] cell_voltage   # An array of individual cell voltages for each cell in the pack
                         # If individual voltages unknown but number of cells known set each to NaN
float32[] cell_temperature # An array of individual cell temperatures for each cell in the pack
                           # If individual temperatures unknown but number of cells known set each to NaN
string location          # The location into which the battery is inserted. (slot number or plug)
string serial_number     # The best approximation of the battery serial number

语义说明：voltage 单位V，temperature 单位°C，current 单位A且放电为负；charge、capacity、design_capacity 单位Ah，分别表示当前电量、上次满充容量和设计容量。percentage 为0–1比例。未测量的相关浮点量按注释填NaN；单体数量已知但数值未知时，对应数组元素填NaN。power_supply_status 表示未知、充电、放电、未充电、已满；health 与 technology 分别使用各自健康和化学类型常量。present 表示电池是否存在，location 与 serial_number 表示安装位置和序列号。待维护者补充：本设备实际提供的字段及采样时间约定。

1.2.1.2. /diagnostic

{
  "diagnostic": {
    "type": "hybrid",
    "topic": "/diagnostic",
    "handler": "reader",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "rdiagnostic_msgs/msg/HealthState",
      "qos": {
        "history": "keep_last",
        "depth": 5,
        "reliability": "best_effort",
        "durability": "volatile"
      }
    }
  }
}

1.2.1.2.1. 类型 Schema

类型：rdiagnostic_msgs/msg/HealthState

来源：RTypes develop：ros2_types/rdiagnostic_msgs/msg/HealthState.msg

###############################################################################
# Copyright (c) 2025 RobbyAnt. All rights reserved. 
#
# HealthState.msg
# Topic: /diagnostic
# Description: 机器人健康状态信息
#
# Author: qiaosou.wxt
# Version: 1.0.0
# Last Update: 2025-12-12
###############################################################################

# 当前最高的故障等级，用于快速判断机器人健康状态
# 值见于 ErrorInfo.msg
uint8 severity_level

# 故障信息列表
rdiagnostic_msgs/ErrorInfo[] errors

1.2.1.2.2. 间接依赖类型 Schema：ErrorInfo

类型：rdiagnostic_msgs/msg/ErrorInfo

来源：RTypes develop：ros2_types/rdiagnostic_msgs/msg/ErrorInfo.msg

###############################################################################
# Copyright (c) 2025 RobbyAnt. All rights reserved. 
#
# ErrorInfo.msg
#
# 描述一条故障信息的基础数据结构
#
# Author: qiaosou.wxt
# Version: 1.0.0
# Last Update: 2025-12-19
###############################################################################

# 原始故障码
uint32 code

# 故障模块ID, 可能为空
string module_id

# 故障描述信息
string message

# 故障发生时间，系统时间戳，单位毫秒
uint64 occurrence_time_ms

# 上报故障的进程Nexus ID
uint8 source_id

# 故障等级，从code中解析而得
uint8 severity_level

# 面向用户和运维人员的故障描述码,根据code和module_id生成
string code_str

uint8 SEVERITY_LEVEL_NONE = 0 # 无故障
uint8 SEVERITY_LEVEL_INFO = 1 # 通知
uint8 SEVERITY_LEVEL_WARN = 2 # 警告
uint8 SEVERITY_LEVEL_ERROR = 4 # 错误
uint8 SEVERITY_LEVEL_FATAL = 8 # 致命错误

语义说明：HealthState.severity_level 为当前最高故障等级，errors 为 ErrorInfo 列表。等级为0无故障、1通知、2警告、4错误、8致命错误。ErrorInfo.code 为原始故障码，module_id 可为空，message 为故障描述，occurrence_time_ms 为系统时间戳且单位毫秒，source_id 为上报进程的 Nexus ID；severity_level 从 code 解析，code_str 由 code 和 module_id 生成，面向用户与运维。待维护者补充：原始码编码规则及故障消失后的列表更新约定。

1.2.2. service（2）

1.2.2.1. /change_state

{
  "change_state_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false,
      "default_timeout_ms": 2000
    },
    "ros2": {
      "service_prefix": "/",
      "service_type": "state_machine_msgs/srv/ChangeState"
    }
  }
}

1.2.2.1.1. 类型 Schema

类型：state_machine_msgs/srv/ChangeState

来源：RTypes develop：ros2_types/state_machine_msgs/srv/ChangeState.srv

###############################################################################
# Copyright (c) 2026 RobbyAnt. All rights reserved.
#
# ChangeState.srv
# Service: /change_state
# Description: 请求状态切换服务
#
# Author: jinlong
# Version: 1.0.0
# Last Update: 2026-03-17
###############################################################################

# ============ Request ============
string TRIGGER_HMI_REQUEST=hmi_request
string TRIGGER_API_REQUEST=api_request
string TRIGGER_DOUBLE_CLICK=double_click
string TRIGGER_TRIPLE_CLICK=triple_click

uint8 target_main_state          # 目标主状态（0表示保持当前主状态）
uint8 target_sub_state           # 目标子状态（0表示 IDLE）
string trigger                   # 触发类型（空字符串默认为 hmi_request）

---

# ============ Response ============
bool success                     # 操作是否成功

uint16 error_code                # 结构化错误码

string message                   # 结果描述，如果失败则用于描述失败原因

uint8 current_main_state          # 转换后的实际主状态

uint8 current_sub_state           # 切换后的实际子状态

1.2.2.1.2. `target_main_state` 取值范围

以下取值沿用 SystemState 的主状态枚举。注意：在 /change_state 请求中，target_main_state = 0 的语义是“保持当前主状态”，不是将目标状态切换为 SYSTEM_STATE_UNKNOWN；SYSTEM_STATE_SWITCHING = 99 是状态机内部的切换中状态，能否作为外部请求目标仍以状态转换准入规则为准。

值	枚举常量	含义
`0`	`SYSTEM_STATE_UNKNOWN`（`/change_state` 中为保持当前主状态）	未知 / 保持当前主状态
`1`	`SYSTEM_STATE_HIBERNATE`	休眠
`2`	`SYSTEM_STATE_INITIALIZING`	初始化中
`3`	`SYSTEM_STATE_AUTOMATIC`	自动模式
`4`	`SYSTEM_STATE_MANUAL`	手动模式
`5`	`SYSTEM_STATE_FAULT`	故障
`6`	`SYSTEM_STATE_MAINTENANCE`	维护模式
`7`	`SYSTEM_STATE_EMERGENCY_STOP`	急停
`99`	`SYSTEM_STATE_SWITCHING`	切换中

1.2.2.1.3. `target_sub_state` 取值范围

target_sub_state 必须按目标主状态所属的枚举组解释；相同数值在不同主状态下含义不同。0 表示对应主状态下的 IDLE。当前 Schema 仅为 AUTOMATIC、MANUAL、MAINTENANCE 和 EMERGENCY_STOP 声明了专用子状态。

目标主状态	值	枚举常量	含义
`AUTOMATIC (3)`	`0`	`AUTO_SUB_IDLE`	空闲
`AUTOMATIC (3)`	`1`	`AUTO_SUB_BUSY`	忙碌
`AUTOMATIC (3)`	`2`	`AUTO_SUB_OTA`	OTA
`AUTOMATIC (3)`	`3`	`AUTO_SUB_AUTO_CHARGING`	自动充电
`AUTOMATIC (3)`	`4`	`AUTO_SUB_PLUGIN_CHARGING`	插件充电
`AUTOMATIC (3)`	`5`	`AUTO_SUB_TELEOP`	遥操作
`AUTOMATIC (3)`	`6`	`AUTO_SUB_MODEL_INFER`	模型推理
`AUTOMATIC (3)`	`7`	`AUTO_SUB_MOTION_CTL`	运动控制
`MANUAL (4)`	`0`	`MANUAL_SUB_IDLE`	空闲
`MANUAL (4)`	`1`	`MANUAL_SUB_MANUAL_CONTROL`	手动控制
`MANUAL (4)`	`2`	`MANUAL_SUB_FOLLOW_CONTROL`	随动控制
`MANUAL (4)`	`3`	`MANUAL_SUB_MANUAL_NAVI`	手动导航
`MANUAL (4)`	`4`	`MANUAL_SUB_MANUAL_TELEOP`	手动遥操作
`MANUAL (4)`	`5`	`MANUAL_SUB_PLUGIN_CHARGING`	插件充电
`MANUAL (4)`	`6`	`MANUAL_SUB_MAPPING`	建图
`MAINTENANCE (6)`	`0`	`MAINTENANCE_SUB_IDLE`	空闲待命
`MAINTENANCE (6)`	`1`	`MAINTENANCE_SUB_FOLLOW_CONTROL`	随动模式（手推）
`MAINTENANCE (6)`	`2`	`MAINTENANCE_SUB_MANUAL_CONTROL`	遥控模式
`MAINTENANCE (6)`	`3`	`MAINTENANCE_SUB_SSH`	SSH 运维模式
`EMERGENCY_STOP (7)`	`0`	`ESTOP_SUB_IDLE`	默认 / 占位
`EMERGENCY_STOP (7)`	`1`	`ESTOP_SUB_TRIGGERED`	急停触发（硬件或软件）
`EMERGENCY_STOP (7)`	`2`	`ESTOP_SUB_RELEASED`	急停释放（等待恢复指令）

语义说明：target_main_state 为目标主状态，0表示保持当前主状态；target_sub_state 为目标子状态，0表示IDLE。trigger 为空时默认为 hmi_request；Schema 还声明 api_request、double_click、triple_click。响应 success、error_code、message 表示操作结果及失败原因，current_main_state/current_sub_state 为转换后的实际状态。状态枚举可结合本页 SystemState 阅读。待维护者补充：状态转换准入条件、合法主子状态组合与错误码表。

1.2.2.2. /get_sm_state

{
  "get_sm_state_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false,
      "default_timeout_ms": 2000
    },
    "ros2": {
      "service_prefix": "/",
      "service_type": "state_machine_msgs/srv/GetSMState"
    }
  }
}

1.2.2.2.1. 类型 Schema

类型：state_machine_msgs/srv/GetSMState

来源：RTypes develop：ros2_types/state_machine_msgs/srv/GetSMState.srv

###############################################################################
# Copyright (c) 2026 RobbyAnt. All rights reserved.
#
# GetSMState.srv
# Service: /get_sm_state
# Description: 获取当前状态机系统状态
#
# Author: qiaosou
# Version: 1.0.0
# Last Update: 2026-04-7
###############################################################################

# ============ Empty Request ============ 

---

# ============ Response ============ 
# 系统状态， 和/system_state发布的topic内容一样
SystemState state

1.2.2.2.2. 间接依赖类型 Schema：SystemState

类型：state_machine_msgs/msg/SystemState

来源：RTypes develop：ros2_types/state_machine_msgs/msg/SystemState.msg

###############################################################################
# Copyright (c) 2026 RobbyAnt. All rights reserved.
#
# SystemState.msg
# Topic: /system_state
# Description: 系统状态发布消息
#
# Author: jinlong
# Version: 1.0.0
# Last Update: 2026-03-17
###############################################################################

# ============ 主状态枚举 ============
uint8 SYSTEM_STATE_UNKNOWN = 0
uint8 SYSTEM_STATE_HIBERNATE = 1
uint8 SYSTEM_STATE_INITIALIZING = 2
uint8 SYSTEM_STATE_AUTOMATIC = 3
uint8 SYSTEM_STATE_MANUAL = 4
uint8 SYSTEM_STATE_FAULT = 5
uint8 SYSTEM_STATE_MAINTENANCE = 6
uint8 SYSTEM_STATE_EMERGENCY_STOP = 7
uint8 SYSTEM_STATE_SWITCHING = 99

# ============ AUTOMATIC子状态枚举 ============
uint8 AUTO_SUB_IDLE = 0
uint8 AUTO_SUB_BUSY = 1
uint8 AUTO_SUB_OTA = 2
uint8 AUTO_SUB_AUTO_CHARGING = 3
uint8 AUTO_SUB_PLUGIN_CHARGING = 4
uint8 AUTO_SUB_TELEOP = 5
uint8 AUTO_SUB_MODEL_INFER = 6
uint8 AUTO_SUB_MOTION_CTL = 7

# ============ MANUAL子状态枚举 ============
uint8 MANUAL_SUB_IDLE = 0
uint8 MANUAL_SUB_MANUAL_CONTROL = 1
uint8 MANUAL_SUB_FOLLOW_CONTROL = 2
uint8 MANUAL_SUB_MANUAL_NAVI = 3
uint8 MANUAL_SUB_MANUAL_TELEOP = 4
uint8 MANUAL_SUB_PLUGIN_CHARGING = 5
uint8 MANUAL_SUB_MAPPING = 6

# ============ MAINTENANCE子状态枚举 ============
uint8 MAINTENANCE_SUB_IDLE = 0             # 空闲待命
uint8 MAINTENANCE_SUB_FOLLOW_CONTROL = 1   # 随动模式（手推）
uint8 MAINTENANCE_SUB_MANUAL_CONTROL = 2   # 遥控模式
uint8 MAINTENANCE_SUB_SSH = 3               # SSH运维模式

# ============ EMERGENCY_STOP子状态枚举 ============
uint8 ESTOP_SUB_IDLE = 0             # 默认/占位
uint8 ESTOP_SUB_TRIGGERED = 1        # 急停触发（硬件或软件）
uint8 ESTOP_SUB_RELEASED = 2        # 急停释放（等待恢复指令）




# ============ 消息主体 ============
std_msgs/Header header

uint8 current_main_state         # 当前主状态
uint8 current_sub_state          # 当前子状态
uint8 previous_main_state        # 前一主状态
uint8 previous_sub_state         # 前一子状态
uint8 target_main_state          # 目标主状态 (SWITCHING 过渡使用)
uint8 target_sub_state           # 目标子状态 (SWITCHING 过渡使用)

builtin_interfaces/Time state_start_time   # 切换到该状态的时间
string reason                    # 切换原因描述

语义说明：请求为空；返回 state，内容与 /system_state 发布的 SystemState 相同。current_、previous_ 分别表示当前和前一主/子状态，target_* 用于SWITCHING过渡，state_start_time 为切换到该状态的时间，reason 为切换原因。主状态包含未知、休眠、初始化、自动、手动、故障、维护、急停及切换中；子状态应按对应主状态的常量分组解释，不能跨分组仅凭数值比较。待维护者补充：合法主子状态组合、转换条件及 header 时间约定。

1. 状态信息接口清单​

1.1. 接口概览表​

1.1.1. 订阅 topic（2）​

1.1.2. service（2）​

1.2. 附录：JSON 配置​

1.2.1. 订阅 topic（2）​

1.2.1.1. /battery_state​

1.2.1.1.1. 类型 Schema​

1.2.1.2. /diagnostic​

1.2.1.2.1. 类型 Schema​

1.2.1.2.2. 间接依赖类型 Schema：ErrorInfo​

1.2.2. service（2）​

1.2.2.1. /change_state​

1.2.2.1.1. 类型 Schema​

1.2.2.1.2. target_main_state 取值范围​

1.2.2.1.3. target_sub_state 取值范围​

1.2.2.2. /get_sm_state​

1.2.2.2.1. 类型 Schema​

1.2.2.2.2. 间接依赖类型 Schema：SystemState​