MTConnect driver: verify Java reference coverage and close gaps #804

New Issue

2026-11-10T14:21:02-05:00

dohertj2 commented

2026-11-10 14:21:02 -05:00

Request

Ensure lmxopcua provides the read-only MTConnect Agent driver capabilities demonstrated by the Java driver in ignitionoee, and close any verified gaps.

Existing implementation: lmxopcua already contains ZB.MOM.WW.OtOpcUa.Driver.MTConnect and its contracts/tests. Treat this as a coverage and parity review of that driver, followed by any necessary additions, rather than creating a duplicate driver. Existing work includes #613, #626, #627, #628 and #650; preserve capabilities beyond the Java baseline.

Java reference

Capabilities to verify

Read-only HTTP/HTTPS + XML Agent integration: /probe discovery, /current snapshots, and multipart /sample streaming; configurable Agent URI and optional device scope.
Typed Device → Component → DataItem browsing, correct namespace handling, bounded tree construction, and deterministic collision handling.
Subscription-driven live values and cached snapshot reads for unmonitored items, with shared HTTP resources and bounded request/stream settings.
Accurate numeric/string conversion and explicit quality for UNAVAILABLE, malformed values, and transport failures; preserve source timestamps and avoid fabricated Good values.
Sequence tracking, Agent instance/restart detection, rebaseline on sequence/ring-buffer errors, bounded retries without progress, heartbeat watchdog, reconnect/backoff, and deterministic cancellation/disposal.
No controller write path; document representation support and limitations. Java excludes TIME_SERIES/DATA_SET/TABLE, while lmxopcua has completed work in these areas: retain and verify existing .NET functionality rather than narrowing it to Java's subset.

Acceptance criteria

Compare current .NET behavior and tests against the Java implementation; record capabilities already covered and concrete gaps, if any.
Implement only verified gaps using existing lmxopcua driver/configuration/OPC UA infrastructure.
Cover relevant Java regression scenarios: parser bounds and malformed XML, multipart framing, numeric overflow, browse collisions, UNAVAILABLE, sequence rebaseline/no-progress limits, frozen Agent watchdog, Agent restart, and teardown.
Validate browse/read/subscribe and write rejection through lmxopcua using the fixture; exercise adapter stop/restart, Agent restart, and a stalled stream.
Update driver documentation and retain validation results and any deferred live checks. If the requested capabilities are already complete, document evidence and close without redundant implementation.

The Java driver was live-validated on development Ignition against the fixture on 2026-08-10, including live subscriptions, adapter UNAVAILABLE, Agent restart/rebuild, cached reads, stalled-stream watchdog, and rebaseline limits. This is reference evidence; it does not establish validation of lmxopcua's implementation or every MTConnect device/vendor.

## Request Ensure lmxopcua provides the read-only MTConnect Agent driver capabilities demonstrated by the Java driver in ignitionoee, and close any verified gaps. **Existing implementation:** lmxopcua already contains `ZB.MOM.WW.OtOpcUa.Driver.MTConnect` and its contracts/tests. Treat this as a coverage and parity review of that driver, followed by any necessary additions, rather than creating a duplicate driver. Existing work includes #613, #626, #627, #628 and #650; preserve capabilities beyond the Java baseline. ## Java reference - [Java MTConnect driver source](https://gitea.dohertylan.com/dohertj2/ignitionoee/src/branch/main/modules/drivers/gateway/src/main/java/com/zb/mom/driver/mtconnect) - [Java MTConnect tests](https://gitea.dohertylan.com/dohertj2/ignitionoee/src/branch/main/modules/drivers/gateway/src/test/java/com/zb/mom/driver/mtconnect) - [Driver documentation and configuration](https://gitea.dohertylan.com/dohertj2/ignitionoee/src/branch/main/modules/drivers/README.md#mtconnect-agent-device) - [Live validation recipe and evidence](https://gitea.dohertylan.com/dohertj2/ignitionoee/src/branch/main/docs/recipes/mtconnect-oee-bind.md) - [Official C++ Agent / SHDR development fixture](https://gitea.dohertylan.com/dohertj2/ignitionoee/src/branch/main/deploy/docker/mtconnect-fixture) - [Existing lmxopcua implementation](https://gitea.dohertylan.com/dohertj2/lmxopcua/src/branch/main/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect) ## Capabilities to verify - Read-only HTTP/HTTPS + XML Agent integration: `/probe` discovery, `/current` snapshots, and multipart `/sample` streaming; configurable Agent URI and optional device scope. - Typed Device → Component → DataItem browsing, correct namespace handling, bounded tree construction, and deterministic collision handling. - Subscription-driven live values and cached snapshot reads for unmonitored items, with shared HTTP resources and bounded request/stream settings. - Accurate numeric/string conversion and explicit quality for `UNAVAILABLE`, malformed values, and transport failures; preserve source timestamps and avoid fabricated Good values. - Sequence tracking, Agent instance/restart detection, rebaseline on sequence/ring-buffer errors, bounded retries without progress, heartbeat watchdog, reconnect/backoff, and deterministic cancellation/disposal. - No controller write path; document representation support and limitations. Java excludes TIME_SERIES/DATA_SET/TABLE, while lmxopcua has completed work in these areas: retain and verify existing .NET functionality rather than narrowing it to Java's subset. ## Acceptance criteria - [ ] Compare current .NET behavior and tests against the Java implementation; record capabilities already covered and concrete gaps, if any. - [ ] Implement only verified gaps using existing lmxopcua driver/configuration/OPC UA infrastructure. - [ ] Cover relevant Java regression scenarios: parser bounds and malformed XML, multipart framing, numeric overflow, browse collisions, UNAVAILABLE, sequence rebaseline/no-progress limits, frozen Agent watchdog, Agent restart, and teardown. - [ ] Validate browse/read/subscribe and write rejection through lmxopcua using the fixture; exercise adapter stop/restart, Agent restart, and a stalled stream. - [ ] Update driver documentation and retain validation results and any deferred live checks. If the requested capabilities are already complete, document evidence and close without redundant implementation. The Java driver was live-validated on development Ignition against the fixture on 2026-08-10, including live subscriptions, adapter UNAVAILABLE, Agent restart/rebuild, cached reads, stalled-stream watchdog, and rebaseline limits. This is reference evidence; it does not establish validation of lmxopcua's implementation or every MTConnect device/vendor.

dohertj2 referenced this issue

2026-11-11 00:05:58 -05:00

MTConnect: end-to-end gate through a deployed server and OPC UA client (adapter stop, Agent restart, stalled stream) #823

dohertj2 referenced this issue

2026-11-11 00:05:58 -05:00

Owner decision: MTConnect empty value — BadNoCommunication or empty string (Java parity) #824

dohertj2 referenced this issue

2026-11-11 00:05:58 -05:00

MTConnect: deploy-time warning when SampleCount >= the Agent's buffer size #825

dohertj2 referenced this issue from a commit

2026-11-11 00:48:23 -05:00

fix(mtconnect): close Java-driver parity gaps found by the #804 review

dohertj2 referenced this issue from a commit

2026-11-11 00:48:23 -05:00

docs(mtconnect): Java reference parity matrix + live validation record (#804)

dohertj2 commented

2026-11-11 00:49:03 -05:00

Done on master (merge 8a0f0df0; d6392dae, f17ff1e6). Parity matrix vs the ignitionoee Java driver is in docs/drivers/MTConnect.md §"Java reference parity (#804)": ~35 capabilities already covered, .NET exceeds Java on TIME_SERIES/DATA_SET/TABLE, native CONDITION alarms, backoff and adaptive sample count (all kept). Nine verified gaps closed, each with a test that failed before:

cppagent 2.x HTTP 400/404 error documents were treated as network failures (infinite reconnect at an expired sequence) — now parsed and recovered;
Agent restarts during recovery were adopted silently — now raise re-browse and drop stale values;
a never-progressing stream read Healthy forever — Degraded after 3 progress-free recoveries;
unbounded XML recursion could stack-overflow the server process — depth cap 64;
DTDs accepted on /probe and write replies — refused everywhere;
6–9. stray Description under Components, float overflow/NaN served Good, 42.000000 on ints, duplicate sibling component names.
Unit 714 (was 678), integration vs the shared cppagent fixture 20/20 (was 18), plus a driver-level live run (adapter stop, Agent restart, paused Agent).
IWritable (since 2026-08-05) writes only the Agent's AllowPut surface, never the controller; off by default behind two gates — consistent with "no controller write path". Follow-ups: #823, #824 (owner decision), #825.

Done on master (merge 8a0f0df0; d6392dae, f17ff1e6). Parity matrix vs the ignitionoee Java driver is in `docs/drivers/MTConnect.md` §"Java reference parity (#804)": ~35 capabilities already covered, .NET exceeds Java on TIME_SERIES/DATA_SET/TABLE, native CONDITION alarms, backoff and adaptive sample count (all kept). Nine verified gaps closed, each with a test that failed before: 1. cppagent 2.x HTTP 400/404 error documents were treated as network failures (infinite reconnect at an expired sequence) — now parsed and recovered; 2. Agent restarts during recovery were adopted silently — now raise re-browse and drop stale values; 3. a never-progressing stream read Healthy forever — Degraded after 3 progress-free recoveries; 4. unbounded XML recursion could stack-overflow the server process — depth cap 64; 5. DTDs accepted on /probe and write replies — refused everywhere; 6–9. stray Description under Components, float overflow/NaN served Good, `42.000000` on ints, duplicate sibling component names. Unit 714 (was 678), integration vs the shared cppagent fixture 20/20 (was 18), plus a driver-level live run (adapter stop, Agent restart, paused Agent). `IWritable` (since 2026-08-05) writes only the Agent's AllowPut surface, never the controller; off by default behind two gates — consistent with "no controller write path". Follow-ups: #823, #824 (owner decision), #825.

dohertj2 closed this issue

2026-11-11 00:49:04 -05:00

dohertj2 referenced this issue from a commit

2026-11-11 05:24:23 -05:00

fix(mtconnect): the Agent refuses count ABOVE bufferSize, not at it (#825)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dohertj2/lmxopcua#804