> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mrdvs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# V2 ROS2 接口说明

> 介绍 V2 定位模块 ROS2 SDK 的编译、运行、话题和服务接口。

## 概述

本文介绍 V2 定位模块 `lx_camera_ros` 的 ROS2 话题与服务接口。

## 编译

安装 Qt5 的 Core 和 Network 组件。不同 Linux 发行版的安装方式可能不同；以下为 Ubuntu 示例：

```bash theme={null}
sudo apt install qtbase5-dev qtbase5-dev-tools libqt5network5
```

从 [libzip 下载页](https://libzip.org/download/) 获取 `libzip` 源码，并按官方说明编译。

在 `/lx_camera_ros` 目录执行：

```bash theme={null}
./build.sh
```

## 运行

> [!NOTE]
>
> 修改 YAML 配置文件后，必须重新编译，修改才会生效。

```bash theme={null}
./start.sh
```

## ROS2 话题接口

测试接口前，请确认相机已上电并等待约 30 秒，且 ROS2 SDK 节点已启动。

| 场景 | 相关话题 |
| - | - |
| 定位 | 位姿、定位状态、切换地图、重定位 |
| 建图 | 建图状态、建图进度 |
| 维护与配置 | 存储空间、故障模块、参数设置与地图下载 |

#### 接收定位位姿接口

ROS2 持续接收相机发送的定位值 `x`、`y`、`theta`，并将定位值及由 `theta` 转换得到的四元数发布至 `LxCamera_LocationPoseResult`。该位姿会通过 TF 广播。

```bash theme={null}
ros2 topic echo /LxCamera_LocationPoseResult
```

#### 接收定位状态接口

ROS2 以 1 Hz 接收相机发送的定位状态（`true/false`），并以 `std_msgs::msg::Bool` 发布至 `LxCamera_LocationResult`。

```bash theme={null}
ros2 topic echo /LxCamera_LocationResult
```

#### 接收当前相机已使用空间接口

ROS2 以 2 Hz 接收相机发送的存储空间使用占比，并以 `std_msgs::msg::Float32` 发布至 `LxCamera_Capacity_Status`。

```bash theme={null}
ros2 topic echo /LxCamera_Capacity_Status
```

#### 接收当前出现故障的模块名字

ROS2 接收相机发送的故障模块名称，并以 `std_msgs::msg::String` 发布至 `LxCamera_Module_Error`。

```bash theme={null}
ros2 topic echo /LxCamera_Module_Error
```

#### 接收建图进度接口

开始建图后，ROS2 以 `std_msgs::msg::Int32` 将建图进度（`0–100`）发布至 `LxCamera_Mapping_Progress`。

```bash theme={null}
ros2 topic echo /LxCamera_Mapping_Progress
```

#### 接收建图状态接口

开始建图后，ROS2 以 `std_msgs::msg::Bool` 将建图状态发布至 `LxCamera_MappingState`。

```bash theme={null}
ros2 topic echo /LxCamera_MappingState
```

#### 设置参数接口

向 `LxCamera_SetParam` 发布 `std_msgs::msg::String` 消息。消息包含 9 个以英文逗号分隔的浮点数：`x,y,z,yaw,pitch,roll,x,y,yaw`。前 6 个为相机位姿，后 3 个为 LiDAR 位姿。设置成功后，会更新 `/home/fr1511b/hontai/params/config_install_FL21500HAF.ini` 中 `[Laser1]` 和 `[Camera1]` 的相关参数。

```bash theme={null}
source install/setup.bash
ros2 topic pub -1 /LxCamera_SetParam std_msgs/msg/String "{data: '1,1,1,1,1,1,1,1,1'}"
```

#### 切换地图接口

向 `LxCamera_SwitchMap` 发布 `std_msgs::msg::String` 消息，内容为已完成建图的地图名称。刷新相机 Web 前端后，若当前地图名称已更新，则表示切换成功。

```bash theme={null}
source install/setup.bash
ros2 topic pub -1 /LxCamera_SwitchMap std_msgs/msg/String "{data: 'pf'}"
```

#### 下载地图接口

1. 用户发布`std_msgs::msg::String`类型消息到topic：`LxCamera_DownloadMap`
2. 消息格式为字符串，包含两个字段：save\_path表示保存地址(上位机中的地址，使用绝对路径)，mapname表示地图名称(相机中已经完成建图的".zip"格式的文件名)
3. 成功后，你上位机指定的路径下会有一个指定地图名称的压缩包，解压后得到一个`pgm地图文件`和一个`yaml配置文件`

```bash theme={null}
// 进入lx_camera_ros2_ws目录
//开启终端
source install/setup.bash
ros2 topic pub -1 /LxCamera_DownloadMap std_msgs/msg/String "{data: '/home/zsure/LANXIN\,pf'}"
```

#### 上传里程计接口

1. 用户发布`nav_msgs::msg::Odometry`类型数据到topic：`/sim/odom` (可修改)

```bash wrap theme={null}
// 进入lx_camera_ros2_ws目录 //开启终端 source install/setup.bash ros2 topic pub /odom nav_msgs/msg/Odometry "header: stamp: {sec: 0, nanosec: 0} frame_id: 'odom' child_frame_id: 'base_link' pose: pose: position: x: 1.0 y: 2.0 z: 0.0 orientation: x: 0.0 y: 0.0 z: 0.0 w: 1.0 covariance: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0] twist: twist: linear: x: 0.5 y: 0.0 z: 0.0 angular: x: 0.0 y: 0.0 z: 0.1 covariance: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]"
```

#### 重定位接口

1. 用户发布`geometry_msgs::msg::PoseWithCovarianceStamped`类型的数据到topic：`LxCamera_UploadReloc`
2. 数据为激光位姿，包含：`x,y,yaw`
3. 相机网页上显示的本体位置更新为发送的位置则重定位成功

```bash theme={null}
ros2 topic pub -1 /LxCamera_UploadReloc geometry_msgs/msg/PoseWithCovarianceStamped "{
  header: {frame_id: ''},
  pose: {
    pose: {
      position: {x: 0.0, y: 0.0, z: 0.0},
      orientation: {x: 0, y: 0, z: -0.694658, w: 0.71934}
    },
    covariance: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
                 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
                 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
                 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ,0.0 ,0.0]
  }
}"
```

> 平面运动且 Roll、Pitch 为零时，将 yaw 以弧度代入：`x = 0`、`y = 0`、`z = sin(yaw / 2)`、`w = cos(yaw / 2)`。按 `xyzw` 顺序传入单位四元数。

#### 报文类型前缀

上位机使用 UDP 与相机通信。发送报文的前 4 个字节为类型前缀，用于区分接口数据类型：

```text theme={null}
mapping_prefix = "aced220d";          // 建图使能
setparam_prefix = "aced220e";         // 设置参数(相机和雷达)
UploadScan_prefix = "aced2209";       // 上传激光扫描数据到相机
odom_prefix = "aced0f0a";             // 里程计数据
mapname_prefix = "aced220c";          // 切换地图
map_request_prefix = "aced220f";      // 下载指定地图
prefix_after_reloc = "aced0f0b";      // 重定位
```

***

## ROS2 服务接口

建图、切换地图、下载地图和重定位除支持话题方式外，也支持 ROS2 服务接口。服务响应中的 `true` 表示成功，`false` 表示失败。

> [!NOTE]
>
> 以下命令均通过 `ros2 service call` 调用。地图名称不得以数字开头，且长度不超过 30 个字符。

#### 建图

服务名称：`/LxCamera_Mapping_srv`

服务格式定义：

```bash theme={null}
bool status      # 是否开始建图 true:开始建图 false:停止建图
string mapname   # 地图名称,不能以数字开头,30个字符以内
---
bool result      # 操作结果 true:成功 false:失败
```

指令调试：

```bash theme={null}
ros2 service call /LxCamera_Mapping_srv lx_camera_ros/srv/LxMapping "{
  status: true,
  mapname: 'test_map'
}"
```

#### 切换地图

服务名称：`/LxCamera_SwitchMap_srv`

服务格式定义：

```bash theme={null}
string mapname   # 地图名称,不能以数字开头,30个字符以内
---
bool result       # 操作结果 true:成功 false:失败
```

指令调试：

```bash theme={null}
ros2 service call /LxCamera_SwitchMap_srv lx_camera_ros/srv/LxSwitchMap "{
  mapname: 'zszs999'
}"
```

#### 下载地图

服务名称：`/LxCamera_DownloadMap_srv`

服务格式定义：

```bash theme={null}
string mapname    # 地图名称,不能以数字开头,30个字符以内
string save_path   # 保存路径,例如"/home/lx/map"，最后不带"/"
---
bool result        # 操作结果 true:成功 false:失败
```

指令调试：

```bash theme={null}
ros2 service call /LxCamera_DownloadMap_srv lx_camera_ros/srv/LxDownloadMap "{
  mapname: 'TEST_999',
  save_path: '/home/fr1511b/T/TEST'
}"
```

#### 重定位

服务名称：`/LxCamera_UploadReloc_srv`

服务格式定义：

```bash theme={null}
geometry_msgs/PoseWithCovarianceStamped pose
---
bool result        # 操作结果 true:成功 false:失败
```

指令调试：

```bash theme={null}
ros2 service call /LxCamera_UploadReloc_srv lx_camera_ros/srv/LxUploadReloc "{
  "pose": {
    "header": {
      "stamp": {
        "sec": 0,
        "nanosec": 0
      },
      "frame_id": "map"
    },
    "pose": {
      "pose": {
        "position": {
          "x": 4.5,
          "y": -15.5,
          "z": 0.0
        },
        "orientation": {
          "x": 0.0,
          "y": 0.0,
          "z": 0.694658,
          "w": 0.71934
        }
      },
      "covariance": [
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0
      ]
    }
  }
}"
```

#### 获取当前地图名

服务名称：`/LxCamera_GetCurMapname_srv`

服务格式定义：

```bash theme={null}
bool get_cur_mapname # 获取地图标识
---
string mapname      # 当前地图名
```

指令调试：

```bash theme={null}
ros2 service call /LxCamera_GetCurMapname_srv lx_camera_ros/srv/LxGetmapname "{
  get_cur_mapname: true
}"
```

#### 获取当前地图列表

服务名称：`/LxCamera_GetMapList_srv`

服务格式定义：

```bash theme={null}
bool get_map_list # 是否获取地图列表
---
string[] map_list # 地图列表
```

指令调试：

```bash theme={null}
ros2 service call /LxCamera_GetMapList_srv lx_camera_ros/srv/LxGetmaplist "{
  get_map_list: true
}"
```

#### 退出建图

服务名称：`/LxCamera_ExitMapping_srv`

服务格式定义：

```bash theme={null}
bool exit_mapping # 是否退出建图
---
bool state        # 退出建图是否成功 true:成功 false:失败
```

指令调试：

```bash theme={null}
ros2 service call /LxCamera_ExitMapping_srv lx_camera_ros/srv/LxExitMapping "{
  exit_mapping: true
}"
```

#### 删除地图

服务名称：`/LxCamera_EraseMap_srv`

服务格式定义：

```bash theme={null}
string mapname    # 地图名称,不能以数字开头,30个字符以内
---
bool result        # 删除地图是否成功 true:成功 false:失败
```

指令调试：

```bash theme={null}
ros2 service call /LxCamera_EraseMap_srv lx_camera_ros/srv/LxEraseMap "{
  mapname: 'TEST888'
}"
```

#### 下载热力图

服务名称：`/LxCamera_DownloadHeatMap_srv`

服务格式定义：

```bash theme={null}
string mapname    # 地图名称,不能以数字开头,30个字符以内
string save_path   # 保存路径,例如"/home/lx/map"，最后不带"/"
---
bool result        # 操作结果 true:成功 false:失败
```

指令调试：

```bash theme={null}
ros2 service call /LxCamera_DownloadHeatMap_srv lx_camera_ros/srv/LxDownloadMap "{
  mapname: 'TEST_999',
  save_path: '/home/fr1511b/T/TEST'
}"
```

## 增量建图

服务名称：`/LxCamera_IncMapping_srv`

服务格式定义：

```text theme={null}
bool status      # 是否开始建图 1:开始建图 0:停止建图
string mapname   # 地图名称,不能以数字开头,30个字符以内
---
bool result
```

指令调试：

```bash theme={null}
ros2 service call /LxCamera_IncMapping_srv lx_camera_ros/srv/LxMapping "{
  status: true,
  mapname: 'test_map'
}"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.