Testing and debugging — ST course

Every bug happens on a particular scan

A machine misbehaves "sometimes". The capper skips a bottle once every few hundred, the pump restarts "on its own", the batch total is wrong "after a recipe change". Those descriptions are true and useless. Underneath every one of them is a specific scan on which a specific variable took a value you did not expect.

Testing and debugging Structured Text is the craft of finding that scan. It is not about tools first. The tools — watch tables, forcing, simulators, trace recorders — only help if you already think of the program as a sequence of scans, each one reading a snapshot, executing top to bottom, and writing outputs. Chapter 1 asked you to step a program one scan at a time. In this chapter that habit becomes a method.

The method has three parts. Before the code exists, write down what the machine must do as plant cases: given these inputs, after this much time, these outputs. While the code is being written, run those cases against it, including the awkward ones at the boundaries. And when something fails — on the bench or on the plant floor — debug from a hypothesis you can check, not from a change you hope will help.

Online watch, write and force

Every IDE lets you go online with a running controller and watch variables change: CODESYS and TwinCAT show live values next to every variable in the editor, TIA Portal has watch tables and the glasses icon for monitoring SCL, and Studio 5000 shows tag values in the Monitor Tags view and inline in the ST editor. Watching is safe. Use it constantly.

Changing values online comes in two very different strengths.

A write (CODESYS calls it Write values, TIA Portal Modify) puts a value into a variable once. If the program assigns that variable on every scan, your value lasts until the next assignment — a few milliseconds — and you will never see it. Writes are for variables the program only reads or only changes occasionally: a setpoint, a recipe number, a latch.

A force pins a value. The controller re-applies it on every scan, overriding both the input terminal and anything your program writes. It is the most powerful debugging tool in the IDE and the most dangerous.

Forcing a physical output bypasses every interlock you wrote. Force a fill valve open and it stays open when the tank is full, when the E-stop logic in the PLC drops, when the high-level alarm trips. Force a conveyor motor on and the jam detection is irrelevant. People have been injured by forced outputs that someone forgot to remove.

Forces also outlive the debugging session. On an S7-1500 a force job stays active in the CPU after you close TIA Portal and even through a power cycle. In Studio 5000, I/O forces are stored in the controller and the project, and the controller's FORCE LED is the only hint on the cabinet door that one is active. CODESYS asks when you log out whether to keep forced values; the easy answer is the wrong one.

On these pages, the input panels beside every live program are forces: the program reads them but cannot overwrite them. That is exactly how the graded challenges test your code.

Write the plant cases before the code

A plant case is a requirement you can run. Each one says: set these inputs, let this many scans and this much time pass, then check these outputs. A list of them, run in order on one controller, is a test of the whole behaviour — including memory, because state carries from one case to the next.

Every challenge in this course is graded exactly like that. The cases are JSON objects with five fields:

[
  { "description": "Start pressed",
    "setInputs": { "Start": true, "Stop": false },
    "expect": { "Motor": true } },
  { "description": "Start released — still running (seal-in)",
    "setInputs": { "Start": false },
    "scans": 5,
    "expect": { "Motor": true } },
  { "description": "Overload for 2.1 s trips it",
    "setInputs": { "Overload": true },
    "scans": 21, "advanceMs": 2100,
    "expect": { "Motor": false, "Tripped": true } }
]

setInputs forces inputs. They stay forced until a later case changes them, so the second case above still has Stop FALSE.
scans (default 1) is how many scans run before checking; advanceMs spreads that much virtual time across them (default 100 ms per scan), so a timer sees its elapsed time grow scan by scan.
expect lists the outputs to compare after the last scan. Anything not listed is not checked.
All cases run in order on one engine. The third case only makes sense because the first one started the motor.

Writing these before the program does three things. It forces you to decide behaviour you would otherwise leave vague — "what does the motor do if Start is held while Stop is pressed?" is a requirement, not an implementation detail. It gives you a definition of done that does not depend on how confident you feel. And it is a regression suite: after every change, run all the cases again, because the change that fixes case 7 is often the one that breaks case 3.

On a real project the same cases go into the factory acceptance test (FAT) document, run against a simulator before the machine ships. CODESYS has a unit-test framework (CODESYS Test Manager), TwinCAT users commonly use the open-source TcUnit, and TIA Portal projects are tested against S7-PLCSIM Advanced. The format differs; the thinking is the same.

Boundary cases

Most logic bugs live at the edges of a range, not in the middle. A comparison written > that should be >=, a counter that fires one part late, a timer case that checks at 0.99 s and passes by luck. For every threshold, count and time in your requirements, write cases at the boundary and one step either side of it.

Thing	Cases worth writing
Threshold 80.0 °C	79.9, exactly 80.0, 80.1, and the way back down through the hysteresis band
Counter preset 12	11 (not yet), 12 (done), 13 (what now?), and reset in the middle
Timer 2 s	just under (1.9 s), just over (2.1 s), and input dropping at 1.9 s then returning
Analog input	0, full scale, below 0 (wire break), above full scale (overload)
Integers	0, 1, the maximum (32,767 for INT), negative values
Sequence	the first scan after power-up, and every input arriving in the "wrong" order

Timers deserve particular care, because their boundary depends on when they started.

Predict: A TON with PT := T#1s is called every scan with IN := TRUE from the very first scan. The scan time is 100 ms. After exactly 10 scans, what is Q?

PROGRAM Main
VAR
    T  : TON;
    Q  : BOOL;
    ET : TIME;
END_VAR

T(IN := TRUE, PT := T#1s);
Q  := T.Q;
ET := T.ET;

END_PROGRAM

TRUE — 10 scans of 100 ms is 1 s
FALSE — the timer started on scan 1, so after scan 10 only 900 ms have elapsed
TRUE — timers round up to the next scan

Show the answer

FALSE — the timer started on scan 1, so after scan 10 only 900 ms have elapsed

The timer records its start time on the first scan it sees IN TRUE, with ET = 0. Each later scan adds one scan time, so on scan 10 ET is 900 ms and Q is still FALSE; it switches on scan 11. This one-scan offset is real on every PLC, and it is why the plant cases in this course check timers at 2.1 s rather than exactly 2.0 s. A test that only passes at the exact preset is testing your luck with scan timing.

Simulate the plant inside the program

You will rarely get the real machine to test on. It is still being built, or it is in production, or it is a 20-tonne press nobody will let you cycle for fun. The answer is to simulate it: a small piece of code that behaves like the plant, reading your outputs and writing your inputs.

For a tank, that is two lines: the level rises while the inlet valve is open and falls while the outlet is open, limited between empty and full. Put the model in its own clearly marked section, enabled by a constant, so it can never run on the real machine by accident.

PROGRAM Main
VAR CONSTANT
    SIMULATION   : BOOL := TRUE;   (* FALSE on the real machine *)
    TANK_MAX_L   : REAL := 500.0;
    INFLOW_L_SCAN  : REAL := 4.0;  (* 40 L/s at 100 ms per scan *)
    OUTFLOW_L_SCAN : REAL := 2.5;
END_VAR
VAR
    AutoFill   : BOOL;    (* input: operator selects automatic fill *)
    DrainOpen  : BOOL;    (* input: downstream draws from the tank *)
    LowSwitch  : BOOL;    (* plant input: level switch at 100 L *)
    HighSwitch : BOOL;    (* plant input: level switch at 400 L *)
    InletValve : BOOL;    (* output *)
    Level_L    : REAL := 250.0;   (* simulated plant state *)
END_VAR

(* ===== Controller: the code that would ship ===== *)
IF AutoFill AND LowSwitch THEN
    InletValve := TRUE;
ELSIF HighSwitch OR NOT AutoFill THEN
    InletValve := FALSE;
END_IF;

(* ===== Plant model: only while simulating ===== *)
IF SIMULATION THEN
    IF InletValve THEN
        Level_L := Level_L + INFLOW_L_SCAN;
    END_IF;
    IF DrainOpen THEN
        Level_L := Level_L - OUTFLOW_L_SCAN;
    END_IF;
    Level_L    := LIMIT(0.0, Level_L, TANK_MAX_L);
    LowSwitch  := Level_L <= 100.0;
    HighSwitch := Level_L >= 400.0;
END_IF;

END_PROGRAM

Live example — open this page with JavaScript to run and edit it. Inputs you can drive: AutoFill, DrainOpen.

Switch on AutoFill and DrainOpen. The level falls until the low switch makes, the inlet opens, and because inflow beats outflow the level climbs back to 400 L and the valve closes. The controller section has no idea it is talking to a model. Turn AutoFill off and you can watch the tank drain to zero — the kind of test you would never be allowed to run on a real product tank.

A plant model does not need to be accurate; it needs to be qualitatively right and able to misbehave on demand. Add an input that sticks the high switch, a parameter that halves the inflow to simulate a blocked strainer, a fault that freezes the level. Those are the cases where controllers fail, and a model lets you produce them at will. For bigger machines, the same idea scales up into tools such as S7-PLCSIM Advanced with a co-simulation, Rockwell's Logix Echo, TwinCAT running on the engineering PC, or a separate simulation program in the same project.

Debug from a hypothesis

When the bench or the plant shows a failure, the tempting move is to change something and see if it helps. On a live machine that is how one bug becomes three. Work like this instead:

Observe precisely. Which output did what, on which event? "The case packer counted 13 bottles into a 12-pack" is a fact you can work with.
Form a hypothesis that names a variable and a scan. "Count incremented twice for one bottle because the eye flickered at the bottle's edge."
Predict what you would see if it were true. "If I trace the eye input, I will see two rising edges less than 20 ms apart for one bottle."
Check it — with a watch, a trace (TwinCAT Scope, the CODESYS trace, TIA Portal's trace function, or a Studio 5000 trend), or by reproducing it in a plant case.
Change one thing, then run all the cases again.

If the prediction is wrong, the hypothesis was wrong, and you have learned something without touching the code. That is still progress. What is not progress is a debounce timer added "just in case" that hides the real problem for three months.

The usual suspects

Most ST bugs you will ever meet are one of a handful of patterns. Learn to recognise them on sight.

1. The missing ELSE. An IF that sets an output TRUE and never sets it FALSE has built an accidental latch. Chapter 5 covered it; it is still the most common bug in code reviews.

PROGRAM Main
VAR
    Level_High : BOOL;   (* input: high level switch *)
    Beacon     : BOOL;   (* output: should follow the switch *)
END_VAR

IF Level_High THEN
    Beacon := TRUE;      (* no ELSE: once on, nothing switches it off *)
END_IF;

END_PROGRAM

Live example — open this page with JavaScript to run and edit it. Inputs you can drive: Level_High.

Switch Level_High on and off. The beacon stays on forever. Either add the ELSE or, better, write Beacon := Level_High; — a plain assignment cannot latch.

2. The timer inside an IF. A timer only updates when it is called. Put the call inside an IF and, when the condition goes FALSE, the timer is simply not called: it never sees IN go FALSE, never resets, and its Q sticks.

Predict: A run timer is called only while Run is TRUE. Run is TRUE for scans 1 to 7 (700 ms) and FALSE from then on. After 12 scans, what is Alarm?

PROGRAM Main
VAR
    Scan  : INT;
    Run   : BOOL;
    T     : TON;
    Alarm : BOOL;
END_VAR

Scan := Scan + 1;
Run  := Scan <= 7;

IF Run THEN
    T(IN := Run, PT := T#500ms);
END_IF;
Alarm := T.Q;

END_PROGRAM

FALSE — Run went FALSE, so the timer reset
TRUE — the timer reached 500 ms and was never called again to see IN go FALSE
FALSE — the timer never reached its preset in 700 ms

Show the answer

TRUE — the timer reached 500 ms and was never called again to see IN go FALSE

On scan 7 the timer has 600 ms elapsed and Q is TRUE. From scan 8 the IF skips the call, so the timer's inputs are never updated and its outputs are frozen at their last values. Call timers unconditionally, every scan, and put the condition on the IN pin: T(IN := Run, PT := T#500ms);.

3. Edge versus level. A counter that adds one "while the eye is blocked" counts scans, not bottles. At 10 ms per scan, a bottle that blocks the eye for 80 ms counts as eight. Count on an R_TRIG edge (chapter 8 and chapter 11).

4. The total that is never cleared. A FOR loop that sums an array must start from zero on every scan. Forget the Sum := 0; line and the sum grows by the whole array total every scan — a bug that looks right on the very first scan and nowhere else.

PROGRAM Main
VAR
    Weights : ARRAY[1..4] OF INT := [250, 248, 252, 251];  (* grams *)
    Sum     : INT;    (* bug: never cleared *)
    SumOk   : INT;
    i       : INT;
END_VAR

FOR i := 1 TO 4 DO
    Sum := Sum + Weights[i];
END_FOR;

SumOk := 0;                     (* cleared before every pass *)
FOR i := 1 TO 4 DO
    SumOk := SumOk + Weights[i];
END_FOR;

END_PROGRAM

Live example — open this page with JavaScript to run and edit it.

Pause and step: after one scan both read 1001 g. After two, Sum reads 2002. After 33 scans the INT overflows and goes negative. A test that runs only one scan will never catch it — another reason the cases run several.

5. Comparing REALs with =. Floating-point values are almost never exactly equal to a decimal literal. Ten additions of 0.1 do not make exactly 1.0 on a PLC's 32-bit REAL, and they do not here either.

PROGRAM Main
VAR
    Total      : REAL;
    ExactlyOne : BOOL;
    CloseToOne : BOOL;
    i          : INT;
END_VAR

Total := 0.0;
FOR i := 1 TO 10 DO
    Total := Total + 0.1;
END_FOR;

ExactlyOne := Total = 1.0;                 (* never use this *)
CloseToOne := ABS(Total - 1.0) < 0.0001;   (* compare with a tolerance *)

END_PROGRAM

Live example — open this page with JavaScript to run and edit it.

The digits you see here come from this engine's 64-bit arithmetic; a 32-bit PLC REAL misses by a different amount. The lesson is the same on both: compare REALs with >=, <= or a tolerance, never =. A fill that stops "when weight = 500.0" may never stop.

6. Wrong precedence. AND binds tighter than OR, so Run := Start OR Run AND NOT Stop; means Start OR (Run AND NOT Stop). While Start is held, Stop does nothing. Write Run := (Start OR Run) AND NOT Stop; and the stop wins. When in doubt, add parentheses; they cost nothing and the next reader does not have to remember the table.

Challenge: Fix the 3-pack counter

A shrink-wrapper groups bottles in packs of three. A photo-eye Eye is TRUE while a bottle passes, usually for several scans. Count must increase by exactly one per bottle. PackFull must be TRUE while Count is 3 or more, and FALSE otherwise. ResetBtn sets Count back to 0.

The starter has two of the usual suspects in it. Find them from the cases rather than by staring at the code: run it, see which case fails first, and form a hypothesis.

PROGRAM Main
VAR
    Eye      : BOOL;   (* input: TRUE while a bottle blocks the eye *)
    ResetBtn : BOOL;   (* input *)
    Count    : INT;    (* output *)
    PackFull : BOOL;   (* output *)
END_VAR

IF Eye THEN
    Count := Count + 1;
END_IF;

IF Count >= 3 THEN
    PackFull := TRUE;
END_IF;

IF ResetBtn THEN
    Count := 0;
END_IF;

END_PROGRAM

Case	Plant sets	Program must give
Bottle 1 blocks the eye for 4 scans	Eye = TRUE, ResetBtn = FALSE	Count = 1, PackFull = FALSE
Gap	Eye = FALSE	Count = 1
Bottle 2	Eye = TRUE	Count = 2, PackFull = FALSE
Gap	Eye = FALSE	Count = 2
Bottle 3 — pack full	Eye = TRUE	Count = 3, PackFull = TRUE
Pack removed, counter reset	Eye = FALSE, ResetBtn = TRUE	Count = 0, PackFull = FALSE
Next bottle	ResetBtn = FALSE, Eye = TRUE	Count = 1, PackFull = FALSE

Hints

The first case fails with Count = 4 after four scans: what is being counted, bottles or scans?
After a reset, is anything ever setting PackFull back to FALSE?
Count on an R_TRIG of Eye, and make PackFull a plain assignment from the comparison so it can never latch.

Show a solution

PROGRAM Main
VAR
    Eye      : BOOL;
    ResetBtn : BOOL;
    Count    : INT;
    PackFull : BOOL;
    EyeEdge  : R_TRIG;
END_VAR

EyeEdge(CLK := Eye);
IF EyeEdge.Q THEN
    Count := Count + 1;
END_IF;

IF ResetBtn THEN
    Count := 0;
END_IF;

PackFull := Count >= 3;

END_PROGRAM

Challenge: Build the plant model

You are commissioning a level controller before the tank exists, so you need a model of the tank. Write it. InletOpen and OutletOpen are the controller's valve outputs, wired into your model as inputs. Every scan, Level (litres, INT) rises by 5 while the inlet is open and falls by 3 while the outlet is open; both can be open at once. The tank holds 0 to 1000 L: the level must never go below 0 or above 1000. Overflow is TRUE while the level is at 1000 L.

The tank starts empty. The starter models only the inlet.

PROGRAM Main
VAR
    InletOpen  : BOOL;   (* input: from the controller *)
    OutletOpen : BOOL;   (* input: from the controller *)
    Level      : INT;    (* output: simulated level, litres *)
    Overflow   : BOOL;   (* output *)
END_VAR

IF InletOpen THEN
    Level := Level + 5;
END_IF;

END_PROGRAM

Case	Plant sets	Program must give
Inlet open for 10 scans	InletOpen = TRUE, OutletOpen = FALSE	Level = 50, Overflow = FALSE
Both open for 10 scans: net +2 per scan	OutletOpen = TRUE	Level = 70, Overflow = FALSE
Outlet only for 30 scans — the tank runs dry, not negative	InletOpen = FALSE	Level = 0, Overflow = FALSE
Inlet only for 250 scans — the tank fills to the brim	InletOpen = TRUE, OutletOpen = FALSE	Level = 1000, Overflow = TRUE
Outlet opens for 1 scan with the inlet still open	OutletOpen = TRUE	Level = 1000, Overflow = TRUE
Inlet closes, outlet drains for 10 scans	InletOpen = FALSE	Level = 970, Overflow = FALSE

Hints

Add the outlet as its own IF after the inlet, so both can act in the same scan.
The boundary cases fail next: the tank cannot hold less than nothing or more than 1000 L.
Clamp after both changes with LIMIT(0, Level, 1000), then compute Overflow from the clamped level.

Show a solution

PROGRAM Main
VAR
    InletOpen  : BOOL;
    OutletOpen : BOOL;
    Level      : INT;
    Overflow   : BOOL;
END_VAR

IF InletOpen THEN
    Level := Level + 5;
END_IF;
IF OutletOpen THEN
    Level := Level - 3;
END_IF;
Level    := LIMIT(0, Level, 1000);
Overflow := Level >= 1000;

END_PROGRAM

Ready to build something whole

You now have the tools a commissioning engineer actually uses: thinking in scans, watching without disturbing, forcing inputs rather than outputs, writing plant cases before the code, attacking the boundaries, simulating the plant when it does not exist yet, and debugging from a hypothesis you can check. You also have a list of six bugs you will now spot in other people's code within seconds.

The final chapter puts all of it to work on one machine: a bottle filling line with modes, a fill sequence, a simulated scale, counters, a fill timeout, alarms with acknowledge — and a set of plant cases that grade the whole cell.

Every bug happens on a particular scan

Online watch, write and force

Write the plant cases before the code

Boundary cases

Simulate the plant inside the program

Debug from a hypothesis

The usual suspects

Ready to build something whole

Practise this chapter