Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 106 additions & 0 deletions .claude/skills/axo-to-tco-migration/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
---
name: axo-to-tco-migration
description: Port (migrate) an AxOpen / AX# vendor component (Axo<Device>, Simatic AX `src/components.<vendor>.<domain>`) into a TcOpen vendor component (Tco<Vendor><Domain> library, TwinCAT 3). Use when the user wants to migrate, port, convert or take over a component from AxOpen / AXOpen / AX# into this repo, or names an `Axo<Device>` class as the source. Builds on the tco-vendor-component skill.
---

# AxOpen -> TcOpen component migration

Source: the AxOpen repository, default `d:\MTS\Develop\Inxton\ax\axopen-templates\axopen` (ask if it is not there).
**The AxOpen repository is read-only.** Never edit, build, format, `apax install` or create files in it; copy files *out* of it only.

Target: a TcOpen vendor component built exactly as described by the **`tco-vendor-component`** skill. Load that skill
first - its scaffold, registration, naming, localization, testing rules and Definition of done apply unchanged. This skill
only adds how to read the AX source and how to translate AX constructs: [references/ax-to-tco-mapping.md](references/ax-to-tco-mapping.md).

## Placeholder names

This skill uses one generic name family, aligned with tco-vendor-component. Replace it consistently with the real names.

| AX placeholder | TcOpen placeholder |
|---|---|
| `components.<vendor>.<domain>` | library `Tco<Vendor><Domain>` = `TcoTemplate` |
| `AxoTemplate` (class in the `<v_X_Y_x>` namespace) | `TcoTemplate[Pn\|Ecat]_v_1_x_x` |
| `AxoTemplate_<Type>` | `TcoTemplate_<Type>_v_1_x_x` (DUTs, tasks, functions) |
| `eAxoTemplate_<Enum>` | `eTcoTemplate_<Enum>_v_1_x_x` |
| `AxoTemplate_BaseTask` | `TcoTemplateTask_v_1_x_x` (ABSTRACT) |
| `FakeTemplate` harness (`ctrl/test/_harness/`) | `TcoTemplateSimulator` in the test PLC |

Real examples are listed only at the end ([Examples](#examples-reference-ports)).

## AX library anatomy

```
src/components.<vendor>.<domain>/
ctrl/src/AxoTemplate/<v_X_Y_x>/ # component CLASS, Tasks/, TypesStructuresAndEnums/ (or flat)
ctrl/test/ # AxUnit tests, _harness/ (FakeTemplate simulator, S7Harness mocks)
ctrl/assets/ # GSDML / ESI / .hwl.yml hardware templates
src/AXOpen.Components.<Vendor>.<Domain>/ # C# twin partials: messenger text lists (code -> text + help)
Resources/PlcStringResources*.resx # translations of every <#...#> PLC text
src/AXOpen.Components.<Vendor>.<Domain>.blazor/ # views (what the operator sees) + Resources/Strings*.resx
tests/AXOpen.Components.<Vendor>.<Domain>.Tests/ # xUnit (usually messenger completeness)
docs/ # device docs, wiring, device settings, TROUBLES.md
```

A usage example usually exists in `src/showcase/app/src/components.<vendor>.<domain>/`.

## Names

- No namespaces in TwinCAT: vendor, version and (when both buses exist) bus go into every name - see the placeholder table.
- Keep the AX version folder as the version suffix (`v_X_Y_x` -> `_v_X_Y_x`).
- Keep enum member names and values exactly.

## Workflow

0. **Locate and read everything** of the component (all `.st` in `ctrl/src` and `ctrl/test`, the twin `.cs`, the
blazor view, `docs/`, assets). Use an Explore agent for a large component. Produce an inventory:
classes and members, every task's step ladder, the IO byte/bit map with offsets, every messenger code with text + help,
tests, simulator knobs, hardware template (module/slot shape).
1. **Grill** (tco-vendor-component Step 0, plus): bus (`Pn`/`Ecat`); library/FB names; which AX features to drop
(hardware-ID bootstrap, numeric codes, TaskTimeout are dropped by default - see mapping); whether AX steps are ported 1:1
(default yes, comment each block `// AX step N`). The interface map is the AX encode/decode code - no manual needed,
but read the AX docs for unverified bits and keep those notes.
2. **Check the AX code before copying it.** AX components have had real bugs (e.g. a task that never reaches Done
because of a wrong step number, a parameter stored but never used). Port the intent, tell the user about each
deviation, record it in the README.
3. **Build** with tco-vendor-component: scaffold, register, IO, DUTs, functions, task base, tasks, component, twin, view.
Translate with the mapping reference.
4. **Tests**: port the AX `FakeTemplate` harness into `TcoTemplateSimulator` (same knobs: fail/silent/stuck masks,
timing counts, fault flags) and port each AxUnit test into an NUnit PLC-executed test. Tests of the AX hardware
bootstrap (`S7Harness`, HW-ID codes) are dropped together with that feature. Codec tests become mapping tests
(write raw bytes into the simulated input image, assert the decoded `_status`; set `_control`, assert output bytes).
5. **Localization**: neutral texts come from the PLC `<#...#>` literals. AX `PlcStringResources.<de|es|sk>.resx` and blazor
`Strings.*.resx` are a translation source when the English text is the same - reuse their wording, then fill the gaps
(cs-CZ never exists in AX). AX help texts (C# messenger list) are merged into the TcOpen message text where useful.
6. **README**: wiring, hardware template/slot table, device settings, byte maps, troubleshooting - from AX `docs/`.
Copy GSDML/ESI from `ctrl/assets` to `assets/` and `TcoTemplateConnector/ddf/`.
7. **Report** to the user: what was dropped, AX bugs fixed, tests that could not be run.

## Verification without TwinCAT XAE

- **Library twin**: write a temporary filter in the repo root (`TcoTemplate.tmp.slnf`, `"path": "TcOpen.sln"`) with the
library Connector, the Xae tsproj and the TestsConnector, then
`.\_Vortex\builder\vortex.compiler.console.exe -s .\TcoTemplate.tmp.slnf -n false`. It parses the PLC declarations and
regenerates `_generated/`; `WRN ... unknown type` on library types means a misspelt name. Delete the filter afterwards.
- **Test PLC twin**: the compiler resolves types of *referenced PLC libraries* from the TwinCAT managed library repository
(`C:\TwinCAT\3.1\Components\Plc\Managed Libraries\Vortex.Library\TcoTemplate`). A brand-new library is not there until
it is built and installed from XAE, so the test-connector twin (and the NUnit project) only compile after that - say so.
- **.NET**: the connector packs `_meta\TcoTemplate.library`, which only an XAE build produces. To check that the C#
compiles earlier, put an empty placeholder file there for the build and delete it afterwards (`_meta/` is gitignored).
- ST implementation bodies are not checked by the Vortex compiler - review them, and build in XAE before release.
- In this environment bash heredocs collapse `\\`; write JSON (`.slnf`) with the Write tool or a script file.

## Extra definition-of-done items

- [ ] Nothing written to the AxOpen repository (`git -C <axopen> status` clean).
- [ ] Every AX task, operation and public data member is either ported or listed as dropped in the README.
- [ ] No AX identifiers or syntax left in the TcOpen code: `Axo*` types, `ix-attr`, `ix-set`, `REF_TO`, `LTIME`, `THIS.` (case-sensitive search; doc comments naming the AX origin are fine, and words like `RealTime` / `MaxOutputs` are false hits of a case-insensitive search).
- [ ] Every AX test is ported or listed as not applicable.

## Examples (reference ports)

Read them when a detail is unclear. Do not copy vendor names, signal names or texts from them into a new component.

| AX source | TcOpen port | What it shows |
|---|---|---|
| `components.ateq.measurement`, `AxoG6` `v_3_5_x` | `src/TcoAteqMeasurement`, `TcoAteqG6Pn_v_3_5_x` | cyclic PN with 4+4 modules mapped to one image, command handshake in an abstract task base, AX data classes as STRUCT + FUNCTIONs, simulator ported from `FakeG6`, numeric codes replaced by texts |
| `components.kuka.robotics`, `AxoKss` `v_9_3_x` | `src/TcoKukaRobotics`, `TcoKukaKssPn_v_9_3_x` / `...Ecat...` | 1:1 step port with `// AX step N`, both buses, AX bug fixed (start task never reached Done) |
108 changes: 108 additions & 0 deletions .claude/skills/axo-to-tco-migration/references/ax-to-tco-mapping.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
# AX -> TcOpen translation table

Derived from the reference ports listed in SKILL.md (Examples).
Names use the placeholder families of SKILL.md: `AxoTemplate` (AX) and `TcoTemplate` (TcOpen).

## Component

| AX | TcOpen |
|---|---|
| `CLASS AxoTemplate EXTENDS AXOpen.Core.AxoComponent` | `FUNCTION_BLOCK TcoTemplatePn_v_1_x_x EXTENDS TcoIo.TcoPnIoComponent` (`TcoIo.TcoEcatComponent`, `TcoCore.TcoComponent` for .NET TCP) |
| `IMPLEMENTS IAxo<Abstraction>` (e.g. `IAxoRobotics`) | `IMPLEMENTS TcoAbstractions.ITco<Abstraction>`; reuse the `TcoAbstractions` types instead of the AX ones |
| `METHOD PUBLIC Run(inParent : IAxoObject; hwID : UINT)` | FB body with `VAR_IN_OUT inoData : TcoTemplate_IO_v_1_x_x`; parent bound at declaration `(THIS^)` + `FB_init(bInitRetains, bInCopyCode, ParentObject : ITcoObject)` |
| `SUPER.Run(inParent); Messenger.Serve(THIS);` | `IF NOT __ISVALIDREF(inoData) ...RETURN; SUPER^(inPnIoBoxState := ..., inPnIoBoxDiag := ...); _busError := NOT _profinetReady;` |
| `InitHwCheck` / `CheckSubmodule` (`ReadSlotFromHardwareID`, `ReadHardwareIDFromSlot`, `ReadHardwareIOAddress`, size checks) | **dropped** - IO is linked in the System Manager; module sizes are fixed by the IO struct |
| `Config.HWIDs`, `AxoTemplate_HWIDs` | **dropped** |
| `DistributedIO.ReadData(hwID, _module)` per module | one `ARRAY[0..n] OF BYTE AT %I*` per module in `TcoTemplate_Inputs_v_1_x_x` (`In1..InN`, one per module), copied into an image with `MEMCPY` in `UpdateStatus` |
| `DistributedIO.WriteData` | `Out1..OutN AT %Q*` in `_Outputs_`, filled in `UpdateControl` (last statement of the body) |
| `HardwareDiagnosticsTask : AxoHardwareDiagnostics` | **dropped** - PN box state / `_busError` of `TcoPnIoComponent` |
| `Inputs : AxoTemplate_State` + `Status : AxoTemplate_Component_Status` | `_status : TcoTemplate_Status_v_1_x_x` with `ActionDescription` + `State` (+ any extra AX status data) |
| `Outputs : AxoTemplate_Control` | `_control : TcoTemplate_Control_v_1_x_x` |
| public fields `Config`, `Status`, task fields | private `_camelCase` + `PROPERTY Status : REFERENCE TO ...` / `PROPERTY XTask : TcoCore.ITcoTaskStatus` |
| `METHOD ... : IAxoTaskState` | `METHOD ... : TcoCore.ITcoTaskStatus` |
| `RestoreTask.Execute(THIS)` -> `THIS.Restore()` (calls `RestoreTask.DoneWhen(TRUE)` inside) | `IF _restoreTask.Execute() THEN Restore(); _restoreTask.DoneWhen(TRUE); END_IF`; `Restore : ITcoRestorable` = `RestoreTasks()` + safe `_control` |
| `METHOD PROTECTED OVERRIDE ManualControl` | `METHOD PROTECTED ServiceMode` |
| `Status.Action.Id := 50` | `_status.ActionDescription := '<#Restore has been executed.#>'` |

## Tasks

| AX (`AxoTask`) | TcOpen (`TcoCore.TcoTask`) |
|---|---|
| `CLASS ABSTRACT AxoTemplate_BaseTask EXTENDS AxoTask` | `FUNCTION_BLOCK ABSTRACT TcoTemplateTask_v_1_x_x EXTENDS TcoCore.TcoTask` |
| `Run(parent, REF(Config), REF(Status), ...)` + `refX : REF_TO T`, NULL checks | `VAR_IN_OUT inoConfig, inoControl, inoStatus (, inoImage ...)` passed every call; step 0 = `CheckReferences()` (`__ISVALIDREF`) |
| `task.SetIsDisabled(cond); task.Run(...)` | `task.Enabled := NOT cond; task(inoConfig := ..., ...)` - **polarity inverted** |
| `IsBusy() / IsDone() / HasError() / IsReady()` | properties `Busy / Done / Error / Ready` |
| `Execute(THIS)`, `Invoke(THIS)`, `Abort()` | `Execute()`, `Invoke()`, `Abort()` |
| `DoneWhen(TRUE)` | `DoneWhen(TRUE)` |
| `ThrowWhen(cond, '<#text#>')` | `ThrowWhen(cond)` has no text: store the text in a task variable first (`Fail(inText)` helper), post it from `OnError` |
| `OnStart / OnDone / OnError / OnAbort` (OVERRIDE, `SUPER.OnX()`) | `OnStart / OnDone / OnError / OnAbort` (no SUPER call needed), each guarded by `IF __ISVALIDREF(inoStatus)` |
| `OnRestore` | override `Restore : ITcoRestorable` (`SUPER^.Restore(); ...`) |
| no auto-restore | task ends with `IF THIS^.Error AND NOT _errorMessage.Pinned THEN THIS^.Restore(); END_IF`; `OnError` pins `_errorMessage` |
| `Duration` | `ElapsedTime` (rarely needed; use timers) |
| `Config.TaskTimeout` + `ThrowWhen(Duration >= ...)` | **dropped** - `Config.ErrorTime` with `_errorTimer` / `ThrowWhen(_errorTimer.Q)` (T#0S = off) |
| `Messenger.Post(Status.ActionInfo, Info)` after `InfoTime` | `Messenger.OnCondition(_infoTimer.Q).Warning/Info(...)` |
| parameters stored on the component before `Invoke` | task-local variable + `InvokeWithParams(...)` or fluent `WithParams(...)`; or `_control` data written by the operation method (cyclic) |
| sequential `IF _progress = N THEN` | same idiom; comment each block `// AX step N` (step numbers may be kept as in AX, e.g. 0/10/20/100) |
| `GoTo(step)` restarting a step timer | `_progress := step; _stepTimer(IN := FALSE);` |
| `AxoRemoteTask` | `TcoCore.TcoRemoteTask` (.NET TCP archetype) |

## Messenger

| AX | TcOpen |
|---|---|
| `Messenger : AxoMessenger` field + `Serve(THIS)` | built-in `Messenger`; tasks add `_errorMessage : TcoCore.TcoMessenger(THIS^)` |
| `Messenger.Activate(UINT#n, Error)` + C# `MessengerTextList` (code -> text, help) | `Messenger.Error('<#text#>')` with the AX text (and help when short) inline; **numeric codes dropped** |
| `Status.Error.Id := n` | dropped (or a diagnostic field only when the user asks) |
| categories `Error / Warning / Info / ProgrammingError / Potential` | `Error / Warning / Info / Programming / Warning` |
| `ActivateOnCondition(n, cond, cat)` | `Messenger.OnCondition(cond).<Category>(...)` |
| `Messenger.Restore()` | `UnPin()` |

## Data types and language

| AX | TcOpen |
|---|---|
| `CLASS` with data + methods (Decode/Encode/Add/Clear) | `STRUCT` DUT + `FUNCTION`s `Tco<Vendor><Device>_<Verb><Type>_v_X_Y_x(VAR_IN_OUT ...)`; FB only if it must keep state between cycles |
| `CLASS` used only as data | `STRUCT` |
| `ARRAY[*] OF BYTE` parameter | fixed bounds (`ARRAY[0..255] OF BYTE`) or `POINTER TO BYTE` + size |
| `REF_TO T`, `^`, `REF(x)`, `NULL` | `VAR_IN_OUT` (preferred), `REFERENCE TO` + `REF=`, `__ISVALIDREF` |
| `THIS.` / `SUPER.` | `THIS^.` / `SUPER^.` |
| method overloads | distinct names |
| `VAR PUBLIC/PROTECTED` | FB `VAR` + properties; inherited `VAR` are visible to subclasses |
| `LTIME`, `LT#5S` | `TIME`, `T#5S` |
| `OnDelayTimer.OnDelay(THIS, sig, t)`, `.output`, `.Restore()` | `TON`: `t(IN := sig, PT := ...)`, `.Q`, `t(IN := FALSE)` |
| `AxoBlinker` | `TcoUtilities.TcoBlinker(THIS^)` (check period) |
| `TO_INT`, `TO_REAL`, `TO_WORD` | explicit `WORD_TO_INT`, `DINT_TO_REAL`, `INT_TO_WORD` ... |
| `UINT#5`, `WORD#16#8000` | plain literals with typed context (`16#8000`) |
| `STRING` (unbounded) | `STRING(n)` - `ActionDescription : STRING(100)`, texts up to 254 |
| `x.%X3`, `%B0` | `x.3`, byte helpers / `SHL` / `TcoUtilities.TcoBytesTo*` (`eTcoDataFormat.LittleEndian`) |

## Attributes

| AX | TcOpen |
|---|---|
| `{#ix-set:AttributeName = "<#X#>"}` | `{attribute addProperty Name "<#X#>"}` |
| `{#ix-attr:[ReadOnly()]}` | `{attribute clr [ReadOnly()]}` |
| `{#ix-attr:[RenderIgnore()]}` | `{attribute clr [RenderIgnore()]}` or `{attribute 'hide'}` for internals |
| `{#ix-attr:[ComponentDetails(...)]}`, `[Container(...)]`, `[Group(...)]`, `{S7.extern=...}` | drop - layout is the WPF view's job |
| `///<summary>` | `(*~ <docu><summary> ... </summary></docu> ~*)` |
| enum | `{attribute 'qualified_only'}` + `{attribute 'strict'}` |

## Tests and UI

| AX | TcOpen |
|---|---|
| AxUnit `{TestFixture}` / `{Test}` in `ctrl/test` | test PLC test context + NUnit `PlcExectutedTests/` (testing.md of tco-vendor-component) |
| `_harness/Fake<Device>.st` simulator | simulator section of the test context `Main`, same knobs as `_sim*` / `_fault*` variables |
| `S7Harness` (HW-ID / ReadData mocks) | none - tests write the unlinked `_io` struct directly |
| xUnit messenger-completeness tests | none (codes dropped); `Test-TcoLocalization.ps1` checks the texts instead |
| Blazor view + tabs | WPF `<Gen>/Service/<FB>ServiceView.xaml` + view model (status badges, values, task buttons, data panels) |

## Gotchas

- `Enabled` is the inverse of `SetIsDisabled`; re-read each interlock line.
- Several AX `IF _progress = N` blocks may advance within one cycle - the TcOpen idiom does the same; keep block order.
- AX step numbering: TcOpen adds `CheckReferences`; either insert it as an extra step before AX step 0 or check references in the body before the step blocks.
- Profinet devices with several modules: one `AT %I*` array per module; keep the AX image offsets so the decode code stays 1:1.
- Numbers that are 0-based on the bus and 1-based in AX (e.g. program or recipe numbers): keep the AX conversion in the encode/decode functions.
- AX writes the whole output image every cycle (zeroed then encoded) - do the same in `UpdateControl`.
- Unaligned multi-byte fields: decode via byte helpers, not struct overlays (TwinCAT pack mode).
Loading
Loading