设备端介绍
页面导读
案例展示
FastBee-Arduino 在不同芯片和硬件平台上的实际应用案例已统一收录到 案例展示 页面，更多示例请查看 示例教程 目录。
FastBee-Arduino 设备端文档
FastBee-Arduino 是一套运行在 ESP32 系列上的零代码 Web 固件。烧录后，用户通过浏览器完成配网、外设接入、MQTT/Modbus 配置和本地自动化，无需修改固件代码。
当前发布固件的设备通信协议为 MQTT/MQTTS 和 Modbus RTU 主站，另提供天气来源的受限 HTTP(S) GET。设备 Web 管理、HTTP NTP、HTTP OTA 和天气读取不等同于通用 HTTP 上报协议；原始 TCP、Modbus TCP、CoAP 和任意 HTTP 动作不属于当前发布能力。
源码仓库：gitee.com/beecue/fastbee-arduino
推荐路径
| 目标 | 文档 |
|---|---|
| 第一次使用 | 快速开始 |
| 查看落地案例 | 案例展示 |
| 了解能力与硬件差异 | 项目概览、硬件与环境 |
| 烧录与升级 | 在线烧录、源码部署、OTA 升级 |
| 日常操作 | 用户操作手册 |
| 外设 | 外设参考 |
| 自动化 | 外设执行 |
| 触摸屏与可视化 | 设备屏幕、天气与远程资源 |
| 协议 | 通信协议 |
| 系统维护 | 系统管理 |
| 系统改进与验收边界 | 候选与验收状态 |
| 集成开发 | API 接口、架构设计 |
发布环境
发布环境由源码 platformio.ini 和 fim/manifest.json 同时定义：
| 环境 | 芯片 | Flash | PSRAM | OTA |
|---|---|---|---|---|
esp32-F4R0 | ESP32 | 4MB | 无 | 否 |
esp32-F8R0 | ESP32 | 8MB | 无 | 是 |
esp32-F8R8 | ESP32 | 8MB | 8MB | 是 |
esp32c3-F4R0 | ESP32-C3 | 4MB | 无 | 否 |
esp32c6-F4R0 | ESP32-C6 | 4MB | 无 | 否 |
esp32c6-F8R0 | ESP32-C6 | 8MB | 无 | 是 |
esp32s3-F8R0 | ESP32-S3 | 8MB | 无 | 是 |
esp32s3-F8R8 | ESP32-S3 | 8MB | 8MB | 是 |
esp32s3-F16R8 | ESP32-S3 | 16MB | 8MB | 是 |
标准发布矩阵共 9 个环境，命名中的 F 表示 Flash 容量、R 表示 PSRAM 容量；R0 表示无 PSRAM，R8 表示 8MB PSRAM。标准清单不再使用 F8R4，4MB PSRAM 仅作为厂商定制配置。4MB 环境是单 app 分区，不能 OTA；8MB/16MB 环境有 app0/app1 A/B 分区。
设备屏幕仅面向 ESP32-S3，仍须匹配具体控制器和接线，不能按芯片名称自动判定兼容。后端包含 SPI ST7789 / ILI9341（最大控制器窗口 240×320），并新增 ESP32-S3 ST7701 RGB 480×480 测试后端及可选 I2C GT911。代码能力与实体兼容必须分开判断：微雪 Rev4 已完成驱动接入，用户曾确认短时显示稳定，但历史黑屏、漂移和卷边记录仍保留，最新组合负载的物理显示验收尚未完成；同分辨率其他板也须核对初始化序列、引脚和控制电路。esp32-F4R0、esp32c3-F4R0 均裁剪面板/UI/远程资源；经典 ESP32 保留最近记录，C3 为应用槽容量同时裁剪最近记录，但保留实时采集、Modbus、外设执行和普通 Web。C6 的最终能力以容量合格的发布 BIN 和设备接口为准。详见设备屏幕。
统一架构说明
系统只维护一个固件产品，发布环境共享公共编译配置 unified_flags（不是产品版本）；OTA、以太网、4G、红外等硬件相关能力仍由具体环境覆盖或裁剪。运行时由以下条件共同决定功能是否生效：
compiled AND userEnabled AND budgetPassed AND NOT runtimeDisabledcompiled：功能已编译进当前环境。userEnabled：用户在“功能配置”中开启，状态保存于/config/features.json。budgetPassed：启动时内存预算通过；不足时自动跳过初始化，并在/api/system/status中显示为no-memory。runtimeDisabled：运行期保护机制临时停用功能；需要网络或父功能的模块还必须等待网络就绪并满足依赖。
MQTTS 依赖 MQTT，命令脚本依赖规则脚本，GB2312 字库依赖 LCD。esp32-F4R0、esp32c3-F4R0、esp32c6-F4R0 和 esp32c6-F8R0 不编译以太网与 4G；其他环境仍需对应硬件并在运行时启用。BLE 配网暂不属于发布能力。
功能文档
| 分类 | 入口 |
|---|---|
| 网络 | 网络配置（WiFi AP/STA、自定义本地域名、静态 IP、W5500、EC801E） |
| 外设 | 外设配置指南、支持类型 |
| 自动化 | 规则配置、触发器与动作 |
| MQTT/Modbus | MQTT、Modbus RTU |
| 系统 | 功能开关、设备配置、健康监控、日志 |
| 开发 | API、构建配置、分区布局 |
| 示例 | 示例索引 |
验证与测试入口
源码仓库提供静态、构建、设备 API 和 Web 页面测试脚本：
# 静态检查、native、9 个环境构建和固件产物校验
powershell -ExecutionPolicy Bypass -Command ".\scripts\test-all.ps1 -Checks static,native,build,artifacts"
# 设备 API 冒烟 + 16 个公开页面（保留间隔，适合 4MB 设备）
powershell -ExecutionPolicy Bypass -File scripts\smoke-test-device.ps1 -BaseUrl http://<device-ip> -Profile unified -RequireNetworkConnected
powershell -ExecutionPolicy Bypass -File scripts\device-web-smoke.ps1 -BaseUrl http://<device-ip> -Rounds 2 -DelayMs 1000 -TimeoutSec 15 -MaxElapsedMs 5000 -ReportPath test\reports\web-smoke.csv
# 五设备测试台：复制示例并替换实验室 IP、串口和可选本地域名
powershell -ExecutionPolicy Bypass -File scripts\run-device-fleet-tests.ps1 -DeviceConfig <local-fleet-config.json> -BrowserTests:$false页面巡检覆盖 16 个公开 Web 资源并记录状态码、耗时和响应字节数。4MB 无 PSRAM 设备出现 503 时先查看 /api/system/metrics，不要用无间隔并发请求代替真实浏览器访问。主机和产物门禁不证明设备实际烧录的 LittleFS/配置内容，发布时还需检查配置迁移和重启恢复。
文档约定
- 除特别说明外，API 需要登录后由设备下发的 HttpOnly
sessionIdCookie（Cookie 名称可在安全配置中自定义，设备同时兼容session）；GET /api/health和GET /api/system/capabilities免认证。 - 页面名称以当前 Web 控制台为准。“设备配置”等基础菜单始终显示；设备大屏、规则脚本、设备日志和用户管理等可选菜单只在对应功能为
active时显示。 - 示例中的引脚只适用于示例硬件，接线前必须核对开发板原理图并避开 Flash、PSRAM、USB/JTAG 等保留引脚。
- 配置备份优先使用 Web 的导入/导出功能；不要把真实密码、令牌或生产网络配置提交到公共仓库。