# YAM

[YAM](https://doc.i2rt.com/products/yam)は、[I2RT Robotics](https://i2rt.com/)製の、模倣学習とエンボディドAI向けの6自由度アームです。LeRobotでは、`yam_follower`が線形DM4310グリッパーを備えた標準的なYAM v1アーム1本を駆動し、`bi_yam_follower`が2本を駆動します。`lerobot-calibrate`、`lerobot-rollout`、`lerobot-replay`と組み合わせて使用してください。LeRobotにはまだYAMリーダーアームがないため、YAMはポリシーによって駆動するか、データセットの再生によって駆動されます。

I2RTのガイドに従って腕を組み立て、配線してください。このページではLeRobot側の説明を行います。

| ガイド                                                           | 対象範囲                                  |
| --------------------------------------------------------------- | ----------------------------------------------- |
| [YAM アームシリーズ](https://doc.i2rt.com/products/yam)             | 開梱、マウント、配線、モーターとグリップ |
| [ソフトウェアセットアップ](https://doc.i2rt.com/getting-started/sw-setup) | CANアダプタ、ビットレート、固定インターフェース名 |
| [YAM Cell](https://doc.i2rt.com/products/yam-cell)              | 2つのフォロワーとリーダーを備えたバイマニュアルステーション |

  <img
    src="https://doc.i2rt.com/images/yam-standard/YAM-ST-GP-1.webp"
    alt="YAM follower arm with the linear gripper"
    width="48%"
  />
  <img
    src="https://doc.i2rt.com/images/yam-station/DS-ST-1.webp"
    alt="YAM Cell bimanual station"
    width="48%"
  />

_YAM フォローア（左）と YAM Cell 両手ステーション（右）。LeRobot がフォローアを駆動します。画像は I2RT Robotics のご提供によるものです。_

## ハードウェアと安全性

各アームにはID 1から7までの7つのモーターが搭載されています。関節1から3にはDM4340、関節4から6およびグリップにはDM4310が使用されています。YAM Pro、Ultra、BIG YAMおよびその他のグリップは、現時点ではサポートされていません。

必要なのは:

- Linux, and one USB-to-CAN adapter per arm (SocketCAN, classic CAN at 1 Mbit/s).
- すべてのモーターの CAN タイムアウトは最大 400 ms（`8000` ticks、I2RT の値）に設定してください。例えば、[I2RT SDK](https://github.com/i2rt-robotics/i2rt) の `set_timeout.py --timeout` を使用します。このタイムアウトは、LeRobot がコマンドの送信を停止した場合の最後の安全策であり、これが設定されていない場合、LeRobot はトルクを有効にしません。
- 初回接続時のインターネットアクセス: 重力補償は、[`lerobot/robot-urdfs`](https://huggingface.co/buckets/lerobot/robot-urdfs/tree/yam/v1) バケットから YAM モデルをダウンロードし、`HF_LEROBOT_HOME/robot-urdfs/yam/v1` 以下にキャッシュします。

> [!WARNING]
> アームを安定した面に固定し、作業スペースを空けておいてください。接続を解除するとトルクがオフになり、アームは重力で落下します。まずアームを支えてください。動作中に電源またはCANアダプタの接続が切断された場合は、プログラムを停止し、アームを支えたうえで、再接続してください。

## LeRobot🤗のインストール

[インストールガイド](./installation)に従って、YAMサポートをインストールします:

```bash
pip install -e ".[yam]"
```

これにより、アーム用に`motorbridge`と`python-can`、重力補償用に`placo`がインストールされます。

## ハードウェアを接続する

両アームは同じモーターIDを使用するため、それぞれに独立したCANインターフェースが必要です。

```bash
lerobot-setup-can --mode=setup --interfaces=can0 --use_fd=false
```

2つのアームを使用する場合は、`--interfaces=can0,can1` を使用します。このコマンドは `sudo ip link` を用いて Linux インターフェースを設定し、モーターコマンドは送信しません。2つのアームを使用する場合、再起動後に `can0` と `can1` が入れ替わる可能性があります。各インターフェースがどのアームを駆動しているかを確認するか、I2RT の [ソフトウェアセットアップ](https://doc.i2rt.com/getting-started/sw-setup) を使用して `can_follower_l` のような固定名を割り当て、それらの名前をポートとして使用してください。

## デバイスタイプ

| 型              | デバイス            |
| ----------------- | ----------------- |
| `yam_follower`    | 単一フォロワー   |
| `bi_yam_follower` | 両手フォロワー |

2つのアームがある場合、各アームのオプションを`--robot.left_arm_config.<option>`と`--robot.right_arm_config.<option>`で設定します。

## キャリブレーション

キャリブレーションでは、グリップの限界位置（完全に閉じた状態と完全に開いた状態）のみを測定します。関節は工場出荷時のゼロ位置を維持したままです。以下に示すように、まずアームを折りたたんでください。測定中はトルクがオフになっています。アームを支えながら、手動でグリップのみを動かしてください。各プロンプトでEnterキーを押してください。既存のキャリブレーションがある場合、接続時に制御が開始されます。Enterキーを押して既存のキャリブレーションを再利用するか、`c`と入力して再測定してください。LeRobotは、トルクをオフにする前にアームを支えるよう求めます。

  <img
    src="https://doc.i2rt.com/images/yam-standard/YAM-ST-GP-2.webp"
    alt="YAM arm in its folded position"
    width="48%"
  />
  <img
    src="https://doc.i2rt.com/images/linear-gripper-4310/GP-4310-CTR-1.webp"
    alt="Linear DM4310 gripper"
    width="48%"
  />

_すべての関節がゼロの折り畳み姿勢（左）、および線形DM4310グリップ（右）。画像はI2RT Roboticsの提供によるものです。_

```bash
lerobot-calibrate --robot.type=yam_follower --robot.port=can0 --robot.id=yam
```

左のグリップが先に測定され、その後右のグリップが測定され、それぞれ`<id>_left`ファイルと`<id>_right`ファイルに保存されます。

```bash
lerobot-calibrate --robot.type=bi_yam_follower --robot.id=bimanual_yam \
  --robot.left_arm_config.port=can0 --robot.right_arm_config.port=can1
```

後続のコマンドでも同じ`--robot.id`を使用してください。これにより、LeRobotが保存されたファイルを読み込みます。

## 観察とアクション

片腕には、観測とアクションの両方で`joint_1.pos`から`joint_6.pos`、そして`gripper.pos`が含まれます。関節は度数法の絶対角度であり、グリップは0（閉）から100（開）の範囲です。`use_degrees=false`にすると、I2RTやMolmoAct2のデータと同様にラジアンと0から1の範囲に切り替わります。`use_velocity_and_torque=true`にすると、`.vel`と`.torque`の観測が追加されます。アクションは関節の絶対目標値であり、関節の制限値にクリップされます。

2つのアームは、`left_`および`right_`プレフィックスを付けた同じ名前を使用します。アームに設定されたカメラもプレフィックスが付与されますが、トップレベルの`--robot.cameras`は名前をそのまま保持します。

## ポリシーの実行

接続前に、すべての関節がゼロになるようにアームを折りたたみ位置に配置してください。LeRobot は、各関節が測定位置から 11.5° 以内にあることを確認してから、その測定位置から制御を開始します。ポリシーがアクションを送信するまで、何も動きません。

```bash
lerobot-rollout \
  --robot.type=yam_follower --robot.port=can0 --robot.id=yam \
  --robot.cameras='{"wrist": {"type": "opencv", "index_or_path": 0, "width": 640, "height": 480, "fps": 30}}' \
  --policy.path=<user>/<policy> \
  --task="Pick up the cube"
```

2つのアームを使用する場合は、`--robot.type=bi_yam_follower --robot.id=bimanual_yam --robot.left_arm_config.port=can0 --robot.right_arm_config.port=can1`を使用します。ロールアウトを記録するには、`--dataset.repo_id=<user>/rollout_<name>`を追加してください。[推論を実行してポリシーを評価する](./il_robots#run-inference-and-evaluate-your-policy)を参照してください。`lerobot-replay`は、同じ`--robot.*`オプションを使用して、記録されたエピソードを再生します。

最初のアクションの前に、および`command_timeout_s`（1秒）間アクションが届かない場合、アームは現在の姿勢を保持します。`idle_mode=float`の場合、関節は重力補償と軽い減衰が適用され、手動でアームを動かすことができます。この間、グリップの開閉は維持され、トラッキングは手動で動かした位置から再開されます。

## 安全性

- モーターの故障またはフィードバックの欠如により、すべてのコマンドが停止します。2つのアームがある場合、いずれかのアームで故障が発生すると、両方のアームが停止します。続行するには、切断してから再接続してください。
- 重力モデルは、カメラやペイロードを装着していない標準アームをカバーしています。いずれかを追加した後、フロートモードでアームがドリフトしないことを確認し、ドリフトが発生する場合は`gravity_factors`を調整してください。

## 設定オプション

| オプション                    | デフォルト                          | 説明                                                |
| ------------------------- | -------------------------------- | ---------------------------------------------------------- |
| `port`                    | 必須                         | SocketCANインターフェース、例えば`can0`                    |
| `use_degrees`             | `true`                           | 角度は度、グリップは0〜100のスケールです。`false`を指定すると、ラジアンと0〜1のスケールになります。 |
| `use_velocity_and_torque` | `false`                          | `.vel` と `.torque` の観測値を追加します                      |
| `idle_mode`               | `hold`                           | アクションが届かない場合、`hold`でポジションを維持するか、`float`にするか      |
| `command_timeout_s`       | `1.0`                            | アイドルモードに入るまでの、アクションのない秒数             |
| `initial_position_deg`    | すべてゼロ                        | 必須の初期位置。`None`を指定するとチェックがスキップされます          |
| `initial_tolerance_deg`   | `11.5`                           | 初期位置からの許容距離                 |
| `gripper_force_limit_n`   | `50.0`                           | グリップがオブジェクトでブロックされた後の指の力      |
| `gravity_factors`         | `[1.0, 1.1, 1.1, 1.2, 1.0, 1.0]` | 重力補償の関節ごとの乗数          |
| `cameras`                 | `{}`                             | アームに取り付けられたカメラ                                |

## 例: MolmoAct2

[`lerobot/MolmoAct2-BimanualYAM-LeRobot`](https://huggingface.co/lerobot/MolmoAct2-BimanualYAM-LeRobot) は、`allenai/MolmoAct2-BimanualYAM` を LeRobot 形式に変換したもので、公開された正規化統計情報が含まれています。ラジアンと 0〜1 のグリッパーで 2 本の YAM アームを用いて学習され、カメラは上、左、右の順で 3 台使用されています。詳細は [MolmoAct2](./molmoact2) を参照してください。

```bash
pip install -e ".[yam,molmoact2,dataset]"

lerobot-rollout \
  --robot.type=bi_yam_follower --robot.id=bimanual_yam \
  --robot.left_arm_config.port=can0 --robot.right_arm_config.port=can1 \
  --robot.left_arm_config.use_degrees=false --robot.right_arm_config.use_degrees=false \
  --robot.cameras='{
    "top": {"type": "opencv", "index_or_path": "/dev/v4l/by-id/TOP_CAMERA", "width": 640, "height": 480, "fps": 30},
    "left": {"type": "opencv", "index_or_path": "/dev/v4l/by-id/LEFT_CAMERA", "width": 640, "height": 480, "fps": 30, "fourcc": "MJPG"},
    "right": {"type": "opencv", "index_or_path": "/dev/v4l/by-id/RIGHT_CAMERA", "width": 640, "height": 480, "fps": 30, "fourcc": "MJPG"}
  }' \
  --policy.path=lerobot/MolmoAct2-BimanualYAM-LeRobot \
  --inference.type=rtc --inference.rtc.execution_horizon=20 --inference.queue_threshold=20 \
  --device=cuda --interpolation_multiplier=2 \
  --interactive=true --play_sounds=false \
  --task="Pick up the red block and place it in the green bin"
```

`/start` を入力してポリシーを実行し、`/subtask <text>` で指示を変更し、`/reset` で初期位置に戻し、`/stop` で終了します。リターンは一定時間持続し、YAM の速度制限も引き続き適用されるため、初期位置から遠い位置にあるアームは途中で停止する可能性があります。

Float モードを使用すると、任意の位置からポリシーを開始できます。`--robot.left_arm_config.idle_mode=float --robot.right_arm_config.idle_mode=float` を追加してください。最初の `/start` の前、および `/reset` が完了してから 1 秒以内に、アームを手動で希望する位置まで移動し、そこからポリシーを実行するには `/start` を入力してください。このために `/stop` を使用しないでください。セッションを終了し、トルクを無効にしてしまいます。

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

| 問題                                         | 確認                                                                                                        |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| CANインターフェースが存在しないか、ダウンしています            | アダプターの電源とUSBケーブルを確認し、`ip link show`を実行してください。`lerobot-setup-can`を再度実行してください。                  |
| `missing or stale motor feedback`               | 24 V電源、CAN配線およびターミネーション、モーターID 1〜7、および`port`がこのアームのインターフェースであることを確認してください。 |
| 誤った腕が動きます                             | 各インターフェースがどのアームを駆動しているかを確認するか、インターフェースに固定の名前を割り当ててください。                                   |
| `unsafe motor CAN timeout`                      | I2RT SDK を使用して、すべてのモーターの CAN タイムアウトを最大 400 ms に設定します。                                           |
| `not within initial_tolerance_deg`              | 接続する前に、すべての関節をゼロにしてアームを折りたたんでください。                                                   |
| 接続時に再度キャリブレーションを求められます          | キャリブレーション時と同じ`--robot.id`を使用してください。                                                             |
| アームがフロートモードでドリフトする                    | アームのカメラやペイロードに対して`gravity_factors`を調整します。                                              |
| MolmoAct2は腕を誤った位置に移動させます | 両方のアームで`use_degrees=false`を設定してください。モデルはラジアンと0〜1のグリップを使用します。                              |

## 参考文献

- [YAM Arm シリーズ](https://doc.i2rt.com/products/yam): ハードウェア、モーター、グリップ
- [ソフトウェアセットアップ](https://doc.i2rt.com/getting-started/sw-setup): CANビットレートと固定インターフェース名
- [YAM Cell](https://doc.i2rt.com/products/yam-cell): 両手ステーション
- [I2RT SDK](https://github.com/i2rt-robotics/i2rt)：モーターツール、URDFおよびMuJoCoモデル
- [YAM製品ページ](https://i2rt.com/products/yam-6-dof-arm)
- [MolmoAct2](./molmoact2): LeRobotでのポリシーの読み込み