架构设计

fastbee大约 8 分钟

架构设计

本文档描述 FastBee-Arduino 的整体架构、模块职责、数据流和关键设计模式,帮助开发者深入理解系统设计。

运行界面视角

架构中的网络、外设、规则、协议和系统管理模块最终都会落到 Web 控制台。阅读架构图时，可以用下面几张实机截图对应运行时边界：仪表盘负责系统状态总览，网络页负责联网配置，外设页负责硬件抽象，外设执行页负责规则编排。

FastBee-Arduino 运行时架构图

服务边界图用于把架构中的职责落到代码模块：新增能力前先判断它属于外设、规则、网络、协议、系统服务还是安全边界，再进入对应章节和目录。

整体架构

FastBee-Arduino 采用分层架构设计,从硬件到应用层清晰划分职责,降低模块耦合度。

系统定位与版本稳定性基线

FastBee-Arduino 定位为 嵌入式物联网软件系统，面向设备接入、数据采集、协议上报、远程控制和现场维护。Lite、Standard、Full 三个版本允许功能裁剪，但基础稳定能力必须保持一致：系统可以启动、配置可以恢复、网络异常可以重连、平台连接异常可以恢复、内存不足可以降级保护、故障可以通过日志或错误码定位。完整版本功能边界和资源上限见版本对比指南。

长期运行设计原则

功能可裁剪，恢复链路不可裁剪：启动、配网、网络重连、配置保护、健康监控和日志必须在三个版本中保留。
Full 版本承载更多能力，必须依赖 PSRAM、内存门控和接口降级策略；运行时如果 psramTotal 为 0，应视为硬件或构建档位异常。
Lite 版本优先保证低资源稳定运行，不默认开启 OTA、文件管理、用户角色、RuleScript 等重功能。
Standard 版本用于常规业务部署，应覆盖 Modbus、命令脚本、以太网/4G 等现场常用能力，但仍需按实际 Flash/RAM 预算裁剪。
所有版本发布前都必须通过构建、冒烟和长稳验证；Full 版本还必须覆盖 OTA、远程配置、日志/文件和权限相关接口。

稳定性基线

异常恢复的设计目标是让设备在无人值守场景下自动回到可工作状态。网络、MQTT、配置文件、外设初始化和 OTA 都应在失败时给出明确错误码，并避免无限重启或高频 Flash 写入。

模块职责

核心框架层 Core Framework

核心框架包含 FastBeeFramework（主框架）、PeriphExecManager（规则引擎）和 CommandBus（命令总线），详细类和方法说明见核心框架。

FastBeeFramework：单例模式，系统初始化与生命周期管理，按序加载配置→外设→网络→协议→规则→健康监控
PeriphExecManager：4 种触发器（平台/定时/事件/轮询）+ 27 种动作，异步 Worker 池调度，配置持久化到 LittleFS
CommandBus：命令脚本解析与执行，支持 PERIPH/DELAY/LOOP 三类命令

外设管理层 Peripheral Drivers

外设管理由 PeripheralManager 统一负责，包含引脚分配、冲突检测、硬件初始化和驱动注册。支持 25+ 种外设类型。传感器驱动、显示屏驱动和数码管驱动的详细接口说明见核心框架。

PeripheralManager：外设 CRUD、引脚分配与冲突检测、硬件初始化、ISR 中断队列分发
SensorDriver：DHT/DS18B20/HC-SR04/SHT31/AHT20/BH1750/BMP280/MPU6050 等
LCDManager：SSD1306/SH1106 OLED
SevenSegmentDriver：TM1637 数码管

网络通信层 Network

网络层通过 NetworkManager 统一管理多种联网方式，上层协议无需感知底层网络类型。WiFiManager 负责 AP/STA 双模、断线重连和 mDNS；WebConfigManager 基于 ESPAsyncWebServer 提供 RESTful API 和静态资源服务。

NetworkManager：WiFi/以太网(W5500)/4G(EC801E)/LoRa(E22) 适配，通过 Arduino Client 抽象层统一接口
WiFiManager：AP 配网(FastBee-XXXX)、STA 连接、双模并发、指数退避重连、mDNS
WebConfigManager：异步 HTTP 服务器，路由覆盖静态资源、设备/外设/执行/协议/系统 API

协议处理层 Protocols

协议层由 ProtocolManager 统一调度，支持 MQTT 和 Modbus RTU 两种主要协议。详细主题格式和寄存器操作见核心框架和协议文档。

ProtocolManager：协议配置加载、实例初始化、数据上报调度、命令下发处理
MQTTClient：TLS/非TLS 连接、自定义主题前缀、遗嘱消息(LWT)、自动重连与指数退避
ModbusHandler：UART 多端口、自动从站扫描、寄存器批量轮询、功能码 01-06/15/16

系统管理层 System

系统管理涵盖配置存储、健康监控、日志和认证。详细 API 和阈值说明见核心框架。

ConfigStorage：JSON 配置读写、LittleFS 持久化、原子写入保护、配置导入导出
HealthMonitor：5 秒周期检测堆内存/WiFi/MQTT 状态，分级告警（<20KB WARN / <10KB 关闭 SSE / <5KB 降级日志），WDT 10 秒超时
LoggerSystem：ERROR/WARN/INFO/DEBUG 四级日志
AuthManager：Session/Cookie 认证，3 级角色权限 (admin/operator/viewer)，密码加密

数据流

传感器数据采集流程

定时触发器 → PeriphExecManager
         → 读取传感器 (SensorDriver)
         → 写入本地缓存 (sensor_cache)
         → 产生数据事件 (ds:<id>_<field>)
         → 触发联动规则 (EventTrigger)
         → 执行动作 (GPIO/显示/上报)
         → MQTT上报 (MQTTClient)

示例: 温度超限报警

定时触发器每 10 秒触发
PeriphExecManager 调用 DHT11 读取温度
温度值写入本地缓存,产生事件 ds:dht_01_temperature
事件触发器评估条件 (温度 > 30°C)
条件满足,执行动作: 拉高继电器引脚
执行结果通过 MQTT 上报到云平台

Web配置流程

浏览器请求 → WebConfigManager (ESPAsyncWebServer)
         → 路由匹配 (RouteHandler)
         → 权限验证 (AuthManager)
         → ConfigStorage 读写 LittleFS
         → 返回 JSON 响应
         → 前端渲染页面

示例: 添加外设

前端 POST /api/peripherals
PeripheralRouteHandler 接收请求
AuthManager 验证权限
PeripheralManager 验证引脚、初始化硬件
ConfigStorage 写入 peripherals.json
返回 200 OK,前端刷新列表

MQTT消息处理流程

MQTT消息到达 → MQTTClient.onMessage()
            → ProtocolManager 解析主题
            → PeriphExecManager 平台触发器
            → 条件评估 (evaluateCondition)
            → 执行动作 (dispatchAction)
            → 响应上报 (publish)

示例: 平台远程控制

云平台发布消息到 fastbee/device01/command
MQTTClient 接收消息,回调 ProtocolManager
PeriphExecManager 匹配平台触发器
评估条件 (如数据值匹配)
执行动作 (如打开继电器)
执行结果上报到 fastbee/device01/event

关键设计模式

单例模式 Singleton

应用场景: 全局唯一管理器

实现:

class FastBeeFramework {
public:
    static FastBeeFramework* getInstance() {
        static FastBeeFramework instance;
        return &instance;
    }
private:
    FastBeeFramework() {}
};

使用实例:

FastBeeFramework::getInstance()
PeriphExecManager::getInstance()
ConfigStorage::getInstance()
HealthMonitor::getInstance()

观察者模式 Observer

应用场景: 事件监听和分发

实现:

传感器数据事件监听 (sensor_cache)
MQTT消息订阅分发 (topic filter)
系统事件广播 (WiFi连接/MQTT状态)

数据事件格式:

ds:<外设ID>_<字段名>
示例: ds:dht_01_temperature
      ds:bh1750_01_illuminance

策略模式 Strategy

应用场景: 多实现可替换

实现:

多联网方式适配 (WiFi/Ethernet/4G/LoRa)
- 统一接口: NetworkAdapter
- 不同实现: WiFiManager, EthernetAdapter, CellularAdapter, LoRaAdapter
多传感器驱动策略 (DHT/DS18B20/I2C等)
- 统一接口: SensorDriver
- 不同实现: 各传感器专用驱动
多协议处理策略 (MQTT/Modbus/TCP/HTTP)
- 统一接口: ProtocolHandler
- 不同实现: MQTTClient, ModbusHandler, TCPHandler, HTTPClientWrapper

命令模式 Command

应用场景: 动作封装和执行

实现:

PeriphExec 动作执行 (27种动作类型)
CommandBus 命令分发 (脚本引擎)
RuleScript 脚本执行 (full版)

动作执行流程:

解析 actionType → 匹配执行策略 → 调用对应方法 → 返回执行结果

内存管理策略

内存门控 MEMGUARD

目标: 防止内存耗尽导致系统崩溃

策略:

定期检测堆内存 (每5秒)
根据阈值降级服务:
- < 20KB: WARN 日志
- < 10KB: 关闭 SSE 连接 (释放 ~8KB)
- < 5KB: 降低日志级别,减少字符串分配
不自动恢复 (避免频繁抖动),需外部干预

零拷贝优化

目标: 减少内存拷贝和临时对象

实现:

Web响应流式输出 (直接写客户端,不缓冲)
JSON配置按需加载 (不缓存全量)
Gzip压缩产物直接使用 (不解压)
避免 std::make_shared<File> (高碎片率下失败)

静态池化

目标: 避免运行时动态分配,降低堆碎片化

实现:

Worker池预创建 (3个异步任务)
任务栈固定大小 (4KB/8KB)
启动时分配,运行期不扩容
最小堆内存门控 (30KB 才允许异步任务)

编译期优化

内存释放:

禁用蓝牙控制器 (~30KB): esp_bt_controller_mem_release()
关闭未使用功能 (OTA/日志/多用户)

栈优化:

放大 loopTask 栈到 24KB (默认 8KB)
防止深度调用链栈溢出