Ring — Engineering Reference#
The engineering book of Ring's three-audience documentation set. It is written for the person who has to change Ring without breaking a plant: read the code, understand why a seam is where it is, and know which document is authoritative for the facts that move.
Ring is the Windows HMI for a corrugator starch-adhesive glue kitchen. It speaks EtherNet/IP to an Allen-Bradley CompactLogix 1769-L36ERM through libplctag and keeps its own history in a local SQLite database. From the 2026-09-08 write-enabled cutover it writes to that controller for real.
How to use this book#
1. This book explains; the authorities decide. Ring's repository names one
authoritative document per question in docs/INDEX.md. Where
a fact is volatile — a test total, a tag count, a commissioning status, a
procedure to run on cutover night — this book links rather than restates.
Chapters here go deep on mechanism: what the code does, why the seam is
there, and what breaks if you move it.
2. Every claim here was read out of the code. This repository has a
documented history of confident prose that was wrong; an audit found roughly
two-thirds of its in-code TODOs and doc-state claims to be phantom
(CLAUDE.md). So: file paths are cited inline, claims
that could not be verified are marked "unverified", and no volatile number is
copied into prose. If this book and the code disagree, the code wins and
this book is the thing that should be fixed.
3. Read chapter 04 before you touch Ring/Services/PLC/. It is the
safety-critical chapter and the reason the rest of the book exists.
4. You do not need both backgrounds. This book is written so a controls
engineer who has never seen WPF and a WPF developer who has never seen a PLC can
both follow it. Every term from either world is defined in
chapter 01 §1.0, Vocabulary
before it is used. Read that section first if either half of the sentence
"a WPF DispatcherTimer reads a snapshot of a CompactLogix UDT member" is
unfamiliar.
5. Dates matter. Claims that depend on the cutover say so explicitly. A
sentence written in the present tense about a pre-cutover Ring — "every
controller write is suppressed" — stops being true the day
PlcSettings.ReadOnlyMode is flipped.
Chapters#
| # | Chapter | What it covers |
|---|---|---|
| 01 | System Overview | What Ring is, the plant and its tanks, solution and directory layout, tech stack, which controller is which |
| 02 | Runtime Architecture | Boot sequence and its load-bearing ordering, configuration load order, degraded startup, threading and dispatcher model, how the subsystems fit together |
| 03 | PLC Communications — the read path | libplctag usage, the tag reader, seven pollers plus the timers outside them, snapshots and caches, index maps, heartbeat and connection state, clock-skew and comm logging, demo mode |
| 04 | The Write Path and Safety Model | The safety chapter. Every gate, with the code that implements it; the write-surface register as the pinning mechanism; commissioning holds including the two hard-closed ones; the setpoint queue, echo guard and evidence journal; what a new writer owes |
| 05 | Data and Persistence | SQLite configuration, repository shape, migrations, backup/restore contract, the maintenance latch and writer quiesce, historian, audit journals, exports |
| 06 | UI Architecture | The two-tier WPF reality, the shell and hosted-screen pattern, screen areas, resource dictionaries and the 13-locale rule, converters, touch conventions, the shared-handler rule |
| 07 | Services Catalog | A guided index to everything under Ring/Services/ — one verified paragraph per service, grouped by concern |
| 08 | Testing and Quality | Suite mechanics, why parallelism is off, the project-membership guard, the production gate, encoding rules, worktree conventions |
| 09 | Build, Deploy, Release | Build mechanics and their traps, the release package shape, install/rollback/remote access (links to the runbooks) |
| 10 | Extending Ring | Cookbook: a screen, a service, a localized string, a config key, a database table — and the one sanctioned way to add a PLC writer |
| 11 | Diagnostics and Field Triage | Symptom-indexed index into the rest of this book: what to check first for a frozen screen, a flapping link badge, a write that silently does nothing, a stuck Hold, a station that will not launch, and more |
Corrections this book makes to existing documents#
Per the "verify, then write" rule, where this book once found existing prose to
disagree with the code, it said so in place rather than smoothing it over. Four
such corrections have since been folded back into the documents they named —
ARCHITECTURE.md §§2–4 and docs/CONFIG_AND_STARTUP.md §1 now state the
current facts directly, so this table no longer carries them (re-verified
2026-09-01). Two still stand:
| Document | Claim | What the code says |
|---|---|---|
PlcWriteEndpointGuard's own class doc |
describes itself as the last gate, after the heartbeat and demo checks | In PlcTagWriter.WriteCore the order is ReadOnly → Demo → Endpoint → Heartbeat, for a documented diagnostics reason (PlcWriteEndpointGuard.cs:40-44, verified against PlcTagWriter.cs:143-208). ch. 04 |
README.md (repository root) |
"13 tanks (1 mix + 6 storage + 6 doser)" (README.md:13) |
That is TankRoster.IndianaPreset(), the target; the shipped fallback is 4 storage + 4 dosers, and the mix tank is deliberately outside the roster. ch. 01 |
Neither is safety-critical on its own. Both are the kind of drift that makes the next reader distrust the parts that are. A table that only ever grows is also a sign this book has stopped checking whether its own corrections got applied — the four retired rows above are proof that re-verifying periodically is worth doing.
Sibling books#
Part of the three-book documentation set indexed at
docs/manual/README.md:
- Operator Manual — day-to-day plant use.
- Sales & Commercial Guide — the same system at commercial altitude.
Per the set's convention, every chapter here ends with a "Verified against" list naming the files its claims were read from. Keep those lists honest when you change a chapter; they are how the next reader checks this book the way this book checked the others.
The documents this book defers to#
| Question | Authority |
|---|---|
| Which document is authoritative at all? | docs/INDEX.md |
| Are we allowed to enable writes? | docs/production-readiness/WRITE_ENABLE_READINESS_2026-07-26.md |
| How is the cutover run? | CUTOVER_RUNBOOK.md |
| What does a config key mean? | docs/reference/plc/APPSETTINGS_REFERENCE.md |
| How does Ring boot and where do settings live? | docs/CONFIG_AND_STARTUP.md |
| What are the controller facts older docs get wrong? | docs/PLC_FACTS.md |
| What is still held for a controls engineer? | docs/production-readiness/CONTROLS_SIGNOFF_RECORD.md |
| Test totals, gate timings | artifacts/production-gate/production-gate-summary.json (generated) |
| Tag audit / dead-read counts | scripts/code-tag-audit.md (generated) |
A note on the links in this table, and in this book generally. Most of
them are repository paths — docs/production-readiness/*.md, CLAUDE.md,
CONTRIBUTING.md, ARCHITECTURE.md, CUTOVER_RUNBOOK.md. In the published
web and PDF editions those paths resolve to the repository's GitHub remote,
which most readers of a distributed PDF cannot open. Where that is true, the
path itself is the citation — it names the authoritative file precisely so
you can find it in a checkout even when the link does not resolve for you.
And the two documents that set the norms this book follows:
ARCHITECTURE.md and
CONTRIBUTING.md.