# HopeJR

## المتطلبات

- [إعداد العتاد](https://github.com/TheRobotStudio/HOPEJr)

## تثبيت LeRobot

اتبع [تعليمات التثبيت](https://github.com/huggingface/lerobot#installation) لتثبيت LeRobot.

قم بتثبيت LeRobot مع تبعيات HopeJR:

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

## إعداد الجهاز

قبل بدء المعايرة والتشغيل، عليك تحديد منافذ USB لكل مكوّن من مكوّنات HopeJR. نفّذ هذا السكربت للعثور على منافذ USB للذراع واليد والقفاز والهياكل الخارجية:

```bash
lerobot-find-port
```

سيؤدي هذا إلى عرض منافذ USB المتاحة والأجهزة المرتبطة بها. دوّن مسارات المنافذ (مثل `/dev/tty.usbmodem58760433331`، `/dev/tty.usbmodem11301`) لأنك ستحتاج إلى تحديد هذه المسارات في المعاملات `--robot.port` و`--teleop.port` عند تسجيل البيانات، أو إعادة تشغيل الحلقات، أو تشغيل سكربتات التشغيل عن بُعد.

## الخطوة 1: المعايرة

قبل إجراء التشغيل عن بُعد، يجب معايرة أطراف HopeJR. سيتم حفظ ملفات المعايرة في `~/.cache/huggingface/lerobot/calibration`

### 1.1 معايرة يد الروبوت

```bash
lerobot-calibrate \
    --robot.type=hope_jr_hand \
    --robot.port=/dev/tty.usbmodem58760432281 \
    --robot.id=blue \
    --robot.side=right
```

عند تشغيل سكربت المعايرة، ستظهر واجهة معايرة رسومية. تُسمّى مفاصل الأصابع على النحو التالي:

**إبهام**:

- **CMC**: المفصل الأساسي الذي يربط الإبهام باليد
- **MCP**: مفصل مفاصل
- **PIP**: مفصل الإصبع الأول
- **DIP** : مفصل طرف الإصبع

**إصبع السبابة، وإصبع الوسطى، وإصبع البنصر، وإصبع الخنصر**:

- **العضلة المانعة الشعاعية**: تحرك قاعدة الإصبع نحو الإبهام
- **عضلة الثني الكعبرية**: تحرك قاعدة الإصبع نحو الخنصر
- **PIP/DIP**: ثني الفصّين البعيد والقريب من إصبع اليد

يجب معايرة كلٍّ من هذه العناصر على حدة عبر واجهة المستخدم الرسومية. لاحظ أن عضلات الانحناء الزندية والزندية يجب أن تكون نطاقاتها متساوية الحجم (لكن بإزاحات مختلفة) للحصول على حركة متماثلة.

  <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/calibration_gui_1.png" alt="ضبط الحدود في واجهة معايرة اليد" title="ضبط الحدود في واجهة معايرة اليد" width="100%"
  >

استخدم واجهة المعايرة لضبط حدود المدى لكل مفصل كما هو موضح أعلاه.

  <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/calibration_gui_2.png" alt="حفظ قيم المعايرة" title="حفظ قيم المعايرة" width="100%"
  >

بمجرد ضبط الحدود المناسبة لجميع المفاصل، انقر على "حفظ" لتخزين قيم المعايرة في المحركات.

### 1.2 معايرة قفاز المشغّل عن بُعد

```bash
lerobot-calibrate \
    --teleop.type=homunculus_glove \
    --teleop.port=/dev/tty.usbmodem11201 \
    --teleop.id=red \
    --teleop.side=right
```

حرّك كل إصبع عبر نطاق حركته الكامل، بدءًا من الإبهام.

```
Move thumb through its entire range of motion.
Recording positions. Press ENTER to stop...

-------------------------------------------
NAME      |    MIN |    POS |    MAX
thumb_cmc |   1790 |   1831 |   1853
thumb_mcp |   1497 |   1514 |   1528
thumb_pip |   1466 |   1496 |   1515
thumb_dip |   1463 |   1484 |   1514
```

تابع بإصبعك:

```
Move middle through its entire range of motion.
Recording positions. Press ENTER to stop...

-------------------------------------------
NAME                 |    MIN |    POS |    MAX
middle_mcp_abduction |   1598 |   1718 |   1820
middle_mcp_flexion   |   1512 |   1658 |   2136
middle_dip           |   1484 |   1500 |   1547
```

بمجرد اكتمال المعايرة، سيحفظ النظام المعايرة في `/Users/your_username/.cache/huggingface/lerobot/calibration/teleoperators/homunculus_glove/red.json`

### 1.3 معايرة ذراع الروبوت

```bash
lerobot-calibrate \
    --robot.type=hope_jr_arm \
    --robot.port=/dev/tty.usbserial-1110 \
    --robot.id=white
```

سيؤدي هذا إلى فتح واجهة رسومية للتعاير حيث يمكنك تحديد حدود النطاق لكل محرك. يتم تنظيم حركات الذراع على النحو التالي:

- **الكتف**: الميل، الدوران، والانقلاب
- **المرفق**: ثني
- **المعصم**: الميل، الدوران، والالتواء

  <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/calibration_gui_2.png" alt="ضبط الحدود في واجهة معايرة الذراع" title="ضبط الحدود في واجهة معايرة الذراع" width="100%"
  >

استخدم واجهة المعايرة لضبط حدود المدى لكل مفصل. حرّك كل مفصل عبر كامل نطاق حركته وعدّل القيم الدنيا والعليا وفقاً لذلك. بعد ضبط الحدود المناسبة لجميع المفاصل، احفظ المعايرة.

### 1.4 معايرة الهيكل الخارجي للروبوت

```bash
lerobot-calibrate \
    --teleop.type=homunculus_arm \
    --teleop.port=/dev/tty.usbmodem11201 \
    --teleop.id=black
```

يتيح الهيكل الخارجي التحكم في ذراع الروبوت. أثناء المعايرة، سيُطلب منك تحريك جميع المفاصل عبر نطاق حركتها الكامل:

```
Move all joints through their entire range of motion.
Recording positions. Press ENTER to stop...

-------------------------------------------
-------------------------------------------
NAME            |    MIN |    POS |    MAX
shoulder_pitch  |    586 |    736 |    895
shoulder_yaw    |   1257 |   1374 |   1390
shoulder_roll   |    449 |   1034 |   2564
elbow_flex      |   3023 |   3117 |   3134
wrist_roll      |   3073 |   3096 |   3147
wrist_yaw       |   2143 |   2171 |   2185
wrist_pitch     |   1975 |   1993 |   2074
Calibration saved to /Users/your_username/.cache/huggingface/lerobot/calibration/teleoperators/homunculus_arm/black.json
```

## الخطوة 2: التشغيل عن بُعد

بسبب تعارض المتغيرات العالمية في وسيط Feetech، يجب تشغيل التشغيل عن بُعد للذراع واليد في جلسات shell منفصلة:

### يد

```bash
lerobot-teleoperate \
    --robot.type=hope_jr_hand \
    --robot.port=/dev/tty.usbmodem58760432281 \
    --robot.id=blue \
    --robot.side=right \
    --teleop.type=homunculus_glove \
    --teleop.port=/dev/tty.usbmodem11201 \
    --teleop.id=red \
    --teleop.side=right \
    --display_data=true \
    --fps=30
```

### Arm

```bash
lerobot-teleoperate \
    --robot.type=hope_jr_arm \
    --robot.port=/dev/tty.usbserial-1110 \
    --robot.id=white \
    --teleop.type=homunculus_arm \
    --teleop.port=/dev/tty.usbmodem11201 \
    --teleop.id=black \
    --display_data=true \
    --fps=30
```

## الخطوة 3: التسجيل، إعادة التشغيل، التدريب

التسجيل وإعادة التشغيل والتدريب باستخدام Hope-JR ما يزال تجريبيًا.

### تسجيل

يسجّل هذا الإجراء مجموعة البيانات، والتي يمكن اعتبارها مثالاً [هنا](https://huggingface.co/datasets/nepyope/hand_record_test_with_video_data).

```bash
lerobot-record \
    --robot.type=hope_jr_hand \
    --robot.port=/dev/tty.usbmodem58760432281 \
    --robot.id=right \
    --robot.side=right \
    --robot.cameras='{"main": {"type": "opencv", "index_or_path": 0, "width": 640, "height": 480, "fps": 30}}' \
    --teleop.type=homunculus_glove \
    --teleop.port=/dev/tty.usbmodem1201 \
    --teleop.id=right \
    --teleop.side=right \
    --dataset.repo_id=<USER>/hand_record_test_with_video_data \
    --dataset.single_task="Hand recording test with video data" \
    --dataset.num_episodes=1 \
    --dataset.episode_time_s=5 \
    --dataset.push_to_hub=true \
    --dataset.private=true \
    --dataset.streaming_encoding=true \
    --dataset.encoder_threads=2 \
    --display_data=true
# Optional: --dataset.rgb_encoder.vcodec=auto
```

### إعادة التشغيل

```bash
lerobot-replay \
    --robot.type=hope_jr_hand \
    --robot.port=/dev/tty.usbmodem58760432281 \
    --robot.id=right \
    --robot.side=right \
    --dataset.repo_id=<USER>/hand_record_test_with_camera \
    --dataset.episode=0
```

### تدريب

```bash
lerobot-train \
  --dataset.repo_id=<USER>/hand_record_test_with_video_data \
  --policy.type=act \
  --output_dir=outputs/train/hopejr_hand \
  --job_name=hopejr \
  --policy.device=mps \
  --trackio.enable=true \
  --policy.repo_id=<USER>/hand_test_policy
```

### تقييم

```bash
lerobot-record \
  --robot.type=hope_jr_hand \
  --robot.port=/dev/tty.usbmodem58760432281 \
  --robot.id=right \
  --robot.side=right \
  --robot.cameras='{"main": {"type": "opencv", "index_or_path": 0, "width": 640, "height": 480, "fps": 30}}' \
  --display_data=false \
  --dataset.repo_id=<USER>/eval_hopejr \
  --dataset.single_task="Evaluate hopejr hand policy" \
  --dataset.num_episodes=10 \
  --dataset.streaming_encoding=true \
  --dataset.encoder_threads=2 \
  --policy.path=outputs/train/hopejr_hand/checkpoints/last/pretrained_model
# Optional: --dataset.rgb_encoder.vcodec=auto
```