@thi.ng/axidraw 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-12-06T17:16:38Z
+- **Last updated**: 2022-12-16T12:52:25Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,35 @@ 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.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/axidraw@0.2.0) (2022-12-10)
+
+#### 🚀 Features
+
+- major updates/additions ([eb41c28](https://github.com/thi-ng/umbrella/commit/eb41c28))
+  - extract polyline() as standalone fn
+  - add complete() syntax sugar
+  - update UP/DOWN commands to accept opt. pen level/position
+  - add RESET command
+  - extract various draw commands into separate methods, simplify draw()
+  - update draw() w/ FSM to pause/resume/cancel processing
+  - add AxiDrawState FSM enum
+  - add AxiDrawControl class, use as default controller
+  - update AxiDrawOpts w/ new options
+  - update connect() to throw error if unsuccessful
+  - add SIGINT signal handler to handle Ctrl+C
+- update .draw() to auto-wrap command seq ([60aaad2](https://github.com/thi-ng/umbrella/commit/60aaad2))
+- add PolylineOpts, update polyline() ([c8a271f](https://github.com/thi-ng/umbrella/commit/c8a271f))
+
+#### 🩹 Bug fixes
+
+- fix polyline(), only apply custom speed for drawing ([c43b6f5](https://github.com/thi-ng/umbrella/commit/c43b6f5))
+- update draw calls to disable cmd wrapping ([4cd5e53](https://github.com/thi-ng/umbrella/commit/4cd5e53))
+- fix waiting for start/stop/home commands ([42bf4eb](https://github.com/thi-ng/umbrella/commit/42bf4eb))
+
+#### ⏱ Performance improvements
+
+- remove obsolete UP command (and delay) in polyline() ([f71c64b](https://github.com/thi-ng/umbrella/commit/f71c64b))
+
 ## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/axidraw@0.1.0) (2022-12-06)
 
 #### 🚀 Features

package/README.md

@@ -1,35 +1,43 @@
 <!-- This file is generated - DO NOT EDIT! -->
 
-# ![axidraw](https://media.thi.ng/umbrella/banners-20220914/thing-axidraw.svg?25c834ce)
+# ![@thi.ng/axidraw](https://media.thi.ng/umbrella/banners-20220914/thing-axidraw.svg?25c834ce)
 
 [![npm version](https://img.shields.io/npm/v/@thi.ng/axidraw.svg)](https://www.npmjs.com/package/@thi.ng/axidraw)
 ![npm downloads](https://img.shields.io/npm/dm/@thi.ng/axidraw.svg)
-[![Twitter Follow](https://img.shields.io/twitter/follow/thing_umbrella.svg?style=flat-square&label=twitter)](https://twitter.com/thing_umbrella)
+[![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 This project is part of the
 [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo.
 
 - [About](#about)
   - [Declarative vs. imperative](#declarative-vs-imperative)
-  - [No SVG support](#no-svg-support)
+  - [Units, limits & clipping](#units-limits--clipping)
+  - [Path planning](#path-planning)
+  - [thi.ng/geom support](#thinggeom-support)
+  - [SVG support](#svg-support)
   - [Serial port support](#serial-port-support)
+  - [Draw control](#draw-control)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [API](#api)
+  - [Example usage](#example-usage)
+    - [Basics](#basics)
+  - [geom-axidraw example](#geom-axidraw-example)
 - [Authors](#authors)
 - [License](#license)
 
 ## About
 
-Minimal AxiDraw plotter/drawing machine controller for Node.js.
+Minimal AxiDraw plotter/drawing machine controller for Node.js
 
 This package provides a super-lightweight alternative to control an [AxiDraw
 plotter](https://axidraw.com/) directly from Node.js, using a small custom set
 of medium/high-level drawing commands. Structurally, these custom commands are
-[thi.ng/hiccup-like](https://github.com/thi-ng/umbrella/blob/develop/packages/hiccup/)
+[thi.ng/hiccup](https://github.com/thi-ng/umbrella/blob/develop/packages/hiccup/)-like
 S-expressions, which can be easily serialized to/from JSON and are translated to
-[EBB commands](https://evil-mad.github.io/EggBot/ebb.html) for the plotter.
+the native [EBB commands](https://evil-mad.github.io/EggBot/ebb.html) for the
+plotter.
 
 ### Declarative vs. imperative
 
@@ -42,28 +50,84 @@ following the pattern of other packages in the
 until the very last moment before being sent to the machine for physical
 output...
 
-### No SVG support
-
-This package does **not** provide conversion from SVG or any other geometry
-format conversions. Whilst not containing a full SVG parser (only single paths),
-the family of
+### Units, limits & clipping
+
+This package performs **no bounds checking nor clipping** and expects all given
+coordinates to be valid and within machine limits. Coordinates can be given in
+any unit, but if not using millimeters (default), a conversion factor to inches
+(`unitsPerInch`) **MUST** be provided as part of the [options
+object](https://docs.thi.ng/umbrella/axidraw/interfaces/AxiDrawOpts.html) given
+to the `AxiDraw` constructor. Clipping can be handled by the geom or
+geom-axidraw packages (see below)...
+
+### Path planning
+
+Path planning is considered a higher level operation than what's addressed by
+this package and is therefore out of scope. The
+[thi.ng/geom-axidraw](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-axidraw)
+provides some configurable point & shape sorting functions, but this is an
+interim solution and a full path/route planning facility is currently still
+outstanding and awaiting to be ported from other projects.
+
+### thi.ng/geom support
+
+The [thi.ng/geom](https://github.com/thi-ng/umbrella/tree/develop/packages/geom)
+package provides numerous shape types & operations to generate & transform
+geometry. Additionally,
+[thi.ng/geom-axidraw](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-axidraw)
+can act as bridge API and provides the polymorphic
+[`asAxiDraw()`](https://docs.thi.ng/umbrella/geom-axidraw/functions/asAxiDraw.html)
+function to convert single shapes or entire shape groups/hierarchies directly
+into the draw commands used by this (axidraw) package. See package readme for
+more details and examples.
+
+### SVG support
+
+This package does **not** provide any direct conversions from SVG or any other
+geometry format. But again, whilst not containing a full SVG parser (at current
+only single paths can be parsed), the family of
 [thi.ng/geom](https://github.com/thi-ng/umbrella/tree/develop/packages/geom)
-packages provides numerous other shape types & operations which can be directly
+packages provides numerous shape types & operations which can be directly
 utilized to output generated geometry together with this package...
 
-The only built-in conversion provided is the [`AxiDraw.polyline()`]() method to
-convert an array of points (representing a polyline) into an array of drawing
-commands. All other conversions are out of scope for this package (& for now).
+The only built-in conversion provided here is the
+[`polyline()`](https://docs.thi.ng/umbrella/axidraw/functions/polyline.html)
+utility function to convert an array of points (representing a polyline) to an
+array of drawing commands (with various config options). All other conversions
+are out of scope for this package (& for now).
 
 ### Serial port support
 
 We're using the [serialport](https://serialport.io/) NPM package to submit data
-directly to the drawing machine. That pacakge includes native bindings for
+directly to the drawing machine. That package includes native bindings for
 Linux, MacOS and Windows.
 
-The `AxiDraw.connect()` function (see example below) attempts to find the
-drawing machine by matching a given regexp with available port names. The
-default regexp might only work on Mac, but YMMV!
+The
+[`AxiDraw.connect()`](https://docs.thi.ng/umbrella/axidraw/classes/AxiDraw.html#connect)
+function (see example below) attempts to find the drawing machine by matching a
+given regexp with available port names. The default regexp might only work on
+Mac, but YMMV!
+
+At some point it would also be worth looking into
+[WebSerial](https://developer.mozilla.org/en-US/docs/Web/API/Web_Serial_API)
+support to enable plotting directly from the browser. Right now this package is
+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
+[`AxiDrawControl`](https://docs.thi.ng/umbrella/axidraw/classes/AxiDrawControl.html)
+is used as default implementation.
+
+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 paused state and the
+control will be rechecked every N milliseconds for updates (configurable). 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 "continue" state.
 
 ## Status
 
@@ -87,14 +151,11 @@ ES module import:
 
 For Node.js REPL:
 
-```text
-# with flag only for < v16
-node --experimental-repl-await
-
-> const axidraw = await import("@thi.ng/axidraw");
+```js
+const axidraw = await import("@thi.ng/axidraw");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.01 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.67 KB
 
 ## Dependencies
 
@@ -109,50 +170,90 @@ Package sizes (brotli'd, pre-treeshake): ESM: 1.01 KB
 
 [Generated API docs](https://docs.thi.ng/umbrella/axidraw/)
 
-```ts tangle:export/readme.js
-import { AxiDraw } from "@thi.ng/axidraw";
-import { circle, vertices } from "@thi.ng/geom";
+### Example usage
+
+#### Basics
+
+```js tangle:export/readme-basic.js
+import { AxiDraw, polyline } from "@thi.ng/axidraw";
 
 (async () => {
 
 // instantiate w/ default options (see docs for info)
-// default paper size is DIN A4
 const axi = new AxiDraw();
 
-// connect to 1st serial port matching given regexp
-await axi.connect(/^\/dev\/tty\.usbmodem/);
+// connect to 1st serial port matching given pre-string or regexp
+// (the port used here is the default arg)
+await axi.connect("/dev/tty.usbmodem");
 // true
 
-// compute 60 points on a circle at (100,50) w/ radius 30
-// (all units in mm)
-const verts = vertices(circle([100, 50], 30), { num: 60, last: true });
-// [
-//   [ 130, 50 ],
-//   [ 129.8356568610482, 53.1358538980296 ],
-//   [ 129.34442802201417, 56.23735072453278 ],
-//   ...
-// ]
+// vertices defining a polyline of a 100x100 mm square (top left at 20,20)
+const verts = [[20, 20], [120, 20], [120, 120], [20, 120], [20, 20]];
 
-// convert to drawing commands (w/ default opts)
-const path = axi.polyline(verts)
+// convert to drawing commands (w/ custom speed, 25%)
+// see docs for config options
+const path = polyline(verts, { speed: 0.25 })
 // [
-//   [ 'u' ],
-//   [ 'm', [ 130, 50 ], 1 ],
-//   [ 'd' ],
-//   [ 'm', [ 129.8356568610482, 53.1358538980296 ], 1 ],
-//   [ 'm', [ 129.34442802201417, 56.23735072453278 ], 1 ],
-//   ...
+//   ["m", [20, 20]],
+//   ["d"],
+//   ["m", [120, 20], 0.25],
+//   ["m", [120, 120], 0.25],
+//   ["m", [20, 120], 0.25],
+//   ["m", [20, 20], 0.25],
+//   ["u"]
 // ]
 
-// draw/send seq of commands (incl. start/end sequence, configurable)
-await axi.draw([["start"], ...path, ["stop"]]);
+// draw/send seq of commands
+// by default the given commands will be wrapped with a start/end
+// command sequence, configurable via options given to AxiDraw ctor)...
+await axi.draw(path);
 
 })();
 ```
 
+### geom-axidraw example
+
+Result shown here: https://mastodon.thi.ng/@toxi/109473655772673067
+
+```js tangle:export/readme-geom.js
+import { AxiDraw } from "@thi.ng/axidraw";
+import { asCubic, group, pathFromCubics, star } from "@thi.ng/geom";
+import { asAxiDraw } from "@thi.ng/geom-axidraw";
+import { map, range } from "@thi.ng/transducers";
+
+(async () => {
+    // create group of bezier-interpolated star polygons,
+    // with each path using a slightly different configuration
+    const geo = group({ translate: [100, 100] }, [
+        ...map(
+            (t) =>
+                pathFromCubics(
+                    asCubic(star(90, 6, [t, 1]), {
+                        breakPoints: true,
+                        scale: 0.66,
+                    })
+                ),
+            range(0.3, 1.01, 0.05)
+        ),
+    ]);
+
+    // connect to plotter
+    const axi = new AxiDraw();
+    await axi.connect();
+    // convert geometry to drawing commands & send to plotter
+    await axi.draw(asAxiDraw(geo, { samples: 40 }));
+})();
+```
+
+Other selected toots/tweets:
+
+- https://mastodon.thi.ng/@toxi/109474947869078797
+- https://mastodon.thi.ng/@toxi/109483553358349473
+- more to come...
+
 ## Authors
 
-Karsten Schmidt
+- [Karsten Schmidt](https://thi.ng)
 
 If this project contributes to an academic publication, please cite it as:
 
@@ -167,4 +268,4 @@ If this project contributes to an academic publication, please cite it as:
 
 ## License
 
-&copy; 2022 Karsten Schmidt // Apache Software License 2.0
+&copy; 2022 Karsten Schmidt // Apache License 2.0

package/api.d.ts

@@ -1,28 +1,35 @@
+import type { IDeref } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 import type { ReadonlyVec } from "@thi.ng/vectors";
 /** Start command sequence (configurable via {@link AxiDrawOpts}) */
-export declare type StartCommand = ["start"];
+export type StartCommand = ["start"];
 /** Stop command sequence (configurable via {@link AxiDrawOpts}) */
-export declare type StopCommand = ["stop"];
+export type StopCommand = ["stop"];
 /** Return plotter to initial XY position */
-export declare type HomeCommand = ["home"];
+export type HomeCommand = ["home"];
+/** Reset curr position as home (0,0) */
+export type ResetCommand = ["reset"];
 /** Turn XY motors on/off */
-export declare type MotorCommand = ["on" | "off"];
+export type MotorCommand = ["on" | "off"];
 /** Pen config, min/down position, max/up position (in %) */
-export declare type PenConfigCommand = ["pen", number?, number?];
+export type PenConfigCommand = ["pen", number?, number?];
 /**
- * Pen up/down, optional delay (in ms), if omitted values used from
- * {@link AxiDrawOpts}.
+ * Pen up/down, optional delay (in ms), optional custom level/position. If
+ * omitted, default values used from {@link AxiDrawOpts}. Using -1 as delay also
+ * uses default.
  */
-export declare type PenUpDownCommand = ["u" | "d", number?];
+export type PenUpDownCommand = ["u" | "d", number?, number?];
 /**
  * Move to abs pos (in worldspace coords, default mm), optional speed factor
  * (default: 1)
  */
-export declare type MoveXYCommand = ["m", ReadonlyVec, number?];
+export type MoveXYCommand = ["m", ReadonlyVec, number?];
 /** Explicit delay (in ms) */
-export declare type WaitCommand = ["w", number];
-export declare type DrawCommand = StartCommand | StopCommand | HomeCommand | MotorCommand | PenConfigCommand | PenUpDownCommand | MoveXYCommand | WaitCommand;
+export type WaitCommand = ["w", number];
+export type DrawCommand = StartCommand | StopCommand | HomeCommand | ResetCommand | MotorCommand | PenConfigCommand | PenUpDownCommand | MoveXYCommand | WaitCommand;
+/**
+ * Global plotter drawing configuration. Also see {@link DEFAULT_OPTS}.
+ */
 export interface AxiDrawOpts {
     /**
      * Conversion factor from geometry worldspace units to inches.
@@ -58,13 +65,13 @@ export interface AxiDrawOpts {
     /**
      * Delay after pen up
      *
-     * @defaultValue 300
+     * @defaultValue 150
      */
     delayUp: number;
     /**
      * Delay after pen down
      *
-     * @defaultValue 300
+     * @defaultValue 150
      */
     delayDown: number;
     /**
@@ -89,13 +96,92 @@ export interface AxiDrawOpts {
      * 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.
+     *
+     * @defaultValue 1000
+     */
+    refresh: number;
+    /**
+     * If true (default), installs SIGINT handler to lift pen when the Node.js
+     * process is terminated.
+     */
+    sigint: boolean;
 }
 export declare const START: StartCommand;
 export declare const STOP: StopCommand;
 export declare const HOME: HomeCommand;
+export declare const RESET: ResetCommand;
 export declare const PEN: PenConfigCommand;
 export declare const UP: PenUpDownCommand;
 export declare const DOWN: PenUpDownCommand;
 export declare const ON: MotorCommand;
 export declare const OFF: MotorCommand;
+/**
+ * FSM state enum for (interactive) control for processing of drawing commands.
+ * See {@link AxiDraw.draw} and {@link AxiDrawControl} for details.
+ */
+export declare enum AxiDrawState {
+    /**
+     * Draw command processing can continue as normal.
+     */
+    CONTINUE = 0,
+    /**
+     * Draw command processing is suspended indefinitely.
+     */
+    PAUSE = 1,
+    /**
+     * Draw command processing is cancelled.
+     */
+    CANCEL = 2
+}
+/**
+ * Drawing behavior options for a single polyline.
+ */
+export interface PolylineOpts {
+    /**
+     * Speed factor (multiple of globally configured draw speed). Depending on
+     * pen used, slower speeds might result in thicker strokes.
+     *
+     * @defaultValue 1
+     */
+    speed: number;
+    /**
+     * Pen down (Z) position (%) for this particular shape/polyline. Will be
+     * reset to globally configured default at the end of the shape.
+     */
+    down: number;
+    /**
+     * Delay for pen down command at the start of this particular
+     * shape/polyline.
+     */
+    delayDown: number;
+    /**
+     * Delay for pen up command at the end this particular shape/polyline.
+     */
+    delayUp: number;
+    /**
+     * If enabled, no pen up/down commands will be included.
+     * {@link PolylineOpts.speed} is the only other option considered then.
+     *
+     * @defaultValue false
+     */
+    onlyGeo: boolean;
+}
 //# sourceMappingURL=api.d.ts.map

package/api.js

@@ -1,8 +1,28 @@
 export const START = ["start"];
 export const STOP = ["stop"];
 export const HOME = ["home"];
+export const RESET = ["reset"];
 export const PEN = ["pen"];
 export const UP = ["u"];
 export const DOWN = ["d"];
 export const ON = ["on"];
 export const OFF = ["off"];
+/**
+ * FSM state enum for (interactive) control for processing of drawing commands.
+ * See {@link AxiDraw.draw} and {@link AxiDrawControl} for details.
+ */
+export var AxiDrawState;
+(function (AxiDrawState) {
+    /**
+     * Draw command processing can continue as normal.
+     */
+    AxiDrawState[AxiDrawState["CONTINUE"] = 0] = "CONTINUE";
+    /**
+     * Draw command processing is suspended indefinitely.
+     */
+    AxiDrawState[AxiDrawState["PAUSE"] = 1] = "PAUSE";
+    /**
+     * Draw command processing is cancelled.
+     */
+    AxiDrawState[AxiDrawState["CANCEL"] = 2] = "CANCEL";
+})(AxiDrawState || (AxiDrawState = {}));

package/axidraw.d.ts

@@ -1,33 +1,47 @@
-import type { Fn0 } from "@thi.ng/api";
+import type { IReset } from "@thi.ng/api";
 import { ReadonlyVec, Vec } from "@thi.ng/vectors";
 import { SerialPort } from "serialport";
 import { AxiDrawOpts, DrawCommand } from "./api.js";
 export declare const DEFAULT_OPTS: AxiDrawOpts;
-export declare class AxiDraw {
+export declare class AxiDraw implements IReset {
     serial: SerialPort;
     opts: AxiDrawOpts;
     isConnected: boolean;
+    isPenDown: boolean;
+    penLimits: [number, number];
     pos: Vec;
+    targetPos: Vec;
     constructor(opts?: Partial<AxiDrawOpts>);
+    reset(): this;
     /**
      * Async function. Attempts to connect to the drawing machine via given
      * (partial) serial port path/name, returns true if successful.
      *
+     * @remarks
+     * First matching port will be used. If `path` is a sting, a port name must
+     * only start with it in order to be considered a match.
+     *
+     * An error is thrown if no matching port could be found.
+     *
      * @param path
      */
-    connect(path?: RegExp): Promise<boolean>;
+    connect(path?: string | RegExp): Promise<void>;
     /**
      * Async function. Converts sequence of {@link DrawCommand}s into actual EBB
-     * commands and sends them via configured serial port to the AxiDraw. The
-     * optional `cancel` predicate is checked prior to each individual command
-     * and processing is stopped if that function returns a truthy result.
-     *
-     * Returns number of milliseconds taken for drawing.
+     * 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).
      *
      * @remarks
      * This function is async and if using `await` will only return once all
      * commands have been processed or cancelled.
      *
+     * The `control` implementation/ provided as part of {@link AxiDrawOpts} can
+     * be used to pause, resume or cancel the drawing (see
+     * {@link AxiDrawOpts.control} for details).
+     *
      * Reference:
      * - http://evil-mad.github.io/EggBot/ebb.html
      *
@@ -42,23 +56,35 @@ export declare class AxiDraw {
      * ```
      *
      * @param commands
-     * @param cancel
+     * @param wrap
      */
-    draw(commands: Iterable<DrawCommand>, cancel?: Fn0<boolean>): Promise<number>;
+    draw(commands: Iterable<DrawCommand>, wrap?: boolean): Promise<number>;
     /**
-     * Takes an array of 2D points and converts them into an array of
-     * {@link DrawCommand}s. The optional `speed` factor can be used to control
-     * draw speed (default: 1).
+     * Syntax sugar for drawing a **single** command only, otherwise same as
+     * {@link AxiDraw.draw}.
+     *
+     * @param cmd
+     */
+    draw1(cmd: DrawCommand): Promise<number>;
+    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;
+    protected onSignal(): Promise<void>;
+    protected send(msg: string): void;
+    /**
+     * Sends pen up/down config
      *
      * @remarks
-     * Unless `onlyGeo` is explicitly enabled, the resulting command sequence
-     * will also contain necessary pen up/down commands.
+     * Reference:
+     * - https://github.com/evil-mad/AxiDraw-Processing/blob/80d81a8c897b8a1872b0555af52a8d1b5b13cec4/AxiGen1/AxiGen1.pde#L213
      *
-     * @param pts
-     * @param speed
-     * @param onlyGeo
+     * @param id
+     * @param x
      */
-    polyline(pts: ReadonlyVec[], speed?: number, onlyGeo?: boolean): DrawCommand[];
-    protected send(msg: string): void;
+    protected sendPenConfig(id: number, x: number): void;
 }
 //# sourceMappingURL=axidraw.d.ts.map

package/axidraw.js

@@ -1,60 +1,90 @@
+import { isString } from "@thi.ng/checks";
 import { delayed } from "@thi.ng/compose";
-import { assert, unsupported } from "@thi.ng/errors";
+import { assert, ioerror, unsupported } from "@thi.ng/errors";
 import { ConsoleLogger } from "@thi.ng/logger";
-import { abs2, mulN2, set2, sub2 } from "@thi.ng/vectors";
+import { abs2, mulN2, set2, sub2, zero, ZERO2, } from "@thi.ng/vectors";
 import { SerialPort } from "serialport";
-import { DOWN, HOME, OFF, ON, PEN, UP, } from "./api.js";
+import { AxiDrawState, HOME, OFF, ON, PEN, UP, } from "./api.js";
+import { AxiDrawControl } from "./control.js";
+import { complete } from "./polyline.js";
 export const DEFAULT_OPTS = {
     logger: new ConsoleLogger("axidraw"),
+    control: new AxiDrawControl(),
+    refresh: 1000,
     unitsPerInch: 25.4,
     stepsPerInch: 2032,
     speed: 4000,
     up: 60,
     down: 30,
-    delayUp: 300,
-    delayDown: 300,
+    delayUp: 150,
+    delayDown: 150,
     preDelay: 0,
     start: [ON, PEN, UP],
     stop: [UP, HOME, OFF],
+    sigint: true,
 };
 export class AxiDraw {
     constructor(opts = {}) {
         this.isConnected = false;
+        this.isPenDown = false;
         this.pos = [0, 0];
+        this.targetPos = [0, 0];
         this.opts = { ...DEFAULT_OPTS, ...opts };
+        this.penLimits = [this.opts.down, this.opts.up];
+    }
+    reset() {
+        zero(this.pos);
+        zero(this.targetPos);
+        return this;
     }
     /**
      * Async function. Attempts to connect to the drawing machine via given
      * (partial) serial port path/name, returns true if successful.
      *
+     * @remarks
+     * First matching port will be used. If `path` is a sting, a port name must
+     * only start with it in order to be considered a match.
+     *
+     * An error is thrown if no matching port could be found.
+     *
      * @param path
      */
-    async connect(path = /^\/dev\/tty\.usbmodem/) {
+    async connect(path = "/dev/tty.usbmodem") {
+        const isStr = isString(path);
         for (let port of await SerialPort.list()) {
-            if (path.test(port.path)) {
+            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.isConnected = true;
-                return true;
+                if (this.opts.sigint) {
+                    this.opts.logger.debug("installing signal handler...");
+                    process.on("SIGINT", this.onSignal.bind(this));
+                }
+                return;
             }
         }
-        return false;
+        ioerror(`no matching device for ${path}`);
     }
     /**
      * Async function. Converts sequence of {@link DrawCommand}s into actual EBB
-     * commands and sends them via configured serial port to the AxiDraw. The
-     * optional `cancel` predicate is checked prior to each individual command
-     * and processing is stopped if that function returns a truthy result.
-     *
-     * Returns number of milliseconds taken for drawing.
+     * 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).
      *
      * @remarks
      * This function is async and if using `await` will only return once all
      * commands have been processed or cancelled.
      *
+     * The `control` implementation/ provided as part of {@link AxiDrawOpts} can
+     * be used to pause, resume or cancel the drawing (see
+     * {@link AxiDrawOpts.control} for details).
+     *
      * Reference:
      * - http://evil-mad.github.io/EggBot/ebb.html
      *
@@ -69,103 +99,152 @@ export class AxiDraw {
      * ```
      *
      * @param commands
-     * @param cancel
+     * @param wrap
      */
-    async draw(commands, cancel) {
+    async draw(commands, wrap = true) {
         assert(this.isConnected, "AxiDraw not yet connected, need to call .connect() first");
         let t0 = Date.now();
-        if (!cancel)
-            cancel = () => false;
-        const { opts: config, pos } = this;
-        const { stepsPerInch, unitsPerInch, speed, preDelay } = config;
-        // scale factor: worldspace units -> motor steps
-        const scale = stepsPerInch / unitsPerInch;
-        let targetPos = [0, 0];
-        let delta = [0, 0];
-        for (let $cmd of commands) {
-            if (cancel())
-                break;
+        const { control, logger, preDelay, refresh } = this.opts;
+        for (let $cmd of wrap ? complete(commands) : commands) {
+            if (control) {
+                let state = control.deref();
+                if (state === AxiDrawState.PAUSE) {
+                    const penDown = this.isPenDown;
+                    if (penDown)
+                        this.penUp();
+                    do {
+                        await delayed(0, refresh);
+                    } while ((state = control.deref()) === AxiDrawState.PAUSE);
+                    if (state === AxiDrawState.CONTINUE && penDown) {
+                        this.penDown();
+                    }
+                }
+                if (state === AxiDrawState.CANCEL) {
+                    this.penUp();
+                    break;
+                }
+            }
             const [cmd, a, b] = $cmd;
             let wait = -1;
             switch (cmd) {
                 case "start":
                 case "stop":
-                    this.draw(config[cmd], cancel);
+                    await this.draw(this.opts[cmd], false);
                     break;
                 case "home":
-                    this.draw([["m", [0, 0]]], cancel);
+                    wait = this.home();
+                    break;
+                case "reset":
+                    this.reset();
                     break;
                 case "on":
-                    this.send("EM,1,1\r");
+                    this.motorsOn();
                     break;
                 case "off":
-                    this.send("EM,0,0\r");
+                    this.motorsOff();
                     break;
                 case "pen":
-                    {
-                        let val = a !== undefined ? a : config.down;
-                        // unit ref:
-                        // https://github.com/evil-mad/AxiDraw-Processing/blob/80d81a8c897b8a1872b0555af52a8d1b5b13cec4/AxiGen1/AxiGen1.pde#L213
-                        this.send(`SC,5,${(7500 + 175 * val) | 0}\r`);
-                        val = b !== undefined ? b : config.up;
-                        this.send(`SC,4,${(7500 + 175 * val) | 0}\r`);
-                        this.send(`SC,10,65535\r`);
-                    }
+                    this.penConfig(a, b);
                     break;
                 case "u":
-                    wait = a !== undefined ? a : config.delayUp;
-                    this.send(`SP,1,${wait}\r`);
+                    wait = this.penUp(a, b);
                     break;
                 case "d":
-                    wait = a !== undefined ? a : config.delayDown;
-                    this.send(`SP,0,${wait}\r`);
+                    wait = this.penDown(a, b);
                     break;
                 case "w":
                     wait = a;
                     break;
                 case "m":
-                    {
-                        mulN2(targetPos, a, scale);
-                        sub2(delta, targetPos, pos);
-                        set2(pos, targetPos);
-                        config.logger.info("target", targetPos, "delta", delta);
-                        const maxAxis = Math.max(...abs2([], delta));
-                        wait = (1000 * maxAxis) / (speed * (b || 1));
-                        this.send(`XM,${wait | 0},${delta[0] | 0},${delta[1] | 0}\r`);
-                    }
+                    wait = this.moveTo(a, b);
                     break;
                 default:
                     unsupported(`unknown command: ${$cmd}`);
             }
             if (wait > 0) {
                 wait = Math.max(0, wait - preDelay);
-                config.logger.debug(`waiting ${wait}ms...`);
+                logger.debug(`waiting ${wait}ms...`);
                 await delayed(0, wait);
             }
         }
         return Date.now() - t0;
     }
     /**
-     * Takes an array of 2D points and converts them into an array of
-     * {@link DrawCommand}s. The optional `speed` factor can be used to control
-     * draw speed (default: 1).
+     * Syntax sugar for drawing a **single** command only, otherwise same as
+     * {@link AxiDraw.draw}.
      *
-     * @remarks
-     * Unless `onlyGeo` is explicitly enabled, the resulting command sequence
-     * will also contain necessary pen up/down commands.
-     *
-     * @param pts
-     * @param speed
-     * @param onlyGeo
+     * @param cmd
      */
-    polyline(pts, speed = 1, onlyGeo = false) {
-        const commands = pts.map((p) => ["m", p, speed]);
-        return onlyGeo
-            ? commands
-            : [UP, commands[0], DOWN, ...commands.slice(1), UP];
+    draw1(cmd) {
+        return this.draw([cmd], false);
+    }
+    motorsOn() {
+        this.send("EM,1,1\r");
+    }
+    motorsOff() {
+        this.send("EM,0,0\r");
+    }
+    penConfig(down, up) {
+        down = down !== undefined ? down : this.opts.down;
+        this.sendPenConfig(5, down);
+        this.penLimits[0] = down;
+        up = up !== undefined ? up : this.opts.up;
+        this.sendPenConfig(4, up);
+        this.penLimits[1] = up;
+        this.send(`SC,10,65535\r`);
+    }
+    penUp(delay, level) {
+        if (level !== undefined)
+            this.sendPenConfig(4, level);
+        delay = delay !== undefined && delay >= 0 ? delay : this.opts.delayUp;
+        this.send(`SP,1,${delay}\r`);
+        this.isPenDown = false;
+        return delay;
+    }
+    penDown(delay, level) {
+        if (level !== undefined)
+            this.sendPenConfig(5, level);
+        delay = delay !== undefined && delay >= 0 ? delay : this.opts.delayDown;
+        this.send(`SP,0,${delay}\r`);
+        this.isPenDown = true;
+        return delay;
+    }
+    moveTo(p, tempo = 1) {
+        const { pos, targetPos, opts } = this;
+        // apply scale factor: worldspace units -> motor steps
+        mulN2(targetPos, p, opts.stepsPerInch / opts.unitsPerInch);
+        const delta = sub2([], targetPos, pos);
+        set2(pos, targetPos);
+        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;
+    }
+    home() {
+        return this.moveTo(ZERO2);
+    }
+    async onSignal() {
+        this.opts.logger.warn(`SIGNINT received, stop drawing...`);
+        this.penUp(0);
+        this.motorsOff();
+        await delayed(0, 100);
+        process.exit(1);
     }
     send(msg) {
         this.opts.logger.debug(msg);
         this.serial.write(msg);
     }
+    /**
+     * Sends pen up/down config
+     *
+     * @remarks
+     * Reference:
+     * - https://github.com/evil-mad/AxiDraw-Processing/blob/80d81a8c897b8a1872b0555af52a8d1b5b13cec4/AxiGen1/AxiGen1.pde#L213
+     *
+     * @param id
+     * @param x
+     */
+    sendPenConfig(id, x) {
+        this.send(`SC,${id},${(7500 + 175 * x) | 0}\r`);
+    }
 }

package/control.d.ts

@@ -0,0 +1,20 @@
+import type { IDeref, IReset } from "@thi.ng/api";
+import { AxiDrawState } from "./api.js";
+/**
+ * Default implementation with easy-to-use API to control the processing of draw
+ * commands via {@link AxiDraw.draw}.
+ *
+ * @remarks
+ * See {@link AxiDrawOpts.control} for further details.
+ */
+export declare class AxiDrawControl implements IDeref<AxiDrawState>, IReset {
+    interval: number;
+    state: AxiDrawState;
+    constructor(interval?: number);
+    deref(): AxiDrawState;
+    reset(): this;
+    pause(): void;
+    resume(): void;
+    cancel(): void;
+}
+//# sourceMappingURL=control.d.ts.map

package/control.js

@@ -0,0 +1,34 @@
+import { AxiDrawState } from "./api.js";
+/**
+ * Default implementation with easy-to-use API to control the processing of draw
+ * commands via {@link AxiDraw.draw}.
+ *
+ * @remarks
+ * See {@link AxiDrawOpts.control} for further details.
+ */
+export class AxiDrawControl {
+    constructor(interval = 1000) {
+        this.interval = interval;
+        this.state = AxiDrawState.CONTINUE;
+    }
+    deref() {
+        return this.state;
+    }
+    reset() {
+        this.state = AxiDrawState.CONTINUE;
+        return this;
+    }
+    pause() {
+        if (this.state === AxiDrawState.CONTINUE) {
+            this.state = AxiDrawState.PAUSE;
+        }
+    }
+    resume() {
+        if (this.state === AxiDrawState.PAUSE) {
+            this.state = AxiDrawState.CONTINUE;
+        }
+    }
+    cancel() {
+        this.state = AxiDrawState.CANCEL;
+    }
+}

package/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./api.js";
 export * from "./axidraw.js";
+export * from "./control.js";
+export * from "./polyline.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,2 +1,4 @@
 export * from "./api.js";
 export * from "./axidraw.js";
+export * from "./control.js";
+export * from "./polyline.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/axidraw",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Minimal AxiDraw plotter/drawing machine controller for Node.js",
   "type": "module",
   "module": "./index.js",
@@ -10,7 +10,7 @@
     "type": "git",
     "url": "https://github.com/thi-ng/umbrella.git"
   },
-  "homepage": "https://github.com/thi-ng/umbrella/tree/master/packages/axidraw#readme",
+  "homepage": "https://github.com/thi-ng/umbrella/tree/develop/packages/axidraw#readme",
   "funding": [
     {
       "type": "github",
@@ -21,7 +21,7 @@
       "url": "https://patreon.com/thing_umbrella"
     }
   ],
-  "author": "Karsten Schmidt <k+npm@thi.ng>",
+  "author": "Karsten Schmidt (https://thi.ng)",
   "license": "Apache-2.0",
   "scripts": {
     "build": "yarn clean && tsc --declaration",
@@ -34,31 +34,33 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.5.1",
-    "@thi.ng/compose": "^2.1.20",
-    "@thi.ng/errors": "^2.2.5",
-    "@thi.ng/logger": "^1.4.4",
-    "@thi.ng/vectors": "^7.5.26",
+    "@thi.ng/api": "^8.6.0",
+    "@thi.ng/compose": "^2.1.21",
+    "@thi.ng/errors": "^2.2.6",
+    "@thi.ng/logger": "^1.4.5",
+    "@thi.ng/vectors": "^7.5.27",
     "serialport": "^10.5.0"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.33.5",
-    "@thi.ng/testament": "^0.3.6",
+    "@microsoft/api-extractor": "^7.33.7",
+    "@thi.ng/testament": "^0.3.7",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
-    "typedoc": "^0.23.20",
-    "typescript": "^4.8.4"
+    "typedoc": "^0.23.22",
+    "typescript": "^4.9.4"
   },
   "keywords": [
+    "2d",
+    "async",
     "axidraw",
+    "driver",
     "geometry",
     "io",
     "logger",
     "node",
-    "plotter",
-    "polygon",
+    "penplotter",
     "polyline",
-    "serial",
+    "serialport",
     "typescript"
   ],
   "publishConfig": {
@@ -80,11 +82,17 @@
     },
     "./axidraw": {
       "default": "./axidraw.js"
+    },
+    "./control": {
+      "default": "./control.js"
+    },
+    "./polyline": {
+      "default": "./polyline.js"
     }
   },
   "thi.ng": {
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "54c5f22520162bac0d58426a3f86ca636e797f71\n"
+  "gitHead": "f445a9cc8022bcdebbf6ff91fd66ced016d72f01\n"
 }

package/polyline.d.ts

@@ -0,0 +1,29 @@
+import type { ReadonlyVec } from "@thi.ng/vectors";
+import { DrawCommand, PolylineOpts } from "./api.js";
+/**
+ * Takes an array of 2D points and yields an iterable of {@link DrawCommand}s.
+ * The drawing behavior can be customized via additional {@link PolylineOpts}
+ * given.
+ *
+ * @remarks
+ * The resulting command sequence assumes the pen is in the **up** position at
+ * the beginning of the line. Each polyline will end with a {@link UP} command.
+ *
+ * @param pts
+ * @param opts
+ */
+export declare function polyline(pts: ReadonlyVec[], opts: Partial<PolylineOpts>): IterableIterator<DrawCommand>;
+/**
+ * Syntax sugar. Takes an iterable of draw commands, adds {@link START} as
+ * prefix and {@link STOP} as suffix. I.e. it creates a "complete" drawing...
+ *
+ * @example
+ * ```ts
+ * [...complete([ ["m", [0, 0]] ])]
+ * // [ ["start"], ["m", [0, 0]], ["stop"] ]
+ * ```
+ *
+ * @param commands
+ */
+export declare function complete(commands: Iterable<DrawCommand>): Generator<DrawCommand, void, undefined>;
+//# sourceMappingURL=polyline.d.ts.map

package/polyline.js

@@ -0,0 +1,54 @@
+import { DOWN, START, STOP, UP } from "./api.js";
+/**
+ * Takes an array of 2D points and yields an iterable of {@link DrawCommand}s.
+ * The drawing behavior can be customized via additional {@link PolylineOpts}
+ * given.
+ *
+ * @remarks
+ * The resulting command sequence assumes the pen is in the **up** position at
+ * the beginning of the line. Each polyline will end with a {@link UP} command.
+ *
+ * @param pts
+ * @param opts
+ */
+export function* polyline(pts, opts) {
+    if (!pts.length)
+        return;
+    const { speed, delayDown, delayUp, down, onlyGeo } = {
+        speed: 1,
+        onlyGeo: false,
+        ...opts,
+    };
+    if (onlyGeo) {
+        for (let p of pts)
+            yield ["m", p, speed];
+        return;
+    }
+    yield ["m", pts[0]];
+    if (down !== undefined)
+        yield ["pen", down];
+    yield delayDown != undefined ? ["d", delayDown] : DOWN;
+    for (let i = 1, n = pts.length; i < n; i++)
+        yield ["m", pts[i], speed];
+    yield delayUp != undefined ? ["u", delayUp] : UP;
+    // reset pen to configured defaults
+    if (down !== undefined)
+        yield ["pen"];
+}
+/**
+ * Syntax sugar. Takes an iterable of draw commands, adds {@link START} as
+ * prefix and {@link STOP} as suffix. I.e. it creates a "complete" drawing...
+ *
+ * @example
+ * ```ts
+ * [...complete([ ["m", [0, 0]] ])]
+ * // [ ["start"], ["m", [0, 0]], ["stop"] ]
+ * ```
+ *
+ * @param commands
+ */
+export function* complete(commands) {
+    yield START;
+    yield* commands;
+    yield STOP;
+}