# TwinCAT XAR fixture project

This folder holds the TwinCAT 3 XAE project that the XAR VM (or TCBSD
target) runs for the integration-tests suite and the broader browse /
UDT / array / enum coverage exercised by the OPC UA driver.

**Status today**: the `.sln` / `.tsproj` / `.plcproj` wrappers still get
generated per-workstation in XAE (GUIDs are install-specific), but every
PLC object is committed as a standalone `.TcGVL` / `.TcDUT` / `.TcPOU`
under `PLC/{GVLs,DUTs,POUs}/`. Reconstruction is "Add Existing Item" of
each file into a fresh XAE project — see **Importing the committed PLC
objects** below.

## Why `.tsproj`, not the binary bootproject

TwinCAT ships two project forms: the XAE `.tsproj` (XML, source of
truth) and the compiled bootproject that the XAR runtime actually
loads. Ship the `.tsproj` because:

- Text format — reviewable in PR diffs, diffable in git
- Rebuildable across TC3 engineering versions (the XAE tool rebuilds
  the bootproject from `.tsproj` on "Activate Configuration")
- Doesn't carry per-install state (target AmsNetId, source licensing)

Reconstruction workflow on the VM:

1. Open TC3 XAE (Visual Studio shell)
2. File → Open → `OtOpcUaTwinCatFixture.tsproj`
3. Target system → the VM's AmsNetId (set in System Manager → Routes)
4. Build → Build Solution (produces the bootproject)
5. Activate Configuration → Run Mode (deploys to XAR + starts the
   runtime)

## Required project state

`TwinCAT3SmokeTests.cs` ships 14 `[TwinCATFact]` methods plus a 16-case
`[TwinCATTheory]` — the tests depend on the exact shapes below. Missing
or renamed symbols surface as ADS `DeviceSymbolNotFound` or wrong-type
read failures, not silent skips. Changed seed values will flip specific
assertions — the load-bearing ones are called out inline.

### Integration-test contract

The dependency surface spans `GVL_Fixture`, `GVL_Primitives`, `GVL_Arrays`,
`GVL_Enums`, `GVL_Plant`, and `MAIN`.

**`GVL_Fixture`** (source: [`PLC/GVLs/GVL_Fixture.TcGVL`](PLC/GVLs/GVL_Fixture.TcGVL))
holds exactly three variables — `nCounter : DINT := 1234`,
`rSetpoint : REAL := 0.0`, `bFlag : BOOL := TRUE`. `MAIN`
(source: [`PLC/POUs/MAIN.TcPOU`](PLC/POUs/MAIN.TcPOU)) increments
`nCounter` every cycle so the native-notification test sees monotonic
change without writing. Seeded values aren't reliable — PlcTask
watchdog restarts reset them — so the read test only asserts a
non-negative DINT.

**`GVL_Primitives.vWord := 16#BEEF`** — the bit-indexed BOOL test pins
to bit 3 (set in `0xBEEF`) and bit 4 (clear). Changing the seed flips
that test.

**`GVL_Primitives` numeric seeds** — the primitive-type theory reads
each of `vSInt, vUSInt, vInt, vUInt, vDInt, vUDInt, vLInt, vULInt,
vReal, vLReal, vString` and asserts the exact seed value. Matches
the declarations in [`PLC/GVLs/GVL_Primitives.TcGVL`](PLC/GVLs/GVL_Primitives.TcGVL).

**`GVL_Arrays.aReal1D[5]`** — the array round-trip test writes + reads
element index 5. The array must be writable; don't apply read-only
attributes.

**`GVL_Plant.Line1.Stations[1].Axes[1].Motor.{Temperature, Running}`** —
the nested-UDT test reads both (LREAL + BOOL). `FB_LineSim` must be
driving the hierarchy (see `MAIN`) so values are alive.

**`GVL_Enums.currentAxisState`** — the browse test asserts this symbol
surfaces by name.

### Complex hierarchy (for browse / UDT / array / enum coverage)

All sources in [`PLC/`](PLC/). Commits are split
one-object-per-file so XAE can "Add Existing Item" each into a fresh
project (the `.plcproj` wrapper is environment-specific and not
committed).

**Type coverage** — `GVL_Primitives` has one of every ADS primitive:
`BOOL, BYTE, WORD, DWORD, LWORD, SINT, USINT, INT, UINT, DINT, UDINT,
LINT, ULINT, REAL, LREAL, STRING(80), WSTRING(80), TIME, TOD, DATE, DT`.

**Array coverage** — `GVL_Arrays` has 1-D primitives, `ARRAY[1..4,1..4]
OF REAL`, `ARRAY[0..2,0..2,0..2] OF DINT`, plus `ARRAY[1..4] OF ST_Axis`
for per-element nested-struct browse.

**Enum + alias coverage** — `E_AxisState : DINT`, `E_Severity : INT`,
`T_Temperature : LREAL`, `T_MeterPerSec : LREAL`. `GVL_Enums` exposes
each at the root so tests can assert `EnumStrings` /
`DataTypeDefinition` rendering without walking the plant hierarchy.

**5-level plant hierarchy** — rooted at `GVL_Plant.Line1 : ST_Line`:

```
GVL_Plant.Line1                         (ST_Line)
    .Stations[1..3]                     (ARRAY OF ST_Station)
        .Axes[1..4]                     (ARRAY OF ST_Axis)
            .Motor                      (ST_Motor)
            .Encoder                    (ST_Encoder)
            .Commands                   (ST_AxisCommands)
            .TravelLog[1..8]            (ARRAY OF LREAL)
        .IO                             (ST_StationIO — 32x DI/DO, 8x AI/AO)
        .Alarms[1..16]                  (ARRAY OF ST_Alarm)
    .Recipe                             (ST_Recipe)
        .Steps[1..10]                   (ARRAY OF ST_RecipeStep)
        .SupportedSkus[1..4]            (ARRAY OF STRING)
    .Stats                              (ST_Stats)
```

**Live value churn** — `FB_LineSim` + `FB_AxisSim` are called from
`MAIN` every cycle: axes ramp position + derive velocity/accel, motor
current/temperature track a sine, IO masks rotate, one alarm per station
toggles each 32 cycles, stats counters increment. Subscription tests
see real data-change notifications without an external writer.

### Task

- `PlcTask` — cyclic, 10 ms interval, priority 20
- Assigned to `MAIN`

### Runtime ID

- TC3 PLC runtime 1 (AMS port `851`) — the smoke-test fixture defaults
  to this. Use runtime 2 / port `852` only if the single runtime is
  already taken by another project on the same VM.

## Importing the committed PLC objects

On a machine with a working TcXaeShell (or Visual Studio with the TC3
XAE integration):

1. File → New → Project → **TwinCAT XAE Project** → name
   `OtOpcUaTwinCatFixture`. This lays down the `.sln` + `.tsproj`
   scaffolding.
2. In the Solution Explorer, right-click the `PLC` node →
   **Add New Item → Standard PLC Project** → name `PLC`. Delete the
   auto-generated stub `MAIN` — the committed one will replace it.
3. Right-click the PLC project's `DUTs` folder → **Add → Existing Item
   …** → multi-select every file under [`PLC/DUTs/`](PLC/DUTs/) and
   **Add As Link** (so the repo stays the source of truth). Repeat for
   `GVLs/` → [`PLC/GVLs/`](PLC/GVLs/) and `POUs/` →
   [`PLC/POUs/`](PLC/POUs/).
4. Assign `MAIN` to `PlcTask` (cyclic, 10 ms, priority 20).
5. Set the target system to the TCBSD / XAR VM via the AMS route, then
   **Build → Build Solution** + **Activate Configuration → Run Mode**.

If XAE complains about missing references while importing, add the DUTs
before the GVLs (the structs are referenced by the plant GVL) and the
enums/aliases first within DUTs.

## XAR VM setup (one-time)

Full bootstrap lives in `docs/v2/dev-environment.md`. The TwinCAT-specific
steps:

1. **Create the Hyper-V VM** — Gen 2, Windows 10/11 64-bit, 4 GB RAM,
   2 CPUs. External virtual switch so the dev box can reach
   `<vm-ip>:48898`.
2. **Install TwinCAT 3 XAE + XAR** — free download from Beckhoff
   (`www.beckhoff.com/en-en/products/automation/twincat/`). Activate the
   7-day trial on first boot.
3. **Note the VM's AmsNetId** — shown in the TwinCAT system tray icon →
   Properties → AMS NetId (format like `5.23.91.23.1.1`).
4. **Configure bilateral ADS route**:
   - On the VM: System Manager → Routes → Add Route → dev box's
     AmsNetId + IP
   - On the dev box: edit `%TC_INSTALLPATH%\Target\StaticRoutes.xml` (or
     use the dev box's own TwinCAT System Manager if installed) to add
     the VM's AmsNetId + IP
5. **Import this project** per the reconstruction workflow above.
6. **Hit Activate Configuration + Run Mode**. The runtime starts; the
   system tray icon goes green; port `48898` is live.

## License rotation

The XAR trial expires every 7 days. When it lapses:

1. The runtime goes silent (red tray icon, ADS port `48898` stops
   responding to new connections).
2. Integration tests skip with the reason message pointing at this
   folder's README.
3. Operator runs `C:\TwinCAT\3.1\Target\StartUp\TcActivate.exe /reactivate`
   on the VM console (not RDP — the trial activation wants the
   interactive-login desktop).

Options to eliminate the manual step:

- **Scheduled task** that runs the reactivate every 6 days at 02:00 —
  documented in the Beckhoff forums as working for some TC3 builds,
  not officially supported.
- **Paid runtime license** (~$1k one-time per runtime, per CPU) — kills
  the rotation permanently, worth it if the integration host is
  long-lived.

## How to run the TwinCAT-tier tests

On the dev box:

```powershell
$env:TWINCAT_TARGET_NETID = '5.23.91.23.1.1'     # replace with the VM AmsNetId — REQUIRED
$env:TWINCAT_TARGET_HOST  = '10.0.0.42'          # replace with the VM IP (defaults to localhost)
# $env:TWINCAT_TARGET_PORT = '852'               # only if not using PLC runtime 1 (default 851)
dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests
```

Only `TWINCAT_TARGET_NETID` is required — fixture gates on it specifically.
`TWINCAT_TARGET_HOST` defaults to `localhost` when unset; `TWINCAT_TARGET_PORT`
defaults to `851`. With the NetID unset, the whole integration suite
(~28 cases, both `[TwinCATFact]` and `[TwinCATTheory]`) skips cleanly;
unit suite (`TwinCAT.Tests`) runs unchanged.

## See also

- [`docs/drivers/TwinCAT-Test-Fixture.md`](../../../docs/drivers/TwinCAT-Test-Fixture.md)
  — coverage map
- [`docs/v2/dev-environment.md`](../../../docs/v2/dev-environment.md)
  §Integration host — VM + route + license-rotation notes
- Beckhoff Information System → TwinCAT 3 → Product overview + ADS +
  PLC reference (licensed; internal link only)