Core Function Interfaces

1. State Information Interfaces

Scope: Four state-information interfaces used by the WS bridge. Battery information is included in state information. For navigation, see Navigation Interfaces.

Topics use HYBRID Channels; Services use hybrid_rpc Channels. Overview links lead to the corresponding JSON configuration.

1.1. Interface overview

1.1.1. Subscribed topics (2)

Topic	Description	Type	Transport	Configuration notes	Details
`/battery_state`	Battery charge, charging/discharging status, health, voltage/current, temperature, and cell data	`sensor_msgs/msg/BatteryState`	Hybrid.ros2 (subscription)	auto_route=false; QoS best_effort	JSON / Schema
`/diagnostic`	Highest robot fault severity and individual fault codes, sources, descriptions, and occurrence times	`rdiagnostic_msgs/msg/HealthState`	Hybrid.ros2 (subscription)	auto_route=false; QoS best_effort + keep_last(5)	JSON / Schema

1.1.2. service（2）

Service	Description	service_type	Invocation method	Configuration notes	Details
`/change_state`	Request a main/substate change; returns result, errors, and actual state	`state_machine_msgs/srv/ChangeState`	`change_state`	auto_route=false; timeout 2000ms	JSON / Schema
`/get_sm_state`	Query current, previous, and target main/substates, state start time, and transition reason	`state_machine_msgs/srv/GetSMState`	`get_sm_state`	auto_route=false; timeout 2000ms	JSON / Schema

1.2. Appendix: JSON configuration

Each configuration corresponds to an overview row; its key is the instance name.

1.2.1. Subscribed topics (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. Type Schema

Type: sensor_msgs/msg/BatteryState

Source: ROS 2 Humble standard module sensor_msgs (declared as an RTypes dependency)

# 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

Semantics: voltage is in V, temperature in °C, and current in A (negative when discharging). charge, capacity, and design_capacity are in Ah and represent current charge, last full-charge capacity, and design capacity. percentage is a ratio from 0 to 1. Use NaN for unmeasured floating-point fields as specified in comments; when cell count is known but values are unknown, use NaN for those array elements. power_supply_status indicates unknown, charging, discharging, not charging, or full. health and technology use their respective health and chemistry constants. present indicates battery presence; location and serial_number identify installation location and serial number. Maintainers still need to specify fields actually supplied by this device and sampling-time conventions.

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. Type Schema

Type: rdiagnostic_msgs/msg/HealthState

Source: RTypes develop: ros2_types/rdiagnostic_msgs/msg/HealthState.msg

###############################################################################
# Copyright (c) 2025 RobbyAnt. All rights reserved. 
#
# HealthState.msg
# Topic: /diagnostic
# Description: Robot health status
#
# Author: qiaosou.wxt
# Version: 1.0.0
# Last Update: 2025-12-12
###############################################################################

# Current highest fault severity, for a quick health assessment
# Values are defined in ErrorInfo.msg
uint8 severity_level

# Fault information list
rdiagnostic_msgs/ErrorInfo[] errors

1.2.1.2.2. Indirect dependency Schema: ErrorInfo

Type: rdiagnostic_msgs/msg/ErrorInfo

Source: RTypes develop: ros2_types/rdiagnostic_msgs/msg/ErrorInfo.msg

###############################################################################
# Copyright (c) 2025 RobbyAnt. All rights reserved. 
#
# ErrorInfo.msg
#
# Base data structure describing a fault
#
# Author: qiaosou.wxt
# Version: 1.0.0
# Last Update: 2025-12-19
###############################################################################

# Original fault code
uint32 code

# Fault module ID; may be empty
string module_id

# Fault description
string message

# Fault occurrence time: system timestamp in milliseconds
uint64 occurrence_time_ms

# Nexus ID of the reporting process
uint8 source_id

# Severity parsed from code
uint8 severity_level

# User/operator-facing fault description code, generated from code and module_id
string code_str

uint8 SEVERITY_LEVEL_NONE = 0 # No fault
uint8 SEVERITY_LEVEL_INFO = 1 # Information
uint8 SEVERITY_LEVEL_WARN = 2 # Warning
uint8 SEVERITY_LEVEL_ERROR = 4 # Error
uint8 SEVERITY_LEVEL_FATAL = 8 # Fatal error

Semantics: HealthState.severity_level is the highest current severity; errors is a list of ErrorInfo records. Levels are 0 none, 1 information, 2 warning, 4 error, and 8 fatal. ErrorInfo.code is the original fault code; module_id may be empty; message describes the fault; occurrence_time_ms is a system timestamp in milliseconds; source_id is the reporting process's Nexus ID. severity_level is parsed from code, and code_str is generated from code and module_id for users and operators. Maintainers still need to specify the original code encoding and how the list updates after faults disappear.

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. Type Schema

Type: state_machine_msgs/srv/ChangeState

Source: RTypes develop: ros2_types/state_machine_msgs/srv/ChangeState.srv

###############################################################################
# Copyright (c) 2026 RobbyAnt. All rights reserved.
#
# ChangeState.srv
# Service: /change_state
# Description: Request a state transition
#
# 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          # Target main state (0 keeps the current main state)
uint8 target_sub_state           # Target substate (0 means IDLE)
string trigger                   # Trigger type (empty defaults to hmi_request)

---

# ============ Response ============
bool success                     # Whether the operation succeeded

uint16 error_code                # Structured error code

string message                   # Result description; failure reason on error

uint8 current_main_state          # Actual main state after the transition

uint8 current_sub_state           # Actual substate after the transition

1.2.2.1.2. `target_main_state` values

These values reuse the SystemState main-state enumeration. In /change_state requests, target_main_state = 0 means keep the current main state, not transition to SYSTEM_STATE_UNKNOWN. SYSTEM_STATE_SWITCHING = 99 is an internal transitional state; whether external requests can target it depends on transition admission rules.

Value	Enumeration constant	Meaning
`0`	`SYSTEM_STATE_UNKNOWN` (keep the current main state in `/change_state`)	Unknown / keep current main state
`1`	`SYSTEM_STATE_HIBERNATE`	Hibernate
`2`	`SYSTEM_STATE_INITIALIZING`	Initializing
`3`	`SYSTEM_STATE_AUTOMATIC`	Automatic mode
`4`	`SYSTEM_STATE_MANUAL`	Manual mode
`5`	`SYSTEM_STATE_FAULT`	Fault
`6`	`SYSTEM_STATE_MAINTENANCE`	Maintenance mode
`7`	`SYSTEM_STATE_EMERGENCY_STOP`	Emergency stop
`99`	`SYSTEM_STATE_SWITCHING`	Transitioning

1.2.2.1.3. `target_sub_state` values

Interpret target_sub_state using the enumeration group of its target main state. The same number can mean different things under different main states. 0 denotes that main state's IDLE. The current Schema defines dedicated substates only for AUTOMATIC, MANUAL, MAINTENANCE, and EMERGENCY_STOP.

Target main state	Value	Enumeration constant	Meaning
`AUTOMATIC (3)`	`0`	`AUTO_SUB_IDLE`	Idle
`AUTOMATIC (3)`	`1`	`AUTO_SUB_BUSY`	Busy
`AUTOMATIC (3)`	`2`	`AUTO_SUB_OTA`	OTA
`AUTOMATIC (3)`	`3`	`AUTO_SUB_AUTO_CHARGING`	Automatic charging
`AUTOMATIC (3)`	`4`	`AUTO_SUB_PLUGIN_CHARGING`	Plug-in charging
`AUTOMATIC (3)`	`5`	`AUTO_SUB_TELEOP`	Teleoperation
`AUTOMATIC (3)`	`6`	`AUTO_SUB_MODEL_INFER`	Model inference
`AUTOMATIC (3)`	`7`	`AUTO_SUB_MOTION_CTL`	Motion control
`MANUAL (4)`	`0`	`MANUAL_SUB_IDLE`	Idle
`MANUAL (4)`	`1`	`MANUAL_SUB_MANUAL_CONTROL`	Manual control
`MANUAL (4)`	`2`	`MANUAL_SUB_FOLLOW_CONTROL`	Follow control
`MANUAL (4)`	`3`	`MANUAL_SUB_MANUAL_NAVI`	Manual navigation
`MANUAL (4)`	`4`	`MANUAL_SUB_MANUAL_TELEOP`	Manual teleoperation
`MANUAL (4)`	`5`	`MANUAL_SUB_PLUGIN_CHARGING`	Plug-in charging
`MANUAL (4)`	`6`	`MANUAL_SUB_MAPPING`	Mapping
`MAINTENANCE (6)`	`0`	`MAINTENANCE_SUB_IDLE`	Idle / standby
`MAINTENANCE (6)`	`1`	`MAINTENANCE_SUB_FOLLOW_CONTROL`	Follow mode (hand-guiding)
`MAINTENANCE (6)`	`2`	`MAINTENANCE_SUB_MANUAL_CONTROL`	Remote-control mode
`MAINTENANCE (6)`	`3`	`MAINTENANCE_SUB_SSH`	SSH maintenance mode
`EMERGENCY_STOP (7)`	`0`	`ESTOP_SUB_IDLE`	Default / placeholder
`EMERGENCY_STOP (7)`	`1`	`ESTOP_SUB_TRIGGERED`	Emergency stop triggered (hardware or software)
`EMERGENCY_STOP (7)`	`2`	`ESTOP_SUB_RELEASED`	Emergency stop released (awaiting recovery command)

Semantics: target_main_state is the target main state; 0 keeps the current main state. target_sub_state is the target substate; 0 means IDLE. An empty trigger defaults to hmi_request; the Schema also declares api_request, double_click, and triple_click. Response success, error_code, and message describe the result or failure; current_main_state/current_sub_state are the actual resulting states. See SystemState below for enumerations. Maintainers still need to specify transition admission conditions, valid main/substate combinations, and error codes.

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. Type Schema

Type: state_machine_msgs/srv/GetSMState

Source: RTypes develop: ros2_types/state_machine_msgs/srv/GetSMState.srv

###############################################################################
# Copyright (c) 2026 RobbyAnt. All rights reserved.
#
# GetSMState.srv
# Service: /get_sm_state
# Description: Query the current state-machine system state
#
# Author: qiaosou
# Version: 1.0.0
# Last Update: 2026-04-7
###############################################################################

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

---

# ============ Response ============ 
# System state; same content as the /system_state topic
SystemState state

1.2.2.2.2. Indirect dependency Schema: SystemState

Type: state_machine_msgs/msg/SystemState

Source: RTypes develop: ros2_types/state_machine_msgs/msg/SystemState.msg

###############################################################################
# Copyright (c) 2026 RobbyAnt. All rights reserved.
#
# SystemState.msg
# Topic: /system_state
# Description: System state publication message
#
# Author: jinlong
# Version: 1.0.0
# Last Update: 2026-03-17
###############################################################################

# ============ Main-state enumeration ============
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 substate enumeration ============
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 substate enumeration ============
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 substate enumeration ============
uint8 MAINTENANCE_SUB_IDLE = 0             # Idle / standby
uint8 MAINTENANCE_SUB_FOLLOW_CONTROL = 1   # Follow mode (hand-guiding)
uint8 MAINTENANCE_SUB_MANUAL_CONTROL = 2   # Remote-control mode
uint8 MAINTENANCE_SUB_SSH = 3               # SSH maintenance mode

# ============ EMERGENCY_STOP substate enumeration ============
uint8 ESTOP_SUB_IDLE = 0             # Default / placeholder
uint8 ESTOP_SUB_TRIGGERED = 1        # Emergency stop triggered (hardware or software)
uint8 ESTOP_SUB_RELEASED = 2        # Emergency stop released (awaiting recovery command)




# ============ Message body ============
std_msgs/Header header

uint8 current_main_state         # Current main state
uint8 current_sub_state          # Current substate
uint8 previous_main_state        # Previous main state
uint8 previous_sub_state         # Previous substate
uint8 target_main_state          # Target main state (during SWITCHING)
uint8 target_sub_state           # Target substate (during SWITCHING)

builtin_interfaces/Time state_start_time   # Time of transition into this state
string reason                    # Transition reason

Semantics: The request is empty. The returned state has the same content as SystemState on /system_state. current_* and previous_* identify current and previous main/substates; target_* is used during SWITCHING. state_start_time is when the state was entered; reason describes why. Main states include unknown, hibernate, initializing, automatic, manual, fault, maintenance, emergency stop, and transitioning. Interpret substates within their main-state constant group; do not compare numbers across groups alone. Maintainers still need to specify valid main/substate combinations, transition conditions, and header timestamp conventions.

1. State Information Interfaces​

1.1. Interface overview​

1.1.1. Subscribed topics (2)​

1.1.2. service（2）​

1.2. Appendix: JSON configuration​

1.2.1. Subscribed topics (2)​

1.2.1.1. /battery_state​

1.2.1.1.1. Type Schema​

1.2.1.2. /diagnostic​

1.2.1.2.1. Type Schema​

1.2.1.2.2. Indirect dependency Schema: ErrorInfo​

1.2.2. service（2）​

1.2.2.1. /change_state​

1.2.2.1.1. Type Schema​

1.2.2.1.2. target_main_state values​

1.2.2.1.3. target_sub_state values​

1.2.2.2. /get_sm_state​

1.2.2.2.1. Type Schema​

1.2.2.2.2. Indirect dependency Schema: SystemState​