@tsplc/sim 0.0.0-stage → 0.1.0

package/src/serve.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { page } from "./page";
+import type { Simulation } from "./simulation";
+
+/** An operator or test action the view offers, such as "Receive bin at Framing01". */
+export interface SimulationAction {
+  id: string;
+  label: string;
+  /** The station, part or load it concerns; the view lists it there. */
+  at?: string;
+  run: () => Promise<void> | void;
+}
+
+export interface ServeSimulationOptions {
+  hostname: string;
+  port: number;
+  title?: string;
+  periodMs?: number;
+  /** Actions currently available, recomputed for every view refresh. */
+  actions?: () => SimulationAction[];
+  /** Extra CSS for the page, such as colour overrides. */
+  css?: string;
+  log?: { warn: (message: string, error: unknown) => void };
+}
+
+const controlSchema = z.object({ pause: z.boolean().optional(), step: z.boolean().optional() });
+const deviceActionSchema = z.object({
+  device: z.string(),
+  action: z.string(),
+  argument: z.string().default(""),
+});
+
+const loadSchema = z.object({ id: z.string() });
+
+const json = (body: unknown, status = 200) =>
+  Response.json(body, { status, headers: { "Cache-Control": "no-store" } });
+
+/**
+ * Runs a simulation in real time and serves its live view: the line drawn from its topology,
+ * device inspector and actions, the application's actions, removing loads by hand, and pause/step.
+ */
+export const serveSimulation = (
+  simulation: Pick<Simulation, "state" | "step" | "act" | "remove" | "run">,
+  options: ServeSimulationOptions,
+) => {
+  const controller = new AbortController();
+  const periodMs = options.periodMs ?? 50;
+  let paused = false;
+  const actions = () => options.actions?.() ?? [];
+  const attempt = async (run: () => Promise<void> | void) => {
+    try {
+      await run();
+      return json({ ok: true });
+    } catch (error) {
+      options.log?.warn("Simulation action failed", error);
+      return json({ message: error instanceof Error ? error.message : String(error) }, 409);
+    }
+  };
+  const server = Bun.serve({
+    hostname: options.hostname,
+    port: options.port,
+    routes: {
+      "/": () =>
+        new Response(page({ title: options.title ?? "Simulation", css: options.css ?? "" }), {
+          headers: { "Content-Type": "text/html; charset=utf-8" },
+        }),
+      "/state": () =>
+        json({
+          ...simulation.state(),
+          paused,
+          actions: actions().map(({ id, label, at }) => ({ id, label, at })),
+        }),
+      "/control": {
+        POST: async (request) => {
+          const command = controlSchema.parse(await request.json());
+          if (command.pause !== undefined) paused = command.pause;
+          if (command.step) await simulation.step(periodMs);
+          return json({ paused });
+        },
+      },
+      "/devices/act": {
+        POST: async (request) => {
+          const { device, action, argument } = deviceActionSchema.parse(await request.json());
+          return attempt(() => simulation.act(device, action, argument));
+        },
+      },
+      "/loads/remove": {
+        POST: async (request) => {
+          const { id } = loadSchema.parse(await request.json());
+          return attempt(() => simulation.remove(id));
+        },
+      },
+      "/actions/:id": {
+        POST: (request) => {
+          const action = actions().find(({ id }) => id === request.params.id);
+          return action
+            ? attempt(action.run)
+            : json({ message: "Action no longer available" }, 404);
+        },
+      },
+    },
+    fetch: () => json({ message: "Not found" }, 404),
+  });
+  const running = simulation.run(controller.signal, { periodMs, paused: () => paused });
+  return {
+    url: server.url,
+    stop: async () => {
+      controller.abort();
+      await running;
+      await server.stop(true);
+    },
+  };
+};

package/src/simulation.ts

@@ -0,0 +1,533 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { type Device, type DeviceView, wirePath } from "./hardware";
+import { drawLine } from "./layout";
+import {
+  type CustomPart,
+  type Line,
+  type Motion,
+  type Part,
+  type Station,
+  type Target,
+  targetNames,
+} from "./line";
+
+/** Reads and writes PLC variables by dotted path. */
+export interface SimulationIo {
+  read: (paths: readonly string[]) => Promise<ReadonlyMap<string, unknown>>;
+  write: (values: ReadonlyMap<string, unknown>) => Promise<void>;
+}
+
+export interface Load<Data> {
+  readonly id: string;
+  readonly kind: string;
+  readonly length: number;
+  readonly width: number;
+  /** What a reader reports for this load, such as its barcode; relabelling changes it. */
+  code: string;
+  data: Data;
+}
+
+/** Where a load is: its leading edge along a conveyor, or held at a station. */
+type Place =
+  | {
+      kind: "conveyor";
+      conveyor: string;
+      head: number;
+      lateral: number;
+      /** While its tail still hangs off the conveyor it came from, entered at `at`. */
+      from?: { conveyor: string; at: number };
+    }
+  | { kind: "station"; station: string }
+  | { kind: "waiting"; conveyor: string };
+
+interface Placed<Data> {
+  load: Load<Data>;
+  place: Place;
+}
+
+interface Segment {
+  id: string;
+  part: CustomPart;
+  start: number;
+  end: number;
+}
+interface Point {
+  id: string;
+  part: Exclude<Part, CustomPart>;
+  at: number;
+}
+interface Track {
+  id: string;
+  draw: string;
+  length: number;
+  next?: { to: string; at: number };
+  segments: Segment[];
+  points: Point[];
+}
+
+export interface SimulationState {
+  timeMs: number;
+  error: string | null;
+  conveyors: Array<{
+    id: string;
+    draw: string;
+    length: number;
+    next?: string;
+    parts: Array<{
+      id: string;
+      kind: Part["kind"];
+      label?: string;
+      start: number;
+      end: number;
+      exits?: { left?: string; right?: string };
+      station?: string;
+      side?: "left" | "right";
+      view: DeviceView;
+    }>;
+  }>;
+  stations: Array<{ id: string; label: string; loads: number }>;
+  loads: Array<{
+    id: string;
+    kind: string;
+    code: string;
+    length: number;
+    width: number;
+    place: Place;
+  }>;
+  devices: Array<{
+    id: string;
+    /** The part it belongs to; null for devices off the conveyors, such as pushbuttons. */
+    part: string | null;
+    model: string;
+    view: DeviceView;
+    pins: Record<string, unknown>;
+    actions: readonly string[];
+  }>;
+}
+
+const same = (a: unknown, b: unknown) =>
+  Array.isArray(a) && Array.isArray(b)
+    ? a.length === b.length && a.every((item, index) => item === b[index])
+    : a === b;
+
+const resolve = (
+  id: string,
+  conveyor: Line["conveyors"][string],
+  draw: string,
+  name: (target: Target) => string,
+): Track => {
+  const segments: Segment[] = [];
+  const points: Point[] = [];
+  let position = 0;
+  conveyor.parts.forEach((part, index) => {
+    const partId = part.id ?? `${id}[${index}]`;
+    if (part.kind !== "part") {
+      points.push({ id: partId, part, at: position + (part.offset ?? 0) });
+      return;
+    }
+    segments.push({ id: partId, part, start: position, end: position + part.length });
+    position += part.length;
+  });
+  return {
+    id,
+    draw,
+    length: position,
+    segments,
+    points,
+    ...(conveyor.next !== undefined && {
+      next:
+        "to" in conveyor.next
+          ? { to: name(conveyor.next.to), at: conveyor.next.at }
+          : { to: name(conveyor.next), at: 0 },
+    }),
+  };
+};
+
+const devicesOf = (segment: Segment): Array<[string, Device]> =>
+  Object.entries(segment.part.devices).map(([name, device]) => [`${segment.id}.${name}`, device]);
+
+const along = (motion: Motion) => ("along" in motion ? Math.max(0, motion.along) : 0);
+
+/**
+ * Runs a line against a PLC. Each tick reads the PLC outputs the devices are wired to,
+ * senses the line, updates every device, writes the changed PLC inputs, then moves loads.
+ */
+export const createSimulation = <Data = unknown, Definition extends Line = Line>(
+  line: Definition,
+  options: { io: SimulationIo },
+) => {
+  type ConveyorName = keyof Definition["conveyors"] & string;
+  type StationName = keyof NonNullable<Definition["stations"]> & string;
+  const names = targetNames(line);
+  const name = (target: Target) => {
+    const found = names.get(target);
+    if (found === undefined) throw new Error("A part leads outside the line.");
+    return found;
+  };
+  const drawings = drawLine(line);
+  const tracks = new Map(
+    Object.entries(line.conveyors).map(([id, item]) => [
+      id,
+      resolve(id, item, drawings.get(item)!, name),
+    ]),
+  );
+  const stations = new Map<string, Station>(Object.entries(line.stations ?? {}));
+  const devices = new Map<string, Device>();
+  const lineDevices = new Set(Object.keys(line.devices ?? {}));
+  for (const [id, device] of Object.entries(line.devices ?? {})) devices.set(id, device);
+  for (const track of tracks.values()) {
+    for (const segment of track.segments)
+      for (const [id, device] of devicesOf(segment)) devices.set(id, device);
+    for (const point of track.points)
+      if (point.part.kind === "reader") devices.set(point.id, point.part.device);
+  }
+  const reads = [...new Set([...devices.values()].flatMap((device) => device.reads))];
+  const placed = new Map<string, Placed<Data>>();
+  const written = new Map<string, unknown>();
+  const pendingReads = new Map<string, string[]>();
+  let timeMs = 0,
+    sequence = 0,
+    error: string | null = null;
+
+  const onConveyor = (conveyor: string) =>
+    [...placed.values()]
+      .flatMap(({ load, place }) =>
+        place.kind === "conveyor" && place.conveyor === conveyor ? [{ load, place }] : [],
+      )
+      .sort((a, b) => b.place.head - a.place.head);
+  /** Loads whose footprint covers part of this conveyor, with their head in its coordinates. */
+  const footprints = (track: Track) => [
+    ...onConveyor(track.id).map(({ load, place }) => ({ load, head: place.head, place })),
+    ...(track.next && tracks.has(track.next.to)
+      ? onConveyor(track.next.to).flatMap(({ load, place }) =>
+          place.from?.conveyor === track.id && place.head - place.from.at < load.length
+            ? [{ load, head: track.length + place.head - place.from.at, place }]
+            : [],
+        )
+      : []),
+  ];
+  const covers = (head: number, length: number, at: number) => head - length <= at && at <= head;
+  const stationLoads = (id: string) =>
+    [...placed.values()].filter(({ place }) => place.kind === "station" && place.station === id)
+      .length;
+
+  const sense = () => {
+    const writes = new Map<string, unknown>();
+    for (const track of tracks.values()) {
+      const loads = footprints(track);
+      const blocked = (at: number) =>
+        loads.some(
+          ({ load, head, place }) =>
+            covers(head, load.length, at) && Math.abs(place.lateral) < load.width / 2,
+        );
+      for (const segment of track.segments) {
+        const onPart = loads
+          .filter(({ load, head }) => head > segment.start && head - load.length < segment.end)
+          .map(({ load, head, place }) => ({
+            head: head - segment.start,
+            tail: head - load.length - segment.start,
+            lateral: place.lateral,
+          }));
+        const sensed = segment.part.sense?.(
+          {
+            blocked: (at) => blocked(segment.start + at),
+            occupied: onPart.length > 0,
+            loads: onPart,
+          },
+          segment.part.devices,
+        );
+        for (const [wire, value] of sensed ?? []) writes.set(wirePath(wire), value);
+      }
+      for (const point of track.points) {
+        if (point.part.kind === "photoeye")
+          writes.set(wirePath(point.part.output), blocked(point.at));
+        else if (point.part.kind === "reader") {
+          const queue = pendingReads.get(point.id) ?? [];
+          point.part.device.world.in.read = queue.shift() ?? null;
+          pendingReads.set(point.id, queue);
+        }
+      }
+    }
+    for (const [id, item] of stations)
+      for (const sensor of item.sensors ?? [])
+        writes.set(wirePath(sensor.output), sensor.active({ loads: stationLoads(id) }));
+    return writes;
+  };
+
+  /** Puts a load onto a conveyor with its head at `head`, or into a station, if there is room. */
+  const enter = (
+    target: string,
+    load: Load<Data>,
+    head: number,
+    from?: { conveyor: string; at: number },
+  ) => {
+    const track = tracks.get(target);
+    if (track) {
+      const blocked = onConveyor(target).some(
+        (other) =>
+          other.load !== load &&
+          other.place.head > head - load.length &&
+          other.place.head - other.load.length < head,
+      );
+      if (blocked) return false;
+      placed.set(load.id, {
+        load,
+        place: {
+          kind: "conveyor",
+          conveyor: target,
+          head,
+          lateral: 0,
+          ...(from !== undefined && { from }),
+        },
+      });
+      return true;
+    }
+    const capacity = stations.get(target)?.capacity;
+    if (capacity !== undefined && stationLoads(target) >= capacity) return false;
+    placed.set(load.id, { load, place: { kind: "station", station: target } });
+    return true;
+  };
+
+  const move = (dtMs: number) => {
+    for (const track of tracks.values()) {
+      const motions = new Map(
+        track.segments.map((segment) => [segment, segment.part.motion(segment.part.devices)]),
+      );
+      let limit = Number.POSITIVE_INFINITY;
+      for (const { load, place } of onConveyor(track.id)) {
+        if (place.kind !== "conveyor") continue;
+        const tail = place.head - load.length;
+        // A part moving loads across, such as lifting belts, carries a load whose middle is on it.
+        const middle = place.head - load.length / 2;
+        const across = track.segments.find(
+          (segment) => segment.start <= middle && middle <= segment.end,
+        );
+        const motion = across && motions.get(across);
+        if (across && motion && "across" in motion) {
+          place.lateral += (motion.across * dtMs) / 1000;
+          const width = across.part.width ?? 0;
+          const exit = across.part.exits?.[place.lateral > 0 ? "right" : "left"];
+          // A missing or full exit holds the load at the part's edge.
+          if (
+            Math.abs(place.lateral) >= width &&
+            (exit === undefined || !enter(name(exit), load, load.length))
+          )
+            place.lateral = Math.sign(place.lateral) * width;
+          limit = tail;
+          continue;
+        }
+        if (place.lateral !== 0) {
+          limit = tail;
+          continue;
+        }
+        const covered = track.segments.filter(
+          ({ start, end }) => start < place.head && end > Math.max(tail, 0),
+        );
+        const speed = covered.length
+          ? Math.min(...covered.map((segment) => along(motions.get(segment) ?? { held: true })))
+          : 0;
+        let target = Math.min(place.head + (speed * dtMs) / 1000, limit);
+        let picked = false;
+        for (const point of track.points) {
+          if (target < point.at) continue;
+          // An operator takes it off here; it waits on the point while the station is full.
+          if (point.part.kind === "pickup") {
+            if (picked || place.head > point.at) continue;
+            picked = enter(name(point.part.station), load, 0);
+            if (!picked) target = point.at;
+          } else if (point.part.kind === "reader" && place.head < point.at)
+            pendingReads.set(point.id, [...(pendingReads.get(point.id) ?? []), load.code]);
+        }
+        if (picked) continue;
+        const next = track.next;
+        if (target > track.length && next !== undefined) {
+          const entered = enter(next.to, load, next.at + target - track.length, {
+            conveyor: track.id,
+            at: next.at,
+          });
+          if (!entered) place.head = track.length;
+        } else place.head = Math.min(target, track.length);
+        limit = place.head - load.length;
+      }
+    }
+    for (const { load, place } of placed.values())
+      if (place.kind === "waiting") enter(place.conveyor, load, load.length);
+  };
+
+  const pointView = (point: Point): DeviceView => {
+    switch (point.part.kind) {
+      case "reader":
+        return point.part.device.view();
+      case "photoeye":
+        return { status: written.get(wirePath(point.part.output)) ? "busy" : "idle" };
+      case "pickup":
+        return {
+          status: stationLoads(name(point.part.station)) ? "busy" : "idle",
+          label: name(point.part.station),
+        };
+    }
+  };
+
+  const segmentView = (segment: Segment): DeviceView => {
+    const views = devicesOf(segment).map(([, device]) => device.view());
+    if (!views.length)
+      return {
+        status: along(segment.part.motion(segment.part.devices)) > 0 ? "running" : "stopped",
+      };
+    const order = ["fault", "warning", "busy", "running", "stopped", "idle"] as const;
+    return views.reduce((worst, view) =>
+      order.indexOf(view.status) < order.indexOf(worst.status) ? view : worst,
+    );
+  };
+
+  const simulation = {
+    /** Advances the line by `dtMs`, exchanging I/O with the PLC once. */
+    tick: async (dtMs: number) => {
+      const plc = await options.io.read(reads);
+      const writes = sense();
+      for (const device of devices.values())
+        for (const [path, value] of device.update(plc, dtMs)) writes.set(path, value);
+      const changed = new Map(
+        [...writes].filter(([path, value]) => !same(written.get(path), value)),
+      );
+      if (changed.size) {
+        await options.io.write(changed);
+        for (const [path, value] of changed) written.set(path, value);
+      }
+      move(dtMs);
+      timeMs += dtMs;
+    },
+    /** Ticks in real time until aborted, skipping ticks while `paused()`; failed ticks are reported in `state().error`. */
+    run: async (
+      signal: AbortSignal,
+      options: { periodMs?: number; paused?: () => boolean } = {},
+    ) => {
+      const periodMs = options.periodMs ?? 50;
+      let last = performance.now();
+      while (!signal.aborted) {
+        const now = performance.now();
+        if (!options.paused?.()) await simulation.step(Math.min(now - last, 1000));
+        last = now;
+        await delay(Math.max(0, periodMs - (performance.now() - now)), undefined, {
+          signal,
+        }).catch(() => undefined);
+      }
+    },
+    /** One tick that records a failure in `state().error` instead of throwing, then rewrites every input. */
+    step: async (dtMs: number) => {
+      try {
+        await simulation.tick(dtMs);
+        error = null;
+      } catch (cause) {
+        error = cause instanceof Error ? cause.message : String(cause);
+        // The PLC may have restarted or missed writes, so send every input again.
+        written.clear();
+      }
+    },
+    /** Queues a load at a conveyor's start; it enters once there is room. */
+    addLoad: (
+      conveyor: ConveyorName,
+      load: { kind: keyof Definition["loads"] & string; code: string; data: Data },
+    ) => {
+      const kind = line.loads[load.kind];
+      if (!kind) throw new Error(`Unknown load kind ${load.kind}.`);
+      if (!tracks.has(conveyor)) throw new Error(`Unknown conveyor ${conveyor}.`);
+      const created: Load<Data> = {
+        id: `L${++sequence}`,
+        length: kind.length,
+        width: kind.width ?? kind.length,
+        ...load,
+      };
+      placed.set(created.id, { load: created, place: { kind: "waiting", conveyor } });
+      return created;
+    },
+    /**
+     * Moves a load as an operator would: into a station, onto a conveyor's start once there is
+     * room, or onto a conveyor with its tail at `at` mm (failing if that spot is taken).
+     */
+    place: (id: string, target: ConveyorName | StationName, at?: number) => {
+      const entry = placed.get(id);
+      if (!entry) throw new Error(`Unknown load ${id}.`);
+      if (tracks.has(target) && at === undefined)
+        entry.place = { kind: "waiting", conveyor: target };
+      else if (!enter(target, entry.load, (at ?? 0) + entry.load.length))
+        throw new Error(`No room for ${entry.load.code} at ${target}.`);
+    },
+    remove: (id: string) => {
+      placed.delete(id);
+    },
+    loads: () => [...placed.values()].map(({ load, place }) => ({ load, place })),
+    loadsAt: (station: StationName) =>
+      [...placed.values()]
+        .filter(({ place }) => place.kind === "station" && place.station === station)
+        .map(({ load }) => load),
+    act: (device: string, action: string, argument = "") => {
+      const target = devices.get(device);
+      if (!target) throw new Error(`Unknown device ${device}.`);
+      target.act(action, argument);
+    },
+    state: (): SimulationState => ({
+      timeMs,
+      error,
+      conveyors: [...tracks.values()].map((track) => ({
+        id: track.id,
+        draw: track.draw,
+        length: track.length,
+        ...(track.next !== undefined && { next: track.next.to }),
+        parts: [
+          ...track.segments.map((segment) => ({
+            id: segment.id,
+            kind: segment.part.kind,
+            ...(segment.part.label !== undefined && { label: segment.part.label }),
+            start: segment.start,
+            end: segment.end,
+            ...(segment.part.exits && {
+              exits: {
+                ...(segment.part.exits.left && { left: name(segment.part.exits.left) }),
+                ...(segment.part.exits.right && { right: name(segment.part.exits.right) }),
+              },
+            }),
+            view: segmentView(segment),
+          })),
+          ...track.points.map((point) => ({
+            id: point.id,
+            kind: point.part.kind,
+            start: point.at,
+            end: point.at,
+            ...(point.part.kind === "pickup" && {
+              station: name(point.part.station),
+              side: point.part.side ?? "right",
+            }),
+            view: pointView(point),
+          })),
+        ],
+      })),
+      stations: [...stations].map(([id, item]) => ({
+        id,
+        label: item.label ?? id,
+        loads: stationLoads(id),
+      })),
+      loads: [...placed.values()].map(({ load, place }) => ({
+        id: load.id,
+        kind: load.kind,
+        code: load.code,
+        length: load.length,
+        width: load.width,
+        place: { ...place },
+      })),
+      devices: [...devices].map(([id, device]) => ({
+        id,
+        part: lineDevices.has(id) ? null : id.split(".")[0]!,
+        model: device.model,
+        view: device.view(),
+        pins: device.pins(),
+        actions: device.actions,
+      })),
+    }),
+  };
+  return simulation;
+};
+
+export type Simulation<Data = unknown, Definition extends Line = Line> = ReturnType<
+  typeof createSimulation<Data, Definition>
+>;