FastBee-Arduino 设备端封面图 ## 页面导读 - **页面内容**: FastBee-Arduino 设备端文档入口：能力边界、推荐路径、发布环境与芯片选型。 - **适用场景**: 适合使用 ESP32 系列开发板的用户，覆盖从零代码固件烧录到外设与规则配置的全过程。 - **前置条件**: 准备一块受支持的 ESP32 开发板、USB 数据线和 Chrome 或 Edge 浏览器。 ## 案例展示 FastBee-Arduino 在不同芯片和硬件平台上的实际应用案例已统一收录到 [案例展示](https://www.fastbee.cn/doc/device/v2/case-showcase.md) 页面，更多示例请查看 [示例教程](https://www.fastbee.cn/doc/device/v2/examples.md) 目录。 ## 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](https://gitee.com/beecue/fastbee-arduino) ### 推荐路径 ```mermaid flowchart LR A[选择匹配的合并固件] --> B[在线或串口烧录] B --> C[连接设备 AP] C --> D[登录并配置 WiFi] D --> E[启用功能/添加外设] E --> F[配置 MQTT、Modbus 和规则] ``` | 目标 | 文档 | | --- | --- | | 第一次使用 | [快速开始](https://www.fastbee.cn/doc/device/v2/getting-started/quick-start.md) | | 查看落地案例 | [案例展示](https://www.fastbee.cn/doc/device/v2/case-showcase.md) | | 了解能力与硬件差异 | [项目概览](https://www.fastbee.cn/doc/device/v2/getting-started/overview.md)、[硬件与环境](https://www.fastbee.cn/doc/device/v2/getting-started/edition-comparison.md) | | 烧录与升级 | [在线烧录](https://www.fastbee.cn/doc/esp32-flasher.html)、[源码部署](https://www.fastbee.cn/doc/device/v2/deploy/hardware-config.md)、[OTA 升级](https://www.fastbee.cn/doc/device/v2/deploy/ota-upgrade.md) | | 日常操作 | [用户操作手册](https://www.fastbee.cn/doc/device/v2/getting-started/user-manual.md) | | 外设 | [外设参考](https://www.fastbee.cn/doc/device/v2/peripherals.md) | | 自动化 | [外设执行](https://www.fastbee.cn/doc/device/v2/periph-exec.md) | | 触摸屏与可视化 | [设备屏幕](https://www.fastbee.cn/doc/device/v2/system/screen-panel.md)、[天气与远程资源](https://www.fastbee.cn/doc/device/v2/protocols/remote-resources.md) | | 协议 | [通信协议](https://www.fastbee.cn/doc/device/v2/protocols.md) | | 系统维护 | [系统管理](https://www.fastbee.cn/doc/device/v2/system.md) | | 系统改进与验收边界 | [候选与验收状态](https://www.fastbee.cn/doc/device/v2/deploy/system-improvement-status.md) | | 集成开发 | [API 接口](https://www.fastbee.cn/doc/device/v2/dev/api-reference.md)、[架构设计](https://www.fastbee.cn/doc/device/v2/dev/architecture.md) | ### 发布环境 发布环境由源码 `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 和设备接口为准。详见[设备屏幕](https://www.fastbee.cn/doc/device/v2/system/screen-panel.md)。 ### 统一架构说明 系统只维护一个固件产品，发布环境共享公共编译配置 `unified_flags`（不是产品版本）；OTA、以太网、4G、红外等硬件相关能力仍由具体环境覆盖或裁剪。运行时由以下条件共同决定功能是否生效： ```text compiled AND userEnabled AND budgetPassed AND NOT runtimeDisabled ``` * `compiled`：功能已编译进当前环境。 * `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 配网暂不属于发布能力。 ### 功能文档 | 分类 | 入口 | | --- | --- | | 网络 | [网络配置](https://www.fastbee.cn/doc/device/v2/system/network-config.md)（WiFi AP/STA、自定义本地域名、静态 IP、W5500、EC801E） | | 外设 | [外设配置指南](https://www.fastbee.cn/doc/device/v2/peripherals/peripheral-configuration-guide.md)、[支持类型](https://www.fastbee.cn/doc/device/v2/getting-started/supported-sensors-and-modules.md) | | 自动化 | [规则配置](https://www.fastbee.cn/doc/device/v2/periph-exec/periph-exec-configuration-guide.md)、[触发器与动作](https://www.fastbee.cn/doc/device/v2/periph-exec/periph-exec-flow.md) | | MQTT/Modbus | [MQTT](https://www.fastbee.cn/doc/device/v2/protocols/mqtt-config.md)、[Modbus RTU](https://www.fastbee.cn/doc/device/v2/protocols/modbus-rtu.md) | | 系统 | [功能开关](https://www.fastbee.cn/doc/device/v2/system/feature-config.md)、[设备配置](https://www.fastbee.cn/doc/device/v2/system/device-config.md)、[健康监控](https://www.fastbee.cn/doc/device/v2/system/health-monitor.md)、[日志](https://www.fastbee.cn/doc/device/v2/system/device-log.md) | | 开发 | [API](https://www.fastbee.cn/doc/device/v2/dev/api-reference.md)、[构建配置](https://www.fastbee.cn/doc/device/v2/dev/build-config.md)、[分区布局](https://www.fastbee.cn/doc/device/v2/dev/partition-layout.md) | | 示例 | [示例索引](https://www.fastbee.cn/doc/device/v2/examples.md) | ### 验证与测试入口 源码仓库提供静态、构建、设备 API 和 Web 页面测试脚本： ```powershell # 静态检查、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:// -Profile unified -RequireNetworkConnected powershell -ExecutionPolicy Bypass -File scripts\device-web-smoke.ps1 -BaseUrl http:// -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 -BrowserTests:$false ``` 页面巡检覆盖 16 个公开 Web 资源并记录状态码、耗时和响应字节数。4MB 无 PSRAM 设备出现 `503` 时先查看 `/api/system/metrics`，不要用无间隔并发请求代替真实浏览器访问。主机和产物门禁不证明设备实际烧录的 LittleFS/配置内容，发布时还需检查配置迁移和重启恢复。 ### 文档约定 * 除特别说明外，API 需要登录后由设备下发的 HttpOnly `sessionId` Cookie（Cookie 名称可在安全配置中自定义，设备同时兼容 `session`）；`GET /api/health` 和 `GET /api/system/capabilities` 免认证。 * 页面名称以当前 Web 控制台为准。“设备配置”等基础菜单始终显示；设备大屏、规则脚本、设备日志和用户管理等可选菜单只在对应功能为 `active` 时显示。 * 示例中的引脚只适用于示例硬件，接线前必须核对开发板原理图并避开 Flash、PSRAM、USB/JTAG 等保留引脚。 * 配置备份优先使用 Web 的导入/导出功能；不要把真实密码、令牌或生产网络配置提交到公共仓库。