@tsplc/sim 0.0.0-stage → 0.1.0

package/src/hardware/cognex.ts

@@ -0,0 +1,165 @@
+import { defineHardware, pinIn, pinOut, type Wiring } from "../hardware";
+import type { Paths } from "../paths";
+
+/** The DataMan EtherNet/IP input (reader → PLC) and output (PLC → reader) assembly fields. */
+export interface DataManAssembly {
+  Input: {
+    TriggerReady: boolean;
+    TriggerAck: boolean;
+    Acquiring: boolean;
+    MissedAcq: boolean;
+    DecodeCompleteToggle: boolean;
+    ResultsBufferOverrun: boolean;
+    ResultsAvailable: boolean;
+    GeneralFault: boolean;
+    SoftEventAck: number;
+    TriggerID: number;
+    ResultID: number;
+    ResultCode: number;
+    ResultExtended: number;
+    ResultLength: number;
+    ResultData: number[];
+  };
+  Output: {
+    TriggerEnable: boolean;
+    Trigger: boolean;
+    BufferResultsEnable: boolean;
+    ResultsAck: boolean;
+    SoftEvent: number;
+  };
+}
+
+const pins = {
+  TriggerEnable: pinIn("bool"),
+  Trigger: pinIn("bool"),
+  BufferResultsEnable: pinIn("bool"),
+  ResultsAck: pinIn("bool"),
+  SoftEvent: pinIn("number"),
+  TriggerReady: pinOut("bool"),
+  TriggerAck: pinOut("bool"),
+  Acquiring: pinOut("bool"),
+  MissedAcq: pinOut("bool"),
+  DecodeCompleteToggle: pinOut("bool"),
+  ResultsBufferOverrun: pinOut("bool"),
+  ResultsAvailable: pinOut("bool"),
+  GeneralFault: pinOut("bool"),
+  SoftEventAck: pinOut("number"),
+  TriggerID: pinOut("number"),
+  ResultID: pinOut("number"),
+  ResultCode: pinOut("number"),
+  ResultExtended: pinOut("number"),
+  ResultLength: pinOut("number"),
+  ResultData: pinOut("bytes"),
+};
+
+/** Wires every assembly field of a PLC record that uses the Cognex field names. */
+export const datamanWiring = (record: Paths<DataManAssembly>): Wiring<typeof pins> =>
+  // Paths are proxies without enumerable keys, so name each field.
+  Object.fromEntries(
+    Object.entries(pins).map(([name, pin]) => [
+      name,
+      Reflect.get(pin.direction === "in" ? record.Output : record.Input, name),
+    ]),
+  );
+
+export interface DataManConfig {
+  /** Self (presentation) mode: one acquisition per load passing the reader. */
+  trigger: "self";
+  /** Result data bytes in the input assembly. */
+  resultSize: number;
+  /** Results the reader buffers before reporting an overrun. */
+  bufferSize?: number;
+}
+
+interface Result {
+  data: number[];
+  id: number;
+}
+
+/**
+ * Cognex DataMan reader on EtherNet/IP, in Self trigger mode with result buffering and the
+ * ResultsAvailable/ResultsAck handshake. A load passing the reader is one acquisition; an empty
+ * code is a no-read.
+ *
+ * https://docs.cognex.com/dmst_2541/web/EN/Industrial_Protocols_Manual/Content/Topics/PDF/DIPM/eip-operation.htm
+ */
+export const dataman = defineHardware({
+  name: "Cognex DataMan",
+  pins,
+  world: (): { in: { read: string | null }; out: Record<string, never> } => ({
+    in: { read: null },
+    out: {},
+  }),
+  setup: (config: DataManConfig) => ({
+    acquisition: null as Result | null,
+    queue: [] as Result[],
+    staged: false,
+    reads: 0,
+    bufferSize: config.bufferSize ?? 50,
+  }),
+  update: ({ pins: io, world, config, state }) => {
+    // The assembly always carries `resultSize` bytes.
+    if (io.ResultData.length !== config.resultSize)
+      io.ResultData = Array(config.resultSize).fill(0);
+    io.TriggerReady = false;
+    io.TriggerAck = false;
+    io.Acquiring = false;
+    if (!io.BufferResultsEnable) state.queue = [];
+    if (io.ResultsAck) io.ResultsAvailable = false;
+    // The PLC can scan between separately written fields, so a result's fields go out one
+    // tick before ResultsAvailable announces them, as the reader's assembly would arrive whole.
+    if (state.staged) {
+      io.ResultsAvailable = !io.ResultsAck;
+      state.staged = false;
+    }
+
+    // Last tick's acquisition decodes now.
+    if (state.acquisition) {
+      io.DecodeCompleteToggle = !io.DecodeCompleteToggle;
+      const room =
+        !io.BufferResultsEnable ||
+        state.queue.length + Number(io.ResultsAvailable) < state.bufferSize;
+      io.ResultsBufferOverrun = !room;
+      if (room) state.queue.push(state.acquisition);
+    }
+
+    const canPublish =
+      !io.BufferResultsEnable || (!io.ResultsAvailable && !io.ResultsAck && !state.staged);
+    const result = canPublish ? state.queue.shift() : undefined;
+    if (result) {
+      io.ResultID = result.id;
+      io.ResultCode = result.data.length ? 1 : 0;
+      io.ResultExtended = 0;
+      io.ResultLength = result.data.length;
+      io.ResultData = Array.from({ length: config.resultSize }, (_, i) => result.data[i] ?? 0);
+      state.staged = true;
+    }
+
+    state.acquisition =
+      world.in.read !== null
+        ? { data: [...new TextEncoder().encode(world.in.read)], id: io.TriggerID }
+        : null;
+    if (state.acquisition) {
+      state.reads++;
+      io.TriggerID = (io.TriggerID + 1) % 65_536;
+      io.Acquiring = true;
+      io.MissedAcq = false;
+    }
+  },
+  view: ({ pins: io, state }) => ({
+    status: io.ResultsAvailable ? "busy" : "idle",
+    label: io.ResultsAvailable ? "result waiting" : `${state.reads} reads`,
+    details: {
+      lastResult: new TextDecoder().decode(
+        Uint8Array.from(io.ResultData.slice(0, io.ResultLength)),
+      ),
+      queued: state.queue.length,
+    },
+  }),
+  actions: {
+    /** Presents a code to the reader as if a load passed it; an empty code is a no-read. */
+    read: ({ world }, code) => {
+      world.in.read = code;
+    },
+  },
+});

package/src/hardware/generic.ts

@@ -0,0 +1,74 @@
+import { defineHardware, pinIn, pinOut } from "../hardware";
+
+const noWorld = (): { in: Record<string, never>; out: Record<string, never> } => ({
+  in: {},
+  out: {},
+});
+
+/**
+ * A pushbutton or switch contact wired to a PLC input. Momentary buttons stay pressed for
+ * `pressMs` after `press`; maintained ones (such as an e-stop) stay until `release`.
+ */
+export const pushbutton = defineHardware({
+  name: "Pushbutton",
+  pins: { contact: pinOut("bool") },
+  world: noWorld,
+  setup: (config: { kind: "momentary" | "maintained"; pressMs?: number }) => ({
+    pressed: false,
+    remainingMs: 0,
+    pressMs: config.pressMs ?? 300,
+  }),
+  update: ({ pins, config, state, dtMs }) => {
+    if (config.kind === "momentary" && state.pressed) {
+      state.remainingMs -= dtMs;
+      if (state.remainingMs <= 0) state.pressed = false;
+    }
+    pins.contact = state.pressed;
+  },
+  view: ({ state }) => ({
+    status: state.pressed ? "busy" : "idle",
+    label: state.pressed ? "pressed" : "released",
+  }),
+  actions: {
+    press: ({ state }) => {
+      state.pressed = true;
+      state.remainingMs = state.pressMs;
+    },
+    release: ({ state }) => {
+      state.pressed = false;
+    },
+  },
+});
+
+/** A two-position selector switch wired to a PLC input, such as a station's enable switch. */
+export const selector = defineHardware({
+  name: "Selector switch",
+  pins: { contact: pinOut("bool") },
+  world: noWorld,
+  setup: (config: { on: boolean }) => ({ on: config.on }),
+  update: ({ pins, state }) => {
+    pins.contact = state.on;
+  },
+  view: ({ state }) => ({ status: state.on ? "running" : "idle", label: state.on ? "on" : "off" }),
+  actions: {
+    on: ({ state }) => {
+      state.on = true;
+    },
+    off: ({ state }) => {
+      state.on = false;
+    },
+  },
+});
+
+/** A lamp, beacon or horn driven by a PLC output. */
+export const lamp = defineHardware({
+  name: "Lamp",
+  pins: { power: pinIn("bool") },
+  world: noWorld,
+  setup: (config: { label?: string }) => config,
+  update: () => {},
+  view: ({ pins, state }) => ({
+    status: pins.power ? "running" : "idle",
+    label: `${state.label ?? "lamp"} ${pins.power ? "on" : "off"}`,
+  }),
+});

package/src/hardware/intelligrated.ts

@@ -0,0 +1,150 @@
+import { defineHardware, pinIn, pinOut } from "../hardware";
+
+type Switch =
+  | `SW1-${1 | 2 | 3 | 4 | 5 | 6}`
+  | `SW2-${1 | 2 | 3 | 4 | 5 | 6}`
+  | `SW3-${1 | 2 | 3 | 4 | 5 | 6}`
+  | `SW4-${1 | 2 | 3 | 4 | 5 | 6}`;
+/** Switches this model reads; ON is `true`. The rest are "as fitted" and may be recorded too. */
+type ModelledSwitch =
+  | "SW1-1"
+  | "SW1-4"
+  | "SW1-5"
+  | "SW2-1"
+  | "SW2-2"
+  | "SW2-6"
+  | "SW3-1"
+  | "SW3-2"
+  | "SW3-3"
+  | "SW3-4"
+  | "SW3-5"
+  | "SW3-6";
+
+export interface Cs1001Config {
+  /** DIP switches as set on the card (ON = `true`). */
+  switches: Record<ModelledSwitch, boolean> & Partial<Record<Switch, boolean>>;
+  /** Roller surface speed at full speed (10 V on CN2-3), in mm/s. */
+  ratedSpeed: number;
+  /** Rotation that moves a load forward (downstream, or right for a transfer belt). */
+  forward: "CW" | "CCW";
+  /** SW1-1 OFF only: the SW4-1..4 internal speed as a fraction of `ratedSpeed`. */
+  internalSpeed?: number;
+  /** SW2-1 OFF (INT) only: how long an unlinked zone runs to release a load by itself. */
+  runHoldingMs?: number;
+}
+
+/** SW3-4/SW3-5 acceleration/deceleration times from the WWL manual §3-5 (via docs/hardware.md). */
+const rampMs = (on4: boolean, on5: boolean) => (on4 ? (on5 ? 200 : 240) : on5 ? 400 : 600);
+
+/** The manual's speed table stops the roller below its first band (2.55–2.95 V). */
+const minimumVolts = 2.55;
+
+const pins = {
+  /** Run/stop control: forces RUN (SW2-6 ON) or STOP (SW2-6 OFF) while active. */
+  "CN2-1": pinIn("bool"),
+  /** Reverses rotation while active (ZPA mode); SW3-1 selects its polarity. */
+  "CN2-2": pinIn("bool"),
+  /** Speed command, 0–10 V (SW1-1 EXT). Wire with `analog()` from the PLC's raw value. */
+  "CN2-3": pinIn("number"),
+  /** Zone photoeye blocked. */
+  "CN2-4": pinOut("bool"),
+  "CN2-5": pinOut("bool"),
+  "CN2-6": pinOut("bool"),
+  /** Motor running (sync), independent of the CN2-1 command. */
+  "CN2-7": pinOut("bool"),
+};
+
+/**
+ * Intelligrated CS1001 MDR control card (Hope/WWL "DC Brushless Motor Power Roller Intelligent
+ * Control Card") driving one zone, configured by its DIP switches and wired through CN2.
+ *
+ * Modelled: ZPA mode without neighbour links (CN4/CN5 unwired), CN2-1 force run/stop (SW2-6),
+ * EOZ/INT end-of-zone behaviour (SW2-1), CN2-2 direction (SW3-1/SW3-2), CN2-3 external speed
+ * (SW1-1), acceleration (SW3-4/SW3-5), and the CN2-4/CN2-5/CN2-6/CN2-7 outputs. Linked ZPA,
+ * Master/Slave modes, half-speed control and output polarities other than PNP are not modelled
+ * and are rejected, because the source behaviour is not documented here.
+ */
+export const cs1001 = defineHardware({
+  name: "Intelligrated CS1001",
+  pins,
+  world: () => ({ in: { photoeye: false }, out: { motor: 0 } }),
+  setup: (config: Cs1001Config) => {
+    const sw = config.switches;
+    const unsupported = (setting: string) => {
+      throw new Error(`CS1001: ${setting} is not modelled.`);
+    };
+    if (sw["SW1-4"] || sw["SW1-5"]) unsupported("Master/Slave mode (SW1-4/SW1-5)");
+    if (sw["SW3-6"]) unsupported("half-speed control (SW3-6 ON)");
+    if (!sw["SW3-3"]) unsupported("NPN CN2-4..7 outputs (SW3-3 OFF)");
+    if (!sw["SW1-1"] && config.internalSpeed === undefined)
+      throw new Error("CS1001: SW1-1 OFF (internal speed) needs internalSpeed.");
+    if (!sw["SW2-1"] && config.runHoldingMs === undefined)
+      throw new Error("CS1001: SW2-1 OFF (INT release) needs runHoldingMs.");
+    return { speed: 0, releasingMs: 0, error: false, warning: false };
+  },
+  update: ({ pins: io, world, config, state, dtMs }) => {
+    const sw = config.switches;
+    // FIELD-CONFIRMED 2026-10-24: with SW2-2 OFF (NPN) the B&R's sourcing output reads as
+    // active, so the card runs whatever the PLC writes.
+    const control = sw["SW2-2"] ? io["CN2-1"] : true;
+    let run: boolean;
+    if (sw["SW2-6"] && control) run = true;
+    else if (!sw["SW2-6"] && control) run = false;
+    else if (sw["SW2-1"])
+      run = false; // EOZ holds its load until CN2-1 runs it.
+    else {
+      // INT: an unlinked zone with a blocked photoeye releases by itself until its run-holding timer expires.
+      state.releasingMs = world.in.photoeye ? state.releasingMs + dtMs : 0;
+      run = world.in.photoeye && state.releasingMs < (config.runHoldingMs ?? 0);
+    }
+    if (state.error) run = false;
+    const volts = io["CN2-3"];
+    const fraction = sw["SW1-1"]
+      ? volts < minimumVolts
+        ? 0
+        : Math.min(volts, 10) / 10
+      : (config.internalSpeed ?? 0);
+    // SW3-1 ON: CN2-2 active at 24 V (the PLC's TRUE); OFF (NPN): active at 0 V.
+    const reverse = sw["SW3-1"] ? io["CN2-2"] : !io["CN2-2"];
+    const base = sw["SW3-2"] ? "CCW" : "CW";
+    const rotation = reverse ? (base === "CW" ? "CCW" : "CW") : base;
+    const target = run ? fraction * config.ratedSpeed * (rotation === config.forward ? 1 : -1) : 0;
+    const step = (config.ratedSpeed * dtMs) / rampMs(sw["SW3-4"], sw["SW3-5"]);
+    state.speed =
+      Math.abs(target - state.speed) <= step
+        ? target
+        : state.speed + Math.sign(target - state.speed) * step;
+    world.out.motor = state.speed;
+    io["CN2-4"] = world.in.photoeye;
+    io["CN2-5"] = state.error;
+    io["CN2-6"] = state.warning;
+    io["CN2-7"] = state.speed !== 0;
+  },
+  view: ({ state, world, config }) => ({
+    status: state.error
+      ? "fault"
+      : state.warning || !config.switches["SW2-2"]
+        ? "warning"
+        : state.speed !== 0
+          ? "running"
+          : "stopped",
+    label: state.speed !== 0 ? `${Math.round(Math.abs(state.speed))} mm/s` : "stopped",
+    details: {
+      photoeye: world.in.photoeye,
+      ...(!config.switches["SW2-2"] && { note: "SW2-2 NPN: CN2-1 is ignored" }),
+    },
+  }),
+  actions: {
+    /** Raises CN2-5 and stops the motor, as a stall or jam would. */
+    fault: ({ state }) => {
+      state.error = true;
+    },
+    warn: ({ state }) => {
+      state.warning = true;
+    },
+    reset: ({ state }) => {
+      state.error = false;
+      state.warning = false;
+    },
+  },
+});

package/src/hardware.ts

@@ -0,0 +1,167 @@
+import { type Path, pathName } from "./paths";
+
+type PinType = "bool" | "number" | "bytes";
+type PinValue<Type extends PinType> = Type extends "bool"
+  ? boolean
+  : Type extends "number"
+    ? number
+    : number[];
+
+/** An electrical terminal, seen from the device: `in` is driven by the PLC, `out` drives a PLC input. */
+export interface Pin {
+  readonly direction: "in" | "out";
+  readonly type: PinType;
+}
+export const pinIn = <Type extends PinType>(type: Type) => ({ direction: "in", type }) as const;
+export const pinOut = <Type extends PinType>(type: Type) => ({ direction: "out", type }) as const;
+export type Pins = Record<string, Pin>;
+
+/** Converts between a PLC value and a pin value, such as raw analog counts and volts. */
+export interface Scaled {
+  readonly path: Path<number>;
+  readonly toPin: (plc: number) => number;
+  readonly toPlc: (pin: number) => number;
+}
+export type Wire<Value> = Path<Value> | (Value extends number ? Scaled : never);
+
+/**
+ * A linear analog channel: `analog(path, { plc: [0, 32767], pin: [0, 10] })` wires a raw
+ * 0..32767 output to a 0..10 V input.
+ */
+export const analog = (
+  path: Path<number>,
+  range: { plc: readonly [number, number]; pin: readonly [number, number] },
+): Scaled => {
+  const [plcLow, plcHigh] = range.plc,
+    [pinLow, pinHigh] = range.pin;
+  return {
+    path,
+    toPin: (plc) => pinLow + ((plc - plcLow) * (pinHigh - pinLow)) / (plcHigh - plcLow),
+    toPlc: (pin) => Math.round(plcLow + ((pin - pinLow) * (plcHigh - plcLow)) / (pinHigh - pinLow)),
+  };
+};
+
+/** Each pin may be wired to one PLC variable of its type; unwired inputs read as their default. */
+export type Wiring<Spec extends Pins> = {
+  readonly [Name in keyof Spec]?: Wire<PinValue<Spec[Name]["type"]>>;
+};
+type PinValues<Spec extends Pins> = { [Name in keyof Spec]: PinValue<Spec[Name]["type"]> };
+
+export interface DeviceView {
+  status: "running" | "stopped" | "idle" | "busy" | "warning" | "fault";
+  label?: string;
+  details?: Record<string, string | number | boolean>;
+}
+
+export interface HardwareContext<Spec extends Pins, World extends WorldPorts, Config, State> {
+  /** Input pins hold this tick's PLC values; set output pins to drive PLC inputs. */
+  readonly pins: PinValues<Spec>;
+  /** Physical ports the topology connects: `in` is sensed from the line, `out` acts on it. */
+  readonly world: World;
+  readonly config: Config;
+  readonly state: State;
+  readonly dtMs: number;
+}
+
+interface WorldPorts {
+  in: Record<string, unknown>;
+  out: Record<string, unknown>;
+}
+
+export interface HardwareModel<Spec extends Pins, World extends WorldPorts, Config, State> {
+  /** Product name, such as "Intelligrated CS1001". */
+  readonly name: string;
+  readonly pins: Spec;
+  /** Initial physical port values; they also fix each port's type. */
+  readonly world: () => World;
+  /** Validates the configuration (switch settings) and creates the device's private state. */
+  readonly setup: (config: Config) => State;
+  /** Runs once per tick: read input pins and `world.in`, then set output pins and `world.out`. */
+  readonly update: (context: HardwareContext<Spec, World, Config, State>) => void;
+  readonly view?: (context: HardwareContext<Spec, World, Config, State>) => DeviceView;
+  readonly actions?: Record<
+    string,
+    (context: HardwareContext<Spec, World, Config, State>, argument: string) => void
+  >;
+}
+
+/** One physical device on the line: a model, its configuration and its wiring. */
+export interface Device<World extends WorldPorts = WorldPorts> {
+  readonly model: string;
+  readonly world: World;
+  /** PLC variables this device reads each tick. */
+  readonly reads: readonly string[];
+  /** Sets input pins from PLC values, runs the model and returns the PLC values it drives. */
+  readonly update: (plc: ReadonlyMap<string, unknown>, dtMs: number) => Map<string, unknown>;
+  readonly view: () => DeviceView;
+  readonly pins: () => Record<string, unknown>;
+  readonly actions: readonly string[];
+  readonly act: (action: string, argument: string) => void;
+}
+
+const defaultValue = (type: PinType): PinValue<PinType> =>
+  type === "bool" ? false : type === "number" ? 0 : [];
+
+const isScaled = (wire: Wire<never> | Scaled | Path<unknown>): wire is Scaled => "toPin" in wire;
+/** The PLC variable a wire connects to. */
+export const wirePath = (wire: Path<unknown> | Scaled) =>
+  isScaled(wire) ? pathName(wire.path) : pathName(wire);
+
+/**
+ * Defines a hardware model. The result is a factory that instantiates one device from its
+ * configuration and wiring: `cs1001({ config: { switches }, wiring: { "CN2-1": path } })`.
+ */
+export const defineHardware =
+  <Spec extends Pins, World extends WorldPorts, Config, State>(
+    model: HardwareModel<Spec, World, Config, State>,
+  ) =>
+  (options: { config: Config; wiring: Wiring<Spec> }): Device<World> => {
+    const state = model.setup(options.config);
+    const world = model.world();
+    const pins = Object.fromEntries(
+      Object.entries(model.pins).map(([name, pin]) => [name, defaultValue(pin.type)]),
+    ) as PinValues<Spec>; // Each entry is the default of its declared pin type.
+    let dtMs = 0;
+    const context = (): HardwareContext<Spec, World, Config, State> => ({
+      pins,
+      world,
+      config: options.config,
+      state,
+      dtMs,
+    });
+    const wired = Object.entries(options.wiring).flatMap(([name, wire]) => {
+      const pin = model.pins[name];
+      if (!pin) throw new Error(`${model.name} has no pin ${String(name)}.`);
+      const target: Path<unknown> | Scaled | undefined = wire;
+      return target ? [{ name, pin, wire: target, path: wirePath(target) }] : [];
+    });
+    return {
+      model: model.name,
+      world,
+      reads: wired.filter(({ pin }) => pin.direction === "in").map(({ path }) => path),
+      update: (plc, elapsed) => {
+        dtMs = elapsed;
+        for (const { name, pin, wire, path } of wired) {
+          if (pin.direction !== "in" || !plc.has(path)) continue;
+          const value = plc.get(path);
+          Reflect.set(pins, name, isScaled(wire) ? wire.toPin(Number(value)) : value);
+        }
+        model.update(context());
+        const writes = new Map<string, unknown>();
+        for (const { name, pin, wire, path } of wired) {
+          if (pin.direction !== "out") continue;
+          const value: unknown = Reflect.get(pins, name);
+          writes.set(path, isScaled(wire) ? wire.toPlc(Number(value)) : value);
+        }
+        return writes;
+      },
+      view: () => model.view?.(context()) ?? { status: "idle" },
+      pins: () => ({ ...pins }),
+      actions: Object.keys(model.actions ?? {}),
+      act: (action, argument) => {
+        const handler = model.actions?.[action];
+        if (!handler) throw new Error(`${model.name} has no action ${action}.`);
+        handler(context(), argument);
+      },
+    };
+  };

package/src/index.ts

@@ -0,0 +1,44 @@
+export { plcPaths, pathName, type Path, type Paths } from "./paths";
+export {
+  analog,
+  defineHardware,
+  pinIn,
+  pinOut,
+  type Device,
+  type DeviceView,
+  type HardwareModel,
+  type Pin,
+  type Pins,
+  type Wire,
+  type Wiring,
+} from "./hardware";
+export {
+  conveyor,
+  defineLine,
+  keyed,
+  photoeye,
+  pickup,
+  reader,
+  part,
+  section,
+  station,
+  zone,
+  type Conveyor,
+  type CustomPart,
+  type Heading,
+  type Motion,
+  type Sensing,
+  type Line,
+  type Part,
+  type Pickup,
+  type Station,
+  type Target,
+} from "./line";
+export {
+  createSimulation,
+  type Load,
+  type Simulation,
+  type SimulationIo,
+  type SimulationState,
+} from "./simulation";
+export { plcIo } from "./io";

package/src/io.ts

@@ -0,0 +1,27 @@
+import type { SimulationIo } from "./simulation";
+
+/** The PLC client calls the simulation needs, as provided by `createPlc` from `@tsplc/opcua`. */
+interface PlcClient {
+  read: (
+    paths: Iterable<string>,
+  ) => Promise<Record<string, { quality: string; status: string; value: unknown }>>;
+  write: (values: ReadonlyMap<string, unknown>) => Promise<unknown>;
+}
+
+/** Exchanges the simulation's I/O over a `createPlc` session; unreadable inputs fail the tick. */
+export const plcIo = (plc: PlcClient): SimulationIo => ({
+  read: async (paths) => {
+    const readings = await plc.read(paths);
+    return new Map(
+      paths.map((path) => {
+        const reading = readings[path];
+        if (reading?.quality !== "good")
+          throw new Error(`Cannot read ${path}: ${reading?.status ?? "missing"}`);
+        return [path, reading.value];
+      }),
+    );
+  },
+  write: async (values) => {
+    await plc.write(values);
+  },
+});