手機

使用您的手機（iOS 或 Android）來控制您的機器人。

在本指南中，您將學習：

如何連接 iOS/Android 手機
手機姿勢如何映射到機器人末端執行器 (EE) 目標
如何調整安全限制、夾爪控制以及逆運動學 (IK) 設定

要使用手機控制機器人，請透過以下指令安裝相關依賴套件：

pip install lerobot[phone]

開始使用

支援的平台

iOS：使用 HEBI Mobile I/O 應用程式（ARKit 姿勢 + 按鈕）。請先下載該應用程式並開啟，範例程式會自動在網路上搜尋並串流傳輸手機的姿勢與輸入訊號。
Android：使用 teleop 套件 (WebXR)。當您啟動 Python 程序時，它會顯示一個本地 URL。請在手機上開啟該連結，點擊「Start」，然後使用「Move」按鈕來串流傳輸姿勢。

相關連結

Android WebXR 函式庫：PyPI 上的 teleop
iOS 應用程式：HEBI Mobile I/O

手機方向與控制

方向：手持手機時，螢幕朝上，手機頂端邊緣指向與機器人夾爪相同的方向。這能確保校準過程將手機的座標系與機器人座標系對齊，使動作感覺更自然，請參考下圖。
啟用/停用
- iOS：按住 B1 啟用遙控，放開即停止。第一次按下時會捕捉基準姿勢。
- Android：按住 Move 按鈕，放開即停止。第一次按下時會捕捉基準姿勢。
夾爪控制
- iOS：類比輸入 A3 用於控制夾爪的速度。
- Android：按鈕 A 和 B 作為增量/減量控制（A 開啟，B 關閉）。您可以在 GripperVelocityToJoint 步驟中調整速度。

步驟 1：選擇平台

修改範例程式，在 PhoneConfig 中使用 PhoneOS.IOS 或 PhoneOS.ANDROID。API 在各平台間完全相同，僅輸入來源不同。所有範例皆位於 examples/ 目錄下，且均有 phone_so100_*.py 變體版本。

遙控範例

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

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

步驟 2：連接與校準

建立 Phone(teleop_config) 並呼叫 connect() 時，系統會自動提示校準。請按照上述方向握住手機，然後：

iOS：按住 B1 捕捉基準姿勢。
Android：點擊 WebXR 頁面上的 Move 按鈕捕捉基準姿勢。

為什麼要校準？我們捕捉當前的姿勢，以便後續的姿勢都在對齊機器人的框架中表示。當您再次按下按鈕啟用控制時，系統會重新捕捉位置，以避免手機在未啟用期間被移動造成的漂移。

步驟 3：執行範例

執行其中一個範例指令碼以進行遙控、錄製資料集、重播資料集或評估策略。

所有指令碼皆假設您已設定好機器人（例如 SO-100 follower）並設定了正確的序列埠。

此外，您需要將機器人的 URDF 檔案複製到範例資料夾中。對於本教學中的範例（使用 SO100/SO101），請從 SO-ARM100 儲存庫將 SO101 資料夾複製到 examples/phone_to_so100/ 目錄，使 URDF 檔案路徑變為 examples/phone_to_so100/SO101/so101_new_calib.urdf。

執行此範例以進行遙控：

cd examples/phone_to_so100
python teleoperate.py

執行範例後：

Android：啟動指令碼後，在手機上開啟顯示的本地 URL，點擊「Start」，然後按住「Move」。
iOS：先開啟 HEBI Mobile I/O；B1 可啟用動作，A3 控制夾爪。

此外，您可以透過編輯範例中顯示的處理器步驟來客製化映射或安全限制。您也可以透過修改輸入和運動學步驟，重新映射輸入（例如使用不同的類比輸入）或調整管線以適配其他機器人（例如 LeKiwi）。詳細內容請參閱機器人與遙控處理器 (Processors for Robots and Teleoperators) 指南。

執行此範例以錄製資料集，此操作會儲存絕對的末端執行器觀測值與動作：
```
cd examples/phone_to_so100
python record.py
```
執行此範例以重播已錄製的片段：
```
cd examples/phone_to_so100
python replay.py
```
執行此範例以評估預訓練策略：
```
cd examples/phone_to_so100
python evaluate.py
```

重要的管線步驟與選項

運動學應用於多個步驟中。我們使用 Placo，這是一個圍繞 Pinocchio 的封裝，用於處理我們的運動學計算。我們透過傳入機器人的 URDF 和目標框架來建構運動學物件，並將 target_frame_name 設定為夾爪框架。
```
kinematics_solver = RobotKinematics(
  urdf_path="./SO101/so101_new_calib.urdf",
  target_frame_name="gripper_frame_link",
  joint_names=list(robot.bus.motors.keys()),
)
```

MapPhoneActionToRobotAction 步驟將校準後的手機姿勢與輸入轉換為目標增量與夾爪指令。下圖顯示了該步驟的輸出內容。

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

EEReferenceAndDelta 步驟將目標增量轉換為絕對的末端執行器 (EE) 期望姿勢，並在啟用時儲存參考點。end_effector_step_sizes 是 EE 姿勢的步長，可以修改以調整運動速度。
```
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,
),
```
EEBoundsAndSafety 步驟將 EE 的運動限制在工作空間內，並檢查 EE 步長是否有過大的跳變以確保安全。end_effector_bounds 是 EE 姿勢的邊界，可以修改以變更工作空間。max_ee_step_m 是 EE 姿勢的步長限制，可以修改以調整安全限制。
```
EEBoundsAndSafety(
    end_effector_bounds={"min": [-1.0, -1.0, -1.0], "max": [1.0, 1.0, 1.0]},
    max_ee_step_m=0.10,
)
```
GripperVelocityToJoint 步驟將類似速度的夾爪輸入，結合當前的測量狀態，轉換為絕對的夾爪位置。speed_factor 是速度的乘數。
```
GripperVelocityToJoint(speed_factor=20.0)
```

不同的 IK 初始猜測

我們在運動學步驟中使用不同的 IK 初始猜測。初始猜測可以是當前測量的關節狀態，或是先前的 IK 解。

閉迴路 (用於錄製/評估)：設定 initial_guess_current_joints=True，以便 IK 每一幀都從測量的關節狀態開始。

InverseKinematicsEEToJoints(
    kinematics=kinematics_solver,
    motor_names=list(robot.bus.motors.keys()),
    initial_guess_current_joints=True,  # closed loop
)

開迴路 (用於重播)：設定 initial_guess_current_joints=False，以便 IK 從先前的 IK 解繼續計算，而非測量狀態。這能在沒有回饋的情況下重播時保持動作穩定性。
```
InverseKinematicsEEToJoints(
    kinematics=kinematics_solver,
    motor_names=list(robot.bus.motors.keys()),
    initial_guess_current_joints=False,  # open loop
)
```

管線步驟詳解

MapPhoneActionToRobotAction：將校準後的手機姿勢與輸入轉換為目標增量與夾爪指令。動作由啟用訊號（iOS 為 B1，Android 為 Move）控制。
EEReferenceAndDelta：在啟用時鎖定參考 EE 姿勢，並將其與目標增量結合，在每一幀產生絕對的期望 EE 姿勢。停用時，它會持續發送上一次的指令姿勢。
EEBoundsAndSafety：將 EE 姿勢限制在工作空間內，並限制動作變化率以確保安全。同時宣告 action.ee.* 特徵。
InverseKinematicsEEToJoints：透過 IK 將 EE 姿勢轉為關節位置。建議在閉迴路控制中使用 initial_guess_current_joints=True；在開迴路重播時設為 False 以保持穩定。
GripperVelocityToJoint：結合當前測量狀態，將類似速度的夾爪輸入整合為絕對的夾爪位置。
ForwardKinematicsJointsToEE：根據觀測到的關節狀態計算 observation.state.ee.*，用於日誌記錄及訓練 EE 狀態。

疑難排解

iOS 無法偵測：確保 HEBI Mobile I/O 已開啟，且您的筆電與手機處於同一個網路上。
Android URL 無法存取：確認您使用的 https 是否應為 http，請使用指令碼顯示的精確 IP 位址，並允許瀏覽器忽略憑證問題。
動作感覺反轉：調整 MapPhoneActionToRobotAction 中的符號反轉，或是交換軸線以匹配您的設定。

在 GitHub 上更新

LeRobot

手機