codesys-home-automation/codesys-tree/README.md

Local CODESYS Tree

Local mirror of the CODESYS project staged at:

C:\codesys-projects\Codesys_Home_Automation\Home_Automation.project

This tree was generated from the read_project_inventory MCP call so you can edit POUs, GVLs, DUTs and Programs directly in Cursor on macOS, then push the changes back to the Windows VM with the sync_project MCP tool.

Layout

Mirrors the CODESYS POU pane:

Device/
  Plc Logic/
    Application/
      PLC_PRG.st
      0.Structures/   - DUTs (struct_*)
      1.Variables/    - GVLs (NVL_Sender, NVL_Receiver, GVL)
      2.Functions/    - (empty)
      3.Function Blocks/
      4.Programs/

Hardware / non-textual nodes (Device, EtherCAT_Master, EK1100, K1..K4, GPIOs_A_B, Onewire, Camera device, SPI, I?C, Task Configuration, Library Manager, Project Settings, __VisualizationStyle) are not mirrored as files — they live only in the .project XML and are listed in _manifest.json under non_textual_tree for reference.

File format (.st files)

Each file contains a single CODESYS object. Two sections are delimited by sentinel banner comments so the splitter is unambiguous:

(* === DECLARATION === *)
<everything that goes in the declaration editor (VAR blocks, header, attribs)>

(* === IMPLEMENTATION === *)
<the ST body — empty for DUTs / GVLs / declaration-only programs>

If a section is empty, leave the line after its banner blank — do not delete the banner. The sync helper expects both banners to be present.

Manifest

_manifest.json maps every .st file back to its CODESYS object_path (e.g. Device / Plc Logic / Application / 3.Function Blocks / fb_light) and records whether the object originally had a declaration and/or implementation. This is what the sync step uses to build the textual_updates payload.

I/O snapshot

_io.json is the raw output of read_device_io (all devices + channels + variable mappings + IEC addresses).

_io.md is the human-readable summary: per-device tables, current mappings against NVL_Sender.*, plus a "findings worth flagging" section that highlights duplicates, unmapped channels, and gaps between the FB logic and the physical wiring.

Refresh both with read_device_io then regenerate. The IO snapshot is read-only here — to push mapping changes back, use the write_io_mapping tool (or the io_mappings list inside sync_project).

Workflow

1. Edit locally

Open any .st file in Cursor and edit either the declaration or the implementation section. Don't move the banner lines.

2. Dry-run sync (preview)

Call the MCP tool sync_project with dry_run: true and a textual_updates list built from the files you changed. Each entry looks like:

{
  "object_path": "Device / Plc Logic / Application / 3.Function Blocks / fb_light",
  "declaration": "FUNCTION_BLOCK fb_light\nVAR_INPUT\n  ...\nEND_VAR",
  "implementation": "// ST body here"
}

3. Apply

Re-run sync_project with dry_run: false. The agent opens the project once, applies all updates in a single open/save cycle, and reports back per-object status.

4. Build

After a successful sync, run build_project to verify the project still compiles on the VM.

Re-syncing from CODESYS → local

If the project changes on the Windows side, re-run read_project_inventory and regenerate the affected .st files plus _manifest.json. Treat the VM project file as the source of truth for the structure (folders, object kinds, IO mappings); treat the local tree as the source of truth only for content you've edited here.

Not included

These items live in the project but are not mirrored as files:

• Library Manager (library refs — managed in CODESYS UI)
• Task Configuration / MainTask / EtherCAT_Task (task settings)
• Device / fieldbus nodes (Device, EtherCAT_Master, EK1100, K1..K4, GPIOs_A_B, Onewire, Camera device, SPI, I?C) — manage via manage_device, read_device_io, write_io_mapping.
• Project Settings, SoftMotion General Axis Pool, __VisualizationStyle.