@thi.ng/axidraw 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-12-22T21:47:07Z
+- **Last updated**: 2022-12-29T20:56:59Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,28 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/axidraw@0.3.0) (2022-12-29)
+
+#### 🚀 Features
+
+- add draw metrics ([0ff015c](https://github.com/thi-ng/umbrella/commit/0ff015c))
+  - add Metrics interface
+  - update AxiDraw.draw() to record metrics
+  - update .moveTo() to return delay & distance
+- add serial port abstraction & impls ([c774da1](https://github.com/thi-ng/umbrella/commit/c774da1))
+  - add SerialConnection adapter
+  - add `SERIAL_PORT` default impl (actual serial port)
+  - add `MOCK_SERIAL` & MockSerial impl for testing
+  - update AxiDrawOpts & AxiDraw to use adapter only
+- add registrationMark() util, fix imports ([e05e99d](https://github.com/thi-ng/umbrella/commit/e05e99d))
+- add Metrics.penCommands, fix nested metrics handling ([a7149cd](https://github.com/thi-ng/umbrella/commit/a7149cd))
+  - add counter for pen up/down commands
+  - add start/stop cmd metrics to current tally
+
+#### ♻️ Refactoring
+
+- update "no-browser" pkg handling ([0e84f1b](https://github.com/thi-ng/umbrella/commit/0e84f1b))
+
 ## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/axidraw@0.2.0) (2022-12-10)
 
 #### 🚀 Features

package/README.md

@@ -17,6 +17,7 @@ This project is part of the
   - [SVG support](#svg-support)
   - [Serial port support](#serial-port-support)
   - [Draw control](#draw-control)
+  - [Metrics](#metrics)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -115,9 +116,11 @@ only aimed at Node.js though...
 
 ### Draw control
 
-The main draw function provided by this package is async and can supports custom
-implementations to pause, resume or cancel the processing of further drawing
-commands. By the default
+The main
+[`draw()`](https://docs.thi.ng/umbrella/axidraw/classes/AxiDraw.html#draw)
+function provided by this package is async and supports custom implementations
+to pause, resume or cancel the processing of further drawing commands. By the
+default
 [`AxiDrawControl`](https://docs.thi.ng/umbrella/axidraw/classes/AxiDrawControl.html)
 is used as default implementation.
 
@@ -129,6 +132,20 @@ when resuming it will be sent down again (if it was originally down). Draw
 commands are only sent to the machine if no control is provided at all or if the
 control is in the "continue" state.
 
+### Metrics
+
+The [`draw()`](https://docs.thi.ng/umbrella/axidraw/classes/AxiDraw.html#draw)
+function also records several
+[metrics](https://docs.thi.ng/umbrella/axidraw/interfaces/Metrics.html), useful
+for further analysis (or to identify optimizations) of the plotting process.
+These metrics include:
+
+- total duration
+- total distance traveled
+- draw distance (i.e. only whilst pen is down)
+- number of pen up/down commands (i.e. to consider servo lifespan)
+- total number of commands
+
 ## Status
 
 **ALPHA** - bleeding edge / work-in-progress
@@ -147,7 +164,7 @@ For Node.js REPL:
 const axidraw = await import("@thi.ng/axidraw");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.67 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.96 KB
 
 ## Dependencies
 
@@ -240,8 +257,12 @@ import { map, range } from "@thi.ng/transducers";
 
 Other selected toots/tweets:
 
+- https://mastodon.thi.ng/@toxi/109490174709589253
+- https://mastodon.thi.ng/@toxi/109473655772673067
 - https://mastodon.thi.ng/@toxi/109474947869078797
 - https://mastodon.thi.ng/@toxi/109483553358349473
+- https://mastodon.thi.ng/@toxi/109570540391689321
+- https://mastodon.thi.ng/@toxi/109586780630493994
 - more to come...
 
 ## Authors

package/api.d.ts

@@ -31,6 +31,33 @@ export type DrawCommand = StartCommand | StopCommand | HomeCommand | ResetComman
  * Global plotter drawing configuration. Also see {@link DEFAULT_OPTS}.
  */
 export interface AxiDrawOpts {
+    /**
+     * Serial connection to use (only used for testing/dev purposes, otherwise
+     * leave default).
+     *
+     * @defaultValue {@link SERIAL_PORT}
+     */
+    serial: SerialConnection;
+    /**
+     * Logger instance for outputting draw commands, state info and metrics.
+     */
+    logger: ILogger;
+    /**
+     * Optional implementation to pause, resume or cancel the processing of
+     * drawing commands (see {@link AxiDrawControl} for default impl).
+     *
+     * @remarks
+     * If a control is provided, it will be checked prior to processing each
+     * individual command. Drawing will be paused if the control state is in
+     * {@link AxiDrawState.PAUSE} state and the control will be rechecked every
+     * {@link AxiDrawOpts.refresh} milliseconds for updates. In paused state,
+     * the pen will be automatically lifted (if it wasn't already) and when
+     * resuming it will be sent down again (if it was originally down).
+     *
+     * Draw commands are only sent to the machine if no control is provided at
+     * all or if the control is in the {@link AxiDrawState.CONTINUE} state.
+     */
+    control?: IDeref<AxiDrawState>;
     /**
      * Conversion factor from geometry worldspace units to inches.
      * Default units are millimeters.
@@ -92,26 +119,6 @@ export interface AxiDrawOpts {
      * @defaultValue `[UP, HOME, OFF]`
      */
     stop: DrawCommand[];
-    /**
-     * Logger instance
-     */
-    logger: ILogger;
-    /**
-     * Optional implementation to pause, resume or cancel the processing of
-     * drawing commands (see {@link AxiDrawControl} for default impl).
-     *
-     * @remarks
-     * If a control is provided, it will be checked prior to processing each
-     * individual command. Drawing will be paused if the control state is in
-     * {@link AxiDrawState.PAUSE} state and the control will be rechecked every
-     * {@link AxiDrawOpts.refresh} milliseconds for updates. In paused state,
-     * the pen will be automatically lifted (if it wasn't already) and when
-     * resuming it will be sent down again (if it was originally down).
-     *
-     * Draw commands are only sent to the machine if no control is provided at
-     * all or if the control is in the {@link AxiDrawState.CONTINUE} state.
-     */
-    control?: IDeref<AxiDrawState>;
     /**
      * Refresh interval for checking the control FSM in paused state.
      *
@@ -184,4 +191,59 @@ export interface PolylineOpts {
      */
     onlyGeo: boolean;
 }
+/**
+ * Metrics returned by {@link AxiDraw.draw}.
+ */
+export interface Metrics {
+    /**
+     * Total number of milliseconds taken for drawing all given commands (incl.
+     * any pauses caused by the control)
+     */
+    duration: number;
+    /**
+     * Total draw distance, i.e. distance traveled whilst pen down (in original
+     * user units, see {@link AxiDrawOpts.unitsPerInch}).
+     */
+    drawDist: number;
+    /**
+     * Total traveled, incl. any movements without drawing (in original user
+     * units, see {@link AxiDrawOpts.unitsPerInch}).
+     */
+    totalDist: number;
+    /**
+     * Number of pen up/down commands (useful for measuring servo lifespan).
+     */
+    penCommands: number;
+    /**
+     * Total number of {@link DrawCommand}s processed.
+     */
+    commands: number;
+}
+export interface SerialConnection {
+    /**
+     * Async function. Returns a list of available serial ports. The arg given
+     * is the path requested by the user when calling {@link AxiDraw.connect}.
+     *
+     * @param path
+     */
+    list(path: string): Promise<{
+        path: string;
+    }[]>;
+    /**
+     * Returns an actual serial port (or mock) instance, is given the first
+     * matching path in array returned by {@link SerialConnection.list}.
+     *
+     * @param path
+     * @param baudRate
+     */
+    ctor(path: string, baudRate: number): ISerial;
+}
+export interface ISerial {
+    /**
+     * Writes given string to the port.
+     *
+     * @param msg
+     */
+    write(msg: string): void;
+}
 //# sourceMappingURL=api.d.ts.map

package/axidraw.d.ts

@@ -1,10 +1,9 @@
 import type { IReset } from "@thi.ng/api";
 import { ReadonlyVec, Vec } from "@thi.ng/vectors";
-import { SerialPort } from "serialport";
-import { AxiDrawOpts, DrawCommand } from "./api.js";
+import { AxiDrawOpts, DrawCommand, ISerial, Metrics } from "./api.js";
 export declare const DEFAULT_OPTS: AxiDrawOpts;
 export declare class AxiDraw implements IReset {
-    serial: SerialPort;
+    serial: ISerial;
     opts: AxiDrawOpts;
     isConnected: boolean;
     isPenDown: boolean;
@@ -30,9 +29,9 @@ export declare class AxiDraw implements IReset {
      * Async function. Converts sequence of {@link DrawCommand}s into actual EBB
      * commands and sends them via configured serial port to the AxiDraw. If
      * `wrap` is enabled (default), the given commands will be automatically
-     * wrapped with start/stop commands via {@link complete}. Returns total
-     * number of milliseconds taken for drawing (incl. any pauses caused by the
-     * control).
+     * wrapped with start/stop commands via {@link complete}. Returns object of
+     * collected {@link Metrics}. If `showMetrics` is enabled (default), the
+     * metrics will also be written to the configured logger.
      *
      * @remarks
      * This function is async and if using `await` will only return once all
@@ -57,22 +56,33 @@ export declare class AxiDraw implements IReset {
      *
      * @param commands
      * @param wrap
+     * @param showMetrics
      */
-    draw(commands: Iterable<DrawCommand>, wrap?: boolean): Promise<number>;
+    draw(commands: Iterable<DrawCommand>, wrap?: boolean, showMetrics?: boolean): Promise<Metrics>;
     /**
      * Syntax sugar for drawing a **single** command only, otherwise same as
      * {@link AxiDraw.draw}.
      *
      * @param cmd
      */
-    draw1(cmd: DrawCommand): Promise<number>;
+    draw1(cmd: DrawCommand): Promise<Metrics>;
     motorsOn(): void;
     motorsOff(): void;
     penConfig(down?: number, up?: number): void;
     penUp(delay?: number, level?: number): number;
     penDown(delay?: number, level?: number): number;
-    moveTo(p: ReadonlyVec, tempo?: number): number;
-    home(): number;
+    /**
+     * Sends a "moveto" command (absolute coords). Returns tuple of `[duration,
+     * distance]` (distance in original/configured units)
+     *
+     * @param p
+     * @param tempo
+     */
+    moveTo(p: ReadonlyVec, tempo?: number): number[];
+    /**
+     * Syntax sugar for {@link AxiDraw.moveTo}([0, 0]).
+     */
+    home(): number[];
     protected onSignal(): Promise<void>;
     protected send(msg: string): void;
     /**

package/axidraw.js

@@ -1,13 +1,15 @@
 import { isString } from "@thi.ng/checks";
 import { delayed } from "@thi.ng/compose";
+import { formatDuration } from "@thi.ng/date";
 import { assert, ioerror, unsupported } from "@thi.ng/errors";
 import { ConsoleLogger } from "@thi.ng/logger";
-import { abs2, mulN2, set2, sub2, zero, ZERO2, } from "@thi.ng/vectors";
-import { SerialPort } from "serialport";
+import { abs2, mag, mulN2, set2, sub2, zero, ZERO2, } from "@thi.ng/vectors";
 import { AxiDrawState, HOME, OFF, ON, PEN, UP, } from "./api.js";
 import { AxiDrawControl } from "./control.js";
 import { complete } from "./polyline.js";
+import { SERIAL_PORT } from "./serial.js";
 export const DEFAULT_OPTS = {
+    serial: SERIAL_PORT,
     logger: new ConsoleLogger("axidraw"),
     control: new AxiDrawControl(),
     refresh: 1000,
@@ -51,14 +53,11 @@ export class AxiDraw {
      */
     async connect(path = "/dev/tty.usbmodem") {
         const isStr = isString(path);
-        for (let port of await SerialPort.list()) {
+        for (let port of await this.opts.serial.list(path.toString())) {
             if ((isStr && port.path.startsWith(path)) ||
                 (!isStr && path.test(port.path))) {
                 this.opts.logger.info(`using device: ${port.path}...`);
-                this.serial = new SerialPort({
-                    path: port.path,
-                    baudRate: 38400,
-                });
+                this.serial = this.opts.serial.ctor(port.path, 38400);
                 this.isConnected = true;
                 if (this.opts.sigint) {
                     this.opts.logger.debug("installing signal handler...");
@@ -73,9 +72,9 @@ export class AxiDraw {
      * Async function. Converts sequence of {@link DrawCommand}s into actual EBB
      * commands and sends them via configured serial port to the AxiDraw. If
      * `wrap` is enabled (default), the given commands will be automatically
-     * wrapped with start/stop commands via {@link complete}. Returns total
-     * number of milliseconds taken for drawing (incl. any pauses caused by the
-     * control).
+     * wrapped with start/stop commands via {@link complete}. Returns object of
+     * collected {@link Metrics}. If `showMetrics` is enabled (default), the
+     * metrics will also be written to the configured logger.
      *
      * @remarks
      * This function is async and if using `await` will only return once all
@@ -100,12 +99,23 @@ export class AxiDraw {
      *
      * @param commands
      * @param wrap
+     * @param showMetrics
      */
-    async draw(commands, wrap = true) {
+    async draw(commands, wrap = true, showMetrics = true) {
         assert(this.isConnected, "AxiDraw not yet connected, need to call .connect() first");
         let t0 = Date.now();
+        let numCommands = 0;
+        let penCommands = 0;
+        let totalDist = 0;
+        let drawDist = 0;
+        const $recordDist = (dist) => {
+            totalDist += dist;
+            if (this.isPenDown)
+                drawDist += dist;
+        };
         const { control, logger, preDelay, refresh } = this.opts;
         for (let $cmd of wrap ? complete(commands) : commands) {
+            numCommands++;
             if (control) {
                 let state = control.deref();
                 if (state === AxiDrawState.PAUSE) {
@@ -126,13 +136,20 @@ export class AxiDraw {
             }
             const [cmd, a, b] = $cmd;
             let wait = -1;
+            let dist;
             switch (cmd) {
                 case "start":
-                case "stop":
-                    await this.draw(this.opts[cmd], false);
+                case "stop": {
+                    const metrics = await this.draw(this.opts[cmd], false, false);
+                    numCommands += metrics.commands;
+                    penCommands += metrics.penCommands;
+                    totalDist += metrics.totalDist;
+                    drawDist += metrics.drawDist;
                     break;
+                }
                 case "home":
-                    wait = this.home();
+                    [wait, dist] = this.home();
+                    $recordDist(dist);
                     break;
                 case "reset":
                     this.reset();
@@ -148,15 +165,18 @@ export class AxiDraw {
                     break;
                 case "u":
                     wait = this.penUp(a, b);
+                    penCommands++;
                     break;
                 case "d":
                     wait = this.penDown(a, b);
+                    penCommands++;
                     break;
                 case "w":
                     wait = a;
                     break;
                 case "m":
-                    wait = this.moveTo(a, b);
+                    [wait, dist] = this.moveTo(a, b);
+                    $recordDist(dist);
                     break;
                 default:
                     unsupported(`unknown command: ${$cmd}`);
@@ -167,7 +187,21 @@ export class AxiDraw {
                 await delayed(0, wait);
             }
         }
-        return Date.now() - t0;
+        const duration = Date.now() - t0;
+        if (showMetrics) {
+            logger.info(`total duration : ${formatDuration(duration)}`);
+            logger.info(`total commands : ${numCommands}`);
+            logger.info(`pen up/downs   : ${penCommands}`);
+            logger.info(`total distance : ${totalDist.toFixed(2)}`);
+            logger.info(`draw distance  : ${drawDist.toFixed(2)}`);
+        }
+        return {
+            duration,
+            drawDist,
+            totalDist,
+            penCommands,
+            commands: numCommands,
+        };
     }
     /**
      * Syntax sugar for drawing a **single** command only, otherwise same as
@@ -209,6 +243,13 @@ export class AxiDraw {
         this.isPenDown = true;
         return delay;
     }
+    /**
+     * Sends a "moveto" command (absolute coords). Returns tuple of `[duration,
+     * distance]` (distance in original/configured units)
+     *
+     * @param p
+     * @param tempo
+     */
     moveTo(p, tempo = 1) {
         const { pos, targetPos, opts } = this;
         // apply scale factor: worldspace units -> motor steps
@@ -218,8 +259,11 @@ export class AxiDraw {
         const maxAxis = Math.max(...abs2([], delta));
         const duration = (1000 * maxAxis) / (opts.speed * tempo);
         this.send(`XM,${duration | 0},${delta[0] | 0},${delta[1] | 0}\r`);
-        return duration;
+        return [duration, (mag(delta) * opts.unitsPerInch) / opts.stepsPerInch];
     }
+    /**
+     * Syntax sugar for {@link AxiDraw.moveTo}([0, 0]).
+     */
     home() {
         return this.moveTo(ZERO2);
     }

package/index.d.ts

@@ -2,4 +2,6 @@ export * from "./api.js";
 export * from "./axidraw.js";
 export * from "./control.js";
 export * from "./polyline.js";
+export * from "./serial.js";
+export * from "./utils.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -2,3 +2,5 @@ export * from "./api.js";
 export * from "./axidraw.js";
 export * from "./control.js";
 export * from "./polyline.js";
+export * from "./serial.js";
+export * from "./utils.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/axidraw",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Minimal AxiDraw plotter/drawing machine controller for Node.js",
   "type": "module",
   "module": "./index.js",
@@ -39,7 +39,7 @@
     "@thi.ng/compose": "^2.1.23",
     "@thi.ng/errors": "^2.2.7",
     "@thi.ng/logger": "^1.4.6",
-    "@thi.ng/vectors": "^7.5.29",
+    "@thi.ng/vectors": "^7.5.30",
     "serialport": "^10.5.0"
   },
   "devDependencies": {
@@ -58,7 +58,8 @@
     "geometry",
     "io",
     "logger",
-    "node-only",
+    "nodejs",
+    "no-browser",
     "penplotter",
     "polyline",
     "serialport",
@@ -89,11 +90,17 @@
     },
     "./polyline": {
       "default": "./polyline.js"
+    },
+    "./serial": {
+      "default": "./serial.js"
+    },
+    "./utils": {
+      "default": "./utils.js"
     }
   },
   "thi.ng": {
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "bc6f7f5e2765bb96fe64db804eaf4b2443b47fc6\n"
+  "gitHead": "28bb74c67217a352d673b6efdab234921d4a370e\n"
 }

package/serial.d.ts

@@ -0,0 +1,27 @@
+import type { ISerial, SerialConnection } from "./api.js";
+/**
+ * Default connection using the actual serial port.
+ */
+export declare const SERIAL_PORT: SerialConnection;
+/**
+ * Mock serial connection which uses a in-memory logger to record all draw
+ * commands. Only intended for testing/dev purposes.
+ */
+export declare const MOCK_SERIAL: SerialConnection;
+/**
+ * Minimal mock "serial port" implementation for testing purposes. Records all
+ * sent messages into an internal string array for later analysis.
+ */
+export declare class MockSerial implements ISerial {
+    sent: string[];
+    /**
+     * Clears internal log of "sent" message.
+     */
+    clear(): void;
+    /**
+     * Appends
+     * @param msg
+     */
+    write(msg: string): void;
+}
+//# sourceMappingURL=serial.d.ts.map

package/serial.js

@@ -0,0 +1,38 @@
+import { SerialPort } from "serialport";
+/**
+ * Default connection using the actual serial port.
+ */
+export const SERIAL_PORT = {
+    list: () => SerialPort.list(),
+    ctor: (path, baudRate) => new SerialPort({ path, baudRate }),
+};
+/**
+ * Mock serial connection which uses a in-memory logger to record all draw
+ * commands. Only intended for testing/dev purposes.
+ */
+export const MOCK_SERIAL = {
+    list: async (path) => [{ path }],
+    ctor: () => new MockSerial(),
+};
+/**
+ * Minimal mock "serial port" implementation for testing purposes. Records all
+ * sent messages into an internal string array for later analysis.
+ */
+export class MockSerial {
+    constructor() {
+        this.sent = [];
+    }
+    /**
+     * Clears internal log of "sent" message.
+     */
+    clear() {
+        this.sent = [];
+    }
+    /**
+     * Appends
+     * @param msg
+     */
+    write(msg) {
+        this.sent.push(msg);
+    }
+}

package/utils.d.ts

@@ -0,0 +1,17 @@
+import { ReadonlyVec } from "@thi.ng/vectors";
+import type { DrawCommand } from "./api.js";
+/**
+ * Generates a {@link DrawCommand} sequence to draw a registration mark
+ * (crosshair + circle) centered around `pos`.
+ *
+ * @example
+ * ```ts
+ * axi.draw(registrationMark([20, 20]))
+ * ```
+ *
+ * @param pos
+ * @param size
+ * @param r
+ */
+export declare const registrationMark: ([x, y]: ReadonlyVec, size?: number, r?: number) => DrawCommand[];
+//# sourceMappingURL=utils.d.ts.map

package/utils.js

@@ -0,0 +1,34 @@
+import { map, normRange } from "@thi.ng/transducers";
+import { cartesian2 } from "@thi.ng/vectors";
+/**
+ * Generates a {@link DrawCommand} sequence to draw a registration mark
+ * (crosshair + circle) centered around `pos`.
+ *
+ * @example
+ * ```ts
+ * axi.draw(registrationMark([20, 20]))
+ * ```
+ *
+ * @param pos
+ * @param size
+ * @param r
+ */
+export const registrationMark = ([x, y], size = 5, r = size * 0.75) => [
+    // crosshair
+    // horizontal
+    ["m", [x - size, y]],
+    ["d"],
+    ["m", [x + size, y]],
+    ["u"],
+    // vertical
+    ["m", [x, y - size]],
+    ["d"],
+    ["m", [x, y + size]],
+    ["u"],
+    // circle
+    ["m", [x + r, y]],
+    ["d"],
+    ...map((t) => ["m", cartesian2([], [r, t * Math.PI * 2], [x, y])], normRange(40)),
+    ["u"],
+    ["m", [x, y]],
+];