CODESCRIBE

/koh-DEH-skribe/

CODESYS plaintext import and export scripts.

No python installation is required to use the scripts as CODESYS ships with its own copy of Python 2.

CODESCRIBE supplies CODESYS scripts to:

• export a project to plaintext files that can be tracked in source control, as well as edited in other editors
• import plaintext files back into a CODESYS project for uploading / debugging / etc
• generate a "template" project by making a copy of the current project and deleting all exportable objects
• update the current working project from a template by copying the template file and importing plaintext files

With CODESCRIBE, a CODESYS project like this:

Becomes a plaintext project like this:

The following items are exported:

• Folders
• POUs
• EVLs
• EVCs
• Task Configurations
• DUTs
• Methods
• Properties
• Actions
• Transitions
• Communication Devices*

*see Exporting and Importing Communication Devices

Items are exported in formatted structured text (.st) where possible, and in native CODESYS xml everywhere else.

Project Templates

The intention of CODESCRIBE is not to export a complete copy of the project, but to only export the implementation logic of the project, enabling collaboration via git and other source control methods. An empty, but configured, underlying project file should also be committed to the repo to manage any other configuration that CODESYS provides (e.g. project level configuration, device configuration). For example, Example Project_template_v1.project:

Note, it is recommended to not source control the actual working copy of the project (Example Project.project) to avoid duplication.

A template file can be generated from an existing project file by using the Save As Template script. This script will copy the project, give it the appropriate name and delete any objects that can be imported by CODESCRIBE. If an existing project following the template naming scheme is found, the new template will use an incremented version number.

To generate a project from a template file, you need two things: the <project_name>_template_v<X>.project file and a folder named <project_name> with the files exported by the Export To Files script. To generate a project, copy the template project in the same location and rename it to <project_name>.project. Open the copy with CODESYS and use the Import From Files button to import the project files.

Library Projects (.library)

CODESCRIBE also supports CODESYS library projects (.library), not just device projects (.project). A project is treated as a library when its file has the .library extension (with a fallback: any project that contains no devices is treated as a library too).

For libraries there is no Device / Application node, so objects are exported/imported directly from the project root into the source folder, and communication devices are not involved. The Save As Template / Update From Template workflow works the same way and preserves the .library extension on generated template files.

Importing only changed files (faster imports)

For library projects, Import From Files is incremental: it keeps a local hash manifest (<name>.codescribe_manifest.json, next to the project file) of the files produced by the last export/import. On the next import it only re-imports files whose content changed, creates new files, and removes objects whose files were deleted. This greatly reduces import time on large libraries.

The manifest is a local cache and is git-ignored. On a fresh clone (no manifest) the first import is a full import; subsequent imports are incremental. Update From Template always does a full import because it starts from a freshly copied template.

Incremental export (clean git diffs)

For libraries, Export To Files is incremental too: it exports everything to a temporary folder and then writes only the files that actually changed into the source folder (and removes files whose objects were deleted), keeping git diffs minimal. Note that every object must still be serialized to detect changes, so this keeps diffs clean but is not necessarily faster than a full export.

Exporting / importing only a subfolder

When exporting or importing a library, CODESCRIBE first asks whether to operate on the whole project or just a specific subfolder (entered as a path relative to the source folder, e.g. POUs/Math). This is handy for large libraries where you only touched one area. (The text-input prompt uses system.ui.query_string; if it is unavailable it falls back to the whole project.)

Library metadata snapshot

Export To Files additionally writes a snapshot of the library metadata (Library Manager / Project Information) as native XML into a sibling <name>_metadata folder, so changes to referenced libraries or version info show up in git diffs. This snapshot is intentionally kept out of the tracked object set and is never re-imported — the project template still carries the authoritative configuration.

Exporting and Importing Communication Devices

Exporting communication devices has been hardcoded to create folders for top-level devices under Communication. Any devices under these top-level devices will be exported using native CODESYS xml. This is done because the top-level devices can not be removed from the CODESYS project.

If this functionality is causing you problems, it can be disabled by adding a folder with the name _NO_EXPORT directly under Communication. You can then still rely on your project template to carry your communication configurations.

Status

CODESCRIBE has been tested only on CODESYS V3.5 SP11, using the project structure supplied by the IFM CR711s packages.

Installing

Using the install script

Using the install script requires Python 3 to be installed on your system (https://www.python.org/downloads/).

Once the repo is cloned, run install.bat as administrator. This will in turn run install.py.

Once installed, proceed to Adding the Script Toolbar to CODESYS.

Installing manually

Copy config.json to C:\<CODESYS INSTALL LOCATION>\CODESYS\Script Commands. The Script Commands folder may need to be created.

Open the copy of config.json and edit the "Icon" and "Path" fields to point to their respective locations in cloned repo (under src and icons). For example, this config:

"Icon": "export_to_files.ico",
"Path": "script_export_to_files.py",

Should be changed to:

"Icon": "<PATH TO REPO>\\icons\\export_to_files.ico",
"Path": "<PATH TO REPO>\\src\\script_export_to_files.py",

NOTE: the escaped backslashes (\\) are required for windows paths in json

Once installed, proceed to Adding the Script Toolbar to CODESYS.

Adding the Script Toolbar to CODESYS

1. Select Tools -> Customize

   

2. Select Toolbars

   

3. Select the blank toolbar at the bottom of the list and click "Add toolbar". Call it Scripts.

   

4. Expand Scripts, select the blank spot and click "Add command"

   

5. Under Categories, scroll down, select ScriptEngine Commands and pick the script you want to add

   • Scripts supplied by this repo are Export To Files, Export From Files, Save As Template and Update From Template

   

6. Repeat the process to add the other scripts

   

7. Click OK to save changes

   

8. You should now have new icons available in your toolbar

   

CODESYS Scripting Docs

• https://help.codesys.com/webapp/idx-scriptingengine;product=ScriptEngine;version=3.5.10.0
• C:\<CODESYS INSTALL LOCATION>\CODESYS\Online Help\en\ScriptEngine.chm

Similar Projects

• https://github.com/18thCentury/CodeSys

License & Attribution

Licensed under the Apache License, Version 2.0 — see LICENSE and NOTICE.

This project is a modified fork of CODESCRIBE by the CODESCRIBE authors (including Greenforge Labs). See NOTICE for details of the original work and the changes made in this fork.