Codesys Loop

CODESYS development loop

src/HomeAutomation.project is a binary. It cannot be read, diffed or edited as text. The way in and out is PLCopen XML, which CODESYS both exports and imports — and because CODESYS ships a ScriptEngine and runs with --noUI, the real compiler can judge the result. Never reason about ST correctness from the XML alone when you can compile it instead.

Two entry points, both committed at a normal path so CI and contributors can use them too, not only agents:

• tools/ai/codesys.ps1 — the wrapper you run.
• tools/ai/codesys_task.py — runs inside CODESYS (IronPython 2.7). Don't run it directly.

Check the toolchain first

./tools/ai/codesys.ps1 doctor

Fast, does not launch CODESYS. Required:

Override discovery with -Exe / -CodesysProfile, or set $env:CODESYS_EXE.

Python is not needed by this harness — only by the update-fb-docs skill. doctor reports it as a warning, not a failure.

Installing Python (for the docs generator only)

gen_fb_docs.py needs 3.7+ (it uses f-strings and from __future__ import annotations). Install a current release:

winget install --id Python.Python.3.12 --scope machine

Then open a new shell and verify:

py --version

Two Windows gotchas worth knowing before you debug a "Python was not found" message:

• winget installs the python.org build, which provides python.exe and the py launcher but no python3.exe. On this machine, invoke the docs generator as py .claude/skills/update-fb-docs/scripts/gen_fb_docs.py.
• Windows ships an App Execution Alias stub for python/python3 that opens the Microsoft Store instead of running anything. If a bare python still opens the Store after installing, turn the aliases off under Settings → Apps → Advanced app settings → App execution aliases. doctor already ignores anything resolving inside WindowsApps for this reason.

Tasks

Each task boots CODESYS, so budget 40–90 seconds. A --noUI process has no usable stdout: results go to .ai/reports/<task>.json, with a progress log at <task>.json.log that survives a crash. .ai/ is gitignored.

.ai/work is wiped at the start of every verify and simulate — it is the sandbox. Never keep anything there. Edit fragments belong in .ai/edits/.

Working on another project

-Project <path> points any task at a different .project file — that is how sync-implementation-project drives a building's installation project. Reports are then stem-qualified (baseline.SiteA.json), so a foreign build cannot overwrite this project's baseline. download refuses -Project.

Four companions to it:

The last two fail the same way — silently, with a green build — and a candidate lifted out of another project needs both.

Workflow

1. Confirm the export is current before trusting it:

   git log -1 --format=%cd -- src/Exports/PLCopen.xml src/HomeAutomation.project

   If the project is newer, run export first. Regenerating docs or reasoning about pins from a stale export bakes in wrong interfaces.

2. Record a baseline once per session: verify -Baseline. The project builds with 9 pre-existing warnings — three OSCAT CONSTANTS_SETUP string-length warnings, three IP_CONTROL2 sign conversions, GVL_PERSISTENT, one genuine sign conversion in PRG_DMX_SEND line 70, and one for PRG_DALI_VERIFY.Dimmer.DimValue having no persistent list on Wago_PFC200_G2_Virtual. That last one is load-bearing: it is only reported because the DALI block really is compiled there, so if it ever disappears, the verification application has stopped verifying. The application is never downloaded, so nothing needs retaining. With a baseline recorded, verify prints a NEW vs baseline section so your own changes stand out. Re-record after a library or CODESYS version change.

3. Read the current code from src/Exports/PLCopen.xml: declarations, ST bodies, methods and the task configuration are all there.

4. Write the change as a single-block PLCopen file in .ai/candidates/. Start from tools/ai/templates/FB_TEMPLATE.xml, which documents the dialect. For anything non-trivial, copy the shape of a comparable existing block out of PLCopen.xml rather than inventing structure.

5. Verify — ./tools/ai/codesys.ps1 verify. This copies the project to .ai/work, imports the candidates, builds, and reports every message with object, line and column. Iterate here; the real project is untouched. Read the harness section of the report, not just the result line (see below).

6. Apply only once verify is clean: apply -Force. It refuses to save if the build fails. Then re-export so the XML matches the binary again, and update the docs with the update-fb-docs skill.

Steps 6 onwards change tracked files, including a binary. Ask before running them unless the user has already said to land the change.

Changing an existing POU: use edits, not candidates

A candidate XML import REPLACES the whole object, so it is right for a new block and wrong for changing an existing one — a partial file silently drops every method it omits, and appending to an existing POU's plaintext declaration is ignored outright. For existing code use .ai/edits/edits.json, which drives the ScriptEngine's textual API and is applied by both verify and apply:

{ "edits": [
    { "pou": "FB_MQTT_BASE",  "decl_append_file": "base.decl",
      "skip_if_contains": "FriendlyName" },
    { "pou": "FB_OUTPUT_BINARY_MQTT", "body_prepend_file": "prologue.st",
      "skip_if_contains": "self-wiring prologue" },
    { "pou": "PRG_MAIN",  "decl_replace_file": "main.decl" },
    { "pou": "PRG_MAIN",  "member": "MAIN_INIT", "body_replace_file": "main_init.st" }
] }

Notes that cost real time to rediscover:

• Always set skip_if_contains on an append or prepend. An edit spec gets re-run constantly during a refactor, and without the sentinel a second run duplicates the text. *_replace needs no guard.
• *_file paths resolve relative to the spec file, then to the repo root. Keep fragments in .ai/edits/ — never .ai/work, which verify deletes.
• A name stops identifying a POU as soon as a project has two controllers. An installation with two PFCs has two PRG_MAIN, both real, both owning text, and every edit addressed by name alone is then refused as ambiguous. "path": "Wago_G1_Annex/" picks one. The refusal is the useful behaviour — the alternative is a coin flip over which building gets rewritten — so do not work around it by renaming a program. delete_pou has no such qualifier yet; it will report the same ambiguity and stop.
• insert() takes the offset first, the reverse of the shipped stub. Same trap as export_xml.
• create_method works on an INTERFACE too, which is how a method reaches I_RS485_DEVICE or I_RS485_TRANSPORT without hand-authoring interface XML: the interface object owns text, so create_method plus decl_replace is the whole job. Every implementer then needs the same method or the build fails by name — which is the useful failure, and how the six RS485 device blocks were kept in step when GetCommissioning was added.
• A /// doc comment written by decl_replace does not reach the export. CODESYS only materialises <documentation> for a comment its own editor parsed, so a method created from a script exports with its plaintext declaration intact and no structured documentation — and update-fb-docs therefore shows it as _TODO: describe this._ however carefully the fragment was commented. Write the description in the doc page, or in the generator's GLOSSARY when the method means the same thing on every block.
• -Edits none skips the spec, which is how you build the committed project standalone as a control. A verify -Baseline never applies edits.
• Generating the fragments from a script (see .ai/edits/gen.ps1 in history) beats hand-writing 14 near-identical prologues.

Renaming: rename, not edits

Renaming is its own task because node.rename() renames an object and updates nothing that refers to it — CODESYS's IDE refactoring is not exposed to the ScriptEngine. The references are the harness's job:

./tools/ai/codesys.ps1 rename -Map tools/ai/rename/179-objects.json -DryRun
./tools/ai/codesys.ps1 rename -Map tools/ai/rename/179-objects.json -Force

The map holds objects (a type, block, program or GVL — the name is project-unique, so every occurrence of the token is that object) and identifiers (variables inside one declaring object). An identifier group's mode decides how far it reaches:

Five things learned building it, all of which cost a run:

• A program rename is two renames. The task configuration calls a program through a separate object that carries the program's name and owns no code, so every text-owning filter misses it. Renaming the program alone gives Identifier 'PLC_PRG_MAIN' not defined <.../Task Configuration/MainTask>. The task now renames the call twin too, and reports it as (task call).
• One name can mean several objects. Two applications mean two MqttVariables, and FB_MQTT_BASE declares STRING(GVL_MQTT.MQTT_TOPIC_LEN), so the name has to resolve in both. Ambiguity is refused unless the map says {"new": ..., "all": true} — or "path" to pick one.
• A shadow is the one mistake that compiles. PRG_DALI_VERIFY declared an instance called Dimmer while the enumeration Dimmer was becoming E_DIMMER; a blind sweep renames the instance too, consistently, and the build stays clean with a variable now called E_DIMMER. The task refuses an object rename whose old name is also declared as a variable, and identifier groups run first so one map can move the variable out of the way.
• Dry-run counts are an upper bound. Passes do not compose without writing, so a map that renames both a variable and an object of the same name double-counts: 515 references in -DryRun versus 473 actually rewritten.
• String literals are never touched, comments always are. Topics, discovery keys and JSON live in literals; a comment still naming the old object is worse than no comment.

Afterwards: verify -Baseline (object paths moved, so the old baseline reads every unchanged warning as NEW), export, then update-fb-docs. The docs generator keys the GVL region on the list's name, so a GVL rename means editing gen_fb_docs.py too.

Authoring candidates: what the importer actually accepts

Established by compile probe, not by reading documentation:

• A hand-written candidate CAN file itself into a folder. The skill's own advice used to be that a candidate with no folders lands at the project root, which is true only because nobody had put folders in one. Add a projectstructure <addData> block naming the target folder and the object, with no ObjectId attributes at all, and the default import path honours it - the report then reads added: BASIC/FB_YOUR_NAME rather than a bare name. Worth doing: folder placement is cosmetic to the compiler, but there is no scripted way to move an object afterwards, so the alternative is IDE hand-work.

  <addData>
    <data name="http://www.3s-software.com/plcopenxml/projectstructure" handleUnknown="discard">
      <ProjectStructure>
        <Folder Name="BASIC">
          <Object Name="FB_YOUR_NAME">
            <Object Name="InitMqtt" />
          </Object>
        </Folder>
      </ProjectStructure>
    </data>
  </addData>

  The methods are listed as nested <Object>s; the import adds each and reports it. FB_INPUT_TEMPERATURE_RTD_MQTT landed in BASIC/ this way.

• Plaintext declarations work for a NEW POU, but do not reliably override an existing one. Authoring a brand-new block with a plaintext declaration and an empty <interface /> works (proven). But taking an existing POU out of the export, appending a VAR_INPUT block to its plaintext declaration and re-importing it does not apply the new members: the block keeps exactly its old declaration, the import still reports replaced 1, and the only symptom is Identifier 'X' not defined in whatever referenced the new member. Emptying the structured <interface> did not change this. Unresolved — the next attempt should isolate it by (a) removing the <interface> element entirely rather than emptying it, (b) trying a plain INT member to rule out the enum type, and (c) comparing against editing the structured <interface> instead, which is the safer default until this is understood. Prefer the ScriptEngine textual API (textual_declaration.append) for editing an existing POU's declaration; that path is already proven by the verify harness, which injects into a real program this way on every run.

• A <dataType> takes <baseType> then <addData>, and nothing else. There is no <documentation> child on a DUT in tc6_0200; adding one fails the whole file with

  The element 'dataType' ... has invalid child element 'addData'

  which names the wrong element and reads like an ordering problem, so the obvious fix — shuffling the children — does not help. Put a type's prose in the per-value enumvaluedocumentation block instead. The import failure is easy to miss: verify reports it in imports[].errors, then the build fails with a hundred Identifier not defined errors for the type, and the real message is the first one, not the hundred. E_RELAY_TYPE was authored this way — copy it.

• For a NEW POU, put the plaintext declaration in an <addData> block on the <pou>:

  <data name="http://www.3s-software.com/plcopenxml/interfaceasplaintext" handleUnknown="implementation">
    <InterfaceAsPlainText>
      <xhtml xmlns="http://www.w3.org/1999/xhtml">FUNCTION_BLOCK FB_X EXTENDS FB_MQTT_BASE
  VAR
      x : INT;
  END_VAR</xhtml>
    </InterfaceAsPlainText>
  </data>

  The importer prefers it over the structured <interface>, it is lossless, and EXTENDS works. Get a template by running export -Plaintext, which writes .ai/reports/PLCopen.plaintext.xml with every POU in this form.

• A METHOD's interface must be structured XML. A nested InterfaceAsPlainText inside a <Method> is silently ignored, so the method is built from the structured <interface> instead — which produced a malformed FB_init that failed in four different ways at once. For FB_init that means <returnType><BOOL /></returnType> plus bInitRetains, bInCopyCode and your own parameters as <inputVars>.

• qualified_only is set on every GVL here (GVL_MQTT, GVL_DALI, GVL_PERSISTENT, GVL_DMX, GVL_RS485), so a POU body must write GVL_MQTT.fbMqttPublishQueue, never the bare name.

FB_init and inheritance, as this compiler actually behaves

• A derived FB that declares no FB_init of its own still accepts the base's FB_init parameters at the declaration site: inst : FB_DERIVED(sFriendlyName := 'Kitchen');. Declare FB_init once on the base and the whole hierarchy inherits the parameter.
• FB_init may read a GVL value and may take ADR() of a GVL member. It compiles — but runtime initialisation order between a GVL and an instance in another POU is not something the compiler checks. Prefer storing only literals passed into FB_init and doing GVL-dependent wiring lazily on the first cycle, which is order-proof.
• Precedent worth copying: GVL_MQTT.PLC_Device is declared inside the GVL with a full FB_init argument list including pMqttPublishQueue := ADR(fbMqttPublishQueue).

Instantiating a block the harness cannot

Auto-instantiation cannot declare a block whose FB_init takes parameters. Two optional files let you take over:

Any candidate block named in these files is counted as covered and drops out of not_instantiated. Note the programs here keep their logic in actions, so a program's own body is often empty and exposes no implementation; the harness falls back to the first action that has one and reports it as impl_host.

Delete them when the work they supported is finished. They are gitignored and machine-local, they are injected into every verify from then on, and nothing reports that they exist. Two ways that bites:

• verify compiles more than the project does. A harness left over from an old refactor keeps an otherwise-unreferenced block compiled on your machine only. Your verify is green, a colleague's or CI's is green for a different reason, and the shipped project never compiles that block at all. apply injects no harness, so it is the honest answer to "is this block compiled?"
• They break the next refactor and blame the wrong thing. A leftover harness calling InitRS485(...) failed a run that had just moved that configuration into FB_init - four errors pointing at a program nobody had touched, in code that is not in the repository.

Library references

libs is the way in and out of the Library Manager, which is otherwise only reachable from the IDE.

./tools/ai/codesys.ps1 libs                        # what is referenced, and what is installed
./tools/ai/codesys.ps1 libs -LibFilter modbus      # also: every installed Modbus library
./tools/ai/codesys.ps1 libs -RemoveLib '#IoDrvModbus'
./tools/ai/codesys.ps1 libs -AddLib 'SysCom, 3.5.17.0 (System)'
./tools/ai/codesys.ps1 libs -UpdateLib 'PRO_JSON'  # repoint a PLACEHOLDER at the newest installed

Read-only without -RemoveLib / -AddLib / -UpdateLib. With any of them it behaves like apply: it builds first and refuses to save a project that does not build, which is what makes "is anything still using this?" a question you can answer by trying it.

Four things about the report are worth knowing before acting on it:

• -LibFilter only sees this machine. The repository query lists what is installed, not what the CODESYS Store has. "Nothing newer" means "none here", never "none exists" — installing a newer library is still an IDE job.
• A * version floats. PRO_JSON, * (Pro Electric) already resolves to the newest installed version, so it is never reported as behind one. What pins it to something older is a redirection, which the report shows separately.
• (not resolved in this project) is not outdated. Several visualisation placeholders carry a default resolution but resolve to nothing, because nothing uses them. Reporting those as outdated would send you after a version no build is reading.
• Names must match the Library Manager exactly, # included for a placeholder. libs with no arguments prints the exact strings.

-UpdateLib takes a placeholder name only. A fixed reference carries its version inside its name, so moving one means -RemoveLib then -AddLib.

The repository global is called librarymanager

Not library_manager, which is what the shipped .pyi stub says and what does not resolve — the same class of stub-versus-reality gap as export_xml's argument order and insert()'s parameter order. repository_manager() in codesys_task.py tries the names and then falls back to finding whatever object answers get_all_libraries, so this should not need rediscovering.

Also: a repository entry's displayname is the full "IoDrvModbus, 4.5.0.0 (CODESYS)" string, not a bare name. Grouping on it directly yields one entry per version and matches nothing.