Skip to main content

User Manual

fastbeeAbout 17 min

User Manual

Synchronized Device Documentation

This page corresponds to the synchronized Chinese source. Commands, JSON examples, API paths, field names, and screenshots are kept aligned with the Chinese device-side source documentation.

What This Page Covers

  • User Manual context and expected reader workflow.
  • Configuration, verification, and release-readiness details.
  • Source-aligned implementation notes, screenshots, and troubleshooting references.

Source Reference

The detailed operational source is preserved below so implementation details stay exact while the English navigation, titles, and reading path remain available.

用户操作手册

本文面向实际接线和 Web 配置使用，覆盖从首次启动到外设配置、外设执行、传感器联动、导入导出和排错的完整流程。

文档索引

发布稳定性入口

发布、部署和长期运行验证请优先阅读：稳定性与发布检查清单。

面向轻量版、标准版和全功能版长期稳定运行的关键材料：

🚀 快速导航

我想...

目标阅读文档预计时间
了解项目是什么项目概述5分钟
快速上手使用快速开始15分钟
部署和验证固件部署与版本验证指南10分钟
完整测试各版本测试与版本验证指南15分钟
了解目录和文件项目目录与文件说明10分钟
选择固件版本版本对比指南5分钟
选择支持的模块/传感器支持清单5分钟
配置传感器/外设示例文档10分钟/个
创建自动化规则外设执行配置20分钟
理解系统架构架构设计30分钟
参与开发贡献开发指南40分钟
排查问题用户手册按需查阅

📖 核心文档（必读）

📘 入门系列

文档说明适合人群
项目概述项目背景、目标、特性、技术栈、版本对比所有人
快速开始5步完成首次配置，烧录到联动规则新手用户
部署与版本验证一键烧录、冒烟测试、发布产物和长期稳定建议运维/开发者
测试与版本验证静态检查、native、全版本编译、设备 smoke/soak 测试矩阵开发者/测试人员
项目目录与文件说明顶层目录、源码模块、脚本、测试和生成产物说明开发者/维护者
用户手册完整操作手册、高级功能、排错指南所有用户

📗 进阶系列

文档说明适合人群
架构设计整体架构图、模块职责、数据流、设计模式进阶用户/开发者
核心框架FastBeeFramework、规则引擎、外设管理详解开发者
开发指南环境搭建、编码规范、测试流程、扩展开发贡献者

📚 文档分类导航

1️⃣ 快速入门（7个）

适合第一次使用 FastBee 的用户，按顺序阅读效果最佳

序号文档说明必读
1项目概述项目背景、目标、特性、技术栈⭐
2快速开始5步完成首次配置⭐
3部署与版本验证一键烧录、版本发布、设备冒烟测试⭐
4用户手册完整操作手册、排错指南⭐
5架构设计系统架构和模块关系推荐
6核心框架主要组件和关键类开发者
7开发指南环境搭建和贡献规范开发者

2️⃣ 示例文档（50个）- examples/

LED与显示（8个）
序号文档说明
01LED首次使用LED基础配置
02LED闪烁LED闪烁控制
03流水灯流水灯效果
03b流水灯-脚本脚本实现流水灯
11PWM呼吸灯PWM调光
14RGB灯带NeoPixel控制
15数码管显示TM1637数码管
23OLED显示OLED屏幕
电机控制（3个）
序号文档说明
07直流电机DC电机控制
08步进电机步进电机控制
22舵机SG90舵机角度控制
传感器（25个）

详见 示例文档完整列表

通信与控制（7个）

详见 示例文档完整列表

Modbus应用（5个）

详见 示例文档完整列表

3️⃣ 示例场景（4个）- examples/

文档说明
OLED显示温度温度传感器+OLED
数码管显示温度温度传感器+数码管
Modbus控制设备Modbus远程控制
Modbus传感器设备Modbus数据采集

4️⃣ 外设执行 - periph-exec/

触发器（4个）- periph-exec/
文档说明
平台触发MQTT平台指令触发
定时触发时间间隔触发
事件触发系统事件触发
轮询触发条件轮询触发
动作类型（8个）- periph-exec/
文档说明
GPIO动作高/低电平/闪烁
PWM动作PWM控制/呼吸灯
传感器读取数据采集
显示动作OLED/数码管显示
Modbus动作Modbus读写（标准版/全功能版）
脚本动作命令脚本（标准版/全功能版）
事件控制事件触发/规则控制
系统动作重启/OTA/NTP
执行场景（6个）- periph-exec/
文档说明
温湿度报警温控系统
烟雾报警烟雾检测报警
光控灯光照自动开关灯
按键控制按键多功能
Modbus监控Modbus数据采集
超声波报警距离过近报警

5️⃣ 外设参考手册 - peripherals/

GPIO与PWM（4个）
文档类型说明
GPIO输出type:12LED/继电器/蜂鸣器
GPIO输入type:11/13/14按键/传感器数字输入
PWM输出type:17LED调光/电机调速
ADC输入type:15/26模拟信号采集
电机控制（2个）
文档类型说明
舵机type:41SG90/MG996R角度控制
步进电机type:4228BYJ-48精确定位
显示设备（3个）
文档类型说明
OLED显示type:36SSD1306/SH1106
TM1637数码管type:474位7段数码管
LCD1602type:36字符屏（占位）
温湿度传感器（4个）
文档类型说明
DHT11/DHT22type:38单总线温湿度
DS18B20type:38OneWire温度
AHT20type:38I2C温湿度
SHT31type:38I2C高精度温湿度
环境传感器（4个）
文档类型说明
超声波type:38HC-SR04测距
BMP280type:38气压/温度/海拔
MPU6050type:38六轴陀螺仪
BH1750type:38光照强度
通信设备（3个）
文档类型说明
Modbus设备type:51RS485从站控制（标准版/全功能版）
红外遥控type:38NEC/RC5解码
RFID读卡器type:38MFRC522射频卡
其他外设（3个）
文档类型说明
NeoPixeltype:45WS2812B灯带
旋转编码器type:43AB相计数
SD卡type:37数据存储（占位）

6️⃣ 完整配置指南

文档说明链接
外设配置指南所有外设类型详解(610行)peripherals/peripheral-configuration-guide.md
外设执行指南触发器与动作详解(694行)periph-exec/periph-exec-configuration-guide.md
脚本使用指南命令脚本完整说明，Lite 默认不可用periph-exec/script-guide.md
Modbus使用指南Modbus协议详解，需标准版/全功能版protocols/modbus_usage_guide.md
OLED使用指南OLED显示详解(430行)peripherals/oled_usage_guide.md
配置导入导出配置备份和迁移system/device-config.md
外设执行流程底层架构和任务调度(1457行)periph-exec/periph_exec_flow.md

7️⃣ 系统与协议 - system/

系统管理（12个）
分类文档数量说明
设备管理3个仪表台、设备配置、日志
网络配置2个WiFi、以太网/4G/LoRa、固件版本与版本差异
用户权限2个用户管理、角色管理
文件管理1个LittleFS操作、配置导入导出
外设管理2个外设配置、外设执行
其他2个规则脚本、固件版本
协议配置（3个）- protocols/
文档说明
MQTT配置MQTT服务器连接、主题格式、认证方式
Modbus RTU串口配置、从站扫描、寄存器映射
协议概述协议概述和多网络传输支持

🎯 文档使用路径

新手用户路径

项目概述 → 快速开始 → 示例文档 → 外设配置指南

进阶用户路径

架构设计 → 核心框架 → 外设执行指南 → 传感器完整指南

开发者路径

开发指南 → 架构设计 → 核心框架 → 外设执行流程 → 源码

排错路径

用户手册(排错章节) → 设备日志 → 相关示例文档 → 串口监视器

📊 文档统计

类别数量说明
核心文档6个必读文档
示例教程50个实际应用示例
外设手册25个外设类型详解
执行文档18个触发器/动作/场景
系统文档12个功能模块说明
协议文档3个MQTT/Modbus/概述
场景文档4个完整应用场景
总计116个完整文档体系

🔗 相关链接

1. 固件版本选择

本项目基于 Arduino-ESP32 3.x（ESP-IDF 5.1+）构建，支持 ESP32 全系列芯片，分为三个版本层级：

固件环境版本层级适用芯片主要能力
esp32c3精简版 (Lite)ESP32-C3Web 管理、WiFi/MQTT、mDNS、GPIO、DHT、DS18B20、OLED、TM1637、配置导入/导出
esp32c6精简版 (Lite)ESP32-C6同上，支持 WiFi 6
esp32标准版 (Standard)ESP32精简版基础 + 以太网 W5500 + 4G EC801E + Modbus RTU 主站 + I2C 传感器 + RFID + 红外 + 命令脚本
esp32s3标准版 (Standard)ESP32-S3同上，资源余量更好
esp32s3-full全功能版 (Full)ESP32-S3标准版基础 + LoRa + BLE + OTA + 多用户 + 文件/日志管理 + RuleScript + TCP/HTTP/CoAP + 多语言

选择建议：

  • 低成本批量部署：esp32c3（¥9-12）或 esp32c6（WiFi 6，¥12-15）
  • 需要以太网、4G 或 Modbus：esp32 或 esp32s3
  • 需要 OTA、多用户、文件/日志、RuleScript、多语言或 LoRa：esp32s3-full
  • 详细对比见 版本对比指南
固件版本选型决策图
固件版本选型决策图

2. 快速开始

  1. 使用部署脚本烧录匹配的 LittleFS 文件系统和固件。
  2. 运行设备接口冒烟测试。
  3. 首次启动后连接设备 AP，进入 Web 管理页面。
  4. 在“网络设置”配置 WiFi。
  5. 在“外设配置”添加或导入硬件外设，先保持 enabled: false，确认引脚后再启用。
  6. 在“外设执行”创建采集、联动或控制规则。
  7. 在“设备配置 / 高级配置”导出配置备份。

常用部署命令：

## ESP32 标准版
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32 -Port COM6

## ESP32-S3 标准版
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3 -Port COM6

## ESP32-S3 全功能版
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-full -Port COM6

烧录后检查：

powershell -ExecutionPolicy Bypass -File scripts\smoke-test-device.ps1 -BaseUrl http://192.168.4.1 -Profile standard

设备已连入局域网时，将 BaseUrl 替换为实际 IP；全功能版使用 -Profile full。

部署完成后，浏览器进入 Web 控制台应先看到仪表盘数据。若页面可访问但状态为空，通常是设备仍在启动或会话已过期，刷新并重新登录即可继续检查。

部署后仪表盘检查
部署后仪表盘检查

3. 网络与 MQTT 平台对接

建议先确认“网络在线”，再配置 MQTT。MQTT 会使用当前活动网络传输：WiFi 场景走 WiFiClient，标准版/全功能版在以太网或 4G 在线时走对应适配器。

3.1 联网方式选择

联网方式精简版标准版全功能版操作要点
WiFi STA/AP✅✅✅首次进入 AP，配置路由器 SSID/密码后切换 STA
mDNS✅✅✅网络正常后可尝试 http://fastbee.local
以太网 W5500❌✅✅检查 SPI 引脚、供电和网线，保存后重启
4G EC801E❌✅✅检查 UART 引脚、APN、SIM 卡、天线和信号
LoRa 透传❌❌✅适合网关透传场景，需确认串口和对端在线

3.2 MQTT 配置顺序

  1. 在“网络配置”页面保存并确认联网方式已连接。
  2. 在“通信协议 / MQTT”填写服务器地址、端口、客户端 ID、用户名和密码。
  3. 按平台要求配置发布/订阅主题。FastBee 平台或自建平台的主题和消息格式以平台产品定义为准。
  4. 使用页面上的 MQTT 连接测试，确认返回 connected。
  5. 创建外设执行规则时，平台触发使用 MQTT 下发，采集和执行结果通过 MQTT 上报。

更多主题和消息格式说明见 MQTT 配置 和 协议概览。

网络配置页面
网络配置页面
MQTT 配置页面
MQTT 配置页面

4. 外设配置基本规则

外设配置文件位于 data/config/peripherals.json，每个外设至少包含：

{
  "id": "relay_01",
  "name": "继电器1",
  "type": 12,
  "enabled": false,
  "pinCount": 1,
  "pins": [26, 255, 255, 255, 255, 255, 255, 255],
  "params": {}
}

常用类型速查：

类型type常用模块
I2C2SHT31、AHT20、BH1750、OLED、BMP280、MPU6050
GPIO 输入11/13/14按键、PIR、震动、干簧管、数字避障
GPIO 输出12LED、继电器、蜂鸣器、激光
ADC15/26光敏、土壤湿度、烟雾、雨滴、电压、电流
SENSOR38DHT、HC-SR04、通用传感器占位
ONE_WIRE44DS18B20
NeoPixel45WS2812B
TM163747四位数码管
Modbus 设备51RS485 从站控制（标准版/全功能版）
DEVICE_EVENT60逻辑事件源

Web 页面新增外设时会按类型展开不同参数。建议先保存为禁用状态，确认引脚和供电后再启用。

外设配置列表
外设配置列表
新增外设弹窗
新增外设弹窗
外设配置数据模型
外设配置数据模型

如果外设保存成功但运行不生效，按图检查页面字段、peripherals.json、运行时驱动和规则引用是否使用同一个外设 ID。

5. 外设执行基本规则

外设执行文件位于 data/config/periph_exec.json。一个规则由触发器和动作组成：

{
  "id": "exec_temp_relay",
  "name": "温度过高打开继电器",
  "enabled": false,
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "ds:dht11_01_temperature",
      "operatorType": 2,
      "compareValue": "35"
    }
  ],
  "actions": [
    {
      "targetPeriphId": "relay_01",
      "actionType": 0,
      "actionValue": "",
      "useReceivedValue": false,
      "syncDelayMs": 0,
      "execMode": 0
    }
  ],
  "reportAfterExec": true
}

常用触发器：

triggerType名称用途
0平台触发MQTT/平台命令下发
1定时触发周期采集、定时控制
4事件触发按键、数据源阈值、系统事件
5轮询触发本地数据源条件判断；Modbus 轮询需标准版/全功能版

常用动作：

actionType名称用途
0/1GPIO 高/低电平继电器、LED、蜂鸣器
2/3闪烁/呼吸LED、蜂鸣器提示
4/5PWM/DAC调光、调速、模拟输出
10调用外设步进电机、NeoPixel、UART 等复合动作
15命令脚本多步 GPIO/PWM/延时组合（标准版/全功能版）
19传感器读取ADC、DHT、DS18B20、HC-SR04、SHT31、AHT20、BH1750 等
21触发事件向平台或本地规则发出逻辑事件
24/25/26/27显示动作TM1637、OLED 显示

外设执行页面重点核对规则是否启用、触发器来源、动作数量和目标外设。首次上线建议保持规则禁用，先通过“执行一次”观察日志和外设状态。

外设执行规则列表
外设执行规则列表
触发器时序对比
触发器时序对比
外设执行规则表单安全检查
外设执行规则表单安全检查

普通用户配置规则时可以先看这两张图：触发器时序图帮助选择平台、定时、事件或轮询；安全检查图帮助确认启用前是否具备日志、上报和回滚手段。

6. 传感器读取 actionValue

actionType: 19 使用 JSON 字符串描述读取方式。Web 表单会自动生成该字符串，也可以手动编辑。

{
  "periphId": "sht31_i2c",
  "sensorCategory": "SHT31",
  "dataField": "temperature",
  "sensorLabel": "温度",
  "unit": "℃",
  "decimalPlaces": 1,
  "driverParams": {
    "addr": "0x44",
    "sda": 21,
    "scl": 22
  }
}

常用 sensorCategory：

sensorCategory输出字段资源建议
analogvoltage、valueESP32 可用
digitalvalueESP32 可用
dht11 / dht22temperature、humidityESP32 可用
ds18b20temperatureESP32 可用
ultrasonicdistanceESP32 可用
currentcurrentESP32 可用
voltagevoltageESP32 可用
SHT31temperature、humidityESP32 可用，轻量 I2C
AHT20temperature、humidityESP32 可用，轻量 I2C
BH1750illuminanceESP32 可用，轻量 I2C
BMP280temperature、pressure、altitude标准版/全功能版
MPU6050accelX/Y/Z、temperature、gyroX/Y/Z标准版/全功能版

7. 典型场景

典型场景自动化闭环
典型场景自动化闭环

下面的场景都可以按“采集、判断、执行、上报、复核”的闭环拆解。初次配置时先跑单传感器、单规则、单动作，确认后再组合显示、告警和平台上报。

温湿度超过阈值打开继电器

  1. 配置 DHT11/DHT22/SHT31/AHT20。
  2. 创建定时采集规则，reportAfterExec 设为 true。
  3. 创建事件触发规则，eventId 使用 ds:<外设ID>_<字段>。
  4. 动作选择继电器高电平或低电平，根据模块有效电平决定。

光照低于阈值开灯

  1. 配置 BH1750 或光敏 ADC。
  2. 定时读取 illuminance 或 voltage。
  3. 事件触发 operatorType: 3，例如小于 50。
  4. 动作打开继电器或 LED。

电流过载断电

  1. 配置 ACS712 电流传感器 ADC。
  2. 读取动作高级参数填写 sensitivity、zeroOffset、vRef、adcMax。
  3. 事件触发 current > 15。
  4. 动作关闭继电器，并可追加 actionType: 21 上报 over_current 事件。

Modbus 传感器采集（标准版/全功能版）

  1. 使用 esp32、esp32s3 或 esp32s3-full 固件。
  2. 在“通信协议 / Modbus RTU”配置串口、波特率和从站地址。
  3. 添加 Modbus 子设备或寄存器映射。
  4. 在外设执行中使用轮询触发或 Modbus 动作读取数据，并通过 MQTT 上报。

8. 导入导出建议

  • 所有文档示例默认 enabled: false，导入后先检查引脚再启用。
  • 每次批量修改前导出 peripherals.json 和 periph_exec.json。
  • 从全功能版导出的配置导入 Lite/Standard 时，高级功能字段会被忽略；Lite 不支持 Modbus、脚本、LoRa、OTA 等规则。
  • I2C 模块可以共用同一组 SDA/SCL，但地址不能冲突。
  • GPIO6-GPIO11 通常连接 Flash，不建议作为外设引脚。
  • GPIO34-GPIO39 仅输入，适合 ADC/数字输入，不适合继电器输出。

全功能版可以直接在文件管理页查看和维护 LittleFS 文件，现场迁移前建议优先导出配置文件。

文件管理页面
文件管理页面

配置导入导出建议按下图形成固定流程：每次修改先备份，导入前校验 JSON，导入后用仪表盘、日志和对应功能页复核。

配置文件生命周期流程图
配置文件生命周期流程图

9. 排错

现象检查项
Web 页面能打开但外设无动作外设是否启用、引脚是否正确、继电器有效电平是否反相
传感器读数为空采集规则是否启用、periphId 是否存在、采样间隔是否太短
I2C 传感器初始化失败SDA/SCL 是否接反、地址是否正确、是否有上拉、电源是否为 3.3V
ADC 数值异常是否超过 3.3V、是否需要分压、ADC 衰减和校准参数是否正确
阈值规则不触发先确认采集规则已生成 ds:<id>_<field> 数据源，再配置事件触发
MQTT 测试失败先确认网络在线，再检查服务器、端口、ClientID、用户名/密码和主题规则
以太网/4G 菜单不可用确认固件是否为标准版或全功能版；精简版默认关闭这些能力
Modbus 页面或动作不可用精简版默认关闭 Modbus，请切换 esp32、esp32s3 或 esp32s3-full
fastbee.local 无法访问确认电脑和设备在同一局域网；必要时改用路由器分配的 IP
找不到多语言切换Lite/Standard 默认单语言，完整多语言仅 Full 保留
Last update:
Contributors: kerwincui
fastbee
Copyright © 2026 fastbee