# LD导航系统MQTT快速开始指南

## 1. 配置MQTT连接

编辑 `application.yml`:

```yaml
mqtt:
  broker: tcp://192.168.0.30:1883
  username: your_username
  password: your_password
  clientId: server_client_001
  deviceIds: ld000001,ld000002  # 你的设备ID列表
  subscribeTopics:               # 留空使用默认订阅
  qos: 1
```

## 2. 启动应用

启动Spring Boot应用后,系统会自动:
- 连接到MQTT Broker
- 订阅所有LD导航系统相关主题
- 开始接收机器人消息

## 3. 测试连接

### 方式1: 使用Swagger UI

访问: `http://localhost:8080/swagger-ui.html`

找到"MQTT消息管理"分组,可以看到所有可用的API接口。

### 方式2: 使用Postman或curl

#### 请求地图列表
```bash
curl -X POST "http://localhost:8080/mqtt/ld/map/list?deviceId=ld000001"
```

#### 开启导航
```bash
curl -X POST "http://localhost:8080/mqtt/ld/navigation/start?deviceId=ld000001&mapName=map_a"
```

#### 前往目标点
```bash
curl -X POST "http://localhost:8080/mqtt/ld/task/gotoByNid?deviceId=ld000001&mapName=map_a&nid=19"
```

## 4. 查看日志

启动后查看日志,应该能看到:
```
MQTT消息监听器初始化完成
接收MQTT消息 -> 主题：/robot4inspection/ld000001/localization/pose，QoS：0
处理LD导航系统消息 -> 设备ID：ld000001，短主题：/localization/pose
```

## 5. 常用操作流程

### 完整的导航流程

```bash
# 1. 请求地图列表
POST /mqtt/ld/map/list?deviceId=ld000001

# 2. 开启导航(使用某个地图)
POST /mqtt/ld/navigation/start?deviceId=ld000001&mapName=map_a

# 3. 位姿初始化(如果需要)
POST /mqtt/ld/localization/initByNid?deviceId=ld000001&nid=1

# 4. 前往目标点
POST /mqtt/ld/task/gotoByNid?deviceId=ld000001&mapName=map_a&nid=19

# 5. 监听到达事件(自动接收)
# 系统会自动接收 /task/target/event/arrive 消息

# 6. 如需暂停
POST /mqtt/ld/task/pause?deviceId=ld000001

# 7. 继续任务
POST /mqtt/ld/task/resume?deviceId=ld000001

# 8. 取消任务
POST /mqtt/ld/task/cancel?deviceId=ld000001
```

## 6. 在代码中使用

### 注入服务
```java
@Autowired
private MqttSendService mqttSendService;

@Autowired
private RedisCache redisCache;
```

### 发送指令
```java
// 开启导航
boolean success = mqttSendService.startNavigation("ld000001", "map_a");

// 前往目标点
mqttSendService.gotoTargetByNid("ld000001", "map_a", 19);

// 暂停任务
mqttSendService.pauseTask("ld000001");
```

### 获取机器人状态
```java
// 从Redis获取实时位姿
RobotPoseInfo poseInfo = redisCache.getCacheObject("ld:pose:ld000001");
if (poseInfo != null) {
    List<Double> xyz = poseInfo.getPose().getXyz();
    Integer confidence = poseInfo.getConfidence();
    Integer runState = poseInfo.getRunState();
}

// 从Redis获取任务实时信息
TaskRealtimeInfo taskInfo = redisCache.getCacheObject("ld:task:realtime:ld000001");
if (taskInfo != null) {
    String driveMode = taskInfo.getDriveMode();
    Double remainDistance = taskInfo.getOdom().getRemain();
}
```

## 7. 自定义消息处理

编辑 `MqttMessageListener.java`,在对应的处理方法中添加业务逻辑:

```java
private void handleArriveEvent(String deviceId, String payload) {
    try {
        JSONObject json = JSON.parseObject(payload);
        JSONArray argsArray = json.getJSONArray("args");
        if (argsArray != null && !argsArray.isEmpty()) {
            ArriveEventInfo arriveInfo = argsArray.getObject(0, ArriveEventInfo.class);
            
            if ("ok".equals(arriveInfo.getStatus())) {
                // 到达成功 - 实现你的业务逻辑
                log.info("机器人{}成功到达目标点", deviceId);
                // 例如: 更新数据库任务状态
                // taskService.updateTaskStatus(deviceId, "completed");
            } else {
                // 到达失败 - 处理错误
                TaskErrorCode errorCode = TaskErrorCode.fromCode(arriveInfo.getError());
                log.error("机器人{}到达失败: {}", deviceId, errorCode.getDescription());
                // 例如: 记录错误日志
                // errorLogService.recordError(deviceId, errorCode);
            }
        }
    } catch (Exception e) {
        log.error("解析到达事件失败", e);
    }
}
```

## 8. 常见问题

### Q: 连接不上MQTT Broker?
A: 检查:
1. broker地址是否正确
2. 用户名密码是否正确
3. 网络是否通畅
4. MQTT Broker是否正常运行

### Q: 收不到消息?
A: 检查:
1. 订阅主题是否正确
2. 设备是否在线并发送消息
3. 查看日志是否有错误信息

### Q: 发送指令没反应?
A: 检查:
1. 设备ID是否正确
2. 主题格式是否符合规范
3. 设备是否订阅了对应的指令主题
4. 查看MQTT Broker的消息日志

### Q: 如何调试MQTT消息?
A: 使用MQTT客户端工具:
1. MQTTX (推荐,图形化界面)
2. mosquitto_sub/mosquitto_pub (命令行)
3. 查看应用日志

## 9. 下一步

- 阅读完整文档: `README.md`
- 查看接口规范: `LD导航系统MQTT接口.md`
- 查看变更日志: `CHANGELOG.md`
- 实现自定义业务逻辑
- 编写单元测试

## 10. 技术支持

如有问题,请查看:
1. 项目文档
2. 日志文件
3. MQTT Broker管理界面
4. 联系开发团队