操作手册
用户操作手册
本文面向实际接线和 Web 配置使用，覆盖从首次启动到外设配置、外设执行、传感器联动、导入导出和排错的完整流程。
1. 准备工作
在开始操作前，请先完成以下准备：
- 选择固件版本：根据芯片和功能需求选择 Lite/Standard/Full。完整对比见 版本对比指南。
- 烧录固件：使用部署脚本烧录匹配的 LittleFS 文件系统和固件，详见 部署、烧录与测试。
- 首次配置：连接设备 AP → 进入 Web 管理 → 配置 WiFi → 确认网络在线 → 配置 MQTT。网络和 MQTT 配置步骤见 网络配置 和 MQTT 配置。
- 手机 App 配网：除 Web 界面外，也可通过手机 App 连接 AP 热点后调用配网 API（
/api/wifi/scan、/api/wifi/connect）完成 WiFi 配置和设备参数下发。接口说明和配网流程参见 网络配置 - AP 配网 API。
快速上手完整步骤见 快速开始。
部署完成后，浏览器进入 Web 控制台应先看到仪表盘数据。
2. 外设配置
外设配置文件位于 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 | 常用模块 |
|---|---|---|
| I2C | 2 | SHT31、AHT20、BH1750、OLED、BMP280、MPU6050 |
| 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 | 四位数码管 |
| Modbus 设备 | 51 | RS485 从站控制（标准版/全功能版） |
| DEVICE_EVENT | 60 | 逻辑事件源 |
完整外设类型枚举、引脚分配原则和配置流程图详见 外设配置指南。
操作建议：Web 页面新增外设时先保存为禁用状态，确认引脚和供电后再启用。如果外设保存成功但运行不生效，依次检查页面字段、peripherals.json、运行时驱动和规则引用是否使用同一个外设 ID。
3. 外设执行
外设执行文件位于 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/1 | GPIO 高/低电平 | 继电器、LED、蜂鸣器 |
| 2/3 | 闪烁/呼吸 | LED、蜂鸣器提示 |
| 4/5 | PWM/DAC | 调光、调速、模拟输出 |
| 10 | 发送指令 | 通用外设指令（GPIO、Modbus、自定义外设等） |
| 11 | 灯效控制 | NeoPixel 颜色/动画预设 |
| 12 | 电机控制 | 步进电机正转/反转/停止 |
| 15 | 命令脚本 | 多步 GPIO/PWM/延时组合（标准版/全功能版） |
| 19 | 传感器读取 | ADC、DHT、DS18B20、HC-SR04、SHT31 等 |
| 21 | 触发事件 | 向平台或本地规则发出逻辑事件 |
| 24/25/26/27 | 显示动作 | TM1637、OLED 显示 |
| 28 | 射频发送 | 发送射频编码（如 433MHz） |
| 29 | 串口发送 | 发送串口文本数据 |
完整触发器/动作类型表、条件运算符和平台触发字段说明见 外设执行指南。
操作建议：首次上线保持规则禁用，先通过"执行一次"观察日志和外设状态。启用前确认：ID 不重复、触发器来源明确、动作目标外设存在、有日志和回滚手段。
4. 传感器读取
actionType: 19 使用 JSON 字符串描述读取方式，Web 表单会自动生成：
{
"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，标准版/全功能版）。
完整传感器分类和寄存器级配置参数见 传感器完整指南。
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-F8R0或 Full 固件。 - 在"通信协议 / Modbus RTU"配置串口、波特率和从站地址。
- 添加 Modbus 子设备或寄存器映射。
- 在外设执行中使用轮询触发或 Modbus 动作读取数据，并通过 MQTT 上报。
6. 导入导出
- 所有文档示例默认
enabled: false，导入后先检查引脚再启用。 - 每次批量修改前导出
peripherals.json和periph_exec.json。 - 从全功能版导出的配置导入 Lite/Standard 时，高级功能字段会被忽略；Lite 不支持 Modbus、命令脚本、RuleScript、OTA 等规则。
- I2C 模块可以共用同一组 SDA/SCL，但地址不能冲突。
- GPIO6-GPIO11 通常连接 Flash，不建议作为外设引脚。
- GPIO34-GPIO39 仅输入，适合 ADC/数字输入，不适合继电器输出。
详细的引脚分配原则和硬件约束见 外设配置指南。
建议形成固定流程：每次修改先备份，导入前校验 JSON，导入后用仪表盘、日志和对应功能页复核。
7. 现场部署检查清单
现场部署前建议按下表逐项确认：
| 检查项 | 确认内容 |
|---|---|
| 固件版本 | -Env 与芯片型号和版本档位一致 |
| 网络配置 | WiFi SSID/密码正确，或已配置以太网/4G |
| MQTT 连接 | 服务器地址、端口、ClientID、用户名密码已填写，连接测试返回 connected |
| 外设启用 | 引脚核对完毕，逐个启用并观察仪表盘状态 |
| 规则验证 | 规则先禁用 → "执行一次"验证 → 确认后再启用 |
| 配置备份 | 已导出 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 菜单不可用 | 确认固件是否为 Full 或已定制开启相关开关；Lite/Standard 默认关闭这些能力 |
| Modbus 页面或动作不可用 | 精简版默认关闭 Modbus，请切换 esp32-F4R0、esp32s3-F8R0 或 Full 固件 |
fastbee.local 无法访问 | 确认电脑和设备在同一局域网；必要时改用路由器分配的 IP |
| 找不到多语言切换 | Lite/Standard 默认单语言，完整多语言仅 Full 保留 |
更详细的故障码排查和现场恢复流程见 稳定性与发布检查清单。