twincat-mapping-reader

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 context
• OwnerB as the linked external object or system object
• Link VarA="..." VarB="..." as the concrete field-to-field connection

Typical TwinCAT traces look like:

1. PLC task-side variable path
2. linked NC/group/device/terminal path
3. 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 PLC
• PlcToNc usually means commands or setpoints flowing from PLC to NC
• Inputs 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:

1. Starting symbol
2. Declaration/source location
3. Mapping lines found
4. Resolved target object
5. Direction interpretation
6. Confidence and open gaps