> ## 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 ROS1 接口说明

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

## 编译

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

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

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

在 `/V2-ROS-SDK-service` 目录（与 `src` 同级）编译 ROS 功能包：

```bash theme={null}
catkin_make
```

## 运行

> [!WARNING]
>
> 若相机已部署 ROS 主从配置，请先关闭相关设置，否则可能发生通信异常。相机上电后等待约 20 秒，再启动 ROS 示例程序。

在 `home/username/V2_ROS_SDK` 目录中（与 `src` 同级）执行：

```bash theme={null}
catkin_make
source devel/setup.bash
```

## ROS 话题接口

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

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

### 接收定位位姿接口

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

```bash theme={null}
rostopic echo /lx_localization_node/LxCamera_LocationPoseResult
```

### 接收定位状态接口

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

```bash theme={null}
rostopic echo /lx_localization_node/LxCamera_LocationResult
```

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

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

```bash theme={null}
rostopic echo /lx_localization_node/LxCamera_Capacity_Status
```

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

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

```bash theme={null}
rostopic echo /lx_localization_node/LxCamera_Module_Error
```

### 接收建图状态接口

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

```bash theme={null}
rostopic echo /lx_localization_node/LxCamera_MappingState
```

### 接收建图进度接口

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

```bash theme={null}
rostopic echo /lx_localization_node/LxCamera_Mapping_Progress
```

### 设置参数接口

向 `LxCamera_SetParam` 发布 `std_msgs/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 devel/setup.bash
rostopic pub -1 /lx_localization_node/LxCamera_SetParam std_msgs/String "11,11,10.2,11.2,12.2,13.2,2,2,2"
```

### 切换地图接口

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

```bash theme={null}
source devel/setup.bash
rostopic pub -1 /lx_localization_node/LxCamera_SwitchMap std_msgs/String "for"
```

### 上传里程计

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

rostopic pub /odom nav\_msgs/Odometry "header: seq: 0 stamp: secs: 0 nsecs: 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]"

```cpp theme={null}
// 进入lx_camera_udp目录
//开启终端
source devel/setup.bash
rostopic pub -1 /lx_localization_node/sim/odom std_msgs/String "for"
```

### 下载轮廓地图接口

1. 用户发布`std_msgs/String`类型消息到topic：`LxCamera_DownloadMap`
2. 消息格式为一个保存地址和一个地图名称，使用英文逗号“,”分割。地址是上位机中的地址，使用绝对路径；地图名是相机中已经完成建图的“.zip”格式的文件名。
3. 成功后，你上位机指定的路径下会有一个指定地图名称的压缩包，解压后得到一个`pgm地图文件`和一个`yaml配置文件`。

```cpp theme={null}
// 进入lx_camera_udp目录
//开启终端
source devel/setup.bash
rostopic pub -1 /lx_localization_node/LxCamera_DownloadMap std_msgs/String "/home/zsure/LANXIN,TEST_999"
```

### 上传地图文件zip接口（new）

1. 用户发布`std_msgs/String`类型消息到topic：`LxCamera_UploadMapZip`
2. 消息内容为需要上传的**地图压缩包路径**, 例如：“/home/fr1511b/map.zip” ,需上传 由下载接口下载下来的压缩包
3. 如果找到地图文件则打包后发送到相机，相机接收后会解压到指定的路径：`/home/fr1511b/hontai/map/`

```cpp theme={null}
rostopic pub -1 /lx_localization_node/LxCamera_UploadMapZip std_msgs/String "map_path"
```

### 重定位接口

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

```cpp theme={null}
rostopic pub -1 /lx_localization_node/LxCamera_UploadReloc geometry_msgs/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` 顺序传入单位四元数。

## ROS 服务接口

建图、切换地图、下载地图和重定位除支持话题方式外，也支持 ROS 服务接口。服务返回 `true` 表示操作成功，返回 `false` 表示操作失败。对于需要确认执行结果的操作，建议优先使用服务接口。

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

### 建图

服务名称：`/lx_localization_node/LxCamera_Mapping_srv`

服务格式定义：

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

指令调试：

```bash theme={null}
rosservice call /lx_localization_node/LxCamera_Mapping_srv "status: true
mapname: 'test_map'"
```

### 切换地图

服务名称：`/lx_localization_node/LxCamera_SwitchMap_srv`

服务格式定义：

```text theme={null}
string mapname   # 地图名称,不能以数字开头,30个字符以内
---
bool result
```

指令调试：

```bash theme={null}
rosservice call /lx_localization_node/LxCamera_SwitchMap_srv "mapname: 'zszs999'"
```

### 下载地图

服务名称：`/lx_localization_node/LxCamera_DownloadMap_srv`

服务格式定义：

```text theme={null}
string mapname    # 地图名称,不能以数字开头,30个字符以内
string save_path  # 保存路径,例如 “/home/lx/map”，最后不带“/”
---
bool result
```

指令调试：

```bash theme={null}
rosservice call /lx_localization_node/LxCamera_DownloadMap_srv "mapname: 'TEST_999'
save_path: '/home/fr1511b/T/TEST'"
```

### 重定位

服务名称：`/lx_localization_node/LxCamera_UploadReloc_srv`

服务格式定义：

```text theme={null}
geometry_msgs/PoseWithCovarianceStamped pose
---
bool result
```

指令调试：

```bash theme={null}
rosservice call /lx_localization_node/LxCamera_UploadReloc_srv "pose:
  header:
    seq: 0
    stamp:
      secs: 0
      nsecs: 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]"
```

### 获取当前地图名

服务名称：`/lx_localization_node/LxCamera_GetCurMapname_srv`

服务格式定义：

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

指令调试：

```cpp theme={null}
rosservice call /lx_localization_node/LxCamera_GetCurMapname_srv "get_cur_mapname: true"
```

### 获取当前地图列表

服务名称：`/lx_localization_node/LxCamera_GetMapList_srv`

服务格式定义：

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

指令调试：

```cpp theme={null}
rosservice call /lx_localization_node/LxCamera_GetMapList_srv "get_map_list: true"
```

### 退出建图 (定制接口)

服务名称：`/lx_localization_node/LxCamera_ExitMapping_srv`

服务格式定义：

```cpp theme={null}
bool exit_mapping #是否退出建图
---
bool state #退出建图是否成功
```

指令调试：

rosservice call /lx\_localization\_node/LxCamera\_ExitMapping\_srv "exit\_mapping: true"

### 删除地图

服务名称：`/lx_localization_node/LxCamera_EraseMap_srv`

服务格式定义：

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

指令调试：

```bash theme={null}
rosservice call /lx_localization_node/LxCamera_EraseMap_srv "mapname: 'TEST888'"
```

### 下载热力图

服务名称：`/lx_localization_node/LxCamera_DownloadMap_srv`

服务格式定义：

```cpp theme={null}
string mapname    # 地图名称,不能以数字开头,30个字符以内
string save_path  # 保存路径,例如 “/home/lx/map”，最后不带“/”
---
bool result
```

指令调试：

rosservice call /lx\_localization\_node/LxCamera\_DownloadHeatMap\_srv "mapname: 'TEST\_999' save\_path: '/home/fr1511b/T/TEST'"

### 增量建图

服务名称：`/lx_localization_node/LxCamera_IncMapping_srv`

服务格式定义：

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

指令调试：

```cpp theme={null}
rosservice call /lx_localization_node/LxCamera_IncMapping_srv "status: true
mapname: 'test_map'"
```


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