作るものと必要なもの
LeRobot は Hugging Face のオープンソースのロボティクスライブラリです。同じ一連のコマンドで、ロボットの操作、デモンストレーションの記録、ポリシーの学習、そのポリシーの実行ができます。SO-101 はそのフラッグシップのアームです。リーダーアームを手で動かすとフォロワーアームがそれをなぞり、記録された動きとカメラ画像から、ニューラルネットワークが作業を自力で繰り返せるように学習します。
作業は 7 段階です。部品の調達とソフトウェアのインストール、各モーターへの ID の割り当て、両アームの組み立て、キャリブレーション、カメラを使った遠隔操作、データセットの記録、そしてポリシーの学習と実行です。最後の製作セクションでは LeKiwi モバイルベースを追加し、そのあとにトラブルシューティングのチェックリストが続きます。
横にスクロールすると図の全体を見られます。
必要なものは次のとおりです。アーム 2 台(部品は次のセクションを参照)、各アーム用の USB バスサーボ制御ボードと電源、Python 3.12 以降が動くコンピューター、USB カメラ 2 台(このガイドのコマンドは 2 台を使います)、データセットとチェックポイント用の無料の Hugging Face アカウント、学習用の GPU。ここで使う ACT ポリシーならノート PC クラスの GPU で足り、レンタルの GPU でも構いません。
本ガイドは公式ドキュメントとコミュニティの製作報告をもとにまとめたもので、当社ではすべての手順をすべてのハードウェアリビジョンで実機検証したわけではありません。control_robot.py を呼び出す古いチュートリアルは、lerobot-* コマンドを使う 0.7.0 には当てはまりません。
部品、印刷、電源
SO-101 プロジェクトは部品表(BOM)と印刷用ファイルを公開しており、Hugging Face の SO-101 ページから両方にたどり着けます。リーダーとフォロワーを 1 組そろえるには、Feetech STS3215 サーボ 12 個、制御ボード 2 枚、電源 2 台、USB-C ケーブル 2 本、テーブル用クランプが必要です。組み立てには M2×6 と M3×6 のねじを使いますが、プロジェクトの部品表には載っていないため、サーボやキットに付属しているものを確認してください。印刷済みの部品や完成キットも販売されています。
フォロワーは 1/345 のギア比のサーボを 6 個使います。リーダーは 3 種類の異なるギア比を使うので、自重を支えながら小さな力で動かせます。
電源はサーボに合わせて選びます。7.4 V の STS3215 は 6 V でのストールトルクが 16.5 kg·cm(5 V の電源ではわずかに小さくなります)で、通常は 5 V の電源で動かします。フォロワーにはより強力な 12 V サーボ(30 kg·cm)も使えますが、その場合は 5 A 以上の定格の 12 V 電源が必要です。リーダーは常に 7.4 V のサーボを使います。7.4 V のサーボをつないだボードには、決して 12 V の電源をつながないでください。各電源には、その電圧と対応するアームを書いて目印を付けてください。
横にスクロールすると図の全体を見られます。
印刷は PLA+ で、0.4 mm ノズルなら積層 0.2 mm(0.6 mm ノズルなら積層 0.4 mm)、充填率 15% にします。各アームの部品は、サポートが少なくて済む向きに配置された 1 つのファイルにまとまっています。水平のねじ穴にはサポートを入れないでください。最初に Gauge Zero と Gauge Tight のテストピースを印刷してサーボに当てて確認し、Gauge Zero がプロジェクトの動画のようにはまらない場合は、プリンターの設定を調整して印刷し直してから、アームを印刷してください。
プラスドライバーの #0 と #1 を用意し、テストの前に各ベースをテーブルにクランプで固定してください。この製作用に当社が扱っている部品は、下にリンクがあります。
横にスクロールしてすべての列を比較できます。
| 関節 | モーター ID | リーダーのギア比 | フォロワーのギア比 |
|---|---|---|---|
| ショルダーパン | 1 | 1/191 | 1/345 |
| ショルダーリフト | 2 | 1/345 | 1/345 |
| エルボーフレックス | 3 | 1/191 | 1/345 |
| リストフレックス | 4 | 1/147 | 1/345 |
| リストロール | 5 | 1/147 | 1/345 |
| グリッパー | 6 | 1/147 | 1/345 |
LeRobot とモーターサポートのインストール
LeRobot 0.7.0 には Python 3.12 以降が必要です。conda(miniforge 経由)または uv で独立した環境を作り、新しいターミナルを開くたびに有効化します。動画の処理には、ほとんどのプラットフォームで ffmpeg が必要です(Intel 版 macOS と 32 ビット ARM の Linux では、LeRobot が PyAV に切り替わるので省略できます)。conda のパッケージはどの PyTorch バージョンでも動作します。
conda create -y -n lerobot python=3.12
conda activate lerobot
conda install ffmpeg -c conda-forgePyPI から、必要な extras を指定して LeRobot をインストールします。core_scripts は記録・再生・キャリブレーションで使うものを、feetech は STS3215 サーボのサポートを、training は学習用のツールを追加します。
pip install 'lerobot[core_scripts,feetech]'
pip install 'lerobot[training]'プラットフォームごとの注意:Apple silicon では、PyTorch に macOS 14 以降が必要で、GPU(MPS)アクセラレーションには macOS 15 以降が必要です。Linux で NVIDIA GPU を使うには、既定の PyTorch ビルドにドライバー 580.65 以降が必要です。それより古いドライバーの場合は、先に対応する CUDA ビルドの PyTorch をインストールし、torchcodec は CPU 用のインデックスから取得してください(Hugging Face のインストールのページを参照)。WSL 内では evdev もインストールします(conda install evdev -c conda-forge、uv の場合は sudo apt install libevdev-dev のあとに uv pip install evdev)。PyTorch 2.10 以降なら、conda 版の代わりにシステムの ffmpeg を使えます。
ポートの確認とモーター ID の設定
新品の STS3215 サーボは通常 ID 1 で出荷されており、コントローラーとすべてのサーボが同じボーレートを共有する必要があります。LeRobot は両方を各サーボのメモリに一度だけ書き込むので、組み立ての前に、サーボを 1 個ずつ接続して行ってください。別のロボットから流用したサーボにも、おそらく必要です。
横にスクロールすると図の全体を見られます。
制御ボードを USB でコンピューターに接続して電源を入れ、ポート検出ツールを実行します。指示されたら、そのボードの USB ケーブルだけを抜いて Enter を押すと、スクリプトがポートを表示します。Linux では /dev/ttyACM0、macOS では /dev/tty.usbmodem…、Windows では COM3 のような名前です。ケーブルを挿し直してから、もう一方のボードでも同じ手順を繰り返します。Linux では、各ポートに sudo chmod 666 を実行してアクセスを許可する必要がある場合があります(例:/dev/ttyACM0 と /dev/ttyACM1)。
lerobot-find-portフォロワー、次にリーダーの順にセットアップスクリプトを実行します。それぞれ専用のポートを指定します。スクリプトは 1 回に 1 個ずつモーターを指定するので、実行する前に下の手順を読んでおいてください。
lerobot-setup-motors \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0リーダーでは、ロボット用のオプションではなく、遠隔操作用デバイスのオプションを使います。各プロンプトでは、部品のセクションの表でその関節に記載されているギア比のモーターを手に取ってください(リーダーでは、ショルダーパンとエルボーフレックスが 1/191、ショルダーリフトが 1/345、リストフレックス、リストロール、グリッパーが 1/147)。スクリプトがモーターの設定完了を報告したら、すぐにそのモーターに ID を書いて印を付けてください。
lerobot-setup-motors \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1- スクリプトは 1 回に 1 個ずつモーターを指定し、グリッパー(ID 6)から始めてショルダーパン(ID 1)で終わります。指定されたモーターだけを制御ボードに接続してください。ほかのモーターにチェーン接続してはいけません。
- Enter を押します。ID を設定したとスクリプトが報告したら、そのモーターのケーブルをボードから抜き、次に指定されたモーターを接続して、もう一度 Enter を押します。
- Enter を押す前に、電源、USB、3 ピンケーブルを確認します。スクリプトがエラーを報告した場合は、まずこれらのケーブルを確認してください。また、Waveshare ボードでは、2 つのジャンパーを両方ともチャンネル B(USB)に合わせる必要があります。
- スクリプトが終了したら、モーターを順番にチェーン接続し、ショルダーパンのモーター(ID 1)を制御ボードに接続します。
横にスクロールすると図の全体を見られます。
モーター ID をサーボ 1 個ずつ設定し、そのあと順番にチェーン接続する
リーダーアームとフォロワーアームの組み立て
両方のアームは印刷部品の大半を共有し、同じ順序で組み立てます(手首のロール用の部品は異なり、フォロワーに可動するジョーがある箇所は、リーダーではハンドルとトリガーになります)。ベースと肩、上腕、前腕、手首、そしてフォロワーではグリッパー、リーダーではハンドルとトリガーです。Hugging Face は SO-101 のページで関節ごとに短い動画を公開しているので、このメモと並べて参照してください。まず印刷した部品のサポート材をすべて取り除き、サーボを組み込んで閉じる前に、すべてのサーボに 3 ピンケーブルを差し込んでおきます。
- 関節 1(ショルダーパン):モーターに両方のホーンを取り付け、上側のホーンを M3×6 ねじ 1 本で固定します(下側のホーンにはねじは不要です)。モーターを M2×6 ねじ 4 本でベースに取り付け、最初のモーターホルダーを M2×6 ねじ 2 本でスライドさせて取り付けます。肩を上側に M3×6 ねじ 4 本、下側に 4 本で取り付け、肩のモーターホルダーを追加します。
- 関節 2(ショルダーリフト):両方のホーンを取り付けて上側のホーンを M3×6 ねじ 1 本で固定し(下側のホーンにはねじは不要です)、モーターを上からスライドさせて入れ、M2×6 ねじ 4 本で固定します。次に上腕を左右それぞれ M3×6 ねじ 4 本で取り付けます。
- 関節 3(エルボー):両方のホーンを取り付けて上側のホーンを M3×6 ねじ 1 本で固定し(下側のホーンにはねじは不要です)、モーター 3 を M2×6 ねじ 4 本で挿入して固定し、前腕を左右それぞれ M3×6 ねじ 4 本でそれに接続します。
- 関節 4(リストフレックス):両方のホーンを取り付けて上側のホーンを M3×6 ねじ 1 本で固定し(下側のホーンにはねじは不要です)、モーターホルダー 4 をかぶせ、モーター 4 をスライドさせて入れて M2×6 ねじ 4 本で固定します。
- 関節 5(リストロール):モーター 5 を手首のホルダーに、前面の M2×6 ねじ 2 本で取り付け、ホーンを 1 つだけ M3×6 ねじ 1 本で取り付けます。手首はモーター 4 に、公式の関節 5 の動画に示されているとおりに M3×6 ねじで固定します(テキストの手順書では左右それぞれ 4 本とされています)。
- フォロワーのグリッパー:グリッパーを手首のモーターのホーンに M3×6 ねじ 4 本で取り付け、グリッパーのモーターを左右それぞれ M2×6 ねじ 2 本で取り付け、両方のホーンを取り付けて上側のホーンを M3×6 ねじ 1 本で固定し(下側のホーンにはねじは不要です)、爪は公式のグリッパー動画に示されているとおりに M3×6 ねじで固定します(テキストの手順書では左右それぞれ 4 本とされています)。
- リーダーのハンドル:リーダーホルダーを手首に M3×6 ねじ 4 本で取り付け、ハンドルを M2×6 ねじ 1 本でそこに固定します。モーター 6(トリガーのモーターで、公式ガイドではグリッパーモーターと呼ばれています)を左右それぞれ M2×6 ねじ 2 本で取り付け、ホーンを M3×6 ねじ 1 本で固定し、続いてトリガーを M3×6 ねじ 4 本で取り付けます。
- 電源を入れる前に、各関節を手でゆっくり可動範囲いっぱいに動かし、止まる位置を越えて無理に動かさないでください。こすれずに動くはずです。モーターを組み込んで閉じる前に、各モーターに ID を書いて印を付け、両方のベースをテーブルにクランプで固定します。
両方のアームのキャリブレーション
キャリブレーションは各関節の可動範囲を記録し、同じ物理的な姿勢でリーダーとフォロワーが同じ値を報告するようにします。また、あるロボットで学習したポリシーを別のロボットで動かせるようにもなります。アームごとに 1 回行い、ハードウェアを変更したときや LeRobot がキャリブレーションの欠落を報告したときにもう一度行います。再キャリブレーションより前に作成した記録とポリシーは、古いキャリブレーションに基づいています。
最初にフォロワーをキャリブレーションします。スクリプトの指示に従い、まずすべての関節を可動範囲の中央に動かして Enter を押し、次に各関節を可動範囲の端から端まで動かして、すべての関節を動かし終えたらもう一度 Enter を押します。各アームに固有の id を付けてください。この名前がキャリブレーションファイルのラベルになります。このガイドのコマンドでは、例としてフォロワーに /dev/ttyACM0、リーダーに /dev/ttyACM1 を使っています。ご自身で確認したポートに置き換え、2 台のアームを取り違えないでください。
横にスクロールすると図の全体を見られます。
lerobot-calibrate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm続いて、同じ動作でリーダーをキャリブレーションします。
lerobot-calibrate \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm以降のコマンドでは必ず同じ id を使ってください。LeRobot はこれでキャリブレーションファイルを見つけます。ファイルは既定では ~/.cache/huggingface/lerobot/calibration に保存されます。バックアップを取り、一時フォルダーには置かないようにしましょう。あるコミュニティの製作者は、電源の入れ直しでキャリブレーションファイルを失い、すべての関節を可動範囲の中央に置かないままキャリブレーションをやり直したため、一部の関節のホーミングオフセットが誤った値になりました。
リーダーでフォロワーを遠隔操作する
遠隔操作は 2 台のアームをつなぎ、フォロワーがリーダーをなぞります。キャリブレーションがない場合、コマンドは先にキャリブレーション手順を開始します。最初は小さくゆっくりした動きで始め、フォロワーの関節に近づかないようにし、電源にすぐ手が届くようにしておきます。
lerobot-teleoperate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm次にカメラを追加します。カメラ検出ツールで一覧を表示すると、各カメラの識別子が出力され、それぞれのテストフレームが outputs/captured_images に保存されます。フレームを開いて、どのインデックスがどのカメラかを確認してください。インデックスは再起動したときやカメラを挿し直したときに変わることがあります。
lerobot-find-cameras opencvカメラを接続し、Rerun でライブ表示しながら、もう一度遠隔操作します。ここで付けるカメラ名(top や wrist など)はのちにデータセットのキーになるので、今後は同じ名前と設定を使ってください。
lerobot-teleoperate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm \
--display_data=trueポリシーが学習できるようにカメラを配置する
ポリシーが見るのはカメラ画像と関節位置だけです。そのため、高解像度よりも良いカメラ設置のほうが重要です。ほとんどの作業には 640×480、30 fps で十分で、記録と学習も速く済みます。
横にスクロールすると図の全体を見られます。
- 拡散光でシーンを均一に照らします。直射日光、強い反射、動く影は避けてください。記録時と実行時で照明が異なると、ポリシーが失敗する原因になることがあります。
- カメラはしっかり固定し、記録から実行までの間に動かさないでください。あるコミュニティの製作者の最初のポリシーはテーブルをつつくだけの動きしかせず、いくつかあった原因の 1 つは、記録とテストの間でカメラがわずかに動いていたことでした。
- 作業をフレームに収めます。物体、グリッパー、目標が、少なくとも 1 台のカメラで見えるようにします。良い確認方法は、カメラ画像だけを見て自分でもその作業ができるかどうかです。同じコミュニティの製作者は、カメラ映像だけを見ながらデモンストレーションを行いました。試す場合は、電源にすぐ手が届くようにしておいてください。
- 同じ製作者は、把持の最中にグリッパーの先端がよく見えなかったサイドカメラを、フロントカメラの隣に置いた俯瞰カメラに替えたところ、遮蔽が減りました。手首カメラは、その投稿では次のステップとして挙げられているだけです。一日を通して記録する場合は、ウェブカメラ自体の設定で露出とホワイトバランスを固定してください。LeRobot の RealSense カメラ設定でも
exposure、gain、white_balanceを指定できます。 - Ubuntu で同一のウェブカメラを 2 台使うと、USB アドレスが入れ替わり、カメラエラーで記録が止まることがあります。同じ製作者は、各カメラを物理 USB ポートで識別する udev ルールでこれを解決したため、各カメラは同じポートに挿したままにしてください。そうしない場合は、再起動のたびにカメラ検出ツールをもう一度実行してください。
データセットを記録する
データセットは LeRobotDataset 形式で、Hugging Face Hub にアップロードされます。無料アカウントを作成し、Hugging Face の設定で書き込み権限付きのトークンを作成してからログインし、ユーザー名を変数に保存しておきます。先に HUGGINGFACE_TOKEN に自分のトークンを設定するか、hf auth login だけを単独で実行して、求められたときにトークンを貼り付けます。
hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
echo $HF_USER最初にセットアップのテストとして 5 エピソードを記録します。遠隔操作のときと同じロボットの id、ポート、カメラ設定を使い、作業を平易な言葉で記述します。
lerobot-record \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm \
--display_data=true \
--dataset.repo_id=${HF_USER}/record-test \
--dataset.num_episodes=5 \
--dataset.single_task="Grab the black cube" \
--dataset.streaming_encoding=trueLeRobot はデータセット名に日付と時刻を付け足すため、${HF_USER}/record-test は ${HF_USER}/record-test_YYYYMMDD_HHMMSS として保存されます。以降のコマンドではその完全な名前を使ってください。名前は ls ~/.cache/huggingface/lerobot/${HF_USER} で確認できます。渡した名前のままにしたい場合は --dataset.no_stamp=true を追加します。データセットは ~/.cache/huggingface/lerobot に保存され、記録の終了時に Hub にプッシュされます。個人アカウントからプッシュしたデータセットは公開になる場合があるため、Hub で公開設定を確認し、非公開にしたい場合は --dataset.private=true を追加してください。ローカルだけに保持するには --dataset.push_to_hub=False を追加します。停止したセッションを続けるには、--resume=true、タイムスタンプ付きの完全な --dataset.repo_id、データセットのローカルフォルダーを指定した --dataset.root、そして合計ではなく追加するエピソード数を指定した --dataset.num_episodes を付けて、コマンドを再実行します。
エピソード時間とリセット時間の既定値はどちらも 60 秒(--dataset.episode_time_s と --dataset.reset_time_s)で、エピソード数の既定値は 50 です。記録中はキーボードで進行を操作します。下の表を参照してください。
最初に実用的なデータセットを作るには、いくつかの位置から物体を拾って容器に入れるような、単純な作業を選びます。少なくとも 50 エピソードを記録し、1 つの位置につき約 10 エピソードを目安にします。カメラと把持の仕方を一定に保ち、バリエーションはゆっくり加えてください。失敗したエピソードは撮り直します。決まった位置での 50 エピソードは出発点にすぎません。ポリシーは主に、記録した位置の近くでだけ動作すると考えてください。LeRobot は、保存した各エピソードのあとに記録周期の行を、記録の終了時に要約を表示します。周期が 30 Hz の目標を大きく下回っていても、データセットには 30 Hz と記録されるため、動きが実際より速く見えてしまいます。ループを遅くしている原因を突き止め(ドキュメントの例ではカメラの読み取りでした)、影響を受けたエピソードは、そのまま学習に使わずに撮り直してください。
学習の前にデータを確認します。Hugging Face の LeRobot データセットビジュアライザーでデータセットを開き、エピソードをロボットで再生して、動きが再現されることをテストしてください。再生ではアームがあなたの操作なしに動くため、作業空間を片付け、アームをエピソードの最初の姿勢の近くに置いて開始し、電源にすぐ手が届くようにしておいてください。
lerobot-replay \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
--dataset.episode=0横にスクロールしてすべての列を比較できます。
| キー | 動作 |
|---|---|
| 右矢印キーまたは n | エピソードまたはリセット期間を早めに終了して、次に進む |
| 左矢印キーまたは r | 現在のエピソードを破棄して、撮り直す |
| Esc または q | セッションを停止する。進行中のエピソードは保存され、そのあと動画がエンコードされてデータセットがアップロードされる(そのエピソードを破棄したい場合は、先に左矢印キーまたは r を押す) |
ACT ポリシーを学習する
ACT(Action Chunking Transformer)は LeRobot のチュートリアルで使われているポリシーで、データセットに保存されたモーターとカメラに合わせて適応します。ハードウェアガイドでは、軽量なポリシー(ACT、VQ-BeT、TD-MPC)の GPU メモリは、バッチサイズ 8 で約 2〜6 GB が目安とされています。NVIDIA GPU(cuda)で学習します。Apple silicon の場合はコマンドを --policy.device=mps に変更します。これには macOS 15 以降が必要です(macOS 14 では LeRobot は CPU に切り替わりますが、CPU は学習には向きません)。
完全なデータセット名を指定して学習を開始します。
lerobot-train \
--dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
--policy.type=act \
--output_dir=outputs/train/act_so101_test \
--job_name=act_so101_test \
--policy.device=cuda \
--trackio.enable=true \
--policy.repo_id=${HF_USER}/my_policy \
--steps=20000--steps を指定しない場合、学習は 100,000 ステップ実行されます。小さなデータセットには通常多すぎます。模倣学習は一般に、データを 5〜10 周する間に収束します。30 秒のエピソード 50 本、30 fps のデータセットには約 45,000 フレームがあり、バッチサイズ 8 では 1 周が約 5,600 ステップなので、5〜10 周はおよそ 28,000〜56,000 ステップに相当します。上のコマンドでは、短い最初の実行として --steps=20000(約 3.5 周)を使っています。ポリシーの学習が足りないときは増やしてください。これをかなり小さくする場合は、--policy.scheduler_decay_steps も --steps に近い値に設定します。ハードウェアガイドの見積もりでは、ACT をバッチサイズ 8 で 5 周学習するのに、RTX 3090 または 4090 で約 30〜60 分、L4 または A10G で 1〜2 時間、バッチサイズ 4 の M1、M2、M3 Max で 6〜14 時間かかります。ガイドはこれらの数値を目安としており、実際の実行では約 50% の差が出ることがあるとしています。
適した GPU がない場合は、ACT ノートブックを使って Google Colab で学習するか、hf auth login を実行したうえで、同じコマンドに --job.target=a10g-small のような Hugging Face Jobs のフレーバーを追加します。このコマンドは Trackio を有効にしているため、ジョブでは --trackio.space_id=<user>/<space> も必要です(Space を非公開にするには --trackio.private=true を追加します)。または --trackio.enable=true を削除してください。Jobs は秒単位で課金され、--job.timeout を設定しない限り 48 時間で打ち切られます。また、ローカルのみのデータセットは自動で非公開リポジトリにアップロードされ、学習したモデルは最後にプッシュされます。hf jobs hardware でフレーバーの一覧を確認できます。
チェックポイントは outputs/train/act_so101_test/checkpoints に書き込まれます。中断した実行は最後のチェックポイントから再開できます。学習コマンドは --policy.repo_id=${HF_USER}/my_policy を設定しているため、完成したモデルは最後にそのリポジトリへプッシュされます(--policy.push_to_hub=false でこれをオフにでき、--policy.private=true で非公開になります)。チェックポイントを自分でアップロードする場合は、--policy.path=${HF_USER}/my_policy で見つかるよう、同じリポジトリ名を使ってください。
lerobot-train \
--config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
--resume=true
hf upload ${HF_USER}/my_policy \
outputs/train/act_so101_test/checkpoints/last/pretrained_modelLeRobot の学習スクリプトは、実ロボットでのポリシーを評価しません。そのため、学習に使わないエピソード(記録していない開始位置も含む)を取っておき、そこでポリシーをテストしてください。あるコミュニティの製作者は、50 エピソード(5 つの開始位置の領域それぞれ 10 エピソード)で学習し、それらの領域の新しいエピソードでは成功率 60%、学習から除外した領域のエピソードでは 10% にとどまったと報告しています。データを 1 領域あたり 25 エピソードに増やすと、同じ製作者は 90% と 75% に達しました。これらは小さなサンプルで、製作者自身のスクリプトで採点したものです。
フォロワーでポリシーを実行する
学習したポリシーのデプロイには lerobot-rollout を使います。記録したときと同じロボットの id、カメラ名、カメラ設定、タスクの文言を使い、その後に再起動や挿し直しをした場合は、ポート検出ツールをもう一度実行します。--duration の単位は秒で、指定しない場合はポリシーを止めるまで実行され続けます。
lerobot-rollout \
--strategy.type=base \
--policy.path=${HF_USER}/my_policy \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
--task="Grab the black cube" \
--duration=60ストラテジーは実行中の動作を決めます。下の表を参照してください。データセットを記録するストラテジーでは、ユーザー名のあとに続くリポジトリ名が rollout_ で始まっている必要があります。たとえば --dataset.repo_id=${HF_USER}/rollout_so101_test のようにします。これにはタイムスタンプが付け足されます。sentry のような記録を行うストラテジーでは、--task の代わりに --dataset.single_task を使います。各ストラテジーのフラグについては LeRobot のドキュメントを参照してください。
LeRobot v0.5.x 以前には lerobot-rollout がありません。v0.5.1 のドキュメントの説明どおりに lerobot-record を使ってください。このガイドの学習用フラグは現行リリース向けです。
最初の実行は、短い実行時間(たとえば 15 秒)、障害物のない作業空間、アームを止める方法をあらかじめ決めた状態で行います。電源を切るとモーターの保持が解除されるため、何かに載っていないアームは落下することがあります。アームがテーブルをつつく、あるいは行き過ぎる場合は、モデルを疑う前にセットアップを確認します。同じキャリブレーション id、同じ位置・同じ名前・同じ解像度のカメラ、同じ照明、そしてデータセットがカバーしている位置にある物体、の各点です。
横にスクロールしてすべての列を比較できます。
| ストラテジー | 動作 |
|---|---|
| base | 記録せずに自律的に実行する。素早いテスト向け |
| sentry | 継続的に記録し、自動的にアップロードする |
| highlight | リングバッファを保持し、キーを押すとその内容を保存する |
| dagger | 人が介在するデータ収集 |
| episodic | リセット段階をはさみながら、エピソードごとに記録する |
LeKiwi でロボットを拡張する
LeKiwi は SO-101 フォロワーアームを搭載する 3 輪のモバイルベースです。Raspberry Pi、またはカメラとモーター制御ボード用に十分な USB ポートがある別の 5 V コンピューター(LeKiwi のページでは 2 つ以上とされています)がロボットを動かし、ノート PC からリーダーアームとキーボードで操縦します。有線版ではすべてがノート PC 上で動くため、Pi の手順は省略できます。部品表、印刷ファイル、ベースの組み立て手順は、Hugging Face の LeKiwi ページからリンクされている LeKiwi プロジェクトにあります。
横にスクロールすると図の全体を見られます。
キーボードでベースを操縦するにはグローバルなキーバックエンドが必要なため、X11、Windows のデスクトップ、またはターミナルに入力監視を許可した macOS では動作しますが、Wayland やヘッドレスマシンでは動作しません。
- 上のセクションに従って SO-101 アームを 2 本組み立てます。1 本はベースに搭載し、もう 1 本はリーダーとして使います。そのあとベースを組み立てます。
- Raspberry Pi OS をインストールして SSH を有効にし、
ssh <user>@<pi-ip>でログインできることを確認します。Pi とノート PC の両方に、インストールのセクションと同じ手順で LeRobot をインストールし、そのうえでサーボドライバーと ZeroMQ を含む LeKiwi extra を追加します。LeKiwi extra をインストールする pip install 'lerobot[lekiwi]' - 1 つのコマンドですべてのモーターをセットアップします。アームのモーターには ID 6〜1、ホイールには 9、8、7 が割り当てられます。ホイールの ID は、LeKiwi のドキュメントに示された取り付け位置と一致させる必要があります。LeKiwi の制御ボードは 1 枚だけです。
LeKiwi のモーター ID を設定する lerobot-setup-motors \ --robot.type=lekiwi \ --robot.port=/dev/ttyACM0 - フォロワーアームは Pi 上で、リーダーアームはノート PC 上でキャリブレーションします。LeKiwi のページではリーダーに
--teleop.type=so100_leaderが示されています。examples/lekiwi/teleoperate.pyがどのリーダークラスを作成するかを確認し、同じタイプと--teleop.idでキャリブレーションしてください。ホイールのモーターにキャリブレーションは不要です。LeKiwi のアームをキャリブレーションする lerobot-calibrate \ --robot.type=lekiwi \ --robot.id=my_awesome_kiwi - Pi 上で LeRobot の環境を有効にし、ホストを起動します。ホストは、
--host.connection_time_sを引き上げない限り(たとえば 600 に)30 秒後に停止します。記録のような長いセッションでは、この引き上げが必要です。Pi で LeKiwi ホストを起動する python -m lerobot.robots.lekiwi.lekiwi_host \ --robot.id=my_awesome_kiwi \ --host.connection_time_s=600 - ノート PC で、LeRobot のソースリポジトリにある
examples/lekiwi/teleoperate.pyを編集します。remote_ipを Pi のアドレスに設定し、リーダーアームのportと id を自分の値に設定してから、実行します。record.pyではHF_REPO_IDとTASK_DESCRIPTIONも設定します。replay.pyではremote_ip、port、データセットの id、エピソードのインデックスを設定します。学習済みポリシーを実行するには、LeKiwi のページではexamples/lekiwi/evaluate.pyを使います(remote_ip、port、モデルを設定します)。前のセクションのlerobot-rolloutコマンドは、単体の SO-101 向けに書かれています。速度は R と F で切り替える 3 つのモードがあります。高速は 0.3 m/s と 90°/s、中速は 0.2 m/s と 60°/s、低速は 0.1 m/s と 30°/s です。
横にスクロールしてすべての列を比較できます。
| キー | 動作 |
|---|---|
| W | 前進する |
| A | 左へ移動する |
| S | 後退する |
| D | 右へ移動する |
| Z | 左に旋回する |
| X | 右に旋回する |
| R | 速度を上げる |
| F | 速度を下げる |
トラブルシューティングのチェックリスト
多くの問題は、電源、ケーブル、ポート、あるいは記録時と実行時の間で変わってしまったセットアップが原因です。コードを変更する前に、この表を順に確認してください。
LeRobot 自体についての質問は、Hugging Face のドキュメントからリンクされている Discord コミュニティへどうぞ。当店の部品については、WhatsApp ボタンまたはサポートフォームをご利用ください。
横にスクロールしてすべての列を比較できます。
| 症状 | 確認すること |
|---|---|
| シリアルポートが見つからない、またはアクセスが拒否される | ボードに電源を入れ USB ケーブルを接続した状態で、ポート検出ツールをもう一度実行します。Linux では、そのポートに sudo chmod 666 を実行してアクセスを許可します。ポートは再起動や挿し直しのあとに変わることがあるため、そのたびにポート検出ツールをもう一度実行してください。 |
| ID スクリプトがモーターを見つけられない | 電源、USB ケーブル、3 ピンケーブルを確認します。設定するモーターだけを接続してください。Waveshare ボードでは、2 つのジャンパーを両方ともチャンネル B(USB)にする必要があります。 |
| 流用したサーボが見つからない、または応答しない | SO-101 のガイドにあるとおり、ID とボーレートが新しいロボットと合っていない可能性が高いです。モーターのセットアップを、1 個ずつもう一度実行してください。 |
| キャリブレーションに失敗する、またはキャリブレーション後にアームが正しく動かない | もう一度キャリブレーションします。まずすべての関節を可動範囲の中央に置いて Enter を押し、次に各関節を可動範囲の端から端まで動かします。すべての関節を中央に置かなかったあるコミュニティの製作者は、ホーミングオフセットが誤った値になりました。その後は同じロボットの id を使ってください。 |
| カメラが切断される、またはインデックスが変わる | 再起動やカメラの挿し直しのたびに、カメラ検出ツールをもう一度実行します。同一のウェブカメラ 2 台は、Linux で USB アドレスが入れ替わることがあります。あるコミュニティの製作者は、物理 USB ポートをキーにした udev ルールでこれを解決しました。 |
| 記録のキーが反応しない | 対話型のターミナルからコマンドを起動し、そのウィンドウにフォーカスを保ってください。矢印キーと Esc のほか、文字キーの n、r、q も使えます。キーボードでロボットを操縦する場合(LeKiwi など)に限り、X11、Windows のデスクトップ、または macOS の許可が必要です。 |
| 学習がデータセットを見つけられない | 日付と時刻のサフィックスを含む、完全なデータセット名を使ってください。 |
| 記録時の周期が 30 Hz を大きく下回る | 記録中に表示される周期の行を確認します。カメラの読み取りに時間の大半を取られている場合は、解像度を下げるかカメラの台数を減らしてから、もう一度記録してください。ポリシーは実行時にも同じカメラ構成を前提としており、30 Hz を大きく下回って記録されたエピソードも、30 Hz で動いたものとして保存されるためです。 |
| ポリシーがテーブルをつつく、または行き過ぎる | キャリブレーションの id、カメラの位置、名前、照明を記録セッションと比較し、物体がデータセットに例のある位置から始まっているかを確認してください。 |
| LeKiwi が接続できない、またはホストが 30 秒後に停止する | hostname -I で Pi のアドレスを調べ、ノート PC からそのアドレスに ping を送り、ssh <user>@<pi-ip> を試します。必要なら sudo raspi-config で SSH を有効にしてください。ホストは、--host.connection_time_s を設定しない限り 30 秒後に停止します。 |