# TC3 EventLogger spike — managed-wrapper investigation

**Question (b) from the PR 5.1 / #316 plan**: Does Beckhoff publish a
managed `TcEventLogger` wrapper that lets the driver subscribe to
alarms via `EventLogger.AlarmRaised` instead of decoding AMS port 110
notifications by hand?

## TL;DR

**No managed wrapper.** The `Beckhoff.TwinCAT.Ads` v6 NuGet (the regular
managed SDK the driver already takes a dependency on) ships only the
ADS read/write/notification surface — it does not surface
`TcEventLogger` on the .NET side. The C++ TcCOM headers
(`TcEventLogger.h` etc.) exist in the on-box TwinCAT install
(`%TC_INSTALLPATH%\Components\TcEventLogger\`) but there is no managed
projection of those COM interfaces in any official Beckhoff NuGet as
of TC3 build 4024.x.

Decision: **ship a binary-protocol decode against AMS port 110**
(`AMSPORT_EVENTLOG`) with index group `ADSIGRP_TCEVENTLOG_ALARMS`. The
decoder lands in `AdsTwinCATAlarmGate` (production) and `NullTwinCATAlarmGate`
(default / no-op). Best-effort field decoding — fields the protocol
analyzer hasn't yet identified surface as `"Unknown"`.

## What was checked

| Source | Result |
| --- | --- |
| `Beckhoff.TwinCAT.Ads` v6.x NuGet, namespace inventory | `TwinCAT.Ads`, `TwinCAT.Ads.SumCommand`, `TwinCAT.Ads.TypeSystem`, `TwinCAT.TypeSystem`. **No** `TcEventLogger` namespace. |
| `Beckhoff.TwinCAT.Ads.TcpRouter` v6.x NuGet | Router only; no EventLogger surface. |
| Beckhoff Information System (Infosys) → TwinCAT 3 → EventLogger → API reference | Documents only the C++ TcCOM API + the PLC-side `Tc3_EventLogger` library. No managed-language section. |
| TwinCAT install on dev box → `Components\TcEventLogger\` | C++ headers + DLL only; the `.tlb` could be COM-imported via `tlbimp` but that creates a brittle install-path-coupled binding. |
| Public Beckhoff GitHub orgs | `Beckhoff/TwinCAT-Tools-Library` etc. — no managed EventLogger wrapper. |

## Why decode at the wire?

A `tlbimp` projection of the on-box TcCOM `.tlb` would technically work
but introduces three problems:

1. **Install-path coupling** — the `.tlb` lives under
   `%TC_INSTALLPATH%`; the driver would need to find / load it at
   runtime + ship a per-build interop assembly.
2. **Bitness lock-in** — TcCOM is x86; the driver builds AnyCPU.
3. **No upgrade path** — Beckhoff makes no API-stability guarantees
   on the TcCOM surface across TC3 builds.

Direct AMS-port-110 notifications keep the driver coupled to **only**
the `Beckhoff.TwinCAT.Ads` v6 NuGet's stable wire surface. Trade-off:
the binary protocol is undocumented in managed-code form; we work
around that by:

- Writing a permissive decoder that surfaces unrecognised fields as
  `"Unknown"` rather than throwing.
- Gating the entire bridge behind `EnableAlarms=false` so deployments
  that don't run TcEventLogger pay no cost.
- Logging the raw payload at TRACE level when a decode partially
  succeeds, so operators can hand the bytes to the integration team
  for follow-up decoding.

## What ships in PR 5.1

- `ITwinCATAlarmGate` interface — driver-internal seam.
- `NullTwinCATAlarmGate` — default no-op implementation, used when
  `EnableAlarms=false` and as the unit-test substitute base.
- `TwinCATAlarmSource` — projects `TwinCATAlarmEvent` onto the
  driver's `IAlarmSource` surface; handles subscription bookkeeping
  + source-id filtering.
- `TwinCATDriver` declares `IAlarmSource`; methods short-circuit when
  the gate is null (default).
- Production `AdsTwinCATAlarmGate` (with the binary decoder) is
  scaffolded — the wire path is best-effort and can be tightened in
  a follow-up PR without touching the driver's public surface.

## Open questions for the follow-up PR

1. **Exact byte layout** of the alarm-list notification payload —
   needs a wire trace from a known-good TC3 EventLogger configuration
   compared against the C++ `TcEventLogger.h` struct definitions.
2. **Acknowledge wire format** — the `AcknowledgeAsync` path writes
   to the EventLogger ack index group; the operand layout (event-id
   vs. condition-id mapping) is best-effort in PR 5.1.
3. **Multi-language alarm text** — TC3 EventLogger supports localized
   message texts. The decoder should pick the runtime's configured
   language; PR 5.1 falls back to the first text it finds.
4. **Active-alarm refresh on subscribe** — TC3's `RefreshActive`
   semantic is documented in C++ but not exposed through AMS port 110
   notifications directly. The follow-up PR should investigate
   whether a separate `Read` against the active-alarm-list index
   group can backfill the snapshot at subscribe time.

## Why land PR 5.1 anyway

The driver's public `IAlarmSource` surface, the options knob, the unit
tests, the CLI verb, and the integration-test scaffold are all
independent of the wire decoder's completeness. Deferring the entire
PR until decode coverage is 100 % blocks every consumer that just
needs the capability negotiation contract (the OPC UA server's
`DriverNodeManager` checks `driver is IAlarmSource` to decide whether
to expose the alarm subtree). Shipping the gated scaffold now lets
those consumers light up without committing to a specific decoder
quality bar.