SCS0009 サーボデバッグツール使用チュートリアル

ストアで購入

SCS0009 サーボデバッグツールは、Feetech バスサーボの中の SCS0009 サーボ(ポテンショメータフィードバック、10 ビット分解能 0–1023)専用に設計された FTServo デバッグツールです。グラフィカルインターフェース上で、シリアル接続、サーボスキャン、パラメータの読み書き、位置制御、ボーレート変更、工場出荷リセット、xdat パラメータのバックアップ/復元などの操作を完了できます。

本ツールは JUXI_Technology が開発・保守しており、MIT ライセンスで公開されています。FT デバッガー、xdat パラメータのバックアップ/復元、クロスプラットフォーム対応などの機能はすべて独自に実装されています。

互換性に関する注意

⚠️ 本ツールは現在 Feetech SCS0009 サーボ(SCS シリーズ、ポテンショメータ位置フィードバック、10 ビット分解能 0–1023)のみに対応しています。レジスタテーブル、xdat パラメータ形式、ボーレートテーブルはすべて Feetech SCS0009 向けに設計されており、他ブランド/型番のサーボの互換性は保証されません。

機能一覧

機能	説明
自動ポート検出	USB シリアルポートをスマート認識し、仮想デバイスを自動でフィルタリング
クロスプラットフォーム対応	Windows / Ubuntu / macOS 全プラットフォーム互換
中国語/英語切替	インターフェース内でワンクリックで中国語/英語を切替、選択内容は自動記憶
シリアル接続	手動/自動でシリアルポートを選択、8 段階のボーレート(38400~1M)
サーボスキャン	オンラインサーボを自動検出(ID 1–254)、リアルタイム表示
パラメータ読み取り	全 44 個のレジスタ(EEPROM + SRAM)を読み取り
パラメータ表	5 列表示(アドレス/レジスタ/値/記憶領域/読み書き)、点選で連動
位置制御	目標位置/速度制御、移動完了時にトルクオフを案内
ボーレート変更	サーボのボーレートを変更、失敗時は自動ロールバック
工場出荷リセット	ワンクリックで工場出荷時のデフォルト設定に復元
xdat パラメータ	現在のサーボ EEPROM パラメータを保存 / バックアップを開いて復元

画面構成

主プログラムはシングルパネルレイアウト(FT デバッガー)で、ウィンドウの高さが不足すると自動でスクロールバーが表示され、最大化時は自動で伸縮してフィットします:

┌─────────────────────────────────────────────────────────────┐
│  SCS0009 舵机调试工具                     [EN / English]     │  ← 顶栏
├─────────────────────────────────────────────────────────────┤
│  🔌 串口连接   [端口▾][🔄][波特率▾][连接] [🔴未连接]         │
│  🎯 舵机      [🔍扫描][舵机▾][读取参数][读取状态]            │
│               ┌ 扫描到的舵机列表 ┐                           │
│  📋 参数表    地址|寄存器|值|存储区域|读写  (44 个寄存器)      │
│  🎯 位置控制  目标位置|速度|移动|力矩开|力矩关 | 状态         │
│  🔧 波特率/恢复出厂  新波特率|修改波特率|恢复出厂            │
│  📁 xdat 参数(仅保存EEPROM) 保存当前舵机|打开xdat|恢复参数    │
│  📜 日志                                                      │
└─────────────────────────────────────────────────────────────┘

トップバー:アプリのタイトル、言語切替ボタン。
🔌 シリアル接続:ポート、ボーレートの選択、接続/切断。
🎯 サーボ:スキャン、サーボの選択、パラメータ/状態の読み取り。
📋 パラメータ表:44 個のレジスタを 5 列で表示(アドレス/レジスタ/値/記憶領域/読み書き)、点選で書き込みアドレスが自動連動。
🎯 位置制御:目標位置/速度、移動完了後にステータスバーでトルクオフを案内。
🔧 ボーレート/工場出荷リセット:ボーレート変更(失敗時ロールバック)、工場出荷リセット。
📁 xdat パラメータ(EEPROM のみ保存):現在のサーボパラメータの保存、バックアップを開く、復元。

インストールと起動

環境要件:

依存関係	バージョン	説明
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 が見つかりません)。インストールの確認:

bash

python --version

仮想環境を作成し、依存関係をインストールします:

bash

cd SCS0009_ServoController
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

⚠️ 仮想環境の作成は 1 回だけで十分です。python -m venv .venv を繰り返し実行すると元の環境がリセット/上書きされます(インストール済みの依存関係が消去されます)。以降は毎回 activate でアクティベートするだけで済みます。

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

環境を確認して起動します:

bash

python setup.py
python -m src.gui.factory_calibration_tool

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

デバイスマネージャー(Win+X → デバイスマネージャー)の「ポート (COM と LPT)」でシリアルポート番号を確認します:

端口 (COM 和 LPT)
  └─ USB-SERIAL CH340 (COM3)     ← 你的舵机串口

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

bash

python -m src.gui.factory_calibration_tool --port COM3

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

bash

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

Linux(Ubuntu / Debian)

中国語フォントと依存関係をインストールします(中国語フォントは中国語インターフェースの表示に必須で、emoji フォントはログの ✅⚠️ などのアイコンに使用されます):

bash

sudo apt install python3-venv fonts-noto-cjk fonts-noto-color-emoji

⚠️ シリアルポート権限(dialout グループ)の追加【必須】(Linux ではデフォルトで一般ユーザーが /dev/ttyUSB* / /dev/ttyACM* にアクセスできません):

bash

sudo usermod -a -G dialout $USER
# 注销并重新登录后生效

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

bash

groups

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

仮想環境を作成し、依存関係をインストールして起動します:

bash

cd SCS0009_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 回だけで十分です。python3 -m venv .venv を繰り返し実行すると元の環境が上書きされます(インストール済みの依存関係が消去されます)。以降は毎回 source .venv/bin/activate するだけで済みます。

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

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 --port /dev/ttyUSB0

オプション: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 が古いバージョンであることを避けるため):

bash

# 安装 Homebrew（如果没有）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Python
brew install python

確認:

bash

python3 --version

仮想環境を作成し、依存関係をインストールして起動します(source でアクティベートし、.bat ではありません):

bash

cd SCS0009_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 回だけで十分です。python3 -m venv .venv を繰り返し実行すると元の環境が上書きされます(インストール済みの依存関係が消去されます)。以降は毎回 source .venv/bin/activate するだけで済みます。

⚠️ シリアルポートの命名: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 --port /dev/cu.usbserial-0001

USB ドライバー:ほとんどの一般的なチップ(CH340、CP2102、FTDI)は macOS 標準のドライバーでプラグアンドプレイに対応しています。デバイスが認識されない場合:

bash

system_profiler SPUSBDataType | grep -A5 -i "serial\|CH340\|CP210"

CH340:古いロットは WCH 公式ドライバーのインストールが必要です。
通常は ls /dev/cu.* でデバイスが見えれば問題ありません。

使用上のヒント:
- シリアルポート名は変わります:USB ポートを変えて挿抜すると cu.* 名が変化することがあります。起動のたびに「🔌 シリアル接続」エリアで選択してください。
- 省電力:macOS がスリープするとシリアルポートが切断されることがあります。操作中はスリープを解除するか、スリープ時間を長めに設定してください。
- プライバシー権限:初回実行時に「リムーバブルディスクへのアクセス」が表示されたら、許可をクリックしてください。

使用手順

1. 接続とサーボの認識

USB-シリアル変換アダプタでサーボ制御基板を接続し、サーボに電源を供給します。
GUI を開き、「🔌 シリアル接続」エリアでポートを選択し(または 🔄 をクリックして更新)、ボーレートを設定します(デフォルト 1M)。
接続をクリックすると、状態に 🟢 已连接 が表示されます。

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

2. サーボのスキャン

🔍 サーボをスキャン をクリックし、ID 1–254 の範囲内のオンラインサーボを検出します。
スキャン結果はサーボリストにリアルタイム表示されます(型番付き)。
サーボリストの行をクリックすると、「サーボ」ドロップダウンに自動入力されます。

3. パラメータの読み取り

サーボを選択した後、📖 パラメータを読み取り をクリックすると、全 44 個のレジスタを 1 つずつ読み取ります。
パラメータ表は 5 列で表示され(アドレス/レジスタ/値/記憶領域/読み書き)、EPROM / SRAM / DEFAULT を色分けします。
ログエリアには各レジスタの読み取り結果と失敗原因が表示されます。

各レジスタの意味はポテンショメータ SCSCL サーボ - メモリテーブル解析を参照してください。

4. パラメータの変更 / 書き込み

パラメータ表で変更したいレジスタの行をクリック → 「書き込みアドレス」「長さ」「値」が自動連動します。
「値」入力欄で新しい値を変更し、✏️ 書き込み をクリックします。
プログラムの実行:EEPROM のロック解除 → 書き込み → 再ロック。
書き込み結果のダイアログ:成功時は緑色で「✅ 書き込みに成功しました」、失敗時は赤色で「❌ 書き込みに失敗しました」(原因付き)が表示されます。

5. サーボ ID の変更

パラメータ表で「サーボ ID」(アドレス 0x05)の行を見つけ、クリックして選択します。
「値」を新しい ID に変更し、✏️ 書き込み をクリックします。
プログラムの実行:ロック解除 → アドレス 5 への書き込み → 再ロック。

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

6. 位置制御

「🎯 位置制御」エリアで、スライダーをドラッグして目標位置を調整します(0–1023、ポテンショメータ 10 ビット分解能)。数値ボックスにも同期表示され、数値ボックスに直接入力することもでき、スライダーが同期して追従します。
▶ 移動 をクリックするとサーボが移動を開始し、ステータスバーに「移動中...」と表示されます。
移動完了後に「✅ 移動が完了しました。トルクをオフにしてください」と表示されたら、⏹ トルクオフ をクリックします。

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

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

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

「📁 xdat パラメータ(EEPROM のみ保存)」エリアで:

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

注意事項

安全第一:パラメータの書き込みは EEPROM に永続化されます。書き込み前に、電源が安定していること、ロボットアームが人や物に衝突しないことを確認してください。
電源:SoARM 101 標準版は DC 5V 5A、Pro 版は DC 12V 5A を推奨します。電源が不足するとサーボの脱調や通信失敗の原因になります。
シリアルポートの排他:Windows ではシリアルポートはプログラムによって排他されるため、同じポートを 2 つのプログラムが同時に使用することはできません。他のプログラム(シリアルモニター)が同じポートを開いている間は本ツールを使用しないでください。
Linux のシリアルポート権限:/dev/ttyUSB* / /dev/ttyACM* にアクセスするには、ユーザーを dialout グループに追加する必要があります(前述の「Linux」の節を参照)。
macOS のシリアルポート命名:/dev/tty.*(ブロッキング、スタックする可能性あり)ではなく /dev/cu.*(非ブロッキング)を使用してください(前述の「macOS」の節を参照)。
ホットプラグ:USB を抜くとプログラムは自動再接続を試みます。差し戻した後は 🔄 をクリックしてポートリストを更新してください。
過熱 / 過電圧保護:プログラムは電圧と温度を監視します(温度 > 60°C で警告)。サーボが高温状態を継続する場合は、停止して放熱してください。
パラメータの書き込みは不可逆:EEPROM への書き込み後は元の値が上書きされ、取り消すことができません。変更前に「xdat 現在のサーボを保存」でバックアップすることを推奨します。
ID 変更のリスク:書き込み失敗や検証失敗の場合はプログラムがエラーを報告しますが、極端な場合にはサーボが「応答しない」状態になることがあります。応答しない場合は「工場出荷リセット」を試してください(リセット後は ID が 1 に戻ります)。
エンコーディングの問題:Windows コンソールで emoji が文字化けする場合は、PYTHONIOENCODING=utf-8 を設定してからコマンドラインツールを実行してください。Linux / macOS はネイティブ UTF-8 のため通常この問題はありません。

トラブルシューティング

現象	考えられる原因	対処方法
シリアルポートを開けない / ポートが使用中	他のプログラムが占有	シリアルモニターなどのプログラムを閉じるか、ポートを変更してツールを再起動
Windows でシリアルポートを開くと PermissionError が発生	他のプロセスがその COM ポートを占有	その COM ポートを他のプロセスが占有していないことを確認
サーボをスキャンできない	電源不足 / 配線ミス / ボーレートの不一致	電源と配線を確認し、サーボが 1M ボーレートであることを確認
パラメータの読み取りに失敗	シリアルポートが使用中 / サーボが応答しない	他のプログラムを閉じる。再接続する。アドレスが正しいか確認
書き込みに失敗	サーボの電源不足、または対象レジスタが書き込み不可	サーボの電源と接続を確認し、対象レジスタが書き込み可能か確認
温度上昇が速すぎる	負荷過大またはストール	機構の引っかかりを確認し、速度/加速度を下げる
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 にネイティブ対応)

ディレクトリ構成

SCS0009_ServoController/
├── docs/                    # 分系统教程（中英文）
│   ├── zh/                  # 中文教程
│   │   ├── Windows教程.md
│   │   ├── Linux教程.md
│   │   └── macOS教程.md
│   └── en/                  # 英文教程
│       ├── Windows.md
│       ├── Linux.md
│       └── macOS.md
├── src/
│   ├── gui/                  # PySide6 图形界面
│   │   ├── factory_calibration_tool.py   # 主窗口（FT 调试器 + 语言切换）
│   │   ├── ft_debugger.py                # FT 调试器面板（参数读写 / xdat 备份）
│   │   ├── theme_utils.py                # 浅色主题
│   │   └── language_dialog.py            # 语言选择对话框
│   ├── xdat_utils.py         # xdat 参数文件读写
│   ├── i18n*.py / i18n_translations/     # 中英文国际化
│   └── port_utils.py         # 串口检测
├── scservo_sdk/              # FTServo 舵机通信 SDK
├── requirements.txt
└── setup.py                  # 环境检查脚本

本ツールのリポジトリは src/gui(PySide6 グラフィカルインターフェースと FT デバッガー)、scservo_sdk(FTServo サーボ通信 SDK)、setup.py(環境チェックスクリプト)などのモジュールで構成されています。

マルチボード例

I2C 通信

シリアル通信

ROS サンプル

AI ビジョンチュートリアル(全 11 章)

SCS0009 サーボデバッグツール使用チュートリアル

互換性に関する注意

機能一覧

画面構成

インストールと起動

Windows

Linux(Ubuntu / Debian)

macOS

使用手順

1. 接続とサーボの認識

2. サーボのスキャン

3. パラメータの読み取り

4. パラメータの変更 / 書き込み

5. サーボ ID の変更

6. 位置制御

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

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

注意事項

トラブルシューティング

ディレクトリ構成

I2C 通信

シリアル通信

SCS0009 サーボデバッグツール使用チュートリアル ​

互換性に関する注意 ​

機能一覧 ​

画面構成 ​

インストールと起動 ​

Windows ​

Linux(Ubuntu / Debian) ​

macOS ​

使用手順 ​

1. 接続とサーボの認識 ​

2. サーボのスキャン ​

3. パラメータの読み取り ​

4. パラメータの変更 / 書き込み ​

5. サーボ ID の変更 ​

6. 位置制御 ​

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

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

注意事項 ​

トラブルシューティング ​

ディレクトリ構成 ​

関連製品

SCS0009 サーボデバッグツール使用チュートリアル

互換性に関する注意

機能一覧

画面構成

インストールと起動

Windows

Linux(Ubuntu / Debian)

macOS

使用手順

1. 接続とサーボの認識

2. サーボのスキャン

3. パラメータの読み取り

4. パラメータの変更 / 書き込み

5. サーボ ID の変更

6. 位置制御

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

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

注意事項

トラブルシューティング

ディレクトリ構成