feat(axidraw): major updates/additions

- 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
thi-ng · Dec 8, 2022 · eb41c28 · eb41c28
1 parent 2447c5f
commit eb41c28
Show file tree

Hide file tree

Showing 6 changed files with 305 additions and 75 deletions.
diff --git a/packages/axidraw/package.json b/packages/axidraw/package.json
@@ -80,6 +80,9 @@
 		},
 		"./axidraw": {
 			"default": "./axidraw.js"
+		},
+		"./utils": {
+			"default": "./utils.js"
 		}
 	},
 	"thi.ng": {

diff --git a/packages/axidraw/src/api.ts b/packages/axidraw/src/api.ts
@@ -1,3 +1,4 @@
+import type { IDeref } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 import type { ReadonlyVec } from "@thi.ng/vectors";
 
@@ -10,17 +11,21 @@ export type StopCommand = ["stop"];
 /** Return plotter to initial XY position */
 export type HomeCommand = ["home"];
 
+/** Reset curr position as home (0,0) */
+export type ResetCommand = ["reset"];
+
 /** Turn XY motors on/off */
 export type MotorCommand = ["on" | "off"];
 
 /** Pen config, min/down position, max/up position (in %) */
 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 type PenUpDownCommand = ["u" | "d", number?];
+export type PenUpDownCommand = ["u" | "d", number?, number?];
 
 /**
  * Move to abs pos (in worldspace coords, default mm), optional speed factor
@@ -35,12 +40,16 @@ 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.
@@ -76,13 +85,13 @@ export interface AxiDrawOpts {
 	/**
 	 * Delay after pen up
 	 *
-	 * @defaultValue 300
+	 * @defaultValue 150
 	 */
 	delayUp: number;
 	/**
 	 * Delay after pen down
 	 *
-	 * @defaultValue 300
+	 * @defaultValue 150
 	 */
 	delayDown: number;
 	/**
@@ -107,6 +116,33 @@ 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 const START: StartCommand = ["start"];
@@ -115,6 +151,8 @@ export const STOP: StopCommand = ["stop"];
 
 export const HOME: HomeCommand = ["home"];
 
+export const RESET: ResetCommand = ["reset"];
+
 export const PEN: PenConfigCommand = ["pen"];
 
 export const UP: PenUpDownCommand = ["u"];
@@ -124,3 +162,22 @@ export const DOWN: PenUpDownCommand = ["d"];
 export const ON: MotorCommand = ["on"];
 
 export const OFF: MotorCommand = ["off"];
+
+/**
+ * FSM state enum for (interactive) control for processing of drawing commands.
+ * See {@link AxiDraw.draw} and {@link AxiDrawControl} for details.
+ */
+export enum AxiDrawState {
+	/**
+	 * Draw command processing can continue as normal.
+	 */
+	CONTINUE,
+	/**
+	 * Draw command processing is suspended indefinitely.
+	 */
+	PAUSE,
+	/**
+	 * Draw command processing is cancelled.
+	 */
+	CANCEL,
+}