> ## 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.

# ROS 快速入门

> 配置并运行 V2 视觉定位模块 ROS SDK，完成建图、切换地图、重定位和定位结果订阅。

## 概述

V2 定位模块中的定位程序通过 UDP 与上位机 ROS SDK 通信。模块内置 Web 前端，可用于执行建图、定位和参数配置；ROS SDK 可调用建图、重定位和地图下载等相同能力。

![V2 定位模块与 ROS SDK 的通信架构](https://mintcdn.com/mrdvs/YGY7ZL7PZ7ENJc3f/images/developers/ros-quickstart-preface.avif?fit=max\&auto=format\&n=YGY7ZL7PZ7ENJc3f\&q=85\&s=ab023bfb46ed7a0a86c0c08c65498fa9)

> [!NOTE]
>
> 默认 Web 前端地址为 `192.168.100.201:9998`。相机与 ROS SDK 的目标 IP 和端口必须分别配置，并保持一致。

## 准备环境

安装 Qt5 的 Core 和 Network 组件，以及 `libzip` 依赖。以下为 Ubuntu 的 Qt5 安装示例：

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

按 [libzip 安装说明](https://blog.csdn.net/iamhuanyu/article/details/129603632)安装 `libzip`，然后在 `/V2-ROS-SDK-service` 目录（与 `src` 同级）编译：

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

## 配置并启动节点

**1. 检查 ROS SDK 配置**

打开 `/V2-ROS-SDK-service/src/lx_camera_ros/launch/mapping.launch`。相机默认 IP 为 `192.168.100.201`；如修改相机 IP，须在此文件中同步更新。端口填写 `8001`。

![mapping.launch 中的相机连接配置](https://mintcdn.com/mrdvs/YGY7ZL7PZ7ENJc3f/images/developers/ros-quickstart-operation-2.avif?fit=max\&auto=format\&n=YGY7ZL7PZ7ENJc3f\&q=85\&s=d354c84187b486d7f2eff73ce44bae8c)

**2. 检查网络与模块参数**

确认相机与上位机接入同一交换机并处于同一网段。在 Web 前端中打开 **参数配置**，将 `portCode` 设为 `8987`，将 `portName` 设为运行 ROS SDK 的上位机网卡 IP。

![Web 前端的参数配置入口](https://mintcdn.com/mrdvs/YGY7ZL7PZ7ENJc3f/images/developers/ros-quickstart-operation-3.avif?fit=max\&auto=format\&n=YGY7ZL7PZ7ENJc3f\&q=85\&s=8783c08422f3a93163e858a71b81fb76)

![Web 前端中的 UDP 端口与目标地址配置](https://mintcdn.com/mrdvs/YGY7ZL7PZ7ENJc3f/images/developers/ros-quickstart-operation-4.avif?fit=max\&auto=format\&n=YGY7ZL7PZ7ENJc3f\&q=85\&s=ee2ce85e951a30bbef2db08b9b7a71ff)

**3. 启动 ROS 节点**

```bash theme={null}
cd /V2-ROS-SDK-service
source devel/setup.bash
roslaunch lx_camera_ros mapping.launch
```

节点正常启动后，终端会输出启动信息。

![ROS 节点成功启动的终端输出](https://mintcdn.com/mrdvs/YGY7ZL7PZ7ENJc3f/images/developers/ros-quickstart-operation-5.avif?fit=max\&auto=format\&n=YGY7ZL7PZ7ENJc3f\&q=85\&s=dc02ddd14decd7fef06744def171f42f)

## 验证通信

在新的终端中进入 `/V2-ROS-SDK-service` 并加载环境：

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

订阅存储空间状态话题以验证通信链路。该话题可作为心跳，发布频率为 2 Hz：

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

![订阅存储空间状态话题的终端输出](https://mintcdn.com/mrdvs/YGY7ZL7PZ7ENJc3f/images/developers/ros-quickstart-debugging.avif?fit=max\&auto=format\&n=YGY7ZL7PZ7ENJc3f\&q=85\&s=2d95227fe992a48a59a93de6e36e0f4a)

也可调用以下服务读取当前地图名称：

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

![获取当前地图名称的服务调用结果](https://mintcdn.com/mrdvs/YGY7ZL7PZ7ENJc3f/images/developers/ros-quickstart-debugging-2.avif?fit=max\&auto=format\&n=YGY7ZL7PZ7ENJc3f\&q=85\&s=13eb8f01cfea4bf80b63cb44bf680f66)

## 建图与定位

相机上电后等待约 30 秒，待本体程序启动完成后再启动数据转发节点。

**1. 开始建图**

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

服务返回 `true` 后，移动载体采集地图。

![开始建图后的 Web 前端状态](https://mintcdn.com/mrdvs/YGY7ZL7PZ7ENJc3f/images/developers/ros-quickstart-basic-operating-procedures.avif?fit=max\&auto=format\&n=YGY7ZL7PZ7ENJc3f\&q=85\&s=d61b86fbb7189e9e2f0f6008dcbcf55e)

**2. 结束建图**

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

等待服务返回 `true`，确认建图完成。

![结束建图后的 Web 前端状态](https://mintcdn.com/mrdvs/YGY7ZL7PZ7ENJc3f/images/developers/ros-quickstart-basic-operating-procedures-2.avif?fit=max\&auto=format\&n=YGY7ZL7PZ7ENJc3f\&q=85\&s=09b3b5ccc74f396f447799b9da143276)

**3. 切换至新地图**

```bash theme={null}
rosservice call /lx_localization_node/LxCamera_SwitchMap_srv "map_name: 'test_map'"
```

**4. 发送重定位位姿**

`orientation.x`、`orientation.y`、`orientation.z` 和 `orientation.w` 为姿态四元数，须按 ROS 消息格式填写。

```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]"
```

**5. 订阅实时定位结果**

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

## 排查问题

> **ROS 程序无法编译**
>
> 检查 Qt5 和 `libzip` 是否已完整安装，再重新执行 `catkin_make`。

> **ROS SDK 发送消息后无响应**
>
> 确认相机与上位机处于同一网段，且可通过相机上位机软件访问相机。随后核对相机端与 ROS SDK 端的配置。

> **无法发送 ROS 调试消息**
>
> ROS 消息格式严格。请保留示例中的字段结构，仅修改需要测试的值。


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