Version: 2.8.3
Important
Disclaimer: This is a third-party tool. It is NOT an official product of CODESYS Group and is not affiliated with, sponsored by, or endorsed by CODESYS Group. This tool is provided "as is" and is not a replacement for official CODESYS products.
A CODESYS project is a single binary .project file. Git can store it, but it
cannot see inside: there is no diff, no line-by-line review, no way for two
engineers to merge their work, and no way for any external tool to read your
logic.
cds-text-sync turns that project into a folder of files on disk — one per
object, XML with optional readable .st and .csv text — which you keep in a
normal Git repository, review in pull requests, edit in any editor, and apply
back into the IDE. CODESYS stays the tool that talks to hardware; Git becomes
the tool that holds the history.
CODESYS project ──export──► project-view/ on disk ──► git commit, PR, review
▲ │
└──────────import──────────────┘
That is the core, and everything else in the tool is built on top of it. Once the project is text on disk, things that were impossible become ordinary — which is where the other two layers come from.
Export the open project to disk, edit it anywhere, bring the edits back.
Project_export.pycaptures a full native snapshot to.dump/IDE.xmland rebuilds the editable view inproject-view/.Project_import.pyapplies your disk edits back — textual objects through the CODESYS text APIs, the rest through native XML import — with an optional timestamped.projectbackup first.Project_compare_ui.pyreports what differs between the IDE and disk, as JSON and as a dialog inside CODESYS that can apply changes object by object.- Text projections make the code itself readable: POUs, their methods and actions, GVLs, persistent variable lists and DUTs as
.st; text lists and alarm items as.csv. A logic change then shows up once, in the.stfile, instead of twice in XML and text. - Overwrite protection means export never silently discards a local edit you have not imported yet, and never deletes a file it does not own.
- Profiles describe vendor and fork-specific object kinds, which projections are available, and the safety rules — so a DIAStudio or KeStudio project behaves correctly rather than approximately.
Two paradigms, chosen once per sync folder: XML-first keeps native XML as the
canonical round-trip format with text projections beside it, and text-first
makes the .st files the source of truth and hides the structural XML in a
tool-owned mirror. See Sync modes.
The scripts above live in the CODESYS Tools > Scripting menu and need a human
to click them. Project_daemon.py runs inside the IDE and exposes it over a
per-user Windows named pipe; the cts CLI talks to that pipe. Anything that can
run a shell command can now drive CODESYS — a CI job, a Makefile, or an LLM agent
working on its own.
cts status # daemon / project / sync-folder / PLC state
cts export # IDE -> project-view/
cts import # project-view/ -> IDE
cts build # build the active application
cts test --file plan.json # JSON-defined test planBeyond the sync cycle it covers build execution and logs, PLC connect / start / stop / reset, variable read and write, variable map / snapshot / restore, PLC file listing and transfer, application CRC for deployment verification, project lifecycle (open, close, list devices, simulate, credentials, online diagnostics), object-level read / update / delete, environment discovery, and JSON or text output on every command.
This is the layer that makes autonomous work possible: an agent can read the project, change it, build it, check the result, and iterate — without a person in the loop clicking dialogs. See the CLI reference.
The last thing in a CODESYS project that resisted text was the visualization.
cts visu closes that: you author the screen as an SVG sketch — text, so it
diffs and reviews like everything else — and the tool compiles it into a real
CODESYS visualization object.
The point is who writes the SVG. cts visu --help prints the entire contract
inline — supported tags, semantic classes, colour variables, what is
unsupported — so an LLM agent needs no other documentation to produce a valid
screen, and lint plus preview let it check its own work before anything
reaches the IDE. You never write a colour: an element carries class="panel" or
class="value", and the palette resolves against your project's visual style, in
a light or a dark scheme, from the same unchanged sketch.
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 --gvl VisuVars
cts import--gvl generates the GVL declarations for every PLC variable the screen binds,
so the screen arrives wired rather than referencing names that do not exist.
Full walkthrough: HMI screens from SVG.
Requirements: CODESYS V3.5 SP10+ (SP13 and newer recommended), Windows, and
Python 3 available as python. Full list in
Installation.
Install with one command — it sets up the tool, the CLI, and the CODESYS scripting menu:
irm https://raw.githubusercontent.com/ArthurkaX/cds-text-sync/main/irm/setup.ps1 | iexThen, in CODESYS, from Tools > Scripting > Scripts > P:
Project_directory.py— link the open project to a folder on disk.Project_options.py— pick the sync mode, layout, profile, and which.st/.csvprojections you want.Project_export.py— write the snapshot and buildproject-view/.- Edit the files in
project-view/in any editor, and commit them. Project_import.py— apply the disk edits back into CODESYS.
For layers 2 and 3, install the CLI and start the daemon:
python -m pip install -e <program-folder>
cts --helpDetails: Installation · Script overview · Project layout · CLI reference
| Guide | What is in it |
|---|---|
| Installation | Requirements, the three install methods, CLI install, upgrading |
| Sync modes | XML-first vs text-first, and overwrite protection |
| Script overview | What each Project_*.py does, and the optional projections |
| Project layout | On-disk structure, .gitignore, the day-to-day cycle, Git LFS |
| CLI reference | Every cts command, flag, timeout and error mode |
| HMI screens from SVG | cts visu end to end, including PLC variable binding |
| Team workflow | Branches and PRs for HMI/hardware engineers and developers |
| Alternative installations | Forks and non-standard CODESYS environments |
| Releases & rollback | Stable tags, version policy, reverting |
| Profiles | Vendor/fork object kinds, projection availability, safety rules |
| SVG authoring contract | Layout rules and conventions an authoring model follows |
Diagnostics live in the CLI and the scripts alike: Project_build.py,
Project_discover.py and Project_resources.py write build, environment and
snapshot-size reports, and cts engine call-tree builds a static call graph
offline. For Zed users,
PLC Structured Text
adds IEC 61131-3 syntax highlighting for the generated .st / .iecst files.
To keep this repository lightweight for users who git clone the scripts, all
test cases, problematic objects, and compatibility examples are hosted in a
separate
Reference Project.
Refer to that repository's README for detailed verification procedures.
This is a third-party tool maintained by one person, and nearly every feature and fix in the changelog traces back to a user who took a few minutes to describe a problem. If you use it, you are in a better position than anyone to say what should change.
Pick whichever costs you the least effort:
| I want to... | Where |
|---|---|
| Report something broken | Bug report |
| Say what is confusing or tedious — no repro needed | Friction report |
| Ask for something the tool cannot do | Feature request |
| Ask whether something is a bug or expected | Q&A discussion |
| Say something that is none of the above | Discussions |
| Influence a roadmap decision in one click | Polls |
| Just react to what is planned next | Open roadmap issues |
Note
Discussions are open, and quieter than they should be. If you have something to say that does not fit an issue — a doubt about the direction, a workflow this tool does not serve, an opinion on a decision that is being made — that is what Discussions are for. You do not need a proposal, evidence, or a solution. An objection with nothing behind it but experience is still worth reading.
And if something simply feels awkward to use, there is a form for exactly that — no reproduction steps, no version numbers, half a sentence is enough.
Bug reports are usually resolved within a day or two. Reporters are credited by name in the changelog. Corporate users: internal criticism is welcome here too — an anonymized "our team keeps tripping over X" is more valuable than silence, and you do not need permission to describe a workflow problem.
See the full CHANGELOG.md for details on all versions, and GitHub Releases for stable download links. Contributions: CONTRIBUTING.md.
MIT License.