A7 机械臂
A7 是一款自研 7 自由度机械臂。
快速开始
from linkerbot import A7
with A7(
side="left",
interface_name="can0",
) as arm:
arm.enable() # 使能机械臂所有 7 个关节电机
arm.home() # 将机械臂移动到零位
arm.disable() # 失能机械臂所有 7 个关节电机
构造参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
side | "left" | "right" | 必填 | 左臂或右臂 |
interface_name | str | 必填 | CAN 接口名，如 "can0" |
interface_type | str | "socketcan" | CAN 接口类型 |
tcp_offset | list[float] | [0.0, 0.0, 0.0] | TCP 偏移量 |
world_frame | "urdf" | "maestro" | "urdf" | 世界坐标系约定 |
构造时会自动检查所有 7 个电机是否在线。
前置依赖： A7 依赖 Pinocchio 进行运动学计算，需要安装 kinetix 可选依赖：
pip install linkerbot-py[kinetix]
Windows 用户：Pinocchio 不支持 pip 安装，请使用
conda install pinocchio -c conda-forge。
异常：
ImportError: 未安装kinetix可选依赖（Pinocchio）ValueError:side或world_frame参数非法StateError: 电机未响应 CAN 总线 / 初始数据读取失败
URDF 文件路径：
src/linkerbot/arm/kinetix/urdf/a7__left.urdf和a7__right.urdf
坐标系说明
A7 支持两种世界坐标系，通过 world_frame 参数选择。
URDF 坐标系（默认）
URDF 模型文件的坐标系，原点位于机械臂基座（Base_Link）中心，如图所示：
- X 轴：机器人背后指向机器人前方为 X 轴正方向
- Y 轴：机器人视角左手边（面对机器人站立右手边）为 Y 轴正方向
- Z 轴：由右手定则确定上方为 Z 轴正方向
- Rx, Ry, Rz：表示按照 Z,Y,X 轴顺序，逆时针为正进行旋转
Maestro 坐标系
Maestro 坐标系，相对 URDF 坐标系进行了两步变换，如图所示：
- 原点平移：将世界坐标原点从基座中心平移到 Joint 2（肩部第二关节）中心处
- Z 轴旋转 90°：在新原点将 URDF 坐标轴绕 Z 轴逆时针旋转 +90°
变换后：
- X 轴：机器人视角右手边（面对机器人站立左手边）为 X 轴正方向
- Y 轴：机器人背后指向机器人前方，为 Y 轴正方向
- Z 轴：由右手定则确定上方为 Z 轴正方向
注意：这两种坐标的定义方式主要影响
move_p和move_l涉及到Pose的部分，不影响move_j控制
关节定义
零位定义
所有关节角度为 [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0] 时，机械臂应当处于“自然下垂“姿态（关节相互垂直）；调用 home() 可回到零位，如下图所示：
角度正方向定义
角度正方向遵从右手定则：以右手拇指指向旋转轴正方向，四指弯曲方向为正角度增大方向。
- 轴为
0 1 0（Y 轴正方向）：角度增大时，从正 Y 轴看为逆时针旋转 - 轴为
1 0 0（X 轴正方向）：角度增大时，从正 X 轴看为逆时针旋转 - 轴为
0 0 -1（Z 轴负方向）：角度增大时，从上方看为顺时针旋转 - 轴为
0 -1 0（Y 轴负方向）：角度增大时，从正 Y 轴看为顺时针旋转
A7 左臂关节一览（URDF 坐标系）
| 索引 | 关节名称 | 物理含义 | 旋转轴（URDF） | 角度范围（rad） |
|---|---|---|---|---|
| 0 | Left_Shoulder_Pitch_Joint | 肩部俯仰 | Y 轴正方向（0 1 0） | [-2.97, 1.05] |
| 1 | Left_Shoulder_Roll_Joint | 肩部横滚 | X 轴正方向（1 0 0） | [-0.35, 3.49] |
| 2 | Left_Shoulder_Yaw_Joint | 肩部偏转（上臂扭转） | Z 轴负方向（0 0 -1） | [-2.79, 2.79] |
| 3 | Left_Elbow_Pitch_Joint | 肘部俯仰 | Y 轴负方向（0 -1 0） | [-0.21, 2.355] |
| 4 | Left_Wrist_Yaw_Joint | 腕部偏转（前臂扭转） | Z 轴负方向（0 0 -1） | [-2.79, 2.79] |
| 5 | Left_Wrist_Pitch_Joint | 腕部俯仰 | Y 轴负方向（0 -1 0） | [-1.57, 1.57] |
| 6 | Left_Wrist_Roll_Joint | 腕部横滚 | X 轴正方向（1 0 0） | [-1.57, 1.57] |
A7 右臂关节一览（URDF 坐标系）
| 索引 | 关节名称 | 物理含义 | 旋转轴（URDF） | 角度范围（rad） |
|---|---|---|---|---|
| 0 | Right_Shoulder_Pitch_Joint | 肩部俯仰 | Y 轴负方向（0 -1 0） | [-1.05, 2.97] |
| 1 | Right_Shoulder_Roll_Joint | 肩部横滚 | X 轴正方向（1 0 0） | [-3.49, 0.35] |
| 2 | Right_Shoulder_Yaw_Joint | 肩部偏转（上臂扭转） | Z 轴负方向（0 0 -1） | [-2.79, 2.79] |
| 3 | Right_Elbow_Pitch_Joint | 肘部俯仰 | Y 轴负方向（0 -1 0） | [-0.21, 2.355] |
| 4 | Right_Wrist_Yaw_Joint | 腕部偏转（前臂扭转） | Z 轴负方向（0 0 -1） | [-2.79, 2.79] |
| 5 | Right_Wrist_Pitch_Joint | 腕部俯仰 | Y 轴正方向（0 1 0） | [-1.57, 1.57] |
| 6 | Right_Wrist_Roll_Joint | 腕部横滚 | X 轴正方向（1 0 0） | [-1.57, 1.57] |
Pose（TCP 位姿）表示
Pose 表示 TCP（Tool Center Point，工具中心点）位姿，是一个 Pydantic 模型，包含 6 个字段：
from linkerbot import Pose
pose = Pose(x=0.3, y=0.1, z=0.5, rx=0.0, ry=0.5, rz=0.0)
| 字段 | 含义 | 单位 |
|---|---|---|
x, y, z | 空间坐标位置 | 米（m） |
rx | 绕 X 轴旋转（Roll），范围 [-π, π] | 弧度（rad） |
ry | 绕 Y 轴旋转（Pitch），范围 [-π/2, π/2] | 弧度（rad） |
rz | 绕 Z 轴旋转（Yaw），范围 [-π, π] | 弧度（rad） |
- 姿态使用外旋 ZYX 欧拉角表示：先绕世界坐标轴的 Z 轴旋转 rz，再绕世界坐标轴的 Y 轴旋转 ry，最后绕世界坐标轴的 X 轴旋转 rx。
生命周期管理
API 参考
| 方法 | 说明 |
|---|---|
enable() | 使能所有 7 个关节电机，会导致短暂失能。 |
disable() | 失能所有 7 个关节电机。 |
emergency_stop() | 紧急停止机械臂，使机械臂锁定在当前位姿。 |
calibrate_zero() | 将当前位置设为零位。需要机械臂处于失能状态。 |
reset_error() | 重置所有关节的错误状态。 |
close() | 关闭连接：停止轮询、等待运动完成后停止 CAN 调度器。使用 with 语句时会自动调用。 |
save_params() | 将当前 PID 等参数保存到电机闪存，断电后仍生效。 |
注意事项
- 调用
arm.enable()使能时会导致机械臂短暂失能。 - 设置零位需要机械臂处于失能状态。
控制模式
当前仅支持 PP（Profile Position）模式，调用 enable() 时会自动设置。
ControlMode 枚举可从 linkerbot 导入：
from linkerbot import ControlMode
CAN 总线
interface_name 指定 CAN 接口名称（如 "can0"），interface_type 指定接口类型（默认 "socketcan"）。
更多信息（包括 Windows 用法）请参阅 CAN 总线配置。
功能模块
| 模块 | 文档 |
|---|---|
| 运动控制（move_j/move_p/move_l） | motion.md |
| 运动学（FK/IK/关节限位） | kinematics.md |
| 状态读取（角度/速度/扭矩/温度） | state.md |
| 参数配置（速度/加速度/PID） | config.md |