跳到主要内容

灵动Alicia-DL力反馈示教臂Python SDK

1. 介绍​

Alicia-D SDK 是灵动 Alicia-D 系列机械臂的 Python 开发工具包。本文面向力反馈示教臂（Leader Arm），介绍串口连接、状态读取、扭矩开关，以及力反馈版新增的控制模式、遥操作、力反馈和电流诊断接口。

初稿版本说明

本文按照配套的 Alicia-D-SDK 源码编写。该源码包版本字段为 6.1.0，但不能据此认定公开的同版本安装包包含全部电流模式及力反馈接口。正式下载入口、发布版本和配套固件版本待确认；以下使用配套源码安装。

1.1 主要特性​

核心能力
  • 状态读取：读取关节状态和固件版本，检查设备连接。
  • 扭矩开关：开启或关闭关节扭矩；与力反馈开关分别控制。
  • 零点设置：按配套校准流程重新建立关节零位。
  • 模式切换：查询和切换 position、current 两种公开控制模式。
  • 遥操作控制：通过公开接口进入或退出电流遥操模式。
  • 力反馈控制：设置力反馈请求，读取实际生效状态及未生效原因。
  • 电流调试：下发六轴目标电流，并读取输出和测量电流诊断。

2. 安装与配置​

2.1 环境要求​

  • Python 3.11 及以上版本。
  • 已获取力反馈版配套 Alicia-D-SDK 源码。
  • 计算机能够识别示教臂串口。
  • 进行双向力反馈时，需连接支持对应协议的配套操作臂，并使用匹配的两端固件。

2.2 安装步骤​

在终端进入配套源码中的 Alicia-D-SDK 根目录，即包含 pyproject.toml 的目录，然后执行：

conda create -n alicia-force python=3.11
conda activate alicia-force
python -m pip install -e .

确认 Python 实际加载的 SDK 路径：

python -c "import alicia_d_sdk; print(alicia_d_sdk.__file__)"

输出应指向本次安装的配套源码。若缺少电流模式及力反馈方法，应先检查环境和导入路径。

2.3 快速开始​

以下示例用于连接、读取版本和力反馈状态。将 COM3 替换为实际端口；Linux 下可使用系统识别出的 /dev/ttyUSB0 或 /dev/ttyACM0。

from alicia_d_sdk import create_robot

robot = create_robot(port="COM3")
try:
    if not robot.is_connected():
        raise RuntimeError("连接失败，请检查端口、供电和串口占用")
    print("版本：", robot.get_robot_state(info_type="version"))
    print("控制模式：", robot.get_control_mode())
    print("力反馈状态：", robot.get_force_feedback_state())
finally:
    robot.disconnect()

2.4 设置串口权限​

Linux 用户可将当前账户加入 dialout 组，然后注销并重新登录：

sudo usermod -a -G dialout $USER

Windows 用户在设备管理器中查看端口号，并关闭占用该端口的串口助手或其他程序。

2.5 硬件连接与验证​

按照安装与使用指南连接设备。首先在 SDK 根目录运行版本读取和单次状态读取：

python examples/00_demo_read_version.py --port COM3
python examples/03_demo_read_state.py --port COM3 --single

两端遥操作连接和力反馈应在基础通信正常后验证。

3. 示例代码说明​

3.1 文件结构​

以下为配套源码中与示教臂相关的主要示例。与原版文档相比，零点脚本名称已变更，并新增 13 至 15 号示例。

examples/
├── 00_demo_read_version.py             版本读取
├── 01_torque_switch.py                 扭矩开关
├── 02_demo_set_new_zero.py             零位校准
├── 03_demo_read_state.py               状态读取
├── 13_demo_control_mode.py             位置/电流模式切换
├── 14_demo_force_feedback_control.py   遥操作与力反馈开关
└── 15_demo_direct_current.py           六轴直接电流与诊断

3.2 基础功能​

版本和状态读取用于检查连接及关节数据。状态示例支持 --single、--format deg 或 --format rad，以及 --fps；具体选项可使用脚本的 --help 查看。

扭矩开关会改变关节受力状态，操作前应可靠支撑示教臂。零位校准会修改关节参考位置，应在确认校准姿态后执行，不作为普通连接测试步骤。

3.3 控制模式切换​

python examples/13_demo_control_mode.py --port COM3

脚本读取初始模式，提示操作者托住示教臂并确认后关闭扭矩，再切换到 current 模式。再次确认后恢复 position 模式，扭矩保持关闭。

3.4 遥操作与力反馈​

python examples/14_demo_force_feedback_control.py --port COM3

运行前应确认 D、M 两端姿态接近，且活动范围内无障碍物。脚本按交互提示依次开启遥操作、开启力反馈，最后关闭力反馈并恢复位置模式。退出时会尝试确认恢复结果。

力反馈请求成功不等于实际生效。 应通过 get_force_feedback_state() 检查 effective 和 inhibit_reasons。若无法确认恢复位置模式，先检查设备状态再执行其他运动示例。

3.5 直接电流调试​

15_demo_direct_current.py 用于开发调试，会切换电流模式并开启扭矩。先查看选项，再根据实机测试方案选择电流：

python examples/15_demo_direct_current.py --help
参数含义
--port示教臂串口
--joint单轴编号，1～6
--current-ma单轴目标电流，单位 mA
--currents按 J1～J6 顺序填写六个逗号分隔的 mA 值；覆盖单轴参数
--duration运行时长，单位秒
--period请求刷新周期，单位秒，脚本要求小于 0.10

脚本结束时尝试发送零电流、关闭扭矩并恢复位置模式。非零电流会产生关节力矩，脚本允许输入的数值范围不等于所有姿态下的安全工作范围。通信耗时也会影响实际刷新间隔，应结合回包与诊断确认执行情况。

4. API 参考文档​

4.1 初始化与基础状态​

from alicia_d_sdk import create_robot
robot = create_robot(port="COM3")
接口用途
is_connected()检查连接
disconnect()关闭 SDK 连接
get_robot_state(info_type="version")读取版本信息
print_state(continuous=False, output_format="deg")打印状态
torque_control("on") / torque_control("off")开启/关闭扭矩，返回是否成功

断开 SDK 连接不能代替退出遥操作或关闭扭矩。

4.2 模式与遥操作​

接口返回值与说明
get_control_mode(timeout=1.0)返回 "position"、"current" 或超时后的 None
set_control_mode(mode, timeout=2.0)确认目标模式生效后返回 True
set_teleoperation_enabled(enabled, timeout=2.0)True 进入电流遥操模式；False 请求关闭力反馈并切回位置模式
get_teleoperation_state(timeout=1.0)返回 enabled、active、mode

当前 SDK 的遥操作状态由控制模式推导，不能单独证明操作臂在线或反馈链路有效。退出遥操作不会自动开启扭矩或锁定姿态。

4.3 力反馈控制与状态​

接口返回值与说明
set_force_feedback_enabled(enabled, timeout=2.0)固件确认请求状态后返回 True，不直接写入舵机电流
get_force_feedback_state(timeout=1.0)返回状态字典；未收到状态时返回 None

主要状态字段：

字段含义
requested是否请求开启力反馈
effective力反馈是否实际生效
inhibit_reasons未生效原因列表，例如未进入遥操、机械锁定、D-M 链路超时、硬件故障或协议不支持
sync_active固件回报的同步状态

4.4 电流接口​

接口返回值与说明
set_direct_current(currents_ma, timeout=0.5)输入按 J1～J6 排列的六个整数电流，单位 mA；返回 ACK 字典或 None
get_hls_current_diagnostics(timeout=1.0)返回模式及六轴电流诊断字典，失败返回 None

ACK 中应检查 accepted、result 与 accepted_mask。诊断中各轴的 output_current_a 和 measured_current_a 单位为 A，与下发时的 mA 不同。直接电流控制与遥操作力反馈属于不同使用场景，应分别验证。

5. 故障排除​

现象检查方法
找不到串口或连接失败检查供电、USB 连接、端口号、Linux 权限及串口占用
提示没有电流模式及力反馈接口确认加载的是力反馈版配套源码，而非其他环境中的同名包
模式查询返回 None检查通信和固件协议支持情况，不把超时视为模式已生效
requested=True，但 effective=False查看 inhibit_reasons，按回报原因检查同步、锁定、链路与固件
电流命令被拒绝检查 ACK、当前模式、扭矩状态和固件保护状态
状态读取正常但力反馈无效分别检查计算机到示教臂、示教臂到操作臂两条通信链路