快速开始

MozRobot SDK

MozRobot SDK 是一个用于控制 Moz 机器人系统的综合性 Python SDK。基于 ROS2 构建,它为Moz1机器人提供直观的机器人控制、数据采集的API。

主要特性

• 多配置支持: 双臂、全身（有/无底盘）
• 实时控制: 高频控制循环（最高 120Hz）实现精确操控
• 视觉集成: 原生 RealSense 相机支持,支持多相机配置
• ROS2 原生: 与 ROS2 Humble 生态系统无缝集成
• 安全优先: 内置安全检查和错误处理
• 易于集成: 简单的 Python API,便于快速原型开发和部署

系统要求

• 操作系统: Ubuntu 22.04 LTS (推荐)
• ROS 版本: ROS2 Humble
• Python 版本: 3.10 或更高版本,建议使用系统解释器
• 硬件要求:
  • RealSense 相机：USB 3.0 * 3
  • 与机器人控制系统连接：RJ45 * 1
• 系统资源: 推荐 8GB+ 内存

支持平台

• x86_64
• aarch64

网络配置

• 主机 IP: 必须在 172.16.0.x 子网中（例如：172.16.0.100）
• 机器人 IP: 172.16.0.20
• ROS_DOMAIN_ID: 33（需要与 MovaX 控制系统保持一致）

SDK 包下载

版本号	发布日期	成果物
0.1.0	20250925	mozrobot-0.1.0-x86_64 mozrobot-0.1.0-aarch64

步骤 1：系统依赖

ros-humble安装指南

# 安装 ROS2 Humble
sudo apt install software-properties-common
sudo add-apt-repository universe
sudo apt update && sudo apt install curl -y

sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

sudo apt update
# you can install ros-humble-desktop-full
sudo apt install -y ros-humble-ros-base python3-colcon-common-extensions ros-dev-tools

# 安装系统依赖
sudo apt install -y build-essential cmake git curl wget python3-pip python3-dev
sudo apt install -y libopencv-dev python3-opencv

步骤 2：robot_interface ROS包构建

robot_interface 是必需的ROS2接口包,包含机器人通信消息和服务定义。必须先构建此包才能正常使用SDK。

# 进入依赖包目录
cd /path/to/mozrobot-SDK/deps

# 创建ROS2工作空间并构建robot_interface包
mkdir -p ~/ros_ws/src
cp -r robot_interface ~/ros_ws/src/
cd ~/ros_ws

# 配置ROS2环境
source /opt/ros/humble/setup.bash
export ROS_DOMAIN_ID=33
# 构建包
colcon build --packages-select mc_core_interface

步骤 3：环境配置

# 配置 ROS2 环境
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
echo "export ROS_DOMAIN_ID=33" >> ~/.bashrc
echo "source ~/ros_ws/install/setup.bash" >> ~/.bashrc  # 添加robot_interface包环境
source ~/.bashrc

步骤 4：网络配置

编辑网络配置：

sudo nano /etc/netplan/01-netcfg.yaml

添加以下配置：

network:
  version: 2
  ethernets:
    eth0:  # 替换为实际网络接口名称
      addresses: [172.16.0.100/24]  # 选择 172.16.0.x 范围内的 IP
      gateway4: 172.16.0.1
      nameservers:
        addresses: [8.8.8.8, 8.8.4.4]

应用配置：

sudo netplan apply

步骤 5：SDK 安装

# 安装 Python 依赖
cd /path/to/mozrobot-sdk
pip3 install -r packages/requirements.txt

# 安装sdk
pip install packages/mozrobot-*.whl

步骤 6：验证安装

python3 -c "from mozrobot import MOZ1Robot, MOZ1RobotConfig; print('✅ MozRobot SDK 安装成功!')"

快速测试

# 设置环境
export ROS_DOMAIN_ID=33

# 运行示例
cd mozrobot
python3 example/example_usage.py

# 启用性能优化的示例
python3 example/example_usage.py --enable-soft-realtime --bind-cpu 5 --no-camera

性能优化配置（可选）

MozRobot SDK 支持实时性能优化,适用于对控制精度和延迟有严格要求的场景：

软实时调度

启用软实时调度可以提高机器人控制的实时性能,减少控制延迟和抖动。

# 执行设置脚本（需要管理员权限）
sudo bash scripts/setup_rtprio.sh
sudo reboot

CPU绑定

将机器人控制线程绑定到特定CPU核心,避免任务切换开销,提高控制稳定性。

建议配置：

• 避免使用核心0,通常被系统任务占用

重要注意事项：

• 这些功能是可选的,普通使用不需要配置
• 仅在需要最佳实时性能时启用
• 确保系统有足够的CPU资源用于绑定