0ce191c448
纳入范围: - backend/ Spring Boot 多模块后端(iot-common/device/rule/data/alarm/auth) - frontend/admin/ Vue3 + Element Plus 管理后台 - Android/ 涂鸦原生 APP (com.xhai.iot) - backend/sql/ Flyway 风格迁移脚本(V2~V21) - docs/ 对接文档与设计文档 排除范围: - 构建产物: node_modules/ target/ build/ dist/ .gradle/ - 签名密钥: *.jks *.keystore (严禁入库) - 本机配置: Android/local.properties - 运行日志: logs/ *.log - AI 协作本地数据 .codebuddy/ 与第三方 demo tuya-demo/ .gitattributes 统一以 LF 存储, Windows 批处理保留 CRLF
333 lines
15 KiB
Markdown
333 lines
15 KiB
Markdown
# 智能家居中控屏 Zigbee + Matter 直连后台方案
|
||
|
||
## 一、客户需求
|
||
|
||
客户想采用瑞芯微 RK3568 的 Android 15 系统，开发 10.1 寸智能家居中控屏，采用 Zigbee + Matter 协议。Zigbee 采用涂鸦 ZSU 模组（买空片，未烧录涂鸦固件）。
|
||
|
||
### ZSU 模组规格
|
||
|
||
| 项目 | 参数 |
|
||
|------|------|
|
||
| 芯片 | Silicon Labs EFR32MG21A020F1024IM32-B |
|
||
| 内核 | ARM Cortex-M33，80 MHz |
|
||
| Flash / RAM | 1024 KB / 96 KB |
|
||
| 协议 | IEEE 802.15.4 / Zigbee |
|
||
| 频段 | 2.4 GHz（信道 11–26） |
|
||
| 速率 | 250 Kbps |
|
||
| 发射功率 | 最大 +20 dBm |
|
||
| 天线 | 内置 PCB 天线（增益 1.36 dBi） |
|
||
| 工作温度 | -40℃ ~ 105℃ |
|
||
| 加密 | AES 128/256 硬件加密 |
|
||
|
||
### 核心诉求
|
||
|
||
**不经过涂鸦接口，直接接入我们后台。**
|
||
|
||
### 关键前提
|
||
|
||
ZSU 模组为**空片**（未烧录涂鸦固件），可在 EFR32MG21 芯片上烧录任意固件，完全自主可控，不受涂鸦私有协议束缚。
|
||
|
||
---
|
||
|
||
## 二、总体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ RK3568 Android 15 (AOSP 定制固件) │
|
||
│ │
|
||
│ ┌────────────────────────────────────────────────────────┐ │
|
||
│ │ 系统应用层 (System App, Java/Kotlin) │ │
|
||
│ │ │ │
|
||
│ │ ┌──────────────┐ ┌───────────────────────┐ │ │
|
||
│ │ │ 中控屏 UI App │ │ 网关管理服务 │ │ │
|
||
│ │ │ (10.1寸界面) │ │ (GatewayService) │ │ │
|
||
│ │ │ 设备列表/控制 │ │ - 配网管理 API │ │ │
|
||
│ │ │ 场景/定时 │ │ - 设备状态管理 │ │ │
|
||
│ │ └──────────────┘ │ - MQTT 上报/指令分发 │ │ │
|
||
│ │ │ - 与 Native 层 IPC │ │ │
|
||
│ │ └───────────┬───────────┘ │ │
|
||
│ └────────────────────────────────┼────────────────────────┘ │
|
||
│ │ AIDL/Binder │
|
||
│ ┌────────────────────────────────▼────────────────────────┐ │
|
||
│ │ Native 守护进程层 (C/C++, init.rc 启动) │ │
|
||
│ │ │ │
|
||
│ │ ┌──────────────┐ ┌───────────────────────┐ │ │
|
||
│ │ │ zigbee-core │ │ matter-chip │ │ │
|
||
│ │ │ (EZSP串口) │ │ (Matter协议栈) │ │ │
|
||
│ │ │ UART ↔ ZCL │ │ Commissioning/控制 │ │ │
|
||
│ │ └──────────────┘ └───────────────────────┘ │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────┐ │
|
||
│ │ /dev/ttyS1 │ ← ZSU 模组 UART 串口 │
|
||
│ └──────────────┘ │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
│ MQTT
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ 我们后端 (iot-device / iot-data) │
|
||
│ MQTT Broker (1883) │
|
||
│ iot/devices/+/data (数据上报) │
|
||
│ iot/devices/+/status (状态变更) │
|
||
│ iot/devices/+/command(指令下发) │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
### 数据链路说明
|
||
|
||
1. **Zigbee 子设备** 通过 802.15.4 无线连接到 ZSU 模组（Coordinator）
|
||
2. **Matter 设备** 通过 WiFi 直连 RK3568 上的 Matter Controller
|
||
3. ZSU 模组通过 UART 串口与 RK3568 通信（EZSP 协议）
|
||
4. RK3568 网关代理将设备数据转换为标准 JSON，通过 MQTT 上报后端
|
||
5. 后端通过 MQTT `command` topic 下发指令，网关代理转换为 ZCL/Matter 命令
|
||
|
||
---
|
||
|
||
## 三、ZSU 模组固件方案
|
||
|
||
EFR32MG21 烧录 **Silicon Labs 官方 EmberZNet Zigbee Coordinator 固件**，通过 **EZSP（Ember Zigbee Serial Protocol）** 与 RK3568 通信。
|
||
|
||
| 项目 | 方案 |
|
||
|------|------|
|
||
| 协议栈 | Silicon Labs EmberZNet PRO（Zigbee 3.0 认证） |
|
||
| 角色 | Coordinator（协调器，网络中心节点） |
|
||
| 通信接口 | UART，使用 EZSP ASH 协议帧 |
|
||
| 固件来源 | Silicon Labs Simplicity Studio 生成（免费，需注册 SL 账号） |
|
||
| 配套工具 | zigbee-herdsman（Node.js）或自研 C 库 |
|
||
|
||
**优势**：EmberZNet 是业界最成熟的 Zigbee 协议栈，兼容所有标准 Zigbee 3.0 设备（飞利浦 Hue、宜家、小米等标准子设备）。
|
||
|
||
---
|
||
|
||
## 四、Matter 方案
|
||
|
||
RK3568 运行 Android 15，**Matter 控制器直接运行在中控屏上**，不需要 ZSU 模组参与（Matter 设备走 WiFi/Thread）。
|
||
|
||
| 项目 | 方案 |
|
||
|------|------|
|
||
| Matter 协议栈 | Google matter.js 或 Android CHIP SDK（官方推荐） |
|
||
| Commissioning | RK3568 上发起，扫码或 NFC 配网 |
|
||
| Thread 支持 | 可选：若需 Thread Border Router，需第二颗 ZSU 模组或双协议栈固件 |
|
||
| 设备控制 | 中控屏本地直连 Matter 设备，不经过云 |
|
||
|
||
> 注：EFR32MG21 同时支持 Zigbee 和 Thread（均为 802.15.4），但同一时刻只能运行其中一种固件。若需 Thread Border Router，需用第二颗模组。一期建议 Matter 走 WiFi，二期再评估 Thread。
|
||
|
||
---
|
||
|
||
## 五、网关代理 App 部署形态
|
||
|
||
### 5.1 结论
|
||
|
||
**不采用独立安装的普通 App，以 Android 系统级服务方式集成到 AOSP 嵌入式固件中。**
|
||
|
||
RK3568 运行的是客户自编译的 AOSP（Android Open Source Project），网关代理作为**系统内置服务**，而非用户可卸载的普通 App。
|
||
|
||
### 5.2 三层架构
|
||
|
||
| 层 | 形态 | 语言 | 职责 | 升级频率 |
|
||
|----|------|------|------|----------|
|
||
| **Native 守护进程** | C/C++ 可执行文件，`init.rc` 启动 | C/C++ | EZSP 串口通信、ZCL 命令、CHIP SDK | 极少 |
|
||
| **系统应用 (GatewayService)** | 编译进 AOSP 的 System App | Java/Kotlin | 配网管理、设备状态、MQTT 上报、指令分发 | 中等 |
|
||
| **中控屏 UI App** | System App，可独立 OTA | Java/Kotlin | 10.1 寸触控界面 | 较高 |
|
||
|
||
### 5.3 为什么选系统应用而非独立 App
|
||
|
||
| 对比项 | 独立 App | 系统应用（推荐） |
|
||
|--------|----------|------------------|
|
||
| 开机自启 | 需监听 BOOT_COMPLETED，可能被杀 | 随系统启动，不会被杀 |
|
||
| 串口访问 | 需 USB Host 或反射，权限受限 | 直接读写 `/dev/ttyS1`，system 权限 |
|
||
| Matter Commissioning | 需 Google Play Services | 系统级集成 CHIP SDK，不依赖 GPS |
|
||
| 网络稳定性 | 后台被杀则设备离线 | 作为系统服务常驻，设备永远在线 |
|
||
| OTA 升级 | APK 独立升级 | 系统应用也可独立 OTA（无需刷固件） |
|
||
| 用户体验 | 用户可误删 | 不可卸载，出厂内置 |
|
||
|
||
### 5.4 Native 守护进程
|
||
|
||
用 C/C++ 实现底层协议栈，编译为 Native 可执行文件，通过 `init.rc` 配置开机启动：
|
||
|
||
```rc
|
||
# device/rockchip/rk3568/init.gateway.rc
|
||
service zigbee_core /system/bin/zigbee-core /dev/ttyS1 115200
|
||
class main
|
||
user system
|
||
group system
|
||
oneshot
|
||
seclabel u:r:gateway_service:s0
|
||
|
||
service matter_chip /system/bin/matter-chip --controller
|
||
class main
|
||
user system
|
||
group system inet
|
||
seclabel u:r:gateway_service:s0
|
||
```
|
||
|
||
**职责**：
|
||
- `zigbee-core`：EZSP 串口通信、Zigbee 设备配对/控制、ZCL 命令收发
|
||
- `matter-chip`：基于 Google CHIP (C++) SDK，Matter Commissioning 和设备控制
|
||
|
||
**为什么用 C/C++ 而非 Java**：
|
||
- EmberZNet 的 EZSP 库是 C 语言
|
||
- Google Matter SDK 官方实现是 C++
|
||
- 串口实时通信 C 更高效，延迟低
|
||
|
||
### 5.5 系统应用 (GatewayService)
|
||
|
||
编译进 AOSP 的 System App，通过 AIDL/Binder 与 Native 进程通信：
|
||
|
||
```java
|
||
// 网关管理服务
|
||
public class GatewayService extends IGatewayService.Stub {
|
||
// Zigbee 配网
|
||
public int startPermitJoin(int duration) { ... }
|
||
public List<ZigbeeDevice> getPairedDevices() { ... }
|
||
public int removeDevice(String ieeeAddr) { ... }
|
||
|
||
// Matter 配网
|
||
public String generateMatterQRCode() { ... }
|
||
public int commissionDevice(String payload) { ... }
|
||
|
||
// 指令下发
|
||
public int sendCommand(String deviceId, String command, JSONObject params) { ... }
|
||
|
||
// 与后端 MQTT 通信
|
||
private MqttClient mqttClient;
|
||
private void reportToServer(String deviceId, String data) { ... }
|
||
}
|
||
```
|
||
|
||
### 5.6 嵌入式开发要求
|
||
|
||
| 问题 | 回答 |
|
||
|------|------|
|
||
| 是否需要 Android 嵌入式开发能力？ | 是。需编译 AOSP 固件、配置 `init.rc`、编写 SELinux 规则 |
|
||
| 是否需要改 Linux 内核？ | 通常不需要，RK3568 的 UART 驱动内核已支持 |
|
||
| 是否需要硬件原理图？ | 需要，确认 ZSU 模组的 UART 接到 RK3568 的哪个串口 |
|
||
| 开发环境 | Ubuntu + AOSP 源码 + RK3568 SDK（瑞芯微提供） |
|
||
| 调试方式 | ADB + 串口日志 + Wireshark 抓 Zigbee 包 |
|
||
|
||
---
|
||
|
||
## 六、后端需要做的工作
|
||
|
||
### 6.1 已有可复用的基础设施
|
||
|
||
| 已有能力 | 复用方式 |
|
||
|----------|----------|
|
||
| MQTT Broker + topic 规范 | 网关 App 直接按 `iot/devices/{id}/data` 格式上报 |
|
||
| `device` 表 + `platform` 字段 | 新增 `zigbee`/`matter` 平台值 |
|
||
| `device_data_record` 时序存储 | 数据格式不变，直接入库 |
|
||
| 指令下发 MQTT `command` topic | 网关 App 订阅后转换为 Zigbee/Matter 指令 |
|
||
|
||
### 6.2 需新增的后端工作
|
||
|
||
| 模块 | 内容 | 工作量 |
|
||
|------|------|--------|
|
||
| A. 网关设备注册 | RK3568 中控屏作为"网关设备"注册到 `device` 表（platform=`gateway`），下挂子设备通过 `gateway_id` 关联 | 1-2 天 |
|
||
| B. Zigbee 配网管理 API | 开启/关闭 Permit Join、查询已配对子设备列表、删除子设备 | 2-3 天 |
|
||
| C. Matter 配网 API | 生成 Commissioning QR Code、接收 commissioning 回调、设备列表同步 | 3-4 天 |
|
||
| D. MQTT 数据处理补全 | 当前 `deviceDataHandler` 只有日志，补全实际写入 `device_data_record` 的逻辑 | 1-2 天 |
|
||
| E. 属性映射 | Zigbee Cluster（如开闭 0006、亮度 0008）→ 平台功能点（switch、brightness）；Matter Cluster → 功能点 | 2-3 天 |
|
||
| F. 指令下发适配 | 平台指令 → Zigbee ZCL 命令 / Matter 命令格式转换（在网关 App 侧实现，后端只需透传 JSON） | 1 天 |
|
||
| G. 设备分组/场景 | Zigbee Group 管理、本地场景表 | 2 天（可选，一期可不做） |
|
||
| **合计（后端）** | | **12-17 人天** |
|
||
|
||
### 6.3 数据库变更
|
||
|
||
```sql
|
||
-- device 表新增网关关联字段
|
||
ALTER TABLE device ADD COLUMN gateway_id BIGINT NULL COMMENT '网关设备ID' AFTER owner_id;
|
||
ALTER TABLE device ADD INDEX idx_device_gateway (gateway_id);
|
||
|
||
-- 新增 Zigbee 设备属性映射表
|
||
CREATE TABLE device_zigbee_endpoint (
|
||
id BIGINT PRIMARY KEY COMMENT '主键ID',
|
||
device_id BIGINT NOT NULL COMMENT '设备ID',
|
||
endpoint TINYINT NOT NULL COMMENT 'Zigbee Endpoint',
|
||
cluster_id INT NOT NULL COMMENT 'Cluster ID',
|
||
cluster_name VARCHAR(50) COMMENT 'Cluster名称',
|
||
attribute_id INT NOT NULL COMMENT 'Attribute ID',
|
||
attribute_name VARCHAR(50) COMMENT 'Attribute名称',
|
||
data_type VARCHAR(20) COMMENT '数据类型',
|
||
create_time DATETIME DEFAULT CURRENT_TIMESTAMP
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Zigbee设备属性映射表';
|
||
```
|
||
|
||
---
|
||
|
||
## 七、客户端（RK3568 网关代理）工作量
|
||
|
||
| 模块 | 内容 | 工作量 |
|
||
|------|------|--------|
|
||
| EZSP 串口通信 | 与 ZSU 模组 UART 通信，解析 ASH 帧 | 3-4 天 |
|
||
| Zigbee 设备管理 | Permit Join、配对回调、属性上报、指令下发 | 4-5 天 |
|
||
| Matter Controller | 集成 CHIP SDK，Commissioning、设备控制 | 4-5 天 |
|
||
| MQTT 客户端 | 连接后端 Broker，上报数据/订阅指令 | 1-2 天 |
|
||
| 协议转换层 | Zigbee ZCL ↔ 平台 JSON 格式互转 | 2-3 天 |
|
||
| **合计（客户端）** | | **14-19 人天** |
|
||
|
||
---
|
||
|
||
## 八、工作分工
|
||
|
||
| 层 | 负责方 | 工作量 | 依赖 |
|
||
|----|--------|--------|------|
|
||
| AOSP 固件定制 | 客户硬件团队 | 1-2 周 | RK3568 SDK、硬件原理图 |
|
||
| Native 协议层（C/C++） | 可外包/自研 | 2-3 周 | EmberZNet SDK、CHIP SDK |
|
||
| 系统应用（GatewayService） | 我们开发 | 2-3 周 | Native 层接口定义 |
|
||
| 中控屏 UI App | 我们开发 | 3-4 周 | GatewayService API |
|
||
| 后端 API | 我们开发 | 2-3 周 | 无依赖，可并行 |
|
||
|
||
---
|
||
|
||
## 九、分阶段实施计划
|
||
|
||
### 第一期（MVP，6-8 周）
|
||
|
||
- ZSU 烧录 EmberZNet Coordinator 固件
|
||
- RK3568 网关 App 实现 Zigbee 设备配对 + MQTT 上报
|
||
- 后端补全 MQTT 数据处理 + Zigbee 配网 API
|
||
- 支持：开关、调光、传感器三类标准 Zigbee 设备
|
||
|
||
### 第二期（3-4 周）
|
||
|
||
- RK3568 集成 Matter Controller
|
||
- 后端 Matter 配网 API
|
||
- 支持 WiFi Matter 设备
|
||
|
||
### 第三期（可选）
|
||
|
||
- Thread Border Router（需第二颗 ZSU 或双协议栈方案）
|
||
- 本地场景引擎
|
||
- 设备分组
|
||
|
||
---
|
||
|
||
## 十、总工作量
|
||
|
||
| 模块 | 工作量 |
|
||
|------|--------|
|
||
| 后端 | 12-17 人天 |
|
||
| 客户端（RK3568 网关代理） | 14-19 人天 |
|
||
| AOSP 固件定制（客户方） | 1-2 周 |
|
||
| **合计（我方）** | **26-36 人天** |
|
||
|
||
---
|
||
|
||
## 十一、结论
|
||
|
||
ZSU 空片方案完全可行且推荐。核心优势：
|
||
|
||
1. **绕过涂鸦生态锁定**，Zigbee 链路完全自主
|
||
2. EFR32MG21 + EmberZNet 是业界成熟方案，子设备兼容性好
|
||
3. 我们后端已有 MQTT 基础设施，主要工作量在网关 App 和配网 API
|
||
4. Matter 走 RK3568 原生 Android，不依赖 ZSU
|
||
5. 网关代理以系统级服务集成到 AOSP 固件，开机自启、不可卸载、稳定可靠
|
||
|
||
### 前置确认事项
|
||
|
||
客户需提供：
|
||
|
||
- RK3568 AOSP SDK 及编译环境
|
||
- 硬件原理图（确认 ZSU 模组 UART 接口）
|
||
- 是否有 Android 嵌入式开发能力（若无，可退而求其次用普通 App + root 权限方案）
|