cds-text-sync

Turn a binary CODESYS project into a folder that Git, editors, CI tools and LLM agents can understand. Export the project, review or change its text on disk, then import it back into CODESYS.

This is an independent MIT-licensed tool, not an official CODESYS product.

1. Quick start

Requirements: Windows, CODESYS V3.5 SP10+ (SP13+ recommended), and Python 3.11+.

Install the tool and CODESYS menu scripts:

irm https://raw.githubusercontent.com/ArthurkaX/cds-text-sync/main/irm/setup.ps1 | iex

For each project, the important path is:

1. Open the project in CODESYS and run Project_directory.py. Choose the sync folder for this project.
2. Run Project_export.py. All supported .st and .csv text exports are enabled by default.
3. Edit project-view/ and commit the changes to Git.
4. Run Project_import.py to apply disk changes back to CODESYS.

That is enough for the first export/import cycle. Project_options.py is only needed for advanced settings such as sync mode, layout, profile or projection selection. See the installation guide if the scripts do not appear under Tools > Scripting.

2. Git workflows

Choose the workflow on an empty sync folder before the first export. The mode is fixed for that folder; changing it later means creating a new empty sync folder and exporting again.

I only want readable .st files

Choose text-first in Project_options.py.

• .st is the source of truth for Structured Text edits.
• Structural XML is kept in the tool-owned .dump/xml/ mirror instead of the normal Git view.
• This is the convenient mode for external editors, code review and LLM work.
• XML objects that must stay hand-editable, such as visualizations, can still be kept in the view.

I need full control, including XML

Keep the default XML-first mode.

• Native XML in project-view/ is the canonical round-trip format.
• Readable .st and .csv projections are generated beside it; all supported text projections are enabled by default.
• This mode is the right choice when Git must show and control devices, tasks, visualizations and other non-ST project structure as well.

More detail: sync modes, project layout, and team workflow.

3. I want to find errors in my project

Export the project first, then run the analyzer against its .st files. It is offline: no CODESYS window, daemon or PLC connection is required.

cts analyze --workspace C:\path\to\sync-folder
cts analyze --workspace C:\path\to\sync-folder --format sarif  # CI/code scanning
cts analyze rules
cts analyze explain CTS0007  # for example, indentation

You can open the desktop findings view with Project_analyze_ui.py. Safe autofixes are previewed before they are applied, including structural indentation fixes where available.

▶ Click to open the animation: Static Analyzer findings UI

Details: static analyzer.

▶ Click to open: Quick ST formatting inside CODESYS

Use Project_fmt.py from Tools > Scripting when one Structured Text object looks untidy and opening the full Analyzer would be unnecessary. It aligns variable declarations and repairs structural code indentation directly in the open IDE object.

1. Select a POU, GVL, or DUT in the project tree.
2. Run Project_fmt.py from Tools > Scripting.
3. Filter the object list or select a block. The list shows which blocks need formatting.
4. Open one block, or choose Review All to review blocks from the top.
5. Compare the Before and After panes. Changed characters are highlighted, and Previous change / Next change navigate the preview.
6. Choose Apply, Skip, or Stop. Use the normal CODESYS Undo command if you need to revert an applied change.

More details: Project_fmt script guide.

▶ Click to open the animation: FSM transition map

If your code is built around state machines and you often have to read one quickly — an unfamiliar CASE, or your own from six months ago — run Project_fsm.py from Tools > Scripting, or cts fsm ui from the shell. It reads the exported .st files offline and draws each machine as a GRAFCET diagram: numbered steps, one bar per transition with its receptivity beside it, and a step with several ways out fanned out as a divergence. Click a step or a transition row to highlight it; right-click either one to read the Structured Text it was drawn from.

More details: Project_fsm.py script guide and cts fsm.

4. I want an LLM agent to control the project

Start Project_daemon.py from CODESYS Tools > Scripting. It exposes the currently open project to the cts CLI. An agent can then export, inspect, change, compare, import and build without clicking through the IDE:

cts status                 # check daemon, project and sync folder
cts export                 # CODESYS -> project-view/
cts compare                # inspect IDE vs disk
cts import                 # project-view/ -> CODESYS
cts build                  # build the active application
cts analyze --workspace .  # offline check; daemon is not required

▶ Click to open the animation: using the cts CLI

The CLI also exposes project-tree operations, PLC interaction, tests and diagnostics. Read the CLI reference.

Generate visualization screens from SVG

An agent can create an SVG sketch as plain text, lint and preview it, compile it into a CODESYS visualization, and import the result through the same daemon:

cts visu new --name Line1 --w 1024 --h 600 --out line1.svg
cts visu lint --svg line1.svg --fix
cts visu preview --svg line1.svg
cts visu from-svg --svg line1.svg --create-screen --screen-name Line1
cts import

Details: HMI screens from SVG.

The current agent interface is the shell CLI. If an MCP server would fit your workflow better, open an issue and describe the tools your agent needs; that is a natural next adapter for the same daemon contract.

Documentation

• Installation
• Sync modes
• Script overview
• Project layout
• CLI reference
• Static analyzer
• HMI screens from SVG
• Profiles
• Releases and rollback

Issues, friction reports and feature requests are welcome in the GitHub issue tracker. See the changelog for release history.

MIT License.