Control system design documents: the chain from the P&ID to the code, and the two the tests run from
The chain of documents a control system is designed through, from the P&ID and the control philosophy to the functional design specification, the cause and effect matrix, the IO list, the loop diagrams, the HMI design and the software as tested, what each holds and who owns it, and why a change to one reissues everything after it. With a free IO list and cause and effect template.
Key takeaways
- A control system is designed through a chain of documents, each built from the one before: the P&ID, the control philosophy, the functional design specification, the cause and effect matrix, the alarm philosophy, the IO list, the instrument index, the loop diagrams, the network drawings, the HMI design and finally the software as tested.
- The functional design specification, or control narrative, is the one the programmer codes from, the tester tests against and the operators learn the plant from. If it is thin, all three guess, and they guess differently.
- The cause and effect matrix puts every interlock and trip on one grid that a reviewer, a programmer and a tester can all check. It is the shortest safety document on the plant and the one most worth getting right.
- The IO list is the backbone: every input and output, its tag, signal, range and address. The panel is built from it, the loop diagrams are drawn from it, and the FAT and the loop checks walk through it line by line.
- A change to any document reissues every document after it in the chain. A modification made in the code alone leaves the narrative, the matrix and the drawings describing a plant that no longer exists.
A control system can be commissioned from a program and a set of loop drawings, and plenty are. What is missing then shows up for years: an interlock nobody can explain, a sequence that does something sensible for a reason nobody wrote down, an alarm that was useful once, and a modification that is made in the code because there is nothing else to make it in. The plant works, and the only description of how is the code itself, which only the person who wrote it can read.
The documents that prevent that are a chain, each built from the one before. The P&ID says what the process is. The philosophy says the principles. The narrative says what the system does in words. The cause and effect matrix says every interlock on a grid. The IO list says every signal and where it lands. The loop diagrams say how each is wired. The HMI design says what the operator sees. The software is the last link, built from all of them and tested against them. This guide walks the chain, says what each document holds and who owns it, and goes into the two that the tests are run from, the IO list and the cause and effect matrix, in the detail the template follows. A workbook with both comes with it.
It sits beside the plant protocols piece, which covers how the signals travel, and the acceptance testing guide, which covers how the documents are proved.
Free download
IO list and cause and effect template
An IO list with the tag, type, signal, range, controller address, cable, junction box, alarms, interlock reference and loop drawing against every point, a cause and effect matrix with causes down and effects across, eight worked IO rows and six worked causes from a conveyor, and the document chain on a sheet of its own.
The chain
The order is the order of dependence. Nothing in the chain can be written before the one above it is settled, which is why a project that starts programming before the narrative is issued ends up with the narrative written from the program, and a test written from the narrative that tests the program against itself. The table lists each document, what it says, what it is built from, what it is used for and who owns it. Ownership is a discipline, and the discipline that owns the content keeps it true when the plant changes.
The chain also says what has to be reissued when something changes. A new interlock changes the narrative, the cause and effect matrix, possibly the IO list and a loop diagram, the HMI and the software, and the management of change is not closed until all of them say the new state. A change made in the code alone is the most common way a plant's control documents stop being true.
1P&ID
From: The process design
Everything below starts from it
2Control philosophy
From: The P&ID and the site's standards
The frame the narrative and the HMI design sit inside
3Functional design specification
From: The P&ID and the philosophy, with operations
The programmer codes from it, the FAT tests against it, operations learn the plant from it
4Cause and effect matrix
From: The narrative and the hazard studies
The one page a reviewer, a programmer and a tester can all check
5Alarm philosophy
From: The site's alarm standard
Rationalisation, the master alarm database, the HMI
6IO list
From: The P&ID and the instrument index
Panel design, the loop diagrams, the IO check at FAT and the loop check at SAT
7Instrument index
From: The P&ID
Procurement, calibration, the loop diagrams, the asset register
8Loop diagrams
From: The IO list, the instrument index and the panel drawings
Installation, the loop check, and every fault found afterwards
9Network and architecture drawings
From: The philosophy and the security design
Installation, the SAT communications tests, OT security
10HMI design and graphics
From: The philosophy, the P&ID and the alarm philosophy
What the operators see; tested at FAT and SAT
11Software and configuration
From: All of the above
The plant runs on it; backed up on every change
Then
FAT and SAT
Tested against 3, 4 and 6. A test written from the code tests nothing
→ Each is built from the one before. A change to one reissues everything after it
| Document | What it says | Used for | Owner |
|---|---|---|---|
| P&ID | The process: equipment, lines, instruments and control functions, with every tag | Everything below starts from it | Process engineering |
| Control philosophy | The principles: the control system architecture, the modes of operation, how alarms, interlocks, permissives and sequences are to be handled, naming and numbering | The frame the narrative and the HMI design sit inside | Control engineering |
| Functional design specification | The control narrative: what each system does in words, loop by loop and sequence by sequence, in every mode and on every abnormal path | The programmer codes from it, the FAT tests against it, operations learn the plant from it | Control engineering |
| Cause and effect matrix | Every interlock and trip as a grid: each cause, each effect, and the mark where a cause produces an effect | The one page a reviewer, a programmer and a tester can all check | Control engineering, with process safety where it applies |
| Alarm philosophy | How alarms are chosen, prioritised, presented and reviewed | Rationalisation, the master alarm database, the HMI | Operations and control engineering |
| IO list | Every input and output: tag, type, signal, range, where it lands in the controller and what it is wired through | Panel design, the loop diagrams, the IO check at FAT and the loop check at SAT | Control engineering |
| Instrument index | Every instrument with its service, type, range, make and model, datasheet and loop | Procurement, calibration, the loop diagrams, the asset register | Instrument engineering |
| Loop diagrams | One drawing per loop from the field device to the controller: terminals, cores, junction boxes, cables, power | Installation, the loop check, and every fault found afterwards | Electrical and control |
| Network and architecture drawings | The controllers, servers, switches, links and protocols, and the zones between them | Installation, the SAT communications tests, OT security | Control and IT |
| HMI design and graphics | The display hierarchy, the graphics standard, the navigation, the permissions, the displays themselves | What the operators see; tested at FAT and SAT | Control engineering, with operations |
| Software and configuration | The code and the configuration as tested: the controller program, the HMI project, the alarm database, the network configuration | The plant runs on it; backed up on every change | Control engineering |
The narrative
The functional design specification is the longest document in the chain and the one most worth the time. It says in words, loop by loop and sequence by sequence, what the system does: the modes, the start and stop sequences with their permissives and timers, the interlocks and what resets them, the control loops with their setpoints, ranges and the action on a failed input, the alarms, and every abnormal path. Three groups read it. The programmer codes from it. The test engineer writes the FAT from it. The operators learn the plant from it, and it becomes the basis of their procedures.
A thin narrative makes all three guess, and they guess differently. The test of a good one is that a programmer who has never seen the plant could code it, and an operator who has never seen the code could say what the plant will do when the drift switch operates. It is written by control engineering with operations in the room, because operations know the abnormal paths that the P&ID does not show.
If the narrative cannot tell an operator what happens when the drift switch trips, the code is the only place that knows, and the code cannot be asked.
The cause and effect matrix
Interlocks and trips are hard to review in prose and easy to review on a grid. The cause and effect matrix has the causes down the side, each with its tag, the effects along the top, and a mark where a cause produces an effect: T for a trip, A for an alarm, blank for nothing. A process engineer can read it against the hazard study. A programmer can code it row by row. A tester can walk it cell by cell at the FAT, making each cause and checking for each effect and for nothing else. The example below is the conveyor's, and its six rows are the six worked causes on the template.
Two conventions make it work. Every mark has a note where it needs one, because a trip with a time delay or a start inhibit is not the same as a plain trip, and the note is where that lives. And the matrix is the master for the interlocks: a change to an interlock is made on the matrix first, reviewed there, and only then coded. On a facility with process safety obligations the matrix is also the record of which functions are safety instrumented, and the review it gets reflects that.
| Cause | Tag | Stop CV-201 | Inhibit CR-001 feed | Stop upstream sequence | Alarm to operator | Inhibit restart until reset | Note |
|---|---|---|---|---|---|---|---|
| Pull-wire operated | ZS-201C | T | T | T | A | T | Hardwired to the drive as well as through the PLC |
| Belt drift, either switch | ZS-201A/B | T | T | T | A | T | Either switch, after MOC-2026-044 |
| Underspeed after start delay | SS-201 | T | T | T | A | 10 s start delay before the check is armed | |
| Gearbox bearing temperature high high | TE-201 > 95 | T | T | A | High at 85 is alarm only | ||
| Head chute blocked | LSH-201 | T | T | T | A | T | Stops the belt before the chute fills |
| Downstream CR-001 stopped | CR-001 run = false | T | T | A | Sequence stop, not a trip: belt runs out first |
The IO list
The IO list is the backbone of the design and the backbone of the test. Every input and output has a row: the tag, a description, the type, the signal, the range and units, where it lands in the controller, what it is wired through, the alarms on it, the interlock it takes part in, and the loop drawing that shows it. The panel designer counts the rows to size the racks. The drafter draws a loop diagram per row. The FAT's IO check and the SAT's loop check walk the list from top to bottom, and the status column says how far each row has got.
It is built from the P&ID and the instrument index, and it is kept by control engineering for the life of the plant, because it is the first thing a technician opens when an input stops making sense. The columns are the template's, and the eight worked rows are the conveyor's drift switches, pull-wire, speed switch, bearing temperature, blocked chute switch, belt weigher and run command, the same loops the cause and effect matrix and the acceptance testing examples use.
| Column | What goes in it |
|---|---|
| Tag | From the P&ID, ISA-5.1 style or the site's standard |
| Description | Service and function, in words |
| Area / system | As it says |
| P&ID | The drawing it appears on |
| IO type | As it says |
| Signal | 4-20 mA, HART, 24 V DC dry contact, Profinet, Modbus TCP and so on |
| Range and units | Analogue: the calibrated range and the engineering units. Discrete: the state when true |
| Controller | As it says |
| Rack / slot / channel | Where it lands |
| Cable | From the cable schedule |
| Junction box | As it says |
| Alarm | The alarms configured on it, with priority |
| Interlock ref | The cause and effect row or column it appears in |
| Loop drawing | As it says |
| Status | As it says |
The rest of the chain
The alarm philosophy says how alarms are chosen, prioritised and presented, and it is written once per site rather than per project, because an alarm system is only usable if every project adds to it on the same rules. Alarm management covers it. The instrument index lists every instrument with its service, type, range, make, model and datasheet, and it feeds procurement, calibration and the asset register. The loop diagrams follow each signal from the field device to the controller terminal and are the drawings a technician works from. The network drawings show the controllers, switches, links and the zones between them, which is where OT security is designed in rather than added. The HMI design sets the display hierarchy and the graphics standard before any display is drawn, and ISA-101 is the usual reference.
The last link is the software and configuration as tested: the controller program, the HMI project, the alarm database, the network configuration. It is a document in the sense that matters, because the plant runs on it, and it is backed up on every change rather than on a schedule, with the backup taken at the end of the SAT as the as-built baseline that document control holds.
Where the chain breaks
- Programming started before the narrative is issued, so the narrative is written from the program and tests it against itself.
- No control philosophy, so each loop and each project is designed on its own principles and the HMI shows it.
- A narrative that describes the normal path only, so the abnormal paths are whatever the programmer decided.
- Interlocks reviewed in the code rather than on the matrix, by the person who coded them.
- An IO list kept by the panel vendor and never handed over, so the plant has loop diagrams and no index to them.
- Modifications made in the code alone, leaving the narrative, the matrix and the drawings describing a plant that no longer exists.
- The as-tested configuration not backed up, so the baseline is whatever is running.
- Documents held in the vendor's format and the vendor's system, with the native files never delivered.
Common questions
What is a functional design specification?
The document that says in words what the control system does: for each system and loop, the modes of operation, the start, stop, hold and restart sequences, the interlocks and permissives, the control loops with their setpoints and ranges, the alarms, and what happens on every abnormal path. Also called the control narrative or the functional description. The programmer codes from it, the factory acceptance test is written against it, and operations learn the plant from it. It is written by control engineering with operations, from the P&ID and the control philosophy.
What is a cause and effect matrix?
A grid with the causes, such as a switch operating, a measurement exceeding a limit or a piece of equipment stopping, down the side, the effects, such as stopping a drive, closing a valve or raising an alarm, along the top, and a mark in each cell where that cause produces that effect. It shows every interlock and trip on one page in a form a process engineer, a programmer and a tester can all read and check. On facilities with process safety obligations it is also the record of the safety instrumented functions.
What is an IO list?
The list of every input and output the control system has: the tag from the P&ID, a description, the IO type, the signal type, the range and engineering units, which controller and which rack, slot and channel it lands on, the cable and junction box it comes through, the alarms configured on it, the interlocks it takes part in, and the loop drawing that shows it. It is built from the P&ID and the instrument index, the panel is designed from it, and the IO check at the FAT and the loop check at the SAT walk through it line by line.
What is a loop diagram?
A drawing, one per loop, that follows a signal from the field device to the controller and back: the instrument, its terminals, the cable and its cores, the junction box, the marshalling, the controller terminal, the power supply, and the IO address. It is drawn from the IO list, the instrument index and the panel drawings, and it is what a technician works from when wiring, loop checking or fault finding. ISA-5.4 is the usual reference for its format.
What is a control philosophy?
The document that sets the principles before the detail: the control system architecture, the modes of operation the plant will have, how interlocks, permissives, alarms and sequences are to be handled as a matter of policy, the naming and numbering conventions, and the standards that apply. It is written early, from the P&ID and the site's own standards, and the functional design specification and the HMI design are written inside the frame it sets. Without it, each loop is designed on its own principles.
What standards apply to control system documentation?
ISA-5.1 for instrument and control symbols and tag identification on the P&ID, IEC 62424 for how control engineering requests are represented on P&IDs and exchanged with control engineering tools, IEC 62682 (ISA-18.2) for alarm management and the alarm philosophy, ISA-101 for the HMI design, IEC 61082-1 for the preparation of electrotechnical documents such as loop diagrams, and IEC 62381 for the factory and site acceptance tests the documents are tested in. The format of the functional design specification and the IO list is the site's or the vendor's. The content described here is what matters.
Key terms
Plain-language definitions from our glossary for the concepts this article leans on.
Standards and further reading
- ANSI/ISA-5.1-2024 Instrumentation and control symbols and identification (ISA)
- IEC 62424:2016 Representation of process control engineering: requests in P&I diagrams and data exchange between P&ID tools and PCE-CAE tools (IEC)
- IEC 62682:2022 Management of alarm systems for the process industries (IEC)
- ISA-101.01-2015 Human machine interfaces for process automation systems (ISA)
- IEC 61082-1:2014 Preparation of documents used in electrotechnology, part 1: rules (IEC)
- IEC 62381:2024 Automation systems in the process industry: factory acceptance test (FAT), site acceptance test (SAT) and site integration test (SIT) (IEC)
Related case studies and tools
- Bridging OT and IT with custom software (case study)
Related reading
Working through something like this?
See how we approach these initiatives, or tell us what you are dealing with.