运动控制

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

核心功能

站立与躺下

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

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

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

身体控制

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

set_gait(gait_type, timeout=5)

Set the robot gait type.

Parameters:

  • gait_type (GaitType) – Gait type enum - GaitType.TROT (0): Trot gait - GaitType.NORMAL_STAIR (1): Normal 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

  • 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 stairs gait
result = set_gait(GaitType.TROT)
if result.response.result:
    print("Gait set to stairs mode")

# Set to normal gait
result = set_gait(GaitType.NORMAL_GAIT)

Note

  • Robot must be standing to change gait

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.STAIRS_GAIT:
        print("Stairs gait active")
    elif response.gait_type == GaitType.NORMAL_GAIT:
        print("Normal gait active")

Note

  • Data from /gait topic subscription (5 second timeout)

  • Returns UNKNOWN_GAIT if data is stale or not yet received

控制模式

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

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

充电功能

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

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

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

电池状态

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

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

速度控制

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

驱动器与急停

driver_enable(enable=True, timeout=5)

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

向 /nav/robot_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() 可查询当前驱动器状态

emergency_stop(timeout=5)

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

向 /nav/robot_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() 可查询当前急停状态

resume_estop(timeout=5)

解除软件急停状态。

向 /nav/robot_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) 才能运动

停障开关

set_guardian_switch(enable, timeout=5)

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

向 /nav/robot_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 开关状态

演示动作

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 参数当前协议中保留未用，无需修改默认值

面部表情

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) 及低电量/充电中等状态指示由系统自动驱动，不在本接口开放范围

  • 无运动前置条件，任意模式可用

后尾灯样式

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 机型有后灯板；无该硬件的机型下发后无实际效果

  • 无运动前置条件，任意模式可用

状态查询

驱动器状态

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

急停状态

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

停障状态

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

聚合总状态

get_robot_status_full()

获取机器人全量聚合状态快照。

运动域各字段（robot_state/control_mode/gait_type/dock_state/battery/is_charging/ driver_state/emergency/guardian）均为非阻塞缓存读取；定位状态（loc_state）额外从 Navigation 服务获取，可能阻塞最多约 3 秒。

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）

  • 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）

Return type:

GetRobotStatusResponse

Examples:

resp = get_robot_status_full()
print(f"姿态: {resp.robot_state}, 控制模式: {resp.control_mode}")
print(f"驱动器: {resp.driver_state}, 急停: {resp.emergency}")
print(f"定位: {resp.loc_state}")
if resp.driver_state == DriverEnableState.ENABLED and not resp.emergency:
    print("机器人就绪，可以运动")

Note

  • 运动域字段为非阻塞缓存快照，数据时效为 5 秒

  • loc_state 通过 Navigation GetLocalizationState 服务获取，可能阻塞最多约 3 秒

  • 若需仅查单项状态，推荐使用对应的专项 getter（如 get_driver_state、get_emergency_state）

雷达状态

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 使用。

相关数据类型

运动控制相关的响应类型和枚举类型的详细说明请参见 数据结构 文档：

响应类型:

枚举类型: