专为 Seeed Studio SoARM 10X 系列机械臂设计的 FTServo 舵机工厂校准与 LeRobot 校准工具包
A complete FTServo servo factory calibration and LeRobot-style calibration toolkit designed for Seeed Studio SoARM 10X series robotic arms
| 特性 | 说明 |
|---|---|
| 自动端口检测 | 智能识别 USB 串口，自动过滤虚拟设备 |
| 跨平台支持 | Windows / Ubuntu / macOS 全平台兼容 |
| 网页校准台 | 浏览器内完成扫描、中位校准、单舵机控制和高级维护 |
| 自动扫描 | 自动检测 ID 1-20 范围内所有舵机 |
| 安全任务控制 | 操作超时自动结束，中位测试 30 秒后自动失能 |
| LeRobot 校准 | 生成 LeRobot 格式的 JSON 校准文件，支持 LeRobot 匹配模式 |
| 校准文件中位运行 | 根据校准文件将机械臂移动到中位 |
- Python >= 3.8
- pyserial >= 3.5
推荐安装在 LeRobot 虚拟环境中，如需单独使用建议创建新的虚拟环境，避免污染系统 Python。
# 安装依赖
pip install -r requirements.txtpython setup.py看到 [OK] 环境检查通过 即可。
setup.py同时是 pip 安装脚本。也可直接运行pip install -e .将项目安装为 Python 包，安装后会得到roboctrl-web命令用于启动校准台。
# 启动本机网页校准台
python -m src.web.factory_calibration_web
# 不自动打开浏览器
python -m src.web.factory_calibration_web --no-browser
# 端口 8765 被占用时使用其他网页端口
python -m src.web.factory_calibration_web --port 8766
# 不连接硬件，预览界面和操作流程
python -m src.web.factory_calibration_web --demo网页校准台启动后会自动打开 http://127.0.0.1:8765。如未自动打开，请在本机浏览器手动访问该地址。
同一块控制板一次只能由一个程序占用。启动网页校准台前，请关闭串口助手及其他正在访问同一 COM/USB 串口的程序。
完整操作步骤、安全说明和 ID 修复流程见 用户手册.md。
- 校准：扫描、中位校准、中位测试和全部失能
- 单舵机：状态读取、限位检查、位置控制和力矩开关
- 高级工具：ID 修改、角度限位修复、寄存器读写、波特率修改和恢复出厂
- 校准文件：从动臂/领导臂文件管理、运行到中位、六关节数值编辑和整臂校准向导
在 校准文件 > 校准向导 中选择机械臂类型和文件 ID 后开始校准。向导会先失能舵机并持续同步 ID 1-6 的当前位置和 EEPROM 中位偏移。依次记录六个关节中位，再逐个开始和停止范围记录。勾选 LeRobot 匹配 选项后，向导会先将舵机 Homing Offset 清零，确保生成的 homing_offset 天然落在硬件范围内，文件可直接用于 LeRobot。
所有工具使用 src/port_utils.py 进行智能端口检测：
优先级排序：
┌─────────────────────────────────────────────────────────┐
│ macOS: cu.usbserial → cu.usbmodem → cu.* → tty.* │
│ Linux: ttyUSB → ttyACM → others │
│ Windows: COM1 → COM2 → ... (按编号) │
└─────────────────────────────────────────────────────────┘
自动过滤：
┌─────────────────────────────────────────────────────────┐
│ ❌ DEBUG (调试端口) │
│ ❌ BLUETOOTH (蓝牙设备) │
│ ❌ RFCOMM (蓝牙 RFCOMM) │
│ ❌ INCOMING (传入连接) │
│ ❌ ttyS* (Linux 虚拟串口) │
└─────────────────────────────────────────────────────────┘
A: 先停止当前任务并关闭网页校准台、串口助手等可能占用该 COM 口的程序，再重新启动网页校准台。仍未释放时，在任务管理器中结束残留的项目 Python 进程，然后重新插拔控制板。不要同时启动多个网页校准台实例。
A: ID 已写入舵机，但页面保留的是上一次扫描结果。点击黄色提醒中的 立即扫描，或左侧串口区域常驻的 立即扫描，成功扫描后列表才会更新。
A: 点击 读取状态，检查单舵机卡片上的"限位"。限位跨度过小时，页面会标记 限位异常 并禁用移动。失能舵机后手动移动到两个机械端点并记录位置，再到 高级工具 > 角度限位 写入真实最小值和最大值。
A: 确认启动终端仍在运行，并访问 http://127.0.0.1:8765。如果 8765 被占用：python -m src.web.factory_calibration_web --port 8766，然后访问 http://127.0.0.1:8766。
A: sudo usermod -a -G dialout $USER，重新登录后再运行工具。
A: 检查 ID 6 卡片显示的角度限位。如果最小值和最大值几乎相同，说明机械范围采集时夹爪没有被移动。按照"高级工具 > 角度限位"的步骤重新采集。
| 项目 | 要求 |
|---|---|
| 🐍 Python | 3.8 或更高版本 |
| 🔌 pyserial | >= 3.5 |
Seeed_RoboController/
├── src/ # 源代码
│ ├── port_utils.py # 串口工具模块
│ ├── calibration_manager.py # LeRobot 校准文件管理
│ ├── tools/ # 后台工具脚本
│ │ ├── scan_id.py # 舵机 ID 扫描
│ │ ├── run_calibration_middle.py # 校准文件中位运行
│ │ ├── servo_center_test.py # 中位测试
│ │ ├── servo_disable.py # 舵机失能
│ │ ├── servo_quick_calibration.py # 快速校准
│ │ └── servo_web_command.py # 网页端结构化舵机命令
│ └── web/ # 网页校准台
│ ├── factory_calibration_web.py # Web 服务与任务管理
│ ├── calibration_store.py # 校准文件存储模块
│ └── static/ # 网页界面资源
│ ├── index.html
│ ├── app.js
│ └── app.css
├── scservo_sdk/ # SCServo SDK
├── setup.py # 环境检查 + pip 安装脚本
├── requirements.txt # 依赖清单
├── 用户手册.md # 详细使用手册
├── README.md # 项目文档
└── LICENSE # MIT 许可证
本项目采用 MIT 许可证开源。
如有问题，请提交 Issue
Built with ❤️ for the SoARM 10X community
Powered by Seeed Studio