云擎Python SDK使用说明

1. 介绍

Alicia-M SDK 是一套用于控制 云擎 Alicia-M 系列六轴机械臂（含夹爪）的 Python 开发工具包。该 SDK 基于玄雅自研的 RoboCore 机器人核心库构建，支持通过串口通信实现对机械臂的精确运动控制、夹爪操作，以及机械臂姿态与运行状态等关键数据的实时读取。

1.1 主要特性

核心能力

关节控制：支持设置与读取六个关节的角度，提供平滑插值执行。
控制目标选择：支持选择操作臂（Operation）或示教臂（Teach）模式。
多种控制模式：支持 PV（位置-速度）、PVT（位置-速度-扭矩）、MIT（力矩）等多种控制模式。
末端轨迹：支持笛卡尔空间末端姿态轨迹规划。
夹爪控制：支持精确角度控制或一键开关。
状态读取：实时获取关节角、夹爪角与末端姿态。
自动串口连接：自动搜索串口或手动指定。
教学模式：支持示教录制与轨迹回放。
日志系统：支持日志级别过滤，可控制控制台输出详细程度。

2. 安装与配置

2.1 环境要求

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

2.2 安装步骤

获取代码及配套 examples 例程：

git clone https://github.com/Synria-Robotics/Alicia-M-SDK.git
cd Alicia-M-SDK

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

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

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

cd Alicia-M-SDK
pip install -e .

方法二：从 PyPI 安装

pip install alicia_m_sdk

2.3 快速开始

基本使用示例：

import alicia_m_sdk

# 创建机器人实例
robot = alicia_m_sdk.create_robot(
    port="/dev/ttyUSB0",        # 串口端口
    version="v1_1",             # 机械臂版本
    control_aim="operation",    # 控制目标：operation (操作臂) 或 teach (示教臂)
    control_mode="pv",          # 控制模式：pv, pvt, v, mit 等
    debug_mode=True             # 调试模式
)

# 检查连接状态
if robot.is_connected():
    print("连接成功！")

    # 打印当前状态
    robot.print_state()

    # 回到初始位置
    robot.go_home(speed_deg_s=20)

    # 断开连接
    robot.disconnect()
else:
    print("连接失败，请检查串口")

tip

create_robot() 默认会自动连接机械臂。您也可以通过参数手动指定串口或调整连接行为。

手动指定串口：

# Linux
robot = alicia_m_sdk.create_robot(port="/dev/ttyUSB0")

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

2.4 设置串口权限

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

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

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

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

2.5 硬件连接与验证

将机械臂通过 USB 连接至计算机。

检查串口是否被系统识别（不同平台下设备名称可能为 COM*、ttyUSB* 或 ttyACM*）：

Linux: ls -l /dev/ttyUSB* /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. 示例代码说明

3.1 文件结构

examples/
├── 00_demo_read_version.py              # 读取版本号
├── 01_demo_switch_mode.py               # 切换控制模式与力矩开关
├── 02_demo_monitor_arm_status_simple.py  # 简单状态监控
├── 03_demo_read_state.py                # 读取详细状态
├── 04_demo_move_gripper.py              # 夹爪控制
├── 05_demo_move_joint.py                # 关节空间运动
├── 07_demo_forward_kinematics.py        # 正向运动学
├── 08_demo_inverse_kinematics.py        # 逆向运动学
├── 09_demo_joint_traj.py                # 关节轨迹规划
├── 10_demo_cartesian_traj.py            # 笛卡尔轨迹规划
├── 11_demo_slider_control_joint.py      # 滑块控制
└── 12_demo_sparkvis.py                  # 玄雅上位机 SparkVis 同步

3.2 主要参数说明

参数	默认值	描述
`--port`	`""`	串口号，如 `/dev/ttyUSB0`
`--version`	`"v1_1"`	机械臂版本
`--control-aim`	`"operation"`	控制目标：`operation`（操作臂/0x02）或 `teach`（示教臂/0x01）
`--control-mode`	`"pv"`	控制模式：`pv`（位置-速度）、`mit`、`v` 等
`--speed_deg_s`	`20`	关节运动速度（10-400 度/秒）

附加参数

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

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

3.3 基础功能

00_demo_read_version.py：读取机械臂固件版本号。
01_demo_switch_mode.py：切换机械臂控制模式与力矩状态。
02_demo_monitor_arm_status_simple.py：简单状态监控。
03_demo_read_state.py：持续读取并打印状态信息。

3.4 运动控制

04_demo_move_gripper.py：夹爪控制示例。
05_demo_move_joint.py：关节空间运动控制。

3.5 运动学求解

07_demo_forward_kinematics.py：正向运动学求解。
08_demo_inverse_kinematics.py：逆向运动学求解。

3.6 高级应用

09_demo_joint_traj.py：关节空间轨迹执行。
10_demo_cartesian_traj.py：笛卡尔空间轨迹执行。
11_demo_slider_control_joint.py：滑块实时控制。
12_demo_sparkvis.py：与玄雅机器人上位机 SparkVis UI 进行数据同步与桥接。

3.7 常见参数调整场景

运动控制参数调整：

速度过快：降低 speed_deg_s（范围：5-400 度/秒）
运动不流畅：增加 num_points（轨迹插值点数）
移动时间过长：减少 duration（轨迹持续时间）或 duration_per_segment（每段持续时间）

IK 求解参数调整：

求解失败：尝试不同 method（dls、pinv、transpose），增加 num_initial_guesses（建议 5-10）
局部最优：使用 initial_guess_strategy='random' 或增加 num_initial_guesses
精度要求高：降低 pos_tol/ori_tol 到 1e-5 或更小，增加 max_iters

4. API 参考文档

4.1 初始化接口：`create_robot`

robot = alicia_m_sdk.create_robot(
    port="",                    # 串口号
    gripper_type="100mm",       # 夹爪类型
    version="v1_1",             # 机械臂版本
    base_link="base_link",      # 基座链路
    end_link="link6",           # 末端链路
    control_aim="operation",    # operation 或 teach
    control_mode="pv",          # pv, pvt, v, mit, mit_position, mit_speed, mit_torque
    debug_mode=False            # 调试开关
)

4.2 核心方法

方法	说明
`go_home(speed_deg_s=20)`	移动机械臂到初始位置
`set_robot_state(...)`	设置关节目标或夹爪位置。支持 `target_joints`、`gripper_value`、`wait_for_completion` 等参数
`get_robot_state(info_type="joint_gripper")`	获取当前关节/夹爪/温度/速度等详细状态
`switch_control_mode(mode='pv')`	动态切换控制模式

4.3 控制目标 (Control Aim)

目标	物理标识	说明
`operation`	`0x02`	用于控制执行任务的操作臂
`teach`	`0x01`	通常用于读取或同步示教臂数据

4.4 RoboCore 集成

SDK 集成了玄雅自研的 RoboCore 机器人核心库，提供高性能运动学求解与轨迹规划功能。

1. 介绍​

1.1 主要特性​

2. 安装与配置​

2.1 环境要求​

2.2 安装步骤​

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

方法二：从 PyPI 安装​

2.3 快速开始​

2.4 设置串口权限​

2.5 硬件连接与验证​

2.6 故障排除​

2.7 依赖包说明​

3. 示例代码说明​

3.1 文件结构​

3.2 主要参数说明​

3.3 基础功能​

3.4 运动控制​

3.5 运动学求解​

3.6 高级应用​

3.7 常见参数调整场景​

4. API 参考文档​

4.1 初始化接口：create_robot​

4.2 核心方法​

4.3 控制目标 (Control Aim)​

4.4 RoboCore 集成​