Device abstraction
Virtual and real devices implement the same interfaces — that is what makes "prove it on the virtual rig first" a real strategy.
In one line
The layers above do not know whether they are talking to a virtual device or a real one.
That is not an aesthetic choice. It decides three things:
- whether someone with no hardware can run the whole procedure;
- whether a procedure validated on virtual devices has to be rewritten on site;
- whether end-to-end tests can run in CI.
What the interfaces look like
One interface per device class, exposing what the business actually needs — never the
vendor SDK's shape. Every device interface derives from IDeviceConnection (name, connection
state, connect/disconnect with reconnect backoff):
public interface IImagingDevice : IDeviceConnection
{
IReadOnlyList<string> CameraIds { get; }
Task<Frame> GrabAsync(string cameraId, CancellationToken ct = default);
Task SetExposureAsync(string cameraId, double us);
Task SetGainAsync(string cameraId, double db);
Task<(double ExposureUs, double GainDb)> GetSettingsAsync(string cameraId);
}
public interface IMotionDevice : IDeviceConnection
{
Task<AxisState> GetStateAsync(int axis); // commanded/reported position, moving, servo, homed, limits, fault
Task ServoAsync(int axis, bool on);
Task HomeAsync(int axis, CancellationToken ct = default);
Task MoveAbsAsync(int axis, double mm, double velMmPerS, CancellationToken ct = default);
Task MoveRelAsync(int axis, double mm, double velMmPerS, CancellationToken ct = default);
Task MoveAbsMultiAsync(IReadOnlyList<int> axes, IReadOnlyList<double> mm,
double velMmPerS, CancellationToken ct = default);
Task StopAsync(int axis);
Task WaitDoneAsync(int axis, int timeoutMs, CancellationToken ct = default);
IAsyncEnumerable<IReadOnlyList<double>> PositionStream(CancellationToken ct);
}
public interface IIoDevice : IDeviceConnection
{
IReadOnlyList<IoPointInfo> Points { get; } // name / direction / group / platform / role
// reads and writes go by point name, never by a bare channel number
}A complete rig is an IDeviceSet: Motion, Imaging, Io, ScanHead, Laser,
RangeFinder, Light. The layers above know only that set.
Note what is not in the interfaces: no GetBaslerHandle(), no SendGCode(string), no
vendor-specific escape hatch. Open one and the layers above start depending on it, and the
abstraction is gone.
Three details worth calling out:
AxisStatereports the controller's reported position, not the true one. On the virtual machine the two differ on purpose (by a read noise term and a pitch error). If they were equal, calibration would fit an identity transform and measure nothing.- IO is addressed by point name, and the UI is generated from the point table. Adding a cylinder is a table edit, not a UI edit.
- A grab returns a
Frame: 8-bit greyscale, width, height, timestamp, camera id, plus aPrincipalPoint(image centre; calibration uses it as the reference per C4).
A machine is assembled from configuration
What a machine is lives in a machine description file (the engine package ships
machines/demo-xy-galvo.json). Changing machines changes that file, not the code:
{
"name": "demo-xy-galvo",
"world": { "widthMm": 600, "heightMm": 400, "umPerPixel": 0.8 },
"axes": [
{ "name": "X", "index": 0, "minMm": -165, "maxMm": 165, "velocityMmPerS": 300,
"pitchErrorAmpMm": 0.0008, "pitchErrorPeriodMm": 50, "repeatabilityMm": 0.0002 },
{ "name": "Y", "index": 1, "minMm": -120, "maxMm": 120, "velocityMmPerS": 300, "...": "" },
{ "name": "Z", "index": 2, "minMm": 80, "maxMm": 140, "velocityMmPerS": 20, "...": "" }
],
"cameras": [
{ "name": "cam0", "width": 4096, "height": 3000,
"pixelSizeUm": 1.7236, // * true pixel size
"rotationDeg": -0.80, // * true mounting angle (the sign is easy to flip)
"workingDistanceMm": 110, "zMountOffsetMm": 2.347, // * focus Z is the sum of these
"depthOfFieldMm": 0.17, "k1": 0.0, "k2": 0.0 }
],
"scanHeads": [
{ "name": "galvo0", "fieldSizeMm": 40,
"offsetXMm": 0.412, "offsetYMm": 55.180, // * camera-to-actuator offset
"scaleX": 1.0012, "scaleY": 0.9993, "k1": 1.8e-5, "skew": 3.0e-4 }
]
}The starred fields are exactly what the calibration chains have to measure — and therefore
what the automatic scoring compares against. On the HMI side a single line in appsettings.json
(Device.Mode: Sim or Real) decides which implementation is wired up. No conditional
compilation.
How virtual is the virtual machine
It is not a stub returning canned data; it computes from a physical model:
| Device | What is modelled |
|---|---|
| Camera | Field-of-view mapping, radial distortion (k1/k2), mounting angle, Gaussian defocus blur, exposure/gain/illumination, Gaussian noise |
| Axis | Point-to-point moves, soft limits, homing, periodic pitch error, repeatability, read noise, e-stop |
| Stage | Tilt and flatness ripple (which change defocus, and therefore sharpness) |
| IO | Point table + interlock rules (A changes, B follows after t) + fault injection |
| Galvo | Field distortion (scale / distortion / skew), mounting offset relative to the camera |
| Laser | Mark morphology (ring), beam waist and Rayleigh length, power/frequency response and noise |
Not modelled: acceleration profiles and S-curves, backlash, servo tuning and mechanical resonance, diffraction-level PSF. None of them help you learn a calibration chain, and each one makes the model harder to explain.
The most useful teaching move is to exaggerate one parameter — push the camera mounting angle from −0.8° to −5°, then have a trainee run pixel-size calibration and watch what a mounting angle actually does.
The models are documented in Physics and models.
What does not belong in the device layer
- Business logic. "Blow air, then grab" is workflow, not camera.
- Calibration results. Those describe the machine's current state and live in the calibration store, not on a device object.
- Retry policy. Devices report faults honestly; retry / skip / abort is decided once, in the workflow.
Hold those three lines and swapping hardware really is just a configuration change.