跳到主要内容

启动SDK

A1Z 六轴机械臂的 Python 控制 SDK，提供 CAN 总线电机驱动、基于 Pinocchio 的重力补偿、正/逆运动学，以及零力示教和位置保持等功能。

SDK代码架构​

    a1z/
    ├── pyproject.toml                 # 构建配置 (flit)
    ├── setup.py                       # setuptools 后备
    ├── README.md
    ├── a1z/                       # SDK 主包
    │   ├── dynamics/
    │   │   └── gravity_model.py       # Pinocchio RNEA 重力补偿
    │   ├── motor_drivers/
    │   │   ├── can_interface.py       # CAN 总线封装
    │   │   ├── motor_a_driver.py      # MotorA 驱动 (MIT 混控)
    │   │   ├── motor_b_driver.py      # MotorB 驱动 + MixedMotorChain
    │   │   └── utils.py               # 数据结构, float↔uint 转换
    │   ├── robots/
    │   │   ├── robot.py               # Robot Protocol (抽象接口)
    │   │   ├── arm_robot.py           # ArmRobot 实现 (控制回路+重力补偿)
    │   │   ├── get_robot.py           # 工厂函数 get_a1z_robot()
    │   │   └── kinematics.py          # FK/IK (Pinocchio)
    │   ├── robot_models/
    │   │   └── a1z/               # URDF 模型文件
    │   └── utils/
    │       └── utils.py               # RateRecorder, 日志工具
    ├── examples/
    │   ├── gravity_comp.py            # 重力补偿示例
    │   └── position_hold.py           # 位置保持示例
    └── tools/
        ├── motor_diag.py              # 电机通信诊断与故障排查
        └── set_zero.py                # 电机零点标定
                    Robot Protocol (robot.py)
                           │
                      ArmRobot (arm_robot.py)
                     ╱          │           ╲
          GravityModel    MixedMotorChain    Kinematics
       (gravity_model.py)  (motor_b_driver.py)   (kinematics.py)
              │            ╱          ╲           │
          Pinocchio     MotorA      MotorB    Pinocchio
           (RNEA)    (motor_a_driver) (motor_b_driver)  (FK/IK)
                          ╲          ╱
                        python-can (SocketCAN)

SDK依赖​

  • Python版本： 支持Python 3.10版本及更高版本
  • 操作系统与通信接口： 需要使用Linux系统（例如 Ubuntu），并且电脑具备CAN总线硬件接口（一种用于连接机器人的控制总线）。

    SDK通过Linux下的SocketCAN功能与机器人通信（只要您的Linux系统正确配置了CAN接口即可，无需额外安装驱动。）

  • URDF模型文件： SDK安装包内已包含机器人模型文件（URDF格式），无需手动下载。默认使用的模型文件是A1Z_Flange.urdf，路径在a1z/robot_models/a1z/。

安装SDK​

cd /path/to/a1z

# 开发模式安装（推荐）
pip install -e .

# 或直接安装
pip install .

依赖会自动安装：numpy、python-can>=4.0以及pin（Pinocchio）。

配置CAN总线（SocketCAN 模式）​

注意：检查can盒电阻是否正确安装！

使用 HHS USB-CANFD 适配器（VID/PID a8fa:8598）：

# 1. 加载驱动
sudo modprobe gs_usb

# 2. 将 HHS 适配器绑定到 gs_usb（已绑定时忽略报错）
sudo sh -c 'echo "a8fa 8598" > /sys/bus/usb/drivers/gs_usb/new_id' 2>/dev/null || true

# 3. 确认接口出现（单适配器通常为 can0）
ip link show type can

# 4. 配置并启动（1 Mbps）
sudo ip link set can0 type can bitrate 1000000
sudo ip link set can0 up

CAN线连接方式： a1z_can盒连接A1Z本体与CAN盒连接示意图

按照以下步骤连接相关线束：

  1. 通信部分：机械臂自带线接至转接盒，CAN盒自带线接至转接盒，USB线连接CAN盒与上位机。
  2. 供电部分：电源适配器自带线接至转接盒，带开关的AC线连接电源适配器与电源。

为将CAN匹配电阻接入CAN总线，已原装图示⑤⑥引脚的120Ω电阻短接线。

注意：如拆掉原装短接线，为保证CAN通信稳定，请您在总线最远两端各并联1个120Ω匹配电阻。

使用example运行脚本​

# 零力漂浮（默认 URDF A1Z_Flange.urdf，末端无负载）

# 从小补偿因子开始（推荐首次调试方式）
python examples/gravity_comp.py --gravity_factor 0.3

# 确认补偿方向正确后提升到全补偿
python examples/gravity_comp.py --gravity_factor 1.0

# 位置保持模式
python examples/gravity_comp.py --mode hold

# 位置保持 + 移动到目标
python examples/position_hold.py --q_target_deg 0,30,-20,-15,0,0 --speed 0.5