04tools2026

OpenXHC: Reverse-Engineering a CNC Motion Interface

A C++20 offline codec turned a closed, Windows-only CNC motion interface into a testable native Linux foundation, reconstructing 2,490 captured HID reports byte for byte with zero mismatches and matching machine coordinates within 0.0005 mm.

The result is a deterministic native Linux foundation for replaying and testing the motion interface without touching the controller. It enables the next engineering steps to start from measured behavior: USB transport, trajectory integration, safety supervision, and a LinuxCNC HAL boundary.

Real machine and camera-difference evidence paired with capture-backed codec results. Offline codec only; no USB writes.

Role: Protocol investigation, C++20 codec design, capture-backed validation, safety boundaries, and the integration plan for a future Linux-native driver.
System boundary: Owner-authorized machine captures feed a fixed-capacity C++20 encoder and decoder, then a capture validator checks whole motion bursts, byte-exact reconstruction, and decoded coordinate agreement. The current boundary ends before USB transport or machine control.
Primary constraint: Keep the development path offline: the codec must not open the device or transmit USB reports.
Strongest evidence: Across 14 owner-authorized move bursts, 2,490 real reports re-encoded byte-exact with 0 mismatches, and decoded machine coordinates agreed with the controller display within 0.0005 mm.

The situation

A proprietary motion-control card kept an otherwise capable CNC router tied to one legacy software stack, with no documented native Linux path for understanding the device's motion and status traffic.

Without a trustworthy software model of the interface, every Linux integration experiment would either depend on guesswork or risk sending unverified data to physical hardware.

Constraints

Keep the development path offline: the codec must not open the device or transmit USB reports.
Use owner-authorized traffic from the real machine as the validation source without publishing raw captures, protocol bytes, private paths, or recovered commands.
Separate what the evidence proves today from the USB transport, trajectory planning, safety supervision, and LinuxCNC HAL work that remains.

My responsibility

Protocol investigation, C++20 codec design, capture-backed validation, safety boundaries, and the integration plan for a future Linux-native driver.

The system

Owner-authorized machine captures feed a fixed-capacity C++20 encoder and decoder, then a capture validator checks whole motion bursts, byte-exact reconstruction, and decoded coordinate agreement. The current boundary ends before USB transport or machine control.

Architecture descriptionReal CNC capture evidence flows into an offline C++20 encoder and decoder, then into byte-exact replay and coordinate checks, while USB transport and LinuxCNC integration remain outside the current boundary.

Owner-authorized captures
Real motion evidence retained privately and summarized safely.
Offline C++20 codec
Fixed-capacity parsing and encoding with no device-open path.
Byte-exact validator
Captured reports must reconstruct exactly, not just round-trip.
Coordinate comparison
Decoded positions are checked against observed machine coordinates.

Illustrative CNC evidence flow passing through offline validation stages before a hard machine-control boundary. — Illustrative model. Aggregate metrics are measured; no protocol bytes are shown.

Critical decisions

Make the first deliverable unable to move the machine

Choice: Build the protocol logic as an offline codec with no device-open or USB-write path.
Alternatives considered: Combine early protocol experiments with live hardware transmission.
Tradeoff: This delays direct Linux control, but it makes the inferred model testable without turning incomplete knowledge into physical motion.

Require real-traffic reconstruction

Choice: Validate the encoder and decoder against captured machine traffic, including byte-exact report reconstruction and coordinate comparison.
Alternatives considered: Rely only on synthetic round-trip tests generated by the codec itself.
Tradeoff: Capture validation needs carefully retained private evidence, but it can falsify a self-consistent codec that still misunderstands the real device.

Treat evidence gates as part of the interface

Choice: Keep raw records and field-level protocol details private until an independent second-day capture clears the project's public evidence rule.
Alternatives considered: Publish the current inferred field map after two same-day sessions.
Tradeoff: Public documentation moves more slowly, while the project avoids turning a plausible inference into an unsupported compatibility promise.

Proof

Real-traffic codec validationAcross 14 owner-authorized move bursts, 2,490 real reports re-encoded byte-exact with 0 mismatches, and decoded machine coordinates agreed with the controller display within 0.0005 mm.

Evidence boundary: The evidence covers an offline C++20 codec and validator against two same-day, owner-authorized capture sessions from one XHC MK4-IV controller. Public media uses a sanitized machine view and camera-difference derivative, not raw traffic.
Known limits: The current artifact has no USB transport, no device writes, no trajectory planner, no LinuxCNC HAL integration, and no machine-control path. A second-day capture remains the evidence gate before publishing field-level protocol details or treating the interface map as stable.

Engineering signal

Why this matters to engineering teams

OpenXHC demonstrates the judgment required to make an undocumented physical-system boundary measurable, testable, and safe enough for a team to extend deliberately.

Falsifiable interface model

The codec must reproduce traffic created outside the implementation, so an incorrect model can fail visibly.

Hardware-safe iteration

Protocol work remains offline, allowing fast test cycles without turning incomplete knowledge into physical motion.

Portable integration boundary

Parsing is isolated from transport, planning, supervision, and the future LinuxCNC HAL layer.

Evidence-led systems work

Measured results, explicit limits, and publication gates separate demonstrated capability from future scope.

Reflection

Byte-exact reconstruction is a stronger protocol check than a synthetic encoder-decoder round trip because the device traffic was produced outside the implementation under test.
Physical-system software becomes easier to reason about when parsing, transport, planning, and actuation are separate boundaries.
A useful early milestone can remove uncertainty without pretending to deliver machine control before its safety layers exist.