Skip to main content
Version: 1.1.0 (Latest)

Python SDK使用说明

1. 介绍​

灵越Python SDK (https://github.com/Synria-Robotics/Bessica-D-SDK) 是一个用于控制7轴双机械臂的 Python 工具包。它提供了通过串口与机械臂通信、控制关节运动、操作夹爪以及读取状态信息的功能。

1.1 主要特性​

  • 串口通信：自动查找或指定串口进行连接
  • 数据解析：解析来自机械臂的反馈数据帧
  • 零点设置：将机械臂当前位置设置为新的零点
  • 力矩控制：启用或禁用机械臂关节力矩，允许自由拖动或锁定位置
  • 单双臂关节控制：同步控制双臂关节角度，可分别控制左右臂某个关节
  • 夹爪控制：控制夹爪的开合角度
  • 拖动示教：关闭扭矩后手动拖拽，将当前位置设置为零点,控制机械臂运动至设置位置

2. 安装​

1.克隆或下载SDK 可以使用Git克隆此仓库：

git clone https://github.com/Synria-Robotics/Bessica-D-SDK.git
cd Bessica-D-SDk

2.安装依赖项 创建conda环境 (必须):

conda create -n bessica_d_sdk python=3.8
conda activate bessica_d_sdk

安装库以及依赖

pip install -r requirements.txt
pip install -e .

3.硬件连接

  • 使用电源适配器给机械臂供电并打开电源键。
  • 使用type-c数据线将 Bassica-D 机械臂连接到您的计算机。
  • 操作系统操作系统通常会自动识别 USB 转串口设备。在 Linux 系统上，设备通常显示为 /dev/ttyUSB0、/dev/ttyUSB1 等。在 Windows 上，它会显示为 COMx (例如 COM3), 在MacOS上，它会显示为cu.usbserial-xxxx (例如 cu.usbserial-1440)

设置串口权限​

# 方法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

硬件连接验证

  1. 将机械臂通过USB连接至计算机；

  2. 检查串口是否被系统识别；

ls -l /dev/ttyUSB*
  • 确认串口设备名称（如ttyUSB0、ttyUSB1等）。

验证安装​

连接好机械臂之后，您可以尝试运行一个示例程序来验证SDK是否正常工作。 运行 read_angles.py 示例：

python ./exampels/demo_read_state.py

如果一切配置正确，您应该能在终端看到持续输出的机械臂关节角度和夹爪角度。按 Ctrl+c 退出程序。

故障排除​

  • 无法连接到机械臂/未找到可用串口：
    • 确保机械臂供电正常。
    • 检查Type-C数据线是否连接稳定。
    • 确认您的用户有权限访问串口设备 (在 Linux 上，可能需要将用户添加到 dialout 组，例如 sudo usermod -a -G dialout $USER，然后重新登录)
    • 如果 SDK 无法自动找到端口，您可以在初始化 ArmController 时手动指定端口，例如： 
      # filepath: examples/your_script.py
      # ...existing code...
      # controller = ArmController() # 自动搜索
      controller = ArmController(port="/dev/ttyUSB0") # Linux 示例
      # controller = ArmController(port="COM3") # Windows 示例
      # ...existing code...
  • 权限错误 (Permission denied):
    • 在 Linux 上，尝试使用 sudo python3 your_script.py 运行，或者参照上述方法将用户添加到 dialout 组。

如果您还遇到其他问题，请检查 SDK 日志输出或在项目的 lssue 跟踪系统中报告问题。

3. 示例代码说明​

examples 目录包含使用 Bessica-D SDK 与机械臂交互的演示脚本，涵盖基本控制、状态读取、夹爪操作和示教功能。

脚本文件功能说明
demo_read_state.py读取指定机械臂当前的关节角度和夹爪角度，支持持续输出
demo_single_arm.py控制单臂的七个关节：设置角度、归零、单关节操作
demo_dual_arm.py同步控制双臂的全部关节角度，可分别控制左右臂某个关节
demo_gripper.py控制夹爪开合角度，支持单/双臂夹爪设置和交互式输入
demo_zero_calibration.py关闭扭矩后手动拖拽，将当前位置设置为零点
demo_interactivate_mode.py综合控制界面，支持关节操作、夹爪控制、示教往复、扭矩开关等交互模式

3.1 推荐阅读顺序​

  1. demo_read_state.py：了解状态读取机制
  2. demo_single_arm.py：学习单臂控制流程
  3. demo_dual_arm.py：扩展到双臂控制
  4. demo_gripper.py：掌握夹爪使用方式
  5. demo_zero_calibration.py：了解零点设置方法
  6. demo_interactivate_mode.py：实际部署或测试前的综合调试入口

3.2 注意事项​

  • 所有脚本均使用 ArmController 类作为控制入口。
  • 请确保运行前机械臂已正确连接并上电。
  • 在操作夹爪和归零前，请注意保持机械臂物理安全。