zach/dotter

// NextDraw: browser/JS port of the Bantam Tools NextDraw Python API

// (https://bantam.tools/nd_py). Async methods mirror the Python names in

// camelCase: connect, moveto, lineto, drawPath, penup, ... disconnect.

//

// Everything here talks to the machine through an EBB over a transport, so

// the same code runs against WebSerial or the EBB simulator in src/sim.

import { isClose } from './calc.js';

import { clipPolyline, clipSegment, pointInBounds, pointsNear } from './clip.js';

import { defaultOptions, defaultParams } from './config.js';

import * as control from './control.js';

import { EBB } from './ebb.js';

import { Homing } from './homing.js';

import { applyModelAndHandling } from './models.js';

import { computeSegment, copyPos, trajectory } from './motion.js';

import { PenHandler } from './pen.js';

export const realClock = {

  now: () => performance.now(),

  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),

};

// plot_status.stopped codes (negative while being handled, positive once stopped)

export const STOP_CODES = {

  101: 'Failed to connect',

  102: 'Stopped by pause button press',

  103: 'Stopped by software request',

  104: 'Lost USB connectivity',

  105: 'Power loss detected',

  106: 'Homing failed',

  107: 'Refused a motion command beyond the firmware step-rate limit',

};

function newStats() {

  return {

    upTravelInch: 0,

    downTravelInch: 0,

    ptEstimate: 0, // ms, preview estimate

    addDist(nd, inches) {

      if (nd.pen.phys.zUp) this.upTravelInch += inches;

      else this.downTravelInch += inches;

    },

  };

}

function newPlotStatus() {

  return {

    stopped: 0,

    button: false,

    limit: false,

    power: false,

    connection: false,

    monitor: false,

    buttonTimestamp: -Infinity,

    stats: newStats(),

  };

}

export class NextDraw {

  /**

   * @param {object} opts

   * @param {object} [opts.transport] transport to use in connect()

   * @param {object} [opts.clock] { now(), sleep(ms) }; defaults to real time

   * @param {function} [opts.log] message sink (default console.log)

   */

  constructor({ transport = null, clock = realClock, log = (m) => console.log(m) } = {}) {

    this.transport = transport;

    this.clock = clock;

    this.logFn = log;

    this.options = defaultOptions();

    this.params = defaultParams();

    this.machine = new EBB();

    this.pen = new PenHandler();

    this.homing = new Homing(this);

    this.plotStatus = newPlotStatus();

    this.warnings = new Set();

    this.bounds = [[0, 0], [0, 0]];

    this.connected = false;

    this.stepScale = 2 * this.params.nativeResFactor;

    this.speedPendown = 0;

    this.speedPenup = 0;

    this.useLayerSpeed = false;

    this.layerSpeedPendown = null;

    this.pauseRequested = false;

    // Set any of these true to throw instead of returning quietly.

    this.errors = { connect: false, button: false, keyboard: false, disconnect: false,

      power: false, homing: false, code: 0 };

    this.fwVersion = null;

    this.nickname = null;

    applyModelAndHandling(this, true);

  }

  log(message) {

    this.logFn(message);

  }

  warn(key) {

    if (this.warnings.has(key)) return;

    this.warnings.add(key);

    const text = {

      bounds: `Warning: motion was clipped at the travel limits of the ${this.params.modelName}.`,

      voltage: 'Warning: low or no motor power detected. Is the power supply connected?',

      homing_voltage: 'Automatic homing requires motor power. Check the power supply.',

    }[key];

    if (text) this.log(text);

  }

  // --- Context & settings ---

  /** Enter the interactive context with default options (Python: interactive()). */

  interactive() {

    this.options.units = 0;

    this.options.preview = false;

    this.options.mode = 'interactive';

  }

  requireInteractive() {

    if (this.options.mode !== 'interactive') throw new Error('Function only available in interactive mode.');

    if (!this.connected) {

      this.handleErrors();

      throw new Error('Not connected to NextDraw');

    }

  }

  /** Re-derive bounds and clamp options (nextdraw.update_options). */

  updateOptions() {

    if (this.options.model) {

      applyModelAndHandling(this);

      this.bounds = [[-1e-9, -1e-9], [this.params.travelX + 1e-9, this.params.travelY + 1e-9]];

    }

    const o = this.options;

    const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));

    o.penPosUp = clamp(o.penPosUp, 0, 100);

    o.penPosDown = clamp(o.penPosDown, 0, 100);

    o.penRateRaise = clamp(o.penRateRaise, 1, 100);

    o.penRateLower = clamp(o.penRateLower, 1, 100);

    o.speedPendown = clamp(o.speedPendown, 1, 100);

    o.speedPenup = clamp(o.speedPenup, 1, 100);

    o.accel = clamp(o.accel, 1, 100);

  }

  /** Apply changed options while connected (Python: update()). */

  async update() {

    this.requireInteractive();

    this.updateOptions();

    await this.pen.servoInit(this);

    if (!this.machine.connected) return;

    await control.enableMotors(this);

    // A resolution change re-enables the motors, which zeroes the EBB step

    // counters and marks the machine un-homed. (The Python API leaves this to

    // the user.) Re-home so the counters and our position agree again.

    if (!(await this.machine.varRead(12))) {

      if (this.options.homing && this.params.autoHome) {

        this.log('Motor resolution changed; re-homing.');

        await this.homing.findHome();

        this.pen.turtle = copyPos(this.pen.phys);

        this.pen.turtle.zUp = true;

      } else {

        this.log('Motor resolution changed; position is no longer known. Move the carriage home and reconnect.');

      }

    }

  }

  // --- Connection ---

  /**

   * Open the connection, configure the pen servo, enable motors and home.

   * Returns true on success, false on failure.

   */

  async connect(transport = this.transport) {

    if (this.options.mode !== 'interactive') {

      this.log('Error: connect() called outside of interactive context.');

      return null;

    }

    if (!this.options.model) {

      this.log('Error: Plotter hardware model not selected.');

      return null;

    }

    if (!transport) throw new Error('No transport given to connect().');

    this.transport = transport;

    applyModelAndHandling(this, true);

    this.pauseRequested = false;

    this.plotStatus = newPlotStatus();

    this.warnings.clear();

    if (!(await this.serialConnect())) {

      this.log(`Failed to connect to ${this.params.modelName}. ${this.machine.err ?? ''}`.trim());

      if (this.errors.connect) throw new Error('Failed to connect to NextDraw');

      this.errors.code = this.plotStatus.stopped;

      return false;

    }

    await this.queryEbbVoltage();

    this.updateOptions();

    this.pen.turtle = copyPos(this.pen.phys);

    this.pen.turtle.zUp = true;

    await control.readStatusByte(this); // Clear any stale button press

    this.plotStatus = newPlotStatus();

    await this.pen.servoInit(this);

    await this.pen.raise(this);

    await control.enableMotors(this);

    if (!(await this.homing.findHome())) {

      this.handleErrors();

      return false;

    }

    this.pen.turtle = copyPos(this.pen.phys);

    this.pen.turtle.zUp = true;

    this.fwVersion = this.machine.version;

    this.nickname = this.machine.name;

    return true;

  }

  async serialConnect() {

    if (await this.machine.connect(this.transport)) {

      await control.connectSetup(this);

      this.connected = true;

      return true;

    }

    this.plotStatus.stopped = 101;

    return false;

  }

  async queryEbbVoltage() {

    await control.readStatusByte(this);

    if (this.plotStatus.power) {

      await this.machine.clearSteps();

      await this.machine.varWrite(0, 12);

      await this.machine.varWrite(0, 13);

      this.plotStatus.power = false;

    }

    this.plotStatus.button = false;

    this.plotStatus.limit = false;

    return control.queryVoltage(this);

  }

  /** Wait for motion to finish, then close the connection. */

  async disconnect() {

    if (this.machine.connected) await control.exhaustQueue(this);

    await this.machine.disconnect();

    this.connected = false;

  }

  // --- Errors & pausing ---

  /** Ask a running plot or move sequence to stop (like Ctrl-C in Python). */

  requestPause() {

    this.pauseRequested = true;

  }

  receivePauseRequest() {

    return this.pauseRequested;

  }

  handleErrors() {

    const code = this.plotStatus.stopped;

    this.errors.code = code;

    const e = this.errors;

    if ((code === 101 && e.connect) || (code === 102 && e.button) || (code === 103 && e.keyboard) ||

        (code === 104 && e.disconnect) || (code === 105 && e.power) || (code === 106 && e.homing)) {

      throw new Error(STOP_CODES[code]);

    }

  }

  /** Check for pause requests, button presses, power loss and lost USB. */

  async pauseCheck() {

    const ps = this.plotStatus;

    if (ps.stopped > 0) return;

    const button = await this.checkButton();

    if (this.receivePauseRequest()) ps.stopped = -103;

    if (ps.power) {

      ps.stopped = -105;

      this.log('Plot stopped because loss of power detected.');

      await this.machine.varWrite(0, 12);

      await this.machine.varWrite(0, 13);

    }

    if (button === -1) {

      this.log('Error: USB connection lost.');

      this.connected = false;

      ps.stopped = -104;

    }

    if (button === 1) {

      this.log('Stopped by button press.');

      ps.stopped = -102;

    }

    if (ps.stopped === -103) this.log('Stopped by request.');

    if (ps.stopped < 0) {

      await this.pen.raise(this);

      ps.stopped = -ps.stopped;

    }

  }

  /** 1 if the PRG button was pressed, 0 if not, -1 on USB error. Polls at most every 50 ms. */

  async checkButton() {

    if (this.options.preview) return 0;

    const ps = this.plotStatus;

    const now = this.clock.now();

    if (now - ps.buttonTimestamp > this.params.buttonInterval * 1000) {

      ps.buttonTimestamp = now;

      await control.readStatusByte(this);

    }

    if (ps.button) return 1;

    if (ps.connection) return -1;

    return 0;

  }

  // --- Motion primitives ---

  /** Point-to-point move with normal motion planning, starting and ending at rest. */

  async goToPosition(x, y, ignoreLimits = false, xyzPos = null) {

    const [moves] = computeSegment(this, [x, y, 0, 0, ignoreLimits], xyzPos);

    await control.feed(this, moves);

  }

  /** Plot one polyline (inches): pen-up travel to start, then a pen-down path. */

  async plotPolyline(vertices) {

    if (this.plotStatus.stopped || !vertices || vertices.length < 2) return;

    await this.pen.raise(this);

    const clamped = vertices.map(([x, y]) => [

      Math.max(0, Math.min(this.bounds[1][0], x)),

      Math.max(0, Math.min(this.bounds[1][1], y)),

    ]);

    await this.goToPosition(clamped[0][0], clamped[0][1]);

    await control.feed(this, trajectory(this, clamped));

  }

  toInches(v) {

    if (this.options.units === 1) return v / 2.54;

    if (this.options.units === 2) return v / 25.4;

    return v;

  }

  fromInches(v) {

    if (this.options.units === 1) return v * 2.54;

    if (this.options.units === 2) return v * 25.4;

    return v;

  }

  /**

   * Move the turtle to (x, y), clipping the actual motion to travel bounds.

   * Out-of-bounds portions are skipped with the pen raised.

   */

  async xyPlotSegment(relative, x, y) {

    this.requireInteractive();

    x = this.toInches(x);

    y = this.toInches(y);

    const turtle = this.pen.turtle;

    if (relative) {

      x += turtle.xpos;

      y += turtle.ypos;

    }

    const b = this.bounds;

    if (isClose(x, b[0][0], 2e-9)) x = b[0][0];

    if (isClose(x, b[1][0], 2e-9)) x = b[1][0];

    if (isClose(y, b[0][1], 2e-9)) y = b[0][1];

    if (isClose(y, b[1][1], 2e-9)) y = b[1][1];

    const start = [turtle.xpos, turtle.ypos];

    const target = [x, y];

    const [accept, seg] = clipSegment([start, target], b);

    if (accept && this.machine.connected) {

      if (!pointsNear(seg[0], start, 1e-9)) {

        if (this.params.autoClipLift && !turtle.zUp) {

          await this.pen.raise(this);

          turtle.zUp = false;

        }

        await this.goToPosition(seg[0][0], seg[0][1]);

      }

      if (!turtle.zUp) await this.pen.lower(this);

      await this.goToPosition(seg[1][0], seg[1][1]);

      if (!pointsNear(seg[1], target, 1e-9) && this.params.autoClipLift && !turtle.zUp) {

        await this.pen.raise(this);

        turtle.zUp = false;

      }

    }

    turtle.xpos = x;

    turtle.ypos = y;

    this.handleErrors();

  }

  /** Absolute move, keeping the current pen state. */

  goto(x, y) {

    return this.xyPlotSegment(false, x, y);

  }

  /** Absolute pen-up move. */

  async moveto(x, y) {

    this.requireInteractive();

    await this.pen.raise(this);

    this.pen.turtle.zUp = true;

    await this.xyPlotSegment(false, x, y);

  }

  /** Absolute pen-down move. */

  lineto(x, y) {

    this.pen.turtle.zUp = false;

    return this.xyPlotSegment(false, x, y);

  }

  /** Relative move, keeping the current pen state. */

  go(dx, dy) {

    return this.xyPlotSegment(true, dx, dy);

  }

  /** Relative pen-up move. */

  async move(dx, dy) {

    this.requireInteractive();

    await this.pen.raise(this);

    this.pen.turtle.zUp = true;

    await this.xyPlotSegment(true, dx, dy);

  }

  /** Relative pen-down move. */

  line(dx, dy) {

    this.pen.turtle.zUp = false;

    return this.xyPlotSegment(true, dx, dy);

  }

  async penup() {

    this.requireInteractive();

    await this.pen.raise(this);

    this.pen.turtle.zUp = true;

  }

  async pendown() {

    this.requireInteractive();

    this.pen.turtle.zUp = false;

    if (this.params.autoClipLift &&

        !pointInBounds([this.pen.turtle.xpos, this.pen.turtle.ypos], this.bounds)) {

      return; // Don't lower the pen outside the travel area.

    }

    await this.pen.lower(this);

  }

  /**

   * Draw a path through [[x, y], ...] (current units): pen-up move to the

   * first vertex, pen-down along the rest, then raise. Clipped at travel bounds.

   */

  async drawPath(vertices) {

    this.requireInteractive();

    if (vertices.length < 2 || this.plotStatus.stopped) return;

    const scaled = vertices.map(([x, y]) => [this.toInches(x), this.toInches(y)]);

    const last = scaled[scaled.length - 1];

    this.pen.turtle.xpos = last[0];

    this.pen.turtle.ypos = last[1];

    this.pen.turtle.zUp = true;

    const { paths } = clipPolyline(scaled, this.bounds, this.params.boundsTolerance);

    for (const path of paths) {

      if (this.plotStatus.stopped) break;

      await this.plotPolyline(path);

      this.handleErrors();

      await this.penup();

    }

    if (this.plotStatus.stopped) {

      this.pen.turtle = copyPos(this.pen.phys);

      this.pen.turtle.zUp = true;

    }

  }

  /** Hardware-timed delay in the motion queue. */

  async delay(ms) {

    this.requireInteractive();

    ms = Math.trunc(ms);

    if (ms > 0) await this.machine.timedPause(ms);

  }

  /** Wait until all queued motion has completed. */

  async block() {

    this.requireInteractive();

    await control.exhaustQueue(this);

  }

  currentPos() {

    return [this.fromInches(this.pen.phys.xpos), this.fromInches(this.pen.phys.ypos)];

  }

  turtlePos() {

    return [this.fromInches(this.pen.turtle.xpos), this.fromInches(this.pen.turtle.ypos)];

  }

  currentPen() {

    return this.pen.phys.zUp;

  }

  turtlePen() {

    return this.pen.turtle.zUp;

  }

  /** Raw EBB query. Bypasses all safety checks; use with great care. */

  async usbQuery(query) {

    this.requireInteractive();

    return this.machine.query(query);

  }

  /** Raw EBB command. Bypasses all safety checks; use with great care. */

  async usbCommand(command) {

    this.requireInteractive();

    await this.machine.query(command);

  }

  // --- Utilities (Python CLI "utility" mode equivalents) ---

  /** Return to the home corner at the current pen state's speed. */

  async walkHome() {

    this.requireInteractive();

    await this.pen.raise(this);

    await control.exhaustQueue(this);

    await control.writeStepOffsets(this, 0, 0);

    await this.homing.readPosition();

    await this.goToPosition(Math.min(this.pen.phys.xpos, 0.01), Math.min(this.pen.phys.ypos, 0.01), true);

    await this.homing.precisionMoveTo(0, 0);

    this.pen.turtle = copyPos(this.pen.phys);

    this.pen.turtle.zUp = true;

  }

  /** Disable (freewheel) the XY motors. Position is lost until re-homed. */

  async disableXY() {

    await this.machine.motorsDisable();

    await this.machine.varWrite(0, 12); // No longer homed

  }

  /** Force a fresh homing sequence. */

  async rehome() {

    this.requireInteractive();

    await this.pen.raise(this);

    await control.enableMotors(this);

    await this.machine.varWrite(0, 12);

    const ok = await this.homing.findHome();

    this.pen.turtle = copyPos(this.pen.phys);

    this.pen.turtle.zUp = true;

    return ok;

  }

  /** Lower the pen, pause half a second, raise it. */

  async cyclePen() {

    this.requireInteractive();

    await this.pen.cycle(this);

  }

  // --- Plotting ---

  /**

   * Plot a list of polylines given in inches from the home corner, like the

   * Python Plot context does for an SVG: plot each path, then return home.

   * onProgress(doneCount, total) is called after each path.

   */

  async plotPolylines(polylines, { onProgress = null } = {}) {

    this.requireInteractive();

    this.pauseRequested = false;

    this.plotStatus.stopped = 0;

    this.plotStatus.stats = newStats();

    await this.pen.raise(this);

    let done = 0;

    for (const polyline of polylines) {

      if (this.plotStatus.stopped) break;

      const { paths, outOfBounds } = clipPolyline(polyline, this.bounds, this.params.boundsTolerance);

      if (outOfBounds) this.warn('bounds');

      for (const path of paths) {

        if (this.plotStatus.stopped) break;

        await this.plotPolyline(path);

      }

      done += 1;

      onProgress?.(done, polylines.length);

    }

    await this.pen.raise(this);

    if (this.plotStatus.stopped === 0) {

      await this.goToPosition(Math.min(this.pen.phys.xpos, 0.1), Math.min(this.pen.phys.ypos, 0.1));

      await this.homing.precisionMoveTo(0, 0);

    }

    this.pen.turtle = copyPos(this.pen.phys);

    this.pen.turtle.zUp = true;

    const stopped = this.plotStatus.stopped;

    if (stopped) {

      // Allow further commands after a pause; the caller sees the code.

      this.plotStatus.stopped = 0;

      this.pauseRequested = false;

    }

    return { stopped, stats: this.plotStatus.stats };

  }

}