运动控制

本模块提供机器人运动控制相关的所有功能,包括站立、躺下、姿态控制、电池状态查询等。

核心功能

站立与躺下

stand_up(timeout=30)

Make the robot stand up.

This function intelligently checks the current robot state before sending commands. - If already standing: returns success immediately without sending command - If currently standing up: returns failure (wait for completion) - If lying down: sends stand up command

Parameters:

timeout (int) – Timeout in seconds for the service call (default: 5)

Returns:

Response containing state and result

state.code: StateCode (0=success, 1=fail, etc.)
state.describe: Description of the result
response.result: Boolean indicating if command executed successfully

Return type:

StandUpResponse

Examples:

# Make the robot stand up
result = stand_up()
if result.response.result:
    print("Robot stood up successfully")
else:
    print(f"Failed: {result.state.describe}")

# Stand up with custom timeout
result = stand_up(timeout=10)
if result.response.result:
    print("Robot is now standing")

Note

The robot driver must be enabled before calling this function

底层 ROS2 接口

通道一（下发站立指令）：

类型: Service /nav/robot_command——消息类型随 Unimotion 固件版本而异：新固件 saturn_msgs/srv/RobotCommand，旧固件 ysc_robot_msgs/srv/RobotCommand； SDK 双 client 就绪探测自动选路
名称: /nav/robot_command
参数映射:

封装参数	原生字段（Request）
（固定值）	`comamnd_name="StandUp"`（新固件显式站立；旧固件回退发 `"StandUpDown"`，由通道二状态预检保证显式语义。该 .srv 字段名原文如此拼写）
`timeout`	客户端等待时长，不下发

通道二（下发前的状态预检，读订阅缓存）：

类型: Topic 订阅缓存 std_msgs/msg/UInt32
名称: /nav/robot_state
说明: 若缓存显示已站立则直接返回成功、正在站立中则返回失败，均不下发服务请求。

lie_down(timeout=30)

Make the robot lie down.

This function intelligently checks the current robot state before sending commands. - If already lying down: returns success immediately without sending command - If currently standing up: returns failure (cannot interrupt) - If standing: sends lie down command

Parameters:

timeout (int) – Timeout in seconds for the service call (default: 5)

Returns:

Response containing state and result

state.code: StateCode (0=success, 1=fail, etc.)
state.describe: Description of the result
response.result: Boolean indicating if command executed successfully

Return type:

LieDownResponse

Examples:

# Make the robot lie down
result = lie_down()
if result.response.result:
    print("Robot is now lying down")
else:
    print(f"Failed: {result.state.describe}")

# Lie down with custom timeout
result = lie_down(timeout=10)
if result.response.result:
    print("Robot successfully lying down")

Note

The robot driver must be enabled before calling this function

底层 ROS2 接口

通道一（下发趴下指令）：

类型: Service /nav/robot_command——消息类型随 Unimotion 固件版本而异：新固件 saturn_msgs/srv/RobotCommand，旧固件 ysc_robot_msgs/srv/RobotCommand； SDK 双 client 就绪探测自动选路
名称: /nav/robot_command
参数映射:

封装参数	原生字段（Request）
（固定值）	`comamnd_name="LieDown"`（新固件显式趴下；旧固件回退发 `"StandUpDown"`，由通道二状态预检保证显式语义。该 .srv 字段名原文如此拼写）
`timeout`	客户端等待时长，不下发

通道二（下发前的状态预检，读订阅缓存）：

类型: Topic 订阅缓存 std_msgs/msg/UInt32
名称: /nav/robot_state
说明: 若缓存显示已趴下则直接返回成功、正在站立中则返回失败，均不下发服务请求。

get_robot_state()

Get the current robot posture state.

This function returns the robot’s current state with automatic data validation. If the state data is stale or not available, it returns UNKNOWN_STATE.

Returns:

Response containing state and robot_state

state: State object with code and describe
robot_state:bv RobotState enum value
- RobotState.LIE_DOWN (0): Lying down
- RobotState.STANDING_UP (1): Currently standing up (in transition)
- RobotState.STAND_UP (2): Standing
- RobotState.UNKNOWN_STATE (7): Unknown/No state (data unavailable or stale)

Return type:

GetRobotStateResponse

Examples:

# Get robot state
response = get_robot_state()

# Check if successful
if response.state.code == 0:  # StateCode.success
    if response.robot_state == RobotState.STAND_UP:
        print("Robot is standing")
    elif response.robot_state == RobotState.LIE_DOWN:
        print("Robot is lying down")
    elif response.robot_state == RobotState.UNKNOWN_STATE:
        print("Robot state unknown (data unavailable)")

# Simple usage
state = get_robot_state().robot_state
if state == RobotState.STAND_UP:
    print("Standing")

# Get integer value if needed
state_value = int(get_robot_state().robot_state)
print(f"State value: {state_value}")

Note

Data from /nav/robot_state topic subscription (5 second timeout)
Returns UNKNOWN_STATE if data is stale or not yet received
Data validation is performed automatically
stand_up() and lie_down() functions also use this validation internally

底层 ROS2 接口

类型: Topic 订阅缓存 std_msgs/msg/UInt32
名称: /nav/robot_state
说明: 无入参；读取订阅缓存（5 秒时效），数据陈旧或未收到时返回 UNKNOWN_STATE。

身体控制

adjust_body_height(percent, timeout=5)

Adjust the robot body height.

Parameters:

percent (int) – Height percentage (20-50)
timeout (int) – Timeout in seconds for the service call (default: 5)

Returns:

Response containing state and result

state.code: StateCode (0=success, 1=fail, etc.)
state.describe: Description of the result
response.result: Boolean indicating if command executed successfully

Return type:

RobotCommandResponse

Examples:

# Adjust height to 30%
result = adjust_body_height(30)
if result.response.result:
    print("Height adjusted successfully")

Note

Valid height range is 20-50
Robot must be standing to adjust height
percent 仅在客户端做范围校验（20-50），不会下发到底层服务—— 底层 `/nav/robot_command`（RobotCommand.srv）请求只有命令字字段，实际发送固定命令 “BodyHeight”，具体目标高度由底层自行决定

底层 ROS2 接口

类型: Service ysc_robot_msgs/srv/RobotCommand
名称: /nav/robot_command
参数映射:

封装参数	原生字段（Request）
（固定值）	`comamnd_name="BodyHeight"`（该 .srv 字段名原文如此拼写）
`percent`	不下发——Request 仅有 `comamnd_name` 一个字段，无数值通道；`percent` 仅在客户端做范围校验（20–50），高度数值不会传给底层
`timeout`	客户端等待时长，不下发

set_gait(*args, **kwds): Helper for @overload to raise when called.

底层 ROS2 接口

类型: Service /nav/robot_command——消息类型随 Unimotion 固件版本而异：新固件 saturn_msgs/srv/RobotCommand，旧固件 ysc_robot_msgs/srv/RobotCommand； SDK 双 client 就绪探测自动选路
名称: /nav/robot_command
参数映射:

封装参数	原生字段（Request）
`gait_type`	`comamnd_name`（枚举版按枚举映射命令字，见下表；字符串版命令字直接透传。该 .srv 字段名原文如此拼写）
`timeout`	客户端等待时长，不下发

gait_type → comamnd_name 映射（枚举版）：

GaitType 枚举值	`comamnd_name`
`TROT`	`"OrdinaryGait"`
`NORMAL_STAIR`	`"StairsGait"`
`SLOPE`	`"SlopeGait"`
`SENSE_STAIR`	`"VstairsGait"`
`POSE_ADJUST`	`"PoseAdjustGait"`
`CAR_MODE`	`"CarModeGait"`
`RL_TROT`	`"RLOrdinaryGait"`
`RL_MOUNTAIN`	`"RLMountainGait"`

字符串版（推荐新步态值使用）：命令字直接透传，客户端不做机型/值域白名单，由服务端判定当前机型支持与否（不支持返回失败）。已知命令字还包括 "HighStepGait"（高台步态，M20）——后续上游新增命令字无需改 SDK。

get_gait()

Get the current robot gait type.

This function returns the robot’s current gait type with automatic data validation. If the gait data is stale or not available, it returns UNKNOWN_GAIT.

Returns:

Response containing state and gait_type

state: State object with code and describe
gait_type: GaitType enum value
- GaitType.TROT (0): Trot gait
- GaitType.NORMAL_STAIR (1): Normal stair gait
- GaitType.SLOPE (2): Slope stair gait
- GaitType.SENSE_STAIR (6): Sense stair gait
- GaitType.POSE_ADJUST (13): Pose adjust gait
- GaitType.CAR_MODE (14): Pose adjust gait
- GaitType.RL_TROT (0x20): RL trot gait
- GaitType.RL_Mountain (0x21): RL mountain gait
- GaitType.UNKNOWN_GAIT (99): Unknown (data unavailable or stale)

Return type:

GetGaitResponse

Examples:

# Get gait type
response = get_gait()
if response.state.code == 0:  # StateCode.success
    if response.gait_type == GaitType.NORMAL_STAIR:
        print("Stair gait active")
    elif response.gait_type == GaitType.TROT:
        print("Trot gait active")

Note

Data from /gait topic subscription (5 second timeout)
Returns UNKNOWN_GAIT if data is stale or not yet received

底层 ROS2 接口

类型: Topic 订阅缓存 std_msgs/msg/UInt8
名称: /nav/gait
说明: 无入参；读取订阅缓存（5 秒时效），数据陈旧或未收到时返回 UNKNOWN_GAIT。

控制模式

set_control_mode(mode, timeout=5)

Set the robot control mode.

Parameters:

mode (ControlMode) – Control mode enum - ControlMode.JOY_MODE (0): Joystick/manual control mode - ControlMode.NAV_MODE (1): Navigation/automatic control mode
timeout (int) – Timeout in seconds for the service call (default: 5)

Returns:

Response containing state and result

state.code: StateCode (0=success, 1=fail, etc.)
state.describe: Description of the result
response.result: Boolean indicating if command executed successfully

Return type:

RobotCommandResponse

Examples:

# Set to navigation mode
result = set_control_mode(ControlMode.NAV_MODE)
if result.response.result:
    print("Control mode set to navigation")

# Set to joystick mode
result = set_control_mode(ControlMode.JOY_MODE)

Note

Switches between manual and automatic control

底层 ROS2 接口

类型: Service ysc_robot_msgs/srv/RobotCommand
名称: /nav/robot_command
参数映射:

封装参数	原生字段（Request）
`mode`	`comamnd_name`（`NAV_MODE` → `"EnableNavigation"`，`JOY_MODE` → `"EnableTeleoption"`；该 .srv 字段名原文如此拼写）
`timeout`	客户端等待时长，不下发

get_control_mode()

Get the current robot control mode.

This function returns the robot’s current control mode with automatic data validation. If the control mode data is stale or not available, it returns UNKNOWN_MODE.

Returns:

Response containing state and control_mode

state: State object with code and describe
control_mode: ControlMode enum value
- ControlMode.JOY_MODE (0): Joystick/manual control
- ControlMode.NAV_MODE (1): Navigation/automatic control
- ControlMode.UNKNOWN_MODE (99): Unknown (data unavailable or stale)

Return type:

GetControlModeResponse

Examples:

# Get control mode
response = get_control_mode()
if response.state.code == 0:  # StateCode.success
    if response.control_mode == ControlMode.NAV_MODE:
        print("Navigation mode active")
    elif response.control_mode == ControlMode.JOY_MODE:
        print("Joystick mode active")

Note

Data from /nav/control_mode topic subscription (5 second timeout)
Returns UNKNOWN_MODE if data is stale or not yet received

底层 ROS2 接口

类型: Topic 订阅缓存 std_msgs/msg/UInt8
名称: /nav/control_mode
说明: 无入参；读取订阅缓存（5 秒时效），数据陈旧或未收到时返回 UNKNOWN_MODE。

充电功能

go_to_dock(timeout=60)

Command the robot to go to the charging dock.

Parameters:

timeout (int) – Timeout in seconds for the service call (default: 30)

Returns:

Response containing state and result

state.code: StateCode (0=success, 1=fail, etc.)
state.describe: Description of the result
response.result: Boolean indicating if command executed successfully

Return type:

GoToDockResponse

Examples:

# Command robot to go to dock
result = go_to_dock()
if result.response.result:
    print("Robot is going to dock")
else:
    print(f"Failed: {result.state.describe}")

# With custom timeout
result = go_to_dock(timeout=60)

Note

Uses ‘/nav/robot_command’ service with ‘GoToDock’ command
Robot must be in proper state to execute this command

底层 ROS2 接口

类型: Service ysc_robot_msgs/srv/RobotCommand
名称: /nav/robot_command
参数映射:

封装参数	原生字段（Request）
（固定值）	`comamnd_name="GoToDock"`（该 .srv 字段名原文如此拼写）
`timeout`	客户端等待时长，不下发

leave_dock(timeout=60)

Command the robot to leave the charging dock.

Parameters:

timeout (int) – Timeout in seconds for the service call (default: 30)

Returns:

Response containing state and result

state.code: StateCode (0=success, 1=fail, etc.)
state.describe: Description of the result
response.result: Boolean indicating if command executed successfully

Return type:

LeaveDockResponse

Examples:

# Command robot to leave dock
result = leave_dock()
if result.response.result:
    print("Robot is leaving dock")
else:
    print(f"Failed: {result.state.describe}")

# With custom timeout
result = leave_dock(timeout=60)

Note

Uses ‘/nav/robot_command’ service with ‘LeaveDock’ command
Robot must be on the dock to execute this command

底层 ROS2 接口

类型: Service ysc_robot_msgs/srv/RobotCommand
名称: /nav/robot_command
参数映射:

封装参数	原生字段（Request）
（固定值）	`comamnd_name="LeaveDock"`（该 .srv 字段名原文如此拼写）
`timeout`	客户端等待时长，不下发

get_dock_state()

Get the current charging dock state.

This function returns the robot’s current dock state with automatic data validation. If the dock state data is stale or not available, it returns UNKNOWN_DOCK.

Returns:

Response containing state and dock_state

state: State object with code and describe
dock_state: DockState enum value
- DockState.IDLE (0): Idle
- DockState.GOING_TO_DOCK (1): Going to dock
- DockState.STAND_ABOVE_DOCK (2): Standing above dock
- DockState.ADJUST_POSE (3): Adjusting pose
- DockState.LIE_ON_DOCKER (4): Lying on dock
- DockState.STANDING_AFTER_CHARGING (5): Standing after charging
- DockState.LEAVING_DOCK (6): Leaving dock
- DockState.LEAVE_DOCK (7): Left dock
- DockState.UNKNOWN_DOCK (99): Unknown (data unavailable or stale)

Return type:

GetDockStateResponse

Examples:

# Get dock state
response = get_dock_state()
if response.state.code == 0:  # StateCode.success
    if response.dock_state == DockState.LIE_ON_DOCKER:
        print("Robot is on dock and charging")
    elif response.dock_state == DockState.IDLE:
        print("Robot is idle")

Note

Data from /nav/dock_state topic subscription (5 second timeout)
Returns UNKNOWN_DOCK if data is stale or not yet received

底层 ROS2 接口

类型: Topic 订阅缓存 std_msgs/msg/UInt32
名称: /nav/dock_state
说明: 无入参；读取订阅缓存（5 秒时效），数据陈旧或未收到时返回 UNKNOWN_DOCK。

电池状态

get_battery_state()

Get the complete battery state information.

This function returns the robot’s complete battery state with automatic data validation. If the battery state data is stale or not available, is_valid will be false.

Returns:

Response containing state and battery information

state: State object with code and describe
is_valid: Boolean indicating if battery_state data is valid
- true: Data is valid and up-to-date
- false: Data is stale, unavailable, or module not initialized
battery_state: sensor_msgs/BatteryState with complete battery information
- percentage: Battery charge percentage (0.0-100.0)
- voltage: Voltage in Volts (V)
- current: Current in Amperes (A), negative indicates discharge
- temperature: Temperature in Celsius (degC)
- charge: Current charge in Amp-hours (Ah)
- capacity: Battery capacity in Amp-hours (Ah)
- power_supply_status: Charging status (0=UNKNOWN, 1=CHARGING, 2=DISCHARGING, 3=NOT_CHARGING, 4=FULL)
- power_supply_health: Battery health status
- power_supply_technology: Battery technology type
- present: Battery present (true/false)
- cell_voltage: Voltage of individual cells
- location: Battery location/identifier
- serial_number: Battery serial number

Return type:

GetBatteryStateResponse

Examples:

# Get complete battery state
response = get_battery_state()
if response.state.code == 0:  # StateCode.success
    if response.is_valid:
        battery = response.battery_state
        print(f"Battery level: {battery.percentage}%")
        print(f"Voltage: {battery.voltage}V")
        print(f"Current: {battery.current}A")
        print(f"Temperature: {battery.temperature}°C")

        # Check charging status
        if battery.power_supply_status == 1:  # CHARGING
            print("Battery is charging")
        elif battery.power_supply_status == 4:  # FULL
            print("Battery is full")
    else:
        print("Battery data is not valid or unavailable")

Note

Data from /nav/battery_state topic subscription (5 second timeout)
Always check is_valid before using battery_state data
When is_valid=false, battery_state will be an empty/default BatteryState message
Uses sensor_msgs/BatteryState message type

底层 ROS2 接口

类型: Topic 订阅缓存 sensor_msgs/msg/BatteryState
名称: /nav/battery_state
说明: 无入参；读取订阅缓存（5 秒时效），数据陈旧或未收到时 is_valid=False 且返回空 BatteryState。

is_charge()

Check if the robot is currently charging.

This function returns whether the robot is currently charging with automatic data validation. If the charge state data is stale or not available, it returns false.

Returns:

Response containing state and charging status

state: State object with code and describe
is_charging: Boolean indicating if robot is charging
- true: Robot is currently charging
- false: Robot is not charging (or data unavailable)

Return type:

IsChargeResponse

Examples:

# Check if charging
response = is_charge()
if response.state.code == 0:  # StateCode.success
    if response.is_charging:
        print("Robot is charging")
    else:
        print("Robot is not charging")

# Simple usage
if is_charge().is_charging:
    print("Charging in progress")

Note

Data from /nav/charge_state topic subscription (5 second timeout)
Returns is_charging = false if data is stale or not yet received
Uses std_msgs/Bool message type

底层 ROS2 接口

类型: Topic 订阅缓存 std_msgs/msg/Bool
名称: /nav/charge_state
说明: 无入参；读取订阅缓存（5 秒时效），数据陈旧或未收到时 is_charging 返回 False。

速度控制

send_cmd_vel(linear_x=0.0, linear_y=0.0, angular_z=0.0, dt=1.0, blocking=True)

Send velocity command to control robot motion via /cmd_vel topic (supports omnidirectional movement).

This function publishes Twist messages to control the robot’s linear velocities (forward/backward and left/right) and angular velocity. It supports both blocking and non-blocking modes.

Parameters:

linear_x (float) – Forward/backward linear velocity in m/s - Positive value: move forward - Negative value: move backward - Recommended ranges depend on gait and terrain (see Note below)
linear_y (float) – Left/right linear velocity in m/s (omnidirectional) - Positive value: move left - Negative value: move right - Recommended ranges depend on gait and terrain (see Note below)
angular_z (float) – Angular velocity in rad/s - Positive value: turn counter-clockwise (left) - Negative value: turn clockwise (right) - Recommended ranges depend on gait and terrain (see Note below)
dt (float) – Duration in seconds for the robot to move - Must be non-negative - dt > 0: Robot moves for this duration at 10Hz, then automatically stops - dt = 0: Publishes velocity command once only (no automatic stop)
blocking (bool) – Whether to block until motion completes (default: True) - True: Function blocks and waits until dt expires (if dt > 0) - False: Function returns immediately, motion continues in background

Returns:

Response containing state and success flag

state.code: StateCode (0=success, 1=fail, etc.)
state.describe: Description of the result
success: Boolean indicating if command was published successfully

Return type:

SendCmdVelResponse

Examples:

# Stop robot for 1 second (using all defaults: 0, 0, 0, 1.0, True)
result = send_cmd_vel()
if result.success:
    print("Robot stopped for 1 second")

# Move forward for 2 seconds (using keyword args)
result = send_cmd_vel(linear_x=0.2, dt=2.0)
if result.success:
    print("Robot moved forward and stopped")

# Move left (omnidirectional) for 1.5 seconds
result = send_cmd_vel(linear_y=0.3, dt=1.5)
if result.success:
    print("Robot moved left and stopped")

# Rotate in place for default 1 second
result = send_cmd_vel(angular_z=0.5)

# Turn left while moving forward
result = send_cmd_vel(linear_x=0.2, angular_z=0.3, dt=2.0)

# Move diagonally (forward + left)
result = send_cmd_vel(linear_x=0.2, linear_y=0.2, dt=2.0)

# Non-blocking mode - robot moves in background
result = send_cmd_vel(angular_z=0.2, blocking=False)
if result.success:
    print("Robot is turning in background for 1 second")
    # Next line executes immediately, robot continues turning
    do_other_work()  # Robot still turning while this executes

# Publish once without automatic stop (use with caution!)
result = send_cmd_vel(linear_x=0.1, dt=0.0)
if result.success:
    print("Command sent, robot will continue until stopped manually")
    # Must manually send stop command later: send_cmd_vel(dt=0.0) or send_cmd_vel()

Note

Recommended velocity ranges (depends on gait and terrain):

Regular gait:
- Flat ground: linear.x: [-1.0, 2.0] m/s, linear.y: [-0.4, 0.4] m/s, angular.z: [-0.8, 0.8] rad/s
- Slope: linear.x: [-0.8, 0.8] m/s, linear.y: [-0.4, 0.4] m/s, angular.z: [-0.6, 0.6] rad/s
RL gait (all terrains):
- linear.x: [-2.0, 2.0] m/s, linear.y: [-0.4, 0.4] m/s, angular.z: [-0.8, 0.8] rad/s

Important: - When dt > 0: Robot automatically stops after dt seconds (all axes: x, y, z) - When dt = 0: Robot continues moving until you send stop command (linear_x=0, linear_y=0, angular_z=0) - blocking=True: Python execution waits until motion completes - blocking=False: Python execution continues immediately, motion happens in background - Uses geometry_msgs/Twist message type - Publishes to /cmd_vel topic at 10Hz when dt > 0

底层 ROS2 接口

类型: Topic 发布 geometry_msgs/msg/Twist
名称: /nav/cmd_vel
参数映射:

封装参数	原生字段（Twist）
`linear_x`	`linear.x`（前后线速度，m/s）
`linear_y`	`linear.y`（左右线速度，m/s，全向）
`angular_z`	`angular.z`（角速度，rad/s）
（固定值）	`linear.z` / `angular.x` / `angular.y` 恒为 0
`dt`	客户端循环语义，不下发：`dt > 0` 时以 10Hz 循环发布同一 Twist 共 `dt` 秒，结束后补发一帧全零 Twist 刹停；`dt = 0` 时仅发布一帧且不自动刹停（需调用方另发零速）
`blocking`	客户端行为，不下发：`True` 在调用线程内循环发布至 `dt` 结束，`False` 交由后台线程循环、函数立即返回

驱动器与急停

driver_enable(enable=True, timeout=5)

使能或失能机器人驱动器。

向 /nav/sdk_command 服务发送 “EnableDriver”（使能）或 “DisableDriver”（失能）指令。

Parameters:

enable (bool) – True 使能驱动器，False 失能驱动器（默认: True）
timeout (int) – 服务调用超时秒数（默认: 5）

Returns:

指令响应

state: State 对象（code/describe）
response.result: bool，True 表示指令执行成功

Return type:

RobotCommandResponse

Examples:

# 使能驱动器
result = driver_enable(True)
if result.response.result:
    print("驱动器使能成功")

# 失能驱动器
result = driver_enable(False)
if result.response.result:
    print("驱动器失能成功")

Note

执行 stand_up / 运动等操作前必须先使能驱动器
通过 get_driver_state() 可查询当前驱动器状态

底层 ROS2 接口

类型: Service saturn_msgs/srv/RobotCommand
名称: /nav/sdk_command
参数映射:

封装参数	原生字段（Request）
`enable`	`comamnd_name`（`True` → `"EnableDriver"`，`False` → `"DisableDriver"`；该 .srv 字段名原文如此拼写）
`timeout`	客户端等待时长，不下发

emergency_stop(timeout=5)

触发软件急停，机器人立即停止运动。

向 /nav/sdk_command 服务发送 “EStop” 指令。急停后需调用 resume_estop() 解除，再重新使能驱动器才能继续运动。

Parameters:

timeout (int) – 服务调用超时秒数（默认: 5）

Returns:

指令响应

state: State 对象（code/describe）
response.result: bool，True 表示急停指令已成功下发

Return type:

RobotCommandResponse

Examples:

result = emergency_stop()
if result.response.result:
    print("急停已触发，机器人已停止")

Note

机器人急停后必须先调用 resume_estop() 解除急停，才能再次使能驱动器
通过 get_emergency_state() 可查询当前急停状态

底层 ROS2 接口

类型: Service saturn_msgs/srv/RobotCommand
名称: /nav/sdk_command
参数映射:

封装参数	原生字段（Request）
（固定值）	`comamnd_name="EStop"`（该 .srv 字段名原文如此拼写）
`timeout`	客户端等待时长，不下发

resume_estop(timeout=5)

解除软件急停状态。

向 /nav/sdk_command 服务发送 “ResumeEStop” 指令，解除急停后需重新使能驱动器才能继续运动。

Parameters:

timeout (int) – 服务调用超时秒数（默认: 5）

Returns:

指令响应

state: State 对象（code/describe）
response.result: bool，True 表示急停解除成功

Return type:

RobotCommandResponse

Examples:

# 解除急停后重新使能驱动器
result = resume_estop()
if result.response.result:
    print("急停已解除")
    driver_enable(True)  # 重新使能驱动器

Note

必须先调用 emergency_stop() 或机器人处于急停状态后才有意义调用本函数
解除急停后还需重新调用 driver_enable(True) 才能运动

底层 ROS2 接口

类型: Service saturn_msgs/srv/RobotCommand
名称: /nav/sdk_command
参数映射:

封装参数	原生字段（Request）
（固定值）	`comamnd_name="ResumeEStop"`（该 .srv 字段名原文如此拼写）
`timeout`	客户端等待时长，不下发

停障开关

set_guardian_switch(enable, timeout=5)

开启或关闭 Guardian 障碍停止开关。

向 /nav/sdk_command 服务发送 “EnableGuardianSwitch”（开启）或 “DisableGuardianSwitch”（关闭）指令。Guardian 开启时遇到障碍物机器人会自动停止。

Parameters:

enable (bool) – True 开启 Guardian，False 关闭 Guardian
timeout (int) – 服务调用超时秒数（默认: 5）

Returns:

指令响应

state: State 对象（code/describe）
response.result: bool，True 表示指令执行成功

Return type:

RobotCommandResponse

Examples:

# 开启 Guardian
result = set_guardian_switch(True)
if result.response.result:
    print("Guardian 已开启，遇障碍将自动停止")

# 关闭 Guardian
result = set_guardian_switch(False)
if result.response.result:
    print("Guardian 已关闭")

Note

通过 get_guardian_state() 可查询当前 Guardian 开关状态

底层 ROS2 接口

类型: Service saturn_msgs/srv/RobotCommand
名称: /nav/sdk_command
参数映射:

封装参数	原生字段（Request）
`enable`	`comamnd_name`（`True` → `"EnableGuardianSwitch"`，`False` → `"DisableGuardianSwitch"`；该 .srv 字段名原文如此拼写）
`timeout`	客户端等待时长，不下发

get_guardian_states(stale_timeout=0.5)

获取 Guardian 感知的四方向速度衰减状态（前/后/左/右）。

从 /nav/guardian 话题（daystar_navigation_msgs/GuardianStates）订阅并缓存。非阻塞缓存读取、立即返回，可在运动控制循环中逐 tick 高频调用。

Parameters:

stale_timeout (float) – 数据时效（秒），默认 0.5（topic 20Hz，连丢 10 帧判异常）。距最近一帧超过该时长则 fresh=False

Returns:

响应结构

state: State 对象（code/describe）
front: float，前方衰减比。1.0=正常；0~1=减速区（可作速度缩放参考）；-2.0=停车区
rear: float，后方衰减比，语义同 front
left: float，左侧衰减比，语义同 front
right: float，右侧衰减比，语义同 front
fresh: bool，True 表示近期收到过 /nav/guardian 数据；False=数据过期或从未收到
switch_on: bool，停障开关缓存值（/nav/guardian_state，非阻塞读，5 秒时效）
switch_fresh: bool，True 表示近期收到过停障开关数据

Return type:

GetGuardianStatesResponse

Examples:

# 前进前检查前方是否可通行
states = get_guardian_states()
if not states.fresh:
    print("guardian 数据不可用，按无障碍处理")
elif states.front < 0.0:
    print("前方处于停车区，不能前进")
elif states.front < 1.0:
    print(f"前方处于减速区，建议速度缩放到 {states.front:.2f} 倍")
else:
    print("前方畅通")

Note

数据来源：/nav/guardian 话题订阅（daystar_navigation_msgs/GuardianStates，QoS(1) 非 latched）
衰减比为 -2.0 表示停车区，不能当作速度乘法因子直接使用
数据过期或未收到时四方向保持最近值且 fresh=False，调用方应按无障碍（fail-open）处理
任务脚本中 send_cmd_vel(dt>0) 已内置 guardian 避障（遇障暂停/障碍离开续行/超时取消），无需手工循环检查本接口；本接口用于运动前预检或自定义控制循环

底层 ROS2 接口

通道一（四方向速度衰减状态）：

类型: Topic 订阅缓存 daystar_navigation_msgs/msg/GuardianStates
名称: /nav/guardian
说明: 非阻塞读缓存，按 trigger_source（/front /rear /left /right）取各方向 velocity_decay_ratio。

通道二（停障开关缓存，随响应一并带出 switch_on / switch_fresh）：

类型: Topic 订阅缓存 std_msgs/msg/Bool
名称: /nav/guardian_state
参数映射:

封装参数	原生字段
`stale_timeout`	客户端行为，不下发：仅用于本地判定 `fresh` 标记（距最近一帧超过该秒数则 `fresh=False`）

演示动作

demo_control(demo_type, enable=True, timeout=5)

触发机器人预设动作（Demo 演示）。

通过 /nav/sdk_action（saturn ParamsCommand）向机器人下发预设演示动作指令。

Parameters:

demo_type (int) – 动作类型编号 - 2: 摇头（shake hand） - 3: 摆尾（shake butt） - 4: 打招呼（greetings） - 其他值将导致执行失败
enable (bool) – 保留参数，当前协议未使用，保持默认值 True 即可（默认: True）
timeout (int) – 服务调用超时秒数（默认: 5）

Returns:

指令响应

state: State 对象（code/describe）
response.result: bool，True 表示动作指令下发成功

Return type:

RobotCommandResponse

Examples:

# 触发摇头动作
result = demo_control(demo_type=2)
if result.response.result:
    print("摇头动作已触发")

# 触发打招呼动作
result = demo_control(demo_type=4)
if result.response.result:
    print("打招呼动作已触发")

Note

执行前置条件：驱动器已使能、未处于急停状态、机器人已站立
enable 参数当前协议中保留未用，无需修改默认值

底层 ROS2 接口

类型: Service saturn_msgs/srv/ParamsCommand
名称: /nav/sdk_action
参数映射:

封装参数	原生字段（Request）
`demo_type`	`command_value`（固定 `command_name="demo_control"`；客户端仅放行 2/3/4）
`enable`	保留参数，客户端不使用、不下发
`timeout`	客户端等待时长，不下发

面部表情

set_expression(index, timeout=5)

切换机器人面部表情（LED 屏）。

通过 /nav/sdk_action（saturn ParamsCommand，command_name=”light_style”）下发表情序号，切换机器人面部 LED 显示的表情。纯显示指令，不影响运动，任意控制模式下均可调用。

Parameters:

index (int) – 表情序号（仅放行情绪类，其余值将被拒绝） - 4: 正常表情 - 5: 笑脸 - 6: 哭泣 - 7: 跟随 - 8: 惊吓 - 13: 生气 - 14: 眨眼 - 19: 躺下 - 20: 卖惨 - 21: 不屑 - 22: 皱眉 - 23: 害怕
timeout (int) – 服务调用超时秒数（默认: 5）

Returns:

指令响应

state: State 对象（code/describe）
response.result: bool，True 表示表情切换指令下发成功

Return type:

RobotCommandResponse

Examples:

# 切换为笑脸
result = set_expression(index=5)
if result.response.result:
    print("已切换为笑脸")

# 配合动作做情绪表达
result = set_expression(index=13)  # 生气
if result.response.result:
    print("已切换为生气表情")

Note

仅放行情绪类表情序号 4/5/6/7/8/13/14/19/20/21/22/23；关机(2)/开机(3)/关 LED(1) 等设备控制、故障告警(601/602/603) 及低电量/充电中等状态指示由系统自动驱动，不在本接口开放范围
无运动前置条件，任意模式可用

底层 ROS2 接口

类型: Service saturn_msgs/srv/ParamsCommand
名称: /nav/sdk_action
参数映射:

封装参数	原生字段（Request）
`index`	`command_value`（固定 `command_name="light_style"`；客户端白名单仅放行 4/5/6/7/8/13/14/19/20/21/22/23）
`timeout`	客户端等待时长，不下发

后尾灯样式

set_back_light(index, timeout=5)

切换机器人后尾灯样式（后灯板 LED，仅 MX DVT 机型支持）。

通过 /nav/sdk_action（saturn ParamsCommand，command_name=”back_light_style”）下发样式序号，切换机器人后尾灯 LED 显示样式。纯显示指令，不影响运动，任意控制模式下均可调用。

Parameters:

index (int) – 后尾灯样式序号（仅放行可主动设置的样式，其余值将被拒绝） - 54: 标准闪 - 55: 快闪 - 56: 慢呼吸 - 57: 标准呼吸 - 68: 特殊功能状态1
timeout (int) – 服务调用超时秒数（默认: 5）

Returns:

指令响应

state: State 对象（code/describe）
response.result: bool，True 表示样式切换指令下发成功

Return type:

RobotCommandResponse

Examples:

# 切换为标准呼吸
result = set_back_light(index=57)
if result.response.result:
    print("已切换为标准呼吸")

Note

仅放行可主动设置的样式 54/55/56/57/68；启动/电量/充电/转向/急停/故障等其余序号由系统自动驱动，不在本接口开放范围
仅 MX DVT 机型有后灯板；无该硬件的机型下发后无实际效果
无运动前置条件，任意模式可用

底层 ROS2 接口

类型: Service saturn_msgs/srv/ParamsCommand
名称: /nav/sdk_action
参数映射:

封装参数	原生字段（Request）
`index`	`command_value`（固定 `command_name="back_light_style"`；客户端白名单仅放行 54/55/56/57/68）
`timeout`	客户端等待时长，不下发

状态查询

驱动器状态

get_driver_state()

获取驱动器使能状态。

从 /nav/driver_state 话题（std_msgs/UInt8）订阅并缓存，5 秒内未收到数据则返回 UNKNOWN。

Returns:

响应结构

state: State 对象（code/describe）
driver_state: DriverEnableState 枚举
- DriverEnableState.UNKNOWN (0): 未知（数据陈旧或尚未收到）
- DriverEnableState.ENABLED (1): 已使能
- DriverEnableState.ENABLING (2): 使能中
- DriverEnableState.ENABLE_FAILED (3): 使能失败
- DriverEnableState.DISABLED (4): 未使能

Return type:

GetDriverStateResponse

Examples:

response = get_driver_state()
if response.driver_state == DriverEnableState.ENABLED:
    print("驱动器已使能，可以运动")
elif response.driver_state == DriverEnableState.DISABLED:
    print("驱动器未使能，请先调用 driver_enable(True)")

Note

数据来源：/nav/driver_state 话题订阅（5 秒时效）
数据陈旧或尚未收到时返回 UNKNOWN

底层 ROS2 接口

类型: Topic 订阅缓存 std_msgs/msg/UInt8
名称: /nav/driver_state
说明: 无入参；读取订阅缓存（5 秒时效），数据陈旧或未收到时返回 UNKNOWN。

急停状态

get_emergency_state()

获取软件急停状态。

从 /nav/emergency_state 话题（std_msgs/Bool）订阅并缓存，5 秒内未收到数据则返回 False。

Returns:

响应结构

state: State 对象（code/describe）
emergency: bool，True 表示机器人当前处于软件急停状态

Return type:

GetEmergencyStateResponse

Examples:

response = get_emergency_state()
if response.emergency:
    print("机器人处于急停状态，需先调用 resume_estop() 解除")
else:
    print("无急停，可正常操作")

Note

数据来源：/nav/emergency_state 话题订阅（5 秒时效）
数据陈旧或尚未收到时 emergency 返回 False

底层 ROS2 接口

类型: Topic 订阅缓存 std_msgs/msg/Bool
名称: /nav/emergency_state
说明: 无入参；读取订阅缓存（5 秒时效），数据陈旧或未收到时 emergency 返回 False。

停障状态

get_guardian_state()

获取 Guardian（障碍停止）开关状态。

从 /nav/guardian_state 话题（std_msgs/Bool）订阅并缓存，5 秒内未收到数据则返回 False。

Returns:

响应结构

state: State 对象（code/describe）
guardian: bool，True 表示 Guardian 障碍停止开关已启用

Return type:

GetGuardianStateResponse

Examples:

response = get_guardian_state()
if response.guardian:
    print("Guardian 已开启，遇障碍将自动停止")
else:
    print("Guardian 已关闭")

Note

数据来源：/nav/guardian_state 话题订阅（5 秒时效）
数据陈旧或尚未收到时 guardian 返回 False

底层 ROS2 接口

类型: Topic 订阅缓存 std_msgs/msg/Bool
名称: /nav/guardian_state
说明: 无入参；读取订阅缓存（5 秒时效），数据陈旧或未收到时 guardian 返回 False。

聚合总状态

get_robot_status_full(wait_timeout=1.0)

获取机器人全量聚合状态快照（一次调用取齐运动域 + 定位域，带跨进程兜底）。

各字段读自本进程的 topic 订阅缓存（时效 5 秒）。任务子进程的订阅可能整体断流（暂停恢复后易发，transport 层缺陷：topic 数据停送而服务通道正常），此时本函数会自动经 /sdk/get_robot_status 向主进程取一份权威快照填补失效字段，并置 from_fallback=True。兜底也拿不到时 fresh=False——此时所有字段都只代表”读不到”，不代表真实状态。

Parameters:

wait_timeout (float) – 数据未就绪时的最长等待秒数（默认 1.0）。9 个字段共享这一条截止线而非各等满，故断流时总等待不超过该值。传 0 表示纯读缓存不等待。

Returns:

全量状态响应，字段如下

state: State 对象（code/describe）
robot_state: RobotState 枚举（姿态：LIE_DOWN/STANDING_UP/STAND_UP/UNKNOWN_STATE）
control_mode: ControlMode 枚举（JOY_MODE/NAV_MODE/UNKNOWN_MODE）
gait_type: GaitType 枚举（TROT/NORMAL_STAIR/…/UNKNOWN_GAIT）
dock_state: DockState 枚举（IDLE/GOING_TO_DOCK/…/UNKNOWN_DOCK）
loc_state: LocalizationState 枚举（NORMAL/LACKDATA/LOST/UNKNOWN_LOC）
localization_mode: LocalizationMode 枚举（MAP/SLAM/REFLECTOR/UNKNOWN_LOC_MODE）
battery: sensor_msgs/BatteryState（完整电池信息，参见 get_battery_state）
is_charging: bool（是否正在充电）
driver_state: DriverEnableState 枚举（UNKNOWN/ENABLED/ENABLING/ENABLE_FAILED/DISABLED）
emergency: bool（是否处于软件急停）
guardian: bool（Guardian 障碍停止开关是否开启）
lidar_state: LidarState 枚举（UNKNOWN/NORMAL/HIGHFREQ/LOWFREQ/DISCONNECT）
fresh: bool（数据是否可信，False 时不得据字段值做状态判断）
from_fallback: bool（是否经 /sdk/get_robot_status 兜底取得）

Return type:

GetRobotStatusResponse

Examples:

resp = get_robot_status_full()
if not resp.fresh:
    # 读不到真实状态：只发幂等命令，不做"看起来没急停就跳过"这类判断
    print("状态数据不可信，跳过基于状态的判断")
else:
    print(f"姿态: {resp.robot_state}, 控制模式: {resp.control_mode}")
    if resp.driver_state == DriverEnableState.ENABLED and not resp.emergency:
        print("机器人就绪，可以运动")

Note

数据时效 5 秒；订阅断流时自动经 /sdk/get_robot_status 兜底（最短 1 秒重试一次）
务必先看 fresh：emergency/guardian/is_charging 读不到时都是 False，与真实状态同形
一次取齐比逐项调 get_robot_state/get_control_mode/… 快得多（后者每项各阻塞 3~5 秒）

底层 ROS2 接口

类型: Topic 订阅缓存（聚合多路，无服务调用）
说明: 无入参；逐字段读取以下话题的订阅缓存（各 5 秒时效，陈旧或未收到时该字段回退为 UNKNOWN/False/空值）：

话题名称	消息类型
`/nav/robot_state`	`std_msgs/msg/UInt32`
`/nav/control_mode`	`std_msgs/msg/UInt8`
`/nav/gait`	`std_msgs/msg/UInt8`
`/nav/dock_state`	`std_msgs/msg/UInt32`
`/nav/battery_state`	`sensor_msgs/msg/BatteryState`
`/nav/charge_state`	`std_msgs/msg/Bool`
`/nav/driver_state`	`std_msgs/msg/UInt8`
`/nav/emergency_state`	`std_msgs/msg/Bool`
`/nav/guardian_state`	`std_msgs/msg/Bool`
`/nav/localization_state`（`loc_state` 字段）	`daystar_navigation_msgs/msg/LocalizationState`
`/nav/lidar_states`（`whole_lidar_state` 字段）	`daystar_navigation_msgs/msg/LidarState`
`/nav/current_localization_mode`	`std_msgs/msg/UInt8`

雷达状态

get_lidar_state()

获取雷达整机健康状态。

订阅 /nav/lidar_states`（daystar_navigation_msgs/msg/LidarState）的 `whole_lidar_state 字段并缓存，5 秒内无数据则返回 UNKNOWN。本调用为非阻塞缓存读取，立即返回。

Parameters:

无参数。 –

Returns:

响应结构

state: State 对象（code/describe）
lidar_state: LidarState 枚举，取值如下：
- LidarState.UNKNOWN (0): 未知（数据陈旧或尚未收到）
- LidarState.NORMAL (1): 正常（约 10Hz）
- LidarState.HIGHFREQ (2): 高频（≥15Hz）
- LidarState.LOWFREQ (3): 低频（≤5Hz）
- LidarState.DISCONNECT (4): 断连

Return type:

GetLidarStateResponse

Examples:

response = get_lidar_state()
if response.lidar_state == LidarState.NORMAL:
    print("雷达状态正常")
elif response.lidar_state == LidarState.DISCONNECT:
    print("雷达已断连，请检查连接")
elif response.lidar_state == LidarState.UNKNOWN:
    print("雷达状态未知（尚未收到数据或数据陈旧）")

Note

数据来源：订阅 /nav/lidar_states 话题（daystar_navigation_msgs/msg/LidarState），取 whole_lidar_state 字段（uint8），5 秒时效。
数据陈旧或尚未收到时返回 LidarState.UNKNOWN；state.code 仍为 success。
本调用非阻塞，不等待数据就绪；若需确保数据有效，请配合 get_robot_status_full 使用。

底层 ROS2 接口

类型: Topic 订阅缓存 daystar_navigation_msgs/msg/LidarState
名称: /nav/lidar_states
说明: 无入参；读取订阅缓存中 whole_lidar_state 字段（5 秒时效），数据陈旧或未收到时返回 UNKNOWN。

运动控制

核心功能

站立与躺下

身体控制

控制模式

充电功能

电池状态

速度控制

驱动器与急停

停障开关

演示动作

面部表情

后尾灯样式

状态查询

驱动器状态

急停状态

停障状态

聚合总状态

雷达状态

相关数据类型