🧪 新しいチュートリアルを公開中 — ロボットアームからセンサーまで
コンテンツへスキップ
この製品を購入公式ストア公式サイト

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.83.10+ を推奨。python.org からダウンロード
PySide6>= 6.0GUI フレームワーク
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

  1. Python 3.10+ をインストールします(インストール時に必ず Add Python to PATH をチェックしてください。チェックしないとコマンドラインで python が見つかりません)。インストールの確認:
bash
python --version
  1. 仮想環境を作成し、依存関係をインストールします:
bash
cd Juxi_ServoController
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

ヒント:アクティベート後、コマンドラインの先頭に (.venv) が表示されます。

  1. 環境を確認して起動します:
bash
python setup.py
python -m src.gui.factory_calibration_tool

[OK] 环境检查通过,可以运行项目 と表示されれば、環境が正しいことが確認できます。

  1. デバイスマネージャー(Win+X → デバイスマネージャー)の「ポート (COM と LPT)」でシリアルポート番号を確認します:
端口 (COM 和 LPT)
  └─ USB-SERIAL CH340 (COM3)     ← 你的舵机串口

COM 番号を控えてください。起動後にトップバーで選択します。手動でポートを指定することもできます(シリアルポートが使用中の場合):

bash
python -m src.gui.factory_calibration_tool --port1 COM3 --port2 COM4

使用可能なポートを確認:

bash
python -m src.gui.factory_calibration_tool --list-ports

Linux(Ubuntu / Debian)

  1. 中国語フォントと依存関係をインストールします(中国語フォントは中国語インターフェースの表示に必須で、emoji フォントはログの ✅⚠️ などのアイコンに使用されます):
bash
sudo apt install python3-venv fonts-noto-cjk fonts-noto-color-emoji
  1. ⚠️ シリアルポート権限(dialout グループ)の追加【必須】(Linux ではデフォルトで一般ユーザーが /dev/ttyUSB* / /dev/ttyACM* にアクセスできません):
bash
sudo usermod -a -G dialout $USER
# 注销并重新登录后生效

確認(出力に dialout が含まれている必要があります):

bash
groups

有効にならない場合:パソコンを再起動してください。一部のディストリビューションではグループ名が uucp(Arch)や tty です。

  1. 仮想環境を作成し、依存関係をインストールして起動します:
bash
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

pip が externally managed environment エラーを報告する場合は、pip install --break-system-packages -r requirements.txt に変更するか、仮想環境を使用してください。

  1. USB-シリアル変換デバイスを確認します(アダプタを挿入後):
bash
ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null

典型的な出力:

/dev/ttyUSB0   # CH340 / CP2102 / PL2303
/dev/ttyACM0   # 原生 USB 串口(Arduino / ESP32 板载)

詳細な製造元情報を確認:

bash
dmesg | tail -20 | grep -i tty
# 或
lsusb

複数のデバイスがある場合、挿抜順に ttyUSB0 / ttyUSB1 が割り当てられ、不安定になることがあります。/dev/ttyACM* を使用するか、製造元別に固定することを推奨します(後述の udev の節を参照)。

手動でポートを指定:

bash
python -m src.gui.factory_calibration_tool --port1 /dev/ttyUSB0 --port2 /dev/ttyUSB1

シリアルポートが 1 つだけの場合、ツールは 2 番目のポートを自動的に「無効」に設定します。

  1. オプション: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

  1. Homebrew で Python をインストールします(システム標準の Python が古いバージョンであることを避けるため):
bash
# 安装 Homebrew(如果没有)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Python
brew install python

確認:

bash
python3 --version
  1. 仮想環境を作成し、依存関係をインストールして起動します(source でアクティベートし、.bat ではありません):
bash
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
  1. ⚠️ シリアルポートの命名:macOS は USB-シリアル変換デバイスを /dev 配下に置き、2 通りの命名があります:
プレフィックス意味使用可否
/dev/tty.usbserial-*モデムスタイル(ブロッキング式)スタックする可能性あり、非推奨
/dev/cu.usbserial-*コール/ターミナルスタイル(非ブロッキング)✅ 推奨使用

自分のシリアルポート名を確認:

bash
ls /dev/cu.*

典型的な出力:

/dev/cu.usbserial-0001      # CP2102 / FTDI
/dev/cu.usbmodem141101      # 板载 USB 串口(Arduino / ESP32)
/dev/cu.wchusbserial1420    # CH340

プログラムは cu.* デバイスを自動的に優先選択します。手動でポートを指定する場合は tty. ではなく cu. を使用してください。

手動でポートを指定:

bash
python -m src.gui.factory_calibration_tool --port1 /dev/cu.usbserial-0001 --port2 /dev/cu.usbmodem141101
  1. USB ドライバー:ほとんどの一般的なチップ(CH340、CP2102、FTDI)は macOS 標準のドライバーでプラグアンドプレイに対応しています。デバイスが認識されない場合:
bash
system_profiler SPUSBDataType | grep -A5 -i "serial\|CH340\|CP210"
  • CH340:古いロットは WCH 公式ドライバーのインストールが必要です。
  • 通常は ls /dev/cu.* でデバイスが見えれば問題ありません。
  1. 使用上のヒント:
    • シリアルポート名は変わります:USB ポートを変えて挿抜すると cu.* 名が変わることがあります。起動のたびにトップバーのドロップダウンで選択してください。
    • 省電力:macOS がスリープするとシリアルポートが切断されることがあります。操作中はスリープを解除するか、スリープ時間を長めに設定してください。
    • プライバシー権限:初回実行時に「リムーバブルディスクへのアクセス」を求められたら、許可をクリックしてください。

使用手順

1. 接続とサーボの認識

  1. USB-シリアル変換アダプタでロボットアームの制御基板を接続し、サーボに電源を供給します。
  2. GUI を開き、トップバーのシリアルポートドロップダウンで対応するポートを選択します(🔄 をクリックして更新することもできます)。
  3. パネル上部に 🟢 已连接 が表示され、ID 1–20 の範囲内のオンラインサーボ(通常は 1–6)が自動スキャンされます。

シリアルポートが使用中と表示される場合は、他のプログラム(シリアルモニター、終了していない前のツール)がそのポートを占有していないことを確認してください。

2. 中位キャリブレーション(現在位置を 2048 に設定)

キャリブレーションの前に、各関節が希望する「ゼロ位置 / 中位」になるように、ロボットアームの姿勢を物理的に合わせてください。

  1. パネルの シリアルX中位キャリブレーション ボタンをクリックします。
  2. プログラムはまずサーボのトルクをオフにし、サーボを希望する中位へ手動で調整するよう案内します。
  3. 確認後、プログラムは各サーボに対して次を実行します:EEPROM のロック解除 → キャリブレーションコマンドの書き込み(値 128 をアドレス 40 へ)→ EEPROM の再ロック。
  4. キャリブレーション後は「中位テスト」で検証できます。サーボがほぼ元の位置を保つ(変位が非常に小さい)場合は、キャリブレーション成功です。

3. 中位テスト

  1. シリアルX中位テスト をクリックします。
  2. プログラムはトルクを有効にし、すべてのサーボを 2048 へ移動します。
  3. サーボが現在位置からほとんど動かなければキャリブレーションは正確です。大きく動く場合は、そのキャリブレーション値が信頼できないため、再キャリブレーションが必要です。

4. モーターのトルクオフ(手動調整)

  • シリアルXトルクオフ をクリックすると、そのポートのすべてのサーボのトルクがオフになり、自由に手動で回転できます。
  • 個々のサーボは、単体サーボ制御 ページのスライダー下部にあるトルクスイッチで個別にオン/オフできます。

5. 単体サーボ制御(Tab2)

  1. 🎚️ 単体サーボ制御 ページでは、オンラインの各サーボに位置スライダーが 1 つとトルクスイッチが 1 つ対応します。
  2. スライダーをドラッグ → 離す と、サーボが目標位置へ移動します。
  3. スライダー下部のトルクスイッチで、そのサーボのトルクを個別にオン/オフできます。

6. FT デバッガー(パラメータの読み書きと位置制御)

🔬 FT デバッガー ページ:

  1. シリアル接続:ポート、ボーレート(デフォルト 1M)を選択し、接続後に サーボをスキャン でオンラインサーボを検出します。
  2. パラメータ読み出し:すべてのレジスタ(EEPROM + SRAM)を読み取ります。
  3. パラメータテーブル:5 列で全 56 個のレジスタを表示し、行をクリックすると「書き込みアドレス」が自動連動します。
  4. 位置制御:目標位置/速度を設定して実行します。移動完了後はトルクをオフにするよう案内が表示されます。
  5. ボーレートの変更、工場出荷リセット、xdat パラメータのバックアップ/復元は、以下の各節を参照してください。

7. サーボ ID の変更

  1. 🔬 FT デバッガー ページに入り、シリアルポートに接続してサーボをスキャンします。
  2. 対象のサーボを選択し、パラメータテーブルで「サーボ ID」(アドレス 0x05)の値を変更し、書き込みをクリックします。
  3. プログラムは次を実行します:ロック解除 → アドレス 5 への書き込み → 新しい ID の検証 → 再ロック。

⚠️ ID を変更する前に、バス上にこのサーボが 1 台だけであることを必ず確認し、ID の衝突を避けてください。

8. ボーレートの変更 / 工場出荷リセット

  • ボーレートの変更:FT デバッガーページの「ボーレート / 工場出荷リセット」エリアで、新しいボーレート(38400 – 1000000 bps)を選択して変更します。書き込み後はシリアルポートのボーレートを自動で切り替えて ping で検証し、失敗時は自動的にロールバックします。
  • 工場出荷リセット:サーボは工場出荷時のデフォルト(ID=1、ボーレート=1000000)に戻ります。その後は再スキャンが必要です。

9. xdat パラメータのバックアップと復元

FT デバッガーページの「xdat パラメータ(EEPROM のみ保存)」エリアで:

  1. 💾 現在のサーボを保存:現在選択中のサーボの EEPROM パラメータを xdat ファイルとして保存します(バックアップ)。
  2. サーボのパラメータを変更した後、元に戻したい場合:
  3. 📂 xdat を開く:バックアップファイルを読み込みます。
  4. 📤 パラメータをサーボへ復元:バックアップを現在のサーボの EEPROM へ書き戻します。

10. 2 ポート同期遠隔操作

⚠️ 方向の説明:シリアル1 が シリアル2 を制御します。シリアル1(マスター)はサーボ角度を読み取るだけで、シリアル2(スレーブ)が同期制御されます。

  1. トップバーで 🎮 遠隔操作 をクリックします(シリアル1 が角度を読み取り → シリアル2 が同じ ID のサーボを同期制御)。
  2. 2 つのポートのサーボ ID が一致している必要があり、共通部分のサーボのみが同期されます。
  3. 同じボタンをもう一度クリックすると停止し、その後、左右パネルのスキャンスレッドが自動的に再開します。

11. LeRobot キャリブレーション(コマンドライン)

bash
# 校准从动臂(保存到 ~/.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 を保存。

キャリブレーションファイルに従って中位へ移動:

bash
python -m src.tools.run_calibration_middle <校准文件.json> --mode zero

LeRobot 環境のインストールとデータ収集の流れは LeRobot ロボットアームチュートリアルを参照してください。

コマンドラインツール

グラフィカルインターフェースのほか、以下のコマンドラインエントリも提供されています(GUI 不要):

bash
# 扫描舵机
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

注意事項

  1. 安全第一:中位キャリブレーションは EEPROM に永続化されます。キャリブレーション前に、電源が安定していること、ロボットアームが人や物に衝突しないことを確認してください。
  2. 電源:SoARM 101 標準版は DC 5V 5A、Pro 版は DC 12V 5A を推奨します。電源が不足するとサーボの脱調や通信失敗の原因になります。
  3. シリアルポートの排他:Windows ではシリアルポートはプログラムによって排他されるため、同じポートを GUI のスキャンスレッドとキャリブレーションのサブプロセスが同時に使用することはできません。ツールは操作前にスキャンスレッドを停止し、古いプロセスを終了します。手動で繰り返しクリックしないでください。
  4. Linux のシリアルポート権限:/dev/ttyUSB* / /dev/ttyACM* にアクセスするには、ユーザーを dialout グループに追加する必要があります(前述の「Linux」の節を参照)。
  5. macOS のシリアルポート命名:/dev/tty.*(ブロッキング、スタックする可能性あり)ではなく /dev/cu.*(非ブロッキング)を使用してください(前述の「macOS」の節を参照)。
  6. ホットプラグ:USB を抜くとプログラムは自動再接続を試みます。差し戻した後は 🔄 をクリックしてポートリストを更新してください。
  7. 過熱 / 過電圧保護:プログラムは電圧と温度を監視します(温度 > 60°C で警告)。サーボが高温状態を継続する場合は、停止して放熱してください。
  8. 中位キャリブレーションは不可逆:書き込み後は元のオフセットが上書きされ、元に戻せません。キャリブレーション前に元の位置を記録しておくことを推奨します。
  9. ID 変更のリスク:書き込み失敗や検証失敗の場合、プログラムはエラーを報告してスキャンを再開しますが、極端な場合にはサーボが「応答しなくなる」ことがあります。応答しなくなった場合は「工場出荷リセット」を試してください(リセット後は ID が 1 に戻ります)。
  10. エンコーディングの問題: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/ttyUSB0dialout グループに未加入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(環境チェックスクリプト)などのモジュールで構成されています。