云擎操作臂 Python SDK v1.1.1

版本兼容

本文档对应 Alicia-M SDK v1.1.1，适配 云擎通讯协议 v1.0.6。如果您直接对接底层串口帧，请同时参考本系列的《云擎通讯协议》页面。

1. 介绍

Alicia-M SDK 是用于控制 云擎 Alicia-M 系列六轴操作臂和夹爪的 Python 开发工具包。SDK 封装了串口通信、协议编解码、设备状态轮询、PV/MIT 控制、夹爪控制、运动学、轨迹规划、遥操作和设备设置等能力。

SDK 会屏蔽底层协议帧、寄存器地址、CRC 校验和状态轮询线程等实现细节。客户代码通常只需要通过 create_robot() 创建机器人对象，再调用清晰的 Python 方法完成设备连接、状态读取、关节运动、夹爪控制、模式切换、运动学计算、轨迹规划和维护配置。

普通开发流程建议只使用统一入口 alicia_m_sdk.create_robot() 创建机器人对象，再通过 SynriaRobotAPI 完成连接、状态读取和运动控制。

import alicia_m_sdk

robot = alicia_m_sdk.create_robot(port="COM37")
robot.set_robot_state(target_joints=[0, 30, 0, 0, -30, 0], joint_format="deg")
robot.disconnect()

1.1 核心能力

SDK 能做什么

统一控制入口：create_robot() 创建 SynriaRobotAPI 实例，覆盖连接、状态读取、运动控制、夹爪、诊断、用户设置和轨迹接口。
自动串口发现：port="" 时自动扫描可用串口；也可以显式指定 Windows COM37 或 Linux /dev/ttyACM0。
PV / MIT 双模式：PV 模式适合常规点位运动，MIT 模式适合阻抗控制、拖动示教、低延迟遥操作和逐帧控制。
关节 + 夹爪协同：set_robot_state() 可同时控制 6 个关节和夹爪，也可以只移动夹爪或只移动关节。
实时状态缓存：后台轮询维护角度、夹爪、速度、力矩和运行状态；扩展轮询可读取 Kp、Kd、插补速度和温度。
RoboCore 集成：支持正/逆运动学、关节轨迹、笛卡尔轨迹和轨迹 CSV 保存。
遥操作支持：内置 Alicia-D 到 Alicia-M 的 URDF 限位映射遥操作流程。
设备维护接口：提供自检、使能/失能、模式切换、零位设置、夹爪类型和用户设置读写。

2. 安装与连接

2.1 环境要求

Python >=3.11
Alicia-M 操作臂及 USB 连接线
Windows、Linux、macOS 均可使用
Linux 需要确认当前用户拥有串口访问权限

2.2 从 PyPI 安装

安装稳定版本：

pip install alicia-m-sdk

安装预发布版本：

pip install --pre alicia-m-sdk

包名和导入名

PyPI 包名使用连字符：alicia-m-sdk。Python 代码中的导入名使用下划线：import alicia_m_sdk。

2.3 从源码安装

如果需要运行仓库中的完整 examples/，建议从源码安装：

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

conda create -n msdk python=3.11
conda activate msdk

pip install -e .

可选依赖按功能拆分：

pip install -e ".[planning]"       # scipy 轨迹规划
pip install -e ".[visualization]"  # matplotlib 轨迹绘图
pip install -e ".[sparkvis]"       # WebSocket / SparkVis
pip install -e ".[teleop]"         # Alicia-D -> Alicia-M 遥操作
pip install -e ".[torch]"          # RoboCore torch 后端
pip install -e ".[all]"            # 常用可选依赖

2.4 串口权限

Windows 和 macOS 通常不需要额外配置。Linux 如果出现 Permission denied，可以按下列方式处理。

# 推荐：将当前用户加入 dialout 组，注销并重新登录后生效
sudo usermod -a -G dialout $USER

# 临时调试：放开当前 USB 串口权限
sudo chmod 666 /dev/ttyUSB* /dev/ttyACM*

# 永久规则：允许访问 ttyUSB/ttyACM 设备
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 硬件连接验证

将 Alicia-M 上电并通过 USB 连接到电脑后，先确认系统能看到串口：

系统	检查方式
Windows	打开设备管理器，查看 `COM` 端口
Linux	`ls -l /dev/ttyUSB* /dev/ttyACM*`
macOS	`ls /dev/cu.*`

再运行版本读取示例验证 SDK 是否能正常通信：

# Windows
python examples/00_demo_read_version.py --port COM37

# Linux
python examples/00_demo_read_version.py --port /dev/ttyACM0

如果不传 --port，SDK 会尝试自动扫描串口。

3. 快速开始

3.1 使用上下文管理器

推荐用 with 管理连接生命周期。进入 with 时 SDK 会确保已连接，离开时会自动断开串口。

import alicia_m_sdk

with alicia_m_sdk.create_robot(port="COM37", control_mode="pv") as robot:
    robot.set_robot_state(
        target_joints=[0, 30, 0, 0, -30, 0],
        gripper_value=500,
        joint_format="deg",
        speed=15,
        gripper_speed=100,
    )

    state = robot.get_robot_state("all")
    print(state.angles)   # 6 个关节角，单位 rad
    print(state.gripper)  # 夹爪开合值，范围 0~1000

3.2 自动扫描串口

port 默认是空字符串，表示自动发现 Alicia-M 串口。适合设备较少、开发调试的场景。

import alicia_m_sdk

robot = alicia_m_sdk.create_robot()
print(robot.connected_port)
robot.disconnect()

3.3 手动指定串口

生产脚本或多设备环境建议手动指定串口，避免连接到错误设备。

import alicia_m_sdk

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

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

if robot.is_connected():
    print("Alicia-M connected")

robot.disconnect()

3.4 延迟连接

如果希望先创建对象，再在合适时机连接，可以设置 auto_connect=False。

import alicia_m_sdk

robot = alicia_m_sdk.create_robot(
    port="COM37",
    auto_connect=False,
    sync_control_mode=False,
)

robot.connect(timeout=5.0)
print(robot.get_robot_state("version"))
robot.disconnect()

sync_control_mode=False 适合只读取版本号、状态等不需要立即同步控制模式的场景，可以减少连接阶段的等待。

4. 核心控制流程

4.1 PV 点位运动

PV 模式由固件完成位置和速度控制，适合点到点移动、回零、普通动作执行和轨迹回放。

import alicia_m_sdk

with alicia_m_sdk.create_robot(port="COM37", control_mode="pv") as robot:
    if robot.control_mode.value != "pv":
        robot.switch_mode("pv")

    ok = robot.set_robot_state(
        target_joints=[0, 30, 0, 0, -30, 0],
        joint_format="deg",
        speed=20,
        wait_for_completion=True,
    )
    print("arrived:", ok)

常用参数：

参数	说明
`target_joints`	6 个关节目标角；`joint_format="deg"` 时使用角度，`"rad"` 时使用弧度
`speed`	关节运动速度参数，数值越大运动越快
`wait_for_completion`	是否等待运动到达后再返回
`gripper_value`	可选夹爪目标值，范围 `0~1000`
`gripper_speed`	夹爪速度参数

4.2 只控制夹爪

如果 target_joints=None 且传入 gripper_value，SDK 只移动夹爪，不改变当前关节位置。

with alicia_m_sdk.create_robot(port="COM37") as robot:
    # 方式一：使用 set_robot_state
    robot.set_robot_state(
        target_joints=None,
        gripper_value=1000,
        gripper_speed=100,
    )

    # 方式二：使用夹爪快捷接口
    robot.set_gripper_target("open")
    robot.set_gripper_target("close")
    robot.set_gripper_target(value=500)

夹爪目标值范围为 0~1000。通常 0 接近闭合，1000 接近张开，实际开合距离取决于安装的夹爪类型和固件配置。

4.3 关节和夹爪协同运动

同一个 set_robot_state() 调用可以同时下发关节和夹爪目标。

with alicia_m_sdk.create_robot(port="COM37", control_mode="pv") as robot:
    robot.set_robot_state(
        target_joints=[0, 20, -10, 0, -35, 0],
        gripper_value=300,
        joint_format="deg",
        speed=15,
        gripper_speed=80,
    )

如果某一类目标传 None，表示保持当前状态：

# 只动关节，夹爪保持当前值
robot.set_robot_state(
    target_joints=[0, 10, 0, 0, -20, 0],
    gripper_value=None,
    joint_format="deg",
)

# 只动夹爪，关节保持当前角度
robot.set_robot_state(
    target_joints=None,
    gripper_value=600,
)

4.4 MIT 阻抗控制

MIT 模式用于阻抗控制、拖动示教和高频遥操作。控制律可理解为：

tau = kp * (pos_ref - pos_cur) + kd * (vel_ref - vel_cur) + t_ref

在 MIT 模式下，set_robot_state() 会发送位置、速度、力矩、Kp、Kd 等参数。可以仍然使用点位式写法，由 SDK 负责插值和到达判断。

with alicia_m_sdk.create_robot(port="COM37", control_mode="mit") as robot:
    if robot.control_mode.value != "mit":
        robot.switch_mode("mit")

    robot.set_robot_state(
        target_joints=[0, 30, 0, 0, -30, 0],
        gripper_value=500,
        joint_format="deg",
        speed=30,
        use_interpolation=True,
        kp=[150.0] * 7,
        kd=[2.0] * 7,
        torque=[0.0] * 7,
        vel_ref=[0.0] * 7,
        wait_for_completion=True,
    )

MIT 参数格式：

参数	说明
`kp`	位置环增益，可传标量、6 关节列表或 7 电机列表
`kd`	速度环增益，可传标量、6 关节列表或 7 电机列表
`torque`	前馈力矩，单位 N·m，可传标量、6 关节列表或 7 电机列表
`vel_ref`	目标速度，单位 rad/s，可传标量、6 关节列表或 7 电机列表
`use_interpolation`	MIT 模式下是否使用线性轨迹插值

零值不会被默认值覆盖

kp、kd、torque、vel_ref 显式传入 0 或 0.0 时表示真实零值。只有传入 None 时，SDK 才会使用对应默认值。

4.5 MIT 低延迟逐帧控制

send_mit_command() 适合低延迟和高频控制场景。调用方需要自行维持控制频率，并为每个电机准备 MIT 参数。

import time
import alicia_m_sdk
from alicia_m_sdk import MitParams

with alicia_m_sdk.create_robot(port="COM37", control_mode="mit") as robot:
    params = [
        MitParams(pos_ref=0.0, vel_ref=0.0, t_ref=0.0, kp=120.0, kd=1.5)
        for _ in range(7)
    ]

    for _ in range(200):
        robot.send_mit_command(params, gripper=500)
        time.sleep(0.01)  # 100 Hz

这种接口不会替调用方做完整轨迹规划，也不会等待到达目标，更适合已有外部控制器或实时遥操作循环的项目。

5. 状态读取

SDK 连接后会在后台维护设备状态缓存。常规状态读取不会每次都阻塞等待串口响应，因此适合在控制循环中频繁调用。

5.1 读取关节和夹爪

with alicia_m_sdk.create_robot(port="COM37") as robot:
    joints = robot.get_robot_state("joint")
    joint_gripper = robot.get_robot_state("joint_gripper")

    print(joints)                    # [j0, j1, j2, j3, j4, j5]，单位 rad
    print(joint_gripper["angles"])   # 6 个关节角，单位 rad
    print(joint_gripper["gripper"])  # 夹爪值，范围 0~1000

5.2 读取完整 `JointState`

info_type="all" 返回完整状态对象，适合需要同时查看角度、速度、力矩和扩展字段的程序。

with alicia_m_sdk.create_robot(port="COM37", extended_polling=True) as robot:
    state = robot.get_robot_state("all")

    print(state.angles)        # 关节角，rad
    print(state.gripper)       # 夹爪值，0~1000
    print(state.velocities)    # 关节速度，rad/s
    print(state.torques)       # 关节力矩，N*m
    print(state.kps)           # MIT Kp，扩展轮询开启后可用
    print(state.kds)           # MIT Kd，扩展轮询开启后可用
    print(state.linear_vels)   # 插补速度，扩展轮询开启后可用
    print(state.temperatures)  # 线圈温度，扩展轮询开启后可用

5.3 查询类型说明

`info_type`	返回内容	备注
`"joint"`	`list[float]`	6 个关节角，单位 rad
`"joint_gripper"`	`dict`	`angles` 和 `gripper`
`"velocity"`	`list[float]` 或 `None`	关节速度，单位 rad/s
`"torque"`	`list[float]` 或 `None`	关节力矩，单位 N·m
`"linear_vels"`	`list[float]` 或 `None`	插补速度，需扩展轮询
`"temperatures"`	`list[float]` 或 `None`	线圈温度，需扩展轮询
`"all"`	`JointState` 或 `None`	完整状态对象
`"version"`	`VersionInfo` 或 `None`	固件版本、硬件版本等
`"status"`	`RobotStatus` 或 `None`	运行状态
`"control_mode"`	`list[dict]` 或 `None`	一次性查询各电机控制模式

5.4 扩展轮询

默认轮询只读取基础状态，兼容范围更广。需要 Kp、Kd、插补速度、温度等字段时，可以启用扩展轮询。

robot = alicia_m_sdk.create_robot(port="COM37")

robot.set_extended_polling(True)
state = robot.get_robot_state("all")
print(state.kps, state.kds, state.linear_vels, state.temperatures)

robot.set_extended_polling(False)
robot.disconnect()

也可以在创建时直接启用：

robot = alicia_m_sdk.create_robot(
    port="COM37",
    extended_polling=True,
)

6. API 参考

6.1 `create_robot()`

create_robot() 是推荐的机器人创建入口。它会设置 RoboCore 后端、加载机器人模型、创建 SynriaRobotAPI，并在默认情况下自动连接设备。

robot = alicia_m_sdk.create_robot(
    port="",                    # 空字符串表示自动发现串口
    version="auto",             # 自动从固件识别模型版本；也可显式传 "v1_0" / "v1_1" / "v1_2"
    variant=None,               # URDF 变体；None 时使用默认 follower
    control_aim=None,           # "leader" / "follower" / None；None 表示自动检测或使用设备当前配置
    control_mode=None,          # "pv" / "mit" / None；None 表示连接时同步固件当前模式
    sync_control_mode=True,     # 连接时是否读取并同步固件控制模式
    baudrate=1_000_000,         # 串口波特率
    backend="cpp",              # RoboCore 后端："cpp" / "numpy" / "torch"
    debug_mode=False,           # 是否开启 DEBUG 日志
    auto_connect=True,          # 创建后是否立即连接
    extended_polling=False,     # 是否启用扩展状态轮询
)

参数说明：

参数	推荐值	说明
`port`	`""` 或实际串口	自动发现或手动指定串口
`version`	`"auto"`	自动识别硬件/模型版本；离线使用运动学时可显式指定
`control_aim`	`None`	通常 Alicia-M 作为 follower；遥操作脚本会显式传 `"follower"`
`control_mode`	`None`	让 SDK 跟随设备当前模式；需要固定模式时传 `"pv"` 或 `"mit"`
`sync_control_mode`	`True`	只读版本或状态时可设为 `False` 加快连接
`backend`	`"cpp"`	默认使用 RoboCore C++ 后端；没有 C++ 扩展时可切换为 `"numpy"`
`extended_polling`	`False`	需要扩展状态字段时再打开

6.2 `set_robot_state()`

set_robot_state() 是最常用的运动控制接口。它会根据当前控制模式自动走 PV 或 MIT 路径。

ok = robot.set_robot_state(
    target_joints=[0, 30, 0, 0, -30, 0],
    gripper_value=500,
    joint_format="deg",
    speed=40,
    gripper_speed=100,
    wait_for_completion=True,
    use_interpolation=True,
    kp=None,
    kd=None,
    torque=None,
    vel_ref=None,
)

参数	说明
`target_joints`	6 个关节目标角；`None` 表示不改变关节
`gripper_value`	夹爪目标值 `0~1000`；`None` 表示不改变夹爪
`joint_format`	`"deg"` 或 `"rad"`
`speed`	关节运动速度参数
`gripper_speed`	夹爪运动速度参数
`wait_for_completion`	是否等待到达目标
`use_interpolation`	MIT 模式是否使用线性插值
`kp` / `kd`	MIT 阻抗增益
`torque` / `vel_ref`	MIT 前馈力矩和目标速度

返回值为布尔值，表示 SDK 是否认为动作成功完成或下发成功。

6.3 `get_robot_state()`

version = robot.get_robot_state("version")
status = robot.get_robot_state("status")
modes = robot.get_robot_state("control_mode")
state = robot.get_robot_state("all")

version、status、all 主要来自后台缓存；control_mode 会发送一次控制模式查询帧并等待响应。控制循环中应优先读取缓存类状态，避免频繁阻塞查询。

6.4 模式切换和使能

robot.enable_robot()
robot.disable_robot()

robot.switch_mode("pv")
robot.switch_mode("mit")

robot.torque_control("off")  # MIT 模式下卸力
robot.torque_control("on")   # MIT 模式下恢复

switch_mode() 会执行失能、切换、使能的流程。切换过程中操作臂会短暂失能，请确保机械臂处于安全姿态。

6.5 夹爪类型和用户设置

Alicia-M 支持将夹爪类型写入设备用户设置。SDK v1.1.1 支持字符串、枚举或配置值形式。

with alicia_m_sdk.create_robot(port="COM37") as robot:
    robot.set_gripper_type("50mm")
    robot.set_gripper_type("100mm")

    settings = robot.get_user_settings(timeout=1.0)
    print(settings.values)

18_demo_user_settings.py 中也提供了命令行示例：

python examples/18_demo_user_settings.py --port COM37
python examples/18_demo_user_settings.py --port COM37 --gripper-type 10 --yes
python examples/18_demo_user_settings.py --port /dev/ttyACM0 --gripper-type 40 --yes

写入用户设置

用户设置会保存到设备侧，并影响后续夹爪动作。写入前请确认设备处于安全状态，且夹爪类型与实际硬件一致。

6.6 夹爪夹持参数

SDK 提供 get_gripper_params() 和 set_gripper_params() 读取或写入协议 0x17 对应的夹爪夹持参数。

with alicia_m_sdk.create_robot(port="COM37") as robot:
    params = robot.get_gripper_params(mask=0, aim="follower")
    print(params)

    result = robot.set_gripper_params(
        values={"force": 0.5},
        aim="follower",
        save=False,
        readback=True,
    )
    print(result)

set_gripper_params(..., save=False) 默认只让参数立即生效，不主动写入掉电保存区，适合调试夹持力、前馈力矩和力控参数。确认参数符合预期后，可以显式传入 save=True 请求设备保存当前完整夹爪参数配置；保存写入可能比普通写入慢，SDK 会使用至少 3 秒的响应等待时间。

不同固件公开的参数名和掩码位可能不同。工程中建议先用 15_demo_gripper_params.py 读取当前参数，再按协议文档确认要写入的字段。

6.7 运动学和轨迹规划

RoboCore 可用时，SDK 会加载 Alicia-M 模型并提供 FK、IK 和轨迹规划接口。

with alicia_m_sdk.create_robot(port="COM37", version="auto") as robot:
    pose = robot.get_pose()
    print(pose["position"])
    print(pose["quaternion_xyzw"])

    fk = robot.compute_forward_kinematics(
        joints=[0, 30, 0, 0, -30, 0],
        joint_format="deg",
    )

    ik = robot.set_pose(
        target_pose=pose["transform"],
        method="dls",
        execute=False,
    )
    print(ik["success"])

关节轨迹规划和执行：

waypoints = [
    [0.0, 0.0, 0.0, 0.0, -0.3, 0.0],
    [0.0, 0.4, 0.0, 0.0, -0.6, 0.0],
    [0.0, 0.2, 0.2, 0.0, -0.4, 0.0],
]

traj = robot.plan_joint_trajectory(
    waypoints=waypoints,
    planner_type="b_spline",
    duration=5.0,
    frequency=200.0,
)

if traj.get("success"):
    robot.execute_planned_joint_trajectory(traj, speed=100.0)

常用轨迹接口：

接口	用途
`get_pose()`	读取当前关节状态并计算末端位姿
`compute_forward_kinematics()`	对指定关节角计算 FK
`set_pose()`	IK 求解，并可选择是否执行到目标位姿
`plan_joint_trajectory()`	规划关节空间轨迹
`plan_cartesian_trajectory()`	规划笛卡尔空间轨迹
`execute_planned_joint_trajectory()`	执行已规划的关节轨迹
`move_joint_trajectory()`	从当前状态平滑移动到目标关节角
`move_cartesian_linear()`	执行笛卡尔直线轨迹

7. 示例程序详解

examples/ 目录中的脚本覆盖了从连接验证到遥操作、轨迹规划、设备设置的完整使用流程。

7.1 Demo 导览

第一次接入 Alicia-M 时，建议按下面顺序验证，先确认通信，再看状态，最后做运动控制：

运行 00_demo_read_version.py，确认 SDK 能连接设备并读取固件版本。
运行 02_demo_read_status.py 或 03_demo_read_states.py，确认运行状态、控制模式、关节角和夹爪值读取正常。
运行 06_demo_move_gripper.py 或 07_demo_move_joint.py，在安全空间内验证夹爪和关节运动。

python examples/00_demo_read_version.py --port COM37
python examples/03_demo_read_states.py --port COM37
python examples/07_demo_move_joint.py --port COM37 --speed 15

python examples/00_demo_read_version.py --port /dev/ttyACM0
python examples/03_demo_read_states.py --port /dev/ttyACM0
python examples/07_demo_move_joint.py --port /dev/ttyACM0 --speed 15

如果串口名不确定，可以先不传 --port，让 SDK 自动扫描；需要在生产环境固定设备时，再显式指定 Windows COM37 或 Linux /dev/ttyACM0。

7.2 基础功能

编号	文件	用途
00	`00_demo_read_version.py`	读取固件版本、硬件版本和设备信息，推荐作为连接验证第一步
01	`01_demo_diagnostic.py`	运行设备自检，查看通信和设备响应是否正常
02	`02_demo_read_status.py`	读取控制模式和运行状态
03	`03_demo_read_states.py`	循环打印关节角、夹爪、速度、力矩和扩展状态
04	`04_demo_switch_mode.py`	切换 PV / MIT 控制模式
05	`05_demo_disable_enable.py`	演示失能和使能

常用命令：

python examples/00_demo_read_version.py --port COM37
python examples/02_demo_read_status.py --port COM37
python examples/03_demo_read_states.py --port COM37 --extend

03_demo_read_states.py --extend 会调用 set_extended_polling(True)，适合检查 Kp、Kd、插补速度和温度字段。

7.3 运动控制

编号	文件	用途
06	`06_demo_move_gripper.py`	单独控制夹爪开合
07	`07_demo_move_joint.py`	PV 模式关节运动
08	`08_demo_move_full_arm.py`	PV 模式关节 + 夹爪协同运动
09	`09_demo_move_joint_mit.py`	MIT 模式关节运动
10	`10_demo_move_full_arm_mit.py`	MIT 模式关节 + 夹爪协同运动

常用命令：

python examples/06_demo_move_gripper.py --port COM37
python examples/07_demo_move_joint.py --port COM37 --speed 15
python examples/10_demo_move_full_arm_mit.py --port COM37

建议初次上手先运行 PV 示例，确认空间安全、方向正确后，再进入 MIT 示例。

7.4 运动学和轨迹

编号	文件	用途
11	`11_demo_forward_kinematics.py`	读取当前关节角并计算末端位姿
12	`12_demo_inverse_kinematics.py`	演示 IK 求解和可选执行
16	`16_demo_joint_traj.py`	关节空间轨迹规划、保存、绘图和执行

常用命令：

python examples/11_demo_forward_kinematics.py --port COM37
python examples/12_demo_inverse_kinematics.py --port COM37
python examples/16_demo_joint_traj.py --port COM37 --plot
python examples/16_demo_joint_traj.py --port /dev/ttyACM0 --planner multi_segment --segment-type quintic

16_demo_joint_traj.py 支持手动记录路点、自动生成路点或从文件加载路点。规划成功后会保存轨迹 CSV，并可选择绘制目标轨迹、反馈轨迹和速度曲线。

7.5 高级应用和设备设置

编号	文件	用途
13	`13_demo_reset_zero.py`	设置当前姿态为零位
14	`14_demo_teleop_mapped.py`	Alicia-D 到 Alicia-M 的 URDF 限位映射遥操作
15	`15_demo_gripper_params.py`	读取和写入夹爪夹持参数
17	`17_demo_mit_torque_switch.py`	MIT 模式力矩开关测试
18	`18_demo_user_settings.py`	读取和写入用户设置，例如夹爪类型

15_demo_gripper_params.py 对应协议 0x17 夹爪夹持参数。写入目标夹持力、前馈力矩、最大保持力矩、力控比例和积分参数时，SDK 会先做范围校验；默认 --gripper-type auto 会尝试读取当前夹爪类型，并按小夹爪或大夹爪的精确协议范围限制输入。写入默认只立即生效，需要掉电保存时显式添加 --save；--save 只用于写入参数，读取时不要使用。

python examples/15_demo_gripper_params.py --port COM37 --read
python examples/15_demo_gripper_params.py --port COM37 --gripper-type auto --target-force 35 --max-hold-torque 2.5
python examples/15_demo_gripper_params.py --port COM37 --gripper-type auto --target-force 30 --save
python examples/15_demo_gripper_params.py --port /dev/ttyACM0 --gripper-type auto --read

遥操作示例：

# Windows
python examples/14_demo_teleop_mapped.py --leader-port COM63 --port COM51 --mode mit

# Linux
python examples/14_demo_teleop_mapped.py --leader-port /dev/ttyACM0 --port /dev/ttyACM1 --mode mit

# PV 模式遥操作
python examples/14_demo_teleop_mapped.py --leader-port COM63 --port COM51 --mode pv

遥操作常用参数：

参数	默认值	说明
`--mode`	`mit`	Follower 控制模式，可选 `pv` / `mit`
`--leader-port`	`COM63`	Alicia-D 示教臂串口
`--port` / `--follower-port`	`COM51`	Alicia-M 操作臂串口
`--follower-version`	`v1_1`	Alicia-M 模型版本
`--frequency`	`100.0`	控制循环频率，单位 Hz
`--speed`	`200.0`	Follower 运动速度参数
`--interpolation`	关闭	MIT 模式下启用线性插值
`--home`	关闭	遥操作前先让 Follower 回零
`--verbose`	关闭	打印映射状态

遥操作安全

启动遥操作前请确认 Alicia-D 和 Alicia-M 都处在安全位置，工作空间内没有人员和障碍物。停止遥操作时建议先让操作臂回到安全姿态，再在终端中断程序。

8. 常见参数调整场景

8.1 PV 运动

现象	建议
运动过快	降低 `speed` 或 `gripper_speed`
到达后仍有明显误差	检查目标角单位是否与 `joint_format` 一致
夹爪动作方向不符合预期	确认夹爪类型配置和实际硬件一致
多段动作不够平滑	使用 `plan_joint_trajectory()` 或 `16_demo_joint_traj.py`

8.2 MIT 控制

现象	建议
关节太软	增大 `kp`
关节振荡或抖动	降低 `kp` 或增大 `kd`
启动 MIT 动作有突变	先调用 `initialize_mit_gains()` 平滑过渡 Kp/Kd
需要完全无前馈	显式传入 `torque=0.0` 或 `[0.0] * 7`
高频控制延迟敏感	使用 `send_mit_command()` 并由外部循环维持频率

8.3 IK 和轨迹

现象	建议
IK 求解失败	尝试不同 `method`，或提供更接近目标的初始关节角
轨迹规划失败	检查路点数量、关节限位和路点单位
轨迹执行不顺滑	增加 `duration` 或降低执行 `speed`
想对比目标和实测轨迹	使用 `16_demo_joint_traj.py --track-joints --plot`

9. 故障排除

9.1 无法连接设备

连接失败

确认 Alicia-M 已上电，USB 线连接牢固。
确认串口号正确，例如 Windows COM37、Linux /dev/ttyACM0。
确认串口没有被其他程序占用。
Linux 用户确认已加入 dialout 用户组，修改后需要注销并重新登录。
先运行 00_demo_read_version.py 验证最小通信链路。

9.2 状态一直为 `None`

后台轮询需要设备成功连接并收到第一批状态帧。可以先等待几百毫秒，或检查固件是否正常上传状态。

import time

state = None
for _ in range(20):
    state = robot.get_robot_state("all")
    if state is not None:
        break
    time.sleep(0.1)

print(state)

9.3 模式不符合预期

连接时 control_mode=None 表示跟随固件当前模式。如果程序必须运行在特定模式，创建后显式检查并切换。

if robot.control_mode.value != "pv":
    robot.switch_mode("pv")

如果只是读取版本或状态，不想在连接时同步控制模式，可设置：

robot = alicia_m_sdk.create_robot(
    port="COM37",
    sync_control_mode=False,
)

10. 项目结构

alicia_m_sdk/
|-- api/            # 面向客户的统一 API 门面，业务文件只有 synria_robot_api.py
|-- _internal/      # 内部辅助实现，例如连接握手
|-- execution/      # 内部关节控制、轨迹执行、遥操作
|-- hardware/       # 内部串口连接、协议帧、设备状态轮询
|-- integrations/   # 内部/高级 RoboCore 运动学和轨迹规划适配
|-- types/          # 可公开的配置、状态、枚举、异常
`-- utils/          # 内部工具和 demo 辅助

分层关系可以理解为：

demo代码
  |
  v
SynriaRobotAPI 统一入口
  |
  +-- _internal: 连接握手和内部协调
  +-- execution: 运动控制、夹爪控制、轨迹执行、遥操作
  +-- integrations: RoboCore 运动学和轨迹规划
  +-- hardware: 串口通信、协议编解码、状态轮询

常规开发只需要导入顶层包：

import alicia_m_sdk

robot = alicia_m_sdk.create_robot()

需要类型标注或低层能力时，再按需导入 MitParams、JointState、ControlMode 等类型。

11. 开发与验证

源码开发或发布前，可以运行 SDK 仓库中的测试、构建和包检查命令：

python -m pytest
python -m build
python -m twine check dist/*

Windows 下可以用清理脚本检查或删除缓存、构建产物和临时文件：

clean_sdk.bat /dry-run
clean_sdk.bat

默认清理不会删除 logs/ 或虚拟环境；确需包含这些目录时，可显式使用 clean_sdk.bat /logs 或 clean_sdk.bat /venv。

SDK 仓库中还包含面向维护和深入集成的扩展文档：

文档	用途
`docs/API_MAINTENANCE.md`	维护类接口说明
`docs/API_REFERENCE.md`	API 参考
`docs/ARCHITECTURE.md`	SDK 架构说明
`docs/PROTOCOL.md`	协议封装与底层通信说明

1. 介绍​

1.1 核心能力​

2. 安装与连接​

2.1 环境要求​

2.2 从 PyPI 安装​

2.3 从源码安装​

2.4 串口权限​

2.5 硬件连接验证​

3. 快速开始​

3.1 使用上下文管理器​

3.2 自动扫描串口​

3.3 手动指定串口​

3.4 延迟连接​

4. 核心控制流程​

4.1 PV 点位运动​

4.2 只控制夹爪​

4.3 关节和夹爪协同运动​

4.4 MIT 阻抗控制​

4.5 MIT 低延迟逐帧控制​

5. 状态读取​

5.1 读取关节和夹爪​

5.2 读取完整 JointState​

5.3 查询类型说明​

5.4 扩展轮询​

6. API 参考​

6.1 create_robot()​

6.2 set_robot_state()​

6.3 get_robot_state()​

6.4 模式切换和使能​

6.5 夹爪类型和用户设置​

6.6 夹爪夹持参数​

6.7 运动学和轨迹规划​

7. 示例程序详解​

7.1 Demo 导览​

7.2 基础功能​

7.3 运动控制​

7.4 运动学和轨迹​

7.5 高级应用和设备设置​

8. 常见参数调整场景​

8.1 PV 运动​

8.2 MIT 控制​

8.3 IK 和轨迹​

9. 故障排除​

9.1 无法连接设备​

9.2 状态一直为 None​

9.3 模式不符合预期​

10. 项目结构​

11. 开发与验证​

1. 介绍

1.1 核心能力

2. 安装与连接

2.1 环境要求

2.2 从 PyPI 安装

2.3 从源码安装

2.4 串口权限

2.5 硬件连接验证

3. 快速开始

3.1 使用上下文管理器

3.2 自动扫描串口

3.3 手动指定串口

3.4 延迟连接

4. 核心控制流程

4.1 PV 点位运动

4.2 只控制夹爪

4.3 关节和夹爪协同运动

4.4 MIT 阻抗控制

4.5 MIT 低延迟逐帧控制

5. 状态读取

5.1 读取关节和夹爪

5.2 读取完整 `JointState`

5.3 查询类型说明

5.4 扩展轮询

6. API 参考

6.1 `create_robot()`

6.2 `set_robot_state()`

6.3 `get_robot_state()`

6.4 模式切换和使能

6.5 夹爪类型和用户设置

6.6 夹爪夹持参数

6.7 运动学和轨迹规划

7. 示例程序详解

7.1 Demo 导览

7.2 基础功能

7.3 运动控制

7.4 运动学和轨迹

7.5 高级应用和设备设置

8. 常见参数调整场景

8.1 PV 运动

8.2 MIT 控制

8.3 IK 和轨迹

9. 故障排除

9.1 无法连接设备

9.2 状态一直为 `None`

9.3 模式不符合预期

10. 项目结构

11. 开发与验证