wrps-demo-kit/01-design/README.md

01-design — the design authority

Everything downstream is built against these documents and checked back to them. The PLC code implements them; the register map is derived from them; the HMI displays what they define.

The documents

Document	What it is	Status
00-origin/scada-ai-usecase-pump-scheduling.md	The seed. One page of narrative describing the demo idea. Everything else grew from this.	Origin
WRPS-PRO-001_Process_Basis_of_Design.pdf	The process: flows, volumes, pump curves, the wet well. Fixes the numbers the demo narrative rests on.	Current
WRPS-DRG-001_PID.pdf	The P&ID — equipment, instruments, tag numbers.	Current
WRPS-INS-001_Instrument_Index_and_Equipment_List.xlsx	Every instrument and item of plant, with ranges and units.	Current
WRPS-CTL-001_Control_Philosophy.pdf	How the station is meant to be operated, and why.	Current
WRPS-CTL-002_Functional_Design_Specification.pdf	The FDS. Governs — where any other document disagrees with it, this one wins.	Current
WRPS-CTL-003_OpenPLC_Implementation_Brief.md	The bridge from design to code: register map, function blocks, control sequence, simulation model, acceptance tests.	Current, with amendments — see below

Read them in that order. The origin file takes two minutes and makes the rest make sense.

⚠️ CTL-003 carries an amendment block

WRPS-CTL-003 was written before the deployment route was settled, and its §1 and §9 describe a build system (flat .st + MatIEC + a runtime web upload) that does not exist on OpenPLC Runtime v4. The document is kept as issued, with a dated Amendments section at the top listing nine corrections.

Its §2 Modbus address map was verified line by line against the generated 03-plc/register-map.csv and is correct in full, as are §3–§8. Only the build system is wrong. See 03-plc/README.md for how the program is really built.

One amendment is not a documentation defect but real outstanding work: none of the 20 acceptance tests in §7 and §8.4 have been run. The control behaviour is unverified.

---

📌 How these documents were made — and how to do it again

This matters more than the documents themselves, because it is the part you can reuse for the next demo.

There was no real project. There is no Waterloo Road Pump Station. The document set was generated with AI from the single page in 00-origin/, deliberately following the shape of a real project lifecycle:

  an idea                 00-origin/scada-ai-usecase-pump-scheduling.md
     │                    one page of narrative — the demo you want to give
     ▼
  basic design            WRPS-PRO-001  Process Basis of Design
     │                    WRPS-DRG-001  P&ID
     │                    WRPS-INS-001  Instrument Index
     ▼
  detailed design         WRPS-CTL-001  Control Philosophy
     │                    WRPS-CTL-002  Functional Design Specification
     ▼
  implementation brief    WRPS-CTL-003  addresses, function blocks, tests
     │
     ▼
  code                    03-plc/ ── 04-scada/ ── 05-tests/

Why bother with the paperwork for a demo

It would be quicker to write the PLC code straight from the idea. Three reasons not to:

1. The demo has to survive questions. An automation audience asks "why three pumps", "what's the firm capacity", "why does it start at 4.0 m". Answers that trace to a Basis of Design land; invented answers do not.
2. The numbers have to agree with each other. Wet-well volume, pump curves, start levels and the time-to-spill figure on the HMI are all the same handful of numbers. Writing them down once, up front, is what stops the screen and the story contradicting each other on stage.
3. It is the artefact set a customer recognises. Showing a P&ID and an FDS alongside the running system is itself part of the pitch.

Doing it for your own demo

1. Write the one-pager first. Narrative, not specification: who is watching, what question gets asked, what makes them lean forward. 00-origin/ is the model — note how much of it is about the audience, not the plant.
2. Generate the basic design from it, and read it properly. This is where you fix the physical numbers. Everything downstream inherits them, and an error here is expensive later.
3. Generate the detailed design from the basic design, not from the idea. Each layer should cite the one above it. That is what keeps the set coherent.
4. Write the implementation brief last, and make it explicit — addresses, enumerations, acceptance tests. It is the contract the code is written to and the thing you check the built system against.
5. State which document governs. Here it is the FDS (CTL-002). Without that rule, two AI-generated documents will eventually disagree and nobody will know which to believe.

What this project got wrong, so you needn't

• CTL-003 was written before the deployment route was proven. It specified a build system that turned out not to exist, and that error is now permanent in the record. Prove the deployment path with a trivial program before writing the implementation brief.
• Acceptance tests were specified and never run. A test list in a document is not verification. Budget the time to actually run them, or do not claim them in the definition of done.
• A superseded document reused a live document number (an earlier build brief was also numbered CTL-002, colliding with the FDS). Number superseded documents out of the live series, or give them a suffix.

Everything in this folder is AI-generated fiction built on a real process engineering pattern. It is realistic enough to demo and to build against. It is not a real site, and no number in it should be quoted to a customer as a reference project.