# mqtt-lab

**Repository Path**: stevenye/mqtt-lab

## Basic Information

- **Project Name**: mqtt-lab
- **Description**: 一个真正符合物联网项目分层思路、但又足够小的完整实验
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MQTT-Lab - 物联网实时监控实验项目

> 一个真正符合物联网项目分层思路、但又足够小的完整实验

## 项目架构

本项目遵循标准的物联网四层架构设计：

```
┌─────────────────────────────────────────────────────────────────┐
│                        应用层 (Application)                      │
│                      iot-web (Vue3 + TS)                        │
│                    实时监控界面 / 数据可视化                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        平台层 (Platform)                         │
│                 iot-platform (Spring Boot + WebFlux)             │
│              数据处理 / 状态管理 / 实时推送 (SSE)                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         网络层 (Network)                         │
│                    Mosquitto MQTT Broker                        │
│                        消息路由 / 通信协议                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       设备层 (Device)                            │
│                 device-simulator (Java + Paho)                  │
│                  模拟传感器数据采集 (3台设备)                      │
└─────────────────────────────────────────────────────────────────┘
```

## 技术栈

| 层级 | 技术组件 | 说明 |
|------|---------|------|
| **设备层** | Java 17 + Eclipse Paho MQTT + Jackson + Lombok | 设备模拟器，生成传感器数据 |
| **网络层** | Mosquitto MQTT Broker | 轻量级消息中间件，端口 1883 |
| **平台层** | Spring Boot 3.3.3 + WebFlux + Spring Integration MQTT | 数据处理与实时推送 |
| **应用层** | Vue 3 + TypeScript + Vite | 前端监控界面 |

## 数据流

```
设备模拟器 ──MQTT Publish──> Mosquitto Broker ──MQTT Subscribe──> 平台服务
    │                           │                              │
    │                           │                              ├─> 状态存储 (ConcurrentHashMap)
    │                           │                              │
    │                           │                              └─> SSE 推送 (Reactor Sinks)
    │                           │                                      │
    │                           │                                      ▼
    │                           │                              前端实时监控
    │                           │
    └───────────────────────────┴──────────────────────────────────────┘
                    MQTT Topic: iot/device/{deviceId}/telemetry
```

## 项目结构

```
mqtt-lab/
├── device-simulator/          # 设备模拟层
│   ├── pom.xml
│   └── src/main/java/
│       └── com/tec/sdedu/devicesimulator/
│           ├── entity/
│           │   └── TelemetryData.java      # 遥测数据实体
│           └── service/
│               └── DeviceSimulator.java     # 设备模拟器主程序
│
├── iot-platform/              # 平台层
│   ├── pom.xml
│   └── src/main/java/
│       └── com/tec/sdedu/iotplatform/
│           ├── config/
│           │   ├── MqttConfig.java          # MQTT 连接配置
│           │   ├── MqttInboundConfig.java   # MQTT 入站适配器
│           │   └── CorsConfig.java          # 跨域配置
│           ├── controller/
│           │   ├── DeviceDataController.java # REST API 接口
│           │   └── DeviceStreamController.java # SSE 流式接口
│           └── service/
│               ├── DeviceMessageService.java # 消息处理服务
│               ├── DeviceStateService.java   # 设备状态管理
│               └── DeviceRealtimeService.java # 实时推送服务
│
├── iot-web/                   # 应用层
│   ├── package.json
│   ├── vite.config.ts
│   └── src/
│       ├── main.ts
│       ├── App.vue
│       └── views/
│           └── DeviceMonitor.vue            # 设备监控页面
│
└── README.md
```

## 快速开始

### 环境要求

- **JDK 17+**
- **Maven 3.8+**
- **Node.js 18+**
- **Mosquitto MQTT Broker** (默认端口 1883)

### 1. 启动 Mosquitto Broker

```bash
# Windows (使用 Chocolatey)
choco install mosquitto
mosquitto -c mosquitto.conf

# 或使用 Docker
docker run -d -p 1883:1883 eclipse-mosquitto:2
```

### 2. 启动设备模拟器

```bash
cd device-simulator
mvn clean compile exec:java -Dexec.mainClass="com.tec.sdedu.devicesimulator.service.DeviceSimulator"
```

### 3. 启动平台服务

```bash
cd iot-platform
mvn spring-boot:run
```

平台服务启动后：
- REST API: `http://localhost:8080/api/devices`
- SSE 流: `http://localhost:8080/api/devices/stream`

### 4. 启动前端应用

```bash
cd iot-web
npm install
npm run dev
```

前端应用默认运行在 `http://localhost:5173`

## API 接口

### REST API

**获取所有设备数据**

```http
GET /api/devices
```

响应示例：
```json
[
  {
    "deviceId": "sensor-001",
    "temperature": 25.5,
    "humidity": 65.2,
    "timestamp": 1692345678123
  },
  {
    "deviceId": "sensor-002",
    "temperature": 28.3,
    "humidity": 58.7,
    "timestamp": 1692345678123
  }
]
```

### SSE (Server-Sent Events)

**实时数据流**

```http
GET /api/devices/stream
Accept: text/event-stream
```

事件格式：
```
data: {"deviceId":"sensor-001","temperature":25.5,"humidity":65.2,"timestamp":1692345678123}
```

## MQTT 主题设计

| 主题 (Topic) | 说明 | QoS |
|--------------|------|-----|
| `iot/device/{deviceId}/telemetry` | 设备遥测数据上报 | 1 |

示例：
- `iot/device/sensor-001/telemetry`
- `iot/device/sensor-002/telemetry`
- `iot/device/sensor-003/telemetry`

## 数据格式

```json
{
  "deviceId": "sensor-001",
  "temperature": 25.5,
  "humidity": 65.2,
  "timestamp": 1692345678123
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `deviceId` | String | 设备唯一标识 |
| `temperature` | Double | 温度值 (°C)，范围 20-35 |
| `humidity` | Double | 湿度值 (%)，范围 40-80 |
| `timestamp` | Long | 数据采集时间戳 (毫秒) |

## 核心特性

### 设备模拟器
- 模拟 3 台传感器设备 (sensor-001, sensor-002, sensor-003)
- 每 3 秒采集一次温湿度数据
- 数据通过 MQTT 协议发布到 Broker

### 平台服务
- **MQTT 订阅**：自动订阅设备遥测数据
- **状态管理**：使用 ConcurrentHashMap 存储设备最新状态
- **实时推送**：基于 Reactor Sinks 实现 SSE 数据流
- **RESTful API**：提供设备数据查询接口
- **跨域支持**：允许前端跨域访问

### 前端监控
- 初始化时通过 REST API 获取所有设备数据
- 通过 SSE 建立实时数据连接
- 实时更新设备温湿度显示

## 扩展建议

1. **数据持久化**：将设备数据存储到 MySQL/PostgreSQL
2. **设备认证**：添加 MQTT 认证机制 (Username/Password 或 TLS)
3. **告警功能**：设置温湿度阈值告警
4. **历史数据**：添加历史数据查询和图表展示
5. **设备管理**：实现设备注册、配置、OTA 升级等功能
6. **部署优化**：使用 Docker Compose 编排所有服务

## 许可证

[MIT License](LICENSE)

## 作者

叶加飞