灵动Python SDK使用说明

1. 介绍

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

1.1 主要特性

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

2. 安装与配置

2.1 安装

克隆灵动Python SDK库：

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

安装依赖：

pip install -e .

2.2 设置串口权限

在Linux系统上，您需要为USB串口设备配置访问权限。

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

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

# 方法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.3 硬件连接与验证

1. 将机械臂通过USB连接至计算机。
2. 检查串口是否被系统识别：

   ls -l /dev/ttyUSB*

3. 运行版本读取示例以验证连接：

   cd examples
   python3 00_demo_read_version.py

   如果连接成功，终端将显示机械臂的固件版本等信息。

2.4 故障排除

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

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

  python3 00_demo_read_version.py --port /dev/ttyUSB0

• 波特率问题：
  • 固件版本 v5.4.19 及以上版本使用波特率 1000000。
  • 旧版本固件使用 921600。SDK会根据版本自动选择，但也可手动指定：

  python3 00_demo_read_version.py --baudrate 921600

3. 示例代码说明

examples 目录包含了丰富的演示脚本，帮助您快速上手。所有脚本都支持 --port 和 --baudrate 参数。

3.1 主要参数说明

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

参数	数据类型	默认值	描述
--port	str	/dev/ttyUSB0	指定机械臂连接的串口号，如 /dev/ttyUSB0。
--baudrate	int	1000000	指定串口通信的波特率。
--robot_version	str	v5_6	机械臂结构版本。
--gripper_type	str	50mm	夹爪型号。
--speed	float	1.0	运动速度因子 (0.0 ~ 1.0)。

附加参数

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

• --format: 角度显示格式，可选 rad（弧度）或 deg（角度），默认为 deg
• --single: 单次打印状态（仅适用于状态读取脚本）
• --mode: 拖动示教模式，可选 manual、auto 或 replay_only
• --save-motion: 动作名称（用于拖动示教功能）
• --list-motions: 列出所有可用动作（拖动示教功能）

---

3.2 基础功能

00_demo_read_version.py

• 描述: 读取机械臂版本信息，用于验证连接。
• 用法:

  python3 00_demo_read_version.py

01_torque_switch.py

• 描述: 切换机械臂所有关节的力矩状态（上电/掉电）。调电后可以自由拖动机械臂。
• 用法:

  # 先关力矩后开力矩
  python3 01_torque_switch.py

02_demo_zero_calibration.py

• 描述: 将机械臂当前位置设置为新的零点。此操作不可逆，请谨慎使用。
• 用法:

  python3 02_demo_zero_calibration.py

03_demo_read_state.py

• 描述: 持续读取并打印机械臂的关节角度、末端姿态和夹爪状态。
• 用法:

  python3 03_demo_read_state.py --port /dev/ttyUSB0 --robot_version v5_6 --gripper_type 50mm

---

3.3 运动控制

04_demo_move_gripper.py

• 描述: 控制夹爪张开或闭合到指定角度。
• 用法:

  # 演示夹爪开合过程
  python3 04_demo_move_gripper.py

05_demo_move_joint.py

• 描述: 将机械臂的单个或多个关节移动到目标角度。
• 用法:

  # 移动机械臂到目标关节角
  python3 05_demo_move_joint.py --port /dev/ttyUSB0

06_demo_move_cartesian.py

• 描述: 在笛卡尔空间内将机械臂末端移动到指定的目标位姿。
• 用法:

  # 移动到预设的目标位姿
  python3 06_demo_move_cartesian.py --port /dev/ttyUSB0 --robot_version v5_6 --gripper_type 50mm

---

3.4 运动学求解

07_demo_forward_kinematics.py

• 描述: 正运动学求解。根据给定的关节角度计算末端的位姿。
• 用法:

  # 计算所有关节都为0度时的末端位姿
  python3 07_demo_forward_kinematics.py --port /dev/ttyUSB0 --robot_version v5_6 --gripper_type 50mm

08_demo_inverse_kinematics.py

• 描述: 逆运动学求解。根据给定的末端目标位姿，计算并可选地执行关节角度。
• 用法:

  # 仅计算逆解，不执行动作
  python3 08_demo_inverse_kinematics.py
  # 计算逆解并控制机械臂移动到目标位姿
  python3 08_demo_inverse_kinematics.py --port /dev/ttyUSB0 --robot_version v5_6 --gripper_type 50mm --execute 

---

3.5 高级应用

09_demo_drag_teaching.py

• 描述: 拖动示教。通过手动拖动机械臂来录制一系列轨迹点，并可以回放。
• 用法:

  # 开始录制名为 "my_path" 的轨迹
  python3 09_demo_drag_teaching.py --name my_path --record
  # 回放 "my_path" 轨迹
  python3 09_demo_drag_teaching.py --name my_path --play