openarm_HT Python SDK

English | 简体中文

openarm_HT 是面向双臂机器人的 Python 软件开发工具包。机器人左右臂各有 7 个机械臂关节和 1 个夹爪电机。本项目提供底层电机通信、MIT 控制、正/逆运动学、动力学补偿、轨迹规划、QP 逆运动学、轨迹录制/回放、键盘和 Quest VR 控制例程。

Caution

机械臂上电前请清空工作区域，确认急停和 Ctrl+C 可用。掉电时机械臂可能下坠，请提前支撑机械臂。首次运行任何动作例程时请使用低速并随时准备停机。

主要功能

左臂、右臂和双臂同步控制
位置、速度、力矩、位置-速度和 MIT 五参数控制
Pinocchio 正运动学、逆运动学和雅可比矩阵
重力、摩擦、科氏力、质量矩阵和完整动力学
五次/七次多项式插值和笛卡尔轨迹
带关节位置、速度和加速度约束的 QP 逆运动学
单臂/双臂轨迹录制、历史轨迹选择和 MIT 回放
键盘笛卡尔控制和 Quest VR DLS/QP 控制
YAML 关节限位、速度、加速度、力矩和 URDF 配置

坐标系

基座坐标系

夹爪末端（TCP）坐标系

下图展示的是夹爪末端坐标方向。TCP（Tool Center Point）是笛卡尔控制使用的夹爪末端参考坐标系，左右臂在 URDF 中分别为 l_hand_tcp_link 和 r_hand_tcp_link。

项目结构

openarm_HT/
├── motor_whl/                                      # 预编译底层电机 SDK
│   ├── hightorque_robot-1.2.0-cp39-cp39-linux_x86_64.whl
│   ├── hightorque_robot-1.2.0-cp310-cp310-linux_x86_64.whl
│   ├── hightorque_robot-1.2.0-cp311-cp311-linux_x86_64.whl
│   ├── hightorque_robot-1.2.0-cp312-cp312-linux_x86_64.whl
│   ├── hightorque_robot-1.0.0-cp39-cp39-linux_aarch64.whl
│   ├── hightorque_robot-1.0.0-cp310-cp310-linux_aarch64.whl
│   ├── hightorque_robot-1.0.0-cp311-cp311-linux_aarch64.whl
│   └── hightorque_robot-1.0.0-cp312-cp312-linux_aarch64.whl
│
├── Openarm-HT_description/                         # 双臂 URDF 模型
│   ├── urdf/
│   │   ├── Openarm-HT_description.urdf
│   │   └── Openarm-HT_description.csv
│   ├── meshes/                                   # 躯干、左右臂和夹爪 3D 模型
│   ├── config/                                   # RViz 和关节显示配置
│   └── launch/                                   # ROS/ROS 2 显示启动文件
│
├── images/
│   ├── Board.png                                 # 通信板接线图
│   ├── base_joint.png                            # 基座坐标系
│   └── tcp_frame.png                             # 夹爪末端 TCP 坐标系
│
├── robot_param/                                  # 机械臂高层配置
│   ├── Openarm_left.yaml                         # 左臂 7 自由度
│   ├── Openarm_right.yaml                        # 右臂 7 自由度
│   ├── Leader.yaml                               # 旧 6 自由度主臂
│   ├── Follower.yaml                             # 旧 6 自由度从臂
│   └── motor_param/
│       ├── 7dof_openarm_HT_params_left.yaml
│       ├── 7dof_openarm_HT_params_right.yaml
│       ├── 6dof_openarm_HT_params_leader.yaml
│       ├── 6dof_openarm_HT_params_follower.yaml
│       ├── motor_1.yaml
│       ├── motor_6.yaml
│       └── robot_config.yaml
│
├── scripts/                                      # Python 控制例程
│   ├── Lib/                                      # 高层封装库
│   │   ├── Openarm.py                           # Openarm 控制类
│   │   ├── qp_ik.py                             # OSQP 有界速度级 IK
│   │   ├── recorder.py                          # JSONL 轨迹录制/回放
│   │   └── __init__.py
│   │
│   ├── 0_robot_get_state.py                    # 单臂状态查看
│   ├── 0_dual_openarm_HT_get_state.py          # 双臂状态查看
│   ├── 0_robot_set_zero.py                     # 单臂设置零位
│   ├── 0_dual_robot_set_zero.py                # 双臂设置零位
│   │
│   ├── 1_Joint_PosVel_control.py               # 单臂位置速度控制
│   ├── 1_dual_Joint_PosVel_control.py          # 双臂位置速度控制
│   ├── 1_Joint_Vel_control.py                  # 单臂速度控制
│   ├── 1_dual_Joint_Vel_control.py             # 双臂速度控制
│   ├── 1_Joint_PD_control.py                   # 单臂 MIT/PD 控制
│   ├── 1_dual_Joint_PD_control.py              # 双臂 MIT/PD 控制
│   ├── 1_moveJ_control.py                      # 单臂 moveJ
│   ├── 1_dual_moveJ_control.py                 # 双臂 moveJ
│   ├── 1_forward_kinematics_test.py            # 单臂正运动学
│   ├── 1_dual_forward_kinematics_test.py       # 双臂正运动学
│   ├── 1_inverse_kinematics_test.py            # 单臂逆运动学
│   ├── 1_dual_inverse_kinematics_test.py       # 双臂逆运动学
│   │
│   ├── 2_gravity_compensation_control.py
│   ├── 2_dual_gravity_compensation_control.py
│   ├── 2_gravity_friction_compensation_control.py
│   ├── 2_dual_gravity_friction_compensation_control.py
│   ├── 2_Jointimpendence_control_with_gra_pd.py
│   ├── 2_dual_Jointimpendence_control_with_gra_pd.py
│   ├── 2_Jointimpendence_control_with_gra_fri_pd.py
│   ├── 2_dual_Jointimpendence_control_with_gra_fri_pd.py
│   ├── 2_inv_PosVel_control.py
│   ├── 2_dual_inv_PosVel_control.py
│   │
│   ├── 3_interpolation_control_zeroVel.py
│   ├── 3_interpolation_control_nozeroVel.py
│   ├── 3_sin_trajectory_control.py
│   ├── 3_dual_sin_trajectory_control.py
│   ├── 3_sin_trajectory_control_with_plot.py
│   ├── 3_gravity_compensation_with_fk.py
│   │
│   ├── 4_QP_inverse_kinematics_control.py       # 单臂 QP 奇异位形/头顶画圆
│   ├── 4_dual_QP_inverse_kinematics_control.py  # 双臂 QP 奇异位形/头顶画圆
│   ├── 5_teleop_control.py                     # 旧主从臂遥操
│   ├── 5_trajectory_record_replay.py          # 单/双臂轨迹录制回放
│   ├── 6_moveL_pos_control.py                  # 笛卡尔直线运动
│   ├── 6_moveL_rotate_control.py               # 笛卡尔旋转运动
│   │
│   ├── 7_keyboard_cartesian_pos_control.py
│   ├── 7_keyboard_cartesian_vel_control.py
│   ├── 7_keyboard_cartesian_vel_collision_control.py
│   ├── 7_keyboard_cartesian_impedance_control.py
│   ├── 7_keyboard_cartesian_pd_nullspace_lock_control.py
│   │
│   ├── 8_vr_single_cartesian_dls_control.py   # VR 单臂 DLS
│   ├── 8_vr_single_cartesian_qp_control.py    # VR 单臂 QP
│   ├── 8_vr_dual_cartesian_dls_control.py     # VR 双臂 DLS
│   ├── 8_vr_dual_cartesian_qp_control.py      # VR 双臂 QP
│   │
│   ├── motor_example/                          # 底层单电机例程
│   │   ├── 01_motor_get_status.py
│   │   ├── 02_position_control.py
│   │   ├── 03_velocity_control.py
│   │   ├── 04_torque_control.py
│   │   ├── 05_voltage_control.py
│   │   ├── 06_current_control.py
│   │   ├── 07_pos_vel_maxtorque_control.py
│   │   ├── 08_pos_vel_torque_kp_kd_control.py
│   │   ├── 09_set_zero.py
│   │   └── motor_control.py
│   └── openarm_trajectory_test1.jsonl          # 轨迹样例
│
├── src/bindings.cpp                                # pybind11 底层绑定
├── CMakeLists.txt
├── setup.py
├── pyproject.toml
├── requirements.txt
├── README.md                                       # 中文
└── README_EN.md                                    # English

系统要求

Ubuntu 20.04/22.04 64-bit
Python 3.9–3.12（推荐 Python 3.10）
openarm_HT 机械臂和 HighTorque 通信板
pin、SciPy、PyYAML 和 OSQP
键盘例程需要图形桌面/X 会话
VR 例程需要外部 Quest 手柄数据转发服务

安装

1. 创建 conda 环境

conda create -n panthera python=3.10
conda activate panthera

2. 安装底层电机 SDK

在项目根目录中根据 CPU 架构和 Python 版本选择 motor_whl/ 中的 wheel。例如 Ubuntu x86_64 + Python 3.10：

pip install motor_whl/hightorque_robot-1.2.0-cp310-cp310-linux_x86_64.whl

aarch64 + Python 3.10：

pip install motor_whl/hightorque_robot-1.0.0-cp310-cp310-linux_aarch64.whl

3. 安装高层库依赖

pip install -r requirements.txt

Important

动力学库的 pip 包名是 pin，Python 中的导入名是 pinocchio。

4. 验证环境

python -c "import hightorque_robot; print('motor SDK OK')"
python -c "import pinocchio; print('Pinocchio OK')"
python -c "import scipy, yaml, osqp; print('dependencies OK')"

连接与快速开始

通信板接线

连接后确认串口：

ls /dev/ttyACM*

临时授予当前设备访问权限：

sudo chmod a+rw /dev/ttyACM*

读取单臂状态

cd scripts
python 0_robot_get_state.py

Openarm() 默认加载 robot_param/Openarm_left.yaml。双臂例程会分别加载：

robot_param/Openarm_left.yaml
robot_param/Openarm_right.yaml

Python 接口示例

from Lib import Openarm

robot = Openarm()  # 默认左臂

position = robot.get_current_pos()
velocity = robot.get_current_vel()
torque = robot.get_current_torque()

target = [-0.2, -0.2, 0.2, -0.4, 0.5, 0.2, -0.1]
speed = [0.3] * robot.motor_count
robot.Joint_Pos_Vel(target, speed, robot.max_torque)

robot.gripper_open()
robot.set_stop()

例程索引

所有机械臂例程位于 scripts/。

前缀	内容	主要例程
`0_`	状态、置零	`0_robot_get_state.py`、`0_dual_openarm_HT_get_state.py`
`1_`	关节控制和 FK/IK	`1_Joint_PosVel_control.py`、`1_dual_moveJ_control.py`
`2_`	重力/摩擦补偿和阻抗	`2_gravity_compensation_control.py`、`2_dual_inv_PosVel_control.py`
`3_`	插值和正弦轨迹	`3_sin_trajectory_control.py`、`3_dual_sin_trajectory_control.py`
`4_`	QP 逆运动学	`4_QP_inverse_kinematics_control.py`、`4_dual_QP_inverse_kinematics_control.py`
`5_`	轨迹录制/回放和主从遥操	`5_trajectory_record_replay.py`、`5_teleop_control.py`
`6_`	笛卡尔 MoveL	`6_moveL_pos_control.py`、`6_moveL_rotate_control.py`
`7_`	键盘笛卡尔控制	`7_keyboard_cartesian_*_control.py`
`8_`	Quest VR 单/双臂 DLS/QP	`8_vr_*_control.py`

Note

5_teleop_control.py 面向旧 6 自由度 Leader/Follower 主从臂配置，不是当前 7 自由度左右臂的通用回放程序。

轨迹录制与回放

cd scripts
python 5_trajectory_record_replay.py

交互菜单支持：

左臂、右臂或双臂录制。
回放当前默认轨迹。
选择历史 JSONL 轨迹。
双臂共享时间轴并使用 MIT 同步回放。

也可使用命令行：

python 5_trajectory_record_replay.py record --arm dual
python 5_trajectory_record_replay.py replay trajectory_dual_YYYYMMDD_HHMMSS.jsonl
python 5_trajectory_record_replay.py list

Quest VR 控制

SDK 内包含 4 个机械臂控制程序：

8_vr_single_cartesian_dls_control.py
8_vr_single_cartesian_qp_control.py
8_vr_dual_cartesian_dls_control.py
8_vr_dual_cartesian_qp_control.py

Quest 位姿和按键数据由外部项目 Quest_controller_stream 发送；该数据转发工程不包含在本 SDK 中。默认 UDP 端口为 5005。

先启动外部转发服务，再在 SDK 终端运行所需的VR例程，例如：

cd scripts
python 8_vr_single_cartesian_qp_control.py

配置说明

关键参数位于 robot_param/Openarm_left.yaml 和 robot_param/Openarm_right.yaml：

joint_limits：关节位置边界
gripper_limits：夹爪边界
max_torque：最大力矩
velocity_limits：关节速度限制
acceleration_limits：关节加速度限制
urdf.end_effector_link：末端 TCP frame
moveit_cartesian：笛卡尔采样和跳变阈值

修改配置后应先运行状态/FK 例程，确认电机数、关节名、限位和 TCP frame 一致。

常见问题

找不到 `/dev/ttyACM*`

检查通信板供电、USB 连接和串口权限，然后重新执行 ls /dev/ttyACM*。

`pinocchio` 导入失败

确认已激活 panthera 环境并通过 pip install pin 安装，避免与 ROS 的其他 Python 版本混用。

键盘例程无法启动

pynput 需要可用的图形桌面/X 会话。请在机械人主机的桌面终端中运行，不要在无显示的 headless 会话中运行。

VR 例程收不到数据

确认 Quest 转发服务已启动，UDP IP/端口与控制脚本一致，且防火墙未阻止 UDP 5005。

开发提示

代码级控制接口位于 scripts/Lib/Openarm.py。
QP IK 实现位于 scripts/Lib/qp_ik.py。
轨迹 JSONL 工具位于 scripts/Lib/recorder.py。
不要绕过 YAML 关节限位和力矩限制。
结束程序时调用 set_stop()，并确认电机进入预期的刹车/阻尼状态。

License

项目打包元数据声明为 MIT License。发布时请在项目根目录中附带完整的 LICENSE 文件。

Navigation Menu

Uh oh!

Repository files navigation

openarm_HT Python SDK

主要功能

坐标系

基座坐标系

夹爪末端（TCP）坐标系

项目结构

系统要求

安装

1. 创建 conda 环境

2. 安装底层电机 SDK

3. 安装高层库依赖

4. 验证环境

连接与快速开始

通信板接线

读取单臂状态

Python 接口示例

例程索引

轨迹录制与回放

Quest VR 控制

配置说明

常见问题

找不到 `/dev/ttyACM*`

`pinocchio` 导入失败

键盘例程无法启动

VR 例程收不到数据

开发提示

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
Openarm-HT_description		Openarm-HT_description
images		images
motor_whl		motor_whl
robot_param		robot_param
scripts		scripts
src		src
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.py		setup.py

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

openarm_HT Python SDK

主要功能

坐标系

基座坐标系

夹爪末端（TCP）坐标系

项目结构

系统要求

安装

1. 创建 conda 环境

2. 安装底层电机 SDK

3. 安装高层库依赖

4. 验证环境

连接与快速开始

通信板接线

读取单臂状态

Python 接口示例

例程索引

轨迹录制与回放

Quest VR 控制

配置说明

常见问题

找不到 /dev/ttyACM*

pinocchio 导入失败

键盘例程无法启动

VR 例程收不到数据

开发提示

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

找不到 `/dev/ttyACM*`

`pinocchio` 导入失败