Rung Reader
Finds the false condition keeping an Allen-Bradley PLC output off, then has a local model explain it.
Archived
Description
When a line faults and the controls engineer who knows the program is off shift, someone has to trace the ladder logic back from the output that will not energize. The intended users are electrically qualified operators and reliability staff, who can act on a diagnosis but find interlocked logic hard to trace under pressure. Rung Reader parses the L5X export, reads the tags the target depends on, and reports the first false condition along with any stale or unreadable values. A local model then restates that finding in at most two sentences.
Block diagram
- L5X export
- Parser
- Rung walker
- LLM narrator
- CLI output
Decisions
The walker decides and the model only narrates
In an early spike a larger local model gave the wrong meaning for XIC, one of the most basic ladder instructions. So the trace is computed by pure functions over the parsed L5X, and the model receives only the computed facts. The prompt forbids adding reasoning or suggesting operator actions, and the reply is cut to two sentences in code. The narrator can still drift: the default model sometimes labelled fresh values as stale, and the eval harness that would have measured this was never built.
Parallel branches: fewest false conditions first
When every branch of a parallel group is false, the walker reports the branch with the fewest false conditions. The count weighs every condition the same, so a branch held off by one safety interlock ranks ahead of a branch held off by two routine permissives. The report shows where to look, and a person decides what to change. Tied branches are all returned in a tied_branches field for a person to judge. A missing tag value raises TagMissingError instead of defaulting to false, because a default of false would let a real fault pass as a clean trace. The cost is that an incomplete tag snapshot stops the trace.
Fall back to stale values when a PLC read fails
The tag resolver keeps the last good value for each tag in a cache that is written to disk atomically. If a read fails, cached tags come back marked stale with their timestamp, uncached tags come back as errors, and the CLI prints both markers. Driver failures use their own exception type so a broad KeyError handler in the walker cannot swallow them. The operator still gets an answer during a network drop, but has to read the stale markers before trusting it.
Errata
- Work stopped at M5 (0.5.0). The HTTP API, SOP retrieval, anomaly watcher and web UI in the roadmap were never built.
- The live-PLC integration test targets Studio 5000 Logix Emulate, but no run against the emulator is recorded. Tag reads are tested against the mock driver.
- When Ollama is unreachable, the explain command exits with an error and does not print the trace. The trace command needs no model.
Revision history
| Version | Changes |
|---|---|
| 0.5.0 | LangGraph explainer on local Ollama, an explain command with JSON output, and an on-premises-only model router. |
| 0.4.0 | Live tag resolver over pycomm3 with a mock driver, a stale-value cache and the trace command. |
| 0.3.0 | Deterministic rung walker with parallel-branch evaluation, plus an L5X diff. |
| 0.2.0 | Add-On Instruction extraction and alias chain resolution. |
Allen-Bradley, Studio 5000 and Logix are trademarks of Rockwell Automation. Rung Reader is not affiliated with Rockwell Automation.