@thi.ng/axidraw 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Change Log
+
+- **Last updated**: 2022-12-06T17:16:38Z
+- **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org/) for commit guidelines.
+
+**Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
+and/or version bumps of transitive dependencies.
+
+## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/axidraw@0.1.0) (2022-12-06)
+
+#### 🚀 Features
+
+- import as new pkg ([cc43e84](https://github.com/thi-ng/umbrella/commit/cc43e84))
+- arbitrary unit support, measure draw time ([32e3212](https://github.com/thi-ng/umbrella/commit/32e3212))
+  - add AxiDrawOpts.unitsPerInch to support any worldspace units
+  - remove paperSize opt
+  - add command constants for better mem use
+  - update AxiDraw.draw() to measure & return time taken
+  - add/update doc strings

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,170 @@
+<!-- This file is generated - DO NOT EDIT! -->
+
+# ![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)
+
+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)
+  - [Serial port support](#serial-port-support)
+- [Status](#status)
+- [Installation](#installation)
+- [Dependencies](#dependencies)
+- [API](#api)
+- [Authors](#authors)
+- [License](#license)
+
+## About
+
+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/)
+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.
+
+### Declarative vs. imperative
+
+Due to AxiDraw's lack of G-Code support, most other available AxiDraw support
+libraries are providing only a purely imperative API to control the machine. In
+contrast, this package utilizes a more declarative approach, also very much
+following the pattern of other packages in the
+[thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo, which allows
+(geometry) data to be inspected, augmented, converted/transformed, serialized up
+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
+[thi.ng/geom](https://github.com/thi-ng/umbrella/tree/develop/packages/geom)
+packages provides numerous other 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).
+
+### 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
+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!
+
+## Status
+
+**ALPHA** - bleeding edge / work-in-progress
+
+[Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Baxidraw%5D+in%3Atitle)
+
+## Installation
+
+```bash
+yarn add @thi.ng/axidraw
+```
+
+ES module import:
+
+```html
+<script type="module" src="https://cdn.skypack.dev/@thi.ng/axidraw"></script>
+```
+
+[Skypack documentation](https://docs.skypack.dev/)
+
+For Node.js REPL:
+
+```text
+# with flag only for < v16
+node --experimental-repl-await
+
+> const axidraw = await import("@thi.ng/axidraw");
+```
+
+Package sizes (brotli'd, pre-treeshake): ESM: 1.01 KB
+
+## Dependencies
+
+- [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/compose](https://github.com/thi-ng/umbrella/tree/develop/packages/compose)
+- [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
+- [@thi.ng/logger](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)
+- [@thi.ng/vectors](https://github.com/thi-ng/umbrella/tree/develop/packages/vectors)
+- [serialport](https://github.com/thi-ng/umbrella/tree/develop/packages/undefined)
+
+## API
+
+[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";
+
+(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/);
+// 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 ],
+//   ...
+// ]
+
+// convert to drawing commands (w/ default opts)
+const path = axi.polyline(verts)
+// [
+//   [ 'u' ],
+//   [ 'm', [ 130, 50 ], 1 ],
+//   [ 'd' ],
+//   [ 'm', [ 129.8356568610482, 53.1358538980296 ], 1 ],
+//   [ 'm', [ 129.34442802201417, 56.23735072453278 ], 1 ],
+//   ...
+// ]
+
+// draw/send seq of commands (incl. start/end sequence, configurable)
+await axi.draw([["start"], ...path, ["stop"]]);
+
+})();
+```
+
+## Authors
+
+Karsten Schmidt
+
+If this project contributes to an academic publication, please cite it as:
+
+```bibtex
+@misc{thing-axidraw,
+  title = "@thi.ng/axidraw",
+  author = "Karsten Schmidt",
+  note = "https://thi.ng/axidraw",
+  year = 2022
+}
+```
+
+## License
+
+&copy; 2022 Karsten Schmidt // Apache Software License 2.0

package/api.d.ts

@@ -0,0 +1,101 @@
+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"];
+/** Stop command sequence (configurable via {@link AxiDrawOpts}) */
+export declare type StopCommand = ["stop"];
+/** Return plotter to initial XY position */
+export declare type HomeCommand = ["home"];
+/** Turn XY motors on/off */
+export declare type MotorCommand = ["on" | "off"];
+/** Pen config, min/down position, max/up position (in %) */
+export declare type PenConfigCommand = ["pen", number?, number?];
+/**
+ * Pen up/down, optional delay (in ms), if omitted values used from
+ * {@link AxiDrawOpts}.
+ */
+export declare type PenUpDownCommand = ["u" | "d", number?];
+/**
+ * Move to abs pos (in worldspace coords, default mm), optional speed factor
+ * (default: 1)
+ */
+export declare 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 interface AxiDrawOpts {
+    /**
+     * Conversion factor from geometry worldspace units to inches.
+     * Default units are millimeters.
+     *
+     * @defaultValue 25.4
+     */
+    unitsPerInch: number;
+    /**
+     * Hardware resolution (steps / inch)
+     *
+     * @defaultValue 2032
+     */
+    stepsPerInch: number;
+    /**
+     * Steps per second
+     *
+     * @defaultValue 4000
+     */
+    speed: number;
+    /**
+     * Up position (%)
+     *
+     * @defaultValue 60
+     */
+    up: number;
+    /**
+     * Up position (%)
+     *
+     * @defaultValue 30
+     */
+    down: number;
+    /**
+     * Delay after pen up
+     *
+     * @defaultValue 300
+     */
+    delayUp: number;
+    /**
+     * Delay after pen down
+     *
+     * @defaultValue 300
+     */
+    delayDown: number;
+    /**
+     * Time in ms to subtract from actual delay time until next command
+     *
+     * @defaultValue 0
+     */
+    preDelay: number;
+    /**
+     * Sequence for `start` {@link DrawCommand}
+     *
+     * @defaultValue `[ON, PEN, UP]`
+     */
+    start: DrawCommand[];
+    /**
+     * Sequence for `end` {@link DrawCommand}
+     *
+     * @defaultValue `[UP, HOME, OFF]`
+     */
+    stop: DrawCommand[];
+    /**
+     * Logger instance
+     */
+    logger: ILogger;
+}
+export declare const START: StartCommand;
+export declare const STOP: StopCommand;
+export declare const HOME: HomeCommand;
+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;
+//# sourceMappingURL=api.d.ts.map

package/api.js

@@ -0,0 +1,8 @@
+export const START = ["start"];
+export const STOP = ["stop"];
+export const HOME = ["home"];
+export const PEN = ["pen"];
+export const UP = ["u"];
+export const DOWN = ["d"];
+export const ON = ["on"];
+export const OFF = ["off"];

package/axidraw.d.ts

@@ -0,0 +1,64 @@
+import type { Fn0 } 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 {
+    serial: SerialPort;
+    opts: AxiDrawOpts;
+    isConnected: boolean;
+    pos: Vec;
+    constructor(opts?: Partial<AxiDrawOpts>);
+    /**
+     * Async function. Attempts to connect to the drawing machine via given
+     * (partial) serial port path/name, returns true if successful.
+     *
+     * @param path
+     */
+    connect(path?: RegExp): Promise<boolean>;
+    /**
+     * 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.
+     *
+     * @remarks
+     * This function is async and if using `await` will only return once all
+     * commands have been processed or cancelled.
+     *
+     * Reference:
+     * - http://evil-mad.github.io/EggBot/ebb.html
+     *
+     * @example
+     * ```ts
+     * // execute start sequence, draw a triangle, then exec stop sequence
+     * axi.draw([
+     *   ["start"],
+     *   ...axi.polyline([[50,50], [100,50], [75, 100], [50,50]]),
+     *   ["stop"]
+     * ]);
+     * ```
+     *
+     * @param commands
+     * @param cancel
+     */
+    draw(commands: Iterable<DrawCommand>, cancel?: Fn0<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).
+     *
+     * @remarks
+     * Unless `onlyGeo` is explicitly enabled, the resulting command sequence
+     * will also contain necessary pen up/down commands.
+     *
+     * @param pts
+     * @param speed
+     * @param onlyGeo
+     */
+    polyline(pts: ReadonlyVec[], speed?: number, onlyGeo?: boolean): DrawCommand[];
+    protected send(msg: string): void;
+}
+//# sourceMappingURL=axidraw.d.ts.map

package/axidraw.js

@@ -0,0 +1,171 @@
+import { delayed } from "@thi.ng/compose";
+import { assert, unsupported } from "@thi.ng/errors";
+import { ConsoleLogger } from "@thi.ng/logger";
+import { abs2, mulN2, set2, sub2 } from "@thi.ng/vectors";
+import { SerialPort } from "serialport";
+import { DOWN, HOME, OFF, ON, PEN, UP, } from "./api.js";
+export const DEFAULT_OPTS = {
+    logger: new ConsoleLogger("axidraw"),
+    unitsPerInch: 25.4,
+    stepsPerInch: 2032,
+    speed: 4000,
+    up: 60,
+    down: 30,
+    delayUp: 300,
+    delayDown: 300,
+    preDelay: 0,
+    start: [ON, PEN, UP],
+    stop: [UP, HOME, OFF],
+};
+export class AxiDraw {
+    constructor(opts = {}) {
+        this.isConnected = false;
+        this.pos = [0, 0];
+        this.opts = { ...DEFAULT_OPTS, ...opts };
+    }
+    /**
+     * Async function. Attempts to connect to the drawing machine via given
+     * (partial) serial port path/name, returns true if successful.
+     *
+     * @param path
+     */
+    async connect(path = /^\/dev\/tty\.usbmodem/) {
+        for (let port of await SerialPort.list()) {
+            if (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;
+            }
+        }
+        return false;
+    }
+    /**
+     * 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.
+     *
+     * @remarks
+     * This function is async and if using `await` will only return once all
+     * commands have been processed or cancelled.
+     *
+     * Reference:
+     * - http://evil-mad.github.io/EggBot/ebb.html
+     *
+     * @example
+     * ```ts
+     * // execute start sequence, draw a triangle, then exec stop sequence
+     * axi.draw([
+     *   ["start"],
+     *   ...axi.polyline([[50,50], [100,50], [75, 100], [50,50]]),
+     *   ["stop"]
+     * ]);
+     * ```
+     *
+     * @param commands
+     * @param cancel
+     */
+    async draw(commands, cancel) {
+        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 [cmd, a, b] = $cmd;
+            let wait = -1;
+            switch (cmd) {
+                case "start":
+                case "stop":
+                    this.draw(config[cmd], cancel);
+                    break;
+                case "home":
+                    this.draw([["m", [0, 0]]], cancel);
+                    break;
+                case "on":
+                    this.send("EM,1,1\r");
+                    break;
+                case "off":
+                    this.send("EM,0,0\r");
+                    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`);
+                    }
+                    break;
+                case "u":
+                    wait = a !== undefined ? a : config.delayUp;
+                    this.send(`SP,1,${wait}\r`);
+                    break;
+                case "d":
+                    wait = a !== undefined ? a : config.delayDown;
+                    this.send(`SP,0,${wait}\r`);
+                    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`);
+                    }
+                    break;
+                default:
+                    unsupported(`unknown command: ${$cmd}`);
+            }
+            if (wait > 0) {
+                wait = Math.max(0, wait - preDelay);
+                config.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).
+     *
+     * @remarks
+     * Unless `onlyGeo` is explicitly enabled, the resulting command sequence
+     * will also contain necessary pen up/down commands.
+     *
+     * @param pts
+     * @param speed
+     * @param onlyGeo
+     */
+    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];
+    }
+    send(msg) {
+        this.opts.logger.debug(msg);
+        this.serial.write(msg);
+    }
+}

package/index.d.ts

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

package/index.js

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

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@thi.ng/axidraw",
+  "version": "0.1.0",
+  "description": "Minimal AxiDraw plotter/drawing machine controller for Node.js",
+  "type": "module",
+  "module": "./index.js",
+  "typings": "./index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thi-ng/umbrella.git"
+  },
+  "homepage": "https://github.com/thi-ng/umbrella/tree/master/packages/axidraw#readme",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/postspectacular"
+    },
+    {
+      "type": "patreon",
+      "url": "https://patreon.com/thing_umbrella"
+    }
+  ],
+  "author": "Karsten Schmidt <k+npm@thi.ng>",
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "yarn clean && tsc --declaration",
+    "clean": "rimraf '*.js' '*.d.ts' '*.map' doc",
+    "doc": "typedoc --excludePrivate --excludeInternal --out doc src/index.ts",
+    "doc:ae": "mkdir -p .ae/doc .ae/temp && api-extractor run --local --verbose",
+    "doc:readme": "yarn doc:stats && tools:readme",
+    "doc:stats": "tools:module-stats",
+    "pub": "yarn npm publish --access public",
+    "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",
+    "serialport": "^10.5.0"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.33.5",
+    "@thi.ng/testament": "^0.3.6",
+    "rimraf": "^3.0.2",
+    "tools": "^0.0.1",
+    "typedoc": "^0.23.20",
+    "typescript": "^4.8.4"
+  },
+  "keywords": [
+    "axidraw",
+    "geometry",
+    "io",
+    "logger",
+    "node",
+    "plotter",
+    "polygon",
+    "polyline",
+    "serial",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "./*.js",
+    "./*.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "default": "./index.js"
+    },
+    "./api": {
+      "default": "./api.js"
+    },
+    "./axidraw": {
+      "default": "./axidraw.js"
+    }
+  },
+  "thi.ng": {
+    "status": "alpha",
+    "year": 2022
+  },
+  "gitHead": "54c5f22520162bac0d58426a3f86ca636e797f71\n"
+}