General Knowledge: Autonomy-Logic OpenPLC .ld Files

This document is a general-purpose knowledge note for AI agents working with the Autonomy-Logic OpenPLC Editor / Runtime ecosystem.

It is intentionally not tied to any one project. The goal is to help future agents reason about .ld files, avoid common false assumptions, and know what to verify before editing ladder programs.

---

1. High-confidence summary

For Autonomy-Logic OpenPLC Editor, a .ld file is not reliably the same thing as the older LDmicro-style plain-text .ld files that dominate many web search results.

In practice, Autonomy-Logic ladder POUs are represented as a hybrid artifact with:

1. an IEC wrapper such as PROGRAM ... VAR ... END_VAR ... END_PROGRAM, and
2. an embedded ladder JSON structure that stores the editor graph for rungs, nodes, and edges.

This conclusion is grounded more strongly by:

• the current editor source code,
• observed Autonomy-Logic project files,
• and the editor's ladder-to-XML generator,

than by generic web search results.

---

2. Search hygiene: what usually goes wrong

When searching the web for openplc .ld, many results describe:

• LDmicro text syntax,
• older thiagoralves/OpenPLC tooling,
• or generic ladder concepts without the Autonomy-Logic serialization format.

Those results are useful for:

• IEC 61131-3 timer semantics,
• ladder logic concepts,
• contact/coil behavior,
• standard function blocks like TON, TOF, TP.

They are not reliable as a source of truth for the exact on-disk .ld serialization used by Autonomy-Logic OpenPLC Editor.

Safe rule

If the task is about file structure, serialization, editing .ld by hand, or how the editor stores ladder diagrams, prefer:

1. Autonomy-Logic editor source code,
2. official Autonomy docs,
3. a real .ld file from an Autonomy-Logic project,
4. and only then general web results.

---

3. Mental model for the Autonomy-Logic format

Think of an Autonomy-Logic ladder .ld file as having two layers:

Layer A: IEC declaration layer

This layer declares the program and variables, for example:

PROGRAM main
VAR
  SOME_INPUT : BOOL;
  SOME_TIMER : TON;
  SOME_OUTPUT : BOOL AT %QX0.0;
END_VAR

This is where you define:

• state bits,
• timer instances,
• counters,
• internal memory bits,
• addressed inputs/outputs,
• and function block instances.

Layer B: editor graph layer

Between END_VAR and END_PROGRAM, the editor stores a JSON object representing the ladder diagram graph.

At a high level, it looks like:

{
  "name": "main",
  "rungs": [
    {
      "id": "...",
      "comment": "...",
      "defaultBounds": [number, number],
      "reactFlowViewport": [number, number],
      "nodes": [...],
      "edges": [...]
    }
  ]
}

The editor treats the ladder diagram as a graph of nodes and edges, then later converts that graph to PLCopen-style XML / runtime-oriented output.

---

4. High-confidence JSON shape

From the current Autonomy-Logic editor source:

Rung-level structure

Each rung has these stable high-level fields:

• id
• comment
• defaultBounds
• reactFlowViewport
• nodes
• edges

Node-level minimum structure

Saved nodes minimally include:

• id
• type
• position
• height (optional in schema)
• width (optional in schema)
• measured (optional in schema)
• draggable
• selectable
• data

Edge-level minimum structure

Saved edges minimally include:

• id
• source
• sourceHandle
• target
• targetHandle
• type (optional)

Known ladder node types

The editor source explicitly enumerates these ladder node types:

• block
• contact
• coil
• parallel
• powerRail
• variable

---

5. What the node types generally mean

powerRail

Represents the left or right power rail of a rung.

Typical characteristics:

• left/right variant
• a connector handle
• non-draggable / non-deletable behavior in editor flows

contact

Represents ladder contacts.

Typical variants include:

• default
• negated
• risingEdge
• fallingEdge

Contacts usually bind to a boolean variable name in data.variable.

coil

Represents ladder coils.

Typical variants include:

• default
• negated
• risingEdge
• fallingEdge
• set
• reset

Coils also usually bind to a boolean variable name in data.variable.

block

Represents a function or function block.

This is how timer blocks such as TON, TOF, and TP are commonly represented.

Important concepts:

• data.variant.name identifies the block type, e.g. TON
• data.variant.type distinguishes function vs function-block style usage
• data.variable.name can hold the instance name for function blocks
• input/output handles define formal parameters such as IN, PT, Q, ET

variable

Used to connect literal values or variables to block pins.

For example, a timer preset is commonly modeled as a separate variable node bound to a block handle such as PT.

Typical variants include:

• input
• output

parallel

Represents ladder branching / merging.

This is the least safe node type to hand-edit without an existing example, because it relies on extra connector relationships and matching open/close behavior.

---

6. Practical editing rules for AI agents

If you must edit an Autonomy-Logic .ld file manually:

Always keep these synchronized

1. VAR declarations in the IEC section
2. references inside ladder JSON nodes
3. debug variable metadata if the project/runtime uses it

Prefer preserving existing structure

Do not aggressively normalize or simplify node objects.

Even if the schema is loose at the top level, real files often contain:

• handles,
• numeric IDs,
• connector metadata,
• variant objects,
• connected variable metadata,
• geometry fields,
• and other editor-generated details.

If a file already has a pattern, copy that pattern instead of inventing a smaller one.

Use local examples before inventing shapes

Before adding a timer block, parallel branch, or complex rung, inspect an existing Autonomy-Logic .ld file that already contains the same construct.

Treat parallel branches as high-risk edits

Branching logic is much easier to break than simple serial contacts/coils. When possible, modify an existing parallel pattern instead of creating one from scratch.

---

7. Timers: what is safe to assume

For IEC 61131-3 semantics, it is generally safe to assume:

• TON = on-delay timer
• TOF = off-delay timer
• TP = pulse timer

And for time literals:

• T#3s
• T#200ms
• T#1m10s

are valid IEC-style duration literals.

Typical timer pattern in Autonomy-Logic ladder JSON

Autonomy-Logic projects commonly represent timer function blocks as:

1. a block node for the timer instance, and
2. a separate variable node feeding the PT input.

That means if you add a timer, you usually need both:

• a timer instance in the IEC VAR section, and
• graph nodes/edges for the timer block plus its preset connection.

Semantics reminder

• TON needs IN to remain true until PT elapses.
• TP emits a pulse for a fixed duration after a triggering edge.
• Effective timing still depends on PLC scan behavior, so exact behavior is bounded by runtime scan resolution.

---

8. Relationship to PLCopen XML

Autonomy-Logic documentation describes OpenPLC projects as PLCopen-oriented at the project level.

The ladder editor source also contains a ladder-to-XML conversion path that maps:

• power rails,
• contacts,
• coils,
• blocks,
• variables,

from the editor graph into ladder XML structures.

This implies an important architectural point:

The editor's .ld storage format and the PLCopen/runtime-facing XML representation are related, but they are not the same thing.

So if you are editing the source .ld file, you are editing the editor graph representation, not the final compiled/runtime representation directly.

---

9. Validation checklist after editing

After any manual .ld change, validate in this order:

1. IEC section sanity

   • Program wrapper still exists
   • VAR ... END_VAR is syntactically intact
   • all new variables are declared

2. Embedded JSON sanity

   • find the first { belonging to the ladder object
   • parse JSON successfully
   • confirm name exists
   • confirm rungs is an array

3. Graph integrity

   • each edge references existing node IDs
   • handles named in edges exist on the corresponding nodes
   • timer blocks that need PT have a valid preset connection

4. Semantic consistency

   • every referenced variable exists in the IEC declarations, unless it is an intentional literal such as T#3s
   • addressed outputs still use valid IEC syntax such as %QX0.0

5. Project metadata consistency

   • if the project stores debug-variable lists, update them too
   • if the project references a POU by name, confirm the name still matches

6. Editor/runtime sanity

   • reopen the project in the editor if possible
   • verify the rung still renders
   • compile or export if tooling is available

---

10. Known pitfalls

Pitfall 1: trusting generic openplc .ld web results

This is the biggest failure mode. Many search results describe the wrong format.

Pitfall 2: editing only the IEC declarations

If you add a new timer or state bit in VAR but do not update the ladder JSON, the editor graph and declarations will drift apart.

Pitfall 3: editing only the JSON graph

If a rung references a new variable name that is not declared in VAR, the project becomes inconsistent.

Pitfall 4: oversimplifying node data

The top-level schema is permissive, but the editor often depends on richer node metadata than a minimal JSON object suggests.

Pitfall 5: hand-authoring parallel nodes without an example

Branching is harder than serial logic because it depends on special connector relationships and path reconstruction.

Pitfall 6: assuming runtime semantics from storage alone

The file stores the editor graph. Final execution depends on how the editor exports/compiles that graph into PLCopen/runtime code.

---

11. Recommended workflow for future agents

When asked to modify an Autonomy-Logic .ld file:

1. Read the target .ld file completely.
2. Read the surrounding project metadata/configuration files.
3. Search for existing examples of the same construct in the same codebase.
4. If unsure about serialization details, inspect the current Autonomy-Logic editor source.
5. Make the smallest possible edit that preserves the surrounding format.
6. Parse the embedded JSON and confirm it is still valid.
7. Re-check IEC declarations and project metadata.
8. If possible, reopen in editor / compile / export.

---

12. Confidence model for future reasoning

High confidence

• .ld in Autonomy-Logic should be treated differently from legacy LDmicro .ld
• ladder storage contains a JSON graph with rungs, nodes, and edges
• known node types include block, contact, coil, parallel, powerRail, variable
• timer semantics like TON, TOF, TP and literals like T#3s follow IEC conventions

Medium confidence

• many editor-generated node details can be safely copied from existing examples
• timer presets are commonly represented via separate variable nodes connected to PT

Lower confidence / verify locally first

• exact required data payload for complex nodes in all editor versions
• the safest way to author parallel nodes from scratch
• any assumption about runtime/export behavior not backed by current source or by a real local example

---

13. Suggested source hierarchy for future research

When building or extending this knowledge, use this order:

1. Autonomy-Logic editor source code
2. official Autonomy documentation
3. real Autonomy project files
4. IEC 61131-3 references for semantics
5. Perplexity/web search only as a discovery aid

Perplexity is still useful, but mainly for:

• finding official pages,
• recalling IEC timer behavior,
• and spotting terminology.

It should not be trusted by itself for exact .ld serialization details.

---

14. Sources used to build this knowledge

Primary grounding:

• Autonomy-Logic OpenPLC Editor source
  • src/renderer/store/slices/ladder/types.ts
  • src/renderer/store/slices/react-flow/types.ts
  • src/utils/PLC/xml-generator/codesys/language/ladder-xml.ts
• Official overview
  • https://old.autonomylogic.com/docs/3-1-openplc-editor-overview/

Secondary supporting references:

• Perplexity-assisted discovery for IEC timer semantics and public OpenPLC context
• IEC-style timer references such as Fernhill-style documentation for TON, TOF, TP, and TIME literals

---

15. If you want to turn this into a real skill later

This file is intentionally plain knowledge, not an executable skill.

To promote it into a reusable skill, convert it into:

• a SKILL.md with explicit triggers,
• a decision tree for when to inspect source vs local files,
• and a required validation procedure after edits.

Good trigger phrases would include:

• edit openplc ld
• fix ladder json
• autonomy logic .ld
• manual ladder file edit
• openplc timer rung