用户操作手册

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

1. 准备工作

在开始操作前，请先完成以下准备：

选择固件环境：根据芯片与 Flash/PSRAM 规格选择出厂环境（如 esp32-F4R0、esp32s3-F8R8），功能按需开启。完整对比见硬件与环境。
烧录固件：使用部署脚本烧录匹配的 LittleFS 文件系统和固件，详见部署、烧录与测试。
首次配置：连接设备 AP → 进入 Web 管理 → 配置 WiFi → 确认网络在线 → 配置 MQTT。网络和 MQTT 配置步骤见网络配置和 MQTT 配置。
手机 App 配网：除 Web 界面外，也可通过手机 App 连接 AP 热点后调用配网 API（/api/wifi/scan、/api/wifi/connect）完成 WiFi 配置和设备参数下发。接口说明和配网流程参见网络配置 - AP 配网 API。

快速上手完整步骤见快速开始。

部署完成后，浏览器进入 Web 控制台应先看到仪表盘数据。

部署后仪表盘检查

2. 外设配置

设备运行时外设配置位于 LittleFS /config/peripherals.json；源码中的 data/config/peripherals.json 只是构建文件系统时使用的工厂模板。每个外设至少包含：

json

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

常用类型速查：

类型	type	常用模块
I2C 主总线	2	SDA/SCL 共享总线；本地 I2C 传感器使用 type 38，OLED 使用 type 36
GPIO 输入	11/13/14	按键、PIR、震动、干簧管、数字避障
GPIO 输出	12	LED、继电器、蜂鸣器、激光
ADC	15/26	光敏、土壤湿度、烟雾、雨滴、电压、电流
SENSOR	38	DHT、HC-SR04、通用传感器占位
ONE_WIRE	44	DS18B20
NeoPixel	45	WS2812B
TM1637	47	四位数码管
RF_MODULE	48	433MHz 射频模块
RADAR_SENSOR	49	RCWL-0516 雷达感应
MODBUS_DEVICE	51	RS485 Modbus 主站设备
LCD1602	52	PCF8574 I2C 字符屏（默认关闭，按需启用）
IR_RECEIVER	53	红外接收头（按环境启用；S3 F8R8 默认关闭）
DEVICE_EVENT	60	逻辑事件源

完整外设类型枚举、引脚分配原则和配置流程图详见外设配置指南。

操作建议：Web 页面新增外设时先保存为禁用状态，确认引脚和供电后再启用。如果外设保存成功但运行不生效，依次检查页面字段、peripherals.json、运行时驱动和规则引用是否使用同一个外设 ID。

新增外设弹窗

3. 外设执行

设备运行时外设执行配置位于 LittleFS /config/periph_exec.json；源码中的同名文件只是工厂模板。一个规则由触发器和动作组成：

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 来源时还需启用 Modbus

常用动作：

actionType	名称	用途
0/1	GPIO 高/低电平	继电器、LED、蜂鸣器
2/3	闪烁/呼吸	LED、蜂鸣器提示
4/5	PWM/DAC	调光、调速、模拟输出
10	调用外设	按目标后端解析命令，不是任意协议透传；目标和参数须与动作契约匹配
11	灯效控制	NeoPixel 颜色/动画预设
12	电机控制	步进电机正转/反转/停止
13/14	GPIO 反转	低电平有效继电器等
15	命令脚本	多步 GPIO/PWM/延时组合（需启用 commandScript）
16/17/18	Modbus 线圈/寄存器/轮询	Modbus 读写和采集（需启用 modbus）
19	传感器读取	ADC、DHT、DS18B20、HC-SR04、SHT31 等
21	触发事件	向平台或本地规则发出逻辑事件
22/23	启用/禁用规则	规则链式联动控制
24/25/26/27	显示动作	TM1637、LCD1602、OLED 显示
28	射频发送	433MHz RF 编码发送
29	串口发送	UART 文本数据发送

完整触发器/动作类型表、条件运算符和平台触发字段说明见外设执行指南。

操作建议：首次上线保持规则禁用，先通过"执行一次"观察日志和外设状态。启用前确认：ID 不重复、触发器来源明确、动作目标外设存在、有日志和回滚手段。

4. 传感器读取

actionType: 19 使用 JSON 字符串描述读取方式，Web 表单会自动生成：

json

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

常用 sensorCategory：dht11/dht22（温湿度）、ds18b20（温度）、ultrasonic（距离）、sht31/aht20（温湿度 I2C）、bh1750（光照 I2C）、bmp280（气压 I2C）、mpu6050（陀螺仪 I2C）。具体 driver 名称、参数和字段以传感器完整指南为准；能否运行还取决于编译开关和运行时内存预算。

完整传感器分类和寄存器级配置参数见传感器完整指南。

5. 典型场景

所有场景都按"采集 → 判断 → 执行 → 上报 → 复核"的闭环拆解。初次配置时先跑单传感器、单规则、单动作，确认后再组合显示、告警和平台上报。更多示例见示例教程。

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

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

光照低于阈值开灯

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

电流过载断电

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

Modbus 传感器采集

使用 esp32-F4R0 或 esp32s3-F8R8 等出厂环境（统一固件已编入 Modbus）。
在"通信协议 / Modbus RTU"配置串口、波特率和从站地址。
添加 Modbus 子设备或寄存器映射。
在外设执行中使用轮询触发或 Modbus 动作读取数据，并通过 MQTT 上报。

6. 导入导出

示例若为禁用模板，导入后核对引脚再启用；少数明确说明的演示包包含启用条目，须先审阅，不能将“文档示例”视为安全状态保证。
每次批量修改前导出 peripherals.json 和 periph_exec.json。
跨芯片或跨 Flash 容量导入配置前先备份；导入后按 /api/system/status 的功能状态复核，4MB 单应用环境不支持 OTA。
I2C 模块可以共用同一组 SDA/SCL，但地址不能冲突。
经典 ESP32 的 GPIO6-GPIO11 通常连接 Flash；其他芯片和板卡按其保留表判断。
经典 ESP32 的 GPIO34-GPIO39 仅输入，不适合继电器输出；不能套用到 C3、C6、S3。

详细的引脚分配原则和硬件约束见外设配置指南。

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

7. 现场部署检查清单

现场部署前建议按下表逐项确认：

检查项	确认内容
固件环境	`-Env` 与芯片实际型号、Flash、PSRAM 一致
网络配置	WiFi SSID/密码正确，或已配置以太网/4G
MQTT 连接	正式配置、连接、订阅及业务上报有效；连接测试后还须核对原配置恢复，握手成功不等于业务成功
外设启用	引脚核对完毕，逐个启用并观察仪表盘状态
规则验证	规则先禁用 → "执行一次"验证 → 确认后再启用
配置备份	已导出 `peripherals.json` 和 `periph_exec.json` 备份
冒烟测试	运行 `smoke-test-device.ps1` 确认基本接口通过

8. 排错

现象	检查项
Web 页面能打开但外设无动作	外设是否启用、引脚是否正确、继电器有效电平是否反相
传感器读数为空	采集规则是否启用、`periphId` 是否存在、采样间隔是否太短
I2C 传感器初始化失败	SDA/SCL 是否接反、地址是否正确、是否有上拉、电源是否为 3.3V
ADC 数值异常	是否超过 3.3V、是否需要分压、ADC 衰减和校准参数是否正确
阈值规则不触发	先确认采集规则已生成 `ds:<id>_<field>` 数据源，再配置事件触发
MQTT 测试失败	先确认网络在线，再检查服务器、端口、ClientID、用户名/密码和主题规则
以太网/4G 不可用	先在功能配置确认 `compiled`；未编译时需换用支持该能力的环境，再检查运行时开关和硬件接线
Modbus 页面或动作不可用	检查 Web “功能配置”页中 Modbus 是否被运行时预算拒绝或关闭
`fastbee.local` 无法访问	确认电脑和设备在同一局域网；必要时改用路由器分配的 IP
找不到多语言切换	当前发布固件统一编译多语言资源，没有独立运行时开关；刷新 Web 资源并确认固件与 LittleFS 来自同一次构建

更详细的故障码排查和现场恢复流程见稳定性与发布检查清单。

用户操作手册 ​

1. 准备工作 ​

2. 外设配置 ​

3. 外设执行 ​

4. 传感器读取 ​

5. 典型场景 ​

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

光照低于阈值开灯 ​

电流过载断电 ​

Modbus 传感器采集 ​

6. 导入导出 ​

7. 现场部署检查清单 ​

8. 排错 ​

用户操作手册

1. 准备工作

2. 外设配置

3. 外设执行

4. 传感器读取

5. 典型场景

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

光照低于阈值开灯

电流过载断电

Modbus 传感器采集

6. 导入导出

7. 现场部署检查清单

8. 排错