Version: 6.1.0 (Latest)

灵动Python SDK使用说明

1. 介绍

Alicia-D SDK 是一个用于控制【灵动 Alicia-D】系列六轴机械臂（带夹爪）的 Python 工具包。它基于 RoboCore 库构建，提供通过串口通信读取示教臂姿态与状态数据等功能。

1.1 主要特性

零点设置：将当前位置设置为新的零点。
状态读取：实时获取关节角、夹爪角与末端姿态。
自动串口连接：自动搜索串口或手动指定。
日志系统：支持日志级别过滤，可控制控制台输出详细程度。

2. 安装与配置

2.1 环境要求

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

2.2 安装步骤

克隆或下载项目

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

创建 Python 环境并安装依赖

使用 Conda 环境（推荐）：

conda create -n alicia python=3.10
conda activate alicia

安装依赖与 SDK：

pip install -e .

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串口设备配置访问权限。

# 方法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连接至计算机。
检查串口是否被系统识别（不同平台有时会将设备识别为 ttyUSB* 或 ttyACM*）：
```
ls -l  /dev/ttyACM*
```
运行版本读取示例以验证连接：
```
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 文件结构

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_demo_sparkvis.py              # SparkVis UI 双向同步
├── 12_benchmark_read_joints.py      # 关节读取性能测试
└── 13_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

`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"            # 末端执行器链路名称
)

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)
统一的机器人状态获取接口，根据 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
返回值： 根据 info_type 返回相应类型的数据，失败返回 None
get_pose()
获取当前末端执行器位置与姿态，返回字典包含 transform, position, rotation, euler_xyz, quaternion_xyzw
print_state(continuous=False, output_format='deg')
打印当前机械臂信息，可持续打印，支持角度/弧度格式。包含关节角度、夹爪状态、末端位姿、温度、速度等信息

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 安装步骤​

克隆或下载项目​

创建 Python 环境并安装依赖​

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 安装步骤

克隆或下载项目

创建 Python 环境并安装依赖

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）：