industrial-aiops

<!-- mcp-name: io.github.industrial-aiops/iaiops -->

# Industrial-AIOps

**English** · [中文](README.zh-CN.md)

**Governed, vendor-neutral industrial data tap + intelligent troubleshooting for AI agents — read-first tools across 14 field protocols in this package (17 line-wide with the energy edition): OPC-UA (incl. Historical Access + tag auto-discovery), Modbus-TCP/RTU (byte-order auto-detect + vendor templates), S7comm, Mitsubishi MC, Omron FINS (stdlib-only client), MTConnect, MQTT/Sparkplug B (full decode), EtherNet/IP (Rockwell/Allen-Bradley Logix), EtherCAT (pysoem/SOEM), PROFINET (DCP), SECS/GEM (HSMS fab), HART-IP (process instrumentation), BACnet/IP (building), and IO-Link (master JSON integration), plus two vendor-REST **read-only** layers above the field bus — a **BAS supervisory-controller layer** (Johnson Controls Metasys / Tridium Niagara, sitting above the BACnet field connector, building edition) and an **Ignition Gateway MES/SCADA read layer** (Inductive Automation Ignition's HTTP/Gateway web API — module health, tag browse/read, alarms, tag-history — factory edition) — plus an AI downtime root-cause copilot (with a `downtime_triage` composer), conservative baseline learning, ISA-18.2 alarm-flood analysis, historian READ integration (RCA pre-incident evidence), a legacy PLC program explainer (ST/AWL/L5X), nine per-industry editions (fab / factory / process / building / water / warehouse / clinical / renewables / plcnext) each carrying its own read-only advisory checks (SPC, PID control-loop, AHU economizer, line bottleneck, medical-gas, disinfection-CT …), open-format export (`iaiops export` CSV/SQLite/Parquet) with a Prometheus/Grafana bridge, data-quality watchdog, UNS governance, OEE/downtime, asset-inventory, and 信创 (TDengine/IoTDB historian sinks + 防护指南/等保2.0/IEC 62443 compliance mapping, report & evidence bundle). The energy edition (变电/电力: IEC-104 / DNP3 / IEC-61850) ships separately as [`iaiops-energy`](https://github.com/industrial-aiops/industrial-aiops-energy).**

Industrial-AIOps is the OT member of the [industrial-aiops](https://github.com/industrial-aiops) org. It is a **factory-level, vendor-neutral, governed data tap** that lets an AI agent safely *read* industrial control systems across many field protocols, plus a **cross-protocol intelligence layer** that localizes "no data" breaks, analyzes alarm floods (ISA-18.2), scores data trustworthiness, ranks unhealthy tags, computes OEE / categorizes downtime, builds an active asset register, auto-discovers OPC-UA tags into a semantic asset model, and — the flagship — runs an **AI downtime root-cause copilot** that correlates the evidence into an **evidence-cited, advisory** verdict. Read-first by design; the few write/command paths are OT-dangerous and gated by MOC discipline. Every tool runs through a vendored governance harness (audit / budget / risk-tier / undo).

> **v0.18.0 — validation status (honest).** Grouped by *how strongly* each path is
> verified, because "tested" spans a real container round-trip and a synthetic fixture and
> the difference is what an evaluator needs. Every `待核实` below is hardware-gated, not
> forgotten — see [issue #28](https://github.com/industrial-aiops/industrial-aiops/issues/28).
>
> **Verified against real libraries / containers / in-process servers.** Pure analysis and
> the **OPC-UA** path run against a real in-process `asyncua` server — including
> **certificate message security** (a `Sign` / `SignAndEncrypt` matrix) and **Alarms &
> Conditions**. **IoTDB** and **TDengine** do a live container write→read round-trip. The
> **HART** command codec is checked against `hart-protocol`. **Modbus-RTU** round-trips over
> a real serial link (a `socat` PTY pair + a `pymodbus` RTU server,
> `tests/test_modbus_rtu_live.py`), exercising actual RTU framing. The **BACnet/IP** read
> path does a genuine Who-Is discover + present-value read against a real `bacpypes3`
> virtual device on a two-IP subnet in a Linux container (`tests/test_bacnet_live.py`),
> through the real async BAC0 (2024+) stack. **Phoenix Contact PLCnext vPLC** is
> *route*-verified over an in-process `asyncua` server reproducing the `Arp.Plc.Eclr` GDS
> address space plus a Modbus-TCP process-data block (`tests/test_plcnext_route.py`).
>
> **Mock-verified — the protocol logic is exercised, no real device is.** **Omron FINS**
> (in-repo mock UDP/TCP responder, `tests/test_fins.py`), **IO-Link** (in-process mock
> master, both JSON dialects, `tests/test_iolink.py`), the **BAS controller** layer (mock supervisory controller in both vendor
> dialects — Metasys OpenBlue REST and Niagara oBIX/REST), the **Ignition Gateway** read
> layer (mock Gateway, both `webdev` / `gateway` flavors), **EtherNet/IP PCCC** for
> PLC-5 / SLC-500 / MicroLogix / Micro800 (mocked pycomm3 `SLCDriver`), **CC-Link /
> CC-Link IE Field** via master-PLC SLMP, **MTConnect** long-poll streaming (synthetic
> advancing / caught-up / reset agents; static XML fixtures elsewhere), **Sparkplug B**
> incl. DataSet/Template decode (synthetic Tahu-schema protobuf payloads), and mocked
> clients for **S7 / MC / EtherNet-IP / SECS-GEM**.
>
> **Pure software, fully covered by the suite.** The `IAIOPS_NO_EGRESS` posture
> gate and the return envelope (0.17.0–0.18.0).
>
> **Still `待核实` — preview, not hardware-verified.** Live Omron PLCs (incl. banked-EM
> access); live IO-Link master datapoint paths; BACnet write / COV / trend on live HVAC;
> HART-IP wire transport against a live gateway; **EtherCAT** (no software simulator
> exists — Linux + root + a real bus only); physical Modbus-RTU RS-485 devices; live
> PLCnext hardware; a live CC-Link master; real PLC-5 / SLC-500 / MicroLogix / Micro800;
> a real MTConnect agent's long-poll behaviour; a live MQTT broker for Sparkplug;
> third-party / vendor OPC-UA servers, certificate-*trust* enforcement and X509 *user*
> tokens; third-party A&C servers; live Metasys / Niagara controllers (incl. native
> oBIX-XML encoding) and live Ignition gateways (exact API version / paths).
>
> (The energy edition's IEC-104 / DNP3 / IEC-61850 validation lives in the
> [`iaiops-energy`](https://github.com/industrial-aiops/industrial-aiops-energy) repo.)
> See *Safety*.

## Why

OT is exactly where you want an agent on a tight leash: read first, never blind-write. Industrial-AIOps is the **safe, neutral read wedge** — one package, one MCP server, many protocols — with governance and an intelligence layer that turns raw reads into actionable diagnoses.

## 🧪 测试与共创 / Beta testing & co-creation

**我们在找现场测试伙伴。** 软件里能验证的我们都验证了（真实 in-process 服务器、真实协议库、Docker 容器 loopback）——剩下的 `待核实` 清单只有真设备能回答：物理 Modbus-RTU（RS-485）、EtherCAT 从站、HART 网关、在线 BACnet 楼宇设备、在线 Metasys/Niagara BAS 控制器、在线 Ignition 网关、国产 PLC（汇川/信捷）、真机 PLCnext、真实变电站 RTU/IED、欧姆龙 FINS 真机、IO-Link 主站。如果你是 OT 工程师、系统集成商或工厂团队，手上有任何这类设备：装上 `iaiops`，对你的设备跑一遍 `iaiops doctor`，把结果告诉我们。**经你验证的设备会署名写进支持矩阵**；现场反馈的问题我们优先分诊；功能可以通过 GitHub Issues/Discussions 直接共创。

**We're looking for field-testing partners.** Everything software-verifiable has been verified; what's left on the honest `待核实` list only real equipment can answer — physical Modbus-RTU (RS-485), EtherCAT slaves, HART gateways, live BACnet HVAC, live Metasys/Niagara BAS controllers, live Ignition gateway, domestic PLCs (Inovance/Xinje), live PLCnext, substation RTUs/IEDs, live Omron FINS PLCs, IO-Link masters. If you're an OT engineer, integrator, or factory team with access to any of these: install `iaiops`, run `iaiops doctor` against your gear, and tell us what happened. **Verified-equipment reports get credited in the support matrix**, field-reported issues get fast triage, and features are co-designed in the open via GitHub Issues/Discussions.

👉 **参与入口 | Start here: [#28 — 招募现场测试伙伴 | Call for field-testing partners (v0.10.0)](https://github.com/industrial-aiops/industrial-aiops/issues/28)** (pinned)

---

## Consolidated capability matrix

| Protocol | Tool | Operation | R/W | risk_tier | Returns (key fields) |
|----------|------|-----------|:---:|:---------:|----------------------|
| OPC-UA | `opcua_server_info` | server status | R | low | state, product_name, namespaces |
| OPC-UA | `opcua_browse` | browse node tree | R | low | [{node_id, browse_name, depth}] |
| OPC-UA | `opcua_read_node` | read one node | R | low | value, datatype, source_timestamp, good |
| OPC-UA | `opcua_read_many` | batch read | R | low | [{node_id, value, ...}] |
| OPC-UA | `opcua_subscribe_sample` | bounded sample | R | low | {collected, samples[]} |
| OPC-UA | `opcua_read_alarms` | alarm surfacing | R | low | {active_alarms[], active_count} |
| OPC-UA | `opcua_read_history` | Historical Access (HDA) | R | low | {supported, count, values[]} |
| OPC-UA | `opcua_diagnose_connection` | connection triage | R | low | {verdict, checks[]} |
| OPC-UA | `opcua_discover_tags` | tag auto-discovery → semantic asset model | R | low | {tag_count, assets[], naming_report} |
| OPC-UA | `opcua_health_summary` | threshold classify (was `health_summary`¹) | R | low | {overall, counts, offenders[]} |
| OPC-UA | `opcua_anomaly_scan` | stddev outliers (was `anomaly_scan`¹) | R | low | {mean, stddev, outliers[]} |
| Modbus | `modbus_read_holding` | FC03 | R | low | {raw_registers, decoded[]} |
| Modbus | `modbus_read_input` | FC04 | R | low | {raw_registers, decoded[]} |
| Modbus | `modbus_read_coils` | FC01 | R | low | {bits[]} |
| Modbus | `modbus_read_discrete` | FC02 | R | low | {bits[]} |
| Modbus | `modbus_detect_byte_order` | byte/word-order auto-detect | R | low | {best_order, candidates[]} |
| Modbus | `modbus_list_templates` | vendor register templates | R | low | {templates[]} |
| Modbus | `modbus_apply_template` | decode block via template | R | low | {values:{name: engineering_value}} |
| Modbus | `modbus_health_summary` | threshold classify | R | low | {overall, counts, offenders[]} |
| S7comm | `s7_cpu_info` | CPU id + run/stop | R | low | {cpu_status, cpu_info} |
| S7comm | `s7_read_area` |