# 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:

```json
{
  "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`.