Explorer for TwinCAT

TwinCAT 3 PLC projects in VS Code, the way TwinCAT XAE shows them. The extension adds the XAE project tree, opens every POU, method, property and accessor in its own tab with the Declaration above the Implementation, and brings Structured Text language features and git views that work per object. The code stays in the .TcPOU, .TcDUT, .TcGVL and .TcIO XML files, and saving writes back only the sections you edited.

• Features
• Requirements
• Installation
• Getting started
• Commands
• Keyboard shortcuts
• Extension settings
• Library stubs
• Known issues and limitations
• Troubleshooting
• Release notes
• Development
• License
• Trademarks

Features

TwinCAT tree

The TwinCAT view in the Explorer, below Outline and Timeline:

• One root per .tsproj, then its PLC projects, References, and the folders and objects of each .plcproj.
• Inside a POU: the folders TwinCAT keeps in the XML (Methods > States), methods, properties with Get/Set, actions and transitions.
• Labels follow XAE (FB_X (FB), MAIN (PRG)), and modified files get their git colour.
• Methods, properties and accessors that differ from HEAD are marked M (changed) or A (new), like the Explorer marks files.
• Ctrl+Alt+T (TwinCAT: Go to Object...) lists every object of the workspace.

Split editor

• One tab per object, titled FB_X, FB_X.Method or FB_X.Property.Get.
• Two panes, like XAE:
  • The Declaration is in the upper pane and the Implementation in the lower one. Each pane has its own scroll bar, and both start at the same height.
  • Drag the bar between them to change the heights; the tab remembers it. Double-click the bar to get equal halves again.
• Which tab shows what: a property tab shows the property declaration, and its Get and Set open in their own tabs. DUTs, GVLs and interfaces have a single pane.
• Opening: a single click in the tree opens a preview tab; a double click, or an edit, keeps it.
• Look:
  • Breadcrumbs follow the XAE path.
  • The panes are Monaco editors (the editor VS Code is built on). They use your VS Code font, tab and theme settings and the same colours.
• Changes vs HEAD:
  • Each pane marks its changed lines in the gutter (green: added, blue: changed, red wedge: removed), unsaved edits included. Alt+F5 and Shift+Alt+F5 go to the next and previous change.
  • Show Changes vs HEAD (editor title button, or a click on a change marker) turns both panes into inline diffs against HEAD. Unchanged lines are folded, the panes stay editable, and the Revert Block button next to a change puts the HEAD text back.
  • Hide Changes vs HEAD returns to the normal panes. A commit, checkout or rebase updates the comparison.
• Line blame, like GitLens' current line blame:
  • The end of the current line shows who changed it last, when, and the commit message (You, 2 days ago • Fix the purge timer).
  • The hover adds the date, Open Changes and Show History. Open Changes shows the commit's changes of this object in the commit diff panel; a click on the annotation does the same.
  • Lines changed since HEAD, saved or not, show Uncommitted changes.
  • TwinCAT: Toggle Line Blame or twincatExplorer.blame.currentLine turns it off.

Safe saving

• Edited sections only: only the CDATA of the sections you edited is replaced. BOM, CRLF, GUIDs and every other byte of the file stay as they were.
• Outside changes survive: sections you did not touch are never written back, so changes made meanwhile in XAE or by git are kept.
• Conflicts are refused: if a section you edited was also changed on disk, the save is refused with a message instead of overwriting it.
• Several tabs: two tabs of the same file can be edited and saved independently.
• Reloads: open tabs without unsaved edits reload when the file changes on disk. Undoing back to the text on disk makes the tab clean again.
• Renaming is blocked: changing the name in a declaration header (METHOD OnEntry to METHOD OnEnter) makes the save fail with a message. Rename objects in TwinCAT XAE.

Structured Text language features

These work in both panes and in notebook cells. They come from a parser of the TwinCAT dialect (EXTENDS, IMPLEMENTS, THIS^, SUPER^, properties, REFERENCE TO, ...).

• Go to Definition (F12, Ctrl+click), including members reached through variable types and inheritance. fbValve.Open() opens the Open method of FB_Valve, or of the function block it extends, at the method name; a local variable moves the cursor to the declaration pane.
• Hover with the declaration, its comments and where it is declared.
• Completion after . (members, inherited members, enum values) and of the names in scope.
• Find All References: Shift+F12 opens a peek view. Other objects are shown read-only there; double-click a result to open it.
• Problems, reported while you type in the editor and in the Problems panel: syntax errors, unknown identifiers, unknown members and unknown named parameters. A click in the Problems panel opens the split editor at the problem.
• Ctrl+T finds POUs, methods, properties, DUTs, GVLs and global variables, and opens the split editor at the symbol.
• Outline of the declared variables (notebook cells).
• TwinCAT: Check All Structured Text analyses every section of every project and reports the problems on the XML files.

Source Control views

Three views in the Source Control sidebar.

TwinCAT Changes lists the objects that differ (POU, methods, properties, accessors), grouped by POU and marked M, A or D.

• Two scopes, switched in the view's title bar:

  • uncommitted changes (vs HEAD);
  • branch changes since the merge base with another branch, what a merge request shows. origin/develop is the default; Compare Branch With... picks another one. Uncommitted changes are included.

• Opening: a click opens the object in the split editor with the diff against that base, at its first change. A deleted object opens as read-only text of its old version.

• Discard Changes (uncommitted scope only):

  • the code of an object goes back to HEAD;
  • a new method, property, action or accessor is removed;
  • a whole file goes back to HEAD, in the working tree and the index.

  It is refused while an editor has unsaved edits of the file.

• Build output (no code changes) gathers files whose change is only XAE metadata: a .tsproj with only new TmcHash values, or a source file with only a new ProductVersion. They can be discarded too.

• Project files holds the other .tsproj/.plcproj changes; a click shows their XML diff.

TwinCAT Commits works like the commits view of GitLens.

• The list:
  • Every commit of HEAD, newest first, as git log lists them, 30 at a time (Load more commits...), with author and age.
  • An arrow marks the commits no remote has yet, and merges have their own icon.
  • Copy the SHA or the message from the context menu.
• A commit expands to the files it changed: its POUs first, each expanding to the objects the commit changed (M, A, D), then the project files and every other file. A merge lists its changes against its first parent, which is what it brought into the branch.
• Opening a changed object: a click shows what the commit changed in it, in the split editor's layout (Declaration above Implementation). The view is read-only, against the commit's first parent, at the first change.
  • The next object replaces it in the same tab.
  • Open Current Version (editor title) opens the object as it is now.
• Opening other files: any other file (project files, and POU files with only a rename or a metadata change) opens in VS Code's diff editor, as in GitLens. An added or deleted file is compared with an empty one. A POU's whole file opens as a notebook diff from its inline button.

TwinCAT History is like GitLens' file history, but per object.

• Which commits:
  • The commits of HEAD that changed one method, property, accessor, action, DUT or GVL, newest first, 50 at a time, back to the commit that created it.
  • The file is followed through renames and moves (git log --follow). Commits that changed only other objects of the file, or only metadata, are left out.
  • For a POU with methods or properties, the view lists the commits that changed any of its objects, each expanding to them.
• Which object:
  • The view shows the object of the active split editor or object notebook; Pin to This Object (view title) keeps it.
  • Show History is in the TwinCAT tree's context menu, in the title bar of the split editor and of the commit diff panel, and on the objects of the Changes and Commits views.
• Opening:
  • A click on a commit shows what it changed in the object, in the commit diff panel.
  • Compare with Working Version opens the object's split editor with its changes since that commit.
  • Uncommitted changes at the top opens the diff against HEAD.

Notebooks

• Object notebook: set twincatExplorer.editor to notebook, or use Reopen Editor With... > TwinCAT Object (Notebook) on a tab. Each section is one cell.
• Whole-file notebook: Reopen Editor With... > TwinCAT File (Notebook) shows a whole .TcPOU as one notebook.
• Notebook diff for git: Open Changes as TwinCAT Notebook compares a whole file with HEAD section by section, folding the unchanged sections. In Staged Changes it compares HEAD with the index.
  • The command is in the tree, Explorer and Source Control menus, and in the ... menu of a split editor tab.
  • Staged renames are followed, and an open comparison refreshes after a commit, checkout or stage.
  • Compare with Git Ref as TwinCAT Notebook... compares with any branch or commit, for example origin/develop when you review a merge request.
• Toolbars: the extension hides the cell toolbar of TwinCAT notebooks. VS Code has no switch per notebook type for the rest (Run All, Select Kernel, + Code, + Markdown), so TwinCAT: Hide Notebook Toolbars (XAE-like Layout) hides the top toolbar and the insert buttons for every notebook. It changes notebook.globalToolbar and notebook.insertToolbarLocation in the user settings, and the same command shows them again.

Requirements

• VS Code 1.95 or later.
• A workspace with TwinCAT 3 projects: a .tsproj and the .plcproj PLC projects it references. The extension activates when the workspace contains a .tsproj.
• Git, for the git features. The extension runs the git that VS Code's Git extension uses (its git.path setting), otherwise the first git.exe (git elsewhere) found in a full folder path of PATH. It never runs a program named git that sits in the workspace.
• Windows is the main target, since TwinCAT XAE runs only there. The extension does not depend on XAE being installed.
• No other extension. The git views are the extension's own, so GitLens is not needed; this README names it only to compare. VS Code's built-in Git extension is used when it is enabled: its git, its git documents, and its events to refresh open comparisons after a commit or checkout.

Installation

Install Explorer for TwinCAT from the Extensions view (Ctrl+Shift+X), or from the command line:

code --install-extension thanhdang.explorer-for-twincat

VS Code profiles have their own extensions, and the code CLI installs into the Default profile unless told otherwise. A window that uses another profile (see the gear menu > Profiles) then never loads the extension. Add --profile <profile> to the command, or install from the Extensions view of that window.

A .vsix file (see Development to build one) installs with Extensions: Install from VSIX... in the target window, or with:

code --install-extension explorer-for-twincat-<version>.vsix --profile <profile>

Reload the window after installing a new version over an old one.

To uninstall, use the Extensions view, or:

code --uninstall-extension thanhdang.explorer-for-twincat --profile <profile>

Getting started

1. Open a folder that contains a .tsproj. The TwinCAT view appears in the Explorer, and TwinCAT Changes, TwinCAT Commits and TwinCAT History appear in the Source Control sidebar.
2. Click a POU, method or property in the tree. It opens in the split editor, with the Declaration above the Implementation.
3. Edit and save with Ctrl+S. Only the sections you changed are written back to the XML file.
4. Use Ctrl+Alt+T to jump to any object, F12 and Shift+F12 to follow the code, and the Source Control views to review what changed.

Commands

All commands are in the Command Palette under the TwinCAT categories. The views add more in their title bars and context menus, for example Discard Changes, Copy Commit SHA and Copy Name.

Keyboard shortcuts

Extension settings

Library stubs

Beckhoff libraries ship compiled, so their declarations are not in the workspace. The extension bundles stubs for the parts in common use:

• Tc2_Standard: timers and triggers;
• Tc2_System: logging and memory functions;
• Tc2_Utilities: FB_FormatString;
• Tc2_MC2: axis function blocks;
• Tc2_Math, Tc3_Module and TcUnit.

Symbols of other libraries are reported as unknown. Add them to a stub file and list that file in twincatExplorer.stubFiles:

LIBRARY Tc2_EtherCAT
FUNCTION_BLOCK FB_EcGetSlaveCount
VAR_INPUT
	sNetId : T_AmsNetId;
	bExecute : BOOL;
END_VAR
VAR_OUTPUT
	bBusy : BOOL;
	bError : BOOL;
	nSlaves : UINT;
END_VAR
END_FUNCTION_BLOCK
END_LIBRARY

PLC projects of the workspace that other PLC projects reference as libraries are resolved from their sources.

Known issues and limitations

Editing and projects

• Only Structured Text is editable; other implementation languages are shown as read-only placeholders.
• Objects are created, renamed, moved and deleted in TwinCAT XAE.
• If TwinCAT XAE has the same project open, it keeps its own copy in memory and can overwrite changes saved from VS Code. Reload the project in XAE after editing here.
• The tree covers the PLC projects; I/O, motion and task configuration stay in XAE.
• PLC projects saved as independent project files (<Project File="X.xti"/> in the .tsproj) are not read yet.

Saving

• Safe saving applies to object tabs, in the split editor and in the object notebook. The TwinCAT File (Notebook) editor writes the whole file, so close it before the file changes in XAE or git.
• Reopen Editor With on a tab with unsaved changes shows the file on disk in the other editor. The changes stay in the first one, and a warning offers to go back to it.
• Compare with Saved on a split editor tab shows the raw text the editor works on (sections after marker lines). Closing that comparison while the tab has unsaved changes makes VS Code ask whether to save them.
• In VS Code 1.141, File: Revert File on a notebook (any notebook, Jupyter too) clears the unsaved marker without restoring the cells. To drop the unsaved edits of a TwinCAT notebook tab, close it and choose "Don't Save". The split editor reverts normally.

The split editor is a webview

• Extensions that work inside VS Code text editors (GitHub Copilot inline suggestions, vim keys, GitLens) do not reach it, and VS Code's Outline view stays empty for it.
• Its change markers are its own and compare with HEAD only, not with the index.
• Inside the panes, Monaco's own key bindings win.
  • Its Ctrl+K chords work: Ctrl+K Ctrl+C comments the line, Ctrl+K Ctrl+0 folds all.
  • So do the common VS Code chords: Ctrl+K S saves all, Ctrl+K W and Ctrl+K Ctrl+W close editors, Ctrl+K Ctrl+Left/Right moves to another group, and so on.
  • Your own Ctrl+K key bindings do not work there.

Problems and navigation

• The Problems panel lists the problems of open split editors per section (FB_X.Method · Implementation), with the line numbers of that pane.
  • Its Show Active File Only filter and the error colour of the tab title do not apply to split editors.
  • F8 inside a split editor moves only between the problems of that object.
• Opening a problem or a symbol briefly opens a read-only copy of the section, which the split editor then replaces. A copy opened pinned (double click, Ctrl+T) is closed instead, and Reopen Closed Editor then brings back the split editor of that object.

Git

• Line blame is git's, by lines of the XML file. The first and last line of a section share their line of the file with the CDATA tags, so a commit that added a line right before or after a section's text is also named for its first or last line.
• Merge commits are not listed in the TwinCAT History view; their changes come with the merged commits.
• Git compares paths case-sensitively. A file renamed only in case (FB_motor to FB_Motor) keeps its old name in git, so until the new name is committed (git mv), its comparison with HEAD, its history and its blame do not find it.

Troubleshooting

• The TwinCAT views do not appear.
  • The workspace must contain a .tsproj outside the folders of twincatExplorer.exclude and outside hidden folders.
  • Check that the extension is installed in the profile of this window (see Installation).
• A project or file is missing from the tree. The Explorer for TwinCAT output channel logs what was loaded, and every project file that could not be read. The tree marks such a project with a warning, for example a .plcproj with merge conflict markers.
• The git views say the projects are not in a git repository. Check that git is installed and on PATH, or that VS Code's Git extension finds it (git.path). Also check that the repository is not one git refuses as unsafe. Then run the view's Refresh.
• Language features miss a library. Add a library stub, or list the identifiers in twincatExplorer.diagnostics.ignore.

Release notes

See the changelog.

Development

npm install
npm run compile
npm run test:unit
npm run package

• npm run compile also type-checks src/webview and bundles it (Monaco, vscode-textmate, oniguruma) with esbuild into out/webview.
• npm run package builds explorer-for-twincat-<version>.vsix. npm run install:local -- <profile> installs it into that VS Code profile (default for the Default profile).
• node scripts/analyze-all.js <repoDir> and node scripts/coverage.js <repoDir> check the parser and the resolver on a whole TwinCAT repository.
• node scripts/third-party-notices.js writes ThirdPartyNotices.txt again after an update of the bundled packages.

License

Explorer for TwinCAT is released under the MIT License.

The split editor bundles Monaco Editor, vscode-textmate and vscode-oniguruma. Their licenses are in ThirdPartyNotices.txt.

Trademarks

Beckhoff® and TwinCAT® are registered trademarks of Beckhoff Automation GmbH. Explorer for TwinCAT is an independent project. It is not affiliated with, endorsed by or sponsored by Beckhoff Automation.