RobotSpineAdmin/ruoyi-admin/src/main/java/com/ruoyi/mqtt/QUICKSTART.md

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

1. 配置MQTT连接

编辑 application.yml:

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

请求地图列表

curl -X POST "http://localhost:8080/mqtt/ld/map/list?deviceId=ld000001"

开启导航

curl -X POST "http://localhost:8080/mqtt/ld/navigation/start?deviceId=ld000001&mapName=map_a"

前往目标点

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. 常用操作流程

完整的导航流程

# 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. 在代码中使用

注入服务

@Autowired
private MqttSendService mqttSendService;

@Autowired
private RedisCache redisCache;

发送指令

// 开启导航
boolean success = mqttSendService.startNavigation("ld000001", "map_a");

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

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

获取机器人状态

// 从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,在对应的处理方法中添加业务逻辑:

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. 联系开发团队