开臂 101

软件设置

SDK安装、SocketCAN驱动配置、ROS2集成、乐机器人设置、Python API参考。从全新安装的 Ubuntu 到运行的手臂，一切应有尽有。

跳转到一个部分：

› SDK安装 › CAN 驱动程序设置 › ROS2 集成 › 乐机器人集成 › Python API > 模拟 › 故障排除

第 1 步 — SDK 安装

SDK安装

OpenArm SDK 分发为 roboticscenter Python 包。它包括 openarm_can （低级 CAN 接口库）和所有支持实用程序。

创建虚拟环境（推荐）

python3 -m venv ~/.venvs/openarm
source ~/.venvs/openarm/bin/activate

安装SDK

pip install roboticscenter

验证安装

python3 -c "import openarm_can; print(openarm_can.__version__)"

您应该看到版本字符串。如果您看到导入错误，请参阅故障排除部分.

从源安装（可选）

git clone https://github.com/reazon-research/openarm.git
cd openarm
pip install -e .

📄 SDK 快速入门（维基） 📄 完整 API 参考 (wiki)

第 2 步 — CAN 驱动程序设置

SocketCAN 驱动程序设置

OpenArm 使用 SocketCAN（Linux 内核子系统）通过 CAN 总线进行通信。驱动程序已经在内核中；您只需要加载模块并打开界面即可。

加载内核模块

sudo modprobe can
sudo modprobe can_raw
sudo modprobe slcan   # for USB-serial CAN adapters (CANable)

调出CAN接口

对于随附的 CANable 2.0 USB 适配器：

# Find the USB serial device (usually /dev/ttyACM0 or /dev/ttyUSB0)
ls /dev/ttyACM*

# Bring up CAN interface at 1 Mbps
sudo slcand -o -c -s8 /dev/ttyACM0 can0
sudo ip link set up can0

验证接口是否已启动

ip link show can0
# Expected output: can0: <NOARP,UP,LOWER_UP> mtu 16 ...

使其在重新启动后保持不变

创建一个systemd服务或添加到 /etc/rc.local。请参阅 SocketCAN 设置指南获取完整的 systemd 服务模板。

测试CAN通讯

# Install can-utils
sudo apt install can-utils -y

# Listen for CAN packets
candump can0

# In another terminal, power on the arm and look for motor heartbeats

第 3 步 — ROS2 集成

ROS2集成

OpenArm 附带 openarm_ros2，一个完整的基于 ros2_control 的包。它支持假硬件模式，无需物理手臂即可进行测试。

安装 ROS2 Humble (Ubuntu 22.04)

sudo apt update && sudo apt install software-properties-common curl -y
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | \
  sudo apt-key add -
sudo sh -c 'echo "deb http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" \
  > /etc/apt/sources.list.d/ros2.list'
sudo apt update
sudo apt install ros-humble-desktop ros-humble-ros2-control \
  ros-humble-ros2-controllers ros-humble-joint-state-publisher-gui -y

克隆并构建 openarm_ros2

mkdir -p ~/openarm_ws/src && cd ~/openarm_ws/src
git clone https://github.com/reazon-research/openarm_ros2.git
cd ~/openarm_ws
source /opt/ros/humble/setup.bash
colcon build --symlink-install

以假硬件模式启动（无需手臂）

source ~/openarm_ws/install/setup.bash
ros2 launch openarm_ros2 openarm.launch.py use_fake_hardware:=true

使用真实硬件启动

ros2 launch openarm_ros2 openarm.launch.py \
  use_fake_hardware:=false \
  can_interface:=can0

发送测试运动命令

ros2 topic pub /joint_trajectory_controller/joint_trajectory \
  trajectory_msgs/msg/JointTrajectory \
  '{joint_names: ["joint1"], points: [{positions: [0.5], time_from_start: {sec: 2}}]}'

请参阅 ROS2控制指南用于完整的控制器配置、启动文件选项和轨迹调整。

第 4 步 — 乐机器人集成

乐机器人集成

LeRobot（由 HuggingFace 开发）是 OpenArm 的主要数据收集和策略培训框架。它处理剧集记录、数据集格式化，并直接与 ACT 和 Diffusion Policy 连接。

安装乐机器人

pip install lerobot

配置您的机器人

为 OpenArm 创建机器人配置文件。 LeRobot使用基于YAML的机器人配置：

# ~/.lerobot/robots/openarm.yaml
robot_type: openarm
can_interface: can0
num_joints: 8
camera_names:
  - wrist_cam
  - overhead_cam

记录数据集

python -m lerobot.scripts.control_robot \
  --robot.type=openarm \
  --control.type=record \
  --control.fps=30 \
  --control.repo_id=your-username/openarm-pick-place \
  --control.num_episodes=50 \
  --control.single_task="Pick up the red cube"

上传至 HuggingFace Hub

huggingface-cli login
python -m lerobot.scripts.push_dataset_to_hub \
  --repo_id=your-username/openarm-pick-place

请参阅数据收集页面完整的剧集录制工作流程和质量检查。

第 5 步——Python API

Python API 快速入门

这 openarm_can 库通过 SocketCAN 提供对所有 8 个关节的直接低级访问。基本控制不需要 ROS2。

基本联合控制

from openarm_can import OpenArm

# Connect to the arm
arm = OpenArm(can_interface="can0")
arm.connect()

# Enable all joints
arm.enable_all()

# Move joint 1 to 45 degrees (in radians: ~0.785)
arm.set_position(joint_id=1, position=0.785, kp=50, kd=1)

# Read current state
state = arm.get_state()
print(f"Joint positions: {state.positions}")
print(f"Joint velocities: {state.velocities}")
print(f"Joint torques: {state.torques}")

# Zero torque (safe shutdown)
arm.disable_all()
arm.disconnect()

我的控制模式

from openarm_can import OpenArm, MITCommand

arm = OpenArm(can_interface="can0")
arm.connect()
arm.enable_all()

# Send a MIT control command: position + velocity + torque feedforward
cmd = MITCommand(
    joint_id=1,
    position=0.5,      # rad
    velocity=0.0,      # rad/s
    kp=80.0,           # position gain
    kd=2.0,            # velocity gain
    torque_ff=0.0      # feedforward torque (Nm)
)
arm.send_mit_command(cmd)

arm.disable_all()
arm.disconnect()

循环读取传感器数据

import time
from openarm_can import OpenArm

arm = OpenArm(can_interface="can0", control_rate_hz=500)
arm.connect()
arm.enable_all()

for _ in range(1000):  # 2 seconds at 500 Hz
    state = arm.get_state()
    print(state.positions)
    time.sleep(1 / 500)

arm.disable_all()
arm.disconnect()

📄 SDK 快速入门 📄 完整 API 参考

可选 — 模拟

模拟支持

OpenArm 支持三种仿真环境。所有这些都与真实硬件共享相同的状态定义和动作空间，从而实现模拟到真实的传输。

ROS2 假硬件（内置 - 无需安装）

无需物理手臂即可测试软件的最快方法。状态反映了真实的硬件接口。

ros2 launch openarm_ros2 openarm.launch.py use_fake_hardware:=true

穆乔科

校准的物理模型。非常适合政策培训和模拟到现实的转换。

pip install mujoco
# Clone the OpenArm MuJoCo model
git clone https://github.com/reazon-research/openarm_mujoco.git
# Run the default sim
python openarm_mujoco/examples/run_sim.py

NVIDIA 艾萨克·辛

用于大规模合成数据生成的 GPU 加速模拟。需要 NVIDIA GPU 和 Isaac Sim 许可证。看以数据为中心的平台文章了解 Isaac Sim 配置详细信息。

模拟与真实的对齐 — OpenArm 的仿真模型反映了真实的硬件运动学、动力学和驱动限制。这意味着您可以在模拟中训练策略，并以最少的调整将其直接部署到真实硬件上。

故障排除

最常见的 3 个问题

错误1 未找到 CAN 接口： no such device can0

SocketCAN接口未启动。这几乎总是因为 USB CAN 适配器未连接，或者内核模块未加载。

使固定：

# 1. Check if the USB adapter is detected
lsusb | grep -i "can\|serial"

# 2. Load the modules
sudo modprobe can && sudo modprobe can_raw && sudo modprobe slcan

# 3. Bring up the interface
sudo slcand -o -c -s8 /dev/ttyACM0 can0
sudo ip link set up can0

# 4. Verify
ip link show can0

错误2 之后关节没有反应 arm.enable_all()

电机未接收命令。最常见的原因是 CAN ID 不正确、CAN 总线错误帧或电源不足。

使固定：

# 1. Check for CAN error frames
candump can0 | grep -i "error"

# 2. Check power supply — arm requires 24V @ 150W minimum
# Voltage sag under load causes motor timeouts

# 3. Verify motor CAN IDs match your config
python3 -c "from openarm_can import OpenArm; a=OpenArm('can0'); a.scan_motors()"

# 4. Reset the arm (power cycle) and retry

错误3 ROS2启动失败： controller_manager not found

ros2_control 软件包未安装或工作空间来源不正确。

使固定：

# 1. Install missing packages
sudo apt install ros-humble-ros2-control \
  ros-humble-ros2-controllers \
  ros-humble-joint-state-publisher-gui -y

# 2. Rebuild the workspace
cd ~/openarm_ws && colcon build --symlink-install

# 3. Source both ROS2 and your workspace (order matters)
source /opt/ros/humble/setup.bash
source ~/openarm_ws/install/setup.bash

# 4. Retry launch
ros2 launch openarm_ros2 openarm.launch.py use_fake_hardware:=true

还卡住了吗？询问 OpenArm 论坛或检查现有的 GitHub 问题.

以前的 ← 设置指南

下一个规格 →

软件工作正常吗？开始收集数据。

一旦手臂开始移动，下一步就是远程操作和数据集记录。

数据收集指南 → 完整 API 参考在论坛上获取帮助

软件设置

SDK安装

创建虚拟环境（推荐）

安装SDK

验证安装

从源安装（可选）

SocketCAN 驱动程序设置

加载内核模块

调出CAN接口

验证接口是否已启动

使其在重新启动后保持不变

测试CAN通讯

ROS2集成

安装 ROS2 Humble (Ubuntu 22.04)

克隆并构建 openarm_ros2

以假硬件模式启动（无需手臂）

使用真实硬件启动

发送测试运动命令

乐机器人集成

安装乐机器人

配置您的机器人

记录数据集

上传至 HuggingFace Hub

Python API 快速入门

基本联合控制

我的控制模式

循环读取传感器数据

模拟支持

ROS2 假硬件（内置 - 无需安装）

穆乔科

NVIDIA 艾萨克·辛

最常见的 3 个问题

软件工作正常吗？ 开始收集数据。

软件工作正常吗？开始收集数据。