SoARM シリーズ サーボキャリブレーションツール使用チュートリアル
SoARM シリーズキャリブレーションツールは、SoARM 10X シリーズロボットアーム(例:SO-ARM101 開発キット)専用に設計された FTServo サーボの工場キャリブレーションおよび LeRobot キャリブレーションのツールキットです。グラフィカルインターフェース上で、サーボの中位キャリブレーション、単体サーボ制御、パラメータの読み書き、xdat パラメータのバックアップ/復元、2 ポート同期遠隔操作などの操作を完了でき、LeRobot 形式の JSON キャリブレーションファイルの生成にも対応しています。ロボットアームの組み立てとサーボの取り付けについては、先に LeRobot ロボットアーム組立ガイドを参照してください。
本ツールは Seeed Studio の Seeed_RoboController プロジェクトをベースに改造・アップグレードしたもので、元のプロジェクトは MIT ライセンスで公開されています。本プロジェクトは既存のコア機能を維持したうえで、GUI を再構築し、FT デバッガー、xdat パラメータのバックアップ/復元、クロスプラットフォーム対応などの拡張機能を追加しています。
互換性に関する注意
⚠️ 本ツールは現在 Feetech(STS3215 シリーズ)のサーボのみに対応しています。レジスタテーブル、xdat パラメータ形式、ボーレートテーブルはすべて Feetech STS3215 シリーズ向けに設計されており、他ブランド/型番のサーボの互換性は保証されません。
機能一覧
| 機能 | 説明 |
|---|---|
| 自動ポート検出 | USB シリアルポートを自動認識し、仮想デバイスを自動で除外 |
| クロスプラットフォーム対応 | Windows / Ubuntu / macOS の全プラットフォームに対応 |
| 2 ポート同期 | 左右 2 つのシリアルポートを独立して操作でき、マスター/スレーブ 2 ポートの同期遠隔操作に対応 |
| 中国語/英語切替 | インターフェース内でワンクリックで中国語/英語を切替、選択内容は自動記憶 |
| 中位キャリブレーション | サーボの現在位置を 2048 の中位として書き込み(EEPROM に永続化) |
| 中位テスト | トルクを有効にしてサーボを中位へ移動し、キャリブレーション結果を検証 |
| モーターのトルクオフ | ワンクリックですべてのサーボのトルクをオフにし、手動調整を容易に |
| 自動スキャン | ID 1–20 の範囲内のすべてのオンラインサーボを自動検出 |
| 単体サーボ制御 | スライダーで個々のサーボの位置とトルクスイッチをリアルタイム制御 |
| FT デバッガー | シリアル接続、スキャン、パラメータの読み書き、位置制御、ボーレート変更、工場出荷リセット、xdat パラメータのバックアップ |
| xdat パラメータ | 現在のサーボ EEPROM パラメータを保存 / バックアップを開いて復元 |
| LeRobot キャリブレーション | LeRobot 形式の JSON キャリブレーションファイルを生成 |
| キャリブレーションファイルによる中位移動 | キャリブレーションファイルに基づいてロボットアームを中位へ移動 |
画面構成
メインプログラムには 3 つのタブがあります:
┌─────────────────────────────────────────────────────────────┐
│ SoARM 系列校准工具 [串口1▾] [串口2▾] [🔄] [🎮遥控][EN]│ ← 顶栏
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────┬──────────────────────────────┐ │
│ │ 串口1 - 舵机标定 │ 串口2 - 舵机标定 │ │
│ │ [🔴未连接] 当前舵机:… │ [🔴未连接] 当前舵机:… │ │
│ │ 舵机1~6 状态表格 │ 舵机1~6 状态表格 │ │
│ │ [中位校准][中位测试]… │ [中位校准][中位测试]… │ │
│ └─────────────────────────┴──────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘- トップバー:アプリのタイトル、シリアルポート選択ドロップダウン、更新ボタン、遠隔操作ボタン、言語切替ボタン。
- 🦾 Tab1 サーボキャリブレーション:左右パネルのショートカット操作(中位キャリブレーション、中位テスト、モーターのトルクオフ)およびリアルタイム状態。
- 🎚️ Tab2 単体サーボ制御:オンラインの各サーボの位置をスライダーで微調整し、トルクをオン/オフ。
- 🔬 Tab3 FT デバッガー:シリアル接続、スキャン、パラメータの読み書き(56 個のレジスタ)、位置制御、ボーレート/工場出荷リセット、xdat パラメータのバックアップと復元。
インストールと起動
環境要件:
| 依存関係 | バージョン | 説明 |
|---|---|---|
| Python | >= 3.8 | 3.10+ を推奨。python.org からダウンロード |
| PySide6 | >= 6.0 | GUI フレームワーク |
| pyserial | >= 3.5 | シリアル通信 |
| システム | Windows 10 / 11、Ubuntu 20.04+ / Debian 11+、macOS 11+ | macOS 11+ は Apple Silicon / Intel に対応 |
ハードウェア接続:USB-シリアル変換アダプタ(例:CH340 / CP2102)でロボットアームの制御基板を接続し、サーボに電源を供給します(標準版は DC 5V 5A、Pro 版は DC 12V 5A を推奨)。
Windows
- Python 3.10+ をインストールします(インストール時に必ず Add Python to PATH をチェックしてください。チェックしないとコマンドラインで
pythonが見つかりません)。インストールの確認:
python --version- 仮想環境を作成し、依存関係をインストールします:
cd Juxi_ServoController
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txtヒント:アクティベート後、コマンドラインの先頭に
(.venv)が表示されます。
- 環境を確認して起動します:
python setup.py
python -m src.gui.factory_calibration_tool[OK] 环境检查通过,可以运行项目 と表示されれば、環境が正しいことが確認できます。
- デバイスマネージャー(
Win+X→ デバイスマネージャー)の「ポート (COM と LPT)」でシリアルポート番号を確認します:
端口 (COM 和 LPT)
└─ USB-SERIAL CH340 (COM3) ← 你的舵机串口COM 番号を控えてください。起動後にトップバーで選択します。手動でポートを指定することもできます(シリアルポートが使用中の場合):
python -m src.gui.factory_calibration_tool --port1 COM3 --port2 COM4使用可能なポートを確認:
python -m src.gui.factory_calibration_tool --list-portsLinux(Ubuntu / Debian)
- 中国語フォントと依存関係をインストールします(中国語フォントは中国語インターフェースの表示に必須で、emoji フォントはログの ✅⚠️ などのアイコンに使用されます):
sudo apt install python3-venv fonts-noto-cjk fonts-noto-color-emoji- ⚠️ シリアルポート権限(dialout グループ)の追加【必須】(Linux ではデフォルトで一般ユーザーが
/dev/ttyUSB*//dev/ttyACM*にアクセスできません):
sudo usermod -a -G dialout $USER
# 注销并重新登录后生效確認(出力に dialout が含まれている必要があります):
groups有効にならない場合:パソコンを再起動してください。一部のディストリビューションではグループ名が
uucp(Arch)やttyです。
- 仮想環境を作成し、依存関係をインストールして起動します:
cd Juxi_ServoController
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python setup.py
python -m src.gui.factory_calibration_toolpip が externally managed environment エラーを報告する場合は、
pip install --break-system-packages -r requirements.txtに変更するか、仮想環境を使用してください。
- USB-シリアル変換デバイスを確認します(アダプタを挿入後):
ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null典型的な出力:
/dev/ttyUSB0 # CH340 / CP2102 / PL2303
/dev/ttyACM0 # 原生 USB 串口(Arduino / ESP32 板载)詳細な製造元情報を確認:
dmesg | tail -20 | grep -i tty
# 或
lsusb複数のデバイスがある場合、挿抜順に
ttyUSB0/ttyUSB1が割り当てられ、不安定になることがあります。/dev/ttyACM*を使用するか、製造元別に固定することを推奨します(後述の udev の節を参照)。
手動でポートを指定:
python -m src.gui.factory_calibration_tool --port1 /dev/ttyUSB0 --port2 /dev/ttyUSB1シリアルポートが 1 つだけの場合、ツールは 2 番目のポートを自動的に「無効」に設定します。
- オプション:udev でデバイス名を固定する(挿抜後に番号が変わるのを防ぐ)。
/etc/udev/rules.d/99-servo.rulesを作成し、USB ID で固定します:
SUBSYSTEM=="tty", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", SYMLINK+="ttyServo"以降は ls -l /dev/ttyServo で固定名を使ってアクセスできます。製造元 ID は lsusb で確認できます。
macOS
- Homebrew で Python をインストールします(システム標準の Python が古いバージョンであることを避けるため):
# 安装 Homebrew(如果没有)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装 Python
brew install python確認:
python3 --version- 仮想環境を作成し、依存関係をインストールして起動します(
sourceでアクティベートし、.batではありません):
cd Juxi_ServoController
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python setup.py
python -m src.gui.factory_calibration_tool- ⚠️ シリアルポートの命名:macOS は USB-シリアル変換デバイスを
/dev配下に置き、2 通りの命名があります:
| プレフィックス | 意味 | 使用可否 |
|---|---|---|
/dev/tty.usbserial-* | モデムスタイル(ブロッキング式) | スタックする可能性あり、非推奨 |
/dev/cu.usbserial-* | コール/ターミナルスタイル(非ブロッキング) | ✅ 推奨使用 |
自分のシリアルポート名を確認:
ls /dev/cu.*典型的な出力:
/dev/cu.usbserial-0001 # CP2102 / FTDI
/dev/cu.usbmodem141101 # 板载 USB 串口(Arduino / ESP32)
/dev/cu.wchusbserial1420 # CH340プログラムは
cu.*デバイスを自動的に優先選択します。手動でポートを指定する場合はtty.ではなくcu.を使用してください。
手動でポートを指定:
python -m src.gui.factory_calibration_tool --port1 /dev/cu.usbserial-0001 --port2 /dev/cu.usbmodem141101- USB ドライバー:ほとんどの一般的なチップ(CH340、CP2102、FTDI)は macOS 標準のドライバーでプラグアンドプレイに対応しています。デバイスが認識されない場合:
system_profiler SPUSBDataType | grep -A5 -i "serial\|CH340\|CP210"- CH340:古いロットは WCH 公式ドライバーのインストールが必要です。
- 通常は
ls /dev/cu.*でデバイスが見えれば問題ありません。
- 使用上のヒント:
- シリアルポート名は変わります:USB ポートを変えて挿抜すると
cu.*名が変わることがあります。起動のたびにトップバーのドロップダウンで選択してください。 - 省電力:macOS がスリープするとシリアルポートが切断されることがあります。操作中はスリープを解除するか、スリープ時間を長めに設定してください。
- プライバシー権限:初回実行時に「リムーバブルディスクへのアクセス」を求められたら、許可をクリックしてください。
- シリアルポート名は変わります:USB ポートを変えて挿抜すると
使用手順
1. 接続とサーボの認識
- USB-シリアル変換アダプタでロボットアームの制御基板を接続し、サーボに電源を供給します。
- GUI を開き、トップバーのシリアルポートドロップダウンで対応するポートを選択します(
🔄をクリックして更新することもできます)。 - パネル上部に
🟢 已连接が表示され、ID 1–20 の範囲内のオンラインサーボ(通常は 1–6)が自動スキャンされます。
シリアルポートが使用中と表示される場合は、他のプログラム(シリアルモニター、終了していない前のツール)がそのポートを占有していないことを確認してください。
2. 中位キャリブレーション(現在位置を 2048 に設定)
キャリブレーションの前に、各関節が希望する「ゼロ位置 / 中位」になるように、ロボットアームの姿勢を物理的に合わせてください。
- パネルの シリアルX中位キャリブレーション ボタンをクリックします。
- プログラムはまずサーボのトルクをオフにし、サーボを希望する中位へ手動で調整するよう案内します。
- 確認後、プログラムは各サーボに対して次を実行します:EEPROM のロック解除 → キャリブレーションコマンドの書き込み(値 128 をアドレス 40 へ)→ EEPROM の再ロック。
- キャリブレーション後は「中位テスト」で検証できます。サーボがほぼ元の位置を保つ(変位が非常に小さい)場合は、キャリブレーション成功です。
3. 中位テスト
- シリアルX中位テスト をクリックします。
- プログラムはトルクを有効にし、すべてのサーボを 2048 へ移動します。
- サーボが現在位置からほとんど動かなければキャリブレーションは正確です。大きく動く場合は、そのキャリブレーション値が信頼できないため、再キャリブレーションが必要です。
4. モーターのトルクオフ(手動調整)
- シリアルXトルクオフ をクリックすると、そのポートのすべてのサーボのトルクがオフになり、自由に手動で回転できます。
- 個々のサーボは、単体サーボ制御 ページのスライダー下部にあるトルクスイッチで個別にオン/オフできます。
5. 単体サーボ制御(Tab2)
- 🎚️ 単体サーボ制御 ページでは、オンラインの各サーボに位置スライダーが 1 つとトルクスイッチが 1 つ対応します。
- スライダーをドラッグ → 離す と、サーボが目標位置へ移動します。
- スライダー下部のトルクスイッチで、そのサーボのトルクを個別にオン/オフできます。
6. FT デバッガー(パラメータの読み書きと位置制御)
🔬 FT デバッガー ページ:
- シリアル接続:ポート、ボーレート(デフォルト 1M)を選択し、接続後に サーボをスキャン でオンラインサーボを検出します。
- パラメータ読み出し:すべてのレジスタ(EEPROM + SRAM)を読み取ります。
- パラメータテーブル:5 列で全 56 個のレジスタを表示し、行をクリックすると「書き込みアドレス」が自動連動します。
- 位置制御:目標位置/速度を設定して実行します。移動完了後はトルクをオフにするよう案内が表示されます。
- ボーレートの変更、工場出荷リセット、xdat パラメータのバックアップ/復元は、以下の各節を参照してください。
7. サーボ ID の変更
- 🔬 FT デバッガー ページに入り、シリアルポートに接続してサーボをスキャンします。
- 対象のサーボを選択し、パラメータテーブルで「サーボ ID」(アドレス 0x05)の値を変更し、書き込みをクリックします。
- プログラムは次を実行します:ロック解除 → アドレス 5 への書き込み → 新しい ID の検証 → 再ロック。
⚠️ ID を変更する前に、バス上にこのサーボが 1 台だけであることを必ず確認し、ID の衝突を避けてください。
8. ボーレートの変更 / 工場出荷リセット
- ボーレートの変更:FT デバッガーページの「ボーレート / 工場出荷リセット」エリアで、新しいボーレート(38400 – 1000000 bps)を選択して変更します。書き込み後はシリアルポートのボーレートを自動で切り替えて ping で検証し、失敗時は自動的にロールバックします。
- 工場出荷リセット:サーボは工場出荷時のデフォルト(ID=1、ボーレート=1000000)に戻ります。その後は再スキャンが必要です。
9. xdat パラメータのバックアップと復元
FT デバッガーページの「xdat パラメータ(EEPROM のみ保存)」エリアで:
- 💾 現在のサーボを保存:現在選択中のサーボの EEPROM パラメータを xdat ファイルとして保存します(バックアップ)。
- サーボのパラメータを変更した後、元に戻したい場合:
- 📂 xdat を開く:バックアップファイルを読み込みます。
- 📤 パラメータをサーボへ復元:バックアップを現在のサーボの EEPROM へ書き戻します。
10. 2 ポート同期遠隔操作
⚠️ 方向の説明:シリアル1 が シリアル2 を制御します。シリアル1(マスター)はサーボ角度を読み取るだけで、シリアル2(スレーブ)が同期制御されます。
- トップバーで 🎮 遠隔操作 をクリックします(シリアル1 が角度を読み取り → シリアル2 が同じ ID のサーボを同期制御)。
- 2 つのポートのサーボ ID が一致している必要があり、共通部分のサーボのみが同期されます。
- 同じボタンをもう一度クリックすると停止し、その後、左右パネルのスキャンスレッドが自動的に再開します。
11. LeRobot キャリブレーション(コマンドライン)
# 校准从动臂(保存到 ~/.cache/huggingface/lerobot/calibration/robots/so_follower/)
python -m src.tools.lerobot_calibrate --arm-type follower
# 校准领导臂
python -m src.tools.lerobot_calibrate --arm-type leader流れ:サーボのトルクをオフ → 各関節を中位に合わせて homing_offset を記録 → ゆっくりと全可動範囲を動かして range_min/max を記録(wrist_roll は連続回転関節で、範囲は [0,4095] に固定)→ JSON を保存。
キャリブレーションファイルに従って中位へ移動:
python -m src.tools.run_calibration_middle <校准文件.json> --mode zeroLeRobot 環境のインストールとデータ収集の流れは LeRobot ロボットアームチュートリアルを参照してください。
コマンドラインツール
グラフィカルインターフェースのほか、以下のコマンドラインエントリも提供されています(GUI 不要):
# 扫描舵机
python -m src.tools.scan_id
# 舵机快速中位校准
python -m src.tools.servo_quick_calibration
# 舵机中位测试
python -m src.tools.servo_center_test
# 失能全部舵机
python -m src.tools.servo_disable
# LeRobot 风格校准
python -m src.tools.lerobot_calibrate
# LeRobot 风格校准(指定串口)
python -m src.tools.lerobot_calibrate /dev/ttyACM0
# 双端口同步遥控
python -m src.tools.servo_remote_control注意事項
- 安全第一:中位キャリブレーションは EEPROM に永続化されます。キャリブレーション前に、電源が安定していること、ロボットアームが人や物に衝突しないことを確認してください。
- 電源:SoARM 101 標準版は DC 5V 5A、Pro 版は DC 12V 5A を推奨します。電源が不足するとサーボの脱調や通信失敗の原因になります。
- シリアルポートの排他:Windows ではシリアルポートはプログラムによって排他されるため、同じポートを GUI のスキャンスレッドとキャリブレーションのサブプロセスが同時に使用することはできません。ツールは操作前にスキャンスレッドを停止し、古いプロセスを終了します。手動で繰り返しクリックしないでください。
- Linux のシリアルポート権限:
/dev/ttyUSB*//dev/ttyACM*にアクセスするには、ユーザーをdialoutグループに追加する必要があります(前述の「Linux」の節を参照)。 - macOS のシリアルポート命名:
/dev/tty.*(ブロッキング、スタックする可能性あり)ではなく/dev/cu.*(非ブロッキング)を使用してください(前述の「macOS」の節を参照)。 - ホットプラグ:USB を抜くとプログラムは自動再接続を試みます。差し戻した後は
🔄をクリックしてポートリストを更新してください。 - 過熱 / 過電圧保護:プログラムは電圧と温度を監視します(温度 > 60°C で警告)。サーボが高温状態を継続する場合は、停止して放熱してください。
- 中位キャリブレーションは不可逆:書き込み後は元のオフセットが上書きされ、元に戻せません。キャリブレーション前に元の位置を記録しておくことを推奨します。
- ID 変更のリスク:書き込み失敗や検証失敗の場合、プログラムはエラーを報告してスキャンを再開しますが、極端な場合にはサーボが「応答しなくなる」ことがあります。応答しなくなった場合は「工場出荷リセット」を試してください(リセット後は ID が 1 に戻ります)。
- エンコーディングの問題:Windows コンソールで emoji が文字化けする場合は、
PYTHONIOENCODING=utf-8を設定してからコマンドラインツールを実行してください。Linux / macOS はネイティブ UTF-8 のため通常この問題はありません。
トラブルシューティング
| 現象 | 考えられる原因 | 対処方法 |
|---|---|---|
| シリアルポートを開けない / ポートが使用中 | 他のプログラムが占有 | シリアルモニターなどのプログラムを閉じるか、ポートを変更してツールを再起動 |
| Windows でシリアルポートを開くと PermissionError が発生 | 他のプロセスがその COM ポートを占有 | その COM ポートを他のプロセスが占有していないことを確認 |
| サーボをスキャンできない | 電源不足 / 配線ミス / ボーレートの不一致 | 電源と配線を確認し、サーボが 1M ボーレートであることを確認 |
| 中位キャリブレーション後にサーボが乱れて動く | キャリブレーション前に姿勢を合わせていない | 「トルクオフ → 手動で位置合わせ → 中位キャリブレーション」を再実行 |
| 温度上昇が速すぎる | 負荷過大またはストール | 機構の引っかかりを確認し、速度/加速度を下げる |
| ID 変更後にサーボが見つからない | ID の衝突または書き込み失敗 | 工場出荷リセットし、再スキャン |
| 遠隔操作が同期しない | 2 つのポートの ID が不一致 | マスター/スレーブポートに同じ ID のサーボがオンラインであることを確認 |
| Windows でシリアルポートが見つからない | ドライバー不足 | デバイスマネージャーでドライバーを確認。USB ポートを変更。CH340 ドライバーをインストール |
| Linux でシリアルポートが見つからない | デバイスが認識されていない | ls /dev/ttyUSB* /dev/ttyACM*、lsusb でデバイスを確認 |
| Permission denied: /dev/ttyUSB0 | dialout グループに未加入 | sudo usermod -a -G dialout $USER を実行して再ログイン。または sudo chmod 666 /dev/ttyUSB0(一時的) |
| Linux でデバイス名が変化 | 挿抜順が ttyUSB 番号に影響 | udev ルールで固定(前述の「Linux」の節を参照)するか、起動のたびに選択 |
macOS で tty. 付きのシリアルポート名がスタックする | ブロッキング式のデバイス名を使用 | cu. プレフィックスのデバイスに変更 |
| macOS でデバイスが見つからない | デバイスが認識されていない | ls /dev/cu.*、挿抜し直し、system_profiler SPUSBDataType で確認 |
| macOS の権限問題 | システムのアクセス制御 | 通常は追加権限は不要。アクセス制御が表示された場合はターミナルのアクセスを許可 |
| 中国語インターフェースが空白 | 中国語フォント不足 | Linux では fonts-noto-cjk をインストール。macOS で異常がある場合は Noto Sans CJK をインストール |
| emoji が四角に表示される | emoji フォント不足 | fonts-noto-color-emoji をインストール |
| pip のインストールが失敗 | システム Python が保護されている(externally managed environment) | 仮想環境を使用。または pip install --break-system-packages -r requirements.txt |
| プログラムが起動しない | 依存関係の不足またはバージョン不一致 | python3 --version でバージョンを確認。pip list で依存関係を確認 |
| macOS で仮想環境のアクティベートが失敗 | 誤ったアクティベートスクリプトを使用 | source .venv/bin/activate に変更(.bat ではない) |
| macOS Apple Silicon でコンパイルエラー | Rosetta の古い Python を使用 | Python 3.10+ を使用(Apple Silicon にネイティブ対応) |
ディレクトリ構成
Juxi_ServoController/
├── docs/ # 分系统教程
│ ├── Windows教程.md
│ ├── Linux教程.md
│ └── macOS教程.md
├── src/
│ ├── gui/ # PySide6 图形界面
│ │ ├── factory_calibration_tool.py # 主工具(双串口标定 + 遥控 + 语言切换)
│ │ ├── ft_debugger.py # FT 调试器(参数读写 / xdat 备份)
│ │ ├── calibration_wizard.py # LeRobot 校准向导
│ │ ├── theme_utils.py # 浅色主题
│ │ └── language_dialog.py # 语言选择对话框
│ ├── tools/ # 命令行工具
│ ├── xdat_utils.py # xdat 参数文件读写
│ ├── i18n*.py / i18n_translations/ # 中英文国际化
│ ├── port_utils.py # 串口检测
│ └── calibration_manager.py# LeRobot 校准文件管理
├── scservo_sdk/ # FTServo 舵机通信 SDK
├── requirements.txt
└── setup.py # 环境检查脚本本ツールのリポジトリは src/gui(PySide6 グラフィカルインターフェース)、src/tools(コマンドラインツール)、scservo_sdk(FTServo サーボ通信 SDK)、setup.py(環境チェックスクリプト)などのモジュールで構成されています。

