lmxopcua/tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md

# TwinCAT XAR fixture project

This folder holds the TwinCAT 3 XAE project that the XAR VM runs for the
integration-tests suite (`tests/.../TwinCAT.IntegrationTests/*.cs`).

**Status today**: stub. The `.tsproj` isn't committed yet; once the XAR
VM is up + a project with the required state exists, export via
File → Export + drop it here as `OtOpcUaTwinCatFixture.tsproj` + its
PLC `.library` / `.plcproj` companions.

## 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

The smoke tests in `TwinCAT3SmokeTests.cs` depend on this exact GVL +
PLC setup. Missing or renamed symbols surface as ADS `DeviceSymbolNotFound`
or wrong-type read failures, not silent skips.

### Global Variable List: `GVL_Fixture`

```st
VAR_GLOBAL
    // Monotonically-increasing counter; MAIN increments each cycle.
    // Seed value 1234 picked so the smoke test can assert ">= 1234" without
    // synchronising with the initial cycle.
    nCounter   : DINT := 1234;

    // Scratch REAL for write-then-read round-trip test. Smoke test writes
    // 42.5 + reads back.
    rSetpoint  : REAL := 0.0;

    // Readable boolean with seed value TRUE. Reserved for future
    // expansion (e.g. discovery / symbol-browse tests).
    bFlag      : BOOL := TRUE;
END_VAR
```

### PLC program: `MAIN`

```st
PROGRAM MAIN
VAR
END_VAR

// One-line program: increment the fixture counter every cycle.
// The native-notification smoke test subscribes to GVL_Fixture.nCounter
// + observes the monotonic changes without a write path.
GVL_Fixture.nCounter := GVL_Fixture.nCounter + 1;
```

### 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.

## 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_HOST  = '10.0.0.42'          # replace with the VM IP
$env:TWINCAT_TARGET_NETID = '5.23.91.23.1.1'     # replace with the VM AmsNetId
# $env:TWINCAT_TARGET_PORT = '852'               # only if not using PLC runtime 1
dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests
```

With any of those env vars unset, all three smoke tests skip cleanly via
`[TwinCATFact]`; 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)