Microduck Robot●microduck-robot.com

Microduck Robot / LEROBOT

LeRobot SO-101 チュートリアル:組み立てから学習・実行まで

このガイドは、SO-101 のリーダーアームとフォロワーアームに関する Hugging Face の公式 LeRobot ドキュメントに沿って進め、製作者が最も見落としやすい確認事項を補い、最後に LeKiwi モバイルベースとトラブルシューティングのチェックリストまでを扱います。コマンドは LeRobot v0.7.0(2026年11月5日公開)に対応しています。LeRobot は変更が速いため、インストールするバージョンのドキュメントでフラグを照合してください。

作るものと必要なもの

LeRobot は Hugging Face のオープンソースのロボティクスライブラリです。同じ一連のコマンドで、ロボットの操作、デモンストレーションの記録、ポリシーの学習、そのポリシーの実行ができます。SO-101 はそのフラッグシップのアームです。リーダーアームを手で動かすとフォロワーアームがそれをなぞり、記録された動きとカメラ画像から、ニューラルネットワークが作業を自力で繰り返せるように学習します。

作業は 7 段階です。部品の調達とソフトウェアのインストール、各モーターへの ID の割り当て、両アームの組み立て、キャリブレーション、カメラを使った遠隔操作、データセットの記録、そしてポリシーの学習と実行です。最後の製作セクションでは LeKiwi モバイルベースを追加し、そのあとにトラブルシューティングのチェックリストが続きます。

横にスクロールすると図の全体を見られます。

組み立ての 7 段階と、それぞれの段階で使うコマンド7 つの段階を上から下へ番号付きで並べた一覧です。1 部品とソフトウェア:pip install lerobot。2 ポートとモーター ID:lerobot-find-port と lerobot-setup-motors。3 両アームの組み立て:コマンドはなく、手作業で行います。4 キャリブレーション:lerobot-calibrate。5 カメラ付きの遠隔操作:lerobot-find-cameras と lerobot-teleoperate。6 データセットの記録:lerobot-record を使い、確認には lerobot-replay を使います。7 ポリシーの学習と実行:lerobot-train のあとに lerobot-rollout を実行します。1部品とソフトウェア部品を揃えて LeRobot を入れるpip install lerobot2ポートとモーター IDサーボを 1 個ずつlerobot-find-portlerobot-setup-motors3両アームを組み立てる関節ごとに順番に組むコマンドなし:手で組み立てます4キャリブレーション両アームで同じ値にするlerobot-calibrate5カメラ付きで遠隔操作リーダーがフォロワーを動かすlerobot-find-cameraslerobot-teleoperate6データセットを記録関節位置と動画lerobot-recordlerobot-replay7ポリシーの学習と実行フォロワーで ACT ポリシーlerobot-trainlerobot-rollout
組み立ての 7 段階と、それぞれの段階で使うコマンド

必要なものは次のとおりです。アーム 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 の電源をつながないでください。各電源には、その電圧と対応するアームを書いて目印を付けてください。

横にスクロールすると図の全体を見られます。

リーダーアームとフォロワーアームの電源と USB上にあるコンピューターが、USB-C ケーブルでリーダーアームの制御ボードとフォロワーアームの制御ボードに接続されています。各制御ボードにはそれぞれ専用の電源があります。各ボードからは、サーボ 1 から順に 3 ピンケーブルで 6 個のサーボがチェーン接続されています。リーダーは常に 7.4 V のサーボを使い、5 V の電源で動かします。フォロワーは、7.4 V のサーボを 5 V の電源で動かすか、12 V のサーボを 5 A 以上の定格の 12 V 電源で動かします。Waveshare ボードでは、2 つのジャンパーをどちらもチャンネル B(USB 用のチャンネル)に設定します。コンピューターリーダーアーム5 V 電源制御ボードWaveshare ボード:ジャンパー 2 つともチャンネル B(USB)に設定。1234567.4 V サーボ 6 個を5 V 電源で駆動。フォロワーアーム電源:5 V、または12 V(5 A+)制御ボードWaveshare ボード:ジャンパー 2 つともチャンネル B(USB)に設定。1234567.4 V サーボは5 V で駆動、12 V サーボは12 V で駆動。電源USB-C3 ピンのサーボケーブル7.4 V のサーボをつないだボードに、12 V 電源を決して接続しないこと。
リーダーアームとフォロワーアームの電源と USB

印刷は PLA+ で、0.4 mm ノズルなら積層 0.2 mm(0.6 mm ノズルなら積層 0.4 mm)、充填率 15% にします。各アームの部品は、サポートが少なくて済む向きに配置された 1 つのファイルにまとまっています。水平のねじ穴にはサポートを入れないでください。最初に Gauge Zero と Gauge Tight のテストピースを印刷してサーボに当てて確認し、Gauge Zero がプロジェクトの動画のようにはまらない場合は、プリンターの設定を調整して印刷し直してから、アームを印刷してください。

プラスドライバーの #0 と #1 を用意し、テストの前に各ベースをテーブルにクランプで固定してください。この製作用に当社が扱っている部品は、下にリンクがあります。

横にスクロールしてすべての列を比較できます。

関節モーター IDリーダーのギア比フォロワーのギア比
ショルダーパン11/1911/345
ショルダーリフト21/3451/345
エルボーフレックス31/1911/345
リストフレックス41/1471/345
リストロール51/1471/345
グリッパー61/1471/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-forge

PyPI から、必要な extras を指定して LeRobot をインストールします。core_scripts は記録・再生・キャリブレーションで使うものを、feetech は STS3215 サーボのサポートを、training は学習用のツールを追加します。

extras を指定して LeRobot をインストールする
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 個ずつ接続して行ってください。別のロボットから流用したサーボにも、おそらく必要です。

横にスクロールすると図の全体を見られます。

SO-101 アームの 6 つの関節と、各関節のモーター IDロボットアームを横から見た図です。関節 1 のショルダーパンは、ベースにある垂直軸を中心にアーム全体を回転させます。関節 2、3、4 のショルダーリフト、エルボーフレックス、リストフレックスは、アームを同じ平面内で曲げ伸ばしします。関節 5 のリストロールは、前腕の軸を中心にグリッパーを回転させます。関節 6 はグリッパーです。各関節のモーター ID は、その関節の番号と同じです。リンクの長さと軸は、公式の SO-101 モデルに従っています。1234561ショルダーパン2ショルダーリフト3エルボーフレックス4リストフレックス5リストロール6グリッパーモーター ID = 関節番号。設定の順番は 6 から 1 へ。フォロワーアームを横から見た図。比率は公式 SO-101 モデルに準拠。リーダーでは関節 6 がトリガーです。
SO-101 アームの 6 つの関節と、各関節のモーター ID

制御ボードを 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 個ずつモーターを指定するので、実行する前に下の手順を読んでおいてください。

フォロワーのモーター ID を設定する
lerobot-setup-motors \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0

リーダーでは、ロボット用のオプションではなく、遠隔操作用デバイスのオプションを使います。各プロンプトでは、部品のセクションの表でその関節に記載されているギア比のモーターを手に取ってください(リーダーでは、ショルダーパンとエルボーフレックスが 1/191、ショルダーリフトが 1/345、リストフレックス、リストロール、グリッパーが 1/147)。スクリプトがモーターの設定完了を報告したら、すぐにそのモーターに ID を書いて印を付けてください。

リーダーのモーター ID を設定する
lerobot-setup-motors \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1
  1. スクリプトは 1 回に 1 個ずつモーターを指定し、グリッパー(ID 6)から始めてショルダーパン(ID 1)で終わります。指定されたモーターだけを制御ボードに接続してください。ほかのモーターにチェーン接続してはいけません。
  2. Enter を押します。ID を設定したとスクリプトが報告したら、そのモーターのケーブルをボードから抜き、次に指定されたモーターを接続して、もう一度 Enter を押します。
  3. Enter を押す前に、電源、USB、3 ピンケーブルを確認します。スクリプトがエラーを報告した場合は、まずこれらのケーブルを確認してください。また、Waveshare ボードでは、2 つのジャンパーを両方ともチャンネル B(USB)に合わせる必要があります。
  4. スクリプトが終了したら、モーターを順番にチェーン接続し、ショルダーパンのモーター(ID 1)を制御ボードに接続します。

    横にスクロールすると図の全体を見られます。

    モーター ID をサーボ 1 個ずつ設定し、そのあと順番にチェーン接続する上のパネル:ID を設定している間は、制御ボードにサーボを 1 個だけ接続します。セットアップスクリプトは、6、5、4、3、2、1 の順にサーボを指定します。下のパネル:セットアップ後は、サーボを順番にチェーン接続します。サーボ 1 を制御ボードに接続し、以降のサーボはそれぞれ前のサーボに接続して、サーボ 6 まで続けます。ID の設定中設定中のサーボだけを接続します。抜いてから、スクリプトが指定する次のサーボを接続します。制御ボード?スクリプトが指定する順序654321セットアップ後サーボを順番にチェーン接続します。サーボ 1 を制御ボードに接続します。制御ボード123456
    モーター ID をサーボ 1 個ずつ設定し、そのあと順番にチェーン接続する

リーダーアームとフォロワーアームの組み立て

両方のアームは印刷部品の大半を共有し、同じ順序で組み立てます(手首のロール用の部品は異なり、フォロワーに可動するジョーがある箇所は、リーダーではハンドルとトリガーになります)。ベースと肩、上腕、前腕、手首、そしてフォロワーではグリッパー、リーダーではハンドルとトリガーです。Hugging Face は SO-101 のページで関節ごとに短い動画を公開しているので、このメモと並べて参照してください。まず印刷した部品のサポート材をすべて取り除き、サーボを組み込んで閉じる前に、すべてのサーボに 3 ピンケーブルを差し込んでおきます。

  1. 関節 1(ショルダーパン):モーターに両方のホーンを取り付け、上側のホーンを M3×6 ねじ 1 本で固定します(下側のホーンにはねじは不要です)。モーターを M2×6 ねじ 4 本でベースに取り付け、最初のモーターホルダーを M2×6 ねじ 2 本でスライドさせて取り付けます。肩を上側に M3×6 ねじ 4 本、下側に 4 本で取り付け、肩のモーターホルダーを追加します。
  2. 関節 2(ショルダーリフト):両方のホーンを取り付けて上側のホーンを M3×6 ねじ 1 本で固定し(下側のホーンにはねじは不要です)、モーターを上からスライドさせて入れ、M2×6 ねじ 4 本で固定します。次に上腕を左右それぞれ M3×6 ねじ 4 本で取り付けます。
  3. 関節 3(エルボー):両方のホーンを取り付けて上側のホーンを M3×6 ねじ 1 本で固定し(下側のホーンにはねじは不要です)、モーター 3 を M2×6 ねじ 4 本で挿入して固定し、前腕を左右それぞれ M3×6 ねじ 4 本でそれに接続します。
  4. 関節 4(リストフレックス):両方のホーンを取り付けて上側のホーンを M3×6 ねじ 1 本で固定し(下側のホーンにはねじは不要です)、モーターホルダー 4 をかぶせ、モーター 4 をスライドさせて入れて M2×6 ねじ 4 本で固定します。
  5. 関節 5(リストロール):モーター 5 を手首のホルダーに、前面の M2×6 ねじ 2 本で取り付け、ホーンを 1 つだけ M3×6 ねじ 1 本で取り付けます。手首はモーター 4 に、公式の関節 5 の動画に示されているとおりに M3×6 ねじで固定します(テキストの手順書では左右それぞれ 4 本とされています)。
  6. フォロワーのグリッパー:グリッパーを手首のモーターのホーンに M3×6 ねじ 4 本で取り付け、グリッパーのモーターを左右それぞれ M2×6 ねじ 2 本で取り付け、両方のホーンを取り付けて上側のホーンを M3×6 ねじ 1 本で固定し(下側のホーンにはねじは不要です)、爪は公式のグリッパー動画に示されているとおりに M3×6 ねじで固定します(テキストの手順書では左右それぞれ 4 本とされています)。
  7. リーダーのハンドル:リーダーホルダーを手首に M3×6 ねじ 4 本で取り付け、ハンドルを M2×6 ねじ 1 本でそこに固定します。モーター 6(トリガーのモーターで、公式ガイドではグリッパーモーターと呼ばれています)を左右それぞれ M2×6 ねじ 2 本で取り付け、ホーンを M3×6 ねじ 1 本で固定し、続いてトリガーを M3×6 ねじ 4 本で取り付けます。
  8. 電源を入れる前に、各関節を手でゆっくり可動範囲いっぱいに動かし、止まる位置を越えて無理に動かさないでください。こすれずに動くはずです。モーターを組み込んで閉じる前に、各モーターに ID を書いて印を付け、両方のベースをテーブルにクランプで固定します。

両方のアームのキャリブレーション

キャリブレーションは各関節の可動範囲を記録し、同じ物理的な姿勢でリーダーとフォロワーが同じ値を報告するようにします。また、あるロボットで学習したポリシーを別のロボットで動かせるようにもなります。アームごとに 1 回行い、ハードウェアを変更したときや LeRobot がキャリブレーションの欠落を報告したときにもう一度行います。再キャリブレーションより前に作成した記録とポリシーは、古いキャリブレーションに基づいています。

最初にフォロワーをキャリブレーションします。スクリプトの指示に従い、まずすべての関節を可動範囲の中央に動かして Enter を押し、次に各関節を可動範囲の端から端まで動かして、すべての関節を動かし終えたらもう一度 Enter を押します。各アームに固有の id を付けてください。この名前がキャリブレーションファイルのラベルになります。このガイドのコマンドでは、例としてフォロワーに /dev/ttyACM0、リーダーに /dev/ttyACM1 を使っています。ご自身で確認したポートに置き換え、2 台のアームを取り違えないでください。

横にスクロールすると図の全体を見られます。

キャリブレーション:まず各範囲の中央、次に各関節の全可動範囲左右に並んだ 2 つのパネルです。ステップ 1:6 つの関節をそれぞれ可動範囲の中央に保ち(バーの中央の点で示します)、Enter を押します。ステップ 2:6 つの関節をそれぞれ全可動範囲で動かします(バーの最小端から最大端への両矢印で示します)。下には、同じ物理的な姿勢ならリーダーとフォロワーで位置の値が同じになることが示されています。ステップ 1:中央すべての関節を可動範囲の中央に動かし、Enter を押します。123456中央ステップ 2:全可動範囲各関節を可動範囲の端から端まで動かし、もう一度 Enter を押します。123456最小最大同じ物理的な姿勢なら、リーダーとフォロワーで位置の値が同じになります。
キャリブレーション:まず各範囲の中央、次に各関節の全可動範囲
フォロワーをキャリブレーションする
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 で十分で、記録と学習も速く済みます。

横にスクロールすると図の全体を見られます。

カメラの配置:作業を捉える固定した視点、均一な光、そしてデータセットのキーになる名前作業空間を横から見た図です。フォロワーアームが、目標の容器の隣にある物体に手を伸ばしています。テーブルの上方のスタンドに取り付けた上方カメラが、作業空間全体を見下ろしており、アーム、物体、目標を覆う網掛けの視野で示されています。グリッパーに取り付けた手首カメラは、ジョーに沿った方向を見ています。左上のやわらかい光のパネルが、シーンを均一に照らします。カメラは記録から実行までの間、固定したままにします。カメラ名はデータセットのキーになり、observation.images.top と observation.images.wrist です。拡散光物体目標上方カメラ手首カメラしっかり固定:記録から実行までカメラを動かさないこと。カメラ名がデータセットのキーに:observation.images.topobservation.images.wrist
カメラの配置:作業を捉える固定した視点、均一な光、そしてデータセットのキーになる名前
  1. 拡散光でシーンを均一に照らします。直射日光、強い反射、動く影は避けてください。記録時と実行時で照明が異なると、ポリシーが失敗する原因になることがあります。
  2. カメラはしっかり固定し、記録から実行までの間に動かさないでください。あるコミュニティの製作者の最初のポリシーはテーブルをつつくだけの動きしかせず、いくつかあった原因の 1 つは、記録とテストの間でカメラがわずかに動いていたことでした。
  3. 作業をフレームに収めます。物体、グリッパー、目標が、少なくとも 1 台のカメラで見えるようにします。良い確認方法は、カメラ画像だけを見て自分でもその作業ができるかどうかです。同じコミュニティの製作者は、カメラ映像だけを見ながらデモンストレーションを行いました。試す場合は、電源にすぐ手が届くようにしておいてください。
  4. 同じ製作者は、把持の最中にグリッパーの先端がよく見えなかったサイドカメラを、フロントカメラの隣に置いた俯瞰カメラに替えたところ、遮蔽が減りました。手首カメラは、その投稿では次のステップとして挙げられているだけです。一日を通して記録する場合は、ウェブカメラ自体の設定で露出とホワイトバランスを固定してください。LeRobot の RealSense カメラ設定でも exposure、gain、white_balance を指定できます。
  5. Ubuntu で同一のウェブカメラを 2 台使うと、USB アドレスが入れ替わり、カメラエラーで記録が止まることがあります。同じ製作者は、各カメラを物理 USB ポートで識別する udev ルールでこれを解決したため、各カメラは同じポートに挿したままにしてください。そうしない場合は、再起動のたびにカメラ検出ツールをもう一度実行してください。

データセットを記録する

データセットは LeRobotDataset 形式で、Hugging Face Hub にアップロードされます。無料アカウントを作成し、Hugging Face の設定で書き込み権限付きのトークンを作成してからログインし、ユーザー名を変数に保存しておきます。先に HUGGINGFACE_TOKEN に自分のトークンを設定するか、hf auth login だけを単独で実行して、求められたときにトークンを貼り付けます。

Hugging Face にログインする
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=true

LeRobot はデータセット名に日付と時刻を付け足すため、${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 は学習には向きません)。

完全なデータセット名を指定して学習を開始します。

ACT ポリシーを学習する
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_model

LeRobot の学習スクリプトは、実ロボットでのポリシーを評価しません。そのため、学習に使わないエピソード(記録していない開始位置も含む)を取っておき、そこでポリシーをテストしてください。あるコミュニティの製作者は、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 プロジェクトにあります。

横にスクロールすると図の全体を見られます。

LeKiwi:ノート PC がネットワーク経由でロボットを操縦し、Raspberry Pi がモーターを動かす左側は、リーダーアームとキーボード、スクリプト teleoperate.py を備えたノート PC です。右側は LeKiwi ロボットで、lekiwi_host を実行する Raspberry Pi が、USB でモーター制御ボードとカメラに接続されています。制御ボードは、ID 6 から 1 のアームモーターと、ID 9、8、7 のホイールモーターを動かします。ノート PC と Pi は、同じネットワーク上で ZeroMQ を使って通信し、コマンド用にポート 5555、観測データ用にポート 5556 を使います。有線版ではすべてがノート PC 上で動きます。ノート PCリーダーアーム(USB)キーボードteleoperate.pyスクリプトの remote_ip にPi のアドレスを指定して実行。同じネットワークZeroMQ5555, 5556LeKiwi ロボットRaspberry Pi(ホスト)lekiwi_host制御ボードカメラアームのモーターID 6 – 1ホイールモーターID 9, 8, 7有線版:Pi は使わず、すべてノート PC 上で動きます。
LeKiwi:ノート PC がネットワーク経由でロボットを操縦し、Raspberry Pi がモーターを動かす

キーボードでベースを操縦するにはグローバルなキーバックエンドが必要なため、X11、Windows のデスクトップ、またはターミナルに入力監視を許可した macOS では動作しますが、Wayland やヘッドレスマシンでは動作しません。

  1. 上のセクションに従って SO-101 アームを 2 本組み立てます。1 本はベースに搭載し、もう 1 本はリーダーとして使います。そのあとベースを組み立てます。
  2. Raspberry Pi OS をインストールして SSH を有効にし、ssh <user>@<pi-ip> でログインできることを確認します。Pi とノート PC の両方に、インストールのセクションと同じ手順で LeRobot をインストールし、そのうえでサーボドライバーと ZeroMQ を含む LeKiwi extra を追加します。
    LeKiwi extra をインストールする
    pip install 'lerobot[lekiwi]'
  3. 1 つのコマンドですべてのモーターをセットアップします。アームのモーターには ID 6〜1、ホイールには 9、8、7 が割り当てられます。ホイールの ID は、LeKiwi のドキュメントに示された取り付け位置と一致させる必要があります。LeKiwi の制御ボードは 1 枚だけです。
    LeKiwi のモーター ID を設定する
    lerobot-setup-motors \
        --robot.type=lekiwi \
        --robot.port=/dev/ttyACM0
  4. フォロワーアームは Pi 上で、リーダーアームはノート PC 上でキャリブレーションします。LeKiwi のページではリーダーに --teleop.type=so100_leader が示されています。examples/lekiwi/teleoperate.py がどのリーダークラスを作成するかを確認し、同じタイプと --teleop.id でキャリブレーションしてください。ホイールのモーターにキャリブレーションは不要です。
    LeKiwi のアームをキャリブレーションする
    lerobot-calibrate \
        --robot.type=lekiwi \
        --robot.id=my_awesome_kiwi
  5. 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
  6. ノート 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 秒後に停止します。

プロジェクトの参照元

お問い合わせ