Skip to main content

Python API 参考 - S1 机器

  • GalbotRobot: 核心机器人控制模块。用于机器人连接、生命周期管理、关节控制、传感器数据查询和硬件状态监控。
  • GalbotMotion: 运动规划与执行模块。用于笛卡尔空间/关节空间运动、轨迹规划、逆运动学和全身控制。
  • GalbotNavigation: 移动导航模块。用于移动底盘定位、地图构建、路径规划和自主移动。
  • GalbotPerception: 端侧感知模块。加载视觉模型、运行推理，并读取结构化结果（如立体深度）；与GalbotRobot传感器API配合使用。
  • Types & Enums: 数据结构、枚举与状态类型。本节用于查询类型定义、传感器类型、错误码及其他模块使用的数据结构。

核心机器人控制（GalbotRobot）​

Galbot 人形机器人的主机器人控制接口。

该类提供用于控制 Galbot 机器人的单例接口，支持关节位置与轨迹控制、末端执行器控制、移动底盘速度控制、传感器数据采集、坐标系变换和系统生命周期管理。使用 GalbotRobot::get_instance(MachineType) 获取指定平台（G1/S1）的引用。除非另有说明，角度单位为弧度，线性距离单位为米，时间戳单位为纳秒。

获取控制器权限（acquire_controller）​

def acquire_controller(controller_name: str) -> ControlStatus

获取硬件控制权限。

请求指定控制器接管硬件控制。该操作与 switch_controller 使用同一套 WBCS 切换请求机制。

参数

名称类型默认值描述
controller_namestr需要传参控制器名称字符串，例如 "left_arm_pvt_ctrl"。

返回值

类型描述
ControlStatus控制状态，指示获取操作的成功或失败

检查轨迹执行状态（check_trajectory_execution_status）​

def check_trajectory_execution_status(
    joint_groups: Sequence[str] = []
) -> list[TrajectoryControlStatus]

获取指定关节组的轨迹执行状态。

查询指定关节组的轨迹当前执行状态。这对于在非阻塞执行模式下监视轨迹进度很有用。

参数

名称类型默认值描述
joint_groupsSequence[str][]关节组列表

返回值

类型描述
list[TrajectoryControlStatus]轨迹控制状态列表：轨迹执行状态列表。

清除末端执行器命令（clear_end_effector_command）​

def clear_end_effector_command(hold: bool = False) -> ControlStatus

清除 WBC 末端执行器任务命令。

清除已发布到 WBC 通道的末端执行器任务轨迹命令。

参数

名称类型默认值描述
holdboolFalse为 true 时，将 WBC 关节参考值锁定为当前传感器位姿，使关节在清除命令后保持当前构型。为 false（默认值）时，关节返回配置的参考位姿。

返回值

类型描述
ControlStatus控制状态，表示命令发布结果。

销毁（destroy）​

def destroy() -> None

清理系统资源。

执行机器人控制系统资源的最终清理，包括中间件连接、传感器接口和通信通道。这是关闭序列的最后一步：request_shutdown() -> wait_for_shutdown() -> destroy()。

此方法应在程序结束时调用一次。调用 destroy() 后，SDK 进入终态，无法在同一进程重新初始化。如需再次使用，请退出当前进程并启动新进程。

执行关节轨迹（execute_joint_trajectory）​

def execute_joint_trajectory(trajectory: Trajectory, is_blocking: bool = True) -> ControlStatus

执行预先规划的关节轨迹。

执行由路径点组成的轨迹，每个路径点都关联着关节位置、速度和时间信息。轨迹控制器在路径点之间进行插值，以生成平滑的运动。

对于标准关节（头部、腿部、手臂），当前版本中只有位置有效；速度、加速度和力度目前被忽略。

参数

名称类型默认值描述
trajectoryTrajectory需要传参轨迹数据结构，包含路点和时序信息。必须指定 trajectory.joint_groups 或 trajectory.joint_names；如果两者都为空，则返回 INVALID_INPUT。
is_blockingboolTrue是否阻塞等待完成

返回值

类型描述
ControlStatus控制状态，指示轨迹执行/提交的成功或失败
warning

每个 TrajectoryPoint.joint_command_vec 的顺序必须与 trajectory.joint_names 定义的关节顺序或 trajectory.joint_groups 的展开顺序一致。

warning

对于逐帧模型推理输出，建议使用命令流式接口（set_joint_commands / set_joint_commands_batch），而不是反复重新提交完整轨迹。

获取当前控制器（get_active_controller）​

def get_active_controller(group_name: str) -> str

获取指定关节组的活动控制器名称。

返回当前 SDK 实例记录的该关节组控制器。该值会以模型默认控制器初始化，并在 SDK 控制器管理接口成功调用后更新。若控制已释放或该关节组无已知控制器，则返回 "CONTROLLER_NAME_NUM"。

参数

名称类型默认值描述
group_namestr需要传参要查询的关节组名称。

返回值

类型描述
strstd::string：当前 SDK 实例已知的活动控制器名称。

获取底盘速度（get_base_velocity）​

def get_base_velocity() -> dict

获取当前移动底盘速度。

返回包含线速度和角速度的结构化底盘速度信息。

返回值

类型描述
dictBaseVelocityInfo 共享指针，包含当前底盘线速度和角速度；获取失败时返回空指针。

获取相机内参（get_camera_intrinsic）​

def get_camera_intrinsic(camera_id: SensorType) -> dict

获取相机内参。

获取指定相机的内参，包括焦距、主点、畸变系数等。

参数

名称类型默认值描述
camera_idSensorType需要传参RGB相机ID

返回值

类型描述
dict字典：包含相机内参。- header: 消息头（带时间戳和帧信息） - height: 图像高度（像素） - width: 图像宽度（像素） - distortion_model: 畸变模型，如 "plumb_bob" - D: 畸变系数（浮点数列表） - K: 相机内参矩阵（9个浮点数列表） - binning_x: 水平像素合并因子 - binning_y: 垂直像素合并因子 - roi: 感兴趣区域（整数列表） - camera_type: 相机类型。失败时返回空字典。
note

相机传感器必须在初始化期间通过 enable_sensor_set 启用。

获取配置（get_config）​

def get_config(service: ConfigService, keys: Sequence[str], use_default: bool = False) -> tuple

读取当前配置值或机器人默认配置值。

默认读取用户当前配置的值，而非运行中服务的内存状态。use_default 为 true 时，仅读取机器人内置默认配置。keys 为空时，读取适用于当前机器人的所有已注册字段。

参数

名称类型默认值描述
serviceConfigService需要传参-
keysSequence[str]需要传参-
use_defaultboolFalse-

返回值

类型描述
tuple-

获取深度图像数据（get_depth_data）​

def get_depth_data(camera_id: SensorType) -> dict

获取指定手臂深度相机的最新深度图像数据。

从手臂安装的 RGB-D 深度流中检索最新深度帧。仅 SensorType.LEFT_ARM_DEPTH_CAMERA 和 SensorType.RIGHT_ARM_DEPTH_CAMERA 可用于此方法。

参数

名称类型默认值描述
camera_idSensorType需要传参要查询的深度相机传感器 ID。

返回值

类型描述
dictdict：包含以下键的字典：- 'header'：消息头，包含时间戳和坐标系信息 - 'format'：深度图像编码和压缩格式 - 'depth_scale'：深度缩放因子 - 'height'：图像高度（像素） - 'width'：图像宽度（像素） - 'data'：编码后的深度图像字节。如果传感器类型无效、传感器未启用或数据获取失败，则返回空字典。
note

深度传感器必须在初始化时包含在 enable_sensor_set 中。

note

此 API 仅适用于 G1 和 S1。G3 不提供安装在手臂上的深度相机。

note

DepthData::data 存储编码后的深度图像字节。请先解码图像，再使用 depth_m = pixel_value / depth_scale 将像素值转换为米。例如 depth_scale = 1000 表示 1000 个计数值等于 1.0 m。

note

解码后的像素值为 0 通常表示无效或缺失深度。

获取设备信息（get_device_information）​

def get_device_information() -> dict

获取设备信息。

检索基本设备信息，包括设备型号、序列号、固件版本、硬件版本和制造商。此信息用于设备管理、版本控制、系统诊断和设备识别。

返回值

类型描述
dictDeviceInfo 共享指针，包含设备信息；获取失败时返回空指针。

获取力传感器数据（get_force_sensor_data）​

def get_force_sensor_data(
    sensor_type: GalbotOneFoxtrotSensor,
    calibrated: bool = False,
    ref_frame: str = ''
) -> dict

获取力/力矩传感器数据。

从指定的力/力矩传感器获取最新的原始测量值或标定后的测量值。力和力矩分量可以按需旋转到受支持参考坐标系的坐标轴方向，同时保持传感器测量原点不变。

参数

名称类型默认值描述
sensor_typeGalbotOneFoxtrotSensor需要传参GalbotOneFoxtrotSensor 枚举，用于指定要查询的力传感器
calibratedboolFalse是否读取标定后的接触力旋量数据。为 false 时读取腕部力传感器的原始数据。
ref_framestr''用于表示返回的力和力矩的参考坐标系（仅使用其坐标轴方向）。传入空字符串则保持源坐标系的坐标轴。支持的非空坐标系为 "base_link"、"torso_base_link"，以及与传感器对应的 "left_arm_end_effector_mount_link" 或 "right_arm_end_effector_mount_link"。

返回值

类型描述
dict指向 ForceData 的共享指针，包含：力向量，单位牛顿（N）：[fx, fy, fz]；力矩向量，单位牛·米（N·m）：[tx, ty, tz]；纳秒级时间戳。若输入无效、数据获取失败或坐标变换不可用，则返回 nullptr。
note

读取原始力传感器数据要求在初始化时通过 enable_sensor_set 使能该传感器。

note

坐标转换仅旋转力和力矩，不会平移力旋量的参考点，也不会引入由平移产生的附加力矩。

获取坐标系名称（get_frame_names）​

def get_frame_names() -> list[str]

获取 TF 树中所有可用的坐标系名称。

返回值

类型描述
list[str]所有可用坐标系名称列表。

获取夹爪状态（get_gripper_state）​

def get_gripper_state(end_effector: str) -> GripperState

获取指定夹爪的当前状态。

返回夹爪的位置、速度、受力以及运动状态估计信息。

GripperState.is_moving 基于时间窗口判定：若在内部窗口内未检测到有效开合变化，则该值会变为 false。

参数

名称类型默认值描述
end_effectorstr需要传参要查询的夹爪关节组名称（例如 left_gripper、right_gripper）。

返回值

类型描述
GripperStateGripperState 共享指针，包含夹爪状态信息；获取失败时返回空指针。

获取IMU数据（get_imu_data）​

def get_imu_data(sensor_id: SensorType) -> dict

获取 IMU（惯性测量单元）传感器数据。

检索最新的 IMU 测量值，包括线性加速度、角速度和方向估计。

参数

名称类型默认值描述
sensor_idSensorType需要传参传感器ID

返回值

类型描述
dict字典：包含以下键：- timestamp_ns: 时间戳（纳秒） - accel: 加速度 Vector3 {"x": float, "y": float, "z": float} - gyro: 陀螺仪 Vector3 {"x": float, "y": float, "z": float} - magnet: 磁力计 Vector3 {"x": float, "y": float, "z": float}。失败时返回空字典。
note

IMU 传感器必须在初始化期间通过 enable_sensor_set 启用。

note

加速度以米每二次方秒（m/s²）为单位。

note

角速度以弧度每秒（rad/s）为单位。

获取红外图像数据（get_ir_data）​

def get_ir_data(camera_id: SensorType) -> dict

从指定的红外相机获取最新的红外图像。

检索指定红外相机捕获的最新红外图像。仅当相机参数配置中 ir_enabled 为 true 时才可用。

参数

名称类型默认值描述
camera_idSensorType需要传参要查询的 IR 相机传感器 ID，可选值：LEFT_ARM_INFRA_CAMERA_1、LEFT_ARM_INFRA_CAMERA_2、RIGHT_ARM_INFRA_CAMERA_1、RIGHT_ARM_INFRA_CAMERA_2。

返回值

类型描述
dict字典：包含以下键：- header: 消息头（带时间戳和帧信息） - format: 图像格式，例如 'mono8; jpeg compressed mono8' - data: 压缩灰度图像二进制数据（字节）。若相机未启用、ir_enabled 为 false，或尚未收到数据，则返回空字典。
note

IR 传感器必须在初始化期间包含在 enable_sensor_set 中。

note

相机参数话题中的 ir_enabled 必须为 true，才会进行订阅。

获取关节组名称（get_joint_group_names）​

def get_joint_group_names() -> list[str]

获取机器人可用的关节组名称。

检索机器人运动学配置中定义的所有关节组名称。这对于在运行时发现可用的控制组很有用。

返回值

类型描述
list[str]关节组名称向量，或如果检索失败则为空向量

获取关节名称（get_joint_names）​

def get_joint_names(only_active_joint: bool = True, joint_groups: Sequence[str] = []) -> list[str]

通过组名获取机器人关节名称。

检索属于指定关节组的关节名称。这对于在设置关节位置时确定正确的顺序很有用。

参数

名称类型默认值描述
only_active_jointboolTrue是否仅返回主动关节
joint_groupsSequence[str][]关节组列表

返回值

类型描述
list[str]返回关节名称列表，顺序取决于参数配置

获取关节位置（get_joint_positions）​

def get_joint_positions(
    joint_groups: Sequence[str] = [],
    joint_names: Sequence[str] = []
) -> list[float]

获取关节位置

参数

名称类型默认值描述
joint_groupsSequence[str][]关节组列表
joint_namesSequence[str][]关节名称列表

返回值

类型描述
list[float]当前关节角度向量（弧度）
note

返回顺序：指定 joint_names 时，按 joint_names 的精确顺序返回。仅指定 joint_groups 时，按关节组定义顺序返回。两者均为空时，按机器类型相关的本体关节顺序返回：G1 为 chassis、head、left_arm、right_arm、leg；S1 为 torso、head、left_arm、right_arm。

获取关节状态（get_joint_states）​

def get_joint_states(
    joint_groups: Sequence[str] = [],
    joint_names: Sequence[str] = []
) -> list[JointState]

获取关节状态

参数

名称类型默认值描述
joint_groupsSequence[str][]关节组名称列表
joint_namesSequence[str][]具体关节名称列表，优先于 joint_groups

返回值

类型描述
list[JointState]List[JointState]：对应关节的实时状态数据。

注意返回顺序：指定 joint_names 时，按 joint_names 的精确顺序返回；仅指定 joint_groups 时，按关节组定义顺序返回；两者均为空时，按机器类型相关的本体关节顺序返回，G1 为 chassis、head、left_arm、right_arm、leg，S1 为 torso、head、left_arm、right_arm。
note

返回顺序：指定 joint_names_vec 时，按 joint_names_vec 的精确顺序返回。仅指定 joint_group_vec 时，按关节组定义顺序返回。两者均为空时，按机器类型相关的本体关节顺序返回：G1 为 chassis、head、left_arm、right_arm、leg；S1 为 torso、head、left_arm、right_arm。

获取激光雷达数据（get_lidar_data）​

def get_lidar_data(sensor_id: SensorType) -> dict

获取最新的激光雷达点云数据。

检索指定 LiDAR 传感器捕获的最新 3D 点云。每个点通常包含 (x, y, z) 坐标和可选的强度值。

参数

名称类型默认值描述
sensor_idSensorType需要传参传感器ID

返回值

类型描述
dict字典：包含点云数据字段和二进制点数据。失败时返回空字典。
note

LiDAR 传感器必须在初始化期间通过 enable_sensor_set 启用。

获取日志信息（get_log_information）​

def get_log_information(timewindow_s: SupportsInt, log_level: LogLevel) -> dict

获取日志信息。

参数

名称类型默认值描述
timewindow_sSupportsInt需要传参时间窗口（秒）
log_levelLogLevel需要传参日志级别

返回值

类型描述
dictLogInfo 共享指针，包含指定时间窗口和日志级别下的日志信息；获取失败时返回空指针。

获取里程计数据（get_odom）​

def get_odom() -> dict

获取机器人里程信息。

从里程计系统检索机器人当前的姿态和速度估计。里程计通常融合车轮编码器、IMU 和其他本体感觉传感器。

返回值

类型描述
dictOdomData 共享指针，包含里程计位姿、速度和时间戳；获取失败时返回空指针。

获取RGB图像数据（get_rgb_data）​

def get_rgb_data(camera_id: SensorType, format: RgbOutputFormat = ..., once: bool = True) -> dict

从指定相机获取一张指定格式的RGB相机图像。

获取一帧 DMA FD 相机图像，并按请求的格式返回由 CPU 持有的数据。JPEG 格式使用 Jetson 硬件编码器；NV12/BGR/RGB 格式返回紧凑排列的 CPU 字节数据，布局信息保存在 RgbData 中。

参数

名称类型默认值描述
camera_idSensorType需要传参RGB相机ID
formatRgbOutputFormat...图像格式，可选 JPEG、NV12、BGR 或 RGB，默认是 JPEG
onceboolTrueonce 为 true 时请求一帧最新图像。当不存在持久工作线程时，会创建一个仅请求一次的订阅，接收并释放该帧后关闭该订阅。如果已经有活跃的持久工作线程，则继续共享它。

返回值

类型描述
dict指向 RgbData 的共享指针，其中包含图像缓冲区、尺寸、布局、编码格式和时间戳。如果相机未启用或取图失败，则返回 nullptr。
note

相机传感器必须在初始化期间通过 enable_sensor_set 启用。

note

DMA FD 帧头不提供 frame_id。对于 RGB DMA 输出，请使用 get_camera_intrinsic() / camera_info 获取帧相关元数据。

获取传感器外参（get_sensor_extrinsic）​

def get_sensor_extrinsic(sensor_id: SensorType, reference_frame: str = 'base_link') -> tuple

获取传感器外参。

检索指定传感器的外部参数，包括相对于机器人基础坐标系的旋转和平移向量。

参数

名称类型默认值描述
sensor_idSensorType需要传参传感器ID
reference_framestr'base_link'参考坐标系

返回值

类型描述
tuple包含以下内容的 Pair：- 7 个 double 的向量，表示变换 [x, y, z, qx, qy, qz, qw]，其中 (x, y, z) 为平移（米），(qx, qy, qz, qw) 为四元数方向 - 变换有效时的时间戳（纳秒）。如果检索失败则返回空向量，时间戳为 0。
note

传感器必须在初始化期间通过 enable_sensor_set 启用。

获取同步观测数据（get_synced_observation）​

def get_synced_observation(
    cameras: Sequence[SensorType],
    with_joint_state: bool = True
) -> SyncedObservation

获取按相机时间戳对齐的同步观测数据。

使用 cameras 中的第一个传感器作为锚点。锚点相机获取最新帧，其它相机则从内部缓存中按时间戳进行最近邻匹配。如果 with_joint_state 为 true，则基于同一个锚点时间戳返回最近邻关节状态。在同步模式下，RGB 条目使用 CPU 持有的 NV12 数据，这样所有相机的采集时间戳都可以保持对齐，而不需要等待串行 JPEG 编码。如果请求的某个相机历史缓存初始为空，该调用最多等待一秒。返回的 joint_state->joint_state_vec 中，每个条目都包含 joint_name，便于调用方识别每个关节采样的语义含义。

参数

名称类型默认值描述
camerasSequence[SensorType]需要传参要进行同步的相机列表。cameras[0] 为锚定相机，且必须已启用。
with_joint_stateboolTrue是否包含最近邻匹配的关节状态。

返回值

类型描述
SyncedObservation同步观测数据的共享指针。成功时：rgb_data_map/depth_data_map 包含按时间戳对齐的相机帧；joint_state（请求时）包含带关节名称的最近邻关节状态样本。输入无效或数据获取失败时返回 nullptr。
note

这是基于软件时间戳的对齐，而不是硬件触发同步。最近邻查找不会强制限制最大时间戳差；有严格同步要求的调用方应自行校验返回的时间戳。

获取坐标变换（get_transform）​

def get_transform(
    target_frame: str,
    source_frame: str,
    timestamp_ns: SupportsInt = 0,
    timeout_ms: SupportsInt = 100
) -> tuple

查询坐标系变换（TF） 查询机器人TF树中两个坐标系之间的变换。

这用于在不同参考坐标系之间转换姿态和位置（例如，从相机坐标系到基坐标系，从末端执行器到世界坐标系）。

参数

名称类型默认值描述
target_framestr需要传参目标坐标系
source_framestr需要传参源坐标系
timestamp_nsSupportsInt0时间戳（纳秒）
timeout_msSupportsInt100超时时间（毫秒）

返回值

类型描述
tuple包含以下内容的 Pair：- 7 个 double 的向量，表示变换 [x, y, z, qx, qy, qz, qw]，其中 (x, y, z) 为平移（米），(qx, qy, qz, qw) 为四元数方向 - 变换有效时的时间戳（纳秒）。如果检索失败或超时则返回空向量，时间戳为 0。

获取 WBC 末端执行器位姿（get_wbc_end_effector_poses）​

def get_wbc_end_effector_poses() -> dict[str, list[float]]

获取 WBC 末端执行器位姿。

返回 WBC 各末端执行器（左臂、右臂、头部）的当前位姿。

返回值

类型描述
dict[str, list[float]]字典映射，包含：
- "lee_pose"：左臂末端位姿 [x, y, z, qx, qy, qz, qw]
- "ree_pose"：右臂末端位姿 [x, y, z, qx, qy, qz, qw]
- "head_pose"：头部末端位姿 [x, y, z, qx, qy, qz, qw]
当失败或缺少键时，可能返回空条目或部分数据。

初始化（init）​

def init(enable_sensor_set: Set[SensorType] = ..., enable_sync_mode: bool = False) -> bool

初始化机器人控制系统。

初始化机器人硬件通信、中间件和传感器接口。为了优化资源使用，只有在 enable_sensor_set 中指定的传感器才会被初始化并可用于数据读取。

此方法应在程序启动时调用一次。在未调用 destroy() 的情况下多次调用不会报错，但只有第一次调用生效。

参数

名称类型默认值描述
enable_sensor_setSet[SensorType]...要启用的传感器集合，如果为空，则启用默认的传感器集合，仅指定所需传感器可减少启动时间和资源占用
enable_sync_modeboolFalse是否启用内部同步缓冲区，用于按时间戳对齐的观测数据接口。

返回值

类型描述
bool初始化成功返回 true，否则返回 false。

检查是否运行中（is_running）​

def is_running() -> bool

检查机器人控制系统是否正在运行。

查询机器人控制系统是否仍处于活动状态，或者是否已收到关闭信号（例如，SIGINT、SIGTERM）。

返回值

类型描述
bool系统正常运行时返回 true，否则返回 false。

发布目标（publish_target）​

def publish_target(target: SingoriXTarget) -> ControlStatus

通过 WBC 发布通道发布原始 SingoriXTarget。

This is the advanced high-frequency path. Construct a SingoriXTarget directly, then call this interface to send it to the low-level controller without waiting for a service response. The SDK performs only basic structural validation.

参数

名称类型默认值描述
targetSingoriXTarget需要传参目标对象

返回值

类型描述
ControlStatus无返回值

注册末端工具原始数据回调（register_endtool_raw_callback）​

def register_endtool_raw_callback(callback: Callable) -> int

注册末端工具原始接收帧的回调。

所有端点/通道组合均通过同一个共享 DDS 主题分发给每个已注册的回调。回调在中间件线程上执行，调用方需要按需过滤 EndToolRawData::side/kind，并保证回调函数线程安全。

参数

名称类型默认值描述
callbackCallable需要传参要注册的回调函数。

返回值

类型描述
int非零的注册句柄；注册失败时返回 0。
note

回调在中间件线程上执行，请对共享状态做并发保护。注销后，已经开始执行的回调仍可能继续直至完成。

释放控制器权限（release_controller）​

def release_controller(group_name: str = 'all') -> ControlStatus

释放硬件权限。

控制硬件，释放关节。与 acquire_controller 相反。如果运行则隐式停止执行。

参数

名称类型默认值描述
group_namestr'all'要释放的关节组名称，支持的组：chassis（底盘）、legs（腿部）、head（头部）、left_arm（左臂）、right_arm（右臂）、gripper（夹爪）、suction_cup（吸盘）或 "all"（释放所有控制器）

返回值

类型描述
ControlStatus控制状态，指示释放操作的成功或失败

重新加载控制器（reload_controller）​

def reload_controller(group_name: str = 'all') -> ControlStatus

重新加载控制器。

重新初始化控制器。相当于一个完整的重启循环：停止->重置->启动。对于错误恢复或应用配置更改很有用。

参数

名称类型默认值描述
group_namestr'all'要重新加载的控制器组名称

返回值

类型描述
ControlStatus控制状态，指示重新加载操作的成功或失败

请求关机（request_shutdown）​

def request_shutdown() -> None

请求系统关闭。

发送关闭信号以启动系统正常关闭。这会触发已注册的退出回调并开始资源清理。作为关闭序列的第一步调用：request_shutdown() -> wait_for_shutdown() -> destroy()。

请求目标（request_target）​

def request_target(target: SingoriXTarget) -> ErrorInfo

通过 WBC 服务通道请求执行原始 SingoriXTarget。

This is the advanced request path. The SDK performs request-side runtime error screening, sends the target through the middleware client, and returns the ErrorInfo service payload. A return value of None means the client was unavailable, disconnected, timed out, or returned an empty response.

参数

名称类型默认值描述
targetSingoriXTarget需要传参目标对象

返回值

类型描述
ErrorInfoErrorInfo 共享指针；包含错误响应载荷，未收到有效响应时返回空指针。

发送末端工具原始帧（send_endtool_raw_frame）​

def send_endtool_raw_frame(side: EndToolSide, frame: bytes) -> ControlStatus

向指定手臂的 TIB 末端工具通道发布一帧 64 字节的不透明数据。

这是传输层 API。SDK 不会对 frame 中设备相关的 CAN/RS485 报文进行编码或校验。返回 SUCCESS 仅表示 DDS 消息已在本地发布，并不代表 WBCS、TIB 或末端工具已接受该指令。

参数

名称类型默认值描述
sideEndToolSide需要传参左臂或右臂/TIB 通道。
framebytes需要传参S1 WBCS 64 字节 TIB 布局的设备相关数据帧。

返回值

类型描述
ControlStatus指令发布状态。
note

在 S1 GBS 1.18.1 上，需在 WBCS 启动前设置 [robot_info.custom_params].endtool_raw_enabled = true。

warning

原始发送通路在服务端没有独占写锁。请勿在生产控制器写入同一末端工具时并发发送原始帧。

设置底盘姿态（set_base_pose）​

def set_base_pose(
    base_pose: Pose,
    is_blocking: bool = True,
    timeout_s: SupportsFloat = 15.0
) -> ControlStatus

设置移动基础位姿命令。

命令机器人的移动底座移动到其参考坐标系中的指定姿态。这使用底盘姿态控制器（CHASSIS_POSE_CTRL）。当完整的 3D 姿态（位置 + 四元数方向）已经可用时，使用此重载。

参数

名称类型默认值描述
base_posePose需要传参底盘目标姿态
is_blockingboolTrue是否阻塞等待完成
timeout_sSupportsFloat15.0超时时间（秒）。

返回值

类型描述
ControlStatus控制状态，指示命令传输的成功或失败

设置底盘姿态（set_base_pose）​

def set_base_pose(
    x: SupportsFloat,
    y: SupportsFloat,
    yaw: SupportsFloat,
    frame_id: str = 'rel(0)',
    reference_frame_id: str = 'odom',
    is_blocking: bool = True,
    timeout_s: SupportsFloat = 15.0
) -> ControlStatus

使用可选坐标系设置移动基础姿态（x、y、航向角）。

将此重载用于由所选坐标系中的 x/y/航向角定义的平面 2D 目标命令。

参数

名称类型默认值描述
xSupportsFloat需要传参X坐标（米）
ySupportsFloat需要传参Y坐标（米）
yawSupportsFloat需要传参航向角（弧度）
frame_idstr'rel(0)'目标坐标系 ID。当前推荐值为 "rel(0)"。"rel(0)" 表示 x/y/yaw 目标值相对于当前底盘位姿解释。"base_link"、"odom" 和 "map" 仅为兼容保留，不建议在当前版本中使用，未来版本可能会更改或移除。默认值："rel(0)"。
reference_frame_idstr'odom'参考坐标系ID
is_blockingboolTrue是否阻塞等待完成
timeout_sSupportsFloat15.0超时时间（秒）。

返回值

类型描述
ControlStatus控制状态，指示命令传输的成功或失败

设置底盘姿态（set_base_pose）​

def set_base_pose(
    x: SupportsFloat,
    y: SupportsFloat,
    yaw: SupportsFloat,
    frame_id: str,
    reference_frame_id: str,
    time_from_start_s: SupportsFloat,
    is_blocking: bool = True,
    timeout_s: SupportsFloat = 15.0
) -> ControlStatus

使用明确的插值时间设置移动基础姿态（x、y、航向角）。

当必须通过 time_from_start_s 协调到达时间时，请使用此重载。

参数

名称类型默认值描述
xSupportsFloat需要传参X坐标（米）
ySupportsFloat需要传参Y坐标（米）
yawSupportsFloat需要传参航向角（弧度）
frame_idstr需要传参目标坐标系 ID。当前推荐值为 "rel(0)"。"rel(0)" 表示 x/y/yaw 目标值相对于当前底盘位姿解释。"base_link"、"odom" 和 "map" 仅为兼容保留，不建议在当前版本中使用，未来版本可能会更改或移除。
reference_frame_idstr需要传参参考坐标系ID
time_from_start_sSupportsFloat需要传参预期到达时间（秒）
is_blockingboolTrue是否阻塞等待完成
timeout_sSupportsFloat15.0超时时间（秒）。

返回值

类型描述
ControlStatus控制状态，指示命令传输的成功或失败

设置底盘速度（set_base_velocity）​

def set_base_velocity(
    linear_velocity: list[float],
    angular_velocity: list[float],
    duration_s: SupportsFloat = 0.0
) -> ControlStatus

设置移动基础速度命令。

命令机器人的移动底座以指定的线速度和角速度移动。速度在机器人的基坐标系中表示。

参数

名称类型默认值描述
linear_velocitylist[float]需要传参线速度（米/秒），在底座坐标系中表示。
顺序：{vx, vy, vz}
- vx: X 方向线速度（前后）
- vy: Y 方向线速度（左右）
- vz: Z 方向线速度（垂直）
angular_velocitylist[float]需要传参角速度（弧度/秒），在底座坐标系中表示。
顺序：{wx, wy, wz}
- wx: 绕 X 轴角速度（翻滚）
- wy: 绕 Y 轴角速度（俯仰）
- wz: 绕 Z 轴角速度（偏航）
duration_sSupportsFloat0.0速度指令发送窗口，单位秒，默认 0.0。零值只发送一次并返回；正值阻塞调用线程，立即发送一次后以 10Hz 续发，直到窗口结束。负数、非有限值或无法安全表示的时长为非法输入。

返回值

类型描述
ControlStatus发送完成返回 SUCCESS；非法输入返回 INVALID_INPUT；SDK 关闭返回 STOPPED_UNREACHED；其他情况返回初始化、控制器、通信、故障或发布错误。
note

到期或提前退出时均不发送停止指令。实际停止取决于底层看门狗及制动过程；SUCCESS 不代表底盘已停止。

note

发送窗口从首次成功发送后开始计时。控制器切换和发送开销会增加调用耗时。等待时线程休眠；Python 调用释放 GIL。

note

调用期间不要并发发送其他底盘命令；其他命令不会取消本续发循环。需要由调用方控制停止时，请使用单次发送模式。

设置配置（set_config）​

def set_config(service: ConfigService, fields: Sequence[ConfigItem]) -> ControlStatus

为某个服务设置一个或多个配置字段。

若 fields 中任一字段无效，则所有字段均不生效，此调用将返回 ControlStatus::INVALID_INPUT。

此调用仅返回单一的聚合状态，不会指出具体哪个（些）字段失败或失败原因。若调用未返回 SUCCESS，请检查日志输出。

参数

名称类型默认值描述
serviceConfigService需要传参待编辑配置所属的服务。
fieldsSequence[ConfigItem]需要传参待设置的字段列表，通过 ConfigItem::key 指定。各服务支持的完整键列表、类型及取值范围，请参见 SDK 文档中的 "Set Config Reference" 页面。

返回值

类型描述
ControlStatus控制状态：所有字段均校验通过并设置成功时返回 SUCCESS；字段校验失败时返回 INVALID_INPUT；读写失败时返回 DATA_FETCH_FAILED / PUBLISH_FAIL。
note

调用成功仅表示配置已持久化保存；需重启设备、由所属服务重新加载后才会生效。

设置末端执行器命令（set_end_effector_command）​

def set_end_effector_command(
    poses: Sequence[list[float]],
    end_effector_frames: Sequence[str],
    reference_frames: Sequence[str] = []
) -> ControlStatus

设置用于高频实时控制的 WBC 末端执行器位姿命令（任务轨迹发布）。

poses 中每一行为 [x, y, z, qx, qy, qz, qw]（单位：米，四元数顺序 xyzw）。poses 与 end_effector_frames 的长度必须一致。

参数

名称类型默认值描述
posesSequence[list[float]]需要传参每个末端执行器对应一个位姿；每行格式为 [x, y, z, qx, qy, qz, qw]（单位：米，四元数顺序 xyzw）。
end_effector_framesSequence[str]需要传参每个位姿对应的目标坐标系 id（例如连杆名称）。
reference_framesSequence[str][]每个位姿对应的参考坐标系。省略或传入 [] 时默认对所有位姿使用 "world"。否则长度必须与 poses 一致。常用值："world"（默认）。

返回值

类型描述
ControlStatus控制状态，表示命令发布结果。

设置夹爪命令（set_gripper_command）​

def set_gripper_command(
    end_effector: str,
    width_m: SupportsFloat,
    velocity_mps: SupportsFloat = 0.03,
    effort: SupportsFloat = 5,
    is_blocking: bool = True
) -> ControlStatus

控制夹具张开宽度和力度。

命令夹具以受控的速度和最大夹持力移动到指定的开口宽度。

参数

名称类型默认值描述
end_effectorstr需要传参要控制的夹爪关节组名称（例如 left_gripper、right_gripper）。
width_mSupportsFloat需要传参目标夹爪开口宽度，单位为米 (m)，测量夹爪手指内表面之间的距离。G1 夹爪宽度范围为 0 至 0.12 m。S1 长行程夹爪宽度范围为 0.007 至 0.11 m。S1 短行程夹爪宽度范围为 0.007 至 0.076 m。
velocity_mpsSupportsFloat0.03夹爪闭合/打开速度，单位为米/秒 (m/s)。默认值：0.03 m/s。取值范围大于 0 且小于等于 0.2 m/s。
effortSupportsFloat5最大抓取力，单位为牛顿米 (N·m)。此参数限制施加的扭矩，以防止对抓取物体造成损坏。取值范围大于 0 且小于等于 100。默认值：5 N·m。
is_blockingboolTrue是否阻塞等待完成

返回值

类型描述
ControlStatus控制状态，指示夹爪命令的成功或失败

设置关节命令（set_joint_commands）​

def set_joint_commands(
    joint_commands: Sequence[JointCommand],
    joint_groups: Sequence[str] = [],
    joint_names: Sequence[str] = [],
    time_from_start_s: SupportsFloat = 0.0
) -> ControlStatus

设置用于高频流控制的底层关节指令。

适用于高频指令流（例如，逐帧模型推理输出）。

此 API 不会从当前/起始位置插值到第一个目标位置。控制器会尽可能快地驱动关节朝向每个指令目标位置。

对于标准关节（头部、腿部、手臂），当前版本中只有 JointCommand::position 有效；速度、加速度和力目前被忽略。

对于夹爪关节，位置字段表示夹爪宽度，速度和力字段均受支持且有效。

参数

名称类型默认值描述
joint_commandsSequence[JointCommand]需要传参关节命令列表
joint_groupsSequence[str][]要控制的关节组。支持的组：legs（腿部）、head（头部）、left_arm（左臂）、right_arm（右臂）、gripper（夹爪）、suction_cup（吸盘）。如果 joint_names 也为空，则不能为空，否则返回 INVALID_INPUT。
joint_namesSequence[str][]要控制的具体关节名称。此参数优先于 joint_groups。如果提供了 joint_names，则忽略 joint_groups。如果 joint_groups 也为空，则不能为空，否则返回 INVALID_INPUT。
time_from_start_sSupportsFloat0.0执行将在 time_start_s 秒后开始。（可选，默认值：0.0）

返回值

类型描述
ControlStatus控制状态，指示命令传输的成功或失败
warning

尤其在第一条命令下发时，请避免当前关节角与目标关节角差值过大。角度突变可能导致运动过快并带来安全风险。

批量设置关节命令（set_joint_commands_batch）​

def set_joint_commands_batch(trajectory: Trajectory) -> ControlStatus

以批处理模式设置关节命令（非阻塞） 实时控制模式下设置多个关节命令轨迹点，支持一次性提交多个时间点的轨迹控制命令。

提供非阻塞高频轨迹执行接口。与set_joint_commands类似，但支持批量轨迹控制，适用于VLA推理批量输出等场景。

参数

名称类型默认值描述
trajectoryTrajectory需要传参包含关节命令路点的轨迹数据结构。必须指定 trajectory.joint_groups 或 trajectory.joint_names；如果两者都为空，则返回 INVALID_INPUT。每个 TrajectoryPoint 包含 time_from_start 和关节命令列表。关节命令包括位置（弧度）、速度（弧度/秒）、加速度（弧度/秒²）、作用力（牛·米）、Kp（位置增益）和 Kd（速度增益）。

返回值

类型描述
ControlStatus控制状态，指示命令提交的成功或失败。立即返回，不等待执行完成（非阻塞）。
warning

每个 TrajectoryPoint.joint_command_vec 的顺序必须与 trajectory.joint_names 定义的关节顺序或 trajectory.joint_groups 的展开顺序一致。

设置关节位置（set_joint_positions）​

def set_joint_positions(
    joint_positions: list[float],
    joint_groups: Sequence[str] = [],
    joint_names: Sequence[str] = [],
    is_blocking: bool = True,
    speed_rad_s: SupportsFloat = 0.2,
    timeout_s: SupportsFloat = 15.0
) -> ControlStatus

按名称设置指定关节组的目标关节位置（用于低频关键帧/姿态转换） 命令机器人将指定关节移动到目标位置。

该运动以具有可配置速度限制的平滑轨迹执行。

参数

名称类型默认值描述
joint_positionslist[float]需要传参目标关节位置
joint_groupsSequence[str][]要控制的关节组名称。支持的组：腿部、头部、左臂、右臂。如果 joint_names 也为空，则不能为空，否则返回 INVALID_INPUT。
joint_namesSequence[str][]要控制的具体关节名称。此参数优先于 joint_groups。如果提供了 joint_names，则忽略 joint_groups。如果 joint_groups 也为空，则不能为空，否则返回 INVALID_INPUT。
is_blockingboolTrue是否阻塞等待完成。true：阻塞直到完成或超时；false：发送后立即返回。
speed_rad_sSupportsFloat0.2最大运动速度（弧度/秒）
timeout_sSupportsFloat15.0超时时间（秒）。

返回值

类型描述
ControlStatus控制状态，指示运动命令的成功或失败
warning

此 API 不适合高频率的逐帧运动控制。

启动控制器（start_controller）​

def start_controller(group_name: str = 'all') -> ControlStatus

开始控制器执行。

激活控制器以开始发送命令。与 stop_controller 相反。需要事先获得硬件权限（获取）。

参数

名称类型默认值描述
group_namestr'all'要启动的控制器组名称

返回值

类型描述
ControlStatus控制状态，指示启动操作的成功或失败

紧急停止底盘（stop_base）​

def stop_base() -> ControlStatus

紧急停止移动底座运动。

立即命令移动基地停止一切运动。这是一项安全功能，当需要立即停止基本运动时应使用。

返回值

类型描述
ControlStatus控制状态，指示命令传输的成功或失败

停止控制器（stop_controller）​

def stop_controller(group_name: str = 'all') -> ControlStatus

停止控制器执行。

停止命令执行但保留硬件权限。与 start_controller 相反。

参数

名称类型默认值描述
group_namestr'all'要停止的控制器组名称

返回值

类型描述
ControlStatus控制状态，指示停止操作的成功或失败

停止轨迹执行（stop_trajectory_execution）​

def stop_trajectory_execution() -> ControlStatus

停止所有当前正在执行的关节轨迹。

立即停止执行所有关节组中的所有活动关节轨迹。停止后关节将保持当前位置。

返回值

类型描述
ControlStatus控制状态，指示命令传输的成功或失败

订阅视频流数据（subscribe_video_data）​

def subscribe_video_data(camera_id: SensorType, callback: Callable) -> SensorStatus

订阅指定相机的 H.264 编码视频帧。

为一个 H.264 视频流注册回调函数。用户回调函数由内部 SDK 调度线程执行，不会阻塞中间件接收回调线程。

参数

名称类型默认值描述
camera_idSensorType需要传参要订阅的相机传感器ID。
callbackCallable需要传参回调函数签名：void(dict video_data)。

返回值

类型描述
SensorStatus如果回调已注册，则返回 SUCCESS。
note

必须通过 enable_sensor_set 在初始化时启用相机传感器。

note

保持回调函数简短且非阻塞。长时间运行的任务可能会延迟此订阅的视频帧获取。

切换控制器（switch_controller）​

def switch_controller(controller_name: str) -> ControlStatus

切换活动控制器策略。

将硬件控制切换到新的策略。请求会发送到 WBCS 控制器管理器，由其执行安全切换，并在接受请求后启动目标控制器。

参数

名称类型默认值描述
controller_namestr需要传参控制器名称字符串，例如 "chassis_pose_ctrl"。

返回值

类型描述
ControlStatus若 WBCS 接受切换，则返回 ControlStatus::SUCCESS；控制器名称未知时返回 ControlStatus::INVALID_INPUT；WBCS 客户端不可用时返回 ControlStatus::INIT_FAILED；5 秒内未收到响应时返回 ControlStatus::TIMEOUT；响应中包含任何控制器命令错误时返回 ControlStatus::FAULT。
note

WBCS 会强制执行控制器优先级。当 BYPASS 控制器的优先级高于目标 PVT 控制器时，无法直接切换到 PVT。若要恢复到 PVT，请依次调用 stop_controller(group_name)、release_controller(group_name)、acquire_controller(pvt_controller) 和 start_controller(group_name)。

注销末端工具原始数据回调（unregister_endtool_raw_callback）​

def unregister_endtool_raw_callback(handle: SupportsInt) -> bool

注销末端工具原始数据回调。

此方法返回后，已经开始执行的回调仍可能继续直至完成。

参数

名称类型默认值描述
handleSupportsInt需要传参register_endtool_raw_callback() 返回的句柄。

返回值

类型描述
bool若句柄存在并已成功移除，则返回 true。
note

此方法返回后，已经开始执行的回调仍可能继续直至完成。

停止订阅视频流数据（unsubscribe_video_data）​

def unsubscribe_video_data(camera_id: SensorType) -> SensorStatus

取消订阅指定相机的 H.264 编码视频帧。

清除此前通过 subscribe_video_data 为该相机注册的所有用户回调。内部 SDK 读取器、环形缓冲区和调度线程将继续运行，以避免重复创建和销毁线程及资源。

参数

名称类型默认值描述
camera_idSensorType需要传参要取消订阅的摄像头传感器ID。

返回值

类型描述
SensorStatus如果回调已清除，则为SUCCESS。

等待关机（wait_for_shutdown）​

def wait_for_shutdown() -> None

阻塞直到关闭完成。

阻塞调用线程直到所有模块都正常关闭完毕。作为关闭序列的第二步调用，在 request_shutdown() 之后、destroy() 之前。

note

当 is_running() 变为 false 时此函数将返回。

全身与底盘归零（zero_whole_body_and_base）​

def zero_whole_body_and_base(
    base_zero_pose: Pose,
    is_blocking: bool = True,
    leg_head_speed_rad_s: SupportsFloat = 0.2,
    leg_head_timeout_s: SupportsFloat = 15.0,
    params: Parameter = None
) -> tuple[MotionStatus, ControlStatus]

一键归零：将全身关节回零，并将底盘位姿回到零位。

该接口会调用 move_whole_body_joint_zero 完成关节归零，并将底盘目标位姿设为零。若 params 为空指针，则使用 default_param。

参数

名称类型默认值描述
base_zero_posePose需要传参-
is_blockingboolTrue-
leg_head_speed_rad_sSupportsFloat0.2-
leg_head_timeout_sSupportsFloat15.0-
paramsParameterNone-

返回值

类型描述
tuple[MotionStatus, ControlStatus]-

全身与底盘归零（zero_whole_body_and_base）​

def zero_whole_body_and_base(
    frame_id: str = 'odom',
    reference_frame_id: str = 'odom',
    is_blocking: bool = True,
    leg_head_speed_rad_s: SupportsFloat = 0.2,
    leg_head_timeout_s: SupportsFloat = 15.0,
    params: Parameter = None
) -> tuple[MotionStatus, ControlStatus]

一键归零：通过可选坐标系将全身关节归零，并将底座（x、y、航向角）归零。

参数

名称类型默认值描述
frame_idstr'odom'坐标系ID
reference_frame_idstr'odom'参考坐标系ID
is_blockingboolTrue是否阻塞等待完成
leg_head_speed_rad_sSupportsFloat0.2腿部和头部关节速度（弧度/秒）
leg_head_timeout_sSupportsFloat15.0腿部和头部运动超时（秒）
paramsParameterNone额外参数

返回值

类型描述
tuple[MotionStatus, ControlStatus]-

运动规划与执行（GalbotMotion）​

Galbot 机器人的统一运动规划和控制接口。

该接口提供全面的机器人运动控制 API，包括： - 正向和逆向运动学计算 - 单链和多链轨迹规划 - 碰撞检测（自碰撞和环境） - 工具和障碍物管理 - 全身协调运动规划使用 GalbotMotion::get_instance(MachineType) 获取特定平台 (G1/G3/S1) 的实例。所有角度单位为弧度，线性单位为米（SI 标准）。四元数必须归一化：√(x² + y² + z² + w²) = 1。

添加障碍物（add_obstacle）​

def add_obstacle(
    obstacle_id: str,
    obstacle_type: str,
    pose: list[float],
    scale: list[float] = [0.0, 0.0, 0.0],
    key: str = '',
    target_frame: str = 'world',
    ee_frame: str = 'ee_base',
    reference_joint_positions: list[float] = [],
    reference_base_pose: list[float] = [],
    ignore_collision_link_names: Sequence[str] = [],
    safe_margin: SupportsFloat = 0.0,
    resolution: SupportsFloat = 0.01
) -> MotionStatus

将碰撞对象加载到环境中。

将几何或基于网格的障碍物插入环境中以避免碰撞。障碍可以是静态的（世界坐标系下固定的）或与机器人相关的。支持原始形状、网格、点云和深度图像。

参数

名称类型默认值描述
obstacle_idstr需要传参障碍物唯一标识符（场景中不得重复），后续可用于删除或更新。
obstacle_typestr需要传参障碍物几何类型
poselist[float]需要传参障碍物位姿：[x, y, z, qx, qy, qz, qw]（米，四元数），相对于 target_frame。
scalelist[float][0.0, 0.0, 0.0]几何尺寸（米）：
- box: [长度, 宽度, 高度]
- sphere: [半径, -, -]
- cylinder: [半径,高度,-]
- mesh/point_cloud: 缩放因子
keystr''类型特定数据：
- mesh/point_cloud: 文件路径（例如 "/path/to/model.stl"）
- depth_image: 相机源数据
- robot_state: 机器人状态数据
target_framestr'world'位姿参考坐标系（默认 "world"），可为 "world"、"base_link" 或运动链名称（如 "left_arm"）。
ee_framestr'ee_base'当 target_frame 为运动链名称时，指定链上参考帧（如 "ee_base"、"camera_base"、"camera_object"）。
reference_joint_positionslist[float][]用于计算坐标变换的机器人关节状态（弧度）。为空时使用当前机器人状态。
reference_base_poselist[float][]地图坐标系下的机器人基座位姿：[x, y, z, qx, qy, qz, qw]。为空时使用当前定位。
ignore_collision_link_namesSequence[str][]忽略碰撞的连杆名称列表
safe_marginSupportsFloat0.0安全距离缓冲（米）。当距离 < safe_margin 时判定碰撞，默认 0。
resolutionSupportsFloat0.01复杂几何体（mesh/point cloud/depth image）的离散化分辨率（米），默认 0.01。

返回值

类型描述
MotionStatus运动状态：- 成功：障碍物添加成功 - 无效输入：无效的障碍物ID（重复）、类型或参数 - 故障：处理几何形状或添加到场景失败
note

点云说明：point_cloud 指通过此 API 显式加载的点云障碍物（通常来自文件/离线数据）。它与导航系统维护的点云地图不同，GalbotMotion 不会自动订阅或与 galbotNav 的点云地图同步碰撞检测。

note

障碍物会持续存在，直到显式删除或清空。

note

对于移动障碍物，请在新位姿处删除并重新添加（当前无更新方法）。

warning

较大的 safe_margin（安全边距）值可能会过度约束规划空间，导致无法找到可行解，请谨慎使用。

附加目标对象（attach_target_object）​

def attach_target_object(
    obstacle_id: str,
    obstacle_type: str,
    pose: list[float],
    scale: list[float] = [0.0, 0.0, 0.0],
    key: str = '',
    target_frame: str = 'world',
    ee_frame: str = 'ee_base',
    reference_joint_positions: list[float] = [],
    reference_base_pose: list[float] = [],
    ignore_collision_link_names: Sequence[str] = [],
    safe_margin: SupportsFloat = 0.0,
    resolution: SupportsFloat = 0.01
) -> MotionStatus

将碰撞物体附加到机器人上（例如，抓取的物体）。与 add_obstacle() 类似，但对象随机器人移动（连接到连杆/运动链），用于表示抓取的物体、传感器或有效载荷。

在运动过程中，对象相对于连接坐标系的姿态保持不变。

参数

名称类型默认值描述
obstacle_idstr需要传参要移除的障碍物ID
obstacle_typestr需要传参障碍物几何类型
poselist[float]需要传参物体位姿：[x, y, z, qx, qy, qz, qw]（米，四元数），在附着时相对于 target_frame。
scalelist[float][0.0, 0.0, 0.0]几何尺寸（米）：box 为 [length, width, height]；sphere 为 [radius, -, -]；cylinder 为 [radius, height, -]。
keystr''障碍物唯一标识符
target_framestr'world'附着参考坐标系（默认 "world"）；抓取物体场景通常填写运动链名称（如 "left_arm"）。
ee_framestr'ee_base'当 target_frame 为运动链名称时，指定链上参考帧（如 "ee_base"、"camera_base" 等）。
reference_joint_positionslist[float][]用于计算附着变换的机器人关节状态（弧度）。为空时使用当前机器人状态。
reference_base_poselist[float][]地图坐标系下的机器人基座位姿：[x, y, z, qx, qy, qz, qw]。为空时使用当前定位。
ignore_collision_link_namesSequence[str][]忽略碰撞的连杆名称列表
safe_marginSupportsFloat0.0安全距离缓冲（米），默认 0。
resolutionSupportsFloat0.01复杂几何体的离散化分辨率（米），默认 0.01。

返回值

类型描述
MotionStatus运动状态：SUCCESS（成功）、INVALID_INPUT（无效输入）或 FAULT（故障）
note

点云说明：与 add_obstacle() 相同。此处的 point_cloud 是显式加载的点云对象，不会自动与任何导航端点云地图同步。

note

附加的对象随机器人移动；其碰撞几何体自动更新。

note

通常用于抓取和放置：抓取后附加目标对象，释放后分离。

warning

请确保 ignore_collision_link_names 包含抓取连杆，以避免误判为碰撞。

附加工具（attach_tool）​

def attach_tool(chain: str, tool: str) -> MotionStatus

将工具连接到末端执行器。

将工具（夹具、相机、定制末端执行器）加载到运动链上。更新运动学模型和碰撞几何体以包含该工具。

参数

名称类型默认值描述
chainstr需要传参用于连接工具的运动链，仅支持 "left_arm" 和 "right_arm"。
toolstr需要传参工具标识符。该名称必须存在于 get_support_tool_list() 中，但该列表只是当前服务已知的候选范围。请根据指定机器人型号和机械臂的实际末端执行器类型及配置来选择工具。

返回值

类型描述
MotionStatus运动状态：- 成功：附加工具成功 - 无效输入：无效的运动链或工具名称 - 故障：附加工具失败
note

工具变换和碰撞几何体必须预先在机器人描述中配置。

note

工具兼容性可能因机器人型号、机械臂及所部署的机器人/MPS 配置而异。因此，get_support_tool_list() 返回的工具并不保证可安装到每一条受支持的运动链上。

note

安装新工具会自动卸下该运动链上此前已安装的工具。

note

对于 set_end_effector_pose()，目标默认仍为法兰。若 target_pose 是工具 TCP，需设置 Parameter::is_tool_pose=true（或调用 Parameter::set_tool_pose(true)）。

note

get_support_tool_list() 返回可安装的工具名称。get_support_ee_frame() 返回带有 frame_id/target_frame 参数的接口所接受的坐标系类型（例如 "EndEffector"、"Camera" 和 "TCP"）。

warning

运动学和碰撞检查将反映附加的工具；请相应更新计划。

检查碰撞（check_collision）​

def check_collision(
    start: Sequence[RobotStates],
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, list[bool]]

检查机器人状态是否存在碰撞。

检查自身碰撞和与环境障碍物的碰撞，支持批量处理。因此，如果需要 Motion 考虑环境障碍物（包括点云），必须显式加载障碍物地图/对象（例如，obstacle_type = point_cloud 且在 key 中提供文件路径）。

注意：将实时感知集成到 galbotMotion 是未来计划，目前内部验证有限。

验证给定机器人配置是否无碰撞。

参数

名称类型默认值描述
startSequence[RobotStates]需要传参起始机器人状态
enable_collision_checkboolTrue是否启用碰撞检查
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, list[bool]]元组（状态，碰撞结果）：
- 状态：检测完成时为 MotionStatus::SUCCESS，否则为错误码
- 碰撞结果：布尔向量（与 start 等长），true 表示检测到碰撞，false 表示无碰撞
note

用于验证计划轨迹或基于采样的规划器。

note

尊重先前添加的障碍物中的 safe_margin（安全边距）设置。

note

尊重先前添加的障碍物中的 safe_margin（安全边距）设置。

检查碰撞详情（check_collision_detail）​

def check_collision_detail(
    robot_states: Sequence[RobotStates],
    is_check_once: bool = False,
    is_log: bool = False,
    params: Parameter = ...
) -> tuple[MotionStatus, list[CollisionInfo]]

检查机器人状态的详细碰撞对。

查询运动学碰撞检测服务，返回当前由 MPS 提供的碰撞对详情。

参数

名称类型默认值描述
robot_statesSequence[RobotStates]需要传参待检查的机器人状态列表；为空时，MPS 检查当前机器人状态。
is_check_onceboolFalseMPS 是否对每个状态执行单次检查。
is_logboolFalseMPS 是否为每个状态输出碰撞检查日志。
paramsParameter...可选参数，目前该接口仅使用 timeout_second。

返回值

类型描述
tuple[MotionStatus, list[CollisionInfo]]元组 (status, collision_infos)：- status：若运动学碰撞请求完成，则为 MotionStatus::SUCCESS - collision_infos：碰撞对详情。collision_type 包含原始 MPS common_str 元数据，包括采样标签及 self/environment 分类。
note
  • collision_type 包含原始 MPS common_str 元数据，包括采样标签及取值为 self 或 env 的碰撞分类。
  • 默认构造的 CollisionInfo 使用 UNKNOWN；MPS 返回的空值则表示为空字符串。

清空障碍物（clear_obstacle）​

def clear_obstacle() -> MotionStatus

从规划场景中移除所有碰撞障碍物。

清除整个障碍物集，将规划场景重置为空（机器人几何体除外）。

返回值

类型描述
MotionStatus-
note

附加的对象（参见 attach_target_object）不会被清除。

note

即使场景已为空，也可以安全调用。

组合规划请求（combine_plan）​

def combine_plan(
    plan_reqs: Sequence[PlanRequest],
    params: PlannerConfig = ...,
    start_state: RobotStates = None
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

将多个异构规划请求组合为单条协调轨迹。

接受一系列 PlanRequest 对象，每个对象指定各自的规划类型（MOTION_PLAN / TRAJ_PLAN / MOVE_LINE）、目标路点以及分段选项。服务器将这些请求组合为一条连续轨迹，各分段之间平滑过渡，且每个分段使用各自的规划算法。

服务器端流程：SDK 发送一个 CombinePlanReq（proto 字段：combine_plan_req），其中包含一系列 SigPlanReq 子请求，每个子请求各自携带 plan_type、目标状态及 PlannerConfig 选项。发送给服务器的 enforce_pass 标志是所有分段 enforce_pass 值的逻辑与（AND）。为 true 时，即使个别分段出现问题，服务器也会尝试继续规划；为 false 时，任意分段失败都会中止整个组合规划。显式设置的分段选项会覆盖顶层 server_options 中的对应字段。服务器将各分段生成的轨迹拼接为单个 RobotTrajectoryVec，并在分段边界处保证 C1 连续性（速度平滑过渡）。若 is_direct_execute=true，组合后的轨迹会被推送到 WBC 队列。

典型使用场景：抓取放置：接近（move_line）-> 抓取（带碰撞检查的 motion_plan）-> 撤离（move_line）；将带碰撞检查的路径分段与仅需快速轨迹的分段混合使用；不同阶段需要不同规划策略的多阶段操作；恢复序列：远离障碍物（motion_plan）-> 返回任务（traj_plan）。

参数

名称类型默认值描述
plan_reqsSequence[PlanRequest]需要传参-
paramsPlannerConfig...-
start_stateRobotStatesNone-

返回值

类型描述
tuple[MotionStatus, dict[str, list[list[float]]]]-
note

服务器保证在分段边界处满足 C1 连续性（速度平滑过渡）。

note

所有分段共享同一条轨迹时间线；各运动链保持时间同步。

warning

MPS 服务器端必须实现 CombinePlanReq 处理逻辑（proto 字段：combine_plan_req = 17）。若服务器版本不支持该处理逻辑，请求将失败。

warning

直接执行时（is_direct_execute=true），请避免传入 start_state。

分离目标对象（detach_target_object）​

def detach_target_object(obstacle_id: str) -> MotionStatus

从机器人上分离物体（例如，释放后）。从机器人上移除附着的物体。通常在释放抓取的对象后调用。

该对象被完全从规划场景中移除（不转换为静态障碍物）。

参数

名称类型默认值描述
obstacle_idstr需要传参-

返回值

类型描述
MotionStatus-
note

如需在移除后将对象作为静态障碍物保留在场景中，请使用 clear_obstacle()。

分离工具（detach_tool）​

def detach_tool(chain: str) -> MotionStatus

将当前工具与末端执行器分离。

相应地更新运动学模型和碰撞几何体。

参数

名称类型默认值描述
chainstr需要传参要分离工具的运动链，仅支持 "left_arm" 和 "right_arm"。

返回值

类型描述
MotionStatus运动状态：- 成功：分离工具成功 - 无效输入：无效的运动链名称或未附加工具 - 故障：分离工具失败
note

如果没有工具附加，则操作成功但无效果。

正向运动学（forward_kinematics）​

def forward_kinematics(
    target_frame: str,
    reference_frame: str = 'base_link',
    joint_state: dict] = {},
    params: Parameter = ...
) -> tuple[MotionStatus, list[float]]

计算目标连杆的正向运动学。

计算给定关节配置的指定连杆的笛卡尔姿态。对于确定末端执行器位置、验证配置或计算中间连杆姿态很有用。

参数

名称类型默认值描述
target_framestr需要传参目标坐标系
reference_framestr'base_link'姿态表达所用的坐标系。有效值为 "world"、"map"、"base_link"（或其别名 "base"），或 get_support_links() 返回的连杆名称。默认值："base_link"。
joint_statedict]{}关节名到关节位置的映射；默认空字典表示使用当前机器人关节状态。
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, list[float]]元组（状态，位姿向量）：
- 状态：成功时为 MotionStatus::SUCCESS，否则为错误码
- 位姿向量：[x, y, z, qx, qy, qz, qw]（米，四元数），失败时为空
note

关节角度以弧度为单位，输出位姿以米为单位的单位四元数表示。

warning

target_frame 必须是 URDF 模型中的有效连杆。

基于状态的正向运动学（forward_kinematics_by_state）​

def forward_kinematics_by_state(
    target_frame: str,
    reference_robot_states: RobotStates = None,
    reference_frame: str = 'base_link',
    params: Parameter = ...
) -> tuple[MotionStatus, list[float]]

使用完整的机器人状态计算正向运动学。

与 forward_kinematics() 类似，但接受 RobotStates 对象来指定完整的机器人配置（全身关节+底座姿态）。

参数

名称类型默认值描述
target_framestr需要传参目标坐标系
reference_robot_statesRobotStatesNone参考机器人起始状态
reference_framestr'base_link'姿态表达所用的坐标系。有效值为 "world"、"map"、"base_link"（或其别名 "base"），或 get_support_links() 返回的连杆名称。默认值："base_link"。
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, list[float]]元组（状态，位姿向量）：
- 状态：成功时为 MotionStatus::SUCCESS，否则为错误码
- 位姿向量：[x, y, z, qx, qy, qz, qw]（米，四元数），失败时为空
note

在不修改实际状态的情况下为假设状态计算正向运动学时非常有用。

获取已构建障碍物列表（get_built_obstacles_list）​

def get_built_obstacles_list() -> list[str]

获取当前加载的障碍物 ID 列表。

返回值

类型描述
list[str]-

获取运动链关节名称（get_chain_joint_names）​

def get_chain_joint_names(chain_name: str) -> list[str]

获取指定运动链的关节名称。

返回该运动链在机器人模型中配置的关节名称有序列表。

参数

名称类型默认值描述
chain_namestr需要传参-

返回值

类型描述
list[str]-

获取链关节状态（get_chain_joint_state）​

def get_chain_joint_state() -> dict[str, list[float]]

获取所有运动链的当前关节配置。

检索每条链的关节状态，将整体配置分解为各个链的贡献。

返回值

类型描述
dict[str, list[float]]-
note

关节向量大小因链的自由度而异。

按类型获取配置（get_config_by_type）​

def get_config_by_type(config_type: str) -> tuple[MotionStatus, MotionPlanConfig]

按类型获取 MPS 配置（结果通过 MotionPlanConfig.common_str 返回）。

参数

名称类型默认值描述
config_typestr需要传参-

返回值

类型描述
tuple[MotionStatus, MotionPlanConfig]-

获取末端执行器姿态（get_end_effector_pose）​

def get_end_effector_pose(
    end_effector_frame: str,
    reference_frame: str = 'base_link'
) -> tuple[MotionStatus, list[float]]

从机器人状态获取当前末端执行器姿态。

使用机器人实时关节状态，通过 MPS 正向运动学计算当前笛卡尔姿态。要求该连杆已在机器人 URDF 模型中定义。

参数

名称类型默认值描述
end_effector_framestr需要传参末端执行器坐标系
reference_framestr'base_link'姿态表达所用的坐标系。有效值为 "world"、"map"、"base_link"（或其别名 "base"），或 get_support_links() 返回的连杆名称。默认值："base_link"。

返回值

类型描述
tuple[MotionStatus, list[float]]元组（状态，位姿向量）：
- 状态：成功时为 MotionStatus::SUCCESS；错误码包括 DATA_FETCH_FAILED（获取关节状态失败）、INVALID_INPUT（坐标系名称无效）
- 位姿向量：[x, y, z, qx, qy, qz, qw]（米，四元数），失败时为空
note

反映当前实际的机器人状态（非计划状态）。

note

当已知确切的 URDF 连杆名称时使用此方法。对于法兰、相机或已连接工具 TCP 等与运动链相关的语义坐标系，请改用 get_end_effector_pose_on_chain()。

获取指定链末端执行器姿态（get_end_effector_pose_on_chain）​

def get_end_effector_pose_on_chain(
    chain_name: str,
    frame_id: str = 'EndEffector',
    reference_frame: str = 'base_link'
) -> tuple[MotionStatus, list[float]]

获取特定运动链的当前末端执行器姿态。

通过链名称和坐标系类型检索末端执行器姿态的便捷方法，无需知道 URDF 中的确切连杆名称。

参数

名称类型默认值描述
chain_namestr需要传参链名称
frame_idstr'EndEffector'运动链坐标系类型："EndEffector"、"Camera" 或 "TCP"
reference_framestr'base_link'姿态表达所用的坐标系。有效值为 "world"、"map"、"base_link"（或其别名 "base"），或 get_support_links() 返回的连杆名称。默认值："base_link"。

返回值

类型描述
tuple[MotionStatus, list[float]]元组 (状态, 位姿向量)：状态（成功时为 MotionStatus::SUCCESS，否则为错误码），位姿向量 [x, y, z, qx, qy, qz, qw]（单位：米，四元数），失败时为空
note

内部将 chain_name + frame_id 映射到实际的 URDF 连杆名称。

note

当希望使用语义坐标系而无需知道 URDF 连杆名称时使用此方法。支持的坐标系类型包括 "EndEffector"（运动链法兰）、"Camera" 以及 "TCP"/"ToolPose"（已连接工具的 TCP）。查询 TCP 前必须先连接工具，否则调用返回 MotionStatus::INVALID_INPUT。

note

解析出的坐标系最终通过与 get_end_effector_pose() 相同的正运动学路径查询，区别在于此重载会先解析 chain_name + frame_id。

获取雅可比矩阵（get_jacobian）​

def get_jacobian(
    chain_name: str,
    target_frame: str = 'EndEffector',
    reference_frame: str = 'base_link',
    joint_state: dict] = {},
    params: Parameter = ...
) -> tuple[MotionStatus, list[list[float]]]

计算指定运动链的雅可比矩阵

参数

名称类型默认值描述
chain_namestr需要传参链名称
target_framestr'EndEffector'用于计算雅可比矩阵的目标连杆。可选值："EndEffector"（默认）：链的末端执行器安装连杆，即 "<chain_name>_end_effector_mount_link"；或 get_support_links() / get_link_names() 返回的任意有效 URDF 连杆名称。不支持 "Tool"（TCP）：运动学服务仅按连杆名称计算雅可比矩阵，不具备工具位姿能力，传入 "Tool" 将返回 MotionStatus::UNSUPPORTED_FUNCRION。
reference_framestr'base_link'参考坐标系。有效值为 "world"、"map" 和 "base_link"。默认值："base_link"。
joint_statedict]{}关节状态对象，包含当前关节位置
paramsParameter...运动学参数配置

返回值

类型描述
tuple[MotionStatus, list[list[float]]]返回 numpy 数组，形状为 [6 x DOF]，表示末端执行器在参考坐标系下的雅可比矩阵
note

返回雅可比矩阵，形状为 [6 x DOF]，表示关节空间到任务空间的线性映射

note

用于运动学分析、力控、奇异值分解等场景

note

可使用 get_support_links() / get_link_names() 获取有效的 target_frame 连杆名称。

通过状态获取雅可比矩阵（get_jacobian_by_state）​

def get_jacobian_by_state(
    chain_name: str,
    target_frame: str = 'EndEffector',
    reference_frame: str = 'base_link',
    reference_robot_states: RobotStates = None,
    params: Parameter = ...
) -> tuple[MotionStatus, list[list[float]]]

通过给定的机器人状态计算指定运动链的雅可比矩阵

参数

名称类型默认值描述
chain_namestr需要传参链名称
target_framestr'EndEffector'用于计算雅可比矩阵的目标连杆。默认为 "EndEffector"（链的末端执行器连杆，即 "<chain_name>_end_effector_mount_link"），也可以是 get_support_links() 返回的任意有效 URDF 连杆名称。不支持 "Tool"（TCP），传入将返回 MotionStatus::UNSUPPORTED_FUNCRION（参见 get_jacobian()）。
reference_framestr'base_link'参考坐标系。有效值为 "world"、"map" 和 "base_link"。默认值："base_link"。
reference_robot_statesRobotStatesNone机器人状态，包含关节位置信息
paramsParameter...运动学参数配置

返回值

类型描述
tuple[MotionStatus, list[list[float]]]元组（状态，雅可比矩阵）：
- 状态：成功时为 MotionStatus::SUCCESS，否则为错误码
- 雅可比矩阵：6xN 矩阵（N 为链自由度），失败时为空
note

返回雅可比矩阵，形状为 [6 x DOF]

def get_link_names(only_end_effector: bool = False) -> list[str]

从运动学模型中获取机器人连杆名称。

检索机器人 URDF 模型中定义的连杆名称列表，可用于过滤末端执行器连杆或返回所有连杆。

参数

名称类型默认值描述
only_end_effectorboolFalse是否仅返回末端执行器连杆，true 仅返回末端执行器/工具连杆，false 返回所有连杆（包括底座、中间连杆等），默认 false（所有连杆）

返回值

类型描述
list[str]连杆名称字符串向量（如果检索失败则为空）
note

基于连杆没有子连杆来检测末端执行器。

note

用于正向运动学查询或 TF 帧验证。

获取运动规划配置（get_motion_plan_config）​

def get_motion_plan_config() -> tuple[MotionStatus, MotionPlanConfig]

获取当前运动规划配置。

检索活动规划器配置，包括速度/加速度限制和规划算法参数。

返回值

类型描述
tuple[MotionStatus, MotionPlanConfig]-
note

用于检查当前限制或保存/恢复配置。

获取机器人状态（get_robot_states）​

def get_robot_states() -> RobotStates

获取当前完整的机器人状态。

检索当前全身关节配置和移动底座姿态。代表机器人的完整运动状态。

返回值

类型描述
RobotStates-
note

反映实际机器人状态（来自传感器反馈/状态估计）。

note

用作规划操作的种子/参考。

获取支持的链（get_supported_chains）​

def get_supported_chains() -> set[str]

获取支持的运动链名称列表（例如 left_arm、right_arm）。

返回值

类型描述
set[str]-

获取支持的末端执行器坐标系（get_supported_ee_frames）​

def get_supported_ee_frames() -> set[str]

获取支持的末端执行器坐标系标识符集。

返回值

类型描述
set[str]-

获取支持的坐标系（get_supported_frames）​

def get_supported_frames() -> set[str]

获取支持的参考坐标系名称集。

返回值

类型描述
set[str]-
def get_supported_links() -> set[str]

获取支持的连杆名称列表（正向运动学/逆向运动学的 URDF 连杆名称）。

返回值

类型描述
set[str]-

获取支持的障碍物类型（get_supported_obstacle_types）​

def get_supported_obstacle_types() -> set[str]

获取支持的障碍物类型集（例如盒子、球体、圆柱体、网格）。

返回值

类型描述
set[str]-

获取支持的工具列表（get_supported_tool_list）​

def get_supported_tool_list() -> set[str]

获取 attach_tool 支持的工具名称列表。

返回值

类型描述
set[str]-

初始化（init）​

def init() -> bool

初始化运动规划系统和通信接口。

必须在任何其他 API 函数之前调用。初始化内部通信中间件，加载机器人运动学模型，并建立与控制服务的连接。

返回值

类型描述
bool-
note

可安全多次调用；成功后的后续调用返回第一次初始化的结果。

warning

如果 init() 返回 false，则所有其他 API 调用将失败。

逆向运动学（inverse_kinematics）​

def inverse_kinematics(
    target_pose: list[float],
    chain_names: Sequence[str],
    target_frame: str = 'EndEffector',
    reference_frame: str = 'base_link',
    initial_joint_positions: dict] = {},
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[float]]]

计算目标笛卡尔姿态的逆运动学。

求解实现指定末端执行器姿态的关节配置。支持单链 IK（仅手臂）或协调多链 IK（手臂 + 躯干/腿）。

参数

名称类型默认值描述
target_poselist[float]需要传参目标笛卡尔位姿：[x, y, z, qx, qy, qz, qw]（米，四元数）。
chain_namesSequence[str]需要传参要解决逆运动学的运动链名称列表
target_framestr'EndEffector'运动链上的坐标系："EndEffector"、"Camera" 或 "TCP"
reference_framestr'base_link'姿态指定所用的坐标系。有效值为 "world"、"map" 和 "base_link"。默认值："base_link"。
initial_joint_positionsdict]{}初始关节位置猜测
enable_collision_checkboolTrue是否启用碰撞检查
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, dict[str, list[float]]]元组（状态，解映射）：
- 状态：若可求解则为 MotionStatus::SUCCESS，否则为错误码
- 解映射：{chain_name -> joint_angles}（弧度），失败时为空
note

IK 可能有多个解；返回第一个有效的解。

note

种子配置影响收敛速度和哪个解被选中。

warning

如果目标在工作空间之外或处于奇异配置，则无法保证有解。

基于状态的逆向运动学（inverse_kinematics_by_state）​

def inverse_kinematics_by_state(
    target_pose: list[float],
    chain_names: Sequence[str],
    target_frame: str = 'EndEffector',
    reference_frame: str = 'base_link',
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[float]]]

使用完整的机器人状态作为种子计算逆运动学。

与 inverse_kinematics() 类似，但接受 RobotStates 来指定种子配置，从而允许精确控制整个机器人状态。

参数

名称类型默认值描述
target_poselist[float]需要传参目标笛卡尔位姿：[x, y, z, qx, qy, qz, qw]（米，四元数）。
chain_namesSequence[str]需要传参要解决逆运动学的运动链名称列表
target_framestr'EndEffector'运动链上的坐标系："EndEffector"、"Camera" 或 "TCP"
reference_framestr'base_link'姿态指定所用的坐标系。有效值为 "world"、"map" 和 "base_link"。默认值："base_link"。
reference_robot_statesRobotStatesNone参考机器人起始状态
enable_collision_checkboolTrue是否启用碰撞检查
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, dict[str, list[float]]]元组（状态，解映射）：
- 状态：若可求解则为 MotionStatus::SUCCESS，否则为错误码
- 解映射：{chain_name -> joint_angles}（弧度），失败时为空
note

在不修改实际状态的情况下为假设状态离线规划时非常有用。

通用逆向运动学（inverse_kinematics_general）​

def inverse_kinematics_general(
    target_waypoint: Sequence[MotionPlanChainTarget],
    reference_robot_states: RobotStates = None,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, JointStates]]

使用通用的多链目标描述计算逆运动学。

采用较新的 MotionPlanTarget 结构（inverse_kinematic_general_req），在单次请求中支持混合链目标与辅助链设置。

参数

名称类型默认值描述
target_waypointSequence[MotionPlanChainTarget]需要传参-
reference_robot_statesRobotStatesNone-
paramsParameter...-

返回值

类型描述
tuple[MotionStatus, dict[str, JointStates]]-

轨迹规划（motion_plan）​

def motion_plan(
    target: RobotStates,
    start: RobotStates = None,
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

规划单个运动链的轨迹。

This is the high-level single-target overload. target must be a PoseState or JointStates instance whose chain_name identifies the chain to plan. It dispatches to traj_plan() by default, or to move_line() when params.move_line is True.

参数

名称类型默认值描述
targetRobotStates需要传参目标位姿
startRobotStatesNone可选的运动链起始状态。若提供，必须是 JointStates 实例；其他 RobotStates 类型会返回 MotionStatus::INVALID_INPUT。传入 nullptr/None 时使用机器人当前状态。直接执行时应保持为 nullptr/None，以免与机器人实际状态冲突。
reference_robot_statesRobotStatesNone参考机器人起始状态
enable_collision_checkboolTrue是否启用碰撞检查
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, dict[str, list[list[float]]]]元组（状态，轨迹映射）：
- 状态：规划成功时为 MotionStatus::SUCCESS，否则为错误码
- 轨迹映射：{chain_name -> waypoint_list}，其中 waypoint_list 为关节配置序列（弧度）
note

碰撞语义：GalbotMotion 不提供实时障碍物订阅；规划期间仅考虑通过 API 添加的障碍物。

warning

target 必须是 PoseState 或 JointStates；传递 base RobotStates 将导致 INVALID_INPUT 错误。

多路点运动规划（motion_plan）​

def motion_plan(
    waypoints: Sequence[Sequence[MotionPlanChainTarget]],
    params: PlannerConfig = ...,
    start_state: RobotStates = None
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

通过运动规划服务器规划一条经过多个路点且考虑碰撞的路径。

向服务器发送 MotionPlanReq，服务器调用基于采样的规划器（默认：EITstar/RRT 变体）搜索无碰撞的几何路径，再交由轨迹规划器进行时间参数化，生成速度/加速度/加加速度曲线。

服务器端流程：将路点转换为内部的 RobotStates 与 PlannerConfig。单链时调用 singleChainMotionPlan()；多链时调用 multiChainMotionPlan()。几何路径在执行前总会进行时间参数化。若 is_check_collision=true（默认），则校验碰撞、关节限位与速度。若 is_direct_execute=true，轨迹会被推送到 WBC 队列执行。

This is the low-level server-facing overload. waypoints can describe one or more coordinated chains. The server performs sampling-based geometric path search and then time-parameterizes the result with the configured velocity, acceleration, and jerk limits.

参数

名称类型默认值描述
waypointsSequence[Sequence[MotionPlanChainTarget]]需要传参路点序列；每个路点为 MotionPlanChainTarget 向量（每条待协调的运动链对应一个目标），支持多链协调。警告："leg" 运动链目前不支持作为 chain_name 或出现在 assist_chains 中，否则将返回 INVALID_INPUT。
paramsPlannerConfig...控制执行与规划行为的 PlannerConfig：is_direct_execute 为 true 时，规划完成后将轨迹下发至 WBC 执行；is_check_collision 为 true 时，在执行前校验轨迹（默认：true）；enable_env_collision_check 用于启用环境障碍物碰撞检测；actuate_type 为每个笛卡尔目标全局添加所选的辅助运动链。此外还控制参考坐标系、工具位姿等。
start_stateRobotStatesNone可选的显式起始状态；为 nullptr 时使用当前机器人状态。警告：直接执行时（is_direct_execute=true），请保留为 nullptr，以避免种子状态与实际机器人状态冲突。

返回值

类型描述
tuple[MotionStatus, dict[str, list[list[float]]]]元组（状态，轨迹映射）：
- 状态：规划成功时为 MotionStatus::SUCCESS，否则为错误码
- 轨迹映射：{chain_name -> trajectory}，trajectory 为沿时间参数化路径的关节配置序列（弧度）
note

碰撞语义：碰撞检查针对自身碰撞以及通过 add_obstacle() / attach_target_object() 加载的环境障碍物进行；不会自动集成实时感知数据（例如导航点云地图）。

warning

不支持将 "leg" 运动链用作 chain_name 或放入 assist_chains。直接执行时，通常应将 start_state 保留为 None，以避免与机器人实际状态冲突。

多路点轨迹规划（motion_plan_multi_waypoints）​

def motion_plan_multi_waypoints(
    target: RobotStates,
    waypoint_poses: Sequence[list[float]],
    start: RobotStates = None,
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

为单个运动链规划一条经过多个路点的轨迹。

target is a PoseState or JointStates template that supplies the waypoint type and chain_name; its stored state values are not used as a goal. waypoint_poses contains the actual Cartesian poses or joint configurations to traverse.

参数

名称类型默认值描述
targetRobotStates需要传参已设置 chain_name 的 PoseState 或 JointStates 模板。
waypoint_posesSequence[list[float]]需要传参PoseState 对应的笛卡尔位姿，或 JointStates 对应的关节配置（弧度）。
startRobotStatesNone可选的运动链起始状态。为 None 时使用当前状态。
reference_robot_statesRobotStatesNone全身规划上下文。为 None 时使用当前状态。
enable_collision_checkboolTrue是否要求轨迹无碰撞。默认为 True。
paramsParameter...规划与执行选项。默认为 default_param。

返回值

类型描述
tuple[MotionStatus, dict[str, list[list[float]]]]tuple[MotionStatus, dict[str, list[list[float]]]]：状态与该运动链的轨迹。
note
  • GalbotMotion 不会自动将实时感知结果导入其碰撞世界。
  • 碰撞检测仅使用自碰撞以及通过 add_obstacle() 或 attach_target_object() 显式加载的环境物体。
  • 规划器生成 C1 连续的运动，因此中间路点可能被平滑过渡而非精确到达。
warning

当中间路点必须精确到达时，请拆分为多次规划。直接执行时，通常应将 start 与 reference_robot_states 保留为 None。

多路点轨迹规划（motion_plan_multi_waypoints）​

def motion_plan_multi_waypoints(
    targets: dict]],
    start: Sequence[RobotStates] = [],
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

通过多个链的路径点规划协调轨迹。

通过路径点序列实现协调的多臂或全身运动。每个链都可以有自己的路点序列，以同步方式执行。

Use this overload for coordinated motion such as bimanual manipulation. Each targets mapping key is a PoseState or JointStates template identifying one chain and waypoint representation; the corresponding value is that chain's waypoint sequence.

参数

名称类型默认值描述
targetsdict]]需要传参多路点目标位姿字典（每个运动链对应一个路点序列）
startSequence[RobotStates][]起始机器人状态
reference_robot_statesRobotStatesNone参考机器人起始状态
enable_collision_checkboolTrue是否启用碰撞检查
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, dict[str, list[list[float]]]]元组（状态，轨迹映射）：
- 状态：规划成功时为 MotionStatus::SUCCESS，否则为错误码
- 轨迹映射：{chain_name -> waypoint_list}（所有运动链）
note

所有链的轨迹在时间上同步以实现协调运动。

warning

直接执行时，通常应将 start 保留为空、reference_robot_states 保留为 None，以避免与机器人实际状态冲突。

直线运动规划（move_line）​

def move_line(
    waypoints: Sequence[Sequence[MotionPlanChainTarget]],
    params: PlannerConfig = ...,
    start_state: RobotStates = None
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

生成经过多个路点的笛卡尔直线运动。

向服务器发送 MoveLineReq，服务器在笛卡尔（任务）空间中为末端执行器规划直线路径，再在中间采样点通过 IK 转换为关节空间轨迹。

服务器端流程：单链时调用 singleChainMoveLine()；多链时调用 multiChainMoveLine()。规划器按照 TrajPlanner 中配置的 move_line_intermidiate_point 数量，沿笛卡尔直线采样中间点；在每个采样点求解 IK 以得到对应的关节配置。生成的关节序列随后进行时间参数化并校验。

与其他规划类型的对比：motion_plan()：带碰撞规避的关节空间采样，末端执行器路径形状由规划器决定（不保证为直线）；traj_plan()：直接关节空间插值，末端执行器路径不可预测；move_line()：笛卡尔空间线性插值，末端执行器路径为直线。

典型使用场景：精确的直线接近/撤退运动（例如轴孔装配、吸附取件）；表面跟随任务（喷涂、焊接、涂胶）；任何需要可预测直线末端执行器轨迹的操作。

参数

名称类型默认值描述
waypointsSequence[Sequence[MotionPlanChainTarget]]需要传参-
paramsPlannerConfig...-
start_stateRobotStatesNone-

返回值

类型描述
tuple[MotionStatus, dict[str, list[list[float]]]]-
note

碰撞语义：若在 params 中启用，碰撞检查针对自身碰撞以及用户加载的环境障碍物进行；服务器会对 IK 采样得到的中间点进行碰撞校验。

note

中间 IK 采样点数量由服务器 TrajPlanner 配置中的 move_line_intermidiate_point 控制；采样点越多，路径越平滑，但规划耗时也越长。

warning

笛卡尔直线运动在路径上可能遇到关节速度/加速度限制、奇异位型或不可达配置，从而导致规划失败。

warning

请确保所有路点均位于该运动链的可达工作空间内。

移动全身关节到零位（move_whole_body_joint_zero）​

def move_whole_body_joint_zero(
    is_blocking: bool = True,
    leg_head_speed_rad_s: SupportsFloat = 0.2,
    leg_head_timeout_s: SupportsFloat = 15.0,
    params: Parameter = ...
) -> MotionStatus

将全身关节移动到预定义的零（家庭）配置。

腿部和头部关节通过 GalbotRobot（直接关节控制）进行控制，而左/右臂则通过启用碰撞检查的运动规划器进行规划。

零配置的联合顺序遵循 SDK 约定：leg(5) + head(2) + left_arm(7) + right_arm(7)。

参数

名称类型默认值描述
is_blockingboolTrue-
leg_head_speed_rad_sSupportsFloat0.2-
leg_head_timeout_sSupportsFloat15.0-
paramsParameter...-

返回值

类型描述
MotionStatus-

移除障碍物（remove_obstacle）​

def remove_obstacle(obstacle_id: str) -> MotionStatus

从规划场景中移除碰撞障碍物。

参数

名称类型默认值描述
obstacle_idstr需要传参-

返回值

类型描述
MotionStatus-
note

移除不存在的障碍物返回 INVALID_INPUT（非 NO_ERROR）。

按类型设置配置（set_config_by_type）​

def set_config_by_type(config: MotionPlanConfig) -> MotionStatus

按类型设置/获取 MPS 配置（GetSet 通道）。

这是对 MPS Get/Set MotionPlanConfig RPC 的一层简单封装：config.config_type 用于选择目标子系统（例如 "sampler"、"ik_solver"、"trajectory_planner"）。对于 set_config_by_type，请求负载编码在 config.common_str 中（内容因类型而异）；对于 get_config_by_type，响应负载通过 out.common_str 返回（内容因类型而异）。

目的是避免暴露大量狭窄的、按类型区分的专用配置接口。

参数

名称类型默认值描述
configMotionPlanConfig需要传参-

返回值

类型描述
MotionStatus-

设置末端执行器姿态（set_end_effector_pose）​

def set_end_effector_pose(
    target_pose: list[float],
    end_effector_frame: str,
    reference_frame: str = 'base_link',
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    is_blocking: bool = True,
    timeout: SupportsFloat = -1.0,
    params: Parameter = ...
) -> MotionStatus

命令末端执行器移动到目标笛卡尔坐标位姿。

笛卡尔运动命令的高级接口。内部执行逆运动学 (IK)、轨迹规划并执行运动。is_blocking 标志仅控制此 API 是等待完成还是在启动后台执行任务后立即返回。

Use this overload for single-chain planning without additional assist chains. end_effector_frame selects the kinematic chain, such as "left_arm" or "right_arm"; it does not select a semantic link on that chain.

参数

名称类型默认值描述
target_poselist[float]需要传参目标笛卡尔位姿：[x, y, z, qx, qy, qz, qw]（米，四元数）。
end_effector_framestr需要传参运动链标识（例如 "left_arm"、"right_arm"）。该参数用于选择手臂，而非该手臂上的目标连杆。目标坐标系由 params->is_tool_pose 选择；关于法兰与工具 TCP 的行为，参见下方说明。
reference_framestr'base_link'姿态指定所用的坐标系。有效值为 "world"、"map"、"base_link"，或 get_support_chains() 返回的运动链名称。默认值："base_link"。
reference_robot_statesRobotStatesNone参考机器人起始状态
enable_collision_checkboolTrue是否启用碰撞检查
is_blockingboolTrue如果为真，则等待动作完成或超时。如果为假，机器人仍会执行动作，而此 API 会在启动一个等待执行完成的后台任务后立即返回。
timeoutSupportsFloat-1.0SDK 等待动作完成的最长时间（以秒为单位）。如果小于 0，则使用 params->timeout_second。在非阻塞模式下，此超时时间应用于后台任务。
paramsParameter...额外参数

返回值

类型描述
MotionStatus运动状态：- 成功：运动成功完成（阻塞）或后台执行开始（非阻塞）- 超时：运动超过超时时长- 输入无效：姿态或参数无效- 故障：规划或执行失败
note

运动类型（直线/关节空间）由 params->move_line 控制。

warning

非阻塞模式不会取消或跳过机器人运动；它只会让此 API 立即返回。

设置末端执行器姿态（set_end_effector_pose）​

def set_end_effector_pose(
    target_pose: list[float],
    end_effector_frame: str,
    reference_frame: str,
    assist_chains: Set[str],
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    is_blocking: bool = True,
    timeout: SupportsFloat = -1.0,
    params: Parameter = ...
) -> MotionStatus

命令末端执行器在辅助链的配合下移动到目标笛卡尔姿态。

这是一个为方便使用而提供的重载成员函数，与上述函数的区别仅在于所接受的参数。

与 set_end_effector_pose(target_pose, end_effector_frame, reference_frame, ...) 相同，但 assist_chains 参数位于 reference_frame 之后，用于协调多链规划。

This overload coordinates the chains listed in assist_chains in addition to the primary chain. end_effector_frame selects that primary kinematic chain; it is not a semantic link name.

参数

名称类型默认值描述
target_poselist[float]需要传参目标笛卡尔位姿：[x, y, z, qx, qy, qz, qw]。
end_effector_framestr需要传参主运动链标识，例如 "left_arm" 或 "right_arm"。
reference_framestr需要传参姿态指定所用的坐标系。有效值为 "world"、"map"、"base_link"，或 get_support_chains() 返回的运动链名称。
assist_chainsSet[str]需要传参需要协调的附加运动链（例如 {"torso"}），不支持 "leg"。
reference_robot_statesRobotStatesNone可选的全身规划初值；为 nullptr 时使用当前状态。
enable_collision_checkboolTrue如果为 true，则要求轨迹无碰撞。
is_blockingboolTrue如果为 true，则等待执行完成；如果为 false，则在后台开始执行后立即返回。
timeoutSupportsFloat-1.0最大等待时间（秒）；负值表示使用 params->timeout_second。
paramsParameter...运动规划与执行参数。

返回值

类型描述
MotionStatusMotionStatus，表示规划或执行状态。
note
  • target_pose 默认指向法兰。调用 attach_tool() 后，若目标描述的是已连接工具的 TCP，请设置 params.is_tool_pose=True。
  • attach_tool() 会更新运动学与碰撞模型，但不会自动改变本 API 使用的目标坐标系。
warning

assist_chains 中不支持 "leg" 运动链。直接执行时，通常应将 reference_robot_states 保留为 None。非阻塞模式同样会使机器人开始运动。

设置运动规划配置（set_motion_plan_config）​

def set_motion_plan_config(config: MotionPlanConfig) -> MotionStatus

设置全局运动规划配置。

更新规划器设置，例如速度/加速度限制、规划算法参数和优化目标。影响后续所有的计划操作。

参数

名称类型默认值描述
configMotionPlanConfig需要传参-

返回值

类型描述
MotionStatus-
note

更改会持续存在，直到显式重置或进程重启。

note

有关可用参数，请参阅 MotionPlanConfig 文档。

状态转字符串（status_to_string）​

def status_to_string(status: MotionStatus) -> str

将 MotionStatus 枚举转换为人类可读的字符串。

将状态代码映射到用于日志记录、错误报告或 UI 显示的描述性字符串。

参数

名称类型默认值描述
statusMotionStatus需要传参-

返回值

类型描述
str-
note

使用 status_string_map_ 进行查找；如果状态未知则返回 UNKNOWN。

轨迹规划（traj_plan）​

def traj_plan(
    waypoints: Sequence[Sequence[MotionPlanChainTarget]],
    params: PlannerConfig = ...,
    start_state: RobotStates = None
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

在不进行路径搜索的情况下，生成经过多个路点的时间参数化关节轨迹。

向服务器发送 TrajPlanReq（mps_core.cpp:handle_sig_point_traj_plan_req 或 handle_mul_point_traj_plan_req），执行带时间参数化的直接关节空间插值。与 motion_plan() 不同，该方法不运行基于采样的路径搜索，而是直接在关节空间中连接各路点。

服务器端流程：单点目标调用 moveJointPlan() 进行起点到目标的直接插值；多点目标调用 moveWaypointJointPlan() 进行平滑多路点插值。该路径默认 is_direct_connect_try=true 且 is_path_search=false。is_check_collision 依然生效（默认 true），因此插值后仍会校验关节限制与速度。

典型使用场景：在已知无障碍空间中快速重新定位，无需基于采样的规划；通过示教点或已记录的关节配置生成平滑轨迹；供已完成路径校验的更高层规划函数内部调用。

参数

名称类型默认值描述
waypointsSequence[Sequence[MotionPlanChainTarget]]需要传参-
paramsPlannerConfig...-
start_stateRobotStatesNone-

返回值

类型描述
tuple[MotionStatus, dict[str, list[list[float]]]]-
note

由于跳过了基于采样的路径搜索阶段，速度快于 motion_plan()。

warning

不会搜索无碰撞路径；若任意路点或直接插值路径穿过障碍物，规划器不会检测到。is_check_collision（默认 true）仍会校验关节限制与速度可行性，但不校验碰撞。

移动导航（GalbotNavigation）​

移动机器人底盘导航与定位接口。

该类提供线程安全的单例接口，用于控制移动底盘导航系统。支持二维位姿估计、重定位、带动态避障的目标导航与路径规划。导航系统在全局地图坐标系下工作，支持阻塞与非阻塞两种导航模式，并兼容差分驱动和全向底盘。除非另有说明，所有位姿参数均以地图坐标系表示。

添加导航箱子（add_bounding_box）​

def add_bounding_box(box_info: dict) -> tuple

添加用于导航障碍物过滤的箱子。

将 SDK 定义的箱子区域发送给融合服务，使导航在处理融合障碍物点时忽略这些区域，而不是把它们当作障碍物。box_tag 是箱子的唯一标记；后续调用 remove_bounding_box() 移除该箱子时，应传入相同的 box_tag。箱子位姿相对于 parent_link_name 表示。

参数

名称类型默认值描述
box_infodict需要传参箱子信息参数，字段包括：
- box_size: [length_x, length_y, length_z]，箱子在局部 x/y/z 轴方向上的尺寸，单位为米。
- box_pose: [x, y, z, qx, qy, qz, qw]，箱子相对于 parent_link_name 的位姿。
- box_tag: 箱子的唯一标记，后续 remove_bounding_box() 需要使用相同的 box_tag。
- parent_link_name: box_pose 所在的父连杆或父坐标系名称。

返回值

类型描述
tuple导航状态，指示箱子过滤区域是否添加成功。
def attach_box_to_link(box_info: dict, ignore_collision_links: Sequence[str] = []) -> tuple

将箱子碰撞物挂载到机器人连杆。

该接口会把箱子作为附着碰撞物发送给 PNS。box_tag 是箱子的唯一标记；后续调用 detach_box_from_link() 解除该箱子挂载时，应传入相同的 box_tag。box_info.parent_link_name 作为 box_info.box_pose 的父连杆。

参数

名称类型默认值描述
box_infodict需要传参箱子信息参数，字段包括：
- box_size: [length_x, length_y, length_z]，箱子在局部 x/y/z 轴方向上的尺寸，单位为米。
- box_pose: [x, y, z, qx, qy, qz, qw]，箱子相对于 parent_link_name 的位姿。
- box_tag: 箱子的唯一标记，后续 detach_box_from_link() 需要使用相同的 box_tag。
- parent_link_name: box_pose 所在的父连杆或父坐标系名称。
ignore_collision_linksSequence[str][]碰撞检测时需要忽略该附着箱子的机器人连杆列表。

返回值

类型描述
tuple导航状态，指示箱子是否成功挂载到指定连杆。

检查目标到达（check_goal_arrival）​

def check_goal_arrival() -> bool

检查机器人是否成功达到当前目标。

该方法查询导航系统以确定机器人是否已在可接受的位置和方向公差内到达目标位姿。当使用非阻塞导航模式轮询完成情况时，这特别有用。

返回值

类型描述
bool若机器人在容差阈值内到达目标则返回 true；若仍在导航、无活动目标或尚未到达则返回 false。
note

在非阻塞导航场景中最有用。

note

到达的公差阈值由导航模块的内部参数定义（通常在 YAML 配置文件中设置）。

note

如果没有激活的导航命令，此方法返回 false。

检查路径可达性（check_path_reachability）​

def check_path_reachability(goal_pose: numpy.ArrayLike, start_pose: numpy.ArrayLike) -> bool

检查地图中是否存在从起点到目标的无碰撞路径。

此方法查询全局路径规划器以确定指定的起始姿态和目标姿态之间是否存在有效的无碰撞路径。这对于在尝试导航之前验证目标姿态或多目标路径规划非常有用。

参数

名称类型默认值描述
goal_posenumpy.ArrayLike需要传参目标位姿（地图坐标系）
start_posenumpy.ArrayLike需要传参起始位姿

返回值

类型描述
bool若起点到目标存在无碰撞路径则返回 true；若未找到有效路径则返回 false。
note

此方法仅基于地图检查静态障碍物。

note

路径计算可能根据距离需要一些时间。

note

返回 true 并不保证成功导航。

def detach_box_from_link(box_tag: SupportsInt) -> tuple

从机器人连杆解除箱子碰撞物。

根据 box_tag 解除对应箱子的附着碰撞物。这里的 box_tag 应与 attach_box_to_link() 挂载该箱子时使用的 box_tag 保持一致。

参数

名称类型默认值描述
box_tagSupportsInt需要传参箱子的唯一标记，应与 attach_box_to_link() 挂载该箱子时使用的 box_tag 一致。

返回值

类型描述
tuple导航状态，指示箱子是否成功从连杆解除挂载。

转储导航动态配置以进行调试（dump_navigation_configs）​

def dump_navigation_configs() -> tuple

转储导航动态配置以进行调试。

此方法查询常用的导航配置键，并通过 SDK 日志记录器打印响应。它用于诊断和调试。

返回值

类型描述
tuple导航状态指示所有调试查询请求是否已被接受。
note

输出格式取决于 PNS 服务响应，可能是 JSON 或 protobuf 文本格式。

获取导航箱子（get_bounding_box）​

def get_bounding_box() -> list

获取当前用于导航障碍物过滤的箱子。

查询融合服务，返回当前的箱子信息列表。box_tag 是箱子的唯一标记。

返回值

类型描述
list当前箱子信息列表；通信失败或没有可用箱子时返回空列表。

获取当前姿态（get_current_pose）​

def get_current_pose() -> list[float]

获取地图坐标系中机器人底盘的当前估计位姿。

该方法返回来自定位系统的最新姿态估计。位姿表示机器人的 base_link 坐标系相对于地图坐标系原点的位置和方向。

返回值

类型描述
list[float]机器人当前位姿 [x, y, z, qx, qy, qz, qw]，在地图坐标系下解释；仅在机器人已定位时有效。
note

仅当 is_localized() 返回 true 时返回的位姿才有效。

note

该位姿表示机器人底盘接地轮廓（base footprint）的中心。

获取任务状态（get_navigation_status）​

def get_navigation_status() -> NavigationTaskStatus

获取当前导航任务状态。

该接口适合在非阻塞模式下轮询任务进度，并根据状态判断任务是否完成。

返回值

类型描述
NavigationTaskStatusNavigationTaskStatus：当前任务状态。若尚未收到状态，则为 UNKNOWN；任务执行中为 RUNNING；任务结束后返回终态。
note

适用于非阻塞模式：循环查询 get_navigation_status()，并在终态或超时后退出。

查询任务状态（get_navigation_target_status）​

def get_navigation_target_status(task_id: str) -> NavigationTaskSnapshot

查询异步导航任务的最新状态。

该接口用于获取已提交任务的当前执行结果，适合在非阻塞模式下持续监控任务进度。

参数

名称类型默认值描述
task_idstr需要传参任务标识，由对应异步导航接口返回。

返回值

类型描述
NavigationTaskSnapshot指定任务的最新导航任务状态快照。

初始化（init）​

def init() -> bool

初始化导航子系统及其依赖项。

在使用任何其他导航功能之前必须调用此方法。它初始化通信通道、加载地图、启动定位模块并准备路径规划器。

返回值

类型描述
bool初始化成功返回 true，否则返回 false。
note

此方法应在获取单例实例后仅调用一次。

note

后续调用将返回第一次初始化的结果。

warning

在成功初始化前调用导航方法将导致错误。

检查是否已定位（is_localized）​

def is_localized() -> bool

检查机器人当前是否在地图中定位。

该方法查询定位系统以确定机器人是否具有足够置信度的有效姿态估计。未定位的机器人不应执行导航任务。

返回值

类型描述
bool若机器人已可靠定位则返回 true；若定位丢失或不确定则返回 false。
note

建议在发出导航命令前检查定位状态。

note

如果返回 false，请考虑调用 relocalize() 并提供初始猜测。

直线移动到目标（move_straight_to）​

def move_straight_to(
    goal_pose: numpy.ArrayLike,
    is_blocking: bool = True,
    timeout: SupportsFloat = 8
) -> tuple

将机器人移动到里程计坐标系中的相对目标位姿。

此方法命令机器人移动到相对于其在里程计 (odom) 坐标系中的当前位置指定的姿态。这对于不需要基于地图的规划的短距离、精确的运动非常有用。与navigate_to_goal()不同，此方法不执行动态障碍物检测或全局路径规划。它使用全向运动规划来直接移动到目标。

参数

名称类型默认值描述
goal_posenumpy.ArrayLike需要传参相对于当前机器人底座帧的目标位姿。
包含：
- x: 前后位移（米）
- y: 左右位移（米）
- theta: 转向角度（弧度）
is_blockingboolTrue执行模式标志。
- true (阻塞): 阻塞直到运动完成、失败或超时
- false (非阻塞): 发送导航命令后立即返回
timeoutSupportsFloat8阻塞模式最大等待时间（秒），默认 8.0 秒；仅在 is_blocking 为 true 时生效。

返回值

类型描述
tuple导航状态指示结果：- 非阻塞模式：命令接受状态 - 阻塞模式：最终运动结果（成功、失败、超时）
note

此方法不检查障碍物或碰撞。请先检查路径可达性。

note

此方法使用里程计帧，不需要地图帧。

note

适用于小的精确调整，如最终接近。

warning

由于禁用了碰撞检查，请确保路径无障。

warning

长距离下里程计漂移可能影响精度。建议缩短单次移动距离或定期重定位。

轨迹导航（navigate_along_trajectory）​

def navigate_along_trajectory(
    waypoints: Sequence[Pose],
    frame_id: str = 'map',
    speed_ratio: SupportsFloat = 1.0,
    enable_collision_check: bool = True
) -> TaskHandle

使用有序三维位姿提交轨迹导航任务。

该接口将输入位姿视为轨迹参考，导航系统可以对路径进行平滑和优化，因此中间位姿不保证被精确经过，但最终位姿会作为导航目标。

参数

名称类型默认值描述
waypointsSequence[Pose]需要传参按顺序排列的轨迹位姿点。
frame_idstr'map'参考坐标系，支持 "map"、"base_link"。
speed_ratioSupportsFloat1.0速度缩放因子 (0, 1.0]。
enable_collision_checkboolTrue是否启用碰撞检测。

返回值

类型描述
TaskHandleTaskHandle：已提交任务的 task_id、请求结果和消息。

多路点导航（navigate_through_waypoints）​

def navigate_through_waypoints(
    waypoints: Sequence[Waypoint],
    frame_id: str = 'map',
    enable_collision_check: bool = True
) -> TaskHandle

提交多路点导航任务。

该接口一次请求下发多个路点，并按照输入顺序逐点执行，适合需要明确经过多个目标位置的导航场景。

参数

名称类型默认值描述
waypointsSequence[Waypoint]需要传参按顺序排列的路点列表。
frame_idstr'map'参考坐标系，支持 "map"、"base_link"。
enable_collision_checkboolTrue是否启用碰撞检测。

返回值

类型描述
TaskHandleTaskHandle：已提交任务的 task_id、请求结果和消息。

导航到目标（navigate_to_goal）​

def navigate_to_goal(
    goal_pose: numpy.ArrayLike,
    enable_collision_check: bool = True,
    is_blocking: bool = False,
    timeout: SupportsFloat = 8,
    omni_plan: bool = False
) -> tuple

将机器人导航至地图坐标系中的目标位姿。

该方法命令移动底座使用全局路径规划器和局部轨迹控制器导航到指定的目标位姿。如果启用了碰撞检查，规划器将计算从当前姿态到目标的无碰撞路径，同时考虑静态地图障碍物和动态障碍物。

参数

名称类型默认值描述
goal_posenumpy.ArrayLike需要传参目标位姿（地图坐标系）
enable_collision_checkboolTrue是否启用碰撞检查
is_blockingboolFalse执行模式标志。默认值：false。false（非阻塞）：发送导航命令后立即返回，并启动一个 SDK 端的监视线程。返回状态指示命令是否被接受，而不是是否已达到目标。true（阻塞）：阻塞，直到达到目标、导航失败或当前线程超时。返回状态反映最终的导航结果。
timeoutSupportsFloat8SDK 端导航监控超时时间（以秒为单位）。默认值：8.0 秒。在阻塞模式下，当前线程监控此超时时间。在非阻塞模式下，后台监控线程使用此超时时间。如果在超时前未达到目标且导航尚未停止，SDK 将自动调用 stop_navigation 函数。
omni_planboolFalse运动规划模式标志。默认值：false。true：启用全向运动规划（全向驱动），允许机器人向任意方向移动并独立旋转。false：使用带运动学约束的差动驱动规划。S1 不支持全向运动规划；在 S1 上请将此参数保持为 false，设置为 true 将返回 NavigationStatus::INVALID_INPUT。

返回值

类型描述
tuple导航状态指示结果：- 非阻塞模式：命令接受状态 - 阻塞模式：最终导航结果（成功、失败、超时）
note

机器人必须先定位（is_localized() 返回 true），才能开始导航。

note

导航请求通信超时时间在内部是固定的，与 SDK 端导航监视器超时时间是分开的。

note

在阻塞模式和非阻塞模式下，SDK 端监控都会使用超时机制。

warning

长距离导航可能需要较长时间；建议使用非阻塞模式或监控进度。

导航到目标V2（navigate_to_goal_v2）​

def navigate_to_goal_v2(
    goal_pose: numpy.ArrayLike,
    max_vel: numpy.ArrayLike,
    pose_frame: str = 'map',
    enable_collision_check: bool = True,
    is_blocking: bool = False,
    timeout: SupportsFloat = 5.0,
    omni_plan: bool = False
) -> tuple

使用导航 v2 接口引导机器人到达目标姿态。

此方法向 PNS 服务发送导航 v2 规划请求。它支持通过 pose_frame 设置全局和局部目标坐标系，并在发送目标请求之前应用导航速度和运行时超时配置。

参数

名称类型默认值描述
goal_posenumpy.ArrayLike需要传参目标姿态：位置（x，y，z）以米为单位，方向以单位四元数（x，y，z，w）表示，在 pose_frame 中解释。
max_velnumpy.ArrayLike需要传参最大导航速度限制 [vx, vy, vyaw]。每个参数必须在 [0.05, 1.5] 范围内。线速度分量单位为米/秒，偏航速度单位为弧度/秒。低于 0.05 的值可能太小，无法可靠地驱动基座。
pose_framestr'map'目标姿态的参考系。仅“map”和“base_link”有效。默认值：“map”。“map”：地图坐标系中的全局目标姿态。“base_link”：相对于机器人基座的局部目标姿态。
enable_collision_checkboolTrue如果为真，则启用规划和运行时执行中最接近的 v2 碰撞检查字段。默认值：真。
is_blockingboolFalse执行模式标志。默认值：false。false（非阻塞）：发送导航命令后立即返回，并启动一个 SDK 端的监视线程。返回状态指示命令是否被接受。true（阻塞）：阻塞，直到到达目标、导航失败、被中断或 SDK 端监视超时。返回状态反映最终的导航结果。
timeoutSupportsFloat5.0导航运行时超时时间（以秒为单位）。默认值：5.0 秒。此值通过 set_navigation_timeout() 函数发送到 PNS 服务。负值将禁用导航运动时间限制。当超时时间为非负数时，SDK 端监控使用超时时间 + 5.0 秒；对于负超时时间，SDK 端监控将等待直至收到终端任务状态报告。
omni_planboolFalse运动规划模式标志。默认值：false。true：启用全向运动规划。false：使用基于航向的规划。S1 不支持全向运动规划；在 S1 上请将此参数保持为 false，设置为 true 将返回 NavigationStatus::INVALID_INPUT。

返回值

类型描述
tuple导航状态指示结果：- 非阻塞模式下：命令接受状态 - 阻塞模式下：最终导航结果。成功和中断分别报告为 NavigationStatus::SUCCESS，失败报告为 NavigationStatus::FAIL，SDK 监视器超时报告为 NavigationStatus::TIMEOUT。
note

此方法使用导航 v2 主题和协议。

note

pose_frame 目前支持“map”表示全局目标，“base_link”表示局部目标。

warning

此方法可能会更改导航控制参数，进而影响基站控制行为，例如速度限制和导航超时。如果应用程序之后需要独立的底层基站控制，请重新设置基站控制参数以覆盖导航配置。

warning

长距离导航可能需要较长时间；建议使用非阻塞模式或监控进度。

速度指令导航机器人（navigate_with_velocity）​

def navigate_with_velocity(
    vx: SupportsFloat,
    vy: SupportsFloat,
    vyaw: SupportsFloat,
    duration_s: SupportsFloat = 3.0,
    enable_collision_check: bool = True
) -> tuple

使用导航 v2 接口，通过速度指令导航机器人。

此方法发送基于速度的导航指令。该指令包含平面基座速度分量和持续时间；执行持续时间由导航服务处理。

参数

名称类型默认值描述
vxSupportsFloat需要传参沿x轴的线速度，单位为米每秒。
vySupportsFloat需要传参沿y轴的线速度，单位为米每秒。
vyawSupportsFloat需要传参绕 z 轴的角速度，单位为弧度每秒。
duration_sSupportsFloat3.0命令持续时间（秒）。必须大于 0.0。默认值：3.0 秒。
enable_collision_checkboolTrue如果为真，则启用运行时碰撞检查，通过最接近的匹配 v2 碰撞字段进行碰撞检测。默认值：真。

返回值

类型描述
tuple导航状态指示导航服务是否已成功接受速度指令。
note

此方法使用导航 v2 主题和协议。

note

enable_collision_check 是一个运行时碰撞检查标志，而不是一个完整的避障策略开关。

warning

此方法是非阻塞的。它会在速度命令被接受后返回，而不是在速度持续时间结束后返回。

重定位（relocalize）​

def relocalize(init_pose: numpy.ArrayLike) -> tuple

执行重新定位以重新估计机器人在地图坐标系中的姿态。

该方法重置定位滤波器并提供初始姿态估计，以帮助机器人在已知地图中重新建立其位置。当机器人失去定位或手动将机器人放置在已知位置时，这非常有用。

参数

名称类型默认值描述
init_posenumpy.ArrayLike需要传参初始姿态估计

返回值

类型描述
tuple导航状态，指示重定位请求的结果。详见 NavigationStatus 枚举的取值说明。
note

重定位时机器人应保持静止以获得最佳效果。

note

调用此方法后，使用 is_localized() 验证成功。

移除导航箱子（remove_bounding_box）​

def remove_bounding_box(box_tag: SupportsInt) -> tuple

移除用于导航障碍物过滤的箱子。

根据 box_tag 移除对应箱子。这里的 box_tag 应与 add_bounding_box() 添加该箱子时使用的 box_tag 保持一致。

参数

名称类型默认值描述
box_tagSupportsInt需要传参箱子的唯一标记，应与 add_bounding_box() 添加该箱子时使用的 box_tag 一致。

返回值

类型描述
tuple导航状态，指示箱子过滤区域是否移除成功。

设置导航到达阈值（set_navigation_arrival_threshold）​

def set_navigation_arrival_threshold(threshold: numpy.ArrayLike) -> tuple

设置导航到达阈值。

此方法更新导航规划和控制使用的位置和偏航容差，以确定是否已到达目标。

参数

名称类型默认值描述
thresholdnumpy.ArrayLike需要传参到达阈值 [x_error, y_error, yaw_error]。每个元素必须在 [0.03, 2.0] 范围内。位置误差以米为单位，偏航误差以弧度为单位。支持的最小精度为 0.03 米或弧度。

返回值

类型描述
tuple导航状态，指示配置请求是否已被接受。
note

不同类型的任务可能需要不同的到达精度。请在开始相应的导航任务之前配置此值。

设置导航运动学限制（set_navigation_kinematics_limits）​

def set_navigation_kinematics_limits(
    vel_limit: numpy.ArrayLike,
    acc_limit: numpy.ArrayLike,
    jerk_limit: numpy.ArrayLike
) -> tuple

设置导航运动学限制。

此方法通过 PNS 动态配置界面更新导航速度、加速度和加加速度限制。

参数

名称类型默认值描述
vel_limitnumpy.ArrayLike需要传参最大速度限制 [vx, vy, vyaw]。每个分量必须在 [0.05, 1.5] 范围内。线速度分量单位为米/秒，偏航速度单位为弧度/秒。低于 0.05 的值可能太小，无法可靠地驱动基座。
acc_limitnumpy.ArrayLike需要传参最大加速度限制 [ax, ay, ayaw]，各分量取值范围须在 [0.05, 6.0] 之间。线性加速度分量单位为米每二次方秒，偏航加速度单位为弧度每二次方秒。低于 0.05 的取值可能过小，无法可靠驱动底盘。
jerk_limitnumpy.ArrayLike需要传参最大加加速度限制 [jx, jy, jyaw]。每个元素必须在 [0.05, 12.0] 范围内。线性加加速度分量单位为米/秒³，偏航加加速度单位为弧度/秒³。低于 0.05 的值可能太小，无法可靠地驱动基座。

返回值

类型描述
tuple导航状态，指示配置请求是否已被接受。
note

此配置需要在开始导航任务之前设置。

warning

此方法可能会更改导航控制参数，进而影响基础控制行为。如果应用程序之后需要独立的底层基础控制，请重新设置基础控制参数以覆盖导航配置。

设置动态目标（set_navigation_target）​

def set_navigation_target(
    target: Pose,
    frame: str = 'map',
    speed_ratio: SupportsFloat = 1.0,
    enable_collision_check: bool = True
) -> TaskHandle

异步提交动态导航目标。

该接口适用于目标可能频繁变化的场景，例如动态跟踪或遥操作。提交新目标后，导航系统会以最新目标为准重新规划；

前一个目标可能被后续请求抢占。为保证导航过程稳定，建议不要以过高频率调用。

参数

名称类型默认值描述
targetPose需要传参目标位姿，格式为 Pose（x, y, z, qx, qy, qz, qw）。
framestr'map'目标位姿参考坐标系，支持 "map"、"base_link"。
speed_ratioSupportsFloat1.0速度缩放因子 (0, 1.0]。
enable_collision_checkboolTrue是否启用碰撞检测。

返回值

类型描述
TaskHandleTaskHandle：已提交任务的 task_id、请求结果和消息。

设置导航超时时间（set_navigation_timeout）​

def set_navigation_timeout(timeout_s: SupportsFloat) -> tuple

设置导航超时配置。

此方法通过 PNS 动态配置接口更新导航超时。它可作为不应无限期运行的任务的安全保障。

参数

名称类型默认值描述
timeout_sSupportsFloat需要传参超时时间（秒）。

返回值

类型描述
tuple导航状态，指示配置请求是否已被接受。
note

该超时的具体服务端含义由 PNS 导航服务定义。

设置导航速度限制（set_navigation_velocity_limit）​

def set_navigation_velocity_limit(vel_limit: numpy.ArrayLike) -> tuple

设置导航速度限制。

此方法通过 PNS 动态配置接口更新导航速度限制。

参数

名称类型默认值描述
vel_limitnumpy.ArrayLike需要传参最大导航速度限制 [vx, vy, vyaw]。每个参数必须在 [0.05, 1.5] 范围内。线速度分量单位为米/秒，偏航速度单位为弧度/秒。低于 0.05 的值可能太小，无法可靠地驱动基座。

返回值

类型描述
tuple导航状态，指示配置请求是否已被接受。
note

此配置需要在开始导航任务之前设置。

warning

此方法可能会更改导航控制参数，进而影响基础控制行为。如果应用程序之后需要独立的底层基础控制，请重新设置基础控制参数以覆盖导航配置。

停止导航（stop_navigation）​

def stop_navigation() -> tuple

停止当前的导航任务并使机器人停止。

此方法立即取消任何正在进行的导航命令（来自navigate_to_goal()或move_straight_to()）并命令机器人停止。机器人将根据其运动学约束减速并安全停止。

返回值

类型描述
tuple导航状态指示是否成功将停止命令发送到导航系统。
note

可在导航期间随时调用。

note

停止后，机器人的位置可能与原始位置不同。

note

机器人将尝试根据其加速度限制平滑停止。

感知模块接口（GalbotPerception）​

感知模块接口；通过 get_instance(MachineType) 获取单例实例。

获取模块的最新缓存结果（get_latest_result）​

def get_latest_result(module: PerceptionModule) -> tuple

返回模块的最新缓存结果，不阻塞。

参数

名称类型默认值描述
modulePerceptionModule需要传参感知模块。

返回值

类型描述
tuple如果有结果可用返回true，否则返回false。

初始化感知模块并加载模型（init）​

def init(enabled_modules: Set[PerceptionModule]) -> bool

初始化感知模块并加载指定模块的模型。

参数

名称类型默认值描述
enabled_modulesSet[PerceptionModule]需要传参要启用的感知模块集合。

返回值

类型描述
bool如果所有请求的模块都成功加载则返回true。

为指定模块运行一次推理（run_once）​

def run_once(module: PerceptionModule) -> bool

为指定模块运行一次推理。

参数

名称类型默认值描述
modulePerceptionModule需要传参感知模块。

返回值

类型描述
bool成功返回true，失败返回false。
note

初始化后，等待约10秒让模型准备就绪后再调用run_once。

等待模块产生新结果或超时（wait_for_new_result）​

def wait_for_new_result(module: PerceptionModule, timeout_s: SupportsFloat = 5.0) -> bool

阻塞直到模块产生新结果或超时。与run_once配合使用获取最新输出。

参数

名称类型默认值描述
modulePerceptionModule需要传参感知模块。
timeout_sSupportsFloat5.0超时时间（秒）。

返回值

类型描述
bool成功返回true，超时返回false。

类型与枚举（Types & Enums）​

驱动类型（ActuateType）​

指定在运动规划和执行期间应启动哪些运动链。这控制机器人是否仅使用目标手臂，或者还涉及躯干或腿部运动。

枚举值描述
ACTUATE_TYPE_NUM驱动类型数量
ACTUATE_WITH_CHAIN_ONLY仅执行目标运动链
ACTUATE_WITH_LEG执行目标运动链和腿部
ACTUATE_WITH_TORSO执行目标运动链和躯干

音频数据结构（AudioData）​

音频数据结构。

成员变量​
名称类型描述
datalist[int]音频数据包。
formatstr音频格式。
headerHeader音频消息头。
typestr音频类型。

碰撞检查选项（CollisionCheckOption）​

碰撞检测启用/禁用配置。

该结构在运动规划和执行期间提供对碰撞检查的细粒度控制。它支持独立切换自碰撞检测（机器人连杆相互碰撞）和环境碰撞检测（机器人与障碍物或工作空间边界碰撞）。禁用碰撞检查可以提高计算性能，但可能会导致不安全的轨迹。在受控环境中谨慎使用。

检查环境碰撞检测是否禁用（get_disable_env_collision_check）​

def get_disable_env_collision_check() -> bool

检查环境碰撞检测是否禁用

返回值

类型描述
bool-

检查自碰撞检测是否禁用（get_disable_self_collision_check）​

def get_disable_self_collision_check() -> bool

检查自碰撞检测是否禁用

返回值

类型描述
bool-

打印碰撞检测配置到标准输出（print）​

def print() -> None

打印碰撞检测配置到标准输出

启用或禁用环境碰撞检测（set_disable_env_collision_check）​

def set_disable_env_collision_check(disable: bool) -> None

设置是否禁用环境碰撞检测

参数

名称类型默认值描述
disablebool需要传参-
warning

禁用环境检查可能导致与障碍物发生碰撞。

启用或禁用自碰撞检测（set_disable_self_collision_check）​

def set_disable_self_collision_check(disable: bool) -> None

true禁用自碰撞检测，false启用

参数

名称类型默认值描述
disablebool需要传参-
warning

禁用自碰撞检查可能导致物理上不可行的配置。

碰撞信息（CollisionInfo）​

所报告连杆对的详细碰撞信息。

包含碰撞状态、涉及的机器人或环境连杆、距离，以及 MPS 运动学碰撞服务返回的碰撞元数据。collision_type 包含从响应 common_str 中复制的原始 MPS 碰撞元数据，当前格式包含采样标签和取值为 "self" 或 "env" 的碰撞分类。默认构造的 CollisionInfo 的默认值为 "UNKNOWN"；服务返回的空值则表示为空字符串。

成员变量​
名称类型描述
collision_typestr原始 MPS 元数据，包含采样标签以及 self/env 分类。
distancefloat所报告连杆对之间的距离（米）。
is_collisionboolMPS 是否报告该连杆对发生碰撞。
link1str所报告连杆对中第一个连杆的名称。
link2str所报告连杆对中第二个连杆的名称。

配置项（ConfigItem）​

待设置的单个配置字段，通过 SDK 定义的 key 在某个 ConfigService 内寻址。

各服务支持的完整键列表、类型及取值范围，请参见 SDK 文档中的 "Set Config Reference" 页面。

成员变量​
名称类型描述
keystr字段标识符（因服务而异，具体请参见 SDK 文档中的 "Set Config Reference" 页面）

配置服务（ConfigService）​

可通过 set_config() 修改配置的服务。

配置作用域为当前场景。详情请参见 GalbotRobot::set_config()。

枚举值描述
CONTROLSingoriX 控制服务
FRONT_HEAD_CAMERA前置头部相机采集服务
LEFT_ARM_CAMERA左臂相机采集服务
MOTION_PLAN运动规划服务
NAVIGATION导航规划服务
RIGHT_ARM_CAMERA右臂相机采集服务
SURROUND_CAMERAS环视相机采集服务；仅 G1 支持，其他机型将被拒绝

控制状态（ControlStatus）​

控制命令执行状态枚举。

表示机器人控制命令的执行状态，包括关节控制、末端执行器控制等运动控制操作。

枚举值描述
COMM_DISCONNECTED通信断开
DATA_FETCH_FAILED数据获取失败
FAULT故障
INIT_FAILED初始化失败
INVALID_INPUT无效输入
IN_PROGRESS进行中
PUBLISH_FAIL发布失败
STOPPED_UNREACHED已停止但未到达
SUCCESS成功
TIMEOUT超时

深度数据（DepthData）​

包含来自深度相机或 RGB-D 传感器的压缩深度图像数据。与 ROS 2 的 sensor_msgs/compressedImage 消息类型兼容（支持深度扩展）。

成员变量​
名称类型描述
databytes包含原始或压缩深度图像数据的二进制数据块
depth_scaleint深度缩放因子，用于将像素值转换为实际深度（米），真实深度 = 像素值 / depth_scale，例如：depth_scale = 1000 表示像素值单位为毫米
formatstr指定深度编码和压缩格式，例如："16UC1; compressedDepth png"（16 位无符号整数，PNG 压缩深度）
headerHeader包含采集时间戳和相机坐标系
heightint深度图像的行数
widthint深度图像的列数

检测与分割结果（DetectionAndSegmentationResult）​

单对象检测或实例分割结果（2D框、类别、可选掩码/关键点）。

成员变量​
名称类型描述
bboxtuple[int, int, int, int]检测框
class_indexint类别索引
class_namestr类别名称
confidencefloat置信度
keypointslist[tuple[float, float]]关键点

检测结果（DetectionResult）​

单个模块周期的聚合感知输出（图像、掩码、姿态、点云等）。

成员变量​
名称类型描述
bounding_boxeslist[tuple[int, int, int, int]]检测框列表
class_indiceslist[int]类别索引列表
class_nameslist[str]类别名称列表
confidenceslist[float]置信度列表
detection_resultslist[DetectionAndSegmentationResult]检测与分割结果列表
grasp_pose_resultlist[list[float]]抓取位姿结果
instance_maskAny实例掩码
ocr_stringlist[str]OCR 识别文本
point_cloudslist点云列表
running_infostr运行信息
sensor_namestr传感器名称
target_point_poseslist[numpy.NDArray[numpy.float32]"]]目标点位姿列表
target_poseslist[numpy.NDArray[numpy.float32]"]]目标位姿列表
timestamp_nsint时间戳（纳秒）

清空结果（clear）​

def clear() -> None

清空所有存储的结果。

获取结果信息（get_result_info）​

def get_result_info() -> str

获取结果摘要字符串。

返回值

类型描述
str-

力矩信息（EffortInfo）​

表示通常由力/扭矩传感器测量的 6 自由度 (6-DOF) 力螺旋（力和扭矩）。也称为空间力或广义力。

成员变量​
名称类型描述
forceVector3力向量（牛顿）：[fx, fy, fz]
- fx: X 方向力
- fy: Y 方向力
- fz: Z 方向力
timestamp_nsint测量时间戳（自纪元以来的纳秒数）
torqueVector3力矩向量（牛顿·米）：[tx, ty, tz]
- tx: 绕 X 轴力矩
- ty: 绕 Y 轴力矩
- tz: 绕 Z 轴力矩

编码的视频帧数据（EncodedVideoData）​

存储从 H.264 相机话题接收到的一帧完整编码帧。

成员变量​
名称类型描述
databytes单帧的 H.264 编码载荷。
formatstr编码格式描述。此接口通常使用 "h264"。
headerHeader包含获取时间戳和相机帧ID。

末端工具原始数据（EndToolRawData）​

S1 WBCS 末端工具透传通路上报的一帧原始数据。

SDK 不会解析 frame 的内容。设备适配层需要根据所安装末端工具的协议，自行过滤并解码 CAN/RS485 报文。

成员变量​
名称类型描述
framebytesS1 WBCS/TIB 布局的 64 字节不透明设备帧。
generationint同一 side/kind 数据流内的报文序号，WBCS 重启后可能重置。
kindEndToolRxKind产生该帧的 WBCS 逻辑反馈通道。
sideEndToolSide产生该帧的末端工具逻辑端点。

末端工具接收流类型（EndToolRxKind）​

承载末端工具原始帧的逻辑反馈通道。

枚举值描述
BUFFER_1KHZfeedback_1khz 通道。
BUFFER_250HZfeedback_250hz 通道。

末端工具侧别（EndToolSide）​

透传指令所选择的 S1 末端工具逻辑端点。

枚举值描述
LEFTleft_endtool 端点。
RIGHTright_endtool 端点。

错误（Error）​

描述单个模块或组件的错误，包括错误代码和用于调试和诊断的人类可读描述。

成员变量​
名称类型描述
commpentstr组件
descriptionstr错误描述
error_codeint用于程序化错误处理的数值错误代码

错误信息（ErrorInfo）​

包含来自多个模块或组件的带时间戳的错误消息集合。

成员变量​
名称类型描述
error_veclist[Error]误差向量
timestamp_nsint收集错误的时间戳（自纪元以来的纳秒数）

力数据（ForceData）​

包含来自 6 轴力/扭矩传感器的带有时间戳的力和扭矩测量值，通常安装在机器人手腕或工具端接口处。

成员变量​
名称类型描述
forceVector3力
timestamp_nsint测量时间戳（自纪元以来的纳秒数）
torqueVector3力矩向量（牛顿·米）：[tx, ty, tz]

坐标系（FrameTriad）​

表示坐标系三个正交轴的可视化表示，通常用于显示坐标系的方向和姿态。

成员变量​
名称类型描述
body_frame_idstr本体坐标系 ID
headerHeader消息头
posePose位姿命令
reference_frame_idstr参考坐标系 ID
twistTwist速度命令
wrenchWrench力/力矩命令

夹爪状态（GripperState）​

表示平行爪夹具的当前状态，包括张开宽度、运动状态和抓取力。

成员变量​
名称类型描述
effortfloat力矩
is_movingbool运动标志（来自运动窗口），false 表示在配置的时间窗口内未检测到有效运动，true 表示检测到有效运动
joint_positionslist[float]夹爪关节位置（弧度），通常0-0.04米
timestamp_nsint状态时间戳（自纪元以来的纳秒数）
velocityfloat夹爪开合速度（米/秒）。
widthfloat夹爪开口宽度（米），距离

关节组命令（GroupCommand）​

用于控制一组关节的命令结构，包含多个关节的目标位置和参数。

成员变量​
名称类型描述
joint_commandslist[JointCommand]该时间点的关节命令列表
time_from_start_sfloat相对轨迹起点的时间（秒）

消息头（Header）​

标准消息头包含时间戳和坐标系信息。时间戳以纳秒的形式存储（与其他传感器类型统一）。

成员变量​
名称类型描述
frame_idstr标识数据所在的坐标系，例如："base_link"、"world"、"camera_optical_frame"、"lidar_link"、"map"
timestamp_nsint数据采集的时间戳（自纪元以来的纳秒数），记录数据被捕获或生成的时间

IK 求解器配置（IKSolverConfig）​

逆运动学 (IK) 解算器配置参数。

该结构配置数值逆运动学解算器，用于计算实现所需末端执行器姿态的关节配置。它支持具有可配置种子策略、收敛容差、关节限制处理和超时参数的碰撞感知 IK。IK 求解是一种迭代数值优化过程，可以受益于多次随机初始化来找到可行的无碰撞解决方案。

获取关节限制安全裕度（get_col_aware_ik_joint_limit_bias）​

def get_col_aware_ik_joint_limit_bias() -> float

获取碰撞感知逆运动学关节限制偏差。较大的偏差会使求解器更倾向于避开碰撞区域。

返回值

类型描述
float-

获取碰撞感知IK 求解器超时（get_col_aware_ik_timeout）​

def get_col_aware_ik_timeout() -> float

获取碰撞感知逆运动学求解超时时间（秒）

返回值

类型描述
float-

检查是否启用碰撞检查日志（get_enable_collision_check_log）​

def get_enable_collision_check_log() -> bool

获取是否启用碰撞检测日志输出

返回值

类型描述
bool-

获取方向误差容差（get_rotation_eps）​

def get_rotation_eps() -> list[float]

获取旋转收敛容差（弧度）

返回值

类型描述
list[float]-

获取IK 求解器种子生成策略（get_seed_type）​

def get_seed_type() -> SeedType

获取逆运动学求解种子类型

返回值

类型描述
SeedType-

获取笛卡尔位置误差容差（get_translation_eps）​

def get_translation_eps() -> list[float]

获取平移收敛容差（米）

返回值

类型描述
list[float]-

打印IK 求解器配置到标准输出（print）​

def print() -> None

打印逆运动学求解器配置到标准输出

设置关节位置限制的安全裕度（set_col_aware_ik_joint_limit_bias）​

def set_col_aware_ik_joint_limit_bias(bias: SupportsFloat) -> None

设置碰撞感知逆运动学关节限制偏差

参数

名称类型默认值描述
biasSupportsFloat需要传参-
note

防止 IK 求解器提议在奇点附近的配置。

设置碰撞感知IK 求解器超时（set_col_aware_ik_timeout）​

def set_col_aware_ik_timeout(timeout: SupportsFloat) -> None

设置碰撞感知逆运动学求解超时时间（秒）

参数

名称类型默认值描述
timeoutSupportsFloat需要传参-
note

较长的超时允许更多种子尝试但会延迟规划。

启用或禁用碰撞检测日志（set_enable_collision_check_log）​

def set_enable_collision_check_log(enable: bool) -> None

设置是否启用碰撞检测日志输出

参数

名称类型默认值描述
enablebool需要传参-
note

用于调试由于碰撞约束导致的 IK 失败。

设置方向误差容差（set_rotation_eps）​

def set_rotation_eps(eps: list[float]) -> None

设置旋转收敛容差（弧度）

参数

名称类型默认值描述
epslist[float]需要传参-
note

当方向误差在此容差内时接受 IK 解。

设置种子类型（set_seed_type）​

def set_seed_type(type: SeedType) -> None

设置逆运动学求解种子类型

参数

名称类型默认值描述
typeSeedType需要传参-

设置笛卡尔位置误差容差（set_translation_eps）​

def set_translation_eps(eps: list[float]) -> None

设置平移收敛容差（米）

参数

名称类型默认值描述
epslist[float]需要传参-
note

当位置误差在此容差内时接受 IK 解。

IMU数据（ImuData）​

包含来自惯性测量单元 (IMU) 的带时间戳的数据，包括加速度计、陀螺仪和磁力计测量值。

成员变量​
名称类型描述
accelVector3线加速度（米/秒²）：[ax, ay, az]。
gyroVector3陀螺仪数据
magnetVector3磁力计数据
timestamp_nsint测量时间戳（自纪元以来的纳秒数）

关节命令（JointCommand）​

指定轨迹或控制命令中单个机器人关节所需的运动参数。

成员变量​
名称类型描述
accelerationfloat加速度
effortfloat期望的关节力矩（牛顿·米）
positionfloat期望的关节位置（弧度）
velocityfloat期望的关节速度（弧度/秒）

单关节状态（JointState）​

表示单个机器人关节的完整实时状态，包含关节标识、采样时间戳、运动学量（位置、速度、加速度）以及动力学量（力矩/effort 与电机电流）。

成员变量​
名称类型描述
accelerationfloat-
currentfloat-
effortfloat-
positionfloat-
timestamp_nsint-
velocityfloat-

关节状态消息（JointStateMessage）​

多个关节的关节状态的时间戳集合，通常表示机器人在某一时刻的完整关节配置的快照。

成员变量​
名称类型描述
joint_state_veclist[JointState]关节状态向量
timestamp_nsint采集时间戳（自纪元以来的纳秒数）

关节状态（JointStates）​

表示运动链的目标关节配置。扩展 RobotStates 以指定基于关节的运动目标。用于关节轨迹规划和正向运动学计算。所有关节角度必须以弧度为单位。矢量大小必须与指定运动链的自由度匹配。

成员变量​
名称类型描述
joint_nameslist[str]-
joint_positionslist[float]-

获取类型（get_type）​

def get_type() -> RobotStatesType

获取状态类型，指示这是关节空间目标

返回值

类型描述
RobotStatesType-

设置关节（set_joint）​

def set_joint(index: SupportsInt, val: SupportsInt) -> None

设置指定索引的关节值

参数

名称类型默认值描述
indexSupportsInt需要传参-
valSupportsInt需要传参-
note

函数执行边界检查；无效索引被静默忽略。

warning

越界访问不会返回错误；请确保索引有效。

设置关节位置（set_joint_positions）​

def set_joint_positions(joints: list[float]) -> None

设置所有关节位置

参数

名称类型默认值描述
jointslist[float]需要传参-
note

向量大小应等于链中驱动关节的数量。

运动学边界（KinematicsBoundary）​

机器人运动链关节的运动边界参数。

该结构定义了机器人运动链（例如，机械臂、移动底座或腿链）的运动学约束。它指定了链条中每个关节的位置、速度、加速度和加加速度限制。这些边界对于确保轨迹规划和执行过程中安全且物理上可行的运动至关重要。每个向量应包含运动链中每个关节的一个值。所有关节空间量均以弧度或每单位时间的弧度指定。

获取下限加速度限制（get_acc_lower_limit）​

def get_acc_lower_limit() -> list[float]

获取加速度下限（rad/s²）

返回值

类型描述
list[float]-

获取上限加速度限制（get_acc_upper_limit）​

def get_acc_upper_limit() -> list[float]

获取加速度上限（rad/s²）

返回值

类型描述
list[float]-

获取运动链名称（get_chain_name）​

def get_chain_name() -> str

获取该边界约束所属的运动链名称

返回值

类型描述
str-

获取下限加加速度限制（get_jerk_lower_limit）​

def get_jerk_lower_limit() -> list[float]

获取加加速度下限（rad/s³）

返回值

类型描述
list[float]-

获取上限加加速度限制（get_jerk_upper_limit）​

def get_jerk_upper_limit() -> list[float]

获取加加速度上限（rad/s³）

返回值

类型描述
list[float]-

获取下限位置限制（get_lower_limit）​

def get_lower_limit() -> list[float]

获取关节位置下限（rad）

返回值

类型描述
list[float]-

获取上限位置限制（get_upper_limit）​

def get_upper_limit() -> list[float]

获取关节位置上限（rad）

返回值

类型描述
list[float]-

获取下限速度限制（get_vel_lower_limit）​

def get_vel_lower_limit() -> list[float]

获取速度下限（rad/s）

返回值

类型描述
list[float]-

获取上限速度限制（get_vel_upper_limit）​

def get_vel_upper_limit() -> list[float]

获取速度上限（rad/s）

返回值

类型描述
list[float]-

打印输出（print）​

def print() -> None

打印运动学边界约束信息到标准输出

设置下限加速度限制（set_acc_lower_limit）​

def set_acc_lower_limit(limits: list[float]) -> None

设置加速度下限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

用于轨迹优化和平滑约束。

设置上限加速度限制（set_acc_upper_limit）​

def set_acc_upper_limit(limits: list[float]) -> None

设置加速度上限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

用于轨迹优化和平滑约束。

设置运动链名称（set_chain_name）​

def set_chain_name(name: str) -> None

设置该边界约束所属的运动链名称

参数

名称类型默认值描述
namestr需要传参-

设置下限加加速度限制（set_jerk_lower_limit）​

def set_jerk_lower_limit(limits: list[float]) -> None

设置加加速度下限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

加加速度约束可提高运动平滑度并减少机械应力。

设置上限加加速度限制（set_jerk_upper_limit）​

def set_jerk_upper_limit(limits: list[float]) -> None

设置加加速度上限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

加加速度约束可提高运动平滑度并减少机械应力。

设置下限位置限制（set_lower_limit）​

def set_lower_limit(limits: list[float]) -> None

设置关节位置下限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

向量大小必须等于链中的关节数。

设置上限位置限制（set_upper_limit）​

def set_upper_limit(limits: list[float]) -> None

设置关节位置上限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

向量大小必须等于链中的关节数。

设置下限速度限制（set_vel_lower_limit）​

def set_vel_lower_limit(limits: list[float]) -> None

设置速度下限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

双向关节通常为负值。

设置上限速度限制（set_vel_upper_limit）​

def set_vel_upper_limit(limits: list[float]) -> None

设置速度上限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

双向关节通常为正值。

激光雷达数据（LidarData）​

与 ROS 2sensor_msgs/PointCloud2 兼容的通用 N 维点云结构。将点数据存储为二进制 blob，并使用定义数据布局的字段描述符。支持有序（结构化）和无序（非结构化）点云。

成员变量​
名称类型描述
datalist[int]包含所有点数据的二进制数据块（按行优先顺序排列），大小应等于 row_step × height 字节，每个点占用 point_step 字节，布局根据 fields 描述符确定
fieldslist[PointField]描述每个点中存在的数据通道（x, y, z, intensity, rgb 等）及其二进制布局。
headerHeader消息头
heightint点云高度，无序点云 height = 1（单行），有序点云 height = 行数（例如，来自旋转 LiDAR 或深度相机）
is_bigendianbool数据的字节序，true 表示大端序，false 表示小端序（x86/ARM 系统通常为小端序）
is_densebool是否所有点都有效，true 表示所有点都有效且没有 NaN 或 Inf 值，false 表示点云可能包含无效点（NaN 或 Inf）
point_stepint单个点结构的总字节大小，包括所有字段和填充，必须 >= 所有字段大小的总和，可能包含对齐填充
row_stepint行行间距
widthint点云宽度，无序点云 width = 点的总数，有序点云 width = 每行的点数（列数），总点数 = height × width

直线轨迹碰撞检测基元（LineTrajCheckPrimitive）​

用于笛卡尔线性轨迹验证的几何基元配置。

该结构配置笛卡尔空间中线性末端执行器轨迹的碰撞检测几何表示。它支持两种基本类型：无限细线和扫掠体积圆柱体。选择适当的原语会影响碰撞检测的保守性和计算成本。圆柱体基元可以更准确地对机器人的实际扫描体积进行建模，但需要更昂贵的几何查询。

获取圆柱体基元半径（get_cylinder_prim_radius）​

def get_cylinder_prim_radius() -> float

获取圆柱基元半径（米）

返回值

类型描述
float-

获取直线检查基元类型（get_line_check_primitive_type）​

def get_line_check_primitive_type() -> PrimitiveType

获取直线检查基元类型

返回值

类型描述
PrimitiveType-

获取直线基元曲率（get_line_prim_curvature）​

def get_line_prim_curvature() -> float

获取直线基元曲率

返回值

类型描述
float-

打印输出（print）​

def print() -> None

打印直线轨迹检查基元信息到标准输出

设置圆柱体基元半径（set_cylinder_prim_radius）​

def set_cylinder_prim_radius(radius: SupportsFloat) -> None

设置圆柱基元半径（米）

参数

名称类型默认值描述
radiusSupportsFloat需要传参-
note

较大的半径增加安全裕度但可能过于保守。

note

仅当基元类型为 CYLINDER 时适用。

设置直线检查基元类型（set_line_check_primitive_type）​

def set_line_check_primitive_type(type: PrimitiveType) -> None

设置直线检查基元类型

参数

名称类型默认值描述
typePrimitiveType需要传参-
note

推荐 CYLINDER 用于安全关键应用。

设置直线基元曲率（set_line_prim_curvature）​

def set_line_prim_curvature(curvature: SupportsFloat) -> None

设置直线基元曲率

参数

名称类型默认值描述
curvatureSupportsFloat需要传参-
note

控制如何将弯曲路径离散为直线段。

note

较低的值提高精度但增加计算成本。

日志级别（LogLevel）​

表示日志消息的严重级别。

枚举值描述
CRITICAL严重日志
DEBUG调试日志
ERROR错误日志
INFO信息日志
TRACE跟踪日志
WARN警告日志

机器类型（MachineType）​

此枚举定义了 Galbot SDK 支持的不同机器人平台或机器类型。客户端可以使用这些值来指定他们正在使用的机器人模型，特别是对于返回特定于平台的实现的工厂方法。将枚举保留在通用类型定义中可确保整个 SDK 的一致性，同时隐藏各个模块中的实现细节。

枚举值描述
G1G1机器人
G3G3机器人
S1S1机器人

运动规划链目标（MotionPlanChainTarget）​

单个路点上某一运动链的目标。

为指定的运动链选择关节空间或笛卡尔空间目标。多个 MotionPlanChainTarget 对象可组合到同一个 MotionPlanWaypoint 中，以协调多个运动链在同一路点上的目标。

成员变量​
名称类型描述
cartPoseState当 mode 为 MotionPlanTargetMode::kCartesian 时使用的笛卡尔空间目标。
chain_namestr该路点上目标运动链的名称。
jointJointStates当 mode 为 MotionPlanTargetMode::kJoint 时使用的关节空间目标。
modeMotionPlanTargetMode选择当前生效的目标表示方式。

运动规划配置（MotionPlanConfig）​

全面的运动规划配置管理。

MotionPlanConfig 充当所有运动规划子系统的集中配置容器。它聚合了采样策略、轨迹生成参数、逆运动学解算器设置、碰撞检测选项、可行性验证标准和运动学约束边界。此类提供了用于配置复杂运动规划管道的统一接口，支持简单的机械臂规划和具有多个运动链的全身人形运动生成。配置对象通过共享指针进行延迟初始化和管理，以优化内存使用并支持可选功能配置。

创建碰撞检查选项（create_collision_check_option）​

def create_collision_check_option() -> CollisionCheckOption

创建碰撞检测选项并返回

返回值

类型描述
CollisionCheckOption-

创建IK 求解器配置（create_ik_solver_config）​

def create_ik_solver_config() -> IKSolverConfig

创建逆运动学求解器配置并返回

返回值

类型描述
IKSolverConfig-

创建直线轨迹检查基元（create_line_traj_check_primitive）​

def create_line_traj_check_primitive() -> LineTrajCheckPrimitive

创建直线轨迹检查基元并返回

返回值

类型描述
LineTrajCheckPrimitive-

创建采样器配置（create_sampler_config）​

def create_sampler_config() -> SamplerConfig

创建采样器配置并返回

返回值

类型描述
SamplerConfig-

创建轨迹可行性检查选项（create_trajectory_feasibility_check_option）​

def create_trajectory_feasibility_check_option() -> TrajectoryFeasibilityCheckOption

创建轨迹可行性检查选项并返回

返回值

类型描述
TrajectoryFeasibilityCheckOption-

创建轨迹规划配置（create_trajectory_plan_config）​

def create_trajectory_plan_config() -> TrajectoryPlanConfig

创建轨迹规划配置并返回

返回值

类型描述
TrajectoryPlanConfig-

获取碰撞检查选项（get_collision_check_option）​

def get_collision_check_option() -> CollisionCheckOption

获取碰撞检测选项

返回值

类型描述
CollisionCheckOption-
note

使用 create_collision_check_option() 确保有效的配置。

获取碰撞检查选项引用（get_collision_check_option_ref）​

def get_collision_check_option_ref() -> CollisionCheckOption

获取碰撞检测选项引用

返回值

类型描述
CollisionCheckOption-

获取可行性边界（get_feasibility_boundary）​

def get_feasibility_boundary() -> list[KinematicsBoundary]

获取可行性边界约束

返回值

类型描述
list[KinematicsBoundary]-

获取硬关节约束（get_hard_joint_limit）​

def get_hard_joint_limit() -> list[KinematicsBoundary]

获取硬关节位置限制边界

返回值

类型描述
list[KinematicsBoundary]-

获取IK 关节约束（get_ik_joint_limit）​

def get_ik_joint_limit() -> list[KinematicsBoundary]

获取逆运动学关节位置限制边界

返回值

类型描述
list[KinematicsBoundary]-

获取IK 求解器配置（get_ik_solver_config）​

def get_ik_solver_config() -> IKSolverConfig

获取逆运动学求解器配置

返回值

类型描述
IKSolverConfig-
note

使用 create_ik_solver_config() 确保有效的配置。

获取IK 求解器配置引用（get_ik_solver_config_ref）​

def get_ik_solver_config_ref() -> IKSolverConfig

获取逆运动学求解器配置引用

返回值

类型描述
IKSolverConfig-

获取直线轨迹检查基元（get_line_traj_check_primitive）​

def get_line_traj_check_primitive() -> LineTrajCheckPrimitive

获取直线轨迹检查基元

返回值

类型描述
LineTrajCheckPrimitive-
note

使用 create_line_traj_check_primitive() 确保有效的配置。

获取直线轨迹检查基元引用（get_line_traj_check_primitive_ref）​

def get_line_traj_check_primitive_ref() -> LineTrajCheckPrimitive

获取直线轨迹检查基元引用

返回值

类型描述
LineTrajCheckPrimitive-

获取是否恢复 IK 关节限制（get_revert_ik_joint_limit）​

def get_revert_ik_joint_limit() -> bool

获取是否恢复逆运动学关节限制

返回值

类型描述
bool-

获取需要恢复 IK 关节限制的运动链（get_revert_ik_joint_limit_chains）​

def get_revert_ik_joint_limit_chains() -> list[str]

获取需要恢复逆运动学关节限制的运动链列表

返回值

类型描述
list[str]-

获取采样器配置（get_sampler_config）​

def get_sampler_config() -> SamplerConfig

获取采样器配置

返回值

类型描述
SamplerConfig-
note

使用 create_sampler_config() 确保有效的配置。

获取采样器配置引用（get_sampler_config_ref）​

def get_sampler_config_ref() -> SamplerConfig

获取采样器配置引用

返回值

类型描述
SamplerConfig-

获取采样关节约束（get_sampler_joint_limit）​

def get_sampler_joint_limit() -> list[KinematicsBoundary]

获取采样器关节位置限制边界

返回值

类型描述
list[KinematicsBoundary]-

获取轨迹可行性检查选项（get_trajectory_feasibility_check_option）​

def get_trajectory_feasibility_check_option() -> TrajectoryFeasibilityCheckOption

获取轨迹可行性检查选项

返回值

类型描述
TrajectoryFeasibilityCheckOption-
note

使用 create_trajectory_feasibility_check_option() 确保有效的配置。

获取轨迹可行性检查选项引用（get_trajectory_feasibility_check_option_ref）​

def get_trajectory_feasibility_check_option_ref() -> TrajectoryFeasibilityCheckOption

获取轨迹可行性检查选项引用

返回值

类型描述
TrajectoryFeasibilityCheckOption-

获取轨迹规划配置（get_trajectory_plan_config）​

def get_trajectory_plan_config() -> TrajectoryPlanConfig

获取轨迹规划配置

返回值

类型描述
TrajectoryPlanConfig-
note

使用 create_trajectory_plan_config() 确保有效的配置。

获取轨迹规划配置引用（get_trajectory_plan_config_ref）​

def get_trajectory_plan_config_ref() -> TrajectoryPlanConfig

获取轨迹规划配置引用

返回值

类型描述
TrajectoryPlanConfig-

获取更新时间（get_update_time）​

def get_update_time() -> int

获取更新时间参数

返回值

类型描述
int-

打印输出（print）​

def print() -> None

将完整的运动规划配置打印到标准输出。

以人类可读格式输出所有子配置参数和运动学边界信息，便于调试、日志记录以及配置状态校验。

设置碰撞检查选项（set_collision_check_option）​

def set_collision_check_option(option: CollisionCheckOption) -> None

设置碰撞检测选项

参数

名称类型默认值描述
optionCollisionCheckOption需要传参-

设置可行性边界（set_feasibility_boundary）​

def set_feasibility_boundary(boundary: Sequence[KinematicsBoundary]) -> None

设置可行性边界约束

参数

名称类型默认值描述
boundarySequence[KinematicsBoundary]需要传参-
note

这些边界用于一般轨迹可行性检查。

设置硬关节约束（set_hard_joint_limit）​

def set_hard_joint_limit(boundary: Sequence[KinematicsBoundary]) -> None

设置硬关节位置限制边界

参数

名称类型默认值描述
boundarySequence[KinematicsBoundary]需要传参-
note

硬限制必须永不违反；通常对应于物理极限。

设置IK 关节约束（set_ik_joint_limit）​

def set_ik_joint_limit(boundary: Sequence[KinematicsBoundary]) -> None

设置逆运动学关节位置限制边界

参数

名称类型默认值描述
boundarySequence[KinematicsBoundary]需要传参-
note

IK 限制可能比硬限制更紧以改善收敛性。

设置IK 求解器配置（set_ik_solver_config）​

def set_ik_solver_config(config: IKSolverConfig) -> None

设置逆运动学求解器配置

参数

名称类型默认值描述
configIKSolverConfig需要传参-

设置直线轨迹检查基元（set_line_traj_check_primitive）​

def set_line_traj_check_primitive(primitive: LineTrajCheckPrimitive) -> None

设置直线轨迹检查基元

参数

名称类型默认值描述
primitiveLineTrajCheckPrimitive需要传参-

设置是否恢复 IK 关节限制（set_revert_ik_joint_limit）​

def set_revert_ik_joint_limit(flag: bool) -> None

设置是否恢复逆运动学关节限制

参数

名称类型默认值描述
flagbool需要传参-
note

用于通过暂时恢复极端限制来从受限配置中恢复。

设置需要恢复 IK 关节限制的运动链（set_revert_ik_joint_limit_chains）​

def set_revert_ik_joint_limit_chains(chains: Sequence[str]) -> None

设置需要恢复逆运动学关节限制的运动链列表

参数

名称类型默认值描述
chainsSequence[str]需要传参-
note

如果非空，自动启用 revert_ik_joint_limit 标志。

note

空向量禁用选择性恢复（适用于所有链）。

设置采样器配置（set_sampler_config）​

def set_sampler_config(config: SamplerConfig) -> None

设置采样器配置

参数

名称类型默认值描述
configSamplerConfig需要传参-

设置采样关节约束（set_sampler_joint_limit）​

def set_sampler_joint_limit(boundary: Sequence[KinematicsBoundary]) -> None

设置采样器关节位置限制边界

参数

名称类型默认值描述
boundarySequence[KinematicsBoundary]需要传参-
note

采样限制定义了探索配置空间的有效范围。

设置轨迹可行性检查选项（set_trajectory_feasibility_check_option）​

def set_trajectory_feasibility_check_option(option: TrajectoryFeasibilityCheckOption) -> None

设置轨迹可行性检查选项

参数

名称类型默认值描述
optionTrajectoryFeasibilityCheckOption需要传参-

设置轨迹规划配置（set_trajectory_plan_config）​

def set_trajectory_plan_config(config: TrajectoryPlanConfig) -> None

设置轨迹规划配置

参数

名称类型默认值描述
configTrajectoryPlanConfig需要传参-

设置更新时间（set_update_time）​

def set_update_time(t: SupportsInt) -> None

设置更新时间参数

参数

名称类型默认值描述
tSupportsInt需要传参-
note

用于配置版本控制和缓存失效。

运动规划目标模式（MotionPlanTargetMode）​

单链运动规划目标所使用的表示方式。

枚举值描述
kCartesian使用 MotionPlanChainTarget::cart 中存储的笛卡尔目标。
kJoint使用 MotionPlanChainTarget::joint 中存储的关节空间目标。

运动规划类型（MotionPlanType）​

组合运动规划中某一段所使用的规划算法。

枚举值描述
MOTION_PLAN基于采样、考虑碰撞的路径规划。
MOVE_LINE带逆运动学采样的笛卡尔直线插值。
TRAJ_PLAN不做路径搜索的关节空间直接插值。

运动状态（MotionStatus）​

机器人动作执行状态枚举。

表示机器人运动命令的执行状态，包括轨迹跟随、位姿到达等运动规划操作。

枚举值描述
COMM_DISCONNECTED通信断开
DATA_FETCH_FAILED数据获取失败
FAULT故障
INIT_FAILED初始化失败
INVALID_INPUT无效输入
IN_PROGRESS进行中
PUBLISH_FAIL发布失败
STATUS_NUM状态数量
STOPPED_UNREACHED已停止但未到达
SUCCESS成功
TIMEOUT超时
UNSUPPORTED_FUNCRION不支持的函数

导航任务快照。

导航任务状态。

枚举值描述
CLOSE_TO_OBSTACLE接近障碍物。
COLLISION碰撞。
FAILED失败。
INTERRUPTED中断。
OCCUPIED占用。
RUNNING运行中。
SUCCESS成功。
UNKNOWN未知。

里程计数据（OdomData）​

里程计数据。 包含来自里程计源（轮式编码器、IMU 融合等）的机器人位姿和速度估计。用于机器人定位和导航。

成员变量​
名称类型描述
angular_velocitylist[float]角速度 [ωx, ωy, ωz]（弧度/秒）
linear_velocitylist[float]线速度 [vx, vy, vz]（米/秒）
orientationlist[float]四元数方向 [qx, qy, qz, qw]
positionlist[float]位置 [x, y, z]（米）
timestamp_nsint里程计时间戳（自纪元以来的纳秒数）

参数（Parameter）​

运动规划参数配置类。

Parameter 派生自 PlannerConfig，且不新增配置字段。对于签名接受 std::shared_ptr<Parameter> 的高级 API，请使用 Parameter，它提供了便捷的构造函数以及 setter/getter 方法；对于签名接受 const PlannerConfig& 的路点/服务器侧 API，请直接使用 PlannerConfig。所有角度参数均以弧度为单位，长度参数以米为单位（SI 单位制）。

成员变量​
名称类型描述
actuate_typeActuateType允许参与规划的运动链。
enable_env_collision_checkbool是否将已加载的环境障碍物纳入碰撞检测。
is_blockingbool是否等待规划或执行完成。
is_check_collisionbool是否启用规划碰撞检测。
is_direct_executebool规划完成后是否立即执行。
is_tool_posebool将笛卡尔目标解释为已连接工具的 TCP 位姿，而非法兰位姿。
joint_statedict[str, list[float]]按运动链指定的可选规划初值；映射为空时使用当前状态。
move_linebool在按该字段分发的 API 中选择目标坐标系的笛卡尔直线运动。
reference_framestr使用该字段的 API 所采用的参考坐标系。
timeout_secondfloat规划或执行请求的最大等待时间（秒）。

获取驱动类型（get_actuate_type）​

def get_actuate_type() -> str

获取驱动类型

返回值

类型描述
str-

获取是否阻塞（get_blocking）​

def get_blocking() -> bool

获取是否阻塞执行

返回值

类型描述
bool-

获取是否检测碰撞（get_check_collision）​

def get_check_collision() -> bool

获取是否进行碰撞检测

返回值

类型描述
bool-

获取是否直接执行（get_direct_execute）​

def get_direct_execute() -> bool

获取是否直接执行

返回值

类型描述
bool-

获取参考帧（get_reference_frame）​

def get_reference_frame() -> str

获取参考坐标系

返回值

类型描述
str-

获取超时（get_timeout）​

def get_timeout() -> float

获取超时时间（秒）

返回值

类型描述
float-

获取工具位姿（get_tool_pose）​

def get_tool_pose() -> bool

获取目标工具位姿

返回值

类型描述
bool-

设置驱动类型（set_actuate）​

def set_actuate(actuate: str) -> None

设置驱动类型

参数

名称类型默认值描述
actuatestr需要传参-
note

无效的键会被忽略，当前驱动类型保持不变。

设置是否阻塞（set_blocking）​

def set_blocking(blocking: bool) -> None

设置是否阻塞执行

参数

名称类型默认值描述
blockingbool需要传参-

设置是否检测碰撞（set_check_collision）​

def set_check_collision(check_collision: bool) -> None

设置是否进行碰撞检测

参数

名称类型默认值描述
check_collisionbool需要传参-
warning

禁用碰撞检查可能会导致不安全的轨迹。

设置是否直接执行（set_direct_execute）​

def set_direct_execute(direct_execute: bool) -> None

设置是否直接执行

参数

名称类型默认值描述
direct_executebool需要传参-

设置是否启用环境碰撞检查（set_enable_env_collision_check）​

def set_enable_env_collision_check(enable: bool) -> None

启用或禁用针对已加载环境障碍物的碰撞检测。

参数

名称类型默认值描述
enablebool需要传参-
note

该标志仅由会将环境碰撞配置转发给运动服务的规划类 API 使用。环境障碍物必须先通过 add_obstacle() 或 attach_target_object() 注册，并且在环境变化时由调用方显式更新这些碰撞物体。GalbotMotion 不提供实时障碍物感知、环境自动更新或动态环境避障能力。

设置是否移动直线（set_move_line）​

def set_move_line(move_line: bool) -> None

设置笛卡尔直线运动模式。

在按 Parameter::move_line 分发的 API（包括 set_end_effector_pose() 和 motion_plan()）中选择笛卡尔直线规划器。受控目标坐标系将在笛卡尔空间中从当前位姿插值到请求的位姿。该约束作用于目标坐标系的路径，而非各关节的运动。

参数

名称类型默认值描述
move_linebool需要传参-
note

仅在任务要求目标坐标系做笛卡尔直线运动时才启用该模式。若中间位姿不可达、经过奇异点、超出关节限位或不存在连续的 IK 解，直线请求可能失败。

note

GalbotMotion::move_line 对其 MotionPlanWaypoints 输入始终选择笛卡尔直线规划，不要求 Parameter::move_line 为 true。

设置参考帧（set_reference_frame）​

def set_reference_frame(frame: str) -> None

设置参考坐标系

参数

名称类型默认值描述
framestr需要传参-
note

必须是机器人 TF 树中的有效帧。

设置超时（set_timeout）​

def set_timeout(timeout: SupportsFloat) -> None

设置运动执行超时时间（秒）

参数

名称类型默认值描述
timeoutSupportsFloat需要传参-
note

在会启动后台执行任务的 API 中，该超时时间仍会被该任务采用。

设置工具位姿（set_tool_pose）​

def set_tool_pose(tool_pose: bool) -> None

设置目标工具位姿

参数

名称类型默认值描述
tool_posebool需要传参-

感知模块（PerceptionModule）​

启用的感知管道（初始化时加载的模型集）。

枚举值描述
FOUNDATION_STEREO高精度立体深度；用于需要高精度的任务（如搬箱子场景）。
LIGHT_STEREO轻量级立体深度；用于精度要求不高的场景（如迎宾场景）。此版本不支持。

规划器配置（PlannerConfig）​

运动规划配置结构。

用于机器人运动规划和执行的全面配置，控制规划模式、碰撞检查、参考坐标系和执行参数等行为。

成员变量​
名称类型描述
actuate_typeActuateType驱动类型（运动链选择）。
- "with_chain_only": 仅使用指定的运动链
- "with_torso": 包含躯干
- "with_leg": 包含腿部
- "unknown": 未知类型
enable_env_collision_checkbool是否将已加载的环境障碍物纳入碰撞检测。
is_blockingbool是否同步等待操作完成，true 表示阻塞直到规划/执行完成或超时发生，false 表示立即返回（异步模式）
is_check_collisionbool是否在规划期间启用碰撞检测，true 表示检查与障碍物和自碰撞，false 表示跳过碰撞检测（请谨慎使用）
is_direct_executebool是否在规划后立即执行轨迹，true 表示一次性完成规划和执行，false 表示仅规划轨迹（用于预览或验证）
is_relative_posebool目标位姿是否相对于当前位姿，true 表示目标位姿是相对于当前位置的位移，false 表示目标位姿是绝对位姿
is_tool_posebool目标是否指定为工具中心点 (TCP) 位姿，true 表示目标是末端执行器 TCP 位姿（笛卡尔空间），false 表示目标是关节空间配置
joint_statedict[str, list[float]]指定规划的起始关节配置。
- 键（key）：关节名称
- 值（value）：关节角度（弧度）
- 空字典表示使用当前机器人状态
move_linebool是否规划直线运动，true 表示在笛卡尔空间中规划直线运动（末端执行器沿直线移动），false 表示在关节空间中规划标准轨迹（可能不是笛卡尔直线）
reference_framestr目标位姿的参考坐标系。
指定目标位姿所在的坐标系，例如：
- "base_link": 机器人底座坐标系
- "world": 世界坐标系
- "odom": 里程计坐标系
timeout_secondfloat阻塞操作的超时时间（秒），等待规划或执行完成的最大时间，默认值：20 秒

规划请求（PlanRequest）​

组合运动规划中单个段的规划请求。

定义 GalbotMotion::combine_plan() 使用的规划算法、段级问题后的放行行为、预留的段级选项以及有序的目标路点。每个路点可包含一个或多个运动链的协调目标。SDK 会将所有请求的 enforce_pass 取逻辑与后发送给 MPS。因此，只有当每个请求都将 enforce_pass 设为 true 时，MPS 才会在出现段级问题后继续规划；只要有任一请求为 false，即表示要求中止整个组合规划。

成员变量​
名称类型描述
enforce_passbool是否允许在段级问题后继续；所有请求的取值按逻辑与合并。
optionsPlannerConfig段级规划选项，为 combine_plan() 未来的覆盖配置预留。
plan_typeMotionPlanType该段使用的 MotionPlanType 规划算法。
targetlist[list[MotionPlanChainTarget]]该段有序的多运动链目标路点。

点（Point）​

表示三维笛卡尔空间中的位置。

成员变量​
名称类型描述
xfloat-
yfloat-
zfloat-

二维点（Point2d）​

表示二维笛卡尔空间中的位置。

成员变量​
名称类型描述
xfloat-
yfloat-

点云字段（PointField）​

描述 PointCloud2 点结构中的一个数据字段，定义其名称、类型、偏移量和计数。与 ROS 2sensor_msgs/PointField 兼容。

成员变量​
名称类型描述
countint此字段的数组长度，标量字段（x, y, z, intensity）通常为 1，数组字段可能大于 1（例如 count=3 表示 3 元素向量）
datatype...数据类型
offsetint此字段相对于点数据结构起始位置的字节偏移量，例如：对于点布局 [x(float32), y(float32), z(float32), intensity(float32)]，x 的偏移为 0，y 的偏移为 4，z 的偏移为 8，intensity 的偏移为 12

点云字段数据类型（PointFieldDataType）​

数据类型枚举。

定义点云字段的原始数据类型，确定每个字段值的字节大小和解释方法。

枚举值描述
FLOAT3232位浮点数
FLOAT6464位浮点数
INT1616位整数
INT3232位整数
INT88位整数
UINT1616位无符号整数
UINT3232位无符号整数
UINT88位无符号整数
UNKNOWN未知

姿态（Pose）​

姿态（位置+方向）结构。

表示 3D 空间中的完整 6-DOF（自由度）姿态，结合位置（平移）和方向（旋转）信息。常用于机器人末端执行器姿态、物体姿态和坐标系变换。

二维位姿（Pose2d）​

二维位姿（位置+偏航）结构，适用于移动基座和导航目标表示二维笛卡尔空间中的平面位姿，结合了位置（平移）和航向角信息。

常用于移动基座位姿和局部导航目标。

成员变量​
名称类型描述
thetafloat-

姿态状态（PoseState）​

表示笛卡尔空间 (SE(3)) 中的目标末端执行器姿态。扩展 RobotStates 为运动链指定基于姿态的运动目标。用于逆运动学和笛卡尔轨迹规划。姿态值：以米为单位的位置，以四元数为单位的方向。坐标系必须存在于机器人的 TF 树中。

成员变量​
名称类型描述
assist_chainsset[str]-

获取类型（get_type）​

def get_type() -> RobotStatesType

获取位姿状态类型

返回值

类型描述
RobotStatesType-

几何基元类型（PrimitiveType）​

原始类型相关说明。

枚举值描述
CYLINDER圆柱体
LINE直线

四元数（Quaternion）​

使用四元数表示 (x, y, z, w) 表示 3D 旋转。单位四元数的大小为 1，表示有效旋转。

成员变量​
名称类型描述
wfloat-
xfloat-
yfloat-
zfloat-

RGB数据（RgbData）​

RGB/彩色图像数据结构

成员变量​
名称类型描述
databytes包含压缩图像数据的二进制数据块
formatstr图像编码格式字符串
headerHeader消息头，包含采集时间戳
heightint图像高度
output_formatRgbOutputFormat图像输出编码格式
plane_countint原始 plane 布局
plane_offset_byteslist[int]每个 plane 相对于 data 起始位置的字节偏移量
stride_byteslist[int]每个 plane 的步长（单位：字节）
widthint图像宽度

RGB图像输出格式（RgbOutputFormat）​

RGB 相机图像的输出格式

枚举值描述
BGRBGR格式
JPEGJPEG格式
NV12NV12格式
RGBRGB格式

机器人状态（RobotStates）​

封装机器人的完整运动状态，包括全身关节配置和移动底座位姿。此类作为更专业的状态表示（PoseState、JointStates）的基础，并在整个规划和控制管道中用于状态规范和反馈。所有角度值均以弧度为单位，线性值以米（SI 单位）为单位。基本姿态使用四元数表示方向（x、y、z、qx、qy、qz、qw）。

成员变量​
名称类型描述
base_statelist[float]-
whole_body_jointlist[float]-

获取类型（get_type）​

def get_type() -> RobotStatesType

获取机器人状态类型

返回值

类型描述
RobotStatesType-

设置基座状态（set_base_state）​

def set_base_state(base_pose: Pose) -> None

设置底座状态（位姿）

参数

名称类型默认值描述
base_posePose需要传参-
note

四元数必须单位归一化（x^2 + y^2 + z^2 + w^2 = 1）。

设置全身关节（set_whole_body_joint）​

def set_whole_body_joint(joint_positions: list[float]) -> None

设置全身关节位置

参数

名称类型默认值描述
joint_positionslist[float]需要传参-
note

向量大小应等于总驱动关节数。

机器人状态类型（RobotStatesType）​

用于区分派生状态类型的枚举。

用于RobotStates派生类的运行时类型识别。

枚举值描述
JOINT关节
POSE姿态
ROBOT_STATES机器人状态数量

S1控制器名称（S1ControllerName）​

S1 机器人的控制器名称常量。

将这些名称传递给 GalbotRobot 的控制器管理接口，例如 switch_controller() 和 acquire_controller()。控制器决定某个硬件组如何解释后续目标；注册到同一硬件组的控制器之间互斥。切换控制器本身不会下发运动指令。控制器的可用性取决于机器人版本、已安装的末端工具以及服务端 SingoriX 配置。切换成功即表示所选控制器在当前连接的机器人上可用。

枚举值描述
ELEVATOR_CTRLS1 躯干升降机构位置控制器。读取躯干升降关节位置目标，应用指令滤波，并将结果高度指令发送至 S1 底盘/升降机构接口。用于升高或降低上半身；它不是腿部或底盘运动控制器。
HEAD_PVT_CTRL头部常规关节 PVT 控制器。使用配置的 PID、滤波器和限幅，在每个控制周期发布采样后的头部关节位置、速度和力矩指令。用于常规头部定位及规划的头部轨迹。
LEFT_ARM_PVT_CTRL左臂 EtherCAT 关节 PVT 控制器。使用配置的 PID、滤波、动力学模型和关节限制，将采样后的左臂七轴位置、速度和力矩指令发送至 S1 EtherCAT 臂部接口。是规划臂部运动的标准控制器。
LEFT_GRIPPER_CTRL左夹爪开合控制器。通过 S1 EtherCAT 接口下发左夹爪位置/开合指令及速度、力矩参数。它将简单夹爪作为单一末端工具动作进行控制；其他已安装的末端工具使用各自的服务端控制器名称。
RIGHT_ARM_PVT_CTRL右臂 EtherCAT 关节 PVT 控制器。使用配置的 PID、滤波、动力学模型和关节限制，将采样后的右臂七轴位置、速度和力矩指令发送至 S1 EtherCAT 臂部接口。是规划臂部运动的标准控制器。
RIGHT_GRIPPER_CTRL右夹爪开合控制器。通过 S1 EtherCAT 接口下发右夹爪位置/开合指令及速度、力矩参数。它将简单夹爪作为单一末端工具动作进行控制；其他已安装的末端工具使用各自的服务端控制器名称。
SWERVE_CHASSIS_POSE_CTRL舵轮底盘闭环位姿与路径控制器。利用定位或里程计反馈跟踪平面位置/朝向目标或路径，将得到的底盘运动转换为转向角和轮速，并报告目标完成情况。用于导航和位姿目标场景。与 SWERVE_CHASSIS_TWIST_CTRL 不同，它执行位姿/路径跟踪与到位检测。
SWERVE_CHASSIS_TWIST_CTRL舵轮底盘直接速度控制器。跟踪平面速度指令 [vx, vy, wz]，应用配置的滤波及速度/加速度限制，随后执行舵轮驱动运动学解算。用于遥操作等连续速度控制场景，不跟踪目标点，也不判断位姿目标是否到达。

S1关节组（S1JointGroup）​

“关节组”是 SDK 的主要控制/规划单元，而不是单个关节： 运动一致控制：每个链/末端执行器组都会验证和执行命令。确定性命令排序：joint_groups 按组顺序扩展为具体的 joint_names。组级行为：每个组都有自己的主动/被动属性和执行容忍度。推荐用法：在填充 API 参数（例如 joint_groups）时，使用此结构体中的常量。如果需要精确的关节名称，请在运行时通过 get_joint_names(true, {group_name}) 查询它们，而不是硬编码。在同时接受 joint_groups 和 joint_names 的 API 中，joint_names 优先。

枚举值描述
head头部
left_arm左7自由度手臂链。默认关节：left_arm_joint1 ... left_arm_joint7。典型用途：左臂操作。
left_gripper左夹爪链。默认关节：left_gripper_joint1。典型用途：夹爪宽度控制。
right_arm右7自由度手臂链。默认关节：right_arm_joint1 ... right_arm_joint7。典型用途：右臂操作。
right_gripper右夹爪链。默认关节：right_gripper_joint1。典型用途：夹爪宽度控制。
swerve_chassis舵机底盘机构组（关节位置控制中为被动）。
默认关节：Wheel_1_direction、Wheel_1_velocity、Wheel_2_direction、Wheel_2_velocity...
torso躯干

采样器配置（SamplerConfig）​

基于采样的运动规划器的配置参数。

该结构配置基于采样的规划算法（例如，RRT、RRT*）。它控制状态空间采样分辨率、插值设置、路径简化和规划终止条件。基于采样的规划器通过随机采样状态并将它们连接起来构建运动计划图来探索配置空间。

获取是否插值（get_interpolate）​

def get_interpolate() -> bool

获取是否启用插值

返回值

类型描述
bool-

获取插值数量（get_interpolation_cnt）​

def get_interpolation_cnt() -> int

获取插值点数量

返回值

类型描述
int-

获取最大规划时间（get_max_planning_time）​

def get_max_planning_time() -> float

获取最大规划时间（秒）

返回值

类型描述
float-

获取最大简化时间（get_max_simplification_time）​

def get_max_simplification_time() -> float

获取最大简化时间（秒）

返回值

类型描述
float-

获取是否简化（get_simplify）​

def get_simplify() -> bool

获取是否启用简化

返回值

类型描述
bool-

获取状态检查分辨率（get_state_check_resolution）​

def get_state_check_resolution() -> float

获取状态检查分辨率

返回值

类型描述
float-

获取状态检查类型（get_state_check_type）​

def get_state_check_type() -> StateCheckType

获取状态检查类型

返回值

类型描述
StateCheckType-

获取终止条件类型（get_termination_condition_type）​

def get_termination_condition_type() -> TerminationConditionType

获取终止条件类型

返回值

类型描述
TerminationConditionType-

打印输出（print）​

def print() -> None

打印采样器配置信息到标准输出

设置是否插值（set_interpolate）​

def set_interpolate(enable: bool) -> None

设置是否启用插值

参数

名称类型默认值描述
enablebool需要传参-
note

插值可提高轨迹平滑度和碰撞检测覆盖率。

设置插值数量（set_interpolation_cnt）​

def set_interpolation_cnt(cnt: SupportsInt) -> None

设置插值点数量

参数

名称类型默认值描述
cntSupportsInt需要传参-
note

较高的计数可改善碰撞检测但增加计算成本。

设置最大规划时间（set_max_planning_time）​

def set_max_planning_time(time: SupportsFloat) -> None

设置最大规划时间（秒）

参数

名称类型默认值描述
timeSupportsFloat需要传参-
note

如果找到精确解，规划可能提前终止（取决于终止条件）。

设置最大简化时间（set_max_simplification_time）​

def set_max_simplification_time(time: SupportsFloat) -> None

设置最大简化时间（秒）

参数

名称类型默认值描述
timeSupportsFloat需要传参-
note

较长的简化时间可能产生更短、更平滑的路径。

设置是否简化（set_simplify）​

def set_simplify(enable: bool) -> None

设置是否启用简化

参数

名称类型默认值描述
enablebool需要传参-
note

简化减少路点并提高轨迹效率。

设置状态检查分辨率（set_state_check_resolution）​

def set_state_check_resolution(resolution: SupportsFloat) -> None

设置状态检查分辨率

参数

名称类型默认值描述
resolutionSupportsFloat需要传参-
note

较低的值增加规划精度但可能减慢计算速度。

设置状态检查类型（set_state_check_type）​

def set_state_check_type(type: StateCheckType) -> None

设置状态检查类型

参数

名称类型默认值描述
typeStateCheckType需要传参-

设置终止条件类型（set_termination_condition_type）​

def set_termination_condition_type(type: TerminationConditionType) -> None

设置终止条件类型

参数

名称类型默认值描述
typeTerminationConditionType需要传参-

随机种子类型（SeedType）​

指定逆运动学 (IK) 解算器的初始化策略。不同的种子类型会影响收敛速度和解的质量。

枚举值描述
RANDOM_PROGRESSIVE_SEED随机渐进种子
RANDOM_SEED随机种子
USER_DEFINED_SEED用户自定义种子

传感器状态（SensorStatus）​

表示传感器数据采集和处理操作的状态，适用于相机、激光雷达、IMU、力传感器和其他传感器类型。

枚举值描述
COMM_DISCONNECTED通信断开
DATA_FETCH_FAILED数据获取失败，传感器可能已断开连接或损坏
FAULT故障
INIT_FAILED初始化失败
INVALID_INPUT无效输入
IN_PROGRESS进行中
PUBLISH_FAIL发布失败
STOPPED_UNREACHED已停止但未到达
SUCCESS成功
TIMEOUT超时

传感器类型（SensorType）​

描述机器人上各种传感器的传感器类型枚举。

识别机器人上可用于感知、定位和操作任务的不同传感器类型。

枚举值描述
BACK_IMUS1 后部激光雷达 IMU
BACK_LIDARS1 后部激光雷达
CHASSIS_IMU底盘 IMU
CHASSIS_LIDARS1 底盘前向激光雷达
HEAD_IMUS1 头部激光雷达 IMU
HEAD_LEFT_CAMERA头部左相机
HEAD_LIDARS1 头部前向激光雷达
HEAD_RIGHT_CAMERA头部右相机
LEFT_ARM_CAMERA左臂相机
LEFT_ARM_DEPTH_CAMERA左臂深度相机，为 G1/S1 左臂工作空间提供 RGB-D 数据
LEFT_ARM_INFRA_CAMERA_1左臂红外相机 1
LEFT_ARM_INFRA_CAMERA_2左臂红外相机 2
RIGHT_ARM_CAMERA右臂相机
RIGHT_ARM_DEPTH_CAMERA右臂深度相机，为 G1/S1 右臂工作空间提供 RGB-D 数据
RIGHT_ARM_INFRA_CAMERA_1右臂红外相机 1
RIGHT_ARM_INFRA_CAMERA_2右臂红外相机 2

SingoriX目标（SingoriXTarget）​

SingoriX控制器的目标表示，用于与SingoriX外部控制器通信。

成员变量​
名称类型描述
headerHeader消息头
target_group_trajectory_mapdict[str, TargetGroupTrajectory]关节空间轨迹映射
target_task_trajectory_mapdict[str, TargetTaskTrajectory]任务空间轨迹映射

状态检查类型（StateCheckType）​

状态检查类型相关说明。

枚举值描述
EUCLIDEAN_DISTANCE欧氏距离
RADIAN_DISTANCE弧度距离

吸盘动作状态（SUCTION_ACTION_STATE）​

代表真空吸盘末端执行器的运行状态，跟踪从空闲到成功或失败的抽吸过程。

枚举值描述
FAILED失败
IDLE空闲
SUCCESS吸盘动作成功
SUCKING吸取中

吸盘状态（SuctionCupState）​

包含真空吸盘夹具的当前状态，包括激活状态、压力读数和动作状态。

成员变量​
名称类型描述
action_stateSUCTION_ACTION_STATE动作状态
activationbool激活
pressurefloat压力
timestamp_nsint状态时间戳（自纪元以来的纳秒数）

同步观测数据（SyncedObservation）​

同步多传感器观测数据。

包含按时间戳对齐的相机帧和可选关节状态。对齐锚点为传入 get_synced_observation() 的第一个相机。

成员变量​
名称类型描述
depth_data_mapdict[SensorType, DepthData]按时间戳对齐的深度图数据
joint_stateJointStateMessage锚点时间戳对应的最近邻关节状态
rgb_data_mapdict[SensorType, RgbData]按时间戳对齐的 NV12 图像数据

目标配置（TargetConfig）​

目标的配置参数，包含目标类型、采样方式、约束条件等设置。

成员变量​
名称类型描述
target_dataint目标数据位掩码
target_idstr目标标识符
target_priorityint目标优先级
target_samplingTargetSampling采样策略
target_tsTimestamp目标时间戳
target_typeint目标类型位掩码

目标关节组轨迹（TargetGroupTrajectory）​

目标在关节组空间中的轨迹，包含一系列途经点和时间信息。

成员变量​
名称类型描述
group_commandslist[GroupCommand]轨迹点
joint_nameslist[str]关节名称
target_configTargetConfig目标配置

目标采样（TargetSampling）​

目标轨迹的采样方法，用于在路径点之间生成中间点。

枚举值描述
TARGET_SAMPLING_B_SPLINESB样条采样
TARGET_SAMPLING_CUBIC_SPLINES三次样条采样
TARGET_SAMPLING_CUSTOM自定义采样
TARGET_SAMPLING_DEFAULT默认采样
TARGET_SAMPLING_DIRECT_PASS直接传递
TARGET_SAMPLING_LINEAR_INTERPOLATE线性插值采样
TARGET_SAMPLING_QUINTIC_SPLINES五次样条采样
TARGET_SAMPLING_S_CURVE_PROFILES曲线轮廓采样
TARGET_SAMPLING_TRAPEZOIDAL_PROFILE梯形轮廓采样

目标任务轨迹（TargetTaskTrajectory）​

目标在任务空间中的轨迹，包含任务级别的约束和要求。

成员变量​
名称类型描述
group_nameslist[str]关联的关节组名称
joint_nameslist[str]关联的关节名称
subtask_nameslist[str]子任务名称
target_configTargetConfig目标配置
task_commandslist[TaskCommand]轨迹点

任务命令（TaskCommand）​

任务级别的命令结构，包含一个或多个目标和执行参数。

成员变量​
名称类型描述
subtask_commandslist[FrameTriad]该时刻的子任务命令
time_from_start_sfloat相对轨迹起点的时间（秒）

导航任务句柄（TaskHandle）​

异步提交导航任务后返回的句柄。

终止条件类型（TerminationConditionType）​

终止条件类型相关说明。

枚举值描述
TIMEOUT仅当超过最大规划时间时终止
TIMEOUT_AND_EXACT_SOLUTION超时或精确解

时间戳（Timestamp）​

表示具有秒和纳秒分量的高精度时间点。兼容 ROS 2builtin_interfaces/Time 和 std_msgs/Header 时间戳格式。

成员变量​
名称类型描述
nanosecint纳秒
secint秒

轨迹（Trajectory）​

表示一个完整的机器人轨迹，包含多个随时间变化的路点。joint_groups 和 joint_names 不能同时为空。如果同时为空，函数将返回 ControlStatus::INVALID_INPUT。此限制确保了关节顺序的确定性，防止因隐式内部默认顺序（可能在 SDK 版本之间变化）导致的难以察觉的 bug。使用方法：推荐设置具有语义组名的 joint_groups 或 joint_names。如果同时设置，joint_names 优先于 joint_groups

成员变量​
名称类型描述
joint_groupslist[str]关节组名称列表，如 ["left_arm", "right_arm"]。注意：joint_groups 和 joint_names 不能同时为空
joint_nameslist[str]显式关节名称。当非空时，优先于 joint_groups，并且仅验证为活动关节。当 joint_groups 也为空时，不能同时为空。
pointslist[TrajectoryPoint]有序的轨迹路点列表。每个点的 joint_command_vec 必须与 joint_names 或 joint_groups 定义的关节顺序匹配。关节顺序的确定方式：(1) 如果 joint_names 非空，则使用 joint_names；(2) 否则使用 joint_groups 按顺序展开（例如，{"head","left_arm"} 展开为 head_joint1, head_joint2, left_arm_joint1, ... left_arm_joint7）。

轨迹控制状态（TrajectoryControlStatus）​

机器人轨迹执行状态枚举。

表示机器人沿着由多个路点组成的预先规划的轨迹运行时的实时执行状态。

枚举值描述
COMPLETED已完成
DATA_FETCH_FAILED数据获取失败
ERROR错误日志
INVALID_INPUT无效输入
RUNNING运行中
STOPPED_UNREACHED轨迹执行过程中停止但未达到终点

轨迹可行性检查选项（TrajectoryFeasibilityCheckOption）​

轨迹验证和可行性检查配置。

该结构提供了对在轨迹验证期间强制执行可行性约束的细粒度控制。它支持碰撞检测、关节限制合规性和速度剖面可行性的独立切换。有选择地禁用检查可以提高调试、模拟或保证满足某些约束的场景的计算性能。禁用可行性检查可能会产生不安全或物理上无法实现的轨迹。仅当通过其他方式验证约束时才应谨慎使用。

获取是否禁用碰撞检查（get_disable_collision_check）​

def get_disable_collision_check() -> bool

获取是否禁用碰撞检测

返回值

类型描述
bool-

获取是否禁用关节限制检查（get_disable_joint_limit_check）​

def get_disable_joint_limit_check() -> bool

获取是否禁用关节限制检查

返回值

类型描述
bool-

获取是否禁用速度可行性检查（get_disable_velocity_feasibility_check）​

def get_disable_velocity_feasibility_check() -> bool

获取是否禁用速度可行性检查

返回值

类型描述
bool-

打印输出（print）​

def print() -> None

打印轨迹可行性检查选项到标准输出

设置是否禁用碰撞检查（set_disable_collision_check）​

def set_disable_collision_check(disable: bool) -> None

设置是否禁用碰撞检测

参数

名称类型默认值描述
disablebool需要传参-
warning

禁用碰撞检查可能导致轨迹与环境发生碰撞

设置是否禁用关节限制检查（set_disable_joint_limit_check）​

def set_disable_joint_limit_check(disable: bool) -> None

设置是否禁用关节限制检查

参数

名称类型默认值描述
disablebool需要传参-
warning

禁用关节限制检查可能导致轨迹超出关节限位

设置是否禁用速度可行性检查（set_disable_velocity_feasibility_check）​

def set_disable_velocity_feasibility_check(disable: bool) -> None

设置是否禁用速度可行性检查

参数

名称类型默认值描述
disablebool需要传参-
note

速度可行性确保轨迹可以被机器人执行。

轨迹规划配置（TrajectoryPlanConfig）​

轨迹规划和参数化配置。

该结构配置轨迹生成参数，用于将离散运动计划转换为平滑的时间参数化轨迹。它支持单段和多路点轨迹规划。轨迹规划涉及计算沿几何路径的速度和加速度分布，同时尊重运动学约束。

获取最小移动时间（get_min_move_time）​

def get_min_move_time() -> float

获取最小运动时间（秒）

返回值

类型描述
float-

获取直线插值中间点（get_move_line_intermediate_point）​

def get_move_line_intermediate_point() -> float

获取直线运动中间点设置

返回值

类型描述
float-

获取路点规划预期时间（get_way_point_plan_expected_time）​

def get_way_point_plan_expected_time() -> float

获取路点规划期望时间

返回值

类型描述
float-

打印输出（print）​

def print() -> None

打印轨迹规划配置信息到标准输出

设置最小移动时间（set_min_move_time）​

def set_min_move_time(time: SupportsFloat) -> None

设置最小运动时间（秒）

参数

名称类型默认值描述
timeSupportsFloat需要传参-
note

非零值防止运动过快；0.0 允许在运动学限制内的最高速度

设置直线插值中间点（set_move_line_intermediate_point）​

def set_move_line_intermediate_point(value: SupportsFloat) -> None

设置直线运动中间点设置

参数

名称类型默认值描述
valueSupportsFloat需要传参-
note

较高的值提高笛卡尔路径精度但增加计算成本。

设置路点规划预期时间（set_way_point_plan_expected_time）​

def set_way_point_plan_expected_time(time: SupportsFloat) -> None

设置路点规划期望时间

参数

名称类型默认值描述
timeSupportsFloat需要传参-
note

用作时间最优轨迹生成算法的提示。

轨迹点（TrajectoryPoint）​

表示机器人轨迹中的路点，指定特定时间的关节状态。joint_command_vec 的顺序必须与 Trajectory.joint_names 或 Trajectory.joint_groups（按顺序展开）定义的关节顺序一致。顺序不匹配将导致未定义行为。

成员变量​
名称类型描述
joint_command_veclist[JointCommand]该路点所有关节的关节命令列表。顺序必须与 joint_names 或 joint_groups 展开顺序一致。
time_from_start_secondfloat起始时间偏移（秒）

扭曲速度（Twist）​

表示刚体的线速度和角速度组合，遵循ROS标准消息格式。

成员变量​
名称类型描述
angularVector3角速度向量
linearVector3线速度向量

三维向量（Vector3）​

表示三维矢量，用于力、扭矩、速度、加速度和其他矢量。

成员变量​
名称类型描述
xfloatX分量
yfloatY分量
zfloatZ分量

路点（Waypoint）​

多路点导航的目标路点定义。

路点可选参数（WaypointParams）​

用于调整单个路点到达精度和运动平滑度的可选参数。

成员变量​
名称类型描述
acceleration_scalefloat-
arrival_orientation_thresholdfloat-
arrival_position_threshold_xfloat-
arrival_position_threshold_yfloat-
jerk_scalefloat-
velocity_scalefloat-

全身控制异常（WBCException）​

将 MotionStatus 枚举值转换为字符串。

力与力矩（Wrench）​

力与力矩相关说明。

成员变量​
名称类型描述
forceVector3力向量
torqueVector3力矩向量

检查运动状态（check_motion_status）​

def check_motion_status(status: MotionStatus) -> str

检查当前运动状态，验证运动是否满足约束条件。

参数

名称类型默认值描述
statusMotionStatus需要传参运动状态

返回值

类型描述
strstr：运动状态的字符串表示。

创建 JointStates 实例（create_joint_state）​

def create_joint_state() -> JointStates

创建一个 JointStates 实例。

返回值

类型描述
JointStatesJointStates：新的关节状态对象。

创建参数（create_parameter）​

def create_parameter(
    direct_execute: bool = False,
    blocking: bool = False,
    timeout: SupportsFloat = 20.0,
    actuate: str = 'with_chain_only',
    tool_pose: bool = False,
    check_collision: bool = True,
    frame: str = 'base_link'
) -> Parameter

创建运动命令参数，设置执行方式、超时、碰撞检查等选项。

参数

名称类型默认值描述
direct_executeboolFalse是否立即执行规划出的轨迹。
blockingboolFalse是否同步等待完成。
timeoutSupportsFloat20.0规划或执行请求的最大等待时间（秒）。
actuatestr'with_chain_only'参与运动的运动链："with_chain_only"、"with_torso" 或 "with_leg"。
tool_poseboolFalse将笛卡尔目标解释为已连接工具的 TCP，而非法兰。
check_collisionboolTrue是否启用规划碰撞检测。
framestr'base_link'位姿目标使用的参考坐标系。

返回值

类型描述
ParameterParameter：新的 Parameter 实例。

创建 PoseState 实例（create_pose_state）​

def create_pose_state() -> PoseState

创建一个 PoseState 实例。

返回值

类型描述
PoseStatePoseState：新的位姿状态对象。