nearxos
d98c44bfa3
PLC application sources (NVL, rooms, boiler), HA/Node-RED integration guide, and NVL patch utilities. Co-authored-by: Cursor <cursoragent@cursor.com>
119 lines
4.0 KiB
Markdown
119 lines
4.0 KiB
Markdown
# 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`.
|