add unity doc.

2026-05-30 16:04:37 +08:00
parent ce52895ec2
commit f4ee53d9c3
1538 changed files with 221228 additions and 2192 deletions
--- a/docs/pico_udp_sender_ubuntu22_setup.md
+++ b/docs/pico_udp_sender_ubuntu22_setup.md
@ -0,0 +1,485 @@
+# Ubuntu 22.04 下 PICO 4 Ultra UDP Sender 配置教程
+
+本文档只记录如何在 **Ubuntu 22.04** 下配置 Unity/PICO 4 Ultra，让头显把左右手柄数据通过 UDP 发给当前 ROS2 工作空间。
+
+目标链路：
+
+```text
+PICO 4 Ultra 双手柄 6DoF pose / grip / trigger
+  -> Unity Android APK
+  -> UDP JSON, 默认 192.168.9.99:15000 或当前 ROS 主机 IP:15000
+  -> xr_rm_input/udp_controller_receiver
+  -> /xr/left_controller 与 /xr/right_controller
+```
+
+## 1. 当前项目事实
+
+- Unity 工程路径：`unity/XR_RM_PICO_UDP_Sender`
+- Unity 版本：`2022.3.62f3c1`
+- Unity Editor 路径：`/home/robot/Unity/Hub/Editor/2022.3.62f3c1/Editor/Unity`
+- PICO SDK 路径：`unity/PICO-Unity-Integration-SDK-release_3.4.0`
+- PICO package 引用：`Packages/manifest.json` 中的 `file:../../PICO-Unity-Integration-SDK-release_3.4.0`
+- Android 包名：`com.local.xr_rm_udp_sender`
+- 默认 UDP 目标：`192.168.9.99:15000`
+- 默认发送频率：`60 Hz`
+- APK 输出：`unity/XR_RM_PICO_UDP_Sender/Builds/XR-RM-PICO-UDP-Sender.apk`
+
+PICO 端建议稳定发送 `60 Hz` 或 `90 Hz`，不要低于 `20 Hz`。ROS 遥操作节点默认 `command_timeout_sec=0.12`，超时会停止。
+
+## 2. Ubuntu 22.04 环境准备
+
+建议环境：
+
+- Ubuntu 22.04 x86_64
+- GNOME 桌面，优先 X11 会话
+- Unity 2022.3 LTS
+- Android Build Support、Android SDK & NDK Tools、OpenJDK
+- ADB
+
+检查当前图形会话：
+
+```bash
+echo $XDG_SESSION_TYPE
+```
+
+如果 Unity Editor 或 Hub 在 Wayland 下出现黑屏、鼠标偏移、构建窗口异常，注销后选择 `Ubuntu on Xorg`。
+
+安装 Unity Hub：
+
+```bash
+sudo apt update
+sudo apt install -y curl gpg ca-certificates
+
+sudo install -d /etc/apt/keyrings
+curl -fsSL https://hub.unity3d.com/linux/keys/public \
+  | sudo gpg --dearmor -o /etc/apt/keyrings/unityhub.gpg
+
+echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/unityhub.gpg] https://hub.unity3d.com/linux/repos/deb stable main" \
+  | sudo tee /etc/apt/sources.list.d/unityhub.list
+
+sudo apt update
+sudo apt install -y unityhub
+```
+
+安装 ADB：
+
+```bash
+sudo apt update
+sudo apt install -y android-tools-adb
+adb version
+```
+
+在 Unity Hub 里安装 Unity 2022.3 LTS，并勾选：
+
+- `Android Build Support`
+- `Android SDK & NDK Tools`
+- `OpenJDK`
+
+优先使用 Unity 随 Editor 安装的 embedded Android SDK/NDK/JDK，不要混用系统 Android Studio 的工具链。
+
+## 3. 准备 PICO 4 Ultra
+
+在 PICO 4 Ultra 中：
+
+1. 登录设备。
+2. 开启开发者模式。
+3. 开启 USB 调试。
+4. 用 USB-C 线连接 Ubuntu 主机。
+5. 在 Ubuntu 上执行：
+
+```bash
+adb devices
+```
+
+PICO 内会弹出 USB 调试授权，选择允许。再次执行：
+
+```bash
+adb devices
+```
+
+应看到类似：
+
+```text
+<device_serial>    device
+```
+
+如果是 `unauthorized`，重新插拔 USB 并在 PICO 内确认授权，或执行：
+
+```bash
+adb kill-server
+adb start-server
+adb devices
+```
+
+## 4. 打开 Unity 工程
+
+在 Unity Hub 中：
+
+1. 点击 `Projects`。
+2. 点击 `Add`。
+3. 选择：
+
+```text
+/home/robot/WS_xr/src/unity/XR_RM_PICO_UDP_Sender
+```
+
+4. 用 Unity `2022.3.62f3c1` 或同系列 2022.3 LTS 打开。
+5. 如果提示升级工程版本，先确认 git 状态再继续。
+
+如果 Unity 打开后找不到 PICO package，检查：
+
+```text
+unity/XR_RM_PICO_UDP_Sender/Packages/manifest.json
+../../PICO-Unity-Integration-SDK-release_3.4.0
+```
+
+该相对路径表示从 `unity/XR_RM_PICO_UDP_Sender/Packages` 往上两级到 `unity/`，再进入 `PICO-Unity-Integration-SDK-release_3.4.0`。
+
+## 5. Android 构建设置
+
+当前工程已提供菜单脚本：
+
+```text
+Assets/Editor/XrRmUdpSenderProjectSetup.cs
+```
+
+在 Unity Editor 菜单中依次执行：
+
+```text
+XR-RM -> Apply UDP Sender Android Settings
+XR-RM -> Create Or Refresh UDP Sender Scene
+XR-RM -> Build Android APK
+```
+
+这些菜单会配置或刷新：
+
+- `Product Name = XR-RM-PICO-UDP-Sender`
+- `Package Name = com.local.xr_rm_udp_sender`
+- Android min SDK = API 29
+- Android target SDK = Auto
+- Internet permission = enabled
+- Scripting Backend = IL2CPP
+- Target Architectures = ARM64
+- Graphics API = OpenGLES3
+- XR Management Android loader = PICO `PXR_Loader`
+- `Assets/Scenes/Main.unity`
+- 场景中的 `PicoControllerUdpSender`、`PicoUdpConfigPanel` 和 `PicoKeepAwake`
+
+也可以使用 batchmode 构建：
+
+```bash
+cd /home/robot/WS_xr/src
+
+UNITY_EDITOR="/home/robot/Unity/Hub/Editor/2022.3.62f3c1/Editor/Unity"
+
+"$UNITY_EDITOR" \
+  -batchmode \
+  -quit \
+  -projectPath "$(pwd)/unity/XR_RM_PICO_UDP_Sender" \
+  -executeMethod XrRmUdpSenderProjectSetup.BuildAndroidApk \
+  -logFile "$(pwd)/unity_build.log"
+```
+
+如果要覆盖自动发现到的 UDP 目标 IP，可在构建命令前设置：
+
+```bash
+export XR_RM_UDP_TARGET_HOST=192.168.9.99
+```
+
+构建成功后 APK 位于：
+
+```text
+unity/XR_RM_PICO_UDP_Sender/Builds/XR-RM-PICO-UDP-Sender.apk
+```
+
+## 6. 安装 APK 到 PICO
+
+确保 PICO 已 USB 连接且 `adb devices` 显示 `device`。
+
+```bash
+cd /home/robot/WS_xr/src
+adb install -r unity/XR_RM_PICO_UDP_Sender/Builds/XR-RM-PICO-UDP-Sender.apk
+```
+
+看到 `Success` 表示安装完成。
+
+检查包是否存在：
+
+```bash
+adb shell pm list packages | grep xr_rm
+```
+
+戴上 PICO：
+
+1. 打开 `Library`。
+2. 进入未知来源/开发者应用区域。
+3. 打开 `XR-RM-PICO-UDP-Sender`。
+
+## 7. 网络配置
+
+PICO 和 Ubuntu ROS 主机必须在同一个局域网。
+
+查看 Ubuntu 主机 IP：
+
+```bash
+hostname -I
+ip -4 addr
+```
+
+假设 Ubuntu 主机 IP 是：
+
+```text
+192.168.9.99
+```
+
+则 PICO App 面板里使用：
+
+| 配置项 | 推荐值 |
+| --- | --- |
+| `Target IP` | `192.168.9.99`，替换为当前 Ubuntu 主机 IP |
+| `Target Port` | `15000` |
+| `Send Rate` | `60 Hz` 或 `90 Hz` |
+| `Coordinates` | `Project` |
+| `UDP Sending` | `ON` |
+
+如果 Ubuntu 开启了 UFW：
+
+```bash
+sudo ufw allow 15000/udp
+sudo ufw status
+```
+
+## 8. PICO App 操作
+
+面板操作：
+
+- 摇杆上/下：选择行
+- 摇杆左/右：调整端口、频率、坐标模式或发送开关
+- Trigger / A / X：编辑当前行或触发当前行
+- B / Y：保存并应用
+- Menu：在配置面板和运行 HUD 之间切换
+- Grip：ROS 侧遥操作使能；未按下时机械臂停止
+
+验证现象：
+
+- 面板中 `L ok / R ok` 表示 Unity 能读到左右手柄。
+- `UDP Sending ON` 后，ROS2 的 `/xr/left_controller` 与 `/xr/right_controller` 应持续刷新。
+- HUD 显示包计数、追踪状态、grip 和 KeepAwake 状态。
+- 按住 `grip` 并移动手柄时，mock 模式下 `/xr_rm/*/cmd_vel` 应出现非零速度。
+- 松开 `grip` 后，`cmd_vel` 应回到零速度。
+
+## 9. ROS2 端验证
+
+先构建并 source 工作空间：
+
+```bash
+cd /home/robot/WS_xr
+source /opt/ros/humble/setup.bash
+colcon build --symlink-install
+source install/setup.bash
+```
+
+只验证 UDP receiver：
+
+```bash
+ros2 launch xr_rm_input udp_receiver.launch.py udp_port:=15000
+```
+
+另开终端查看左右手柄：
+
+```bash
+cd /home/robot/WS_xr
+source /opt/ros/humble/setup.bash
+source install/setup.bash
+
+ros2 topic echo /xr/left_controller
+ros2 topic echo /xr/right_controller
+ros2 topic hz /xr/left_controller
+ros2 topic hz /xr/right_controller
+```
+
+期望现象：
+
+- PICO 应用启动并打开 `UDP Sending ON` 后，两个 topic 都持续刷新。
+- 按左手 `grip` 时，`/xr/left_controller` 的 `grip` 变成 `true`。
+- 按右手 `grip` 时，`/xr/right_controller` 的 `grip` 变成 `true`。
+- 扳机从松开到按下时，`trigger` 从 `0.0` 附近变到 `1.0` 附近。
+- 平移手柄时，`pose.position` 连续变化。
+
+如果收不到包，先抓 UDP：
+
+```bash
+sudo tcpdump -ni any udp port 15000
+```
+
+能看到 UDP 但 ROS topic 没数据，说明 JSON 字段不符合协议。查看 `udp_controller_receiver` 终端里的格式错误提示。
+
+## 10. Mock 闭环验证
+
+先不要连接真机，使用 mock 模式验证完整链路。
+
+终端 1：
+
+```bash
+cd /home/robot/WS_xr
+source /opt/ros/humble/setup.bash
+source install/setup.bash
+ros2 launch xr_rm_bringup arm_debug.launch.py arm:=both use_mock:=true udp_port:=15000
+```
+
+终端 2：
+
+```bash
+cd /home/robot/WS_xr
+source /opt/ros/humble/setup.bash
+source install/setup.bash
+ros2 topic echo /xr_rm/left_rm75/cmd_vel
+ros2 topic echo /xr_rm/right_rm75/cmd_vel
+```
+
+流程：
+
+1. 启动 PICO Unity 应用。
+2. 确认 `/xr/left_controller` 和 `/xr/right_controller` 正常刷新。
+3. 左手按住 `grip`，只移动左手一小段，观察 `/xr_rm/left_rm75/cmd_vel`。
+4. 松开左手 `grip`，确认 `cmd_vel` 回到 0。
+5. 右手重复同样流程。
+6. 用 `ros2 topic hz` 确认频率稳定，建议 `50 Hz` 以上。
+
+如果要排除 PICO 端问题，可用本机 sample sender 验证 ROS 端：
+
+```bash
+ros2 run xr_rm_input sample_udp_sender --hand both --host 127.0.0.1 --port 15000 --seconds 20
+```
+
+## 11. UDP JSON 协议
+
+Unity APK 每个周期发送一个双手柄 JSON 包：
+
+```json
+{
+  "t": 12.345,
+  "frame_id": "xr_world",
+  "controllers": {
+    "left": {
+      "grip": true,
+      "trigger": 0.0,
+      "pos": [-0.12, 1.05, 0.30],
+      "quat": [0.0, 0.0, 0.0, 1.0]
+    },
+    "right": {
+      "grip": true,
+      "trigger": 0.4,
+      "pos": [0.12, 1.05, 0.30],
+      "quat": [0.0, 0.0, 0.0, 1.0]
+    }
+  }
+}
+```
+
+字段要求：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `t` | number | `Time.realtimeSinceStartupAsDouble` |
+| `frame_id` | string | 默认 `xr_world` |
+| `controllers.left` | object | 左手柄 |
+| `controllers.right` | object | 右手柄 |
+| `grip` | bool | ROS 遥操作启停 |
+| `trigger` | float | `0.0-1.0` |
+| `pos` | float[3] | `[x, y, z]` |
+| `quat` | float[4] | `[qx, qy, qz, qw]` |
+
+坐标转换应与当前工程保持一致：
+
+```csharp
+payload.pos[0] = position.x;
+payload.pos[1] = position.y;
+payload.pos[2] = -position.z;
+
+payload.quat[0] = -rotation.x;
+payload.quat[1] = -rotation.y;
+payload.quat[2] = rotation.z;
+payload.quat[3] = rotation.w;
+```
+
+禁用发送、App 暂停或退出时，必须额外发送一次左右手柄 `grip=false`，让 ROS 侧安全停止。
+
+## 12. 坐标方向检查
+
+当前配置使用 PICO/OpenXR 位置坐标：
+
+```text
+X: 向右
+Y: 向上
+Z: 向后
+```
+
+双臂配置中的映射关系：
+
+```text
+左臂机器人位移增量 = [-手柄y,  手柄z, -手柄x]
+右臂机器人位移增量 = [ 手柄y,  手柄z,  手柄x]
+```
+
+建议现场按下面顺序验证：
+
+1. 只启动 `use_mock:=true`。
+2. 按住左手 `grip`，沿 PICO 的 `+X/-X`、`+Y/-Y`、`+Z/-Z` 每次只动一个轴。
+3. 记录 `/xr/left_controller.pose.position` 的变化方向。
+4. 记录 `/xr_rm/left_rm75/cmd_vel` 的方向。
+5. 右手重复。
+
+如果两个手柄在 ROS topic 里的某个轴都反了，优先检查 Unity 的坐标转换。如果 ROS topic 正确，但某一只机械臂运动方向不符合现场坐标，只改对应 YAML 的 `xr_to_robot_matrix`。
+
+## 13. 真机前置检查
+
+本文档只负责 PICO UDP 发送配置，但如果继续接真机，必须先确认：
+
+- 急停可用。
+- 机械臂工作区清空。
+- PICO topic 在 mock 下已经稳定。
+- `grip=false` 时 `/xr_rm/<arm>/cmd_vel` 为 0。
+- `move_to_initial_pose_on_connect` 保持 `false`。
+
+单臂真机：
+
+```bash
+ros2 launch xr_rm_bringup arm_debug.launch.py arm:=left use_mock:=false udp_port:=15000
+ros2 launch xr_rm_bringup arm_debug.launch.py arm:=right use_mock:=false udp_port:=15000
+```
+
+双臂真机必须在左右单臂都验证通过后再启动：
+
+```bash
+ros2 launch xr_rm_bringup arm_debug.launch.py arm:=both use_mock:=false \
+  left_robot_ip:=192.168.192.18 \
+  right_robot_ip:=192.168.192.19 \
+  udp_port:=15000
+```
+
+## 14. 常见问题
+
+| 现象 | 排查 |
+| --- | --- |
+| Unity 找不到 PICO package | 检查 `Packages/manifest.json` 的 `../../PICO-Unity-Integration-SDK-release_3.4.0` 路径 |
+| Gradle 或 Android 构建失败 | 检查 Android Build Support、SDK/NDK/OpenJDK、IL2CPP、ARM64、Android Build Target 和 PICO SDK 编译错误 |
+| PICO 安装失败或 `unauthorized` | 重新授权 USB 调试，执行 `adb kill-server && adb start-server && adb devices` |
+| ROS2 收不到 UDP | 检查同一 Wi-Fi、Target IP、Target Port、UFW、`UDP Sending ON`、`L ok / R ok` |
+| tcpdump 有包但 topic 没数据 | JSON 字段不对，确认包含 `controllers.left/right`，且 `pos` 长度 3、`quat` 长度 4 |
+| 有 topic 但机械臂不动 | 检查 `grip`、teleop 节点订阅话题、工作空间限幅、UDP 超时 |
+| 按左手右臂动 | PICO 端 left/right 获取或填充反了 |
+| 松开 grip 后仍有速度 | 确认 PICO 持续发送 `grip=false`，并检查 teleop 超时停止 |
+| 经常超时 | 发送频率太低、网络丢包、PICO 应用后台暂停；提高 `sendHz` 并保持应用前台运行 |
+| 前后方向反了 | 先切换 Unity 坐标转换，再验证 ROS topic |
+| 某一只臂方向反了 | 修改对应 YAML 的 `xr_to_robot_matrix` |
+
+## 15. 参考链接
+
+- Unity Hub Linux 安装文档：`https://docs.unity.com/en-us/hub/install-hub-linux`
+- Unity 2022.3 系统要求：`https://docs.unity.cn/Documentation/Manual/system-requirements.html`
+- PICO 4 Ultra 开发资源：`https://developer.picoxr.com/pico4-ultra/`
+- PICO Unity Integration SDK：`https://github.com/Pico-Developer/PICO-Unity-Integration-SDK`
+- PICO Controller & HMD input mapping：`https://developer-cn.picoxr.com/en/document/unity/input-mapping/`
+- Unity XR `InputDevice.TryGetFeatureValue`：`https://docs.unity3d.com/ScriptReference/XR.InputDevice.TryGetFeatureValue.html`
+- Unity XR `CommonUsages`：`https://docs.unity3d.com/ScriptReference/XR.CommonUsages.html`