Debug a Program

Note

Debugging is early and in development. Breakpoints, stepping, and variable inspection work for Structured Text programs, but some capabilities are missing or limited. Each section notes the limits that apply to it.

This guide shows how to pause a running program, step through it, and read its variables from your editor. For the full launch configuration and the current limits, see Debugging.

Note

This guide assumes you have installed the IronPLC Compiler. See Installation if you have not already installed it.

Debug the File You Are Editing

  1. Open a Structured Text file.

  2. Click the gutter to the left of a line number to set a breakpoint. A red dot appears.

  3. Press F5.

The program compiles, starts, and stops on the line you marked. The Variables view shows your variables by name and type, and the Call Stack view shows which POU you are in.

Press F10 to run the current line and stop on the next one, or F5 to continue.

No launch.json is needed. To keep a configuration, open the Run and Debug view and select create a launch.json file.

Note

The breakpoint dot may move down a line when the session starts. Breakpoints bind to lines that generate code, so a breakpoint on a blank line, a comment, or a declaration moves to the next line that does.

Stop Before the First Scan

To inspect the program’s initial values before any code runs, set stopOnEntry:

.vscode/launch.json
{
  "type": "ironplc",
  "request": "launch",
  "name": "IronPLC: Stop on Entry",
  "program": "${file}",
  "stopOnEntry": true
}

The program pauses before the first scan cycle. This is the state your declared initial values produce, before any assignment has run.

Stop After a Fixed Number of Scans

A PLC program does not end on its own. Without a breakpoint, a debug session scans until you stop it.

Set scanLimit to end the session after a fixed number of cycles:

.vscode/launch.json
{
  "type": "ironplc",
  "request": "launch",
  "name": "IronPLC: One Scan",
  "program": "${file}",
  "scanLimit": 1
}

Debug a Multi-File Project

The debugger compiles the single file you point it at. A file that uses POUs or types declared in other files does not compile on its own, and the session stops with E0006.

Compile the project first, then debug the container it produces:

  1. Compile the whole project:

    ironplcc compile . -o myproject.iplc

    You can also use the build task, which does the same thing.

  2. Point program at the container:

    .vscode/launch.json
    {
  "type": "ironplc",
  "request": "launch",
  "name": "IronPLC: Debug Project",
  "program": "${workspaceFolder}/myproject.iplc"
}

Breakpoints still work in your source files. The container records which file each line came from, so the debugger matches your breakpoints to the right file.

Recompile after every source change. The debugger runs the container as it finds it.

Watch the Scan Cycle

A breakpoint in a PLC program pauses every scan, not once. To tell one scan from the next, expand the Runtime scope in the Variables view and watch scanCount.

Press F5 to continue. The program runs to the end of the scan, starts the next one, and stops on the same breakpoint with scanCount one higher. Anything your program accumulates — a counter, a timer — moves with it.

When the Debugger Does Not Start

Symptom

Cause

“No program specified to debug”

No file to debug. See E0004.

“Program is not debuggable”

program is neither a source file nor a .iplc container. See E0005.

The session stops with compiler errors

The file did not compile. Check the IronPLC Debug output channel. See E0006.

“Debug server not found”

ironplcvmd was not found next to the compiler. Set ironplc.debugServerPath. See E0007.

“Compile with debug info enabled”

The container has no debug information. Recompile it with ironplcc. See V6009.

The program declares more than one instance

Debugging supports a single program instance. See V6010.

See Troubleshooting for other extension problems.

Next Steps