数据流架构
从设备上电到 App 控制的完整数据闭环。
全链路概览
┌──────────┐ BLE 配网 ┌──────────────┐ WiFi/MQTT ┌──────────────┐
│ ESP32 │ ──────────────→ │ 移动端 APP │ ──────────────→ │ 服务端 │
│ 固件 │ ←────────────── │ (Flutter) │ ←────────────── │ (Go+Gin) │
└──────────┘ WiFi 信息 └──────────────┘ 设备注册/ └──────────────┘
↑ 控制指令 ↑
│ │
│ MQTT 消息 │
│ │
┌──────────────┐ │
│ MQTT Broker │ ──────────────────────┘
│ (内置) │ 设备上线/状态推送
└──────────────┘
↑
│ MQTT 连接
┌──────────────┐
│ ESP32 设备 │
│ (WiFi 已连接) │
└──────────────┘阶段一：BLE 配网
设备首次上电进入配网模式（LED 五次快闪），移动端 APP 通过 BLE 扫描连接：
APP ESP32 设备
│ │
│── BLE 扫描 ─────────────────→│ 设备广播: IoT-Switch-XXXX
│ │
│── BLE 连接 ─────────────────→│ 建立 GATT 连接
│ │
│── 写入 WiFi 信息 ───────────→│ {"ssid":"...", "password":"...", "apiUrl":"..."}
│ │
│ │── 连接 WiFi
│ │── 注册到服务端
│ │── 连接 MQTT Broker
│ │
│←── 配网完成通知 ─────────────│ 设备上线- 设备蓝牙名称格式：
IoT-Wakeup-XXXX或IoT-Switch-XXXX - 配置数据 JSON：
{"ssid": "YourWiFi", "password": "YourPassword", "apiUrl": "http://192.168.1.100:48080"}
阶段二：设备注册与激活
设备通过 WiFi 连接到服务端 API 完成注册：
ESP32 设备 服务端 (Go) MySQL
│ │ │
│── POST /api/v1/devices/ │ │
│ register ─────────────────→│── 写入设备记录 ────────→│
│ │ │
│←── 返回设备凭证 ─────────────│←── 确认 ───────────────│
│ │ │
│ │ Redis
│ │ │
│── MQTT CONNECT ─────────────→│── 验证凭证 ───────────→│ 设备在线状态
│ (使用注册凭证) │ │阶段三：实时控制闭环
设备上线后，App 通过服务端 + MQTT 实现远程控制：
APP (Flutter) 服务端 (Go) MQTT Broker ESP32 设备
│ │ │ │
│── POST /api/v1/control ─────→│ │ │
│ {action: "on"} │── PUBLISH 控制指令 ───→│ │
│ │ topic: device/cmd/ │── 转发 ────────────→│
│ │ │ │── 执行动作
│ │ │←── 状态上报 ────────│
│ │←── 订阅状态 ──────────→│ │
│←── 返回执行结果 ─────────────│ │ │
│ │ │ Redis
│ │── 更新在线状态 ──────────────────────────────→│关键组件说明
| 组件 | 技术选型 | 职责 |
|---|---|---|
| 服务端 API | Go + Gin + GORM | 设备/产品管理、认证、控制指令下发 |
| MQTT Broker | 内置（替代 EMQX） | 设备消息路由、实时通信 |
| MySQL | 8.x | 设备、产品、物模型持久化 |
| Redis | 7.x | 设备在线状态缓存、会话管理 |
| 移动端 APP | Flutter + Dart | BLE 配网、设备列表、远程控制 |
| ESP32 固件 | Arduino + PlatformIO | 设备端 BLE/WiFi/MQTT 运行时 |
端口映射
| 端口 | 服务 | 协议 |
|---|---|---|
| 48080 | Core API | HTTP |
| 48883 | MQTT Broker | TCP |
| 48803 | MQTT Broker | WebSocket |
| 48884 | MQTT Dashboard | HTTP |
| 48306 | MySQL | TCP |
| 48379 | Redis | TCP |
相关文档
- 仓库架构 — 代码组织与模块边界
- 配置链路 — 从固件到服务端的完整配置链
- 设备统一规范 — 设备接入标准
- 本地模拟器 Runbook — 本地联调指南