diff --git a/eqpalg/eqpalg_readme.md b/eqpalg/eqpalg_readme.md new file mode 100644 index 0000000..bc2b950 --- /dev/null +++ b/eqpalg/eqpalg_readme.md @@ -0,0 +1,251 @@ +# eqpalg — 设备算法监控进程 + +## 概述 + +eqpalg（**Eq**uipment **P**rocess **Alg**orithm）是 EIS 系统中的核心设备监控与报警引擎。它基于宝信 PACE 平台构建，通过 ICE 中间件与系统内其他进程通信，从 iHyperDB 实时数据库和共享内存获取工业现场数据，根据数据库中配置的规则对设备运行状态进行实时监控、统计分析和报警。 + +## 进程架构 + +eqpalg 以 **3 个子进程** 的形式运行，通过 ICE 通信协作： + +| 进程名 | ProcessType | 功能 | +|--------|-------------|------| +| `eqpalg-mon` | kMon | **监控进程** — 实时读取共享内存数据，周期性执行所有启用的规则，产出实时报警；同时维护共享内存缓存和数据库时间戳 | +| `eqpalg-cron` | kCron | **定时任务进程** — 按固定周期（默认24小时）查询 iHyperDB 历史数据，执行统计分析（如置信区间更新、样本累积） | +| `eqpalg-task` | kTask | **单次执行进程** — 响应用户在页面上发起的一次性分析任务，从 iHyperDB 拉取指定时间范围的历史数据，运行算法并返回结果 | + +### 关键依赖 + +- **ICE** — 进程间通信（接收电文、转发请求） +- **DB2** — 存储规则配置、报警记录、样本数据和统计结果 +- **iHyperDB** — 工业实时/历史数据库，存储设备 tag 点数据 +- **共享内存（SHM）** — 实时数据的低延迟访问通道 +- **Boost** — 通用工具库（filesystem, serialization, stacktrace 等） +- **dlib / mlpack / Armadillo / Eigen3** — 机器学习与数值计算库 +- **nlohmann/json** — JSON 解析 + +## 核心工作流 + +``` + ┌─────────────┐ + │ DB2 (配置) │ + └──────┬──────┘ + │ 读取规则配置 + ▼ + ┌────────────────────────┐ + │ AlgorithmManager │ + │ (构建所有规则实例) │ + └───────────┬────────────┘ + │ + ┌─────────────┼─────────────┐ + ▼ ▼ ▼ + ┌──────────┐ ┌──────────┐ ┌──────────┐ + │eqpalg-mon│ │eqpalg-cron│ │eqpalg-task│ + └────┬─────┘ └────┬─────┘ └────┬─────┘ + │ │ │ + 共享内存(实时) iHyperDB(历史) iHyperDB + │ │ │ + ▼ ▼ ▼ + ┌─────────────────────────────────────┐ + │ threads::Manager │ + │ (多线程调度，每个 TaskSeq 一个线程) │ + └──────────────┬──────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────┐ + │ HandlerExec │ + │ (单个线程的执行句柄，管理规则集) │ + └──────────────┬──────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────┐ + │ AlgBase │ + │ (具体算法实例的执行) │ + └──────────────┬──────────────────────┘ + │ + ▼ + ┌──────────────┐ + │ 报警 / 统计结果 │ + └──────────────┘ +``` + +### ICE 电文接口 + +进程通过 `EqpAlgICEI` 接收三类 ICE 调用： + +1. **SendDataShort(eventNo, seq)** — 处理控制指令： + - `eventNo=99999`：规则增删改查/执行指令（mon 进程转发给 cron） + - `eventNo=11111`：收到外部报警信息，转发报警 + - `eventNo=22222`：更新规则的上下限阈值 + +2. **SendDataLong** — 复杂数据接口（当前未实现具体逻辑） + +3. **TimeNotify(eventNo)** — 定时任务触发： + - `eventNo=1`：更新设备运行状态 + - `eventNo=2`：更新规则统计的共享内存数据 + - `eventNo=5`：定期向 dsm 进程推送最新 ruleId 列表和共享内存统计 + +### 规则生命周期 + +``` +页面/外部发起 → ICE电文(JSON) → AlgorithmManager.dispose() + │ + ┌────────┬────────┬─────────┼──────────┬────────┐ + ▼ ▼ ▼ ▼ ▼ ▼ + kCreate kDelete kUpdate kEnable kReset kExec + (创建) (删除) (更新) (启/停用) (重置) (单次执行) +``` + +- 所有规则操作均通过 JSON 电文驱动 +- 创建/更新时同步维护 DB2 表 `T_RULE_CFG` 和 `T_RULE_RECORD_TIME` + +## 算法体系 + +所有算法类继承自 `AlgBase`，`AlgBase` 提供： +- 表达式解析引擎（基于 `mix_cc::matheval`） +- iHyperDB/共享内存双数据源 +- 执行间隔控制、心跳日志、前提条件判断 +- 报警/正常数据保存、共享内存统计更新 + +### 当前使用的算法（18种） + +| algId | 类名 | 名称 | 说明 | +|-------|------|------|------| +| 1 | `ExpBase` | 实时逻辑判断 | 对监控变量做布尔逻辑判断，触发报警 | +| 2 | `ExpBase` | 监控变量-上下限 | 检测变量是否超出上下限区间（含在线自学习） | +| 3 | `ExpBase` | 动作反馈-逻辑判断 | 当触发动作条件后，监测反馈是否在规定时间内到位 | +| 4 | `ExpBase` | 动作反馈-上下限 | 触发动作后，监测反馈变量是否回到合理区间 | +| 5 | `ExpBase` | 上下限-保持时间 | 变量超出区间并持续超过设定时间才报警 | +| 6 | `ExpTimes` | 运行时间累计 | 累计设备/部件运行时长，超阈值报警 | +| 7 | `ExpTimes` | 出现次数累计 | 累计事件发生次数，超阈值报警 | +| 8 | `TrendSlope2` | 斜率监控 | 监测变量变化趋势（斜率），检测过快变化 | +| 9 | `Roller2` | 离群检测(百分比) | 同组多变量中检测某个值偏离群体百分比 | +| 10 | `FaultCode` | 故障代码解析(整体) | 将数字故障码与 DB2 字典表比对，解析为可读故障信息 | +| 11 | `FaultCode` | 故障代码解析(按位) | 按位解析数字故障码，适用于组合故障信号 | +| 12 | `ExpSample2D` | 多项式拟合 | Cron 累积 XY 样本，Mon 用拟合多项式做预测与偏差检测 | +| 13 | `ExpSample2D` | 皮尔逊相关性 | Cron 累积样本计算相关系数，Mon 检测相关性偏离 | +| 14 | `TrendSlope3` | 趋势检测增强版 | 斜率监控的改进版本 | +| 15 | `GlitchDetection` | 毛刺检测 | 检测数据中突发的尖峰/毛刺信号，可联动 Python 算法 | +| 16 | `Roller3` | 离群检测(百分比v3) | 离群检测的改进版本 | +| 17 | `ExpBound` | 数据超限幅值 | 检测变量是否超出设定的误差限和警告限 | +| 18 | `Roller3` | 离群检测(实际值v3) | 基于实际值阈值的离群检测 | + +### 已弃用的算法（位于 `.do_not_use/`） + +包括但不限于：样板曲线检测、CPC 检测、区间分布统计、波形监控、DTW 动态时间规整、一类 SVM 异常检测、KRR 核岭回归、FFT 频谱统计等实验性算法。这些代码保留供参考但不再参与编译。 + +## 表达式系统 + +基于 `mix_cc::matheval` 数学表达式解析引擎，规则配置中可书写数学表达式来引用 tag 变量和内置函数： + +- **变量语法**: `m{tagN}` — 引用第 N 个监控 tag 点（如 `m{tag1}`），`s{tagN}` — 动作开始时的快照值 +- **自定义带状态函数**（`StatExp::FunVars`）: + - `KeepT(N, T)` — tagN 为真后保持 T 分钟 + - `KeepC(N)` — tagN 为真后累计次数 + - `RiseEdge(N)` — tagN 的上升沿检测 + - `Detect(N, T)` — T 分钟内检测 tagN 是否为真 +- **hold 函数**: `hold(N, T)` — 将 tagN 保持 T 分钟不变 +- **数学函数**: 标准四则运算、三角函数、log、绝对值等 + +配置格式示例（JSON）： +```json +{ + "exp_str": "m{tag1} > (limit_up_ + 0.251) or m{tag1} < (limit_down_ - 0.251)", + "limit_up_": 800, + "limit_down_": 200, + "hold_time": 5000, + "delay_time": 1000 +} +``` + +## 目录结构 + +``` +eqpalg/ +├── eqpalg.cpp/h # 进程入口，start() 中启动 ICE 服务 +├── eqpalg_icei.cpp/h # ICE 接口实现，处理电文分发 +├── algorithm_manager.cpp/h # 算法管理器：从 DB2 加载规则，协调生命周期 +├── build_algorithm.cpp/h # 算法工厂：algId → 具体算法类实例 +├── alg_base.cpp/h # 所有算法的基类，提供表达式引擎、数据获取等 +├── gb_logger.cpp/h # 全局日志模块 +├── gb_item_memory.cpp/h # 全局内存数据管理 +├── algs/ # 算法实现 +│ ├── exp_base.* # 表达式类算法 (algId 1-5) +│ ├── exp_times.* # 时间/次数累计 (algId 6-7) +│ ├── exp_bound.* # 限幅值检测 (algId 17) +│ ├── exp_sample2D.* # 二维拟合/相关性 (algId 12-13) +│ ├── trend_slope2.* # 斜率监控 (algId 8) +│ ├── trend_slope3.* # 斜率监控增强版 (algId 14) +│ ├── roller2.* # 离群检测 (algId 9) +│ ├── roller3.* # 离群检测 v3 (algId 16,18) +│ ├── fault_code.* # 故障代码解析 (algId 10-11) +│ ├── glitch_detection.* # 毛刺检测 (algId 15) +│ └── null.h # 空算法（未匹配时使用） +├── threads/ # 多线程调度 +│ ├── manager.* # 线程管理器：按 TaskSeq 分配线程 +│ └── handler_exec.* # 单线程执行句柄：管理队列，调度规则 +├── exp_macro/ # 表达式宏（delta/max/min/hold/persist 等） +├── feature_extraction/ # 特征提取（LSM 拟合 / STA 统计 / 分布分析） +├── utility/ # 工具类 +│ ├── alarm_poster.* # 报警推送 +│ ├── alarm_handler.hpp # 报警处理器 +│ ├── build_alarm_info.* # 报警信息构造 +│ ├── condition_monitor.hpp # 条件监控 +│ ├── eqp_stat.* # 设备统计 +│ ├── eqp_status.* # 设备运行状态 +│ ├── ExpModule.* # 表达式模块 +│ ├── HoldTime.* # 保持时间处理 +│ ├── update_data.* # 共享内存数据更新 +│ ├── proxy_py.* # Python 算法代理 +│ ├── StatExp.hpp # 带状态表达式函数 +│ ├── VarsCache.hpp # 变量缓存 +│ └── XorShift128Plus.hpp # 随机数生成器 +├── table_struct/ # DB2 表结构映射（ORM） +├── define/ # 全局定义（枚举、常量、结构体） +├── doc/ # Doxygen 文档 +├── .do_not_use/ # 弃用的算法代码（不参与编译） +└── CMakeLists.txt # 构建配置 +``` + +## 数据流 + +``` + 现场PLC/传感器 + │ + ▼ + iHyperDB (实时/历史数据库) ──← cron/task 查询历史 + │ + ▼ + 共享内存 (实时 tag 数据) ──← mon 实时读取 + │ + ▼ + eqpalg 进程 + │ + ├──→ 报警 → ICE电文 → 其他系统 / 页面展示 + ├──→ 统计结果 → DB2 (T_RULE_RESULT, T_RULE_SAMPLE_*) + └──→ 运行状态 → DB2 (T_RULE_RECORD_TIME, T_EQP_*) +``` + +## 启动流程 + +1. `eqpalg::start()` — 根据模块名确定进程类型（mon/cron/task） +2. 创建 `EqpAlgICEI` 实例 — 注册 ICE 接口 +3. `AlgorithmManager` 构造 — 从 DB2 `T_RULE_CFG` 表读取所有规则配置 +4. `threads::Manager::start()` — 按 `TaskSeq` 分组创建线程 +5. 每个线程创建 `HandlerExec`，根据规则 algId 调用 `build_algorithm()` 创建算法实例 +6. mon 进程额外启动 `mem_cached_thread_` — 以约 19ms 间隔刷新共享内存缓存 + +## 相关进程 + +| 进程 | 关系 | +|------|------| +| **dsm** | eqpalg-mon 定期向 dsm 推送统计数据 | +| **eqpalg-cron** | eqpalg-mon 收到 99999 电文时转发给 cron | +| **RICS** | 同系统内其他设备算法进程 | +| **页面服务** | 通过 ICE 发送规则增删改查指令 | + +## 作者 + +- Cat (null.null.null@qq.com) +- 宝信软件（Baosight Co. Ltd.） +- 版本: 0.1 (2021-09)