Version: 6.1.0 (Latest)

灵动示教臂Python SDK

1. 介绍

Alicia-D SDK 是一套用于控制 灵动 Alicia-D 系列六轴机械臂（含夹爪） 的 Python 开发工具包。本文档主要面向示教臂（Leader Arm）的使用场景。该 SDK 基于玄雅自研的RoboCore 机器人核心库构建，支持通过串口通信实现对示教臂姿态与运行状态等关键数据的实时读取。

1.1 主要特性

核心能力

关节控制：支持设置与读取六个关节的角度，提供平滑插值执行。
末端轨迹：支持笛卡尔空间末端姿态轨迹规划。
夹爪控制：支持精确角度控制或一键开关。
力矩控制：开启或关闭关节电机扭矩，实现自由拖动（示教）。
零点设置：将当前位置设置为新的零点。
状态读取：实时获取关节角、夹爪角与末端姿态。
自动串口连接：自动搜索串口或手动指定。
教学模式：拖动记录姿态点并执行轨迹。
日志系统：支持日志级别过滤，可控制控制台输出详细程度。

2. 安装与配置

2.1 环境要求

Python 3.10 及以上版本
支持串口的计算机（USB 转串口芯片已集成在机械臂）

2.2 安装步骤

获取代码和相应examples

git clone https://github.com/Synria-Robotics/Alicia-D-SDK.git -b v6.1.0
cd Alicia-D-SDK

# 2. 创建 Python 环境（推荐使用 Conda）
conda create -n alicia python=3.10
conda activate alicia

方法一：从源码安装（开发模式）

如果您需要修改源码或参与开发：

cd Alicia-D-SDK
pip install -e .

方法二：从 PyPI 安装

pip install alicia_d_sdk

2.3 快速开始

基本使用示例：

from alicia_d_sdk import create_robot

# 创建机器人实例（自动搜索串口并连接，auto_connect=True 为默认值）
robot = create_robot()

# 检查连接状态
if robot.is_connected():
    print("连接成功！")
    
    # 打印当前状态
    robot.print_state()
    
    # 断开连接
    robot.disconnect()
else:
    print("连接失败，请检查串口")

注意： create_robot() 默认会自动连接（auto_connect=True）。如果不想自动连接，可以设置 auto_connect=False：

# 手动控制连接
robot = create_robot(auto_connect=False)
if robot.connect():
    # 使用机器人
    robot.print_state()
    robot.disconnect()

手动指定串口：

# Linux
robot = create_robot(port="/dev/ttyACM0")

# Windows
robot = create_robot(port="COM3")

2.4 设置串口权限

在Linux系统上，您需要为USB串口设备配置访问权限（windows 和MacOS用户可略过该步骤）。

# 方法1：将用户添加到dialout组（推荐，永久有效）
sudo usermod -a -G dialout $USER
# 注意：需要注销并重新登录以使组权限生效

# 方法2：临时设置串口权限
sudo chmod 666 /dev/ttyACM*

# 方法3：创建udev规则（永久有效）
echo 'KERNEL=="ttyUSB*", MODE="0666"' | sudo tee /etc/udev/rules.d/99-serial.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

2.5 硬件连接与验证

将机械臂通过USB连接至计算机。
检查串口是否被系统识别（不同平台有时会将设备识别为 COM* 或 ttyACM*）：

Linux:
```
ls -l  /dev/ttyACM*
```
MacOS:
```
ls /dev/cu.*
```
Windows:

运行版本读取示例以验证连接：
```
cd examples
python3 00_demo_read_version.py
```
如果连接成功，终端将显示机械臂的固件版本等信息。

2.6 故障排除

无法连接到机械臂 / 未找到可用串口？

检查硬件：确保USB线已牢固连接且机械臂已上电。
检查权限：确认您的用户有权限访问串口设备。
手动指定端口：如果SDK无法自动找到端口，您可以在启动程序时手动指定：
```
python3 00_demo_read_version.py --port /dev/ttyACM0
```

找不到串口/连接失败

检查 USB 线与电源

Linux 用户需确保在 dialout 用户组中：

sudo usermod -a -G dialout $USER
# 然后重新登录

运行 00_demo_read_version.py 检测固件版本

权限错误 (Permission denied)

可尝试以 sudo 运行或检查用户串口权限
Linux: 确保用户在 dialout 组中
检查串口是否被其他程序占用

固件版本检测失败

多次运行 00_demo_read_version.py
检查串口连接是否稳定

2.7 依赖包说明

主要依赖：

pyserial: 串口通信
numpy: 数值计算
pycrc: CRC校验
robocore: 运动学和轨迹规划（自动安装）

3. 示例代码说明

examples/ 目录包含了多个演示脚本，用于展示如何使用 Alicia-D SDK 与示教臂进行交互。以下示例中，部分功能仅适用于操作臂，已在说明中标注。所有脚本都支持 --port 和 --baudrate 参数。

3.1 文件结构

示教臂用户提示

在示教臂场景下，一般只需关注 00 ~ 03 号脚本（版本读取、扭矩控制、归零校准、状态读取）。其余示例主要面向操作臂的运动控制与轨迹规划。

examples/
├── 00_demo_read_version.py          # 读取版本号              ✅ 示教臂常用
├── 01_torque_switch.py              # 扭矩控制                ✅ 示教臂常用
├── 02_demo_zero_calibration.py      # 归零校准                ✅ 示教臂常用
├── 03_demo_read_state.py            # 读取状态                ✅ 示教臂常用
├── 04_demo_move_gripper.py          # 夹爪控制（仅适用于操作臂）
├── 05_demo_move_joint.py            # 关节空间运动（仅适用于操作臂）
├── 06_demo_forward_kinematics.py    # 正向运动学
├── 07_demo_inverse_kinematics.py    # 逆向运动学（仅适用于操作臂）
├── 08_demo_drag_teaching.py         # 拖动示教（仅适用于操作臂）
├── 09_demo_joint_traj.py            # 关节空间轨迹规划（仅适用于操作臂）
├── 10_demo_cartesian_traj.py        # 笛卡尔空间轨迹规划（仅适用于操作臂）
├── 11_benchmark_read_joints.py      # 关节读取性能测试
└── 12_utmostFPS.py                  # 最大帧率测试

3.2 主要参数说明

大多数示例脚本共享一套通用的命令行参数，方便您进行配置和调试。

参数	数据类型	默认值	描述
`--port`	`str`	`/dev/ttyACM0`	指定机械臂连接的串口号，如 `/dev/ttyUSB0`。若系统识别为调制解调器类设备，也可能显示为 `/dev/ttyACM0`。
`--gripper_type`	`str`	`50mm`	夹爪型号。

附加参数

部分示例脚本还包含特定功能的参数：

--format: 角度显示格式，可选 rad（弧度）或 deg（角度），默认为 deg
--single: 单次打印状态（仅适用于状态读取脚本）
--mode: 拖动示教模式，可选 manual、auto 或 replay_only
--save-motion: 动作名称（用于拖动示教功能）
--list-motions: 列出所有可用动作（拖动示教功能）
--speed_deg_s: 关节运动速度（度/秒），默认 10，范围 5-400
--execute: 执行移动到目标位置（逆运动学示例）

3.3 基础功能

`00_demo_read_version.py`

读取机械臂固件版本号

运行此脚本检测固件版本

使用方式：

python 00_demo_read_version.py

`01_torque_switch.py`

切换机械臂所有关节的力矩状态（上电/掉电）

参数说明：

--port: 串口端口（可选）

功能说明：

先关力矩后开力矩
关闭扭矩后机械臂可以手动拖动
示教完成后重新开启扭矩

注意事项：

关闭扭矩前请手动托住机械臂以免其突然掉落
示教完成后务必重新开启扭矩

使用方式：

python 01_torque_switch.py

注意： 示教臂（leader）通常不需要扭矩控制功能，此示例主要用于操作臂（follower）。

`02_demo_zero_calibration.py`

将机械臂当前位置设置为新的零点

此操作不可逆，请谨慎使用。

参数说明：

--port: 串口端口（可选）

适用场景：

机械臂首次使用或长时间未使用后
关节角度出现偏差时
需要重新建立零点参考时

使用方式：

python 02_demo_zero_calibration.py

`03_demo_read_state.py`

持续读取并打印机械臂的关节角度、末端姿态和夹爪状态

支持单次或持续打印模式。

参数说明：

--port: 串口端口（可选）
--gripper_type: 夹爪型号，默认 50mm
--format: 角度显示格式，可选 rad（弧度）或 deg（角度），默认 deg
--single: 单次打印状态，默认持续打印

使用场景：

调试和故障排查
实时监控机械臂状态
验证控制指令执行效果

使用方式：

# 持续打印状态（按 Ctrl+C 停止）
python 03_demo_read_state.py  --gripper_type 50mm

# 单次打印状态
python 03_demo_read_state.py --single

4. API 参考文档

本节介绍 Alicia-D SDK 的核心类与方法接口。以下接口均适用于示教臂，部分控制类接口（如关节运动、夹爪控制）主要用于操作臂场景。

4.1 初始化接口：`create_robot`

from alicia_d_sdk import create_robot

robot = create_robot(
    port="",                    # 串口（留空自动查找）
    gripper_type=None,          # 夹爪类型（"50mm" 或 "100mm"），None 时从缓存文件读取或默认 "50mm"
    debug_mode=False,           # 调试模式
    auto_connect=True,          # 自动连接
    base_link="base_link",      # 基座链路名称
    end_link="tool0",           # 末端执行器链路名称
    backend=None,               # 计算后端，'numpy' 或 'torch'（默认: None，使用 'numpy'）
    device="cpu"                # torch 后端设备，'cpu' 或 'cuda'（默认: 'cpu'）
)

4.2 控制接口：`SynriaRobotAPI`

from alicia_d_sdk import create_robot

robot = create_robot()

连接管理：

connect()
连接机械臂并检测固件版本
disconnect()
断开机械臂连接并停止更新线程
is_connected()
检查机械臂是否连接

状态获取：

get_robot_state(info_type="joint_gripper", timeout=1.0, cache=True)
统一的机器人状态获取接口，根据 info_type 返回不同类型的数据：

参数：
- info_type: 信息类型，可选值：
  - "joint_gripper": 返回 JointState 对象（默认），包含：
    - angles: 六个关节角度列表（弧度）
    - gripper: 夹爪开合度（0-1000，0为完全闭合，1000为完全张开）
    - timestamp: 时间戳（秒）
    - run_status_text: 运行状态文本（"idle", "locked", "sync", "sync_locked", "overheat", "overheat_protect", "unknown"）
  - "joint": 仅返回关节角度列表 List[float]（弧度）
  - "gripper": 仅返回夹爪值 float（0-1000）
  - "version": 返回版本信息字典，包含 serial_number, hardware_version, firmware_version
  - "temperature": 返回舵机温度列表 List[float]（摄氏度）
  - "velocity": 返回舵机速度列表 List[float]（度/秒）
  - "self_check": 返回自检状态字典，包含 raw_mask, bits, timestamp
  - "gripper_type": 返回夹爪类型字符串（如 "50mm" 或 "100mm"），失败时返回 None
- timeout: 最大等待时间（秒），默认 1.0
- cache: 是否使用缓存（仅对 gripper_type 有效），默认 True
返回值： 根据 info_type 返回相应类型的数据，失败返回 None
get_pose(backend=None)
获取当前末端执行器位置与姿态，返回字典包含 transform, position, rotation, euler_xyz, quaternion_xyzw

参数：
- backend: 计算后端，'numpy' 或 'torch'（默认: None，使用初始化时设置的后端）
返回值： 包含 transform, position, rotation, euler_xyz, quaternion_xyzw 的字典，失败返回 None
print_state(continuous=False, output_format='deg', fps=200.0)
打印当前机械臂信息，可持续打印，支持角度/弧度格式。包含关节角度、夹爪状态、末端位姿、温度、速度等信息

参数：
- continuous: 如果为 True，持续打印；如果为 False，仅打印一次，默认 False
- output_format: 角度格式，'deg'（度）或 'rad'（弧度），默认 'deg'
- fps: 连续模式的目标帧率（Hz），默认 200.0

4.3 RoboCore 集成

SDK 集成了 RoboCore 库，提供高性能运动学和轨迹规划功能：

运动学功能（来自 robocore.kinematics）：

forward_kinematics(robot_model, q, backend='numpy', return_end=True)
inverse_kinematics(robot_model, pose, q_init, backend='numpy', method='dls', ...)
jacobian(robot_model, q, backend='numpy', method='analytic')

1. 介绍​

1.1 主要特性​

2. 安装与配置​

2.1 环境要求​

2.2 安装步骤​

方法一：从源码安装（开发模式）​

方法二：从 PyPI 安装​

2.3 快速开始​

2.4 设置串口权限​

2.5 硬件连接与验证​

2.6 故障排除​

找不到串口/连接失败​

权限错误 (Permission denied)​

固件版本检测失败​

2.7 依赖包说明​

3. 示例代码说明​

3.1 文件结构​

3.2 主要参数说明​

3.3 基础功能​

00_demo_read_version.py​

01_torque_switch.py​

02_demo_zero_calibration.py​

03_demo_read_state.py​

4. API 参考文档​

4.1 初始化接口：create_robot​

4.2 控制接口：SynriaRobotAPI​

连接管理：​

状态获取：​

4.3 RoboCore 集成​

运动学功能（来自 robocore.kinematics）：​

1. 介绍

1.1 主要特性

2. 安装与配置

2.1 环境要求

2.2 安装步骤

方法一：从源码安装（开发模式）

方法二：从 PyPI 安装

2.3 快速开始

2.4 设置串口权限

2.5 硬件连接与验证

2.6 故障排除

找不到串口/连接失败

权限错误 (Permission denied)

固件版本检测失败

2.7 依赖包说明

3. 示例代码说明

3.1 文件结构

3.2 主要参数说明

3.3 基础功能

`00_demo_read_version.py`

`01_torque_switch.py`

`02_demo_zero_calibration.py`

`03_demo_read_state.py`

4. API 参考文档

4.1 初始化接口：`create_robot`

4.2 控制接口：`SynriaRobotAPI`

连接管理：

状态获取：

4.3 RoboCore 集成

运动学功能（来自 robocore.kinematics）：