LeRobot

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.7.0).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Điện thoại

Sử dụng điện thoại (iOS hoặc Android) của bạn để điều khiển robot.

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

Cách kết nối điện thoại iOS/Android
Cách tư thế điện thoại được ánh xạ sang các mục tiêu của đầu cuối (EE) robot
Cách tinh chỉnh giới hạn an toàn, điều khiển kẹp và cài đặt IK

Để sử dụng điện thoại điều khiển robot của bạn, hãy cài đặt các phụ thuộc liên quan bằng cách:

pip install 'lerobot[phone,kinematics,feetech,core_scripts]'

kinematics cung cấp động học ngược mà các ví dụ sử dụng, feetech là các động cơ SO-100/SO-101, và core_scripts là các công cụ ghi hình và trực quan hóa.

Bắt đầu

Nền tảng được hỗ trợ

iOS: Sử dụng ứng dụng HEBI Mobile I/O (tư thế ARKit + nút). Tải ứng dụng trước, mở nó và các ví dụ sẽ phát hiện nó trên mạng của bạn và truyền trực tiếp tư thế điện thoại cùng các đầu vào.
Android: Sử dụng gói teleop (WebXR). Khi bạn khởi chạy tiến trình Python, nó sẽ in ra một URL cục bộ. Mở liên kết trên điện thoại của bạn, chạm vào Start, sau đó sử dụng Move để phát trực tiếp tư thế.

Liên kết:

Thư viện WebXR cho Android: teleop trên PyPI
Ứng dụng iOS: HEBI Mobile I/O

Hướng và điều khiển điện thoại

Định hướng: cầm điện thoại với màn hình hướng lên trên và cạnh trên hướng cùng chiều với gắp của robot. Điều này đảm bảo việc hiệu chuẩn căn chỉnh khung của điện thoại với khung của robot để chuyển động cảm giác tự nhiên, xem hình ảnh bên dưới để tham khảo.
Bật/tắt — đây là một công tắc an toàn, bạn phải giữ liên tục trong suốt quá trình di chuyển:
- iOS: Giữ B1 để di chuyển robot, thả ra để giữ nguyên vị trí cánh tay. Mỗi lần nhấn sẽ neo lại điện thoại vào tư thế hiện tại của cánh tay, vì vậy bạn có thể thả ra, đưa tay về vị trí thoải mái, nhấn lại và tiếp tục — robot sẽ không bị nhảy vị trí.
- Android: Tương tự với nút Move trên trang WebXR.
Điều khiển kẹp (hoạt động có hoặc không giữ nút bật):
- iOS: Thanh trượt tương tự A3 điều khiển kẹp như một đầu vào vận tốc — đẩy lên để mở, kéo xuống để đóng, thả về giữa để giữ.
- Android: Nút A và B hoạt động như tăng/giảm (A mở, B đóng). Bạn có thể điều chỉnh tốc độ trong bước GripperVelocityToJoint.
Tư thế cầm: cầm điện thoại bằng cả hai tay, một ngón cái đặt trên nút bật (B1) và ngón còn lại trên thanh trượt kẹp (A3), để bạn có thể điều khiển cánh tay và kẹp cùng lúc mà không cần đổi tư thế cầm. Giữ điện thoại nằm phẳng trong khi thao tác — tư thế của nó chính là lệnh, nên việc cầm lại giữa chừng sẽ làm robot di chuyển.
Tư thế khởi động của robot: teleoperate.py di chuyển cánh tay về tư thế homing khi khởi động (trước khi điện thoại được hiệu chuẩn), và khi nhấn Ctrl+C sẽ đưa nó trở lại vị trí mà nó đang ở khi script bắt đầu. Các lệnh homing điều khiển từng khớp thân về giá trị nửa vòng quay mà set_half_turn_homings() đã căn giữa trong quá trình hiệu chuẩn — tức là tư thế được giữ trong sơ đồ hiệu chuẩn — trong khi kẹp giữ nguyên vị trí hiện tại để việc homing không bao giờ đóng kẹp lên một vật gì. Điều này quan trọng vì các mục tiêu được giải bằng IK từ vị trí cánh tay đang ở khi bạn nhấn nút enable — một cánh tay đang gập lại hoặc duỗi thẳng hoàn toàn sẽ có ít dư địa và dễ chạm đến giới hạn khớp. Các script ví dụ khác (record.py, evaluate.py, replay.py) không thực hiện homing cho cánh tay, vì vậy hãy tự đặt nó về vị trí đó trước khi chạy chúng.

Bước 1: Chọn nền tảng

Sửa đổi các ví dụ để sử dụng PhoneOS.IOS hoặc PhoneOS.ANDROID trong PhoneConfig. API giống nhau trên tất cả các nền tảng, chỉ nguồn đầu vào khác nhau. Tất cả các ví dụ nằm trong examples/phone_to_so100/: teleoperate.py, record.py, replay.py, evaluate.py và rollout.py.

Ví dụ về điều khiển từ xa:

from lerobot.teleoperators.phone import Phone, PhoneConfig
from lerobot.teleoperators.phone.config_phone import PhoneOS

teleop_config = PhoneConfig(phone_os=PhoneOS.IOS)  # or PhoneOS.ANDROID
teleop_device = Phone(teleop_config)

Bước 2: Kết nối và hiệu chuẩn

Khi Phone(teleop_config) được tạo và connect() được gọi, quá trình hiệu chuẩn sẽ được khởi động tự động. Giữ điện thoại ở hướng đã mô tả ở trên, sau đó:

iOS: nhấn và giữ B1 để chụp tư thế tham chiếu.
Android: nhấn nút Move trên trang WebXR để ghi lại tư thế tham chiếu.

Tại sao phải hiệu chuẩn? Chúng ta ghi lại tư thế hiện tại để các tư thế tiếp theo được biểu diễn trong hệ tọa độ căn chỉnh với robot. Khi bạn nhấn nút một lần nữa để bật điều khiển, vị trí sẽ được ghi lại lần nữa để tránh hiện tượng trôi dạt khi điện thoại của bạn bị di chuyển trong lúc đang tắt.

Bước 3: Chạy một ví dụ

Chạy một trong các script mẫu để điều khiển từ xa, ghi lại một tập dữ liệu, phát lại một tập dữ liệu hoặc đánh giá một chính sách.

Tất cả các script đều giả định rằng bạn đã cấu hình và hiệu chuẩn robot của mình (ví dụ: SO-100 follower).

Bạn phải cung cấp URDF của robot. Mọi ví dụ đều giải bài toán động học ngược, đòi hỏi mô hình động học của cánh tay robot, và URDF không được phân phối kèm theo LeRobot.

Đối với SO-100/SO-101 được sử dụng trong hướng dẫn này, hãy sao chép thư mục SO101 từ SO-ARM100 repo vào examples/phone_to_so100/, để tệp nằm tại examples/phone_to_so100/SO101/so101_new_calib.urdf, khi đang ở trong LeRobot repo:
git clone --depth 1 https://github.com/TheRobotStudio/SO-ARM100.git /tmp/SO-ARM100
cp -r /tmp/SO-ARM100/Simulation/SO101 examples/phone_to_so100/SO101
Chỉ định các script trỏ đến một tệp khác bằng --urdf nếu bạn lưu tệp ở nơi khác, hoặc nếu bạn đang điều khiển một cánh tay robot khác.

Chạy ví dụ này để điều khiển từ xa, truyền vào cổng serial của cánh tay follower (tìm bằng lerobot-find-port):
```
cd examples/phone_to_so100
python teleoperate.py --port /dev/tty.usbmodem5A460814411
```
--id chọn bộ hiệu chuẩn đã lưu cần sử dụng, và --urdf trỏ đến URDF ở trên.

Sau khi chạy ví dụ:

Android: sau khi chạy script, mở địa chỉ URL cục bộ được in ra trên điện thoại của bạn, chạm vào Start, sau đó nhấn và giữ Move.
iOS: mở HEBI Mobile I/O trước; giữ nút B1 để di chuyển robot. A3 điều khiển kẹp.

Ngoài ra, bạn có thể tùy chỉnh ánh xạ hoặc giới hạn an toàn bằng cách chỉnh sửa các bước xử lý được minh họa trong các ví dụ. Bạn cũng có thể ánh xạ lại các đầu vào (ví dụ: sử dụng một đầu vào tương tự khác) hoặc điều chỉnh pipeline cho các robot khác (ví dụ: LeKiwi) bằng cách sửa đổi các bước đầu vào và động học. Tìm hiểu thêm về điều này trong hướng dẫn Processors for Robots and Teleoperators.

Chạy ví dụ này để ghi lại một tập dữ liệu, trong đó lưu các quan sát và hành động tuyệt đối của đầu hiệu ứng cuối (end effector):
```
cd examples/phone_to_so100
python record.py
```
Chạy ví dụ này để phát lại các tập đã được ghi lại:
```
cd examples/phone_to_so100
python replay.py
```
Chạy ví dụ này để đánh giá một chính sách đã được huấn luyện trước:
```
cd examples/phone_to_so100
python evaluate.py
```

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

Kinematics được sử dụng ở nhiều bước. Chúng tôi sử dụng Placo, một wrapper bao quanh Pinocchio để xử lý kinematics. Chúng tôi xây dựng đối tượng kinematics bằng cách truyền URDF của robot và target frame. Chúng tôi đặt target_frame_name thành gripper frame.
```
kinematics_solver = RobotKinematics(
  urdf_path="./SO101/so101_new_calib.urdf",
  target_frame_name="gripper_frame_link",
  joint_names=list(robot.bus.motors.keys()),
)
```

Bước MapPhoneActionToRobotAction chuyển đổi tư thế điện thoại đã hiệu chuẩn và các đầu vào thành các delta mục tiêu và lệnh kẹp, dưới đây là những gì bước này xuất ra.

action["enabled"] = enabled
action["target_x"] = pos[1] if enabled else 0.0
action["target_y"] = -pos[0] if enabled else 0.0
action["target_z"] = pos[2] if enabled else 0.0
action["target_wx"] = rotvec[1] if enabled else 0.0
action["target_wy"] = -rotvec[0] if enabled else 0.0
action["target_wz"] = rotvec[2] if enabled else 0.0
action["gripper_vel"] = gripper_vel  # Still send gripper action when disabled

Bước EEReferenceAndDelta chuyển các delta đích sang tư thế EE mong muốn tuyệt đối, lưu một tham chiếu khi bật, trong đó end_effector_step_sizes là các kích thước bước cho tư thế EE và có thể được sửa đổi để thay đổi tốc độ chuyển động.
```
EEReferenceAndDelta(
    kinematics=kinematics_solver,
    end_effector_step_sizes={"x": 0.5, "y": 0.5, "z": 0.5},
    motor_names=list(robot.bus.motors.keys()),
    use_latched_reference=True,
),
```
Bước EEBoundsAndSafety giới hạn chuyển động của EE trong một không gian làm việc và kiểm tra các bước nhảy lớn của EE để đảm bảo an toàn. end_effector_bounds là các giới hạn cho tư thế của EE và có thể được sửa đổi để thay đổi không gian làm việc. max_ee_step_m là các giới hạn bước cho tư thế của EE và có thể được sửa đổi để thay đổi các giới hạn an toàn.
```
EEBoundsAndSafety(
    end_effector_bounds={"min": [-1.0, -1.0, -1.0], "max": [1.0, 1.0, 1.0]},
    max_ee_step_m=0.10,
)
```
Bước GripperVelocityToJoint chuyển đổi đầu vào kẹp có dạng vận tốc thành vị trí tuyệt đối của kẹp bằng cách sử dụng trạng thái đo được hiện tại. speed_factor là hệ số nhân với vận tốc.
```
GripperVelocityToJoint(speed_factor=20.0)
```

Các giá trị ban đầu khác nhau cho IK

Chúng tôi sử dụng các giá trị dự đoán ban đầu IK khác nhau trong các bước động học. Giá trị dự đoán ban đầu có thể là các khớp đo được hiện tại hoặc nghiệm IK trước đó.

Vòng lặp kín (được sử dụng trong ghi/đánh giá): đặt initial_guess_current_joints=True để IK bắt đầu từ các khớp được đo ở mỗi khung hình.
```
InverseKinematicsEEToJoints(
    kinematics=kinematics_solver,
    motor_names=list(robot.bus.motors.keys()),
    initial_guess_current_joints=True,  # closed loop
)
```
Vòng mở (được dùng trong replay): đặt initial_guess_current_joints=False để IK tiếp tục từ nghiệm IK trước đó thay vì trạng thái đo được. Điều này duy trì sự ổn định của hành động khi chúng ta replay mà không có phản hồi.
```
InverseKinematicsEEToJoints(
    kinematics=kinematics_solver,
    motor_names=list(robot.bus.motors.keys()),
    initial_guess_current_joints=False,  # open loop
)
```

Giải thích các bước trong Pipeline

MapPhoneActionToRobotAction: chuyển đổi tư thế điện thoại đã hiệu chuẩn và các đầu vào thành các delta mục tiêu và lệnh kẹp. Chuyển động được điều khiển bởi tín hiệu kích hoạt (B1 trên iOS, Move trên Android).
EEReferenceAndDelta: khóa một tư thế EE tham chiếu khi được bật và kết hợp nó với các delta mục tiêu để tạo ra một tư thế EE mong muốn tuyệt đối cho mỗi khung hình. Khi bị tắt, nó tiếp tục gửi tư thế đã được lệnh gần nhất.
EEBoundsAndSafety: kẹp tư thế EE trong một không gian làm việc và giới hạn tốc độ các bước nhảy để đảm bảo an toàn. Ngoài ra, khai báo các tính năng action.ee.*.
InverseKinematicsEEToJoints: chuyển đổi tư thế EE thành vị trí khớp bằng IK. Khuyến nghị đặt initial_guess_current_joints=True cho điều khiển vòng kín; đặt False để phát lại vòng hở nhằm đảm bảo ổn định.
GripperVelocityToJoint: tích hợp đầu vào kẹp có dạng vận tốc thành vị trí kẹp tuyệt đối bằng cách sử dụng trạng thái đo được hiện tại.
ForwardKinematicsJointsToEE: tính toán observation.state.ee.* từ các khớp quan sát được để ghi log và huấn luyện trên trạng thái EE.

Xử lý sự cố

Không tìm thấy iOS: hãy đảm bảo rằng HEBI Mobile I/O đang mở và máy tính xách tay/điện thoại của bạn đang kết nối cùng một mạng.
Không thể truy cập URL Android: kiểm tra xem bạn đã dùng https thay vì http, hãy dùng chính xác IP được in ra bởi script và cho phép trình duyệt của bạn nhập vào và bỏ qua vấn đề chứng chỉ.
Cảm giác chuyển động bị đảo ngược: hãy kiểm tra từng trục một, sau đó điều chỉnh các phép đảo dấu trong MapPhoneActionToRobotAction hoặc hoán đổi các trục cho phù hợp với cấu hình của bạn.
Cánh tay hầu như không di chuyển hoặc bị giới hạn phạm vi: khởi động lại từ tư thế bắt đầu ở khoảng giữa (xem bên trên) — IK được giải từ cấu hình hiện tại của cánh tay.

Update on GitHub

←Robot & Teleoperator của bên thứ ba Isaac Teleop→