# LeKiwi

<img
  src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/1740517739083.jpeg"
  alt="LeKiwi"
  width="70%"
/>

في الخطوات أدناه، نشرح كيفية تجميع روبوت LeKiwi المحمول.

## توفير المكونات

اتبع هذا [README](https://github.com/SIGRobotics-UIUC/LeKiwi). يحتوي على قائمة المواد، مع رابط للحصول على القطع، بالإضافة إلى تعليمات طباعة القطع ثلاثية الأبعاد. كما يتضمن نصائح إذا كانت هذه تجربتك الأولى في الطباعة أو إذا لم تكن تملك طابعة ثلاثية الأبعاد.

### الإصدار السلكي

إذا كان لديك نسخة **wired** من LeKiwi، يمكنك تجاوز تثبيت Raspberry Pi وإعداد SSH. كما يمكنك تشغيل جميع الأوامر مباشرةً على جهاز الكمبيوتر الخاص بك، سواءً كان ذلك لسكربتات LeKiwi أو سكربتات الذراع القائدة للتشغيل عن بُعد.

## تثبيت البرامج على Pi

الآن علينا إعداد الحاسوب البعيد الذي سيعمل على روبوت LeKiwi. عادةً ما يكون هذا الحاسوب من نوع Raspberry Pi، لكنه يمكن أن يكون أي حاسوب يعمل بجهد 5 فولت ويحتوي على عدد كافٍ من منافذ usb (منفذين أو أكثر) للكاميرات ولوحة التحكم بالمحرك.

### تثبيت نظام التشغيل

لمعرفة كيفية إعداد Raspberry Pi وبطاقة SD الخاصة به، راجع: [إعداد PI](https://www.raspberrypi.com/documentation/computers/getting-started.html). هنا يتم شرح كيفية تنزيل [Imager](https://www.raspberrypi.com/software/) لتثبيت نظام Raspberry Pi OS أو Ubuntu.

### إعداد SSH

بعد إعداد جهاز Pi، يجب عليك تفعيل [SSH](https://www.raspberrypi.com/news/coding-on-raspberry-pi-remotely-with-visual-studio-code/) (بروتوكول shell الآمن) وإعداده حتى تتمكن من تسجيل الدخول إلى الجهاز من حاسوبك المحمول دون الحاجة إلى شاشة أو لوحة مفاتيح أو فأرة متصلة بالجهاز. يمكنك العثور على شرح ممتاز لكيفية القيام بذلك [هنا](https://www.raspberrypi.com/documentation/computers/remote-access.html#ssh). يمكن تسجيل الدخول إلى جهاز Pi من خلال موجه الأوامر (cmd) أو، إذا كنت تستخدم VSCode، يمكنك استخدام إضافة [هذه](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh).

### تثبيت LeRobot على Pi 🤗

قم بتثبيت LeRobot على جهاز Raspberry Pi الخاص بك باستخدام [دليل التثبيت](./installation) الخاص بنا

بالإضافة إلى هذه التعليمات، تحتاج إلى تثبيت دعم محركات Feetech & ZeroMQ على جهاز Pi الخاص بك:

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

## تثبيت LeRobot محليًا

إذا كان لديك LeRobot مثبتًا مسبقًا على حاسوبك المحمول/الثابت، يمكنك تجاوز هذه الخطوة؛ وإلا، فالرجاء اتباع الخطوات نفسها التي قمنا بها على Pi.

اتبع [دليل التثبيت](./installation) الخاص بنا

بالإضافة إلى هذه التعليمات، تحتاج إلى تثبيت دعم محركات Feetech & ZeroMQ على حاسوبك المحمول/السطحي:

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

رائع 🤗! لقد انتهيت الآن من تثبيت LeRobot، ويمكننا البدء في تجميع أذرع SO100/SO101 والقاعدة المتحركة 🤖. كل مرة تريد فيها استخدام LeRobot، يمكنك الانتقال إلى مجلد `~/lerobot` حيث قمنا بتثبيت LeRobot وتنفيذ أحد الأوامر.

# تعليمات التجميع خطوة بخطوة

أولاً، سنقوم بتركيب ذراعي SO100/SO101. ذراع واحد لتوصيله بالأساس المتحرك والآخر للتشغيل عن بُعد. ثم سنقوم بتركيب الأساس المتحرك. يمكن العثور على تعليمات التركيب في هاتين الصفحتين:

- [تجميع SO101](./so101#step-by-step-assembly-instructions)
- [تجميع LeKiwi](https://github.com/SIGRobotics-UIUC/LeKiwi/blob/main/Assembly.md)

### ابحث عن منافذ USB المرتبطة بلوحة المحرك

لإيجاد منفذ كل محوّل عتاد حافلة، نفّذ هذا النص البرمجي:

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

مثال على المخرجات:

```
Finding all available ports for the MotorBus.
['/dev/tty.usbmodem575E0032081']
Remove the USB cable from your MotorsBus and press Enter when done.

[...Disconnect corresponding leader or follower arm and press Enter...]

The port of this MotorsBus is /dev/tty.usbmodem575E0032081
Reconnect the USB cable.
```

حيث أن المنفذ الذي تم العثور عليه هو: `/dev/tty.usbmodem575E0032081` والذي يتوافق مع لوحتك.

على نظام لينكس، قد تحتاج إلى منح الوصول إلى منافذ USB من خلال تشغيل الأمر التالي:

```bash
sudo chmod 666 /dev/ttyACM0
sudo chmod 666 /dev/ttyACM1
```

مثال على المخرجات:

```
Finding all available ports for the MotorBus.
['/dev/ttyACM0']
Remove the usb cable from your MotorsBus and press Enter when done.

[...Disconnect corresponding leader or follower arm and press Enter...]

The port of this MotorsBus is /dev/ttyACM0
Reconnect the USB cable.
```

حيث أن المنفذ الذي تم العثور عليه هو: `/dev/ttyACM0` والذي يتوافق مع لوحتك.

### تهيئة المحركات

يمكن العثور على تعليمات ضبط المحركات في [التوثيق](./so101#configure-the-motors) الخاص بـ SO101. بالإضافة إلى المعرّفات الخاصة بمحركات الذراع، نحتاج أيضًا إلى ضبط معرّفات المحركات للقاعدة المتحركة. يجب أن تكون هذه المعرّفات بترتيب محدد حتى تعمل بشكل صحيح. أدناه صورة توضح معرّفات المحركات ومواقع تركيبها على القاعدة المتحركة. لاحظ أننا نستخدم لوحة واحدة فقط للتحكم بالمحركات على LeKiwi. وهذا يعني أن معرّفات المحركات الخاصة بالعجلات هي 7 و8 و9.

يمكنك تشغيل هذا الأمر لإعداد المحركات الخاصة بـ LeKiwi. سيقوم أولاً بإعداد محركات الذراع (المعرّف 6..1) ثم إعداد محركات العجلات (9، 8، 7)

```bash
lerobot-setup-motors \
    --robot.type=lekiwi \
    --robot.port=/dev/tty.usbmodem58760431551 # <- paste here the port found at previous step
```

### استكشاف أخطاء الاتصال

إذا واجهت صعوبة في الاتصال بـ LeKiwi، فاتبع هذه الخطوات لتشخيص المشكلة وحلها.

#### 1. التحقق من إعداد عنوان بروتوكول الإنترنت

تأكد من استخدام عنوان IP الصحيح لجهاز Pi في الأوامر أو في الكود الخاص بك. للتحقق من عنوان IP لجهاز Raspberry Pi، قم بتشغيل الأمر التالي (على سطر أوامر Pi):

```bash
hostname -I
```

#### 2. تحقق من إمكانية الوصول إلى Pi من الحاسوب المحمول/الحاسوب الشخصي

جرّب إرسال إشارة إلى جهاز Raspberry Pi من جهازك المحمول:

```bash
ping <your_pi_ip_address>
```

إذا فشل ping:

- تأكد من أن جهاز Pi يعمل ومتصل بالشبكة نفسها.
- تحقق من تمكين SSH على Pi.

#### 3. جرّب اتصال SSH

إذا لم تتمكن من الاتصال بـ Pi عبر SSH، فقد لا يكون متصلاً بشكل صحيح. استخدم:

```bash
ssh <your_pi_user_name>@<your_pi_ip_address>
```

إذا واجهت خطأ في الاتصال:

- تأكد من تمكين SSH على Pi عن طريق تشغيل الأمر التالي:
  ```bash
  sudo raspi-config
  ```
  ثم انتقل إلى: **Interfacing Options -> SSH** وفعّله.

### المعايرة

الآن علينا معايرة ذراع القائد وذراع التابع. لا حاجة لمعايرة محركات العجلات. عملية المعايرة بالغة الأهمية لأنها تتيح لشبكة عصبية مُدرَّبة على روبوت واحد أن تعمل على روبوت آخر.

### معايرة ذراع المتابعة (على القاعدة المتنقلة)

تأكد من توصيل الذراع بـ Raspberry Pi ثم نفّذ هذا السكربت أو مثال الواجهة البرمجية (على Raspberry Pi عبر SSH) لبدء معايرة الذراع المتتبعة:

```bash
lerobot-calibrate \
    --robot.type=lekiwi \
    --robot.id=my_awesome_kiwi # <- Give the robot a unique name
```

لقد توحيّدنا طريقة المعايرة لمعظم الروبوتات، وبالتالي فإن خطوات معايرة ذراع LeKiwi هي نفسها خطوات Koch وSO101. أولاً، يجب علينا تحريك الروبوت إلى الموضع الذي يكون فيه كل مفصل في منتصف نطاق حركته، ثم نضغط على `Enter`. ثانياً، نحرك جميع المفاصل عبر نطاق حركتها الكامل. يمكن العثور على فيديو لعملية مماثلة لـSO101 كمرجع [هنا](https://huggingface.co/docs/lerobot/en/so101#calibration-video).

### الإصدار السلكي

إذا كان لديك إصدار LeKiwi **المسلكي**، يرجى تنفيذ جميع الأوامر على حاسوبك المحمول.

### معايرة الذراع الرئيسية

ثم، لمعايرة الذراع القائدة (الموصولة بالحاسوب المحمول/الحاسوب الشخصي)، نفّذ الأمر التالي من مثال واجهة برمجة التطبيقات على حاسوبك المحمول:

```bash
# Use the port of your leader arm, and give the arm a unique name with --teleop.id
lerobot-calibrate \
    --teleop.type=so100_leader \
    --teleop.port=/dev/tty.usbmodem58760431551 \
    --teleop.id=my_awesome_leader_arm
```

```python
from lerobot.teleoperators.so_leader import SO100LeaderConfig, SO100Leader

config = SO100LeaderConfig(
    port="/dev/tty.usbmodem58760431551",
    id="my_awesome_leader_arm",
)

leader = SO100Leader(config)
leader.connect(calibrate=False)
leader.calibrate()
leader.disconnect()
```

## التحكم عن بُعد في LeKiwi

> [!TIP]
> إذا كنت تستخدم جهاز Mac، فقد تحتاج إلى منح الطرفية (Terminal) إذنًا للوصول إلى لوحة المفاتيح من أجل التشغيل عن بُعد. انتقل إلى تفضيلات النظام > الأمان والخصوصية > مراقبة الإدخال، ثم حدد مربع الاختيار الخاص بالطرفية (Terminal).

للتشغيل عن بُعد، اتصل بـ Raspberry Pi عبر SSH، ثم نفّذ `conda activate lerobot` والأمر التالي:

```bash
python -m lerobot.robots.lekiwi.lekiwi_host --robot.id=my_awesome_kiwi
```

يتوقف المضيف بعد `--host.connection_time_s` ثانية (30 ثانية افتراضيًا). للجلسات الأطول، مثل تسجيل مجموعة بيانات، قم بزيادة القيمة، على سبيل المثال `--host.connection_time_s=600`.

ثم على حاسوبك المحمول، شغّل أيضًا `conda activate lerobot` وشغّل مثال الواجهة البرمجية، وتأكد من ضبط `remote_ip` و`port` الصحيحين في `examples/lekiwi/teleoperate.py`.

```bash
python examples/lekiwi/teleoperate.py
```

الآن يمكنك تحريك ذراع القائد واستخدام لوحة المفاتيح (w,a,s,d) للتقدم للأمام، والانعطاف يسارًا، والتراجع، والانعطاف يمينًا. كما يمكنك استخدام (z,x) للانعطاف يسارًا أو يمينًا. ويمكنك استخدام (r,f) لزيادة أو تقليل سرعة الروبوت المتحرك. هناك ثلاثة أوضاع للسرعة، راجع الجدول أدناه:

| وضع السرعة | السرعة الخطية (م/ث) | سرعة الدوران (درجة/ثانية) |
| ---------- | ------------------ | ---------------------- |
| سريع       | 0.3                | 90                     |
| متوسط     | 0.2                | 60                     |
| بطيء       | 0.1                | 30                     |

| المفتاح | إجراء         |
| --- | -------------- |
| W   | الانتقال إلى الأمام   |
| A   | تحريك إلى اليسار      |
| S   | التحرك إلى الخلف  |
| D   | تحريك إلى اليمين     |
| Z   | انعطف يساراً      |
| X   | انعطف يميناً     |
| R   | زيادة السرعة |
| F   | تقليل السرعة |

> [!TIP]
> إذا كنت تستخدم لوحة مفاتيح مختلفة، يمكنك تغيير المفاتيح لكل أمر في [`LeKiwiClientConfig`](https://github.com/huggingface/lerobot/blob/main/src/lerobot/robots/lekiwi/config_lekiwi.py).

### الإصدار السلكي

إذا كان لديك إصدار LeKiwi **المسلكي**، يرجى تنفيذ جميع الأوامر على حاسوبك المحمول.

## تسجيل مجموعة بيانات

بمجرد أن تتعود على التشغيل عن بُعد، يمكنك تسجيل أول مجموعة بيانات لك.

نستخدم ميزات Hugging Face hub لرفع مجموعة البيانات الخاصة بك. إذا لم تكن قد استخدمت Hub من قبل، فتأكد من قدرتك على تسجيل الدخول عبر سطر الأوامر باستخدام رمز وصول للكتابة، ويمكن توليد هذا الرمز من [إعدادات Hugging Face](https://huggingface.co/settings/tokens).

أضف رمزك إلى سطر الأوامر من خلال تنفيذ هذا الأمر:

```bash
hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
```

ثم احفظ اسم مستودع Hugging Face الخاص بك في متغير:

```bash
HF_USER=$(hf auth whoami --quiet)
echo $HF_USER
```

الآن يمكنك تسجيل مجموعة بيانات. لتسجيل الحلقات ورفع مجموعة البيانات الخاصة بك إلى المستودع، نفّذ مثال واجهة برمجة التطبيقات هذا المصمّم خصيصًا لـ LeKiwi. تأكد أولًا من تكييف `remote_ip` و`HF_REPO_ID` ومنفذ الذراع الرئيسية `port` و`TASK_DESCRIPTION` في السكربت. لتسجيل حلقات أكثر أو أطول، غيّر `NUM_EPISODES` و`EPISODE_TIME_SEC` و`RESET_TIME_SEC`، وابدأ المضيف بـ `--host.connection_time_s` يغطي الجلسة بأكملها.

```bash
python examples/lekiwi/record.py
```

#### رفع مجموعة البيانات

محليًا، يُخزَّن مجموعة بياناتك في هذا المجلد: `~/.cache/huggingface/lerobot/{repo-id}`. عند انتهاء تسجيل البيانات، ستُحمَّل مجموعة بياناتك على صفحتك في Hugging Face تحت `HF_REPO_ID` الذي حددته في السكربت (مثلًا `https://huggingface.co/datasets/${HF_USER}/lekiwi_test`)، والذي يمكنك الحصول عليه بتشغيل:

```bash
echo https://huggingface.co/datasets/${HF_USER}/lekiwi_test
```

سيتم وسم مجموعة بياناتك تلقائيًا بـ`LeRobot` ليسهل على المجتمع العثور عليها، كما يمكنك إضافة وسوم مخصصة (مثل `tutorial` في هذه الحالة).

يمكنك البحث عن مجموعات بيانات LeRobot أخرى على المنصة عن طريق البحث عن [وسوم](https://huggingface.co/datasets?other=LeRobot) `LeRobot`.

#### نصائح لجمع البيانات

بمجرد أن تصبح مرتاحًا مع تسجيل البيانات، يمكنك إنشاء مجموعة بيانات أكبر للتدريب. مهمة بداية جيدة هي الإمساك بكائن في مواقع مختلفة ووضعه في حاوية. نقترح تسجيل ما لا يقل عن 50 حلقة، بمعدل 10 حلقات لكل موقع. حافظ على ثبات الكاميرات وحافظ على سلوك إمساك متسق طوال التسجيلات. تأكد أيضًا من أن الكائن الذي تتعامل معه مرئي على الكاميرات. قاعدة إبهام جيدة هي أن تكون قادرًا على أداء المهمة بنفسك بالنظر فقط إلى صور الكاميرا.

في الأقسام التالية، ستقوم بتدريب شبكة العصبية الخاصة بك. بعد تحقيق أداء موثوق في الإمساك، يمكنك البدء في إدخال المزيد من التغيرات أثناء جمع البيانات، مثل مواقع إمساك إضافية، وتقنيات إمساك مختلفة، وتغيير مواضع الكاميرات.

تجنّب إضافة الكثير من التباين بسرعة كبيرة، فقد يعيق ذلك نتائجك.

إذا كنت ترغب في الغوص بعمق أكبر في هذا الموضوع المهم، يمكنك الاطلاع على [المقال](https://huggingface.co/blog/lerobot-datasets#what-makes-a-good-dataset) الذي كتبناه حول ما يجعل مجموعة البيانات جيدة.

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

- على نظام Linux، تعمل مفاتيح تدفق التحكم في التسجيل (مفاتيح الأسهم، Escape) على X11 وWayland وجلسات headless/SSH ما دمتَ تشغّل التسجيل من طرفية تفاعلية (مع إبقائها في حالة تركيز) — لا حاجة إلى إعداد `$DISPLAY`؛ كما تعمل الحروف المكافئة `n` / `r` / `q`. لاحظ أن **التشغيل عن بُعد عبر لوحة المفاتيح لقاعدة LeKiwi** مختلف: فهو يعتمد على واجهة خلفية للمفاتيح على مستوى النظام، وبالتالي يعمل فقط على جلسة X11، أو سطح مكتب Windows، أو macOS مع منح أذونات Accessibility/Input Monitoring — وليس على Wayland أو الأجهزة بدون واجهة رسومية. راجع [قيود pynput](https://pynput.readthedocs.io/en/latest/limitations.html#linux).

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

لإعادة تشغيل حلقة، نفّذ مثال الواجهة البرمجية أدناه، وتأكد من تغيير `remote_ip` و`port` وLeRobotDatasetId وفهرس الحلقة.

```bash
python examples/lekiwi/replay.py
```

تهانينا 🎉، روبوتك جاهز الآن لتعلم مهمة بشكل مستقل. ابدأ تدريبه من خلال قسم التدريب في هذا الشرح: [البدء مع الروبوتات الحقيقية](./il_robots)

## قيّم سياستك

لتقييم سياستك، شغّل مثال واجهة `evaluate.py`، وتأكد من تغيير `remote_ip` و`port` والنموذج..

```bash
python examples/lekiwi/evaluate.py
```

> [!TIP]
> إذا كانت لديك أي أسئلة أو كنت بحاجة إلى مساعدة، يرجى التواصل معنا عبر [Discord](https://discord.com/invite/s3KuuzsPFb).