网关外设与联动
开发预览
本页依据提交 b1a16cbc 的源码与项目外设系统设计文档整理。PeripheralManager 与 PeriphExecEngine 代码已存在且 API 路由已注册；真实硬件访问依赖编译选项与后端实现（libgpiod / Linux IIO / 模拟后端），x86 开发环境默认使用模拟后端。
1. 概述
不同型号工业网关的硬件配置差异极大（DI 4~16 路、DO 4~8 路、AI 2~4 路不等），引脚功能不能硬编码在代码里。外设系统将物理引脚映射为虚拟外设对象，通过配置文件和 Web/API 动态定义，再由执行规则引擎实现"触发器 → 动作"的自动化联动（如门磁开门 → 亮灯、温度超限 → 启动风扇）。
两个核心模块：
- PeripheralManager（外设配置中心）：外设增删改查、硬件初始化/释放、引脚冲突检测、运行时状态与读写统一入口。
- PeriphExecEngine（外设执行规则引擎）：触发器检测、规则匹配、动作编排执行、结果记录与 MQTT 上报。
关键约束：规则引擎永不直接触碰硬件后端，所有读写都经过 PeripheralManager，保证引脚冲突检测、状态同步、日志审计只有一条路径。
2. 外设类型体系
采用字符串类型编码（对现场工程师更可读），聚焦 7 类工业 I/O：
| 类型 | 典型路数 | 信号特征 | 方向 | 典型负载 |
|---|---|---|---|---|
DI | 4~16 | 光耦隔离，12/24V 干接点/湿接点 | 输入 | 门磁、烟感、按钮、限位开关 |
DO | 4~8 | 继电器或 MOSFET，常开/常闭 | 输出 | 报警器、指示灯、电磁阀 |
AI | 2~4 | 4-20mA / 0-10V 标准信号 | 输入 | 温度/压力/液位变送器 |
AO | 1~2 | 4-20mA / 0-10V 标准信号 | 输出 | 变频器、调节阀门 |
LED | 4 | 低/高电平点亮 | 输出 | 电源/运行/网络/故障指示 |
BUZZER | 1 | 有源/无源蜂鸣器 | 输出 | 本地声光告警 |
WATCHDOG | 1 | 需周期性喂狗脉冲 | 输出 | 硬件看门狗芯片 |
外设运行时状态机：DISABLED(0) → ENABLED(1) → INITIALIZED(2) → RUNNING(3)，异常为 ERROR(4)。
3. 外设配置参数
每个外设由 id、name、type、enabled、channel、pins（物理引脚数组）和 params（类型特定参数）组成。各类型 params 要点：
3.1 DI 数字输入
| 参数 | 默认 | 说明 |
|---|---|---|
pullUp | true | 内部上拉 |
activeLow | false | 低电平有效（光耦输出反相时置 true） |
debounceMs | 30 | 软件消抖时间（连续两次采样一致才确认变化） |
reportOnChange | true | 状态变化时上报 |
triggerEdge | both | 触发边沿：rising / falling / both |
3.2 DO 数字输出
| 参数 | 默认 | 说明 |
|---|---|---|
initialState | 0 | 初始电平（0=断开 / 1=闭合） |
activeLow | false | 低电平驱动（继电器模块常见低电平触发） |
outputType | relay | 输出类型：relay / mosfet |
pulseMs | 0 | 脉冲输出时长（0=持续，>0=自动回弹，用于电磁阀点动） |
3.3 AI 模拟输入
| 参数 | 默认 | 说明 |
|---|---|---|
signalType | 4-20mA | 信号类型：4-20mA / 0-10V / 0-20mA / 0-5V |
rawMin / rawMax | 0 / 4095 | ADC 原始值范围 |
engMin / engMax | 0 / 100 | 工程值范围（线性映射） |
unit | "" | 工程单位（°C / MPa / m …） |
sampleIntervalMs | 1000 | 采样周期 |
deadband | 0.0 | 死区（变化超过死区才上报，抑制抖动） |
wireFaultDetect | false | 断线检测（4-20mA 低于 3.6mA 视为断线） |
工程值线性映射：eng = engMin + (raw - rawMin) / (rawMax - rawMin) × (engMax - engMin)。
3.4 AO 模拟输出
| 参数 | 默认 | 说明 |
|---|---|---|
signalType | 4-20mA | 信号类型 |
engMin / engMax | 0 / 100 | 工程值范围 |
defaultValue | engMin | 上电默认输出值 |
slewRateMs | 0 | 输出缓变时间（防止阀门冲击） |
3.5 LED / BUZZER / WATCHDOG
- LED：
role角色（power上电常亮 /running心跳 1Hz 闪烁 /network反映网络连接 /fault由系统故障驱动）。 - BUZZER：
activeLevel有效电平、buzzerType（active有源 /passive无源）、defaultPattern（off/on/beep短鸣 3 声 /alarm急促连续鸣叫）。 - WATCHDOG：
feedIntervalMs（喂狗周期，必须小于硬件看门狗超时）、feedPulseMs、mode（toggle翻转 /pulse固定脉冲）。主线程挂死时硬件看门狗超时自动复位网关，是工业现场"死机自愈"的关键手段。
3.6 配置示例
{
"id": "ai_temp", "name": "锅炉温度变送器", "type": "AI",
"enabled": true, "channel": 0, "pins": [0],
"params": { "signalType": "4-20mA", "rawMin": 0, "rawMax": 4095,
"engMin": 0, "engMax": 200, "unit": "°C",
"sampleIntervalMs": 1000, "deadband": 0.5, "wireFaultDetect": true }
}外设配置存储在 config/peripherals.json，写入采用"先写 .tmp 再 rename"的原子方式；文件含 version（格式版本）与 _templates（外设模板，批量部署时快速填充参数）。
4. 外设执行规则引擎
规则由**触发器（triggers，OR 逻辑）和动作（actions，按序执行）**组成，配置存储在 config/periph_exec.json。
4.1 触发器类型
| 类型 | 输入来源 | 工业场景 |
|---|---|---|
| 平台触发（0） | MQTT / 云端命令 | 远程开关 DO、参数下发 |
| 定时触发（1） | 本地时钟（间隔 / 每日定点） | 周期上报、定时开关泵 |
| 事件触发（4） | DI 变化、系统事件 | 门磁开门 → 亮灯、烟感 → 报警 |
| 轮询触发（5） | 主动读 AI/Modbus（按 pollIntervalMs 检查） | 温度超限 → 启动风扇 |
比较操作符 0~9：EQ / NE / GT / LT / GE / LE / IN_RANGE / OUT_RANGE / CONTAINS / NOT_CONTAINS。DI 变化会自动发布 ds:<periphId> 事件；规则执行完成会发布 mc:<ruleId>:success/failed 事件，支持规则链式联动。
4.2 动作类型
| 类型 | 名称 | 说明 |
|---|---|---|
| 0/1/2/3 | DO 置高/置低/翻转/闪烁 | 闪烁参数 "次数,间隔ms" |
| 4 | AO 设值 | 工程值输出 |
| 5 | LED 控制 | "on" / "off" / "blink" |
| 6 | 蜂鸣器 | "off" / "on" / "beep" / "alarm" |
| 10 | 发送指令 | MQTT 上报，$value 为触发值占位符 |
| 15 | 命令脚本 | PERIPH / DELAY / LOG / MQTT 多行顺序执行 |
| 21/22/23 | 触发事件 / 启用规则 / 禁用规则 | 规则联动 |
| 30 | 系统重启 | 强动作，仅建议平台触发使用 |
4.3 规则示例
{
"id": "exec_1717392000",
"name": "烟感报警联动",
"enabled": true,
"execMode": 0,
"triggers": [
{ "triggerType": 4, "triggerPeriphId": "di_smoke",
"operatorType": 0, "compareValue": "1", "eventId": "ds:di_smoke" }
],
"actions": [
{ "actionType": 0, "targetPeriphId": "do_alarm" },
{ "actionType": 6, "targetPeriphId": "buzzer_alarm", "actionValue": "alarm" },
{ "actionType": 10, "actionValue": "{\"alarm\":\"smoke\"}" }
],
"reportAfterExec": true
}execMode：0=异步（默认，提交执行线程不阻塞调度）、1=同步（动作间按 syncDelayMs 延迟，含系统重启的规则强制同步）。同一规则运行中会跳过重复触发（防重入）。
5. 安全约定与可靠性设计
- 出厂安全模板：外设与规则默认
enabled: false，不会在未知接线环境中自动动作。 - 导入后默认禁用：批量导入的外设与规则强制禁用，需人工确认后逐个启用。
- 引脚冲突检测：同一引脚不能被两个启用的外设占用；禁用外设可保留引脚定义，重新启用时再校验。
- 删除保护：被规则引用的外设删除时会被拒绝并提示先解除引用。
- 恢复前自动备份：恢复备份前先快照当前状态，保证可回滚。
- 执行审计：规则执行结果环形缓存（最近 100 条）并记录日志。
- 强动作限制：涉及继电器/电磁阀/重启的动作必须先"执行一次"手动验证再启用。
6. 配置管理与批量部署
外设与规则支持整体导出/导入，典型批量部署流程：
- 首台网关配置外设与规则，逐个启用验证。
- 导出全部配置（
GET /api/system/config及各模块 export 接口）。 - 同型号网关逐台导入，重启后外设/规则加载（默认禁用）。
- 现场逐个启用并验证 I/O；异常时恢复备份回滚。
7. API 入口
外设管理（9 个端点）与外设执行规则（9 个端点）的完整接口表见 API 第 12、13 节。
8. 实现现状
- PeripheralManager / PeriphExecEngine 代码存在且路由已注册；外设与规则的数据模型、触发器/动作语义与 FastBee-Arduino（ESP32 固件）保持一致，便于生态统一。
- 硬件后端：
LibgpiodBackend（数字量，真实网关）、IioBackend（模拟量，Linux IIO 子系统）、SimulatedHwBackend（开发/CI/单元测试，可注入 DI/AI 状态并断言 DO/AO 输出）。 - 平台触发依赖 MQTT 反向控制链路，该链路当前未接通（见概览第 8 节）；定时/事件/轮询触发为本地逻辑。
- 早期通道式
GpioManager（/api/gpio/*）保留可用，外设管理将逐步成为唯一权威配置源。