twincat-code-reader

name

twincat-code-reader

description

Read and explain TwinCAT 3 PLC projects with emphasis on Structured Text logic, project structure, task execution context, variable scope, NC axis references, I/O bindings, and EtherCAT relationships. Use when Codex needs to inspect TwinCAT solution files, .tsproj files, .plcproj files, .TcPOU/.TcGVL/.TcDUT source, device mappings, NC links, or EtherCAT topology and produce an accurate explanation instead of treating the code like generic application software.

TwinCAT Code Reader

Overview

Use this skill to analyze a TwinCAT project as an executing PLC and motion-control system, not just as a set of source files. Start from task context, declarations, mappings, and hardware relationships before explaining runtime behavior.

Read references/twincat-project-structure.md when the request involves .tsproj, .plcproj, task setup, NC axis links, I/O mappings, or EtherCAT topology. Read references/st-reading-patterns.md when the request involves Structured Text flow, function blocks, state machines, timers, triggers, or scan-cycle interpretation.

Workflow

1. Establish scope before interpreting logic

Identify which TwinCAT layers are present:

• solution and TwinCAT project files
• PLC project files
• POUs, GVLs, DUTs, interfaces, methods, actions
• task configuration
• NC axes or axis groups
• I/O devices and EtherCAT mappings
• HMI/visualization artifacts

If the user only provides isolated ST files, say that hardware and mapping conclusions may be incomplete.

2. Read declarations before statements

Inspect declarations before describing what the code does:

• PROGRAM, FUNCTION_BLOCK, FUNCTION, INTERFACE
• VAR_INPUT, VAR_OUTPUT, VAR_IN_OUT, VAR, VAR_STAT, VAR_TEMP
• global variables from GVLs
• enums/structs from DUTs
• REFERENCE TO, POINTER TO, and FB instances
• AXIS_REF, AXES_GROUP_REF, and motion FB declarations

Treat declarations as the key to ownership, lifetime, and system coupling.

3. Interpret execution as scan-based control

Assume cyclic execution unless the project proves otherwise. Emphasize:

• code runs every task cycle
• later assignments in the same cycle can overwrite earlier outputs
• motion and timer FBs are stateful across scans
• one-shot actions often require edge or execute-flag handling
• initialization may be split across declaration defaults, first-scan state, Init methods, and task startup

Do not explain ST as if it were one-pass application code.

4. Trace mappings explicitly

When variables represent hardware, motion, or NC objects, trace them through the project:

1. PLC symbol or FB field
2. GVL or declaration source
3. task-side link or process-image link
4. NC object, axis, group, device, or EtherCAT terminal
5. likely field meaning, if supported by naming and context

Separate confirmed mappings from inferred real-world meaning.

5. Read TwinCAT project files as first-class sources

Do not stop at .TcPOU files. Also inspect:

• .tsproj for mappings, NC objects, device tree, and EtherCAT-related links
• .plcproj for compile units, libraries, and project composition
• .TcTTO for task cycle time and entry POU
• visualization files when HMI variables influence flow or operator interaction

If .tsproj contains <Mappings> sections, use them to resolve where PLC symbols connect to NC axes, groups, or terminals.

TwinCAT Reading Rules

• Treat AXIS_REF links as evidence of PLC-to-NC integration, not generic variables.
• Treat AXES_GROUP_REF links as motion group bindings that often explain coordinated movement behavior.
• Treat REFERENCE TO AXIS_REF and POINTER TO FB_* as strong clues about object relationships and control ownership.
• Treat Init methods as important setup logic, especially when FB instances receive axis references or station configuration there.
• Treat GVL arrays of AXIS_REF as symbolic handles whose real targets are often resolved in .tsproj mappings.
• When a project uses XTS, motion libraries, or CA groups, explain the NC/motion relationship before summarizing business logic.
• When task timing is available, mention the exact cycle time and relate it to scan behavior.
• When a project contains comments that say axes "need link I/O to actual axes", verify those links in project mappings before assuming they are missing.

Sample patterns to recognize

• GVL_Xts.aMoverAxis[i] mapped to NC-Task 1^Axes^Mover Axis i
• GVL_Xts.aStationServoAxis[i] mapped to station servo axes
• MAIN.stGroupRef mapped to an NC group object such as Group1 (CA Group)
• motion FB instances called every cycle with Execute flags managed by state
• station managers passing axis references into FB instances during Init
• global constants defining track positions, station positions, and timing used by state machines

Output style

When answering, prefer this order:

1. Project context
2. Task and execution model
3. Main declarations and object relationships
4. Runtime/state-machine behavior
5. Mapping summary for NC/I/O/EtherCAT
6. Open uncertainties

Call out what is confirmed by files and what is inferred from naming or architecture.