专为 Seeed Studio SoARM 10X 系列机械臂设计的 FTServo 舵机工厂校准工具包
A complete FTServo servo factory calibration toolkit designed for Seeed Studio SoARM 10X series robotic arms
| 特性 | 说明 |
|---|---|
| 自动端口检测 | 智能识别 USB 串口，自动过滤虚拟设备 |
| 跨平台支持 | Windows / Ubuntu / macOS 全平台兼容 |
| 交互式选择 | 友好的命令行交互，轻松选择串口 |
| 双端口同步 | 支持主从双端口同步遥控控制 |
| GUI 工具 | Qt 图形界面，直观易用 |
| 自动扫描 | 自动检测 ID 1-20 范围内所有舵机 |
pip install -r requirements.txt或手动安装：
pip install PySide6 pyserialpython -m src.tools.scan_id --listpython -m src.tools.scan_id| 脚本名称 | 功能描述 | Windows | Ubuntu | macOS |
|---|---|---|---|---|
| src/gui/factory_calibration_tool.py | 双端口 GUI 校准工具 | ✅ | ✅ | ✅ |
| src/tools/scan_id.py | 扫描检测舵机 ID | ✅ | ✅ | ✅ |
| src/tools/servo_center_test.py | 中位测试验证 | ✅ | ✅ | ✅ |
| src/tools/servo_disable.py | 失能舵机力矩 | ✅ | ✅ | ✅ |
| src/tools/servo_middle_calibration.py | 中位校准 | ✅ | ✅ | ✅ |
| src/tools/servo_quick_calibration.py | 快速失能+校准 | ✅ | ✅ | ✅ |
| src/tools/servo_remote_control.py | 双端口同步遥控 | ✅ | ✅ | ✅ |
| src/gui/servo_angle_limit_set.py | 角度限制设置 GUI | ✅ | ✅ | ✅ |
| src/tools/change_single_servo_id.py | 修改单个舵机 ID | ✅ | ✅ | ✅ |
双串口 GUI 校准工具，支持完整的舵机校准流程。
# 交互式选择端口
python -m src.gui.factory_calibration_tool
# 手动指定端口
python -m src.gui.factory_calibration_tool --port1 /dev/cu.usbserial-xxx --port2 /dev/cu.usbserial-yyy功能：
- 双端口独立控制
- 中位校准与测试
- 实时位置读取
- 力矩开关控制
扫描串口上的所有舵机，自动检测 ID 1-20。
# 交互式选择端口
python -m src.tools.scan_id
# 指定端口扫描
python -m src.tools.scan_id /dev/cu.usbserial-xxx
# 列出可用端口
python -m src.tools.scan_id --list输出示例：
==================================================
舵机扫描工具 / Servo ID Scanner
==================================================
端口 / Port: /dev/cu.usbmodem58FA1023621
扫描范围 / Scan Range: ID 1 - 20
==================================================
扫描中 / Scanning...
--------------------------------------------------
ID | 型号 (Model) | 状态
--------------------------------------------------
1 | 3310 | ✅ 在线 / Online
2 | 3310 | ✅ 在线 / Online
3 | 3310 | ✅ 在线 / Online
--------------------------------------------------
📊 扫描结束 / Scan Complete
发现 3 个舵机 / Found 3 servo(s): [1, 2, 3]
==================================================
测试舵机中位校准结果，移动到位置 2048 验证。
# 交互式选择端口
python -m src.tools.servo_center_test
# 指定端口测试
python -m src.tools.servo_center_test /dev/cu.usbserial-xxx测试流程：
- 扫描舵机
- 读取当前位置
- 启动力矩
- 移动到中位 (2048)
- 显示位移结果
判断标准：
- ✅ 校准成功：舵机保持原位（位移很小）
- ❌ 需要重新校准：舵机移动幅度较大
关闭舵机力矩，使其可以手动旋转。
# 交互式选择端口
python -m src.tools.servo_disable
# 指定端口失能
python -m src.tools.servo_disable /dev/cu.usbserial-xxx使用场景：
- 手动调整舵机位置
- 校准前准备
- 维护和检修
舵机中位校准，将当前位置设为中位值 (2048)。
# 交互式选择端口（可选择模式）
python -m src.tools.servo_middle_calibration
# 指定端口校准
python -m src.tools.servo_middle_calibration /dev/cu.usbserial-xxx两种模式：
| 模式 | 说明 |
|---|---|
| 🤝 交互式 | 逐步引导，每个步骤需确认 |
| 🚀 自动 | 快速执行，自动完成校准 |
校准流程：
- 扫描舵机
- 失能舵机（可选）
- 手动调整到期望中位
- 发送校准命令
- 移动测试验证
快速失能并校准中位，一键完成。
# 交互式选择端口
python -m src.tools.servo_quick_calibration
# 指定端口
python -m src.tools.servo_quick_calibration /dev/cu.usbserial-xxx快捷流程：
- 自动失能所有舵机
- 等待手动调整
- 一键校准中位
双端口同步遥控系统，从主控端口读取角度，同步控制从控端口。
# 交互式选择双端口
python -m src.tools.servo_remote_control
# 指定端口
python -m src.tools.servo_remote_control --read-port /dev/cu.usbserial-xxx --control-port /dev/cu.usbserial-yyy控制参数：
- 更新间隔：10ms (100Hz)
- 舵机速度：3000
- 加速度：100
使用场景：
- 主从同步控制
- 镜像运动复制
- 双机器人协作
GUI 工具，设置舵机角度限制范围。
python -m src.gui.servo_angle_limit_set修改单个舵机的 ID 地址。
python -m src.tools.change_single_servo_id所有脚本使用 src/port_utils.py 进行智能端口检测：
优先级排序：
┌─────────────────────────────────────────────────────────┐
│ macOS: cu.usbserial → cu.usbmodem → cu.* → tty.* │
│ Linux: ttyUSB → ttyACM → others │
│ Windows: COM1 → COM2 → ... (按编号) │
└─────────────────────────────────────────────────────────┘
自动过滤：
┌─────────────────────────────────────────────────────────┐
│ ❌ DEBUG (调试端口) │
│ ❌ BLUETOOTH (蓝牙设备) │
│ ❌ RFCOMM (蓝牙 RFCOMM) │
│ ❌ INCOMING (传入连接) │
└─────────────────────────────────────────────────────────┘
| 设备类型 | 路径格式 | 推荐 |
|---|---|---|
| USB Serial | /dev/cu.usbserial-* |
✅ |
| USB Modem | /dev/cu.usbmodem-* |
✅ |
| TTY 设备 | /dev/tty.usbserial-* |
❌ |
查看可用端口：
ls /dev/cu.* /dev/tty.*
python -c "from src.port_utils import list_ports_for_user; print(list_ports_for_user())"# 查看可用端口
ls -l /dev/ttyUSB* /dev/ttyACM*
# 查看插入设备
dmesg | grep tty# 在设备管理器中查看 "端口 (COM 和 LPT)"
# 或使用 Python
python -c "from src.port_utils import list_ports_for_user; print(list_ports_for_user())"A: 这通常发生在没有物理 USB 设备连接时。新版本已自动过滤此类虚拟设备。确保 USB 舵机已正确连接。
A: 双端口工具需要两个 USB 设备。检查：
python -m src.tools.scan_id --listA: 说明校准前舵机不在正确中位。重新运行：
python -m src.tools.servo_middle_calibration在校准前手动将舵机调整到期望的中位位置。
A: 可能需要安装 USB 转串口驱动：
| 芯片型号 | 驱动下载 |
|---|---|
| CH340 | 下载 |
| CP2102 | 下载 |
| FTDI | 通常自带驱动 |
A: 将用户添加到 dialout 组：
sudo usermod -a -G dialout $USER
# 重新登录后生效| 项目 | 要求 |
|---|---|
| 🐍 Python | 3.7 或更高版本 |
| 🖼️ PySide6 | >= 6.0 |
| 🔌 pyserial | >= 3.5 |
Seeed_RoboController/
├── src/
│ ├── port_utils.py # 串口工具模块
│ ├── tools/ # 命令行工具
│ │ ├── scan_id.py # 舵机 ID 扫描
│ │ ├── servo_center_test.py # 中位测试
│ │ ├── servo_disable.py # 舵机失能
│ │ ├── servo_middle_calibration.py # 中位校准
│ │ ├── servo_quick_calibration.py # 快速校准
│ │ ├── servo_remote_control.py # 双端口遥控
│ │ └── change_single_servo_id.py # 修改舵机 ID
│ └── gui/ # GUI 工具
│ ├── factory_calibration_tool.py # GUI 双端口校准工具
│ └── servo_angle_limit_set.py # 角度限制设置 GUI
│
├── scservo_sdk/ # SCServo SDK
├── setup.py # 安装检查脚本
├── requirements.txt # 依赖清单
└── README.md # 项目文档
运行方式: 所有工具使用
python -m src.<tools|gui>.<脚本名>运行
- 📁 重构项目结构，所有代码移至
src/目录 - 🧹 删除根目录重复的旧包装脚本
- 📦 统一使用 Python 模块方式运行工具 (
python -m src.<tools|gui>.*)
- 智能端口选择，自动过滤虚拟设备
- 交互式端口选择
- 自动扫描 ID 1-20 范围内舵机
- 修正中位值为 2048
- 全平台兼容性增强
- 双语界面（中文/English）
本项目采用 MIT 许可证开源。
如有问题，请提交 Issue
Built with ❤️ for the SoARM 10X community
Powered by Seeed Studio