Usage Guide

This guide covers the companion workflow for using Dynamic PLCCheck for Siemens with Siemens SCL / Structured Text projects and TIA Portal export files.

The extension is not intended to replace TIA Portal. Use TIA Portal for the canonical engineering-station workflow, then use VS Code for the parts where text files, fast navigation, fast tests, CLI checks, and LLM-assisted review are more efficient.

Install

Install the extension from one of the public registries:

• VS Marketplace
• Open VSX

The extension ships with the Go language server backend. You only need to configure a custom backend if you are developing the extension or testing a local language-server build.

Supported Files

The extension activates for these Siemens-related files:

Create PLC Scopes

Add a .plc.json file at the root of each PLC project. This gives the language server a stable boundary for symbol indexing and prevents types from one PLC from leaking into another PLC in the same VS Code workspace.

{
  "name": "PackingLine PLC",
  "description": "Main line controller",
  "libraries": [
    "../shared_types",
    "../lib/opc_blocks"
  ]
}

Library paths are resolved relative to the .plc.json file. Editing or adding .plc.json files causes the language server to rescan automatically.

Recommended Companion Workflow

1. Export or sync PLC source from TIA Portal.
2. Open the exported project in VS Code.
3. Add .plc.json files to define PLC roots when needed.
4. Use diagnostics, hover, completion, and go-to-definition for fast review.
5. Use the FBD and tag-table editors for TIA-specific export files.
6. Add .scltest unit tests for important FB/FC behavior.
7. Run checks and tests from VS Code, a terminal, or CI.
8. Bring the validated changes back into the TIA Portal workflow.

Use Language Features

Open supported PLC files in VS Code and use the normal editor workflow:

• Diagnostics and type checking are reported in the Problems panel.
• Hover shows resolved type information.
• Completion works across scoped PLC symbols.
• Go to Definition follows quoted identifiers and library references where the source is available.
• .s7dcl files show inlay hints for .s7res titles, can navigate to resource entries, and validate FBD call pins when the target block interface is known.

Edit S7DCL FBD Blocks

For .s7dcl files, use Open S7DCL FBD Editor from the editor title menu, Explorer or Git Source Control context menu, or Command Palette.

The FBD view edits the underlying .s7dcl text directly. Click a variable to highlight every rendered use; press Ctrl+C, select another input/output operand, and press Ctrl+V to replace it without entering text-edit mode. Use Ctrl+Z and Ctrl+Y to undo or redo changes in the backing document. Double-click an operand box to type with the same syntax-aware completion used by the text editor, and right-click an item to navigate to its source range. Expression edits immediately run the normal layout algorithm against the affected network, including block sizing, wrapping, and wire routing. Document diagnostics appear in a graphical diagnostics panel and are marked directly on matching operands, pin names, and block calls; select a diagnostic in the panel to reveal its source range. The parser then validates that locally updated model; matching results retain the existing network DOM, zoom, and scroll state instead of causing a second layout shift.

Open an .s7dcl file under Changed in TIA Portal to compare the live TIA version with the local unsaved document graphically. The columns are labeled TIA Portal and Local (unsaved edits included). Open Graphical Comparison on an existing text diff preserves that diff's two source documents. Git comparison remains a separate command, Open Graphical Diff Against HEAD.

Moves have a blue Moved · Network X → Y badge and a separate summary count. A pure move leaves the blocks unchanged; if the network also changes, the viewer shows both facts. Title/comment/attribute-only changes appear as Metadata changed. Export line endings and whitespace between SCL tokens do not count as edits; literal contents and comments remain significant.

Use Open Graphical Diff Against HEAD from the editor title menu, Explorer or Git Source Control context menu, or Command Palette to compare the current in-memory .s7dcl document with its Git HEAD version. The read-only comparison aligns corresponding networks side by side, marks added, removed, modified, and moved networks, and colors changed rungs and blocks by change type. Matching diagrams share a fit-to-width zoom and synchronized scrolling; click a changed block to highlight its counterpart. Unsaved edits are included, and a file that is not present in HEAD is shown as entirely added. The HEAD side is captured when the comparison opens; the working side refreshes as you edit. Use Previous change / Next change, Hide unchanged, and the zoom selector to review large blocks. Expand Source changes to inspect declarations, comments, attributes, or unsupported syntax alongside the diagrams. See the validation report for corpus coverage and reproduction commands.

Edit Tag Tables

For tag-table XML files under a PLC tags folder, the extension opens the dedicated PLC Tag Table Editor by default.

Use it when you want a table-oriented view over exported tag and project-constant data. The language server also scans these XML files for global symbols and reports diagnostics such as duplicate names, undefined types, and naming conflicts.

Write PLC Tests

Create .scltest files next to your PLC project to validate logic directly from VS Code.

TEST_TARGET "MotorControl_FB";

TEST_CASE "Start motor"
  HOLD UUT.Start := TRUE;
  SET UUT.Stop := FALSE;
  WAIT_CYCLES 1;
  ASSERT UUT.Running = TRUE;
  RELEASE_ALL;
END_TEST_CASE

Use the VS Code Test Explorer to discover and run test cases. For full syntax and execution semantics, see the PLC testing guide rendered in this documentation site.

The test runtime is designed for iteration speed. TIA unit tests can spend about two seconds resetting memory between tests; this workflow resets generated runtime state in milliseconds, which makes small unit tests practical while editing.

Inspect Coverage

PLC test runs can produce coverage data for SCL source files. The extension surfaces this feedback in VS Code so you can see which files and folders are covered while you work through test cases.

Use coverage when you are turning exported logic into reviewable, repeatable unit tests. It helps identify branches and blocks that still only exist as manual TIA Portal checks.

Debug and Monitor Live State

The extension includes PLC debug views for runtime state and watch expressions. Unlike TIA watch tables that primarily show the latest monitored value, this workflow records state so you can inspect what a value was at a specific point in the program while stepping through execution.

Use the PLC Debug Dashboard for runtime health, cycle timing, memory information, and live polling status. Use PLC Live Watch for selected tags and expressions during a debug session.

Sync With TIA Portal

On Windows machines with TIA Portal V21 Openness, the extension can keep an exported PLC folder in sync with the TIA project it came from.

If a user-started operation finds a missing or stale Openness AllowList entry, the extension automatically runs plccheck tia trust --install. Accept the Windows administrator prompt; the extension then retries the original operation once. Declining the prompt stops the operation. Background status checks do not request administrator access.

1. Run TIA Portal: Link Folder to TIA Portal Project… from the command palette. Pick a project that is open in TIA Portal (or browse for an .ap21), pick the PLCs, and choose where the PLC folders are created. Each PLC is exported into its own folder with a .plc.json that records the link:

``json { "name": "PLC_1", "tia": { "project": "C:\\Projects\\Demo\\Demo.ap21", "plc": "PLC_1" } } ``

Keep the folder named after the PLC: the bridge identifies the PLC from the folder that contains Program blocks, so a renamed folder cannot be compared or imported. For the same reason a PLC whose name contains characters that are not allowed in folder names (such as / or :) cannot be linked; rename it in TIA Portal first. Link to a .ap21 project, not a .zap21 archive; the bridge saves into an extracted copy of an archive, so imports into an archive would be lost.

1. A TIA: PLC_1 status bar item shows whether the linked project is open in a running TIA Portal. Click it for the full action list.
2. Compare with TIA Portal (status bar, Source Control view, Explorer context menu, or editor title) compares the local files with the live project. A block whose .s7res texts changed since the last sync counts as changed locally (the sidecar records a hash of the texts), since the texts are imported together with the block; if TIA also changed the block, it is listed as a conflict. Results appear in the Source Control view under a TIA Portal provider with the groups Conflicts, Local Changes, Changed in TIA Portal, and Unknown. Click a file to open a diff editor whose left side is read from TIA Portal.
3. Import into TIA Portal compares first and imports only files that are safe: changed locally and unchanged in TIA. A file whose TIA object was deleted or moved since the last export is held back as well, since importing it would recreate the object. Everything else stays listed so you decide per file with the inline actions Import into TIA Portal (Overwrite) or Replace Local File with TIA Portal Version. After an import the local file is refreshed with the source TIA generated from it (TIA re-indents and normalizes layout), so the exported folder always holds TIA's canonical form of each block.
4. Export from TIA Portal replaces the local TIA-owned files with the current project contents and removes TIA-owned files (those with a .meta.json sidecar) that no longer exist in the project. New local files without metadata are kept, including a local-only source that shares its name with a TIA block; when TIA exports an object to exactly the path of such a file, the local content is kept beside it with a .local suffix. The same happens to a file you save while the export is running: TIA Portal's version wins and your saved text is kept as .local. Project-library definitions are written to a Types folder next to the PLC folder, the same layout plccheck tia export uses so .liblink placeholders resolve. Files in Types without an exporter baseline (a .libinfo/.libint pair or metadata sidecar with the same name) are local-only and are never pruned. Because every PLC folder in a destination shares that Types folder, one destination folder holds the PLCs of one TIA project; linking or exporting refuses a destination whose other PLC folders are linked to a different project. Compile in TIA Portal runs a TIA compile and publishes its errors and warnings in the Problems panel against the exported files.
5. Download to PLC, Go Online, Go Offline, and Snapshot Retained Values to Start Values run the corresponding device actions. Download and snapshot ask for confirmation first. If the PLC needs credentials, set siemensTia.online.authType, siemensTia.online.user, and siemensTia.online.passwordEnv (the name of an environment variable holding the password).

TIA Portal can only fingerprint objects of a compiled project. When Compare finds objects it cannot fingerprint, it offers to compile the PLC in TIA Portal and compare again; it never compiles without asking.

A TIA compile changes object fingerprints even when no source changed. Compare detects that: files that TIA reports as changed but whose source matches the local file are refreshed silently, so Changed in TIA Portal only lists real changes, and a local edit on top of a compiled block stays a Local Change instead of becoming a Conflict. A compile can also genuinely change dependent documents (for example, an FBD caller whose instance type reference is resolved after the callee was imported); those stay listed and can be taken with Replace Local File with TIA Portal Version.

All operations run one at a time through plccheck tia, show progress in a cancellable notification, and log every event in the Siemens TIA Portal output channel. When TIA Portal refuses an import because it would detach a project-library instance, the error offers Repair Library Dependencies….

Use plccheck From a Terminal

The same checks and tests can run outside VS Code through the public plccheck CLI.

npx plccheck check ./my-plc-project
npx plccheck test ./my-plc-project
npx plccheck test ./my-plc-project --coverage-json coverage.json --coverage-lcov lcov.info

LLM-Assisted Review

Because the workflow is file-based, LLM tools can inspect PLC source, documentation, test cases, and command output directly. This is useful for explaining unfamiliar logic, drafting tests, reviewing diagnostics, and preparing refactors before changes are reintroduced into the TIA workflow.