# 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)。其中包含物料清单，并附有获取零件的链接，以及 3D 打印零件的说明。此外，如果你是首次进行打印或没有 3D 打印机，其中也提供了相关建议。

### 有线版本

如果您使用的是有线版 **wired** LeKiwi，则可以跳过树莓派的安装和 SSH 配置。对于 LeKiwi 脚本和用于遥操作的 leader arm 脚本，您也可以在 PC 上直接运行所有命令。

## 在 Pi 上安装软件

现在我们需要配置将在 LeKiwi Robot 上运行的远程 PC。这通常是一块 Raspberry Pi，但也可以是任何能在 5V 下运行且拥有足够 USB 端口（2 个或更多）以连接摄像头和电机控制板的 PC。

### 安装操作系统

有关设置 Raspberry Pi 及其 SD 卡的说明，请参阅：[Setup 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/)（安全外壳协议），以便无需在 Pi 上连接屏幕、键盘和鼠标即可从笔记本电脑登录。有关如何操作的优质教程，请参见[此处](https://www.raspberrypi.com/documentation/computers/remote-access.html#ssh)。您可以通过命令提示符（cmd）登录 Pi，或者如果您使用 VSCode，可以使用[此](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)扩展。

### 在 Pi 上安装 LeRobot 🤗

在您的 Raspberry Pi 上，使用我们的[安装指南](./installation)安装 LeRobot

除了这些说明之外，您还需要在 Pi 上安装 Feetech 电机支持 & ZeroMQ：

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

## 在本地安装 LeRobot

如果您已在笔记本电脑/台式机上安装了 LeRobot，可以跳过此步骤；否则，请按照我们在 Pi 上执行的相同步骤进行操作。

请遵循我们的[安装指南](./installation)

除了这些说明之外，您还需要在笔记本电脑/PC 上安装 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`，对应您的开发板。

在 Linux 上，您可能需要运行以下命令来授予 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 [文档](./so101#configure-the-motors)。除了机械臂电机的 id 之外，我们还需要设置移动底盘的电机 id。这些 id 必须按照特定顺序排列才能正常工作。下图展示了移动底盘的电机 id 及其安装位置。请注意，LeKiwi 上仅使用一块电机控制板。这意味着轮子的电机 id 为 7、8 和 9。

您可以运行此命令来为 LeKiwi 设置电机。它将首先设置手臂的电机（id 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 地址配置

请确保在命令或代码中使用了树莓派的正确 IP 地址。要查看树莓派的 IP 地址，请在（树莓派命令行上）运行：

```bash
hostname -I
```

#### 2. 检查 Pi 是否可从笔记本电脑/PC 访问

尝试从笔记本电脑向 Raspberry Pi 发送 ping 命令：

```bash
ping <your_pi_ip_address>
```

如果 ping 失败：

- 确保 Pi 已通电并连接到同一网络。
- 检查 Pi 上是否已启用 SSH。

#### 3. 尝试 SSH 连接

如果无法通过 SSH 连接到 Pi，则可能未正确连接。请使用：

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

如果出现连接错误：

- 通过运行以下命令确保 Pi 上已启用 SSH：
  ```bash
  sudo raspi-config
  ```
  然后导航至：**Interfacing Options -> SSH** 并启用它。

### 校准

现在我们需要校准主臂和从臂。轮式电机无需校准。校准过程非常重要，因为它能让在一个机器人上训练的神经网络在另一个机器人上正常工作。

### 校准从动臂（在移动底盘上）

确保机械臂已连接到 Raspberry Pi，然后通过 SSH 在 Raspberry Pi 上运行此脚本或 API 示例，以启动从动臂的校准：

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

### 有线版本

如果您使用的是有线连接的 **wired** LeKiwi 版本，请在您的笔记本电脑上运行所有命令。

### 校准主臂

然后，为了校准主臂（连接在笔记本电脑/台式机上），请在您的笔记本电脑上运行以下 API 示例命令：

```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）的复选框。

要进行遥操作，请通过 SSH 连接到您的 Raspberry Pi，然后运行 `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` 并运行 API 示例，请确保在 `examples/lekiwi/teleoperate.py` 中设置了正确的 `remote_ip` 和 `port`。

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

现在你可以移动机械臂，并使用键盘（w,a,s,d）控制前进、左转、后退、右转。使用（z,x）向左或向右转向。你可以使用（r,f）增加或降低移动机器人的速度。共有三种速度模式，详见下表：

| 速度模式 | 线性速度（m/s） | 旋转速度（度/秒） |
| ---------- | ------------------ | ---------------------- |
| 快速       | 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) 中更改每个命令对应的按键。

### 有线版本

如果您使用的是有线连接的 **wired** LeKiwi 版本，请在您的笔记本电脑上运行所有命令。

## 记录数据集

熟悉遥操作后，您就可以录制第一个数据集了。

我们使用 Hugging Face hub 功能来上传您的数据集。如果您之前未使用过 Hub，请确保能够通过 cli 使用具有写入权限的 token 登录，该 token 可以从 [Hugging Face 设置](https://huggingface.co/settings/tokens) 中生成。

运行以下命令将您的令牌添加到 CLI 中：

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

然后将您的 Hugging Face 仓库名称存储在一个变量中：

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

现在您可以录制数据集。要录制 episode 并将数据集上传到 hub，请运行此专为 LeKiwi 定制的 API 示例。请务必先在脚本中调整 `remote_ip`、`HF_REPO_ID`、leader arm 的 `port` 以及 `TASK_DESCRIPTION`。若要录制更多或更长的 episode，请修改 `NUM_EPISODES`、`EPISODE_TIME_SEC` 和 `RESET_TIME_SEC`，并以能够覆盖整个会话的 `--host.connection_time_s` 启动 host。

```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`）。

您可以在 hub 上搜索 `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 以及无头/SSH 会话中正常工作——无需配置 `$DISPLAY`；字母等效键 `n` / `r` / `q` 也可用。请注意，**LeKiwi 底盘的键盘遥操作** 有所不同：它依赖于全局按键后端，因此仅在 X11 会话、Windows 桌面，或已授予辅助功能/输入监控权限的 macOS 上可用——在 Wayland 或无头机器上不可用。参见 [pynput 限制](https://pynput.readthedocs.io/en/latest/limitations.html#linux)。

## 重放一个回合

要重放某一集，请运行下方的 API 示例，并确保修改 `remote_ip`、`port`、LeRobotDatasetId 以及 episode 索引。

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

恭喜 🎉，你的机器人已准备好自主学习任务。通过本教程的训练部分开始训练它：[使用真实机器人入门](./il_robots)

## 评估您的策略

要评估您的策略，请运行 `evaluate.py` API 示例，并确保修改 `remote_ip`、`port`、model..

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

> [!TIP]
> 如果您有任何问题或需要帮助，请在 [Discord](https://discord.com/invite/s3KuuzsPFb) 上联系我们。