ECM50-A 多网络联网案例（4G Cat.1 联网）

适用设备：亿佰特 ECM50-A 工业网关（ESP32-S3 R8 + 8MB PSRAM + 16MB Flash） 4G 模组：移远 EC801E-CN（Cat.1；本项目适配的AT命令子集不等于SIM7600/BG96全部命令兼容）固件环境：esp32s3-F16R8（本板 16MB Flash；其他容量必须选择匹配环境）

本文档汇总 ECM50-A 的多模组网配置、4G Cat.1 模组的 AT 指令交互细节、串口日志判读与网络状态验证方法；行为以当前 platformio.ini、src/network/CellularAdapter.cpp 和设备状态 API 为准。

第 8 节同步 COM15 设备的现场外设配置：五个 Modbus 采集设备、一个 Modbus 继电器、D1/D2 光电输入、A1/A2 土壤模拟量输入，以及本板继电器灯控。2026-09-22 按现场要求更新配置和双 DI 故障检测。Modbus 经用户授权先采用模板默认参数；下文网络历史日志不代表本次外设已完成实物验收，当前验证状态见第 8 节。

下文带日期的COM15/IP、构建、网络与外设结果均为历史窗口，不是本次复测。当前运行JSON在上述设备目录的config/，旧ecm50a目录仅保留硬件说明。feature=active表示功能配置状态，不能单独证明模组联网或初始化；internetAvailable也不能单独证明流量经过4G。

1. 硬件规格

项目	参数
主控	ESP32-S3 双核 Xtensa LX7 @ 240MHz
内存	8MB Octal PSRAM
存储	16MB NOR Flash（分区表 `partitions/16MB.csv`）
供电	DC 8-28V 宽电压
通信	Wi-Fi / 4G Cat.1 / 以太网 / LoRa 四模
IO	2×AI（4-20mA）、2×DI、2×DO 继电器、RS485/RS232

1.1 关键 GPIO 分配（摘自 Pin_List）

功能	GPIO	备注
A1 / A2（AI1 / AI2）	GPIO6 / GPIO7	4-20mA 土壤传感器：A1 水分 0–100%，A2 温度 −40–80°C，均保留一位小数
D1 / D2（DI1 / DI2）	GPIO4 / GPIO5	光电传感器黑线 NO / 白线 NC
DO1 / DO2	GPIO15 / GPIO16	本板继电器 COM/NO/NC；灯使用哪一路待确认
RS485 TX / RX	GPIO17 / GPIO18	UART1
以太网 SPI	SCLK=12 / MISO=13 / MOSI=11 / INT=14	CS=47、RST=48（见 network.json）
Run LED	GPIO21	运行指示

1.2 4G 模组接线（`network.json` → `cellular` 段）

jsonc

"cellular": {
  "txPin": 39,
  "rxPin": 40,
  "pwrPin": 38,
  "baudRate": 115200,
  "apn": "CMNET"
}

UART：波特率 115200，8N1。有 UART2 的芯片优先 Serial2，否则回退 Serial1（UART0 被日志/USB 占用）。
PWRKEY：GPIO38，低电平有效。
APN：默认 CMNET（移动），代码中空 APN 自动回退 CMNET；联通用 3GNET、电信用 CTNET。

2. 多模网络配置

所有网络配置保存在 LittleFS 的 /config/network.json，可通过 Web 界面「网络设置」页或配置导入 API 修改。

2.1 Wi-Fi（STA 优先）

jsonc

"mode": 0,
"staSSID": "<local-ssid>",
"staPassword": "<local-password>",
"connectTimeout": 20000,
"reconnectInterval": 5000,
"maxReconnectAttempts": 5

⚠️ 调试纪律：验证设备一律走 STA 模式接入现有路由器，不要让电脑连接设备 AP 热点。示例占位符必须替换为本地凭据，且不得提交生产密码或令牌。 AP 兜底参数：SSID 同设备名，密码默认 admin123，网关 192.168.4.1。

弱信号链路连接策略（2026-08 起固件内置，针对 RSSI 临界设备）：全信道扫描 + 按信号排序 + 关闭 modem sleep（WiFi.setSleep(false)）。实测弱信号设备在 modem sleep 开启时认证握手易超时（反复 AUTH_EXPIRE reason=2/3/36），关闭后认证成功率显著提升。

2.2 以太网

jsonc

"ethernet": {
  "spiMosi": 11, "spiMiso": 13, "spiSck": 12,
  "csPin": 47, "rstPin": 48, "intPin": 14
}

插入 RJ45 后 PHY link up 自动走 DHCP；状态可在「网络设置」页或以太网状态 API 查看。

2.3 4G Cat.1（EC801E-CN）

Web 操作路径：网络设置 → 联网模式 → 4G，填写 APN 后保存，设备按配置重启/切换后执行模组上电与拨号。

2.4 网络切换逻辑

jsonc

"failoverStrategy": 2,
"autoFailover": true,
"maxFailoverAttempts": 3,
"fallbackToDHCP": true,
"enableMDNS": true,
"customDomain": "fastbee"

优先级与故障转移由 NetworkManager 统一调度：主链路断开后按 failoverStrategy 自动切换，恢复后按策略回切。
STA 失败自动回退 AP + 周期探测恢复：开机 STA 连接耗尽重试后设备回退 AP 模式（_apFallbackAuto），之后每 2 分钟短暂切 STA 探测一次（单次窗口 15s，判据为关联成功且 DHCP 拿到 IP）；连续失败 5 次进入退避（每 10 分钟探测一次）。探测成功后自动切回 STA，无需人工干预。
mDNS 域名 http://fastbee.local（enableMDNS=true 时生效）。
4G 的 PDP 状态由 CellularAdapter::update() 每 10s 用 AT+CGPADDR 刷新；API 请求会触发 forceUpdate() 立即刷新。

3. 4G AT 指令交互详解（CellularAdapter 实测流程）

3.1 上电与握手时序

步骤	动作	代码/AT	超时
1	PWRKEY 拉低 1s 后释放触发上电	`powerOn()` GPIO38 LOW→HIGH	—
2	等待模组启动	`delay(5000)`	5s
3	DRAM 水位预检	`CELLULAR_BEGIN_MIN_DRAM` 不足则跳过初始化	—
4	AT 握手	`testAT(1000)` 循环	30s
5	失败则重新上电再试一次	`powerOff()→2s→powerOn()→5s`	15s
6	SIM 就绪检查	`getSimStatus()`，未就绪补等 3s 重试	—
7	信号质量	`AT+CSQ`（CSQ=99/0 告警）	—
8	网络注册	`waitForNetwork()`	120s
9	PDP 激活	`gprsConnect(apn,"","")`，最多 3 次，退避 5s/10s	—

关机：PWRKEY 拉低 1s（≥800ms）触发正常关机，随后等 3s 完成。

3.2 PDP 激活的三重校验

EC801E 与 TinyGSM SIM7600 模式存在兼容差异（AT+CIPSTATUS 不被 EC801E 支持），代码采用多重校验避免误判：

gprsConnect() 成功且 localIP() 为可用 IPv4 且 AT+CGPADDR=1 有分配地址 → 连接成功；
TinyGSM 报失败但 AT+CGPADDR=1 返回有效 IP（如 +CGPADDR: 1,"10.3.89.109"）→ 判定实际已连上（日志 TinyGSM reported fail but PDP is active!）；
首次失败执行 AT 级诊断并尝试手动激活：

text

AT+CGATT?      → PS 附着状态
AT+CGACT?      → PDP 上下文激活状态
AT+CGDCONT?    → PDP 上下文定义
AT+COPS?       → 当前运营商
AT+CEREG?      → LTE 注册状态
AT+CGATT=1     → 确保 PS 附着
AT+CGDCONT=1,"IP","CMNET"
AT+CGACT=1,1   → 手动激活 PDP
AT+CGPADDR=1   → 确认分配 IP

3.3 MQTTS over 4G（Quectel SSL 指令）

QuectelSslClient 直接使用 Quectel SSL AT 建立 TLS（默认 contextId=1、connectId=4、sslContextId=1）：

text

AT+QICSGP=1,1,"CMNET","","",1     ; 定义 PDP（IPv4）
AT+QIACT=1                          ; 激活上下文（超时 150s）
AT+QIACT?                           ; 查询上下文状态
AT+QSSLCFG="seclevel",1,0           ; 不校验证书（自签/测试）
AT+QSSLCFG="sslversion",1,4         ; TLS1.2（失败回退 3=TLS1.1）
AT+QSSLCFG="ignorelocaltime",1,1
AT+QSSLCFG="sni",1,1
AT+QSSLCFG="ciphersuite",1,0XFFFF
AT+QSSLOPEN=1,1,4,"host",8883,0     ; 建立 TLS 连接
AT+QSSLSEND=4,<len>                 ; 发送（等待 prompt）
AT+QSSLRECV=4,<len>                 ; 接收
AT+QSSLCLOSE=4                      ; 关闭

URC 处理：+QSSLURC: "recv" 标记待读数据；"closed" / "pdpdeact" 置为断开。当前选择器优先 TinyGSM TCP + ESP32 mbedTLS 软件 TLS（CellularSoftwareTlsClient），其次才是 QSSL 对象。2026-10-04 的 r19 后继代码在两种 TLS 对象都不可用时拒绝启动，不再回退普通 TCP Client。传输选择在实例建立前失败时，状态可能报告客户端启动失败（-11）；只有 MQTTClient 对未标记为可信 TLS 的外部 Client 执行安全检查时才记录 MQTTS_TRANSPORT_UNAVAILABLE（-15），不能承诺已销毁实例继续返回该码。TLS 对象已分配不代表握手或证书认证通过，QSSL 示例中的 seclevel=0 仍只是测试配置，不能据此宣称证书认证通过。该后继修复待统一软件门禁和实际蜂窝设备验收；本页旧实测记录保持原结论。

4. 串口日志判读

4.1 正常上线序列（实测样例结构）

text

[4G] Initializing EC801E-CN 4G module...
[4G] UART pins - TX:39, RX:40, PWR:38, Baud:115200
[4G] Power ON pulse sent (GPIO38, LOW 1s -> HIGH)
[4G] Waiting for modem startup (5s)...
[4G] Testing AT communication (timeout 30000ms)...
[4G] AT OK (1234ms)
[4G] Modem info: EC801E-CN...
[4G] IMEI: 860000000000000
[4G] SIM ready
[4G] Signal quality (CSQ): 23
[4G] Registering network (timeout 120s)...
[4G] Network registered
[4G] CSQ after registration: 24
[4G] Operator: CHINA MOBILE
[4G] Connecting GPRS with APN: CMNET
[4G] GPRS connect attempt 1/3...
[4G] Initialized and connected successfully

4.2 异常日志与处置

日志	含义	处置
`ERROR: Modem not responding to AT commands`	UART 不通	检查 TX/RX 交叉接线、波特率；代码会自动重新上电重试一次
`ERROR: SIM not ready, status: x`	SIM 未就绪	重插 SIM、确认卡方向与套餐已激活
`WARNING: Very weak or no signal (CSQ=99)`	无信号	更换天线/位置；CSQ≥15 较理想
`ERROR: Network registration failed`	120s 未注册	查 `AT+CEREG?`；确认 SIM 支持 LTE、未锁频段
`GPRS connected but CGPADDR inactive`	拨号成功但 PDP 未生效	代码自动重试；持续出现换 APN
`ERROR: DRAM below ...`	内存预算不足	关闭其他高 RAM 功能后重试（4G 受启动预算保护）
`[WiFi] Disconnected! reason=2/3/36`（AUTH_EXPIRE）	Wi-Fi 认证反复失败	多为弱信号链路认证握手超时；固件已内置关 modem sleep 等缓解策略；同网络其他设备正常即为该设备射频环境问题，需移近路由或换天线
`[STATUS] WiFi=AP_MODE` 长期不恢复	STA 失败回退 AP 后探测未成功	设备按 2 分钟/次（退避期 10 分钟/次）自动探测恢复；也可断电重启触发开机重连；凭据问题用 esptool 离线改 LittleFS `network.json`

5. 网络状态验证

5.1 自动验证（STA/Wi-Fi 通道下执行）

powershell

powershell -ExecutionPolicy Bypass -File scripts\smoke-test-device.ps1 -BaseUrl http://<device-sta-ip> -Profile unified -RequireNetworkConnected
powershell -ExecutionPolicy Bypass -File scripts\device-web-smoke.ps1 -BaseUrl http://<device-sta-ip> -Rounds 2 -DelayMs 1000 -TimeoutSec 15 -MaxElapsedMs 5000

/api/system/status 的已登录响应示例：

json

{
  "success": true,
  "data": {
    "status": "running",
    "freeHeap": 39540,
    "features": { "webServer": "active", "cellular": "active", "ethernet": "active", "mdns": "active" },
    "networkStatus": "connected",
    "networkStatusCode": 2,
    "deviceNetworkType": 0,
    "ipAddress": "<device-sta-ip>",
    "ssid": "<local-ssid>",
    "rssi": -72,
    "macAddress": "<device-mac>",
    "internetAvailable": true
  }
}

判读要点：

features.cellular = "active"：4G 功能已编译且启动预算通过（no-memory 表示被内存预算拒绝）。
deviceNetworkType：当前主链路类型（0=Wi-Fi，4G 链路切换后该字段相应变化）。
internetAvailable：外网探测结果，4G 模式下为 true 即 Cat.1 链路可用。

5.2 Web 界面验证

浏览器访问 http://<ip>（或 http://fastbee.local），默认账号 admin / admin123 登录；
「网络设置」页确认联网模式、信号/注册状态；
「仪表盘」页查看网络卡片与 heap 水位。

设备 API 默认需要登录态；以上脚本会处理认证。不要把未认证的 curl 结果当作网络功能结论。

6. 部署要点

现场配置在 FastBee-Arduino 仓库的 docs/device-test-configs/com15-esp32s3-f16r8/。第 8 节给出当前量程、双 DI 故障事件及已启用的 Modbus 默认参数。部署前应检查配置与目标设备身份。下面的 COM15 是本次 ECM50-A 的串口标签，烧录前仍需按芯片和 MAC 核对实物；其他 S3 板即使同为 esp32s3-F16R8，也不能套用本板配置或备份。

powershell

# 在 FastBee-Arduino 源码仓库根目录执行
# PreserveConfigPath 必须是已核对设备身份的最新私有配置备份
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\deploy-config-bundle.ps1 `
  -Env esp32s3-F16R8 -Port COM15 `
  -BundlePath docs\device-test-configs\com15-esp32s3-f16r8\config -NetworkProfile ecm50a `
  -PreserveConfigPath .device-config-backups\latest\esp32s3-F16R8 `
  -DryRun

-DryRun 只做配置预检，不写设备。核对目标、备份和配置后再执行实际部署。当前 Modbus 默认参数经用户授权启用，仍需据真实设备响应核实。MQTT 保持关闭，接入信息由用户后续填写；烧录时保留设备现有身份、网络和认证材料。

注意事项：

固件与 Web 文件系统应使用匹配版本；上述默认部署流程会上传固件和 LittleFS。配置更新前先备份现机，避免覆盖设备身份、网络和用户配置。
4MB 分区表（经典 ESP32/C3）的文件系统分区标签为 spiffs，这是 LittleFS 兼容标签，不代表使用 SPIFFS；ECM50-A 使用 16MB 分区表。
esp32s3-F16R8 已编译以太网和 4G，运行时默认关闭；ECM50-A 接好模组后还需在“功能配置”中启用，并通过启动内存预算检查。4MB 与 C3/C6 发布环境不能复用这一能力说明。
4G 与 MQTT/MQTTS 联调时，先在 Wi-Fi 下配置好 broker 参数，再切 4G 验证 mqtts 特性状态（4MB 机型可能因内存显示 no-memory，S3 正常）。

7. 故障排查 FAQ

Q1：串口反复出现 [4G] ERROR: Modem not responding？ A：优先排查硬件（PWRKEY 脉冲是否送达、UART 电平与交叉接线、模组供电 ≥2A）。代码已内置一次自动重上电；持续失败时手动断电重启整机。

Q2：注册成功但拿不到 IP？ A：AT+COPS? 确认运营商，AT+CEREG? 确认注册（stat=1/5）；换 APN（CMNET/3GNET/CTNET）；SIM 卡欠费/未开数据也会卡在 PDP。

Q3：MQTTS over 4G 握手失败？ A：优先走软件 TLS（mbedTLS）路径；使用 QSSL 时确认证书等级配置（seclevel=0 用于自签测试）。+QSSLURC: "pdpdeact" 说明 PDP 掉线，先解决 4G 链路稳定性。

Q4：4G 与 Wi-Fi 切换不生效？ A：确认 autoFailover=true 与 failoverStrategy；查看串口 [NET]/[STATUS] 日志中主链路切换记录；必要时用「网络设置」页强制指定联网模式验证单链路。

Q5：Wi-Fi 凭据正确却反复 AUTH_EXPIRE (reason=2/3/36) 连不上？ A：典型弱信号链路症状（RSSI 临界，认证握手超时）。排查顺序：① 确认同网络其他设备可正常连接（可连则为本设备射频环境问题）；② 用 esptool dump LittleFS 分区提取 network.json 核对凭据；③ 物理手段：设备移近路由器、更换/调整天线。固件侧已内置缓解策略（关 modem sleep、全信道扫描、按信号排序），只能提升恢复概率，根治需改善射频环境。

Q6：设备掉回 AP 模式后如何恢复 STA？ A：无需人工干预——固件每 2 分钟自动探测 STA 可用性（退避期 10 分钟/次），窗口打开即自动切回。需要立即恢复时可断电重启触发开机重连。注意调试纪律：电脑不要连接设备 AP 热点，恢复验证一律走 STA。

Q7：之前能访问的 IP 突然 404 或完全不通了？ A：多为 DHCP 租约漂移——路由器重启或租约过期后设备可能分到新 IP。不要硬编码 IP：启动横幅会打印最新 Access URL；批量验证时先扫子网（ping 存活主机后查 /api/system/status），用返回的 macAddress 确认设备身份再更新目标地址；长期使用建议在路由器为设备 MAC 绑定固定 IP。仓库 E2E 套件已默认自动发现在线设备（resolveDevices() + discover-devices.js），无需手工维护 IP 列表。

Q8：设备能连上 Wi-Fi但几分钟后又掉线，反复循环？ A：这是边界信号的另一种形态：关联能成功但链路维持不住（通常 RSSI 仅 -65~-75 dBm）。固件会自动重连，不需人工干预；但若需在窗口期内完成验证/烧录等操作，建议用脚本按 MAC 轮询设备状态，发现链路稳定后再执行长流程任务。根治仍靠物理手段：移近路由器、更换/调整天线、避开金属遮挡。

Q9：Web 登录报「用户名或密码错误」，但凭据确认无误？ A：设备 LittleFS 中的 users.json 可能来自历史改密或旧镜像。先核对实际凭据和已有配置备份；不要把重新上传默认 LittleFS 当作“保留网络的密码重置”，因为它可能同时覆盖用户、网络、协议和外设配置。确需重刷时，先导出或离线备份整个配置分区，并准备重新注入本地网络与平台凭据。

Q10：浏览器访问 http://fastbee.local/ 打不开或指向了错的设备？ A：多设备使用相同 customDomain（默认 fastbee）会产生 mDNS 冲突。固件启动时会探测已占用名称并自动追加后缀，运行中每 30 秒再次收敛；实际名称可从需登录的 /api/network/status 的 mdnsDomain 字段查看。若要固定某台设备使用 fastbee.local，让它先上线或为它设置独立的 customDomain，保存网络设置后设备会重启。

探测依赖局域网多播；弱网络下可能短暂冲突，重启即可重新探测。经典 ESP32 F4R0 的内部内存较少，若 mDNS 触发 Web 内存门控（持续 503），建议关闭 mDNS 并直接使用 IP 访问。

8. ECM50-A F16R8 外设与 Modbus 配置

FastBee-Arduino 提供了与本板引脚表对应的 S3 专用配置目录： docs/device-test-configs/com15-esp32s3-f16r8/。该配置只能用于 esp32s3-F16R8，不得复制给 C3、C6 或经典 ESP32。

8.1 当前配置状态（2026-09-22）

项目	当前状态
Modbus 拓扑	5 个采集设备、1 个继电器，地址 1–6，全部 9600 波特率
Modbus 参数	温湿度按 IVG-TH 文档配置，漏水及温湿度已实际读通；其余未确认的单位、倍率与控制参数仍需核对
土壤模拟量	温度 −40–80°C；水分 0–100%；均按 0.1 分辨率显示/上报
光电故障与灯控	双 DI 互补检测，组合稳定 200ms 后触发一次 `break_down` 事件；DI1 有物体进入时翻转本板 DO1 一次
MQTT	保持关闭；接入信息后续由用户填写，属性/事件/控制主题已预置
部署验收	r3 固件与配置已完成 COM15 烧录及校验，实际网页及采集复测见 8.8；8.7 为旧版历史记录

8.2 现场接线

接口 / 功能	配置 ID	引脚与用途
A1：土壤水分	`ai_soil_humidity`	GPIO6，4–20mA → 0–100%
A2：土壤温度	`ai_soil_temp`	GPIO7，4–20mA → −40–80°C
DI1 / D1：黑线 NO	`di1`	GPIO4，上拉、不反相
DI2 / D2：白线 NC	`di2`	GPIO5，上拉、不反相
本板继电器灯控	`do1` / `do2`	GPIO15 / GPIO16；按灯实际接入的 DO 接口选择
RS485	`rs485`	RX=18、TX=17，9600、8-N-1，自动收发 `dePin=255`

A1 水分、A2 温度按当前传感器线序配置：黄色水分信号接 A1，蓝色温度信号接 A2。原模板 SHT30 不在本次清单中，其外设与独立 s3_optional_sht30 采集规则已按现场配置删除，保留的 I2C 总线禁用。

8.3 Modbus 设备和当前默认参数

以下参数已按用户要求启用。PM2.5/PM10 寄存器地址由用户提供；温湿度依据 IVG-TH 协议图片，漏水 FC04 已实测读通。其他未确认的协议细节沿用默认值，并非已核实的厂家协议。

从站地址	设备	任务 / 设备索引	当前参数
1	漏水控制器	0 / —	FC04，寄存器 0，1 个 UINT16，倍率 1；漏水状态编码待核实
2	TVOC	1 / —	FC03，寄存器 0，UINT16，倍率 1，ppb
3	甲醛	2 / —	FC03，寄存器 0，UINT16，倍率 0.001，ppm
4	空气质量	3 / —	FC04，PM2.5=`0x0000`、PM10=`0x0001`，UINT16，倍率 1，ugm3
5	温湿度 IVG-TH	4 / —	FC04，温度寄存器 0 / 湿度寄存器 1，倍率 0.1；温度为 INT16 补码
6	Modbus 继电器	无 / 0	4 通道，通道 1 起始地址 `0x0000`，FC06 保持寄存器控制，`ncMode=true`

总线采用 9600、8-N-1。五个采集任务按当前配置每 30 秒轮询；任务顺序为漏水、TVOC、甲醛、PM、温湿度。执行规则中地址 2–5 共用一条 s3_modbus_environment（{"poll":[1,2,3,4]}），地址 1 单独保留以隔离失败退避。五条 Modbus 轮询规则减为两条，当前执行规则共 8 条。不同从站仍需分别请求；同一从站的连续寄存器可一次读取。任务/设备索引从 0 开始，不能与从站地址混用。

继电器开关规则 s3_modbus_relay、s3_modbus_relay_off 的目标均为 modbus:0，动作中的 d=0 指设备索引，实际地址为 6。根据中盛手册，通道 1 对应保持寄存器 0x0000，当前使用 FC06（写入 1 吸合、写入 0 释放），模块配置为 4 通道。ncMode=true 用于匹配 NC 接线：平台开状态时线圈释放、NC 导通；平台关状态时线圈吸合、NC 断开。灯连接本板继电器，具有独立的 do1 / do2 控制规则。

默认参数不保证适配每个厂家。异常码或超时需根据协议修正功能码、地址或串口格式；读数返回后仍需核对单位、倍率和符号。采集值来自设备实际响应，不生成随机数替代失败读数。

8.4 双 DI 光电检测和设备故障事件

现场状态	黑线 NO / DI1	白线 NC / DI2	判定
无物体	悬空，高 `1`	导通，低 `0`	正常，无物体
有物体	导通，低 `0`	悬空，高 `1`	正常，有物体
双高	高 `1`	高 `1`	故障，包括所述断线或掉电情形
双低	低 `0`	低 `0`	非法组合，按故障处理

两路配置为普通 DI（type=11、inputMode=2、invertLogic=false），单路去抖 50ms。仅在 DI1 配置：

json

{
  "pairedInputId": "di2",
  "pairDebounceMs": 200
}

固件通过现有 100ms 输入检查任务采样两路，组合连续稳定 200ms 后确认，以抑制 NO/NC 切换的短暂同电平。配对输入不存在、禁用或读取失败也按故障处理。Web 外设编辑中可设置互补输入 ID 和组合确认时间；只需在两路中的一路启用配对。

每次持续故障仅触发一次 break_down 设备故障事件；恢复为互补状态并稳定后，重新允许下一次故障告警。MQTT 不可用时保留当前故障的待发状态，连接后尝试发送，失败至少间隔 5 秒重试，成功后不重复。恢复时取消待发事件，避免重连后补报已消失的故障。待发状态保存在 RAM，重启后重新检测。

新增执行规则 s3_photoelectric_relay_toggle：DI1 稳定从高变低（有物体进入）时，执行一次 ACTION_GPIO_TOGGLE 翻转本板 do1。物体持续停留不会重复触发，离开时不再翻转；双高/双低故障只产生 break_down，不会误触发灯控。灯若接在 DO2，应将该规则动作目标改为 do2。平台实际接收仍需在填写 MQTT 接入信息后验证。

8.5 4–20mA 土壤温度和水分

参数	水分 A1	温度 A2
输入电流	4–20mA	4–20mA
工程量范围	0–100%	−40–80°C
分辨率 / 输出小数位	0.1% / 1 位	0.1°C / 1 位
属性 ID	`soil_humidity`	`soil_temperature`
线性换算	`(I_mA−4) × 100/16`	`−40 + (I_mA−4) × 120/16`

soil_humidity 保留既有属性 ID，单位使用土壤水分 %，不是空气相对湿度 %RH。s3_collect_inputs 每 10 秒采集两路，量程转换统一维护在外设参数，采集动作不重复换算。

当前公开配置使用150Ω分流电阻和calibratedVoltage芯片校准曲线；历史165Ω值不作为当前配置。模拟前端采用150Ω分流电阻、inputGain=1、inputOffset=0、vRef=3.3，每次 16 次均值采样；这些电路参数仍需与实板和标准电流源核对。设置一位小数不代表已达到该实测精度。clampEnabled=false，输入异常保留质量状态，不钳位成正常端点。

校准时同时核对原始值、工程值和质量状态。字段说明见 ADC 模拟输入和电流传感器。

8.6 本板继电器灯控与 MQTT

灯接 ECM50-A 本板继电器接口，保留 s3_platform_do1、s3_platform_do2 两条平台控制规则，输出初始值均为 0，并启用 s3_photoelectric_relay_toggle 联动：灯接 DO1 时，有物体经过一次就翻转当前继电器状态。按实际 DO 接口控制开关，并核对 NO/NC 接线和驱动电平对应的灯状态；灯接 DO2 时需把联动规则目标改为 do2。地址 6 的 Modbus 继电器通道 1 使用 FC06 和保持寄存器 0x0000，当前模块为 4 通道。

MQTT 保持关闭，broker、身份和认证信息由用户后续输入。模板预置 /property/post（属性）、/event/post（设备事件，topicType=4）和 /function/get（控制），均使用 autoPrefix=true 自动加设备前缀。平台物模型需包含 break_down 设备故障事件。

平台事件格式沿用固件标准：

json

[{"id":"break_down","value":"设备故障","remark":"event"}]

填写 MQTT 参数并启用后，在平台核对属性、事件和灯控；未连接期间，本地故障判定与平台接收是两项不同的验证结果。公开文档不保存真实凭据。

8.7 首次部署验证记录（r2 历史版本）

本节保留首次部署的历史结果；当前 r3 修复及复测见 8.8，地址 1、5 的旧超时结论已被后续成功读取取代。

固件、配套 Web 与现场配置已完成 COM15 / ESP32-S3-F16R8 烧录及读回校验，保留设备现有身份、网络和认证材料。设备 MAC 为 14:C1:9F:C1:52:D8；验证时访问地址为 http://192.168.5.18，mDNS 为 http://ecm50a-s3.local。IP 可能随 DHCP 租约变化。

本地单元测试共运行 681 项（680 项通过、1 项跳过），包含实际 C++ 互补输入状态机的正常组合、双高/双低、切换毛刺、恢复、重连补发和计时回绕检查；修复后另有 14 项 Modbus 定向测试、36 项外设执行测试通过。配置、Web 体积及 Markdown 检查通过。

首次现场运行发现 Modbus 数据分发复制大配置导致工作线程栈溢出，已修复并重新构建部署。最终构建确认源码在构建期间未变化，采用冻结的固件、Web 和配置发布。修复版启动观察未见崩溃，后续 API 复查运行时间为 8 分 25 秒，内存保护状态正常；尚未完成长期稳定性验收。

检查项	实测结果与后续事项
光电 DI	DI1=1、DI2=0，符合无物体状态；遮挡、断线、恢复和故障事件仍需现场联调
A1 土壤水分	旧版接线/标签记录：原始值 687，质量 `low`、工程值为空；当前映射已调整为水分
A2 土壤温度	旧版接线/标签记录：约 43.0% 的原始换算值；当前映射已调整为温度
Modbus 地址 2、3、4	已获得实际响应，单位与倍率仍需核对。地址 4 后续出现缓存过期，刷新稳定性待核实
Modbus 地址 1、5	默认参数下轮询及重复读取均超时，需核对供电、地址、接线和厂家协议
Modbus 地址 6	默认 FC01 线圈状态读取超时，未执行开关动作
本板继电器灯控	DO1、DO2 状态均为 0，灯具实际动作尚未验收
MQTT 平台	按要求保持关闭，属性、故障事件和控制需填写接入信息后验证

任务配置周期为 10 秒，超时后的自适应退避会延长实际轮询间隔，本次地址 1、5 观察到 40 秒。当前结论是配置和部署完成，不能将其等同于全部传感器、灯控及平台链路已通过实物验收。

8.8 2026-09-22 现场问题修复（r3 当前版本）

温湿度按 IVG-TH 文档改为 FC04，从 0x0000 连读两个寄存器，温度在前、湿度在后，倍率均为 0.1；温度采用有符号 16 位补码。实际读回 05 04 04 00 EA 02 6B DF 3F，对应 23.4°C、61.9%RH。温度属性 ID 调整为 modbus_temp，避免超过固件 15 字符上限而被截断，平台物模型应使用此 ID。
漏水读取改为 FC04、寄存器 0、数量 1；正确单寄存器请求为 01 04 00 00 00 01 31 CA。用户提供的响应 01 04 02 00 00 B9 30 表示原始值 0，漏水/无漏水编码仍以厂家定义为准。用户重新连接漏水支路后，通过 ESP32 连续两次读回该响应，通信恢复。
串口证实 pexec_w1 栈溢出：超时告警同步触发日志文件轮转及 LittleFS 删除，耗尽工作线程栈。日志生产入口已改为只入缓冲，由既有主循环定时写盘；同时去除其余 Modbus 配置大对象拷贝。没有通过增加工作线程栈掩盖该路径。
UART 终端用于通用串口读写，I2C 探测用于地址扫描和传感器诊断，继续保留。已补齐单条外设与列表能力字段；禁用外设或由 Modbus 占用的串口仅显示原因并禁止读写，不再显示内部 descriptor 错误。RS485 调试应使用 Modbus 协议页。
外设/外设执行列表删除末页最后一项后自动回到有效页；服务器和浏览器同步页码，过滤先于分页。Modbus 删除保存到设备，失败恢复列表；空配置不再从浏览器历史缓存复活。仍被执行规则引用的子设备需先处理引用，避免索引移位后控制错误设备。
补测发现登录后直接进入 Modbus 页面会依赖尚未加载的翻译函数，出现 t is not defined；两个协议模块已改为自带局部回退，新增直接入口回归通过。网页资源以 r3b 单独更新，固件保持 r3。

修复版已部署到 COM15，固件与 LittleFS 写入校验通过；构建报告确认源码在构建期间未变化。现场网络、身份、认证及 MQTT 配置均保留，仅更新三份现场配置和配套 Web。

本地单元测试结合环境修复后的定向复跑，共 710 项通过、1 项因 Windows 符号链接权限跳过；没有将其表述为整套重跑。新增浏览器回归 17 项通过，覆盖诊断入口、末页删除回退、Modbus 直接入口、删除保存/失败回滚/刷新及空列表。

实机浏览器完成两轮菜单导航：外设 9 项、执行规则 7 项、Modbus 6 项（5 采集、1 控制）。RS485 协议占用及 I2C 禁用提示正确，越界分页返回有效末页；HTTP 错误、401 和 JavaScript 错误均为 0。现场浏览器验收为只读；删除持久化及失败回滚由本地模拟 API 回归覆盖，未做实机删除落盘验收。

检查项	r3 实测结果
光电 DI	DI1=1、DI2=0，符合无物体状态
漏水控制器	FC04 读回原始值 0；漏水编码仍需厂家确认
空气温湿度	FC04 连读 237/594，对应 23.7°C、59.4%RH
A1 土壤水分	原始值约 690，低于 4mA 起始值；探头未插土，暂不作传感器故障结论
A2 土壤温度	原始值约 2260；映射调整前曾按水分公式显示，当前应按温度公式换算

实机连续观察约 12 分钟（120 次 API 采样并同步串口采集）全部通过：运行时间连续、无登录失效、内存保护状态始终 NORMAL、串口未见崩溃。最终五个 Modbus 任务均有实际缓存且 lastError=0。已覆盖漏水读取超时后重试成功、日志轮转及旧备份删除，未复现旧栈溢出；工作线程最低剩余栈观测值为 1164 字节。

日志写盘仍出现最长约 4.3 秒的主循环停顿，可能造成页面或调度暂时延迟；本次修复消除了工作线程同步写盘的崩溃路径，不能等同于长期稳定性验收或完全无阻塞。MQTT 按要求保持关闭；平台故障事件接收、光电遮挡/故障/恢复切换、标准电流校准及继电器负载动作仍待现场验收。

r3b 网页更新完成，写入及固件保留校验通过，全部现有配置原样保留。此次更新引起的受控重启不计入上述连续观察窗口。新浏览器直接登录后进入 Modbus 页，两轮均正常显示 RS485 UART1 和六条设备数据，无 HTTP 或 JavaScript 错误；重启后五个采集任务再次读到数据，配置仍为五采集一控制。

r3b 完整页面复测最终通过，两轮导航、诊断说明和分页检查均成功，HTTP/401/JavaScript 错误均为 0。此前补测出现过一次原因未确定的登录请求取消及一次诊断模块超过测试默认 5 秒等待；最终脚本等待页面启动完成，并统一使用 45 秒断言等待。相关失败记录保留，最终通过不代表页面始终快速响应。

2026-09-24 设备大屏布局及现场配置更新

本次仅更新 COM15 的 LittleFS，固件保持 r3。设备 MAC 为 14:C1:9F:C1:52:D8，本次联网地址为 192.168.5.19（DHCP 地址可能变化）。文件系统写入和 MD5 校验通过；保留网络、身份、认证及 MQTT 设置。

“设备大屏”的重置布局按钮位于 device-control 页面。问题是 Modbus 设备清单卡宽 695px，旧排版却只占用一列 340px，导致越界或重叠。修复按卡片实际宽度分配列数，默认布局与重置共用该逻辑。发布以已部署 r3b 网页为基线，解压内容仅控制视图脚本及入口/Service Worker 缓存版本变化；不是将另一“设备屏幕”编辑器的改动混入此次发布。Web 57 文件，312.4/315 KiB 门禁通过。

外设与执行规则名称已改为中文，继电器配置回读为地址 6、9600、4 通道、寄存器基址 0、FC06、NC 反向语义。NC 接点在线圈释放时导通，吸合时断开。光电联动仍是本板 DO1/继电器1。

本地布局浏览器回归 17/17、继电器配置回归 3/3 通过。设备新脚本与发布包解压字节一致。最终实机在1440px和1920px两种窗口下，默认/重置/页面返回共6项几何检查全部通过，HTTP、批量子请求和JavaScript错误均为0。完整实机结果以 artifacts/com15-layout-final-20260924/report.json 为准；写入报告为 artifacts/com15-layout-config-deployed-20260924.json，配置与总线实测为 artifacts/com15-layout-config-acceptance-20260924.json。

外接硬件本轮尚未通过：部署前五个 Modbus 从站已全部超时，部署后地址1、5读取及地址6 FC06开/关和FC03回读均超时；A1/A2原始值均为0，DI1/DI2同为高。需要现场确认外接12V供电及线路，不据此断言所有设备损坏，也不能宣称继电器实际动作成功。MQTT仍未验收。首轮启动后协议接口有连接超时，后续回读成功；短测不替代长期稳定性。

ECM50-A 多网络联网案例（4G Cat.1 联网） ​

1. 硬件规格 ​

1.1 关键 GPIO 分配（摘自 Pin_List） ​

1.2 4G 模组接线（network.json → cellular 段） ​

2. 多模网络配置 ​

2.1 Wi-Fi（STA 优先） ​

2.2 以太网 ​

2.3 4G Cat.1（EC801E-CN） ​

2.4 网络切换逻辑 ​

3. 4G AT 指令交互详解（CellularAdapter 实测流程） ​

3.1 上电与握手时序 ​

3.2 PDP 激活的三重校验 ​

3.3 MQTTS over 4G（Quectel SSL 指令） ​

4. 串口日志判读 ​

4.1 正常上线序列（实测样例结构） ​

4.2 异常日志与处置 ​

5. 网络状态验证 ​

5.1 自动验证（STA/Wi-Fi 通道下执行） ​

5.2 Web 界面验证 ​

6. 部署要点 ​

7. 故障排查 FAQ ​

8. ECM50-A F16R8 外设与 Modbus 配置 ​

8.1 当前配置状态（2026-09-22） ​

8.2 现场接线 ​

8.3 Modbus 设备和当前默认参数 ​

8.4 双 DI 光电检测和设备故障事件 ​

8.5 4–20mA 土壤温度和水分 ​

8.6 本板继电器灯控与 MQTT ​

8.7 首次部署验证记录（r2 历史版本） ​

8.8 2026-09-22 现场问题修复（r3 当前版本） ​

2026-09-24 设备大屏布局及现场配置更新 ​

ECM50-A 多网络联网案例（4G Cat.1 联网）

1. 硬件规格

1.1 关键 GPIO 分配（摘自 Pin_List）

1.2 4G 模组接线（`network.json` → `cellular` 段）

2. 多模网络配置

2.1 Wi-Fi（STA 优先）

2.2 以太网

2.3 4G Cat.1（EC801E-CN）

2.4 网络切换逻辑

3. 4G AT 指令交互详解（CellularAdapter 实测流程）

3.1 上电与握手时序

3.2 PDP 激活的三重校验

3.3 MQTTS over 4G（Quectel SSL 指令）

4. 串口日志判读

4.1 正常上线序列（实测样例结构）

4.2 异常日志与处置

5. 网络状态验证

5.1 自动验证（STA/Wi-Fi 通道下执行）

5.2 Web 界面验证

6. 部署要点

7. 故障排查 FAQ

8. ECM50-A F16R8 外设与 Modbus 配置

8.1 当前配置状态（2026-09-22）

8.2 现场接线

8.3 Modbus 设备和当前默认参数

8.4 双 DI 光电检测和设备故障事件

8.5 4–20mA 土壤温度和水分

8.6 本板继电器灯控与 MQTT

8.7 首次部署验证记录（r2 历史版本）

8.8 2026-09-22 现场问题修复（r3 当前版本）

2026-09-24 设备大屏布局及现场配置更新