| name | twincat-mapping-reader |
| description | Trace TwinCAT 3 symbol mappings across PLC code, task links, NC axes, axis groups, process-image channels, and EtherCAT or XTS-related objects. Use when Codex needs to answer where a PLC variable is mapped, how an AXIS_REF or AXES_GROUP_REF connects to NC objects, which terminal or device path a symbol belongs to, or how to read mapping sections in .tsproj files. |
TwinCAT Mapping Reader
Overview
Use this skill to follow a TwinCAT symbol from its PLC declaration to the system object it actually talks to. Prioritize .tsproj mappings, task-side link names, NC object paths, and terminal/device paths over guesswork.
Read references/mapping-walkthrough.md for the step-by-step mapping workflow. Read references/mapping-patterns.md when you need concrete examples of common TwinCAT mapping shapes such as AXIS_REF, AXES_GROUP_REF, terminal channels, and XTS-related links.
Workflow
1. Start from the user's symbol or object name
Identify the exact item being traced:
- PLC variable such as
GVL_Xts.aMoverAxis[1]
- task-side field such as
.NcToPlc or .PlcToNc
- FB field such as
MAIN.stGroupRef
- terminal path, channel path, or NC object name
- device-tree object path from a mapping line
Normalize the starting point before searching so the trace stays precise.
2. Find the declaration side first
Locate where the symbol is declared or exposed:
- GVL
- POU declaration
- DUT field
- task I/O interface name inside mapping lines
If the symbol is part of a larger object such as AXIS_REF, note whether the user cares about the whole object or only .NcToPlc / .PlcToNc.
3. Inspect .tsproj mappings as the main source of truth
Look inside <Mappings> sections and read:
OwnerA as one side of the mapping contextOwnerB as the linked external object or system objectLink VarA="..." VarB="..." as the concrete field-to-field connection
Typical TwinCAT traces look like:
- PLC task-side variable path
- linked NC/group/device/terminal path
- direction pair between PLC and system object
4. Explain directionality correctly
Be explicit about the direction:
NcToPlc usually means status/feedback flowing from NC to PLCPlcToNc usually means commands or setpoints flowing from PLC to NCInputs and Outputs are relative to the owning side in the mapping, not necessarily physical plant direction- device FB inputs or terminal channels may reflect internal module data, not plain discrete I/O
Do not flip directions casually. State exactly which file path supports the interpretation.
5. Summarize the full hop chain
Present the mapping as a chain, for example:
- PLC symbol
- task-side member
- NC axis/group/device object
- terminal or module path if present
- practical meaning that is confirmed or inferred
Separate confirmed links from likely semantics.
Mapping Rules
- Prefer
.tsproj mappings over comments in ST code when they conflict.
- Treat
OwnerB Name="TINC^NC-Task 1^Axes^..." as an NC object path, not as plain text.
- Treat
OwnerB Name="TINC^NC-Task 1^Objects^..." as a non-axis NC object such as a coordinated group.
- Treat terminal paths like
Term 54 (AT2050-0501)^Term 55 (AT2050-5501)^... as device-tree evidence.
- When tracing
AXIS_REF, explain both .NcToPlc and .PlcToNc links when both are shown.
- When a mapping uses
Data Pointer^..., explain that this may represent internal driver/module data rather than a direct PLC variable.
- If the symbol is declared in PLC code but no mapping is found, say the symbol is unresolved from the available project artifacts.
Typical requests this skill should handle
- "Where is
GVL_Xts.aMoverAxis[3] mapped?"
- "What does
MAIN.stGroupRef connect to?"
- "Trace this PLC symbol to the EtherCAT terminal."
- "Explain this
OwnerA / OwnerB / VarA / VarB mapping."
- "Show whether this axis reference is connected to an NC axis or still unlinked."
- "Tell me if this is real I/O, NC mapping, or XTS internal data."
Output style
Prefer this format:
- Starting symbol
- Declaration/source location
- Mapping lines found
- Resolved target object
- Direction interpretation
- Confidence and open gaps
