codesys-migrator

A command-line tool that helps you move old CODESYS V2.x PLC programs to the modern CODESYS V3.5+ platform, with optional Raspberry Pi targeting.

What Does This Do?

If you have a PLC project built in the older CODESYS V2.x IDE and need to upgrade it to V3.5+, this tool automates the tedious parts:

1. Reads your old project files (.exp exports, .st source, .xml, or binary .pro)
2. Analyzes the code for issues — deprecated function blocks, missing libraries, V2→V3 breaking changes
3. Transforms the code — fixes data types, maps old libraries to new ones, generates placeholder stubs for anything it can't map
4. Outputs clean V3.5-compatible Structured Text files and PLCopen XML ready to import into the CODESYS V3 IDE

It does not replace the CODESYS IDE — you still import the output into CODESYS V3 for final compilation and deployment.

Quick Start

Prerequisites

• Python 3.11+ installed (python.org)
• Your CODESYS V2 project exported as a .exp file (see How to Export below)

Install

git clone <this-repo>
cd codesys-migrator
pip install -e .

Run the Full Pipeline

# Step 1: Recover — resolve libraries, generate stubs for missing ones
codesys-migrator recover MyProject.exp --out recovered/

# Step 2: Analyze — see what issues exist before migrating
codesys-migrator analyze recovered/ --output report.json

# Step 3: Migrate — transform V2 code to V3.5+ format
codesys-migrator migrate recovered/ --out migrated/

# Step 4 (optional): Adapt for Raspberry Pi
codesys-migrator target migrated/ --device raspberrypi --out deploy/

# Step 5: Open CODESYS V3.5+ IDE → File → Import → select deploy/MyProject.xml

That's it. Each step produces a folder of files you can inspect and edit before moving on.

Supported Input Formats

Format	Extension	What You Get
CODESYS V2 Export	.exp	Full parsing — this is the primary input format
Structured Text	.st	Full parsing — standalone ST source files
PLCopen XML	.xml	Full parsing — TC6-standard XML projects
CODESYS V2 Binary	.pro	Metadata only — library names, POU names, version info

.pro files are proprietary binary. You cannot extract program logic from them without the CODESYS V2 IDE. Export to .exp first (instructions below).

Commands Reference

Command	Purpose	Example
recover	Fix a broken project: resolve libraries, generate stubs	codesys-migrator recover input.exp --out recovered/
extract	Extract POUs into individual .st files	codesys-migrator extract input.xml --out extracted/
analyze	Run static analysis and produce a report	codesys-migrator analyze recovered/ --output report.json
migrate	Transform V2 code to V3.5+ format	codesys-migrator migrate recovered/ --out migrated/
target	Adapt for a specific device (Raspberry Pi)	codesys-migrator target migrated/ --device raspberrypi --out deploy/

Run codesys-migrator --help or codesys-migrator <command> --help for full options.

How to Export from CODESYS V2

If you only have a .pro file, you need to export it first:

1. Open the project in the CODESYS V2.x IDE (the old one, not V3)
2. Go to File → Export...
3. Select All POUs, data types, and global variables
4. Save as a .exp file
5. Now you can run: codesys-migrator recover MyProject.exp --out recovered/

What Gets Migrated

Area	What Happens
Data types	STRING → STRING(80) (preserves V2 default length), pointer/array types mapped
Libraries	Standard.lib → Standard, Util.lib → Util, SysLibTime.lib → SysTime, etc.
Missing libraries	Stub function blocks generated with placeholder logic + clear warnings
Deprecated FBs	SysTimeGetMs → SysTimeRtcGet, other V2-era FBs replaced
Task config	MainTask added if missing, with 20ms default cycle
Raspberry Pi	I/O addresses cleared (RPi uses different mapping), GPIO helper FB added, minimum 4ms task interval

AI Integration (MCP Server)

You can connect this tool to VS Code Copilot Chat or Claude Desktop so an AI assistant can analyze and migrate projects for you through conversation.

VS Code Setup

1. Install with MCP support:

   pip install -e ".[mcp]"

2. Add to .vscode/settings.json in any workspace:

   {
     "mcp": {
       "servers": {
         "codesys-migrator": {
           "type": "stdio",
           "command": "python",
           "args": ["-m", "codesys_migrator.mcp.server"]
         }
       }
     }
   }

3. Restart VS Code. In Copilot Chat (Agent mode), you can now say things like:

   • "Analyze the CODESYS project at C:\projects\MyPLC\exported.exp"
   • "Migrate the project in recovered/ to V3.5 for Raspberry Pi"

The MCP server exposes 4 tools:

Tool	What It Does
analyze_project	Static analysis — finds issues, produces JSON report
migrate_project	Full V2→V3 migration with file output
recover_project	Library resolution + stub generation
extract_project	Parse a project file into individual .st files

Claude Desktop Setup

Add to your Claude config file (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "codesys-migrator": {
      "command": "python",
      "args": ["-m", "codesys_migrator.mcp.server"]
    }
  }
}

Verify the MCP Server Works

python -c "from codesys_migrator.mcp.server import mcp; print([t.name for t in mcp._tool_manager.list_tools()])"
# Should print: ['analyze_project', 'migrate_project', 'recover_project', 'extract_project']

Library Mapping Database

Built-in mappings for common CODESYS V2 libraries:

V2 Library	V3 Equivalent	What Happens
Standard.lib	Standard	Automatically mapped
Util.lib	Util	Automatically mapped
SysLibTime.lib	SysTime	Automatically mapped
SysLibCallback.lib	(removed in V3)	Stub generated
oscat_basic_333.lib	OSCAT Basic	Automatically mapped
Building_common.lib	(vendor-specific)	Stub generated

Unknown vendor libraries get stub function blocks with clear (* WARNING *) comments so you know what to replace.

Project Structure

codesys_migrator/
├── cli/main.py              # CLI commands (Typer)
├── parser/                  # Input file parsers
│   ├── plcopen_xml.py       # PLCopen XML (.xml)
│   ├── exp_parser.py        # CODESYS V2 export (.exp)
│   ├── st_parser.py         # Structured Text (.st)
│   └── pro_binary.py        # Binary metadata (.pro)
├── recovery/                # Library resolution + stub generation
├── analyzer/                # Static analysis + compatibility checks
├── transformer/             # V2→V3 transformation + PLCopen XML output
├── targets/                 # Device-specific adapters (Raspberry Pi)
├── models/project.py        # Internal data model (Pydantic)
├── mcp/server.py            # MCP server for AI integration
└── utils/constants.py       # Library mappings, IEC standard definitions

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

48 tests covering all parsers, the analyzer, recovery engine, and migration transformer.

Limitations

• Binary .pro files — metadata only (library names, POU names, version). You must export to .exp from the CODESYS V2 IDE for full logic extraction.
• Graphical languages — FBD, LD, SFC are detected but only Structured Text (ST) bodies are fully parsed and migrated.
• Vendor libraries — Libraries without known V3 equivalents get stub FBs with no real functionality. You must replace them with the actual V3 implementation.
• Not a compiler — This tool transforms source code. You still need the CODESYS V3 IDE to compile, simulate, and deploy.
• PLCopen XML variations — Handles common TC6 namespace versions. Some vendor-specific extensions may not parse correctly.

License

MIT — see LICENSE.