zach/dotter

// A simulated NextDraw: an EBB v3 firmware emulator plus a physical model

// of the carriage. It implements the same transport interface as the

// WebSerial transport, so the real driver code runs against it unchanged.

//

// What it models:

// - The serial protocol: legacy syntax until CU,10,1, then future syntax.

// - Motion commands SM, HM, T3, TD executed step by step (T3/TD per 40 µs

//   tick, exactly as the firmware accumulators do), on mixed axes

//   (motor1 = x + y, motor2 = x - y), with step counters and accumulators.

// - A physical carriage in a box [0, travelX] x [0, travelY], with a limit

//   switch at X = 0 on pin B1, freewheeling of disabled motors (the homing

//   routine relies on this), and the firmware's limit-switch stop (CU,51/52).

// - Pen servo state, EBB RAM variables, nickname, status byte, motor power,

//   the PRG button, and a FIFO timeline driven by a virtual clock.

//

// What it records:

// - log: every command received, with its virtual timestamp.

// - violations: anything that would be unsafe or wrong on a real machine:

//   leaving the travel area, pushing into a wall with both motors driven,

//   step rates above the firmware's 25 kHz limit, unknown commands, motion

//   ignored after a limit stop.

// - ink: polylines traced while the pen was down (physical inches).

// - travel: polylines traced while the pen was up.

const ACC = 2147483648; // 2^31

const UNITS_PER_INCH = 4064; // Physical grid: one 16x microstep on one axis moves 1/4064 in in X and Y.

const MICROSTEPS = { 1: 16, 2: 8, 3: 4, 4: 2, 5: 1 };

export class VirtualClock {

  constructor() {

    this.t = 0;

  }

  now() {

    return this.t;

  }

  async sleep(ms) {

    this.t += Math.max(0, ms);

  }

}

export class EBBSimulator {

  /**

   * @param {object} o

   * @param {VirtualClock} o.clock shared with the NextDraw instance

   * @param {number} [o.travelX] inches (NextDraw 8511: 11.81)

   * @param {number} [o.travelY] inches (NextDraw 8511: 8.58)

   * @param {number} [o.startX] initial carriage X, inches

   * @param {number} [o.startY] initial carriage Y, inches

   * @param {string} [o.firmware] firmware version string

   * @param {boolean} [o.powered] motor power supply connected

   * @param {boolean} [o.limitSwitch] limit switch present

   * @param {string} [o.nickname]

   */

  constructor({ clock = new VirtualClock(), travelX = 11.81, travelY = 8.58, startX = 0, startY = 0,

    firmware = '3.0.3', powered = true, limitSwitch = true, nickname = '' } = {}) {

    this.clock = clock;

    this.firmware = firmware;

    this.xMaxU = Math.round(travelX * UNITS_PER_INCH);

    this.yMaxU = Math.round(travelY * UNITS_PER_INCH);

    this.X = Math.round(startX * UNITS_PER_INCH);

    this.Y = Math.round(startY * UNITS_PER_INCH);

    this.powered = powered;

    this.limitSwitchPresent = limitSwitch;

    this.nickname = nickname;

    this.isOpen = false;

    this.unplugged = false;

    this.inbuf = '';

    this.out = [];

    this.log = [];

    this.violations = [];

    this.ink = [];

    this.travel = [];

    this.stats = { steps: 0, maxRate: 0, motionMs: 0, peakSpeedUp: 0, peakSpeedDown: 0 };

    this.reset();

  }

  /** Power-on state of the EBB (does not move the carriage). */

  reset() {

    this.future = false;

    this.vars = new Uint8Array(32);

    this.steps = [0, 0];

    this.accum = [0, 0];

    this.enabled = [false, false];

    this.stepMode = 1; // EM code: 1 = 16x microstepping

    this.autoEnable = true;

    this.limitMask = 0;

    this.limitTarget = 0;

    this.limitTriggered = false;

    this.servoMin = 22565; // pen-up position at boot

    this.servoMax = 15302; // pen-down position at boot

    this.servoRateUp = 0;

    this.servoRateDown = 0;

    this.servoChannels = 8;

    this.penUp = true;

    this.button = false;

    this.powerLostFlag = false;

    this.powerThreshold = 0;

    this.busyUntil = 0;

    this.portB = { dir: new Array(8).fill(1), out: new Array(8).fill(0) };

    this.currentPath = null;

    this.pathStart = this.position;

  }

  // --- Test controls ---

  pressButton() {

    this.button = true;

  }

  setPower(on) {

    this.powered = on;

    if (!on && this.powerThreshold > 0) this.powerLostFlag = true;

  }

  unplug() {

    this.unplugged = true;

  }

  get position() {

    return [this.X / UNITS_PER_INCH, this.Y / UNITS_PER_INCH];

  }

  // --- Transport interface ---

  async open() {

    if (this.unplugged) throw new Error('Device not found');

    this.isOpen = true;

  }

  async close() {

    this.isOpen = false;

    this.endPath();

  }

  async clearInput() {

    this.out = [];

  }

  async write(text) {

    if (this.unplugged || !this.isOpen) throw new Error('Port is not open');

    this.inbuf += text;

    let idx;

    while ((idx = this.inbuf.indexOf('\r')) >= 0) {

      const cmd = this.inbuf.slice(0, idx).replace(/^\n+/, '');

      this.inbuf = this.inbuf.slice(idx + 1);

      if (cmd.length) this.handle(cmd);

    }

  }

  async readLine() {

    if (this.unplugged) throw new Error('Device disconnected');

    return this.out.length ? this.out.shift() : '';

  }

  // --- Command processing ---

  reply(name, data = null) {

    if (this.future) this.out.push(data == null ? `${name}\n` : `${name},${data}\n`);

    else this.out.push(data == null ? 'OK\r\n' : `${data}\r\nOK\r\n`);

  }

  error(text) {

    this.out.push(`!8 Err: ${text}${this.future ? '\n' : '\r\n'}`);

  }

  violation(kind, detail) {

    this.violations.push({ kind, detail, t: this.clock.now(), position: this.position });

  }

  handle(cmd) {

    this.log.push({ t: this.clock.now(), cmd });

    const parts = cmd.split(',');

    const name = parts[0].toUpperCase();

    const args = parts.slice(1);

    const num = (i, dflt = 0) => (args[i] === undefined || args[i] === '' ? dflt : Number(args[i]));

    switch (name) {

      case 'V':

        this.out.push(`EBBv13_and_above EB Firmware Version ${this.firmware}\r\n`);

        return;

      case 'CU':

        this.configure(num(0), num(1));

        this.reply('CU');

        return;

      case 'QT':

        this.reply('QT', this.nickname || null);

        return;

      case 'ST':

        this.nickname = args.join(',').slice(0, 16);

        this.reply('ST');

        return;

      case 'QG':

        this.reply('QG', this.statusByte().toString(16).toUpperCase().padStart(2, '0'));

        return;

      case 'QC':

        this.reply('QC', `${this.powered ? 400 : 6},${this.powered ? 305 : 4}`);

        return;

      case 'QE': {

        const code = (on) => (on ? MICROSTEPS[this.stepMode] : 0);

        this.reply('QE', `${code(this.enabled[0])},${code(this.enabled[1])}`);

        return;

      }

      case 'QS':

        this.reply('QS', `${this.steps[0]},${this.steps[1]}`);

        return;

      case 'CS':

        this.steps = [0, 0];

        this.accum = [0, 0];

        this.reply('CS');

        return;

      case 'SL':

        this.vars[num(1)] = num(0) & 255;

        this.reply('SL');

        return;

      case 'QL':

        this.reply('QL', String(this.vars[num(0)]));

        return;

      case 'PD':

        this.portB.dir[num(1)] = num(2);

        this.reply('PD');

        return;

      case 'PO':

        this.portB.out[num(1)] = num(2);

        this.reply('PO');

        return;

      case 'PI':

        this.reply('PI', String(this.readPin(num(1))));

        return;

      case 'SC':

        this.servoConfig(num(0), num(1));

        this.reply('SC');

        return;

      case 'SR':

        this.reply('SR');

        return;

      case 'SP':

        this.setPen(num(0), num(1), args[2]);

        this.reply('SP');

        return;

      case 'EM':

        this.enableMotors(num(0), args.length > 1 ? num(1) : null);

        this.reply('EM');

        return;

      case 'ES': {

        const interrupted = this.clock.now() < this.busyUntil ? 1 : 0;

        this.busyUntil = this.clock.now();

        if (num(0) === 1) this.enabled = [false, false];

        this.reply('ES', String(interrupted));

        return;

      }

      case 'SM':

        this.cmdSM(num(0), num(1), num(2), num(3));

        return;

      case 'HM':

        this.cmdHM(num(0), args.length >= 3 ? num(1) : 0, args.length >= 3 ? num(2) : 0);

        return;

      case 'T3':

        this.cmdT3(cmd, args.map(Number));

        return;

      case 'TD':

        this.cmdTD(cmd, args.map(Number));

        return;

      case 'R':

        this.reset();

        this.reply('R');

        return;

      case 'RB':

      case 'BL':

        this.reset();

        this.isOpen = false;

        return;

      default:

        this.violation('unknown-command', cmd);

        this.error(`Unknown command '${name}'`);

    }

  }

  configure(param, value) {

    if (param === 10) this.future = value === 1;

    else if (param === 50) this.autoEnable = value === 1;

    else if (param === 51) {

      this.limitMask = value & 255;

      if (this.limitMask === 0) this.limitTriggered = false;

    } else if (param === 52) this.limitTarget = value & 255;

    else if (param === 60) this.powerThreshold = value;

  }

  statusByte() {

    let s = 0;

    if (this.limitTriggered) s |= 128;

    if (this.powerLostFlag || (this.powerThreshold > 0 && !this.powered)) s |= 64;

    if (this.button) s |= 32;

    if (this.penUp) s |= 16;

    if (this.clock.now() < this.busyUntil) s |= 8 | 4 | 2;

    this.button = false;

    this.powerLostFlag = false;

    return s;

  }

  readPin(pin) {

    if (pin === 1) {

      // Normally-closed switch to ground: reads 1 when pressed or absent.

      if (!this.limitSwitchPresent) return 1;

      return this.X <= 0 ? 1 : 0;

    }

    return this.portB.out[pin] ?? 0;

  }

  servoConfig(param, value) {

    if (param === 4) this.servoMin = value;

    else if (param === 5) this.servoMax = value;

    else if (param === 8) this.servoChannels = value;

    else if (param === 11) this.servoRateUp = value;

    else if (param === 12) this.servoRateDown = value;

  }

  setPen(value, durationMs) {

    if (value === 0) {

      this.queue(durationMs);

      this.penUp = false;

    } else if (value === 1) {

      this.queue(durationMs);

      this.penUp = true;

    } else if (value === 2 || value === 3) {

      if (value === 3) this.servoMax = this.servoMin;

      this.penUp = true;

    }

    if (this.penUp) this.endPath();

  }

  enableMotors(e1, e2) {

    this.queue(0);

    if (e1 > 0) this.stepMode = e1;

    this.enabled[0] = e1 > 0;

    if (e2 != null) this.enabled[1] = e2 > 0;

    // EM resets the global step counters and clears a limit stop.

    this.steps = [0, 0];

    this.accum = [0, 0];

    this.limitTriggered = false;

  }

  /** Reserve FIFO time; returns the start time of this command. */

  queue(durationMs) {

    const start = Math.max(this.clock.now(), this.busyUntil);

    this.busyUntil = start + Math.max(0, durationMs);

    return start;

  }

  motionAllowed(name) {

    if (this.limitTriggered) {

      this.violation('motion-after-limit', `${name} ignored: limit switch stop is active`);

      this.reply(name);

      return false;

    }

    if (this.autoEnable) this.enabled = [true, true];

    return true;

  }

  cmdSM(durationMs, s1, s2, clear) {

    if (!(durationMs >= 1)) {

      this.error('SM duration must be >= 1');

      return;

    }

    if (Math.abs(s1) / durationMs > 25 || Math.abs(s2) / durationMs > 25) {

      this.violation('step-rate', `SM,${durationMs},${s1},${s2} exceeds 25000 steps/s`);

      this.error('Step rate too high');

      return;

    }

    if (s1 === 0 && s2 === 0) {

      this.queue(Math.min(durationMs, 100000));

      this.reply('SM');

      return;

    }

    if (!this.motionAllowed('SM')) return;

    if (clear & 1) this.accum[0] = 0;

    if (clear & 2) this.accum[1] = 0;

    const start = this.queue(durationMs);

    this.trackSpeed(s1 * 1000 / durationMs, s2 * 1000 / durationMs);

    const n = Math.max(Math.abs(s1), Math.abs(s2));

    let done1 = 0;

    let done2 = 0;

    for (let i = 1; i <= n; i++) {

      const t1 = Math.trunc(s1 * i / n);

      const t2 = Math.trunc(s2 * i / n);

      const stopped = this.stepBoth(t1 - done1, t2 - done2);

      done1 = t1;

      done2 = t2;

      if (stopped) {

        this.busyUntil = start + durationMs * i / n;

        break;

      }

    }

    this.markPath();

    this.stats.motionMs += durationMs;

    this.reply('SM');

  }

  cmdHM(rate, p1, p2) {

    if (!(rate >= 1 && rate <= 25000)) {

      this.error('HM rate out of range');

      return;

    }

    if (!this.motionAllowed('HM')) return;

    const d1 = p1 - this.steps[0];

    const d2 = p2 - this.steps[1];

    const n = Math.max(Math.abs(d1), Math.abs(d2));

    const durationMs = (n / rate) * 1000 + 5;

    this.queue(durationMs);

    let done1 = 0;

    let done2 = 0;

    for (let i = 1; i <= n; i++) {

      const t1 = Math.round(d1 * i / n);

      const t2 = Math.round(d2 * i / n);

      if (this.stepBoth(t1 - done1, t2 - done2)) break;

      done1 = t1;

      done2 = t2;

    }

    this.markPath();

    this.stats.motionMs += durationMs;

    this.reply('HM');

  }

  cmdT3(cmd, a) {

    const [intervals, r1, a1, j1, r2, a2, j2, clear = 0] = a;

    if (!(intervals >= 1) || a.slice(0, 7).some((v) => !Number.isInteger(v))) {

      this.violation('bad-command', cmd);

      this.error('Bad T3 parameters');

      return;

    }

    if (!this.motionAllowed('T3')) return;

    if (clear & 1) this.accum[0] = 0;

    if (clear & 2) this.accum[1] = 0;

    this.queue(intervals / 25);

    this.runT3(cmd, intervals, r1, a1, j1, r2, a2, j2);

    this.markPath();

    this.stats.motionMs += intervals / 25;

    this.reply('T3');

  }

  cmdTD(cmd, a) {

    const [intervals, r1a, r1b, a1, j1, r2a, r2b, a2, j2, clear = 0] = a;

    if (!(intervals >= 1) || a.slice(0, 9).some((v) => !Number.isInteger(v))) {

      this.violation('bad-command', cmd);

      this.error('Bad TD parameters');

      return;

    }

    if (!this.motionAllowed('TD')) return;

    if (clear & 1) this.accum[0] = 0;

    if (clear & 2) this.accum[1] = 0;

    this.queue((2 * intervals) / 25);

    // The firmware expands TD into two T3 moves.

    if (!this.runT3(cmd, intervals, r1a, 0, j1, r2a, 0, j2)) {

      this.runT3(cmd, intervals, r1b, a1, -j1, r2b, a2, -j2);

    }

    this.markPath();

    this.stats.motionMs += (2 * intervals) / 25;

    this.reply('TD');

  }

  /** Tick-accurate T3 execution. Returns true if stopped by the limit switch. */

  runT3(cmd, intervals, r1, a1, j1, r2, a2, j2) {

    // Firmware pre-adjusts each rate by -Accel/2 + Jerk/6 (integer division).

    let rate1 = r1 - Math.trunc(a1 / 2) + Math.trunc(j1 / 6);

    let rate2 = r2 - Math.trunc(a2 / 2) + Math.trunc(j2 / 6);

    let acc1 = a1;

    let acc2 = a2;

    let flagged = false;

    for (let t = 0; t < intervals; t++) {

      rate1 += acc1;

      acc1 += j1;

      rate2 += acc2;

      acc2 += j2;

      const peak = Math.max(Math.abs(rate1), Math.abs(rate2));

      if (peak > this.stats.maxRate) this.stats.maxRate = peak;

      this.trackSpeed(rate1 * 25000 / ACC, rate2 * 25000 / ACC);

      if (peak >= ACC && !flagged) {

        flagged = true;

        this.violation('step-rate', `${cmd}: rate ${peak} >= 2^31 (more than one step per 40 µs)`);

      }

      this.accum[0] += rate1;

      this.accum[1] += rate2;

      let d1 = 0;

      let d2 = 0;

      while (this.accum[0] >= ACC) { this.accum[0] -= ACC; d1++; }

      while (this.accum[0] < 0) { this.accum[0] += ACC; d1--; }

      while (this.accum[1] >= ACC) { this.accum[1] -= ACC; d2++; }

      while (this.accum[1] < 0) { this.accum[1] += ACC; d2--; }

      if ((d1 || d2) && this.stepBoth(d1, d2)) {

        this.busyUntil = this.clock.now() + (t + 1) / 25;

        return true;

      }

    }

    return false;

  }

  /** Record peak carriage speed (in/s) from motor step rates (steps/s). */

  trackSpeed(v1, v2) {

    const inchPerStep = 2 * (16 / MICROSTEPS[this.stepMode]) / UNITS_PER_INCH;

    const vx = ((v1 + v2) / 2) * inchPerStep;

    const vy = ((v1 - v2) / 2) * inchPerStep;

    const speed = Math.hypot(vx, vy);

    const key = this.penUp ? 'peakSpeedUp' : 'peakSpeedDown';

    if (!(speed <= this.stats[key])) this.stats[key] = speed;

  }

  /**

   * Take d1 steps on motor 1 and d2 on motor 2 (normally -1..1 each) and move

   * the carriage. Returns true if a limit-switch stop fired.

   */

  stepBoth(d1, d2) {

    this.steps[0] += d1;

    this.steps[1] += d2;

    this.stats.steps += Math.abs(d1) + Math.abs(d2);

    // Physical motor travel per step, in grid units of (x+y) or (x-y).

    const k = 2 * (16 / MICROSTEPS[this.stepMode]);

    const m1 = this.enabled[0] ? d1 * k : 0;

    const m2 = this.enabled[1] ? d2 * k : 0;

    let dx;

    let dy;

    if (this.enabled[0] && this.enabled[1]) {

      dx = (m1 + m2) / 2;

      dy = (m1 - m2) / 2;

    } else if (this.enabled[0]) {

      // Motor 2 freewheels: the carriage moves diagonally until it meets a

      // Y wall, then slides along it.

      dx = m1 / 2;

      dy = m1 / 2;

      if (this.Y + dy < 0) { dy = -this.Y; dx = m1 - dy; }

      if (this.Y + dy > this.yMaxU) { dy = this.yMaxU - this.Y; dx = m1 - dy; }

    } else if (this.enabled[1]) {

      dx = m2 / 2;

      dy = -m2 / 2;

      if (this.Y + dy < 0) { dy = -this.Y; dx = m2 + dy; }

      if (this.Y + dy > this.yMaxU) { dy = this.yMaxU - this.Y; dx = m2 + dy; }

    } else {

      return false; // Both motors off: steps are counted but nothing moves.

    }

    let nx = this.X + dx;

    let ny = this.Y + dy;

    // Sub-step rounding and staircase stepping can touch just past the

    // nominal bounds; allow that much (it is within belt/stop compliance).

    // Anything further is driving the carriage into the frame.

    const tol = 2; // grid units (~0.0005 in)

    if (nx < -tol || nx > this.xMaxU + tol || ny < -tol || ny > this.yMaxU + tol) {

      this.violation('out-of-travel',

        `Carriage driven to (${(nx / UNITS_PER_INCH).toFixed(4)}, ${(ny / UNITS_PER_INCH).toFixed(4)}) in`);

    }

    nx = Math.min(Math.max(nx, -tol), this.xMaxU + tol);

    ny = Math.min(Math.max(ny, -tol), this.yMaxU + tol);

    this.X = nx;

    this.Y = ny;

    if (this.limitMask) {

      const pins = this.readPin(1) << 1;

      if ((pins & this.limitMask) === (this.limitTarget & this.limitMask)) {

        this.limitTriggered = true;

        return true;

      }

    }

    return false;

  }

  /** Append the carriage position to the current ink or travel polyline. */

  markPath() {

    const p = this.position;

    const list = this.penUp ? this.travel : this.ink;

    if (!this.currentPath || this.currentPath.penUp !== this.penUp) {

      const start = this.pathStart;

      this.endPath();

      this.currentPath = { penUp: this.penUp, points: [start] };

      list.push(this.currentPath.points);

    }

    this.currentPath.points.push(p);

    this.pathStart = p;

  }

  endPath() {

    this.currentPath = null;

    this.pathStart = this.position;

  }

}