# LeKiwi

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

Trong các bước bên dưới, chúng tôi giải thích cách lắp ráp robot di động LeKiwi.

## Tìm nguồn cung cấp linh kiện

Hãy làm theo [README](https://github.com/SIGRobotics-UIUC/LeKiwi) này. Tài liệu này chứa danh sách vật liệu, kèm liên kết để tìm mua các linh kiện, cũng như hướng dẫn in 3D các bộ phận. Nó cũng bao gồm lời khuyên nếu đây là lần đầu bạn in 3D hoặc nếu bạn không có máy in 3D.

### Phiên bản có dây

Nếu bạn có phiên bản LeKiwi **wired**, bạn có thể bỏ qua việc cài đặt Raspberry Pi và thiết lập SSH. Bạn cũng có thể chạy tất cả các lệnh trực tiếp trên PC cho cả các script LeKiwi và các script cánh tay điều khiển (leader arm) để vận hành từ xa.

## Cài đặt phần mềm trên Pi

Bây giờ chúng ta phải thiết lập PC từ xa sẽ chạy trên LeKiwi Robot. Đây thường là một Raspberry Pi, nhưng có thể là bất kỳ PC nào chạy được ở 5V và có đủ cổng usb (2 hoặc nhiều hơn) cho các camera và bo mạch điều khiển động cơ.

### Cài đặt hệ điều hành

Để cài đặt Raspberry Pi và thẻ SD của nó, xem: [Setup PI](https://www.raspberrypi.com/documentation/computers/getting-started.html). Tại đây giải thích cách tải xuống [Imager](https://www.raspberrypi.com/software/) để cài đặt Raspberry Pi OS hoặc Ubuntu.

### Cài đặt SSH

Sau khi thiết lập Pi, bạn nên bật và cấu hình [SSH](https://www.raspberrypi.com/news/coding-on-raspberry-pi-remotely-with-visual-studio-code/) (Secure Shell Protocol) để có thể đăng nhập vào Pi từ laptop mà không cần màn hình, bàn phím và chuột trên Pi. Một hướng dẫn tuyệt vời về cách thực hiện điều này có thể tìm thấy [tại đây](https://www.raspberrypi.com/documentation/computers/remote-access.html#ssh). Bạn có thể đăng nhập vào Pi qua Command Prompt (cmd) hoặc, nếu bạn sử dụng VSCode, bạn có thể dùng tiện ích mở rộng [này](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh).

### Cài đặt LeRobot trên Pi 🤗

Trên Raspberry Pi của bạn, hãy cài đặt LeRobot bằng [Hướng dẫn cài đặt](./installation) của chúng tôi

Ngoài các hướng dẫn này, bạn cần cài đặt hỗ trợ động cơ Feetech & ZeroMQ trên Pi của mình:

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

## Cài đặt LeRobot cục bộ

Nếu bạn đã cài đặt LeRobot trên laptop/máy tính của mình, bạn có thể bỏ qua bước này; nếu chưa, hãy làm theo các bước tương tự như chúng tôi đã thực hiện trên Pi.

Theo dõi [Hướng dẫn cài đặt](./installation) của chúng tôi

Ngoài các hướng dẫn này, bạn cần cài đặt hỗ trợ động cơ Feetech & ZeroMQ trên laptop/máy tính của mình:

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

Tuyệt vời 🤗! Bạn đã hoàn tất việc cài đặt LeRobot và có thể bắt đầu lắp ráp cánh tay SO100/SO101 cùng đế di động 🤖. Mỗi khi bạn muốn sử dụng LeRobot, hãy vào thư mục `~/lerobot` nơi chúng ta đã cài đặt LeRobot và chạy một trong các lệnh.

# Hướng dẫn lắp ráp từng bước

Đầu tiên, chúng ta sẽ lắp ráp hai cánh tay SO100/SO101. Một cánh tay để gắn vào đế di động và một cánh tay để điều khiển từ xa. Sau đó, chúng ta sẽ lắp ráp đế di động. Hướng dẫn lắp ráp có thể được tìm thấy trên hai trang này:

- [Lắp ráp SO101](./so101#step-by-step-assembly-instructions)
- [Lắp ráp LeKiwi](https://github.com/SIGRobotics-UIUC/LeKiwi/blob/main/Assembly.md)

### Tìm các cổng USB liên quan đến bo mạch động cơ

Để tìm cổng cho mỗi bộ điều khiển servo bus, hãy chạy script này:

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

Ví dụ về kết quả đầu ra:

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

Cổng được tìm thấy là: `/dev/tty.usbmodem575E0032081` tương ứng với bo mạch của bạn.

Trên Linux, bạn có thể cần cấp quyền truy cập vào các cổng USB bằng cách chạy:

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

Ví dụ về kết quả đầu ra:

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

Cổng được tìm thấy là: `/dev/ttyACM0` tương ứng với bo mạch của bạn.

### Cấu hình động cơ

Hướng dẫn cấu hình các động cơ có thể tìm thấy trong [tài liệu](./so101#configure-the-motors) của SO101. Ngoài các id cho động cơ cánh tay, chúng ta cũng cần thiết lập các id động cơ cho phần di động. Các id này cần được đặt theo một thứ tự cụ thể để hoạt động. Dưới đây là hình ảnh về các id động cơ và vị trí lắp đặt động cơ cho phần di động. Lưu ý rằng chúng ta chỉ sử dụng một bảng điều khiển động cơ trên LeKiwi. Điều này có nghĩa là các id động cơ cho bánh xe là 7, 8 và 9.

Bạn có thể chạy lệnh này để thiết lập động cơ cho LeKiwi. Lệnh sẽ đầu tiên thiết lập động cơ cho cánh tay (id 6..1) và sau đó thiết lập động cơ cho bánh xe (9,8,7)

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

### Xử lý sự cố liên lạc

Nếu bạn gặp khó khăn khi kết nối với LeKiwi, hãy làm theo các bước sau để chẩn đoán và khắc phục sự cố.

#### 1. Kiểm tra cấu hình địa chỉ IP

Hãy đảm bảo rằng IP chính xác của Pi được sử dụng trong các lệnh hoặc trong mã của bạn. Để kiểm tra địa chỉ IP của Raspberry Pi, hãy chạy (trên dòng lệnh của Pi):

```bash
hostname -I
```

#### 2. Kiểm tra xem Pi có thể truy cập được từ laptop/pc không

Thử ping Raspberry Pi từ máy tính xách tay của bạn:

```bash
ping <your_pi_ip_address>
```

Nếu ping thất bại:

- Đảm bảo Pi đã được bật và kết nối cùng mạng.
- Kiểm tra xem SSH có được bật trên Pi không.

#### 3. Thử kết nối SSH

Nếu bạn không thể SSH vào Pi, có thể thiết bị chưa được kết nối đúng cách. Hãy sử dụng:

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

Nếu bạn gặp lỗi kết nối:

- Đảm bảo SSH đã được bật trên Pi bằng cách chạy:
  ```bash
  sudo raspi-config
  ```
  Sau đó, điều hướng đến: **Interfacing Options -> SSH** và bật tính năng này.

### Hiệu chuẩn

Bây giờ chúng ta phải hiệu chuẩn cánh tay dẫn (leader arm) và cánh tay theo (follower arm). Các động cơ bánh xe không cần hiệu chuẩn. Quá trình hiệu chuẩn rất quan trọng vì nó cho phép một mạng nơ-ron được huấn luyện trên một robot hoạt động trên một robot khác.

### Hiệu chuẩn cánh tay theo dõi (trên cơ sở di động)

Hãy đảm bảo cánh tay đã được kết nối với Raspberry Pi và chạy script hoặc ví dụ API này (trên Raspberry Pi qua SSH) để bắt đầu hiệu chuẩn cánh tay theo dõi:

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

Chúng tôi đã thống nhất phương pháp hiệu chuẩn cho hầu hết các robot, do đó, các bước hiệu chuẩn cho cánh tay LeKiwi giống hệt với các bước cho Koch và SO101. Trước tiên, chúng ta phải di chuyển robot đến vị trí mà mỗi khớp nằm ở giữa phạm vi chuyển động của nó, sau đó nhấn `Enter`. Tiếp theo, chúng ta di chuyển tất cả các khớp qua toàn bộ phạm vi chuyển động của chúng. Một video về cùng quy trình này cho SO101 để tham khảo có thể tìm thấy [tại đây](https://huggingface.co/docs/lerobot/en/so101#calibration-video).

### Phiên bản có dây

Nếu bạn có phiên bản LeKiwi **wired**, vui lòng chạy tất cả các lệnh trên laptop của bạn.

### Hiệu chuẩn cánh tay chính

Sau đó, để hiệu chuẩn cánh tay dẫn (được gắn vào laptop/máy tính). Chạy lệnh sau của ví dụ API trên laptop của bạn:

```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()
```

## Điều khiển LeKiwi từ xa

> [!TIP]
> Nếu bạn đang sử dụng Mac, bạn có thể cần cấp quyền cho Terminal để truy cập bàn phím của bạn cho teleoperation. Vào System Preferences > Security & Privacy > Input Monitoring và đánh dấu vào ô cho Terminal.

Để điều khiển từ xa, hãy SSH vào Raspberry Pi của bạn, chạy `conda activate lerobot` và lệnh này:

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

Máy chủ sẽ dừng lại sau `--host.connection_time_s` giây (mặc định là 30). Đối với các phiên dài hơn, chẳng hạn như ghi lại một bộ dữ liệu, hãy tăng giá trị này, ví dụ `--host.connection_time_s=600`.

Sau đó, trên laptop của bạn, hãy chạy `conda activate lerobot` và chạy ví dụ API, đảm bảo bạn đã đặt đúng `remote_ip` và `port` trong `examples/lekiwi/teleoperate.py`.

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

Bây giờ bạn có thể di chuyển cánh tay leader và sử dụng bàn phím (w,a,s,d) để di chuyển về phía trước, sang trái, lùi lại, sang phải. Và sử dụng (z,x) để rẽ trái hoặc rẽ phải. Bạn có thể sử dụng (r,f) để tăng và giảm tốc độ của robot di động. Có ba chế độ tốc độ, xem bảng bên dưới:

| Chế độ Tốc độ | Tốc độ tuyến tính (m/s) | Tốc độ xoay (độ/giây) |
| ---------- | ------------------ | ---------------------- |
| Nhanh       | 0.3                | 90                     |
| Trung bình     | 0.2                | 60                     |
| Chậm       | 0.1                | 30                     |

| Khóa | Hành động         |
| --- | -------------- |
| W   | Tiếp tục   |
| A   | Di chuyển sang trái      |
| S   | Di chuyển ngược lại  |
| D   | Di chuyển sang phải     |
| Z   | Rẽ trái      |
| X   | Rẽ phải     |
| R   | Tăng tốc độ |
| F   | Giảm tốc độ |

> [!TIP]
> Nếu bạn sử dụng bàn phím khác, bạn có thể thay đổi các phím cho từng lệnh trong [`LeKiwiClientConfig`](https://github.com/huggingface/lerobot/blob/main/src/lerobot/robots/lekiwi/config_lekiwi.py).

### Phiên bản có dây

Nếu bạn có phiên bản LeKiwi **wired**, vui lòng chạy tất cả các lệnh trên laptop của bạn.

## Ghi lại một bộ dữ liệu

Khi bạn đã quen thuộc với teleoperation, bạn có thể thu thập bộ dữ liệu đầu tiên của mình.

Chúng tôi sử dụng các tính năng của Hugging Face hub để tải lên bộ dữ liệu của bạn. Nếu bạn chưa từng sử dụng Hub trước đây, hãy đảm bảo rằng bạn có thể đăng nhập qua cli bằng một token có quyền ghi, token này có thể được tạo từ [cài đặt Hugging Face](https://huggingface.co/settings/tokens).

Thêm token của bạn vào CLI bằng cách chạy lệnh này:

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

Sau đó, lưu tên kho Hugging Face của bạn vào một biến:

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

Bây giờ bạn có thể ghi lại một dataset. Để ghi các episode và tải dataset của bạn lên hub, hãy thực thi ví dụ API này được điều chỉnh cho LeKiwi. Hãy đảm bảo trước tiên bạn đã điều chỉnh `remote_ip`, `HF_REPO_ID`, `port` của cánh tay leader và `TASK_DESCRIPTION` trong script. Để ghi thêm hoặc ghi các episode dài hơn, hãy thay đổi `NUM_EPISODES`, `EPISODE_TIME_SEC` và `RESET_TIME_SEC`, và khởi động host với `--host.connection_time_s` bao phủ toàn bộ phiên.

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

#### Tải lên bộ dữ liệu

Trên máy cục bộ, tập dữ liệu của bạn được lưu trong thư mục này: `~/.cache/huggingface/lerobot/{repo-id}`. Khi kết thúc quá trình ghi dữ liệu, tập dữ liệu của bạn sẽ được tải lên trang Hugging Face của bạn dưới tên `HF_REPO_ID` mà bạn đã đặt trong script (ví dụ `https://huggingface.co/datasets/${HF_USER}/lekiwi_test`), bạn có thể lấy được bằng cách chạy:

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

Bộ dữ liệu của bạn sẽ được tự động gắn thẻ `LeRobot` để cộng đồng dễ dàng tìm thấy, và bạn cũng có thể thêm các thẻ tùy chỉnh (ví dụ như `tutorial` trong trường hợp này).

Bạn có thể tìm các bộ dữ liệu LeRobot khác trên hub bằng cách tìm kiếm các [thẻ](https://huggingface.co/datasets?other=LeRobot) `LeRobot`.

#### Mẹo thu thập dữ liệu

Khi bạn đã quen với việc ghi lại dữ liệu, bạn có thể tạo một bộ dữ liệu lớn hơn để huấn luyện. Một tác vụ khởi đầu tốt là nắm một vật thể ở các vị trí khác nhau và đặt nó vào một thùng. Chúng tôi đề xuất ghi lại ít nhất 50 tập, với 10 tập cho mỗi vị trí. Giữ các camera cố định và duy trì hành vi nắm nhất quán trong suốt quá trình ghi. Ngoài ra, hãy đảm bảo rằng vật thể bạn đang thao tác có thể nhìn thấy trên các camera. Một quy tắc thực nghiệm tốt là bạn nên có thể tự thực hiện tác vụ đó chỉ bằng cách nhìn vào hình ảnh từ camera.

Trong các phần tiếp theo, bạn sẽ huấn luyện mạng nơ-ron của mình. Sau khi đạt được hiệu suất nắm bắt đáng tin cậy, bạn có thể bắt đầu đưa vào nhiều biến thể hơn trong quá trình thu thập dữ liệu, chẳng hạn như các vị trí nắm bổ sung, các kỹ thuật nắm khác nhau và thay đổi vị trí camera.

Tránh thêm quá nhiều biến thể quá nhanh, vì điều này có thể cản trở kết quả của bạn.

Nếu bạn muốn tìm hiểu sâu hơn về chủ đề quan trọng này, bạn có thể xem [bài viết trên blog](https://huggingface.co/blog/lerobot-datasets#what-makes-a-good-dataset) mà chúng tôi đã viết về những yếu tố tạo nên một bộ dữ liệu tốt.

#### Xử lý sự cố:

- Trên Linux, các phím điều khiển luồng ghi hình (phím mũi tên, Escape) hoạt động trên X11, Wayland và các phiên headless/SSH miễn là bạn chạy ghi hình từ một terminal tương tác (giữ cho nó ở trạng thái tập trung) — không cần thiết lập `$DISPLAY`; các phím chữ tương đương `n` / `r` / `q` cũng hoạt động. Lưu ý rằng **điều khiển bàn phím cho base LeKiwi** là khác: nó dựa vào một backend phím toàn cục và do đó chỉ hoạt động trên phiên X11, desktop Windows, hoặc macOS với quyền Accessibility/Input Monitoring được cấp — không hoạt động trên Wayland hoặc các máy headless. Xem [giới hạn của pynput](https://pynput.readthedocs.io/en/latest/limitations.html#linux).

## Phát lại một tập

Để phát lại một tập, hãy chạy ví dụ API bên dưới, đảm bảo thay đổi `remote_ip`, `port`, LeRobotDatasetId và chỉ mục tập.

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

Chúc mừng 🎉, robot của bạn đã sẵn sàng để tự học một tác vụ. Bắt đầu huấn luyện nó bằng phần huấn luyện của hướng dẫn này: [Bắt đầu với robot thực tế](./il_robots)

## Đánh giá chính sách của bạn

Để đánh giá chính sách của bạn, hãy chạy ví dụ API `evaluate.py`, đảm bảo thay đổi `remote_ip`, `port`, model..

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

> [!TIP]
> Nếu bạn có bất kỳ câu hỏi nào hoặc cần hỗ trợ, vui lòng liên hệ trên [Discord](https://discord.com/invite/s3KuuzsPFb).

