# YAM

[YAM](https://doc.i2rt.com/products/yam) هو ذراع بست درجات حرية من [I2RT Robotics](https://i2rt.com/) مخصص لتعلم التقليد والذكاء الاصطناعي التجسدي. في LeRobot، يقود `yam_follower` ذراع YAM v1 قياسية واحدة مزودة بمقبض خطي DM4310، بينما يقود `bi_yam_follower` ذراعين. استخدمهما مع `lerobot-calibrate` و`lerobot-rollout` و`lerobot-replay`. لا يتوفر حاليًا ذراع YAM قائد في LeRobot، لذا يتم تشغيل YAM إما بواسطة سياسة أو عن طريق إعادة تشغيل مجموعة بيانات.

اجمع الأذرع وصِلها باستخدام أدلة I2RT؛ تغطي هذه الصفحة جانب LeRobot.

| دليل                                                           | ما يغطيه                                  |
| --------------------------------------------------------------- | ----------------------------------------------- |
| [سلسلة YAM Arm](https://doc.i2rt.com/products/yam)             | فتح الصندوق، التركيب، التوصيلات، المحركات والمقابض |
| [إعداد البرنامج](https://doc.i2rt.com/getting-started/sw-setup) | محوّلات CAN ومعدل البت وأسماء الواجهات الثابتة |
| [خلية YAM](https://doc.i2rt.com/products/yam-cell)              | محطة ثنائية اليد مع متابعين وقادة |

  <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._

## المعدات والسلامة

تحتوي كل ذراع على سبعة محركات بمعرّفات من 1 إلى 7: محركات DM4340 للمفاصل من 1 إلى 3، ومحركات DM4310 للمفاصل من 4 إلى 6 وللملقط. ولا يتم دعم YAM Pro وUltra وBIG YAM والملقطات الأخرى بعد.

تحتاج إلى:

- Linux، ومحوّل USB إلى CAN واحد لكل ذراع (SocketCAN، CAN كلاسيكي بسرعة 1 ميغابت/ثانية).
- يتم ضبط مهلة CAN لكل محرك على 400 مللي ثانية كحد أقصى (`8000` نبضة، وهي قيمة I2RT)، على سبيل المثال باستخدام `set_timeout.py --timeout` من [حزمة I2RT SDK](https://github.com/i2rt-robotics/i2rt). تُعد المهلة خط الدفاع الأخير في حال توقف LeRobot عن إرسال الأوامر، لذا لن يُفعّل LeRobot العزم دونها.
- الوصول إلى الإنترنت عند أول اتصال: تعويض الجاذبية يقوم بتنزيل نموذج YAM من حاوية [`lerobot/robot-urdfs`](https://huggingface.co/buckets/lerobot/robot-urdfs/tree/yam/v1) وتخزينه مؤقتًا تحت `HF_LEROBOT_HOME/robot-urdfs/yam/v1`.

> [!WARNING]
> ثبّت الذراع على سطح ثابت وأبقِ مساحة عملها خالية. يؤدي فصل الاتصال إلى تعطيل العزم، فتسقط الذراع بفعل الجاذبية: ادعمها أولاً. إذا انقطع التيار الكهربائي أو منفصل محوّل CAN أثناء التشغيل، أوقف البرنامج، ثم ادعم الذراع، ثم أعد الاتصال.

## تثبيت LeRobot 🤗

اتبع [دليل التثبيت](./installation)، ثم ثبّت دعم YAM:

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

يقوم هذا الأمر بتثبيت `motorbridge` و`python-can` للذراع، و`placo` لتعويض الجاذبية.

## اتصال العتاد

تحتاج كل ذراع إلى واجهة CAN خاصة بها، لأن كلا الذراعين يستخدمان معرّفات المحركات نفسها.

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

استخدم `--interfaces=can0,can1` لذراعين. يهيّئ الأمر واجهات لينكس باستخدام `sudo ip link` ولا يرسل أي أوامر إلى المحركات. عند وجود ذراعين، قد يتبادل `can0` و`can1` أدوارهما بعد إعادة التشغيل: تحقق من الذراع التي تتحكم بها كل واجهة، أو امنحهما أسماء ثابتة مثل `can_follower_l` باستخدام [إعداد البرنامج](https://doc.i2rt.com/getting-started/sw-setup) الخاص بـ I2RT، واستخدم تلك الأسماء كمنفذ.

## أنواع الأجهزة

| النوع              | الجهاز            |
| ----------------- | ----------------- |
| `yam_follower`    | متابع واحد   |
| `bi_yam_follower` | المتتبع ذو اليد |

مع ذراعين، اضبط خيارات كل ذراع باستخدام `--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` إلى الراديان ومن 0 إلى 1، كما تستخدم بيانات I2RT وMolmoAct2. يضيف `use_velocity_and_torque=true` ملاحظات `.vel` و`.torque`. الإجراءات هي أهداف مطلقة للمفاصل، مقصوصة ضمن حدود المفصل.

تستخدم الذراعان نفس الأسماء مع بادئَي `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"
```

للذراعين، استخدم `--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`، تُعوَّض المفاصل بدلاً من ذلك ضد الجاذبية وتُخمَّد بشكل خفيف بحيث يمكنك تحريك الذراع يدوياً، بينما يحافظ الماسك على فتحة؛ ويستأنف التتبع من أي موضع تحركت إليه.

## السلامة

- توقف جميع الأوامر عند حدوث عطل في المحرك أو انقطاع التغذية الراجعة. عند وجود ذراعين، يؤدي العطل في أي منهما إلى توقف كليهما. افصل الاتصال ثم أعد توصيله للمتابعة.
- يتناول نموذج الجاذبية الذراع القياسية دون كاميرات أو حمولات. بعد إضافة أيٍّ منهما، تأكد من عدم انحراف الذراع في وضع الطفو، وقم بتعديل `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، مع إحصاءات التطبيع المُصدَّرة. تم تدريبه على ذراعين من نوع YAM باستخدام الراديان ومقبض يتراوح بين 0 و1، مع ثلاث كاميرات بالترتيب: علوية، يسار، يمين؛ راجع [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`، حرّك الأذرع يدويًا إلى المكان الذي تريده، ثم اكتب `/start` لتشغيل السياسة من هناك. لا تستخدم `/stop` لهذا الغرض: فهو ينهي الجلسة ويعطّل العزم.

## استكشاف الأخطاء وإصلاحها

| المشكلة                                         | تحقق                                                                                                        |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| الواجهة CAN مفقودة أو متوقفة            | تحقق من طاقة المحوّل وكابل USB، و`ip link show`. شغّل `lerobot-setup-can` مرة أخرى.                  |
| `missing or stale motor feedback`               | تحقق من طاقة 24 فولت، وتوصيلات CAN والإنهاء، ومعرفات المحركات من 1 إلى 7، وأن `port` هو واجهة هذا الذراع. |
| الذراع الخاطئ يتحرك                             | تحقق من الذراع التي يقودها كل واجهة، أو امنح الواجهات أسماء ثابتة.                                   |
| `unsafe motor CAN timeout`                      | اضبط مهلة CAN لكل محرك على 400 مللي ثانية كحد أقصى باستخدام I2RT SDK.                                           |
| `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](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