Skip to content
PreciSim
concepts

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:

  1. whether someone with no hardware can run the whole procedure;
  2. whether a procedure validated on virtual devices has to be rewritten on site;
  3. 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:

  • AxisState reports 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 a PrincipalPoint (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.

Last updated: Sep 22, 2026
Was this page helpful?