# Isaac Teleop

Điều khiển robot của bạn bằng NVIDIA [Isaac Teleop](https://github.com/NVIDIA/IsaacTeleop), một khung làm việc teleoperation đa phương thức. Isaac Teleop điều khiển một phiên `TeleopSession` duy nhất từ nhiều loại thiết bị đầu vào khác nhau — bộ điều khiển XR (VR), theo dõi tay, theo dõi toàn thân, găng tay Manus, bàn đạp chân và nhiều hơn nữa.

Trong LeRobot, Isaac Teleop được đóng gói dưới dạng một ví dụ tự chứa trong [`examples/isaac_teleop_to_so101/`](https://github.com/huggingface/lerobot/tree/main/examples/isaac_teleop_to_so101). Mỗi thiết bị nhập của Isaac Teleop là một lớp con `Teleoperator` riêng trong gói `isaac_teleop` của ví dụ, chia sẻ chung một vòng đời phiên (xem `IsaacTeleopTeleoperator`). Các thiết bị có sẵn hiện nay là **XR controller** (`XRController`) và một cánh tay dẫn **SO-101 leader arm** có thể kéo ngược (`SO101LeaderArm`); găng tay Manus và theo dõi tay/toàn thân là các thiết bị tiếp theo một cách tự nhiên. Hướng dẫn này tập trung vào XR controller; cánh tay dẫn SO-101 được tóm tắt dưới [Chạy ví dụ](#step-3-run-the-example).

**Trong hướng dẫn này, bạn sẽ học được:**

- Cách thiết bị Isaac Teleop điều khiển mục tiêu đầu cuối (EE) của robot
- Cách mà _clutch_ (nút bóp/nắm trên bộ điều khiển XR) kích hoạt điều khiển từ xa mà không làm cánh tay giật
- Cách chạy ví dụ điều khiển từ xa SO‑101 và tinh chỉnh chuyển động / kẹp / IK

## Cài đặt

Ví dụ nằm trong kho LeRobot (không phải một phần của gói pip `lerobot`), vì vậy hãy clone kho và cài đặt từ mã nguồn. Tài liệu tham khảo về cài đặt và sử dụng chính thức, luôn được cập nhật là [`README.md`](https://github.com/huggingface/lerobot/tree/main/examples/isaac_teleop_to_so101/README.md) của ví dụ; tóm lại:

```bash
git clone https://github.com/huggingface/lerobot.git
cd lerobot
uv pip install -e ".[feetech,kinematics,dataset]" "huggingface_hub>=1.5"
uv pip install "isaacteleop[cloudxr,retargeters-lite]~=1.3.131" "scipy>=1.14"
```

`isaacteleop` được phát hành trên PyPI công khai (chỉ hỗ trợ Linux). Extra `cloudxr` cung cấp các ràng buộc runtime của CloudXR; `retargeters-lite` là đường dẫn retargeter dựa trên scipy, có thể giải quyết trên cả kiến trúc x86_64 và ARM (trên aarch64 — ví dụ như DGX Spark — extra `retargeters` đầy đủ không thể giải quyết được do các ràng buộc `dex-retargeting`/`nlopt` của nó, đây là lý do nó không phải là mặc định ở đây). Trên x86_64, bạn có thể cài đặt thêm toàn bộ stack retargeter:

```bash
uv pip install "isaacteleop[retargeters]~=1.3.131"
```

### Cài đặt CloudXR và kết nối thiết bị đeo

Isaac Teleop truyền trực tiếp dữ liệu từ headset đến máy của bạn qua **NVIDIA CloudXR**, thành phần cung cấp runtime OpenXR mà phiên làm việc sẽ kết nối tới. Mặc định, LeTeleop sẽ **tự động khởi động runtime CloudXR cho bạn** khi bạn gọi `teleop_device.connect()` — bạn không còn phải chạy `python -m isaacteleop.cloudxr` và `source cloudxr.env` trong một shell riêng. Tất cả những gì bạn cần là một headset tương thích đã được kết nối và các cổng firewall của CloudXR được mở. Hãy làm theo [Quick Start](https://nvidia.github.io/IsaacCapture/main/getting_started/quick_start.html) của Isaac Teleop để biết chi tiết về ghép nối headset và cấu hình firewall.

**Chạy lần đầu (EULA).** Lần khởi động đầu tiên phải chấp nhận EULA của NVIDIA CloudXR. Việc tự động khởi động sẽ yêu cầu chấp nhận **trên stdin**, do đó trên máy không có giao diện người dùng, nó sẽ treo chờ nhập liệu. Hãy khởi tạo EULA một lần, tương tác, bằng cách:

```bash
python -m isaacteleop.cloudxr --accept-eula   # one-time: accept the CloudXR EULA
```

Sau đó, `connect()` khởi động runtime theo chế độ không tương tác. Quá trình khởi động **chặn trong khoảng 30 giây** trong khi runtime được khởi động.

**Cấu hình.** Hai trường trong `IsaacTeleopConfig` (được chia sẻ bởi mọi thiết bị) kiểm soát điều này:

- `auto_launch_cloudxr` (mặc định `True`) — xác định xem `connect()` có khởi động runtime hay không. Đặt `False` khi CloudXR đã đang chạy từ bên ngoài.
- `cloudxr_env_file` (mặc định `None`) — một tệp `.env` tùy chọn chứa hồ sơ thiết bị CloudXR để chọn phương thức truyền tải cho kính thực tế ảo (ví dụ: hồ sơ Apple Vision Pro). Đây là **đầu vào** của trình khởi chạy; nó không phải là tệp **đầu ra** `~/.cloudxr/run/cloudxr.env` mà quy trình thủ công cũ yêu cầu bạn `source`. `None` giữ nguyên hồ sơ auto-WebRTC mặc định — mặc dù ví dụ SO-101 ghi đè nó thành `default.env` được cung cấp cùng với `teleoperate.py`, trừ khi bạn truyền `--teleop.cloudxr_env_file`.

**Từ chối.** Để bỏ qua việc tự động khởi chạy (CloudXR đã đang chạy), hãy đặt `auto_launch_cloudxr=False` hoặc xuất:

```bash
export LEROBOT_CLOUDXR_SKIP_AUTOLAUNCH=1
```

**Biến môi trường có ưu tiên cao hơn trường cấu hình**: nếu `LEROBOT_CLOUDXR_SKIP_AUTOLAUNCH=1` được đặt, quá trình tự động khởi động sẽ bị bỏ qua ngay cả khi `auto_launch_cloudxr=True`. Biến này **độc lập** với `ISAACLAB_CXR_SKIP_AUTOLAUNCH` của Isaac Lab — việc đặt một biến không ảnh hưởng đến biến kia.

**Mỗi tiến trình chỉ có một teleoperator.** Runtime CloudXR cấu hình môi trường cho toàn bộ tiến trình (một singleton), do đó hãy chạy một teleoperator Isaac Teleop duy nhất cho mỗi tiến trình.

**Đang tắt.** Luôn gọi `teleop_device.disconnect()` khi thoát — kể cả khi nhấn Ctrl-C. Bọc vòng lặp teleoperation của bạn trong `try/finally` và gọi `disconnect()` trong khối `finally`. Thao tác này sẽ hủy phiên OpenXR **trước** khi runtime CloudXR bị hủy, đây là thứ tự bắt buộc; hook `atexit` của launcher chỉ thu dọn runtime và không chạy `__exit__` của phiên, do đó nếu không gọi `disconnect()` một cách tường minh, một lần chạy bị gián đoạn sẽ tắt theo thứ tự sai.

```python
teleop_device.connect()
try:
    while True:
        action = teleop_device.get_action()
        # ... drive the robot ...
finally:
    teleop_device.disconnect()
```

Xem [Yêu cầu hệ thống](https://nvidia.github.io/IsaacCapture/main/references/requirements.html) để biết các phiên bản OS / GPU / CloudXR và thiết bị đeo được hỗ trợ.

## Cách hoạt động

Bộ điều khiển XR là một thiết bị **đầu vào** của Isaac Teleop. `XRController` là một trình đọc mỏng một cách có chủ đích: nó phơi bày tư thế nắm (grip pose) **gốc** của bộ điều khiển — đã được đặt lại gốc tĩnh vào hệ quy chiếu gốc của robot — cùng với các giá trị tương tự của nút bóp (squeeze) và cò (trigger). Nó không có **bộ tái định hướng** (retargeter) nào và cũng không có **logic clutch** riêng. Logic clutch (khóa engage + đặt lại gốc delta lên EE) và ánh xạ gắp (gripper mapping) nằm ở phía hạ nguồn trong vòng lặp ví dụ, sau đó cung cấp dữ liệu cho đường ống IK Cartesian vòng kín có sẵn của LeRobot — cùng đường ống mà người vận hành qua điện thoại sử dụng. Các phần cụ thể cho thiết bị là `XRController`, `Clutch` của vòng lặp và `MapXRControllerActionToRobotAction`; mọi thứ ở phía hạ nguồn (`EEBoundsAndSafety`, `InverseKinematicsEEToJoints`) đều được dùng chung, và một thiết bị trong tương lai (ví dụ găng tay Manus) sẽ thay thế bằng `teleop_<device>.py` + bộ xử lý của riêng nó trong khi tái sử dụng phần còn lại.

`XRController._build_pipeline` kết nối `ControllersSource` của Isaac Teleop — được rebase tĩnh vào hệ tọa độ gốc của robot bởi `ControllerTransform` (`base_T_anchor`) — và phơi bày luồng điều khiển đã biến đổi nguyên văn. `get_action()` đọc trực tiếp tư thế grip, squeeze và trigger từ luồng đó; phiên luôn được bước ở trạng thái `RUNNING` (không có clutch retargeter nào để kiểm soát).

Lớp `Clutch` (trong `examples/isaac_teleop_to_so101/isaac_teleop/clutch.py`, được điều khiển bởi vòng lặp trong `common.py`) mô phỏng `SO101ClutchRetargeter` của Isaac Teleop, nhưng nằm trong vòng lặp để thiết bị có thể chỉ đóng vai trò là bộ đọc mỏng:

- Nó khóa điểm gốc engage tại **cạnh engage** của squeeze (khung hình mà squeeze lần đầu vượt qua `clutch_threshold`) và đặt lại gốc cho cả vị trí lẫn hướng xoay quanh điểm đó, nhờ vậy việc engage không làm cánh tay bị dịch chuyển tức thời. `Clutch.rebase` trả về mục tiêu tuyệt đối trong hệ tọa độ gốc dưới dạng cặp `(pos, quat)`, sau đó vòng lặp ghép chúng thành `ee_pose` 7 chiều để đưa vào bộ xử lý.
- Cò tương tự trở thành độ `closedness` của kẹp trong `[0, 1]` (0 = mở, 1 = đóng), tỷ lệ thuận với mức kéo cò, và `MapXRControllerActionToRobotAction` ánh xạ giá trị này thành mục tiêu hàm.

Xem [Giao diện Retargeting](https://nvidia.github.io/IsaacCapture/main/references/retargeting/index.html) và [tổng quan kiến trúc](https://nvidia.github.io/IsaacCapture/main/overview/architecture.html) của Isaac Teleop để biết cách các nút nguồn và bộ retargeter được kết hợp.

```text
  VR controller (OpenXR)
        │
        ▼
  XRController.get_action()          ── raw base-frame grip_pos / grip_quat + squeeze + trigger
        │                                (TeleopSession always stepped RUNNING; clutch lives downstream)
        ▼
  Clutch.rebase(grip_pos, grip_quat) ── engage-relative delta applied to the EE home (pos + orient)
        │  ee_pose (7) / closedness       → absolute ee_pose; closedness = trigger
        ▼
  MapXRControllerActionToRobotAction ── absolute ee.x/y/z; ee.w* = orientation rotvec target;
        │  ee.x/y/z / ee.w* / ee.gripper_pos   ee.gripper_pos = (1 - closedness) * 100
        ▼
  EEBoundsAndSafety                ── workspace clip + per-frame step clamp (clamp+warn)
        │
        ▼
  InverseKinematicsEEToJoints      ── closed-loop Placo IK; position + soft-orientation
        │  (orientation_weight=0.01)   (passes ee.gripper_pos → gripper.pos)
        ▼
  SO-101 follower joint targets
```

### Bộ ly hợp: do vòng lặp ví dụ sở hữu

Khác với pipeline điện thoại (nơi clutch được chia giữa `MapPhoneActionToRobotAction` và `EEReferenceAndDelta`), clutch XR nằm hoàn toàn trong lớp `Clutch` của vòng lặp ví dụ. Nó phát ra tư thế EE **tuyệt đối**, do đó không có giai đoạn `EEReferenceAndDelta` và không có tích lũy delta trong bộ xử lý — `MapXRControllerActionToRobotAction` là ánh xạ thuần túy, không trạng thái cho từng khung hình.

Cơ cấu clutch khóa điểm gốc engage tại **cạnh engage** của thao tác bóp (khoảnh khắc thao tác bóp vượt qua `clutch_threshold`) và điều khiển EE từ chuyển động _tương đối_ so với điểm gốc đó, nhờ đó cánh tay không bị dịch chuyển tức thời khi engage. Ở **mọi** lần engage — cả khi khởi động lẫn khi clutch lại giữa tác vụ — vị trí _position_ gốc được khóa từ động học thuận trên **khớp đo được** của cánh tay, nên vị trí gốc trùng khớp với nơi cánh tay đang thực sự ở ngay cả khi nó đã di chuyển trong lúc disengage, và thao tác engage không gây nhảy vị trí. _orientation_ gốc giữ nguyên góc xoay được lệnh cuối: cánh tay 5-DOF chỉ theo dõi hướng một cách mềm, nên việc khóa hướng cổ tay đo được sẽ đưa sai số theo dõi của nó vào lệnh điều khiển ở mỗi lần clutch lại.

## Điều khiển

- **Ép / nắm** — **phan ly hợp** (deadman). Giữ nó vượt quá `clutch_threshold` để kích hoạt điều khiển từ xa; thả ra để tạm dừng. Mỗi lần kích hoạt sẽ ghi nhận lại điểm gốc, cho phép bạn di chuyển tay trong khi tạm dừng và kích hoạt lại mà cánh tay không bị giật (kiểu index/clutch).
- **Trigger** — **gripper**, điều khiển **analog**. Hàm theo dõi trigger một cách tỷ lệ — trigger nhấn một nửa để hàm đóng một nửa — thông qua độ đóng trong `[0, 1]` (0 = mở, 1 = đóng) được ánh xạ sang mục tiêu khớp gripper tuyệt đối.
- **Định hướng tay cầm** — **cổ tay**. Clutch tái chuẩn hóa định hướng tay cầm (tương đối engage, khung gốc) thành một mục tiêu định hướng IK mềm mà cổ tay bám theo cùng với vị trí. Trên 5‑DOF SO‑101, cổ tay chỉ bám theo tay một phần theo thiết kế — xem `orientation_weight` bên dưới.

## Bắt đầu

### Bước 1: Tạo teleoperator

```python
# Run from the repo root so the `examples` package is importable.
from examples.isaac_teleop_to_so101.isaac_teleop import XRController, XRControllerConfig

teleop_config = XRControllerConfig(
    hand_side="right",      # "left" or "right" controller
    clutch_threshold=0.5,   # squeeze value above which the clutch engages
)
teleop_device = XRController(teleop_config)
```

`XRController.get_action()` trả về tư thế điều khiển **gốc** của khung cơ sở, không phải mục tiêu đã được đặt lại bằng clutch: `grip_pos` (3,) `[x, y, z]` [m] và `grip_quat` (4,) `[qx, qy, qz, qw]` trong khung cơ sở của robot, cùng các giá trị tương tự vô hướng `squeeze` và `trigger` trong `[0, 1]`. Vòng lặp trong ví dụ sử dụng `Clutch` để chuyển đổi các giá trị này thành `ee_pose` tuyệt đối, và giá trị squeeze được vòng lặp so sánh với `clutch_threshold` để kích hoạt.

### Bước 2: Kết nối

Việc gọi `teleop_device.connect()` trước tiên sẽ tự động khởi động runtime CloudXR (trừ khi bạn đã chọn không tham gia — xem [Cài đặt CloudXR và kết nối headset](#set-up-cloudxr-and-connect-a-headset); bước này chặn trong khoảng 30 giây và ở lần chạy đầu tiên sẽ yêu cầu chấp nhận EULA trên stdin), sau đó khởi động [`TeleopSession`](https://nvidia.github.io/IsaacCapture/main/getting_started/teleop_session.html) của Isaac Teleop (mở phiên OpenXR và phát hiện các bộ điều khiển). Các bộ điều khiển XR tự hiệu chuẩn, vì vậy không có bước hiệu chuẩn thủ công — cơ chế clutch xử lý việc căn lại tâm mỗi khi bạn kích hoạt. Kết hợp `connect()` với `try/finally` gọi `disconnect()` để phiên được gỡ bỏ trước khi runtime kết thúc/Ctrl-C.

### Bước 3: Chạy ví dụ

Ví dụ này giả định rằng bạn đã cấu hình robot (SO‑101 follower) và thiết lập đúng cổng serial.

**URDF của robot và các mesh của nó được tải về tự động** ở lần chạy đầu tiên: thiết bị XR sẽ tải URDF của SO-101 từ [bucket Hugging Face `lerobot/robot-urdfs`](https://huggingface.co/buckets/lerobot/robot-urdfs/tree/so101) vào bộ nhớ đệm LeRobot (`HF_LEROBOT_HOME/robot-urdfs/so101/`) và tái sử dụng sau đó, nên không có bước tải riêng biệt:

```bash
python -m examples.isaac_teleop_to_so101.teleoperate --robot.type=so101_follower --robot.port=/dev/ttyACM0 \
    --robot.id=so101_follower_arm --teleop.type=xr_controller
```

CLI có phong cách `lerobot-teleoperate` (draccus): `--robot.*` cấu hình follower SO-101 và `--teleop.type` chọn thiết bị đầu vào Isaac (`xr_controller` | `so101_leader`), với `--teleop.*` là các thông số thiết bị. `--teleop.type=xr_controller` chạy luồng điều khiển bằng XR-controller như đã mô tả ở trên. Hợp đồng an toàn khi khởi động: mặc định, hệ thống sẽ di chuyển tất cả các khớp đến tư thế đặt lại mặc định trong `--reset_duration` giây (`--reset_to_origin=false` giữ cánh tay ở vị trí hiện tại), sau đó đặt vị trí gốc của clutch từ tư thế đo được của cánh tay để lần gắn kết đầu tiên không bị giật; follower chỉ được ra lệnh khi clutch đang ở trạng thái gắn kết.

**Tùy chỉnh tư thế reset.** Tư thế reset được cung cấp như mặc định tích hợp (một tư thế trung bình thoải mái) và hoạt động ngay lập tức — bạn **không** cần ghi lại bất cứ thứ gì. Để điều chỉnh cho phù hợp với thiết lập của bạn, hãy điều khiển tay cơ về tư thế mong muốn và chạy `python -m examples.isaac_teleop_to_so101.override_reset_pose --id <robot.id>`; lệnh này sẽ ghi các khớp hiện tại vào một tệp riêng cho từng cánh tay trong bộ nhớ đệm LeRobot (`HF_LEROBOT_HOME/reset_poses/<robot.name>/<robot.id>.json`, được đánh khóa giống như hiệu chuẩn), sau đó tệp này sẽ có ưu tiên cao hơn mặc định tích hợp trong lần chạy tiếp theo. Vì tệp này nằm trong bộ nhớ đệm cục bộ của người dùng (không phải trong repo), bản ghi đè của bạn sẽ được giữ trên máy của bạn, và cả `teleoperate` lẫn `record` đều tuân theo nó khi được khởi chạy với cùng `--robot.id`.

Thiết bị còn lại, `--teleop.type=so101_leader`, sao chép 1:1 thiết bị theo dõi từ cánh tay _leader_ SO-101 có thể back-drive, trong đó các khớp được stream bởi plugin `so101_leader` native của Isaac Teleop (không có clutch, không có IK — leader và follower dùng chung động học SO-101).

Binary `so101_leader_plugin` là một plugin C++ **không** nằm trong gói pip `isaacteleop` — bạn cần biên dịch nó từ cây mã nguồn Isaac Teleop. Hãy làm theo [Build Isaac Teleop from source](https://nvidia.github.io/IsaacCapture/main/getting_started/build_from_source/index.html) (tóm lại, từ thư mục checkout Isaac Teleop của bạn: `cmake -B build && cmake --build build --parallel && cmake --install build`); quá trình biên dịch sẽ cài đặt các plugin vào `/install/plugins/`, do đó binary sẽ nằm tại `install/plugins/so101_leader/so101_leader_plugin` — đây là đường dẫn cho `--launch_plugin` bên dưới. Xem `README.md` riêng của plugin (nằm cạnh binary) để biết chi tiết về cổng serial và hiệu chuẩn.

Chỉ định `--teleop.port` đến cổng serial của thiết bị điều khiển vật lý và `--launch_plugin` đến binary của plugin đó để script khởi tạo plugin sau khi CloudXR đã sẵn sàng:

```bash
python -m examples.isaac_teleop_to_so101.teleoperate --robot.type=so101_follower --robot.port=/dev/ttyACM0 \
    --robot.id=so101_follower_arm --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 --teleop.id=so101_leader_arm \
    --launch_plugin=/code/Teleop/install/plugins/so101_leader/so101_leader_plugin
```

(Lưu ý `so101_leader` ở đây là leader _Isaac_, được phân giải đối với registry thiết bị Isaac Teleop, khác với serial `so101_leader` của `lerobot-teleoperate`.) Khi `--teleop.port` được đặt, hiệu chuẩn tick→radian của plugin sẽ được suy ra từ `--teleop.id` và được truyền vào plugin dưới dạng đối số vị trí thứ ba — tệp JSON định dạng LeRobot tại `HF_LEROBOT_CALIBRATION/teleoperators/so_leader/<id>.json`, cùng tệp mà leader SO-101 qua serial sử dụng (`lerobot-calibrate --teleop.type=so101_leader --teleop.id=<id>`). Nếu tệp này thiếu, script sẽ cảnh báo và plugin sẽ sử dụng các giá trị mặc định tích hợp. Chạy `python -m examples.isaac_teleop_to_so101.teleoperate --help` để xem tất cả các cờ. Hợp đồng an toàn khi khởi động của nó: mặc định, follower sẽ được điều chỉnh (slew) đến lần đọc đầu tiên của leader trong `--align_duration` giây (`--align=false` để bỏ qua) để cánh tay không bị giật khi mirror bắt đầu, và trong khi luồng leader bị lỗi thời (stale), follower sẽ được giữ ở tư thế đã đo.

Việc lấy URDF sử dụng `huggingface_hub` (đã là một dependency của LeRobot) đối với bucket công khai `lerobot/robot-urdfs`, nên không cần đăng nhập. Nó được cache dưới `HF_LEROBOT_HOME/robot-urdfs/so101/`; xóa thư mục đó để buộc tải lại.

Sau đó, trên thiết bị đeo của bạn: bóp và giữ cần nắm để kích hoạt, di chuyển tay cầm để điều khiển cánh tay, xoay/ghiêng nó để định hướng cổ tay, và nhấn cò để đóng kẹp (theo tỷ lệ — thả ra để mở).

Để ghi lại một tập dữ liệu (không chỉ điều khiển từ xa), hãy dùng `record.py` trong cùng thư mục. Nó phân phối theo `--teleop.type` (`xr_controller` | `so101_leader`) y hệt như `teleoperate.py`, nên bất kỳ thiết bị nào cũng có thể điều khiển follower, và nó lưu các khớp được lệnh vào một tập dữ liệu LeRobot (các cờ `--dataset.*` theo kiểu `lerobot-record`). Xem docstring của module để biết CLI đầy đủ và các phím tắt ghi bằng bàn phím.

## Các bước và tùy chọn quan trọng của pipeline

Clutch đã tạo ra tư thế khung gốc tuyệt đối, do đó phía processor là một đường dẫn **tư thế tuyệt đối** mỏng — không có ánh xạ lại khung, không có tích lũy delta và không có giai đoạn `EEReferenceAndDelta`.

- `MapXRControllerActionToRobotAction` là ánh xạ không trạng thái theo từng khung hình từ đầu ra của thiết bị sang hợp đồng đầu vào IK. Nó ghi vị trí tuyệt đối trong hệ tọa độ gốc, mã hóa hướng tuyệt đối dưới dạng rotvec đích và đảo chiều độ đóng để tạo ra mục tiêu gắp cho động cơ:

  ```python
  action["ee.x"], action["ee.y"], action["ee.z"] = ee_pose[:3]   # absolute, base frame [m]
  action["ee.wx"], action["ee.wy"], action["ee.wz"] = orient_rotvec  # orientation target (rotvec)
  action["ee.gripper_pos"] = (1 - closedness) * 100   # motor units; SO-101 calibrates 100 = open
  ```

  Cực tính của kẹp (`100 = open, 0 = closed`) là một quy ước hiệu chuẩn phần cứng trong mã nguồn gốc — hãy đảo ngược nó ở đó nếu hàm mở ra khi đáng lẽ phải đóng.

- `EEBoundsAndSafety` kẹp EE trong một vùng làm việc và giới hạn tốc độ nhảy theo từng khung hình. Cơ chế chống dịch chuyển tức thời của clutch giữ cho các khung hình nhỏ, do đó `max_ee_step_m` chủ yếu bắt các lỗi theo dõi tạm thời của bộ điều khiển. Sàn z là `0.0` (mặt phẳng bàn) để một mục tiêu lạc không thể đẩy EE xuống dưới bàn; x/y vẫn giữ trong hộp `[-1, 1]` m lỏng lẻo. Đặt `raise_on_jump=False` để một khung hình vượt giới hạn sẽ bị **kẹp và cảnh báo** thay vì gây lỗi — một sự cố giữa vòng lặp sẽ khiến cánh tay mất kiểm soát:

  ```python
  EEBoundsAndSafety(
      end_effector_bounds={"min": [-1.0, -1.0, 0.0], "max": [1.0, 1.0, 1.0]},
      max_ee_step_m=0.10,
      raise_on_jump=False,
  )
  ```

- `InverseKinematicsEEToJoints(initial_guess_current_joints=False, orientation_weight=0.01)` giải bài toán IK Placo dạng vòng kín. Vì SO‑101 là cánh tay 5‑DOF nên IK thiên về vị trí; giá trị `orientation_weight` nhỏ cho phép nó bám mềm vào mục tiêu hướng đi kèm trong `ee.w*` để cổ tay theo dõi bàn tay, trong khi roll chưa xác định đầy đủ vẫn chỉ được giải một phần theo thiết kế. Không có **lớp** `GripperVelocityToJoint`: giá trị tuyệt đối `ee.gripper_pos` được truyền thẳng tới `gripper.pos`. Tham số `initial_guess_current_joints=False` khởi tạo ấm mỗi lần giải từ **giải pháp IK trước đó** thay vì gieo lại từ các khớp đo được, nhờ đó quỹ đạo khớp liên tục giữa các khung hình. Hãy tinh chỉnh `orientation_weight` trên phần cứng — quá cao sẽ gây xung đột với việc bám vị trí, quá thấp sẽ bỏ qua lệnh hướng.

Ví dụ cũng kiểm soát an toàn ở cấp độ vòng lặp: sau khi hoàn tất quá trình đưa về vị trí gốc (bật mặc định — truyền `--reset_to_origin=false` để giữ cánh tay ở vị trí hiện tại), nó chỉ ra lệnh cho robot **khi clutch đang được khóa**, và gửi lại các khớp đã đo khi clutch đang mở, nhờ đó việc nhả clutch sẽ giữ cánh tay đứng yên tại chỗ.

Xem hướng dẫn [Processors for Robots and Teleoperators](./processors_robots_teleop) để biết thêm về việc điều chỉnh pipeline cho các robot khác.

## Xử lý sự cố

- **`ModuleNotFoundError: isaacteleop`** — gói `isaacteleop` chưa được cài đặt trong môi trường đang hoạt động. Chạy lại lệnh cài đặt ở đầu hướng dẫn này: `uv pip install "isaacteleop[cloudxr,retargeters-lite]~=1.3.131"`.
- **Không tìm thấy bộ điều khiển nào** — hãy đảm bảo rằng runtime CloudXR đang chạy, các cổng tường lửa đã được đưa vào danh sách trắng và thiết bị đeo đã được kết nối (xem [Cài đặt CloudXR và kết nối thiết bị đeo](#set-up-cloudxr-and-connect-a-headset) và [Quick Start](https://nvidia.github.io/IsaacCapture/main/getting_started/quick_start.html) của Isaac Teleop).
- **CloudXR auto-launch thất bại** — `connect()` sẽ ném ra `RuntimeError` nếu runtime không khởi động được trong thời gian chờ khởi động. Kiểm tra nhật ký của launcher tại `~/.cloudxr/logs`. Các nguyên nhân phổ biến: EULA chưa bao giờ được chấp nhận (chạy `python -m isaacteleop.cloudxr --accept-eula` một lần, tương tác — auto-launch sẽ hỏi trên stdin và treo khi chạy headless), hoặc runtime đã đang chạy từ bên ngoài (đặt `LEROBOT_CLOUDXR_SKIP_AUTOLAUNCH=1` hoặc `auto_launch_cloudxr=False` để bỏ qua auto-launch).
- **Cánh tay không di chuyển** — bộ ly hợp là loại deadman: bạn phải giữ thao tác bóp/nắm vượt qua `clutch_threshold`. Hãy hạ thấp ngưỡng này nếu thao tác bóp của bộ điều khiển được báo cáo ở mức yếu.
- **Chuyển động có vẻ lệch** — hãy kiểm tra hướng của thiết bị đeo/không gian chơi. Luồng điều khiển được căn lại vào hệ tọa độ gốc của robot bằng phép biến đổi `base_T_anchor` trên `XRControllerConfig` (mặc định: chuẩn OpenXR → quy ước trục robot); hãy điều chỉnh nếu hệ tọa độ neo của bạn khác.

## Tìm hiểu thêm

Tài liệu NVIDIA Isaac Teleop ([trang chủ tài liệu](https://nvidia.github.io/IsaacCapture/), [GitHub](https://github.com/NVIDIA/IsaacTeleop)):

- [Bắt đầu nhanh](https://nvidia.github.io/IsaacCapture/main/getting_started/quick_start.html) — cài đặt, chạy máy chủ CloudXR, kết nối kính thực tế ảo, chạy ví dụ điều khiển từ xa.
- [TeleopSession](https://nvidia.github.io/IsaacCapture/main/getting_started/teleop_session.html) — API phiên mà `XRController` bọc quanh.
- [Giao diện retargeting](https://nvidia.github.io/IsaacCapture/main/references/retargeting/index.html) và [tổng quan kiến trúc](https://nvidia.github.io/IsaacCapture/main/overview/architecture.html) — cách các nút nguồn và retargeter kết hợp thành một pipeline.
- [Build từ mã nguồn](https://nvidia.github.io/IsaacCapture/main/getting_started/build_from_source/index.html) — build `isaacteleop` (và các plugin C++ của nó, bao gồm plugin `so101_leader` được dùng ở trên) từ một bản checkout cục bộ.
- [Yêu cầu hệ thống](https://nvidia.github.io/IsaacCapture/main/references/requirements.html) và [tài liệu SDK CloudXR](https://docs.nvidia.com/cloudxr-sdk) — các nền tảng, GPU, phiên bản runtime CloudXR/OpenXR và kính thực tế ảo được hỗ trợ.

