# Go2 Navigation

基于 Unitree Go2、Livox LiDAR、ROS/ROS2、FAST-LIO 和 Unitree SDK 的导航与建图资料仓库。仓库把驱动、点云里程计、传统 ROS1 建图、Unitree SLAM 示例、机器人 ROS2 消息包、C++ SDK、网页控制台和 LiDAR 外参标定工具集中在一起，便于在真实 Go2 与 Livox 设备上进行建图、定位、导航和调试。

> **仓库状态**：这是一个多项目集合，不是可以用一条命令构建的单一 ROS workspace。不同目录对应不同上游项目、ROS 发行版和运行方式；请先选择目标模块，再按本文对应章节操作。

## 目录

- [项目组成](#项目组成)
- [系统要求](#系统要求)
- [目录结构](#目录结构)
- [网络与设备](#网络与设备)
- [快速开始](#快速开始)
- [各模块构建与运行](#各模块构建与运行)
- [配置说明](#配置说明)
- [话题、服务与数据流](#话题服务与数据流)
- [地图与标定数据](#地图与标定数据)
- [验证清单](#验证清单)
- [故障排查](#故障排查)
- [文档索引](#文档索引)
- [许可证](#许可证)

## 项目组成

| 路径 | 内容 | 主要入口 | 运行环境 |
| --- | --- | --- | --- |
| `Livox-SDK2/` | Livox HAP、Mid-360 等设备的 C/C++ SDK、示例和通信配置 | `CMakeLists.txt`、`samples/` | Linux/Windows，C++11，CMake 3.0+ |
| `ws_livox/src/livox_ros_driver2/` | Livox ROS Driver 2，发布标准点云或 `CustomMsg` | `build.sh`、`launch_ROS2/` | ROS1 或 ROS2 Foxy/Humble/Jazzy |
| `fast_lio_ws/src/FAST_LIO_ROS2/` | FAST-LIO2 ROS2 激光惯性里程计和 PCD 建图 | `launch/mapping.launch.py` | Ubuntu 20.04+，ROS2，PCL，Eigen |
| `livox_mapping/` | Livox 的 ROS1 LOAM 低速建图包 | `launch/mapping_*.launch` | Ubuntu 16.04/18.04，ROS Kinetic/Melodic |
| `Livox_automatic_calibration-master/` | 双 Livox 雷达点云外参自动标定 | `mapping`、`calibration`、`fitline` | CMake，PCL 1.7，Eigen |
| `unitree_ros2/` | Unitree Go2/B2/H1/G1 的 ROS2 消息包和示例 | `cyclonedds_ws/`、`example/` | ROS2 Foxy 或 Humble，CycloneDDS |
| `unitree_sdk2/` | Unitree C++ SDK2 及 Go2、G1、H1 等示例 | `CMakeLists.txt`、`example/` | Ubuntu 20.04，GCC 9.4，C++17 |
| `unitree_slam/` | Unitree SLAM 二进制、配置、动态库和 `keyDemo` 示例 | `example/src/keyDemo.cpp`、`bin/keyDemo` | ARM64 Unitree 设备或匹配的交叉环境 |
| `unitree_ui/unitree_ui-main/` | 基于 TypeScript、Three.js、Vite 的 WebRTC 控制台 | `package.json`、`start.sh` | Node.js 18+，npm 9+，Chrome |
| `go2_maps/` | 本地 Go2 地图和初始位姿文件（默认被 Git 忽略） | `.yaml`、`.pgm`、`.pcd` | Unitree SLAM/导航数据 |
| `go2-environment-setup-handoff.md` | 另一套自主巡检仓库的环境交接记录 | 文档本身 | 仅作历史参考 |

仓库同时保留部分第三方源码、预编译库、构建目录和示例资源。`3rdparty/`、`build/`、`node_modules/` 等内容不需要重新整理到本 README；使用某个模块时，以该模块的 `README.md`、`CMakeLists.txt`、`package.xml` 或 `package.json` 为准。

## 系统要求

建议在 Ubuntu 20.04/22.04 上运行。ROS1 建图和旧版标定工具依赖旧发行版；FAST-LIO 与 Livox ROS Driver 2 建议使用 ROS2 Humble。

| 组件 | 建议版本 | 用途 |
| --- | --- | --- |
| CMake | 3.10+（SDK2 最低 3.0） | C/C++ 模块构建 |
| GCC/G++ | 9.4+ | SDK2、ROS2 示例和 FAST-LIO |
| ROS2 | Humble（Foxy 也有脚本） | Livox Driver 2、FAST-LIO、Unitree ROS2 |
| ROS1 | Kinetic/Melodic | `livox_mapping` 和部分旧标定流程 |
| PCL | 1.8+；标定工具要求 1.7 | 点云处理 |
| Eigen | 3.3.4+ | 状态估计与几何计算 |
| Node.js/npm | Node.js 18+，npm 9+ | Unitree WebRTC UI |
| Python | Python 3 | UI BLE 服务和启动脚本 |
| 浏览器 | Chrome | WebRTC 控制台 |

先检查本机工具链：

```bash
gcc --version
cmake --version
python3 --version
node --version
source /opt/ros/humble/setup.bash
ros2 --version
```

ROS2 包构建前建议安装依赖：

```bash
sudo apt update
sudo apt install -y build-essential cmake libeigen3-dev libpcl-dev \
  python3-colcon-common-extensions python3-rosdep
rosdep update
```

Unitree ROS2 的官方依赖还包括 `rmw-cyclonedds-cpp`、`rosidl-generator-dds-idl` 和 `libyaml-cpp-dev`。不同 ROS 发行版的包名要把 `foxy` 替换成实际发行版。

## 目录结构

```text
Go2_navigation/
├── Livox-SDK2/                         # Livox SDK2 与 C++ samples
├── Livox_automatic_calibration-master/ # 双雷达外参自动标定
├── fast_lio_ws/src/FAST_LIO_ROS2/      # FAST-LIO2 ROS2
├── livox_mapping/                      # Livox ROS1 LOAM 建图
├── ws_livox/src/livox_ros_driver2/     # Livox ROS Driver 2
├── unitree_ros2/                       # Unitree ROS2 消息与示例
├── unitree_sdk2/                       # Unitree SDK2
├── unitree_slam/                       # Unitree SLAM 二进制与配置
├── unitree_ui/unitree_ui-main/         # WebRTC/Three.js 控制台
├── go2_maps/                           # 本地地图资产
└── go2-environment-setup-handoff.md    # 历史环境交接
```

## 网络与设备

### Unitree Go2

Unitree ROS2 文档以有线网卡连接为例：电脑网卡配置为 `192.168.123.99/24`，机器人通常位于同一网段。把 `unitree_ros2/setup.sh` 中的 `enp3s0` 改为实际网卡名，然后加载环境：

```bash
cd unitree_ros2
source setup.sh
ros2 topic list
```

仅本机仿真或回环测试可使用：

```bash
source unitree_ros2/setup_local.sh   # CycloneDDS 使用 lo
# 或
source unitree_ros2/setup_default.sh # 不指定网卡
```

注意：仓库中的这三个脚本仍然使用 `/opt/ros/foxy` 和 `$HOME/unitree_ros2`。如果仓库不在 `$HOME/unitree_ros2`，需要先修改脚本中的路径；使用 Humble 时也要将 Foxy 路径改为 Humble。

### Livox LiDAR

Livox Driver 2 的 MID360 示例使用独立的设备网段。配置文件示例使用 `192.168.1.x`，控制、推送、点云、IMU、日志端口分别为 `56100`–`56500`（主机端通常为 `56101`–`56501`）。把 `host_ip`、LiDAR IP 和网卡地址改成现场实际值，确保防火墙允许这些 UDP 端口。

Go2 内置 SLAM 的配置则使用机器人 DDS 网络和 `rt/unitree/...` 话题。不要把 Livox 独立网段的配置直接套到 Unitree DDS 网卡上。

## 快速开始

下面是一条适用于“外置 Livox + ROS2 FAST-LIO”的最短流程。每个命令在独立终端执行。

### 1. 构建 Livox SDK2

```bash
cd Livox-SDK2
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
sudo cmake --install build
```

SDK 默认安装库到 `/usr/local/lib`、头文件到 `/usr/local/include`。如果不希望安装到系统目录，请为 Driver 2 和后续 CMake 工程显式设置 `CMAKE_PREFIX_PATH` 或库搜索路径。

### 2. 构建并启动 Livox ROS Driver 2

```bash
source /opt/ros/humble/setup.bash
cd ws_livox/src/livox_ros_driver2
bash build.sh humble
source ../../install/setup.bash
ros2 launch livox_ros_driver2 msg_MID360_launch.py
```

单雷达使用 `MID360_config.json`，多雷达使用 `msg_MID360s_launch.py` 和 `MID360s_config.json`。FAST-LIO 使用 Livox 每点时间戳时，必须发布 `CustomMsg` 格式；不要使用不能提供每点时间的旧 `livox_lidar.launch` 变体。

### 3. 构建并启动 FAST-LIO2

```bash
source /opt/ros/humble/setup.bash
cd fast_lio_ws
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
source install/setup.bash
ros2 launch fast_lio mapping.launch.py config_file:=mid360.yaml
```

如果使用 Avia、Horizon、Velodyne 或 Ouster，把 `config_file` 换成 `avia.yaml`、`horizon.yaml`、`velodyne.yaml` 或 `ouster64.yaml`。先启动 Driver，再启动 FAST-LIO；检查 `/livox/lidar`、`/livox/imu` 是否有数据。

保存 PCD：

```bash
ros2 service call /map_save std_srvs/srv/Trigger "{}"
```

保存路径由对应 YAML 的 `map_file_path` 和 `pcd_save.pcd_save_en` 决定。默认 `interval: -1` 会将所有帧写入一个文件，长时间运行可能占用大量内存。

### 4. 启动网页控制台

```bash
cd unitree_ui/unitree_ui-main
npm install
npm run start:no-ble
```

浏览器打开 Vite 输出的地址（通常是 `http://localhost:5173`）。需要机器人 BLE 配网或 BLE 遥控器时使用：

```bash
npm run start
```

该命令会启动 Vite 和 FastAPI BLE 服务（端口 `5051`）。依赖来自 `server/requirements.txt`，包括 FastAPI、Uvicorn、Bleak、PyCryptodome、pygatt 和 websockets。

## 各模块构建与运行

### Livox SDK2

SDK2 提供 C 风格 API，覆盖 HAP、Mid-360 等 Livox 设备。源码中包含快速启动、日志、信息查询、IP 设置、时间同步、多雷达升级和调试点云等 sample：

```bash
cd Livox-SDK2/build
./samples/livox_lidar_quick_start/livox_lidar_quick_start \
  ../samples/livox_lidar_quick_start/<config.json>
```

日志配置包括 `lidar_log_enable`、`lidar_log_cache_size_MB` 和 `lidar_log_path`。升级固件会让设备停止工作，必须使用与设备匹配的固件文件并在现场操作前确认网络稳定。

### Livox ROS Driver 2

ROS2 launch 文件位于 `ws_livox/src/livox_ros_driver2/launch_ROS2/`：

| Launch | 用途 |
| --- | --- |
| `msg_HAP_launch.py` | HAP，自定义消息 |
| `msg_MID360_launch.py` | 单 Mid-360，自定义消息 |
| `msg_MID360s_launch.py` | 多 Mid-360，自定义消息 |
| `rviz_HAP_launch.py`、`rviz_MID360_launch.py` | 启动驱动并打开 RViz |
| `rviz_mixed.py` | 混合型号可视化 |

需要修改的参数位于 launch 文件开头和 `config/`：`xfer_format`、`multi_topic`、`publish_freq`、`frame_id`、`user_config_path` 以及设备 IP。配置文件使用 JSON，不能包含注释或 `...` 占位符。

### FAST-LIO2 ROS2

FAST-LIO 将 LiDAR 和 IMU 通过紧耦合迭代扩展卡尔曼滤波器融合，并使用 ikd-Tree 增量维护地图。配置重点：

| 参数 | 说明 |
| --- | --- |
| `common.lid_topic` / `imu_topic` | 输入话题，Mid-360 默认 `/livox/lidar`、`/livox/imu` |
| `preprocess.lidar_type` | Livox=1、Velodyne=2、Ouster=3、通用点云=4 |
| `mapping.extrinsic_T/R` | LiDAR 在 IMU body frame 中的外参 |
| `mapping.extrinsic_est_en` | 是否在线估计外参；已有可靠外参时建议关闭 |
| `publish.*` | 点云、地图、路径和 body-frame 输出开关 |
| `pcd_save.*` | PCD 保存开关、间隔和输出路径 |

输出话题和服务由 `src/laserMapping.cpp` 实现，包含 `/cloud_registered`、`/cloud_registered_body`、`/cloud_effected`、`/Laser_map`、`/Odometry`、`/path` 和 `/map_save`。

### Livox ROS1 LOAM 建图

`livox_mapping` 是旧 ROS1 catkin 包，依赖 `livox_ros_driver`、PCL、Eigen 和 OpenCV：

```bash
cd <catkin_ws>/src
ln -s /path/to/Go2_navigation/livox_mapping livox_mapping
cd ..
catkin_make
source devel/setup.bash
roslaunch livox_mapping mapping_mid.launch
```

Horizon 使用 `mapping_horizon.launch`，室外示例使用 `mapping_outdoor.launch`。需要保存地图时，在 launch 文件中设置 `map_file_path`。

### Livox 双雷达外参自动标定

工具会先用基准雷达建立地图，再将目标雷达逐帧配准，最后用 `fitline` 拟合外参矩阵：

```bash
cd Livox_automatic_calibration-master
cmake -S . -B build
cmake --build build -j$(nproc)
cp run.sh build/
cd build
bash run.sh
```

运行前准备：

```text
data/Base_LiDAR_Frames/100000.pcd       # 基准雷达，帧号递增
data/Target-LiDAR-Frames/100000.pcd     # 目标雷达，时间同步
data/Init_Matrix.txt                    # 粗配准初值
```

程序会生成 `data/H-LiDAR-Map-data/H_LiDAR_Map.pcd`、`T_Matrix.txt` 和 `calib_data.txt` 等中间结果。两路数据必须尽可能同步，采集时应缓慢运动、减少动态物体，并保证初始矩阵大致对齐。

### Unitree ROS2 消息与示例

消息包包括：

- `unitree_api`：请求、响应和租约消息。
- `unitree_go`：Go2/B2 的低层、高层、IMU、BMS、LiDAR、遥控器和运动消息。
- `unitree_hg`：G1/H1 等人形机器人的电机、手部和主板消息。

构建：

```bash
source /opt/ros/humble/setup.bash
cd unitree_ros2/cyclonedds_ws
colcon build --symlink-install
source install/setup.bash

cd ../example
colcon build --symlink-install
source install/setup.bash
```

常用示例：

```bash
ros2 run unitree_ros2_example read_motion_state
ros2 run unitree_ros2_example read_low_state
ros2 run unitree_ros2_example read_wireless_controller
ros2 run unitree_ros2_example go2_sport_client
```

Go2 高层运动通过 `/api/sport/request` 请求响应接口，低层控制通过 `/lowcmd` 发布 `unitree_go/msg/LowCmd`。低层控制会直接驱动关节，必须先确认机器人处于安全状态并准备急停。

### Unitree SDK2

SDK2 的 CMake 工程按 CPU 架构从 `lib/<CMAKE_SYSTEM_PROCESSOR>/` 查找预编译库：

```bash
cmake -S unitree_sdk2 -B unitree_sdk2/build -DCMAKE_BUILD_TYPE=Release
cmake --build unitree_sdk2/build -j$(nproc)
```

安装到系统或自定义前缀：

```bash
cmake --install unitree_sdk2/build --prefix /opt/unitree_robotics
```

自定义前缀需要加入 `CMAKE_PREFIX_PATH`。`unitree_sdk2/example/` 中按 Go2、G1、H1、B2、B2W、H2 等型号提供高级控制、低级控制、状态读取、无线遥控和 JSON 示例。

### Unitree SLAM 示例

`unitree_slam/bin/` 内已有 ARM64 二进制和配套动态库；源码示例依赖已安装的 `unitree_sdk2`：

```bash
cmake -S unitree_slam/example -B /tmp/unitree_slam_example-build
cmake --build /tmp/unitree_slam_example-build -j$(nproc)
./unitree_slam/bin/keyDemo eth0
```

`keyDemo` 的按键流程：

| 按键 | 操作 |
| --- | --- |
| `q` / `w` | 开始 / 结束建图 |
| `a` | 开始重定位 |
| `s` / `d` / `f` | 添加位姿、执行任务、清空任务 |
| `z` / `x` | 暂停 / 恢复导航 |
| 其他键 | 停止 SLAM |

示例源码将地图写入机器人 `/home/unitree/test.pcd`，重定位也从该路径读取。现场使用时应修改为机器人上实际存在的 PCD 文件，并检查 `unitree_slam/config/` 中的网卡名、LiDAR 型号、DDS XML 路径和 `rt/unitree/...` 话题。

### Unitree WebRTC UI

网页控制台支持 Go2、G1 和 R1，主要能力包括：实时视频和 3D 视图、双摇杆、运动模式、状态面板、错误解码、服务管理、账号、BLE 配网、BLE 遥控转发、Go2 3D LiDAR SLAM、地图缓存和自动充电。

生产构建：

```bash
cd unitree_ui/unitree_ui-main
npm run build
npm run preview
```

详细协议说明在 `docs/`，其中 `connection.md`、`control.md`、`status.md`、`slam.md`、`lidar.md` 和 `remote-control.md` 是排查连接与控制问题的首选文档。

## 配置说明

### Livox MID360 JSON

`ws_livox/src/livox_ros_driver2/config/MID360_config_backup.json` 是完整的单雷达示例。当前 `MID360_config.json` 含有 `...` 占位符，不是合法 JSON；在启动前必须补齐 `lidar_configs` 并通过解析检查：

```bash
python3 -m json.tool ws_livox/src/livox_ros_driver2/config/MID360_config_backup.json >/dev/null
```

关键字段包括 `lidar_net_info`、`host_net_info`、LiDAR IP、点云数据类型、扫描模式和外参。不要把示例 IP 直接用于现场设备。

### FAST-LIO YAML

`fast_lio_ws/src/FAST_LIO_ROS2/config/` 提供 `avia.yaml`、`horizon.yaml`、`mid360.yaml`、`velodyne.yaml` 和 `ouster64.yaml`。修改输入话题、扫描线、盲区、时间单位、外参、视场角和 PCD 输出路径后再启动。

FAST-LIO 的外参定义是 LiDAR 在 IMU body frame 中的位姿，不是 IMU 在 LiDAR frame 中的逆变换；方向弄反会导致点云扭曲和里程计发散。

### Unitree SLAM YAML/JSON

`unitree_slam/config/` 里包含 Mid-360、XT16、建图、重定位、规划、栅格地图、充电和 DDS 配置。以下内容通常必须按设备修改：

- `network` 或 `network_interface`：实际以太网卡。
- `lidar_ysn`、`lidar_ip`：LiDAR 序列号和地址。
- `odom_topic`、`imu_topic`、`lidar_topic`：机器人实际 DDS 话题。
- `dds_config.json` 与 `dds_parameter.json` 中的绝对路径。
- 建图/重定位的 PCD、PGM、YAML 文件路径。

仓库中的部分配置仍保留 `/home/unitree/...`、`/home/unitree/graph_pid_ws/...` 等设备端历史路径，迁移到新机器前必须替换。

### Go2 地图资产

`go2_maps/` 中的地图通常由以下文件组成：

```text
<name>.pcd                 # 3D 点云地图
<name>.pgm                 # 2D 占据栅格图
<name>.yaml                # 分辨率、原点、阈值和 PGM 引用
<name>.initial-pose        # 初始位姿
<name>.map-manifest.json   # 校准 ID、哈希、点数和版本
```

示例 YAML 使用 `resolution: 0.05`、`mode: trinary`、`occupied_thresh: 0.65`、`free_thresh: 0.25`。地图目录和 mapping log 默认被 `.gitignore` 忽略，发布或备份前请单独归档。

## 话题、服务与数据流

```text
Livox LiDAR
    └─ livox_ros_driver2
        ├─ /livox/lidar + /livox/imu (CustomMsg / sensor_msgs)
        └─ fast_lio_mapping
            ├─ /cloud_registered, /Laser_map
            ├─ /Odometry, /path
            └─ /map_save

Unitree Go2 DDS
    ├─ /sportmodestate, /lowstate, /wirelesscontroller
    ├─ /api/sport/request, /lowcmd
    └─ rt/unitree/slam_*

Browser
    └─ WebRTC data channel/video + BLE FastAPI proxy
```

常用检查命令：

```bash
ros2 topic list
ros2 topic hz /livox/lidar
ros2 topic echo --once /livox/imu
ros2 service list | grep map_save
ros2 topic echo --once /Odometry
```

Unitree UI 的 SLAM 页面使用 `rt/uslam/client_command` 发送 `mapping/...`、`localization/...`、`navigation/...` 和 `patrol/...` 字符串命令，状态从 `rt/uslam/server_log`、点云、里程计和路径话题返回。地图文件通过 WebRTC 内部文件传输通道分块传输，并在浏览器 IndexedDB 中缓存。

## 地图与标定数据

建议采用以下现场流程：

1. 固定 LiDAR 和 IMU，记录安装方向、坐标系和网卡地址。
2. 用 Livox Driver 检查点云与 IMU 时间戳；FAST-LIO 要求每点时间可用。
3. 采集缓慢、闭环且包含丰富几何特征的数据，避免人车等动态物体。
4. 先用已知外参或机械测量值运行 FAST-LIO，保存 PCD 并检查重影、扭曲和闭环误差。
5. 双雷达场景使用 `Livox_automatic_calibration-master`，保证两路 PCD 文件名和时间戳一一对应。
6. 把确认后的外参写入 FAST-LIO YAML 或设备配置，再重新建图验证。
7. Go2 官方 SLAM 地图同时保存 PCD、PGM、YAML、初始位姿和 manifest，不要只保留单个 PCD。

外参验证至少采用一种独立方法：重叠视场观察墙面是否错层，或把目标雷达变换后与基准点云融合再重新建图。若出现分层，优先检查时间同步、坐标方向、初值和地图质量。

## 验证清单

### 构建前

- [ ] ROS 发行版、PCL、Eigen 和编译器版本符合目标模块。
- [ ] 设备网卡、IP、LiDAR 序列号和端口已核对。
- [ ] `MID360_config.json` 等 JSON 通过解析检查，没有 `...` 占位符。
- [ ] FAST-LIO 的 `lid_topic`、`imu_topic` 和外参已确认。
- [ ] Unitree 配置中的绝对路径已替换为本机或机器人实际路径。

### 运行时

- [ ] `ros2 topic list` 能看到 Livox 和 Unitree 话题。
- [ ] `/livox/lidar` 与 `/livox/imu` 频率稳定，时间戳递增。
- [ ] FAST-LIO 的 `/Odometry` 连续更新，点云无明显扭曲。
- [ ] `/map_save` 成功生成 PCD，且文件可用 `pcl_viewer` 打开。
- [ ] 控制机器人前已确认站立模式、急停和通信链路。

### 软件检查

```bash
# Shell 语法
bash -n ws_livox/src/livox_ros_driver2/build.sh
bash -n unitree_ui/unitree_ui-main/start.sh

# UI TypeScript/Vite 构建
cd unitree_ui/unitree_ui-main
npm run build

# ROS2 包索引（已 source 对应环境）
cd ../../fast_lio_ws
colcon list
```

当前仓库没有统一的根目录测试命令；C++/ROS 包主要通过构建、话题、服务和真实设备链路验证。`go2-environment-setup-handoff.md` 中提到的 `robot/`、`dependencies/`、Cargo workspace 和导航测试属于另一套 `/home/limerly/go2_autonomous_inspection` 仓库，不能在本仓库直接执行。

## 故障排查

| 现象 | 优先检查 |
| --- | --- |
| `liblivox_lidar_sdk_shared.so` 找不到 | SDK2 是否安装到 `/usr/local/lib`；运行 `sudo ldconfig` 或设置 `LD_LIBRARY_PATH` |
| Driver 能启动但没有点云 | LiDAR/主机 IP、UDP 端口、防火墙、`host_net_info` 和网卡是否一致 |
| FAST-LIO 报 `Failed to find match for field 'time'` | 驱动是否发布 `CustomMsg`；rosbag 是否保留每点时间字段 |
| FAST-LIO 发散或点云扭曲 | IMU/LiDAR 时间同步、外参方向、`time_sync_en` 和 `time_offset_lidar_to_imu` |
| `/map_save` 返回 `Map save disabled` | YAML 中 `pcd_save.pcd_save_en` 是否为 `true`，`map_file_path` 是否可写 |
| Unitree ROS2 看不到话题 | 网卡名、`RMW_IMPLEMENTATION=rmw_cyclonedds_cpp`、DDS 配置和机器人网段 |
| `setup.sh` 找不到环境 | 脚本中的 `/opt/ros/foxy` 或 `$HOME/unitree_ros2` 是否与实际安装一致 |
| SDK2 CMake 找不到库 | `unitree_sdk2/lib/<架构>/` 是否有当前 CPU 的静态库，或 SDK 是否已安装 |
| `keyDemo` 无法连接 | 运行参数必须是连接机器人且位于 123 网段的网卡，例如 `eth0` |
| UI BLE 服务启动失败 | `pip3 install -r server/requirements.txt`，确认 websockets >= 11、蓝牙适配器和权限 |
| UI 能开但无法连接机器人 | Chrome、机器人 WebRTC 网络模式、STA-L/AP/Remote 配置和固件兼容性 |
| 地图重定位失败 | PCD/YAML/PGM 是否成套，初始位姿坐标系、地图版本和 DDS 话题是否一致 |

## 文档索引

### 仓库级

- [环境交接记录](go2-environment-setup-handoff.md)

### Livox 与 FAST-LIO

- [Livox SDK2](Livox-SDK2/README.md)
- [Livox ROS Driver 2](ws_livox/src/livox_ros_driver2/README.md)
- [Livox ROS1 Mapping](livox_mapping/README.md)
- [Livox 外参自动标定（英文）](Livox_automatic_calibration-master/README.md)
- [Livox 外参自动标定（中文）](Livox_automatic_calibration-master/doc/readme-CN.md)
- [FAST-LIO ROS2](fast_lio_ws/src/FAST_LIO_ROS2/README.md)
- [FAST-LIO 日志分析指南](fast_lio_ws/src/FAST_LIO_ROS2/Log/guide.md)

### Unitree

- [Unitree ROS2（英文）](unitree_ros2/README.md)
- [Unitree ROS2（中文）](unitree_ros2/README%20_zh.md)
- [Unitree SDK2](unitree_sdk2/README.md)
- [Unitree SLAM 示例](unitree_slam/example/README.md)

### WebRTC UI

- [UI 总览](unitree_ui/unitree_ui-main/README.md)
- [连接](unitree_ui/unitree_ui-main/docs/connection.md)
- [控制](unitree_ui/unitree_ui-main/docs/control.md)
- [状态](unitree_ui/unitree_ui-main/docs/status.md)
- [错误处理](unitree_ui/unitree_ui-main/docs/error-handling.md)
- [服务管理](unitree_ui/unitree_ui-main/docs/services.md)
- [账号](unitree_ui/unitree_ui-main/docs/account.md)
- [蓝牙总览](unitree_ui/unitree_ui-main/docs/bluetooth.md)
- [蓝牙 V1/V2 协议](unitree_ui/unitree_ui-main/docs/bluetooth-v1-v2.md)
- [蓝牙 V3 协议](unitree_ui/unitree_ui-main/docs/bluetooth-v3.md)
- [BLE 遥控器](unitree_ui/unitree_ui-main/docs/remote-control.md)
- [Go2 SLAM](unitree_ui/unitree_ui-main/docs/slam.md)
- [Go2 LiDAR/体素地图](unitree_ui/unitree_ui-main/docs/lidar.md)
- [R1 动作列表](unitree_ui/unitree_ui-main/docs/r1_action_list.md)

## 许可证

各子目录保留各自上游许可证，不能用一个根目录许可证替代：

- Livox SDK2：`Livox-SDK2/LICENSE.txt`
- Livox ROS Driver 2：`ws_livox/src/livox_ros_driver2/LICENSE.txt`
- Livox Mapping：`livox_mapping/LICENSE`
- Livox 自动标定：`Livox_automatic_calibration-master/LICENSE`
- FAST-LIO ROS2：`fast_lio_ws/src/FAST_LIO_ROS2/LICENSE`（GPLv2）
- Unitree ROS2：`unitree_ros2/LICENSE`（BSD 3-Clause）
- Unitree SDK2：`unitree_sdk2/LICENSE`（BSD 3-Clause）
- Unitree UI：`unitree_ui/unitree_ui-main/LICENSE`（MIT）

发布二进制、固件、地图或修改后的第三方源码时，请同时保留对应版权和许可证文本。