API 参考

机器人配置

MOZ1RobotConfig

用于设置机器人参数的主要配置类。

构造函数参数：

参数名	类型	默认值	描述
realsense_serials	str	"0000000000,0000000000,0000000000"	RealSense 相机序列号（逗号分隔）
camera_resolutions	str	"320*240,320*240,320*240"	相机分辨率,格式为"宽*高"
no_camera	bool	False	跳过相机初始化（用于测试）
structure	str	"wholebody"	机器人配置类型
robot_control_hz	int	120	控制循环频率（Hz）,与机器人控制系统中的设定保持一致
enable_soft_realtime	bool	False	启用软实时调度,需要先执行 scripts/setup_rtprio.sh
bind_cpu_idxs	Optional[Sequence[int]]	None	CPU绑定索引列表,如 [5] 表示绑定到第5个CPU核心,索引从0开始

支持的机器人结构：

• dualarm: 双臂配置（左臂 + 右臂）
• wholebody_without_base: 无移动底盘的全身配置（双臂 + 躯干）
• wholebody: 带移动底盘的全身配置（双臂 + 躯干 + 底盘）

配置示例：

from mozrobot import MOZ1RobotConfig

# 基础双臂配置
config = MOZ1RobotConfig(
    realsense_serials="123456789,987654321,555666777",
    camera_resolutions="640*480,640*480,640*480",
    structure="dualarm",
    robot_control_hz=120
)

# 无相机测试配置
config_no_cam = MOZ1RobotConfig(
    no_camera=True,
    structure="dualarm"
)

# 全身配置
config_wholebody = MOZ1RobotConfig(
    structure="wholebody",
    robot_control_hz=120
)

# 高性能实时配置
config_realtime = MOZ1RobotConfig(
    structure="dualarm",
    robot_control_hz=120,
    enable_soft_realtime=True,  # 启用软实时调度
    bind_cpu_idxs=[5]  # 绑定到CPU核心5
)

机器人控制

MOZ1Robot

提供连接、控制和数据采集功能的主要机器人控制类。

构造函数：

MOZ1Robot(config: MOZ1RobotConfig)

核心方法：

连接管理

connect() -> None

建立与机器人系统的连接。

• 异常: 连接失败时抛出 RuntimeError

disconnect() -> None

断开与机器人系统的连接。

is_robot_connected -> bool

检查机器人连接状态的属性。

• 返回值: 机器人已连接返回 True,否则返回 False
• 用法: 在发送指令前检查连接状态,确保机器人通信正常

机器人控制

enable_external_following_mode() -> None

启用外部跟随控制模式。

• 重要: 必须使用send_action前激活外部跟随模式
• 功能: 激活机器人外部控制接收器,使send_action发送的指令生效
• 异常: 机器人未连接时抛出 RobotDeviceNotConnectedError

send_action(action: Dict) -> Dict

向机器人发送控制命令。

• 参数:
  • action: 动作命令字典,数据单位为国际单位（弧度,米,秒）
• 返回值: 发送的动作命令确认
• 重要要求:
  1. 调用频率: send_action的调用必须保持稳定频率,与robot_control_hz初始化参数一致
  2. 轨迹连续性: 发送的轨迹必须满足连续性约束,避免加速度、加加速度出现大幅突变
  3. 控制模式独占: 每个执行结构（左臂/右臂/躯干）同一时间只能选择轴空间控制或笛卡尔空间控制其中一种模式
  4. 前置条件: 必须先调用enable_external_following_mode()方法
• 异常: 机器人未连接或发送失败时抛出 RuntimeError

reset_robot_positions(left_arm_joints: Optional[List] = None,
                     right_arm_joints: Optional[List] = None,
                     torso_joints: Optional[List] = None,
                     gripper_positions: Optional[List] = None) -> bool

异步复位机器人到指定位置。

• 参数:

  • left_arm_joints: 左臂关节目标位置（可选）

  • right_arm_joints: 右臂关节目标位置（可选）

  • torso_joints: 躯干关节目标位置（可选）

  • gripper_positions: 夹爪位置（可选）

    数据单位为国际单位（弧度,米）

• 返回值: 复位指令发送成功返回 True
• 重要: 此方法是异步的,调用后需要手动sleep等待机器人完成复位动作
• 建议: 复位后等待3-5秒确保机器人稳定到位,具体时间取决于MovaX中设置的机器人速度
• 异常: 机器人未连接时抛出 RobotDeviceNotConnectedError

状态监控

capture_observation() -> Dict

捕获当前机器人状态,包括图像和关节数据。

• 返回值: 包含观测数据的字典,数据单位为国际单位（弧度,米,秒）
• 相机更新频率: RealSense相机以30Hz频率更新图像数据
• 数据内容: 包含机器人关节状态、笛卡尔位置、夹爪状态和相机图像
• 旋转表示: 所有旋转数据使用旋转向量（rotation vector）表示法
• 底盘控制: 当机器人配置为wholebody时,底盘采用速度控制模式,返回当前速度状态 [vx, vy, wz]
• 异常: 机器人未连接或数据捕获失败时抛出 RuntimeError

更多方法

control_hz -> int

检查机器人的控制频率

• 返回值: 当前生效的机器人控制频率

机器人控制