nova-control-node 0.0.4 → 0.0.6

package/README.md

@@ -11,7 +11,7 @@ Node.js ESM module for controlling the [Creoqode Nova DIY AI Robot](../../README
 | **Node.js 22+** | required at runtime and for the build toolchain. Download from [nodejs.org](https://nodejs.org). |
 | **`serialport` ≥ 12** | runtime dependency — installed automatically with this package. Requires a C++ build toolchain (`node-gyp`) on first install if no pre-built binary is available for your platform. |
 | **USB serial permissions** | on Linux, add your user to the `dialout` group (`sudo usermod -aG dialout $USER`) and re-login. On macOS and Windows no extra configuration is normally required. |
-| **Arduino sketch** | the matching `Nova_SerialController.ino` sketch must be flashed to the robot's Arduino board (baud rate 9600, 8N1). |
+| **Arduino sketch** | the matching [`Nova_SerialController.ino`](../../Nova_SerialController.ino) sketch must be flashed to the robot's Arduino board (baud rate 9600, 8N1). |
 
 ---
 
@@ -64,15 +64,32 @@ Assembles a 5-byte direct servo control packet from the given servo state. Each
 ### `openNova`
 
 ```typescript
-async function openNova (PortPath:string):Promise<NovaController>
+async function openNova (
+  PortPath: string,
+  Rate?:    number,
+  Options?: NovaOptions
+):Promise<NovaController>
 ```
 
 Opens the USB serial port at `PortPath` and returns a `NovaController`.
 
 `PortPath` examples: `/dev/ttyACM0` or `/dev/ttyUSB0` on Linux/macOS, `COM3` on Windows.
 
+An optional second argument `Rate` overrides the default baud rate of 9600. An optional third argument `Options` configures the timing behaviour (see `NovaOptions` below).
+
 The returned promise rejects if the port cannot be opened (e.g. wrong path, permission denied, or device not connected). On success the promise resolves after the 2-second Arduino reset delay that follows every port open.
 
+### `NovaOptions`
+
+```typescript
+interface NovaOptions {
+  StepIntervalMs?: number   // ms between interpolation steps; default 20 (50 Hz); 0 = instant
+  RampRatio?:      number   // fraction of withinMS used for each ramp phase; default 0.25; range 0–0.499
+}
+```
+
+Controls how servo movements are executed when `withinMS` is specified on a movement call. `StepIntervalMs` sets the interval between intermediate packets. `RampRatio` controls what fraction of the total movement time is used for ramp-up and ramp-down phases (each); the remainder is constant speed. For example `RampRatio: 0.25` means 25% ramp-up, 50% constant speed, 25% ramp-down.
+
 ### `NovaController`
 
 ```typescript
@@ -98,15 +115,41 @@ interface NovaController {
 | `pitchHeadTo(Degrees)` | sets s3 — head up `> 110°`, down toward `40°` |
 | `liftHeadTo(Degrees)` | sets s5 — secondary head up/down, range `20°`–`150°` |
 | `rotateBodyTo(Degrees)` | sets s4 — rotates the entire body around the Z-axis |
+| `moveTo(Target, withinMS?)` | moves the servos listed in `Target` to their target angles; with `withinMS`, uses the trapezoidal profile |
 | `State` (get) | returns a deep copy of the pending state if any, else the last-sent state |
 | `State` (set) | replaces any pending entry with `Update` merged onto the *last-sent* state (not onto pending); flush with `sendServoState()` |
 | `sendServoState()` | flushes any pending state update to the Arduino |
 | `destroy()` | closes the serial port |
 
+All movement methods (`home`, `shiftHeadTo`, `rollHeadTo`, `pitchHeadTo`, `liftHeadTo`, `rotateBodyTo`, and `moveTo`) accept an optional `withinMS?:number` final argument. When provided, the method executes a smooth timed movement that completes in exactly the given number of milliseconds, using the trapezoidal velocity profile configured by `RampRatio` in `NovaOptions`. Without `withinMS`, the method uses the existing constant-speed ramp (governed by `StepIntervalMs`).
+
 `State` reflects what was *sent* (or is pending to be sent) to the Arduino, not the physical servo position — there is no read-back channel in the protocol.
 
 Sends are serialised internally: concurrent method calls and `sendServoState()` calls never overlap on the wire. Each write awaits both `Port.write` and `Port.drain` before resolving, ensuring the 5-byte packet is fully flushed to the OS serial buffer. Named methods such as `shiftHeadTo()` *accumulate* changes on top of whatever is already pending; the `State` setter instead *replaces* the pending entry, starting fresh from the last-sent state.
 
+### `runScript`
+
+```typescript
+async function runScript (Nova:NovaController, Script:string):Promise<void>
+```
+
+Parses and executes a multi-line movement script against an already-open controller. Commands are executed sequentially, one per line. Blank lines and lines starting with `#` are ignored.
+
+Supported commands:
+
+| command | description |
+| --- | --- |
+| `home` | send all servos to home positions |
+| `shift-to <deg>` | s1 — head forward / back |
+| `roll-to <deg>` | s2 — head CW / CCW |
+| `pitch-to <deg>` | s3 — head up / down |
+| `rotate-to <deg>` | s4 — body Z-axis rotation |
+| `lift-to <deg>` | s5 — secondary head axis |
+| `move [key val …]` | set multiple servos atomically (e.g. `move shift-to 100 rotate-to 120`) |
+| `wait <ms>` | pause for the given number of milliseconds |
+
+Throws a descriptive error containing the line number if an unknown command or invalid argument is encountered.
+
 ### Types
 
 ```typescript
@@ -198,6 +241,16 @@ Output is written to `packages/nova-control-node/dist/`.
 
 ---
 
+## Related packages
+
+| package | description |
+| --- | --- |
+| [`nova-control-browser`](../nova-control-browser/README.md) | same API for the browser via the Web Serial API |
+| [`nova-control-command`](../nova-control-command/README.md) | CLI — one-shot commands, interactive REPL, and script files |
+| [`nova-control-mcp-server`](../nova-control-mcp-server/README.md) | MCP server — lets an AI assistant control the robot |
+
+---
+
 ## License
 
 [MIT License](../../LICENSE.md) © Andreas Rozek

package/dist/nova-control-node.d.ts

@@ -8,12 +8,13 @@ export declare const HomePosition: Readonly<ServoState>;
 
 /**** NovaController ****/
 export declare interface NovaController {
-    home(): Promise<void>;
-    shiftHeadTo(Degrees: number): Promise<void>;
-    rollHeadTo(Degrees: number): Promise<void>;
-    pitchHeadTo(Degrees: number): Promise<void>;
-    liftHeadTo(Degrees: number): Promise<void>;
-    rotateBodyTo(Degrees: number): Promise<void>;
+    home(withinMS?: number): Promise<void>;
+    shiftHeadTo(Angle: number, withinMS?: number): Promise<void>;
+    rollHeadTo(Angle: number, withinMS?: number): Promise<void>;
+    pitchHeadTo(Angle: number, withinMS?: number): Promise<void>;
+    liftHeadTo(Angle: number, withinMS?: number): Promise<void>;
+    rotateBodyTo(Angle: number, withinMS?: number): Promise<void>;
+    moveTo(Target: ServoUpdate, withinMS?: number): Promise<void>;
     get State(): ServoState;
     set State(Update: ServoUpdate);
     sendServoState(): Promise<void>;
@@ -23,11 +24,15 @@ export declare interface NovaController {
 /**** NovaOptions ****/
 export declare interface NovaOptions {
     StepIntervalMs?: number;
+    RampRatio?: number;
 }
 
 /**** openNova — factory ****/
 export declare function openNova(PortPath: string, Rate?: number, Options?: NovaOptions): Promise<NovaController>;
 
+/**** runScript — execute a multi-line script of movement commands ****/
+export declare function runScript(Nova: NovaController, Script: string): Promise<void>;
+
 /**** SafeRange ****/
 export declare const SafeRange: Readonly<Record<ServoKey, [number, number]>>;
 

package/dist/nova-control-node.js

@@ -59,22 +59,29 @@ async function s(t, n) {
 		}
 	};
 }
-async function c(e, r = t, a) {
-	let c = a?.StepIntervalMs ?? 20, l = await s(e, r), u = { ...n }, d, f = Promise.resolve();
-	function p(e) {
-		d = {
-			...d ?? u,
+function c(e, t) {
+	let n = Math.min(.499, Math.max(0, t)), r = 1 / (1 - n);
+	if (e <= n) return r * e * e / (2 * n);
+	if (e <= 1 - n) return r * (e - n / 2);
+	let i = 1 - e;
+	return 1 - r * i * i / (2 * n);
+}
+async function l(e, r = t, a) {
+	let l = a?.StepIntervalMs ?? 20, u = a?.RampRatio ?? .25, d = await s(e, r), f = { ...n }, p, m = Promise.resolve();
+	function h(e) {
+		p = {
+			...p ?? f,
 			...e
 		};
 	}
-	async function m() {
-		let e = f;
-		f = (async () => {
+	async function g() {
+		let e = m;
+		m = (async () => {
 			try {
 				await e;
 			} catch {}
-			for (; d != null;) {
-				let e = d, t = !0, n = { ...u };
+			for (; p != null;) {
+				let e = p, t = !0, n = { ...f };
 				for (let r of [
 					"s1",
 					"s2",
@@ -82,48 +89,144 @@ async function c(e, r = t, a) {
 					"s4",
 					"s5"
 				]) {
-					let a = e[r] - u[r], o = c > 0 ? i[r] * c : Infinity;
-					Math.abs(a) > o ? (n[r] = u[r] + Math.sign(a) * o, t = !1) : n[r] = e[r];
+					let a = e[r] - f[r], o = l > 0 ? i[r] * l : Infinity;
+					Math.abs(a) > o ? (n[r] = f[r] + Math.sign(a) * o, t = !1) : n[r] = e[r];
 				}
-				t && (d = void 0), u = { ...n }, await l.write(o(n)), t || await new Promise((e) => setTimeout(e, c));
+				t && (p = void 0), f = { ...n }, await d.write(o(n)), t || await new Promise((e) => setTimeout(e, l));
+			}
+		})(), await m;
+	}
+	async function _(e, t) {
+		let n = m;
+		m = (async () => {
+			try {
+				await n;
+			} catch {}
+			let r = { ...f }, i = l > 0 ? Math.max(1, Math.round(t / l)) : 1;
+			p = void 0;
+			for (let t = 1; t <= i; t++) {
+				let n = c(t / i, u), a = { ...f };
+				for (let t of Object.keys(e)) a[t] = Math.round(r[t] + (e[t] - r[t]) * n);
+				f = a, await d.write(o(a)), t < i && await new Promise((e) => setTimeout(e, l));
 			}
-		})(), await f;
+		})(), await m;
 	}
 	return {
-		async home() {
-			p({ ...n }), await m();
+		async home(e) {
+			e != null && e > 0 ? await _({ ...n }, e) : (h({ ...n }), await g());
 		},
-		async shiftHeadTo(e) {
-			p({ s1: e }), await m();
+		async shiftHeadTo(e, t) {
+			t != null && t > 0 ? await _({ s1: e }, t) : (h({ s1: e }), await g());
 		},
-		async rollHeadTo(e) {
-			p({ s2: e }), await m();
+		async rollHeadTo(e, t) {
+			t != null && t > 0 ? await _({ s2: e }, t) : (h({ s2: e }), await g());
 		},
-		async pitchHeadTo(e) {
-			p({ s3: e }), await m();
+		async pitchHeadTo(e, t) {
+			t != null && t > 0 ? await _({ s3: e }, t) : (h({ s3: e }), await g());
 		},
-		async liftHeadTo(e) {
-			p({ s5: e }), await m();
+		async liftHeadTo(e, t) {
+			t != null && t > 0 ? await _({ s5: e }, t) : (h({ s5: e }), await g());
 		},
-		async rotateBodyTo(e) {
-			p({ s4: e }), await m();
+		async rotateBodyTo(e, t) {
+			t != null && t > 0 ? await _({ s4: e }, t) : (h({ s4: e }), await g());
+		},
+		async moveTo(e, t) {
+			t != null && t > 0 ? await _(e, t) : (h(e), await g());
 		},
 		get State() {
-			return structuredClone(d ?? u);
+			return structuredClone(p ?? f);
 		},
 		set State(e) {
-			d = {
-				...u,
+			p = {
+				...f,
 				...e
 			};
 		},
 		async sendServoState() {
-			await m();
+			await g();
 		},
 		destroy() {
-			l.destroy();
+			d.destroy();
 		}
 	};
 }
+async function u(e, t) {
+	let n = t.split("\n");
+	for (let t = 0; t < n.length; t++) {
+		let r = n[t].trim(), i = t + 1;
+		if (r === "" || r.startsWith("#")) continue;
+		let a = r.split(/\s+/), o = a[0].toLowerCase();
+		switch (!0) {
+			case o === "home":
+				await e.home();
+				break;
+			case o === "shift-to": {
+				let t = Number(a[1]);
+				if (isNaN(t)) throw Error(`line ${i}: shift-to requires a numeric angle, got '${a[1]}'`);
+				await e.shiftHeadTo(t);
+				break;
+			}
+			case o === "roll-to": {
+				let t = Number(a[1]);
+				if (isNaN(t)) throw Error(`line ${i}: roll-to requires a numeric angle, got '${a[1]}'`);
+				await e.rollHeadTo(t);
+				break;
+			}
+			case o === "pitch-to": {
+				let t = Number(a[1]);
+				if (isNaN(t)) throw Error(`line ${i}: pitch-to requires a numeric angle, got '${a[1]}'`);
+				await e.pitchHeadTo(t);
+				break;
+			}
+			case o === "rotate-to": {
+				let t = Number(a[1]);
+				if (isNaN(t)) throw Error(`line ${i}: rotate-to requires a numeric angle, got '${a[1]}'`);
+				await e.rotateBodyTo(t);
+				break;
+			}
+			case o === "lift-to": {
+				let t = Number(a[1]);
+				if (isNaN(t)) throw Error(`line ${i}: lift-to requires a numeric angle, got '${a[1]}'`);
+				await e.liftHeadTo(t);
+				break;
+			}
+			case o === "move": {
+				let t = {};
+				for (let e = 1; e < a.length; e += 2) {
+					let n = a[e].toLowerCase(), r = Number(a[e + 1]);
+					if (isNaN(r)) throw Error(`line ${i}: '${n}' requires a numeric angle, got '${a[e + 1]}'`);
+					switch (n) {
+						case "shift-to":
+							t.s1 = r;
+							break;
+						case "roll-to":
+							t.s2 = r;
+							break;
+						case "pitch-to":
+							t.s3 = r;
+							break;
+						case "rotate-to":
+							t.s4 = r;
+							break;
+						case "lift-to":
+							t.s5 = r;
+							break;
+						default: throw Error(`line ${i}: unknown move argument '${n}'`);
+					}
+				}
+				if (Object.keys(t).length === 0) throw Error(`line ${i}: move requires at least one servo argument`);
+				e.State = t, await e.sendServoState();
+				break;
+			}
+			case o === "wait": {
+				let e = Number(a[1]);
+				if (isNaN(e) || e < 0) throw Error(`line ${i}: wait requires a non-negative number in ms, got '${a[1]}'`);
+				await new Promise((t) => setTimeout(t, e));
+				break;
+			}
+			default: throw Error(`line ${i}: unknown command '${o}'`);
+		}
+	}
+}
 //#endregion
-export { t as BaudRate, n as HomePosition, r as SafeRange, i as ServoSpeed, o as buildDirectPacket, c as openNova };
+export { t as BaudRate, n as HomePosition, r as SafeRange, i as ServoSpeed, o as buildDirectPacket, l as openNova, u as runScript };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nova-control-node",
   "description": "Control a NOVA DIY Artificial Intelligence Robot by Creoqode from Node.js",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "type": "module",
   "keywords": [
     "nova",