nova-control-browser 0.0.4 → 0.0.5

package/README.md

@@ -10,7 +10,7 @@ Browser ESM module for controlling the [Creoqode Nova DIY AI Robot](../../README
 | --- | --- |
 | **Chrome or Edge 89+** | required — the Web Serial API is only available in Chromium-based browsers. Firefox and Safari do not support it. |
 | **Node.js 22+** | required for the build toolchain only (`npm run build`). Not needed at runtime in the browser. Download from [nodejs.org](https://nodejs.org). |
-| **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). |
 | **User gesture** | `openNova()` must be called from within a user gesture (e.g. a button click) because the browser requires a transient activation before showing the port picker. |
 
 ---
@@ -65,7 +65,8 @@ Assembles a 5-byte direct servo control packet from the given servo state. Each
 
 ```typescript
 async function openNova (
-  PortOrOptions?:WebSerialPort | WebSerialPortRequestOptions
+  PortOrOptions?:WebSerialPort | WebSerialPortRequestOptions,
+  Options?:       NovaOptions
 ):Promise<NovaController>
 ```
 
@@ -73,6 +74,17 @@ Opens a USB serial port and returns a `NovaController`. Without an argument the
 
 The returned 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 +110,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()` | releases the stream writer lock and 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. 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
@@ -203,6 +241,16 @@ Output is written to `packages/nova-control-browser/dist/`.
 
 ---
 
+## Related packages
+
+| package | description |
+| --- | --- |
+| [`nova-control-node`](../nova-control-node/README.md) | same API for Node.js via the `serialport` package |
+| [`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-browser.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(PortOrOptions?: WebSerialPort | WebSerialPortRequestOptions, 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-browser.js

@@ -53,22 +53,29 @@ async function o(t) {
 		}
 	};
 }
-async function s(e, n) {
-	let i = n?.StepIntervalMs ?? 20, s = await o(e), c = { ...t }, l, u = Promise.resolve();
-	function d(e) {
-		l = {
-			...l ?? c,
+function s(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 c(e, n) {
+	let i = n?.StepIntervalMs ?? 20, c = n?.RampRatio ?? .25, l = await o(e), u = { ...t }, d, f = Promise.resolve();
+	function p(e) {
+		d = {
+			...d ?? u,
 			...e
 		};
 	}
-	async function f() {
-		let e = u;
-		u = (async () => {
+	async function m() {
+		let e = f;
+		f = (async () => {
 			try {
 				await e;
 			} catch {}
-			for (; l != null;) {
-				let e = l, t = !0, n = { ...c };
+			for (; d != null;) {
+				let e = d, t = !0, n = { ...u };
 				for (let a of [
 					"s1",
 					"s2",
@@ -76,48 +83,144 @@ async function s(e, n) {
 					"s4",
 					"s5"
 				]) {
-					let o = e[a] - c[a], s = i > 0 ? r[a] * i : Infinity;
-					Math.abs(o) > s ? (n[a] = c[a] + Math.sign(o) * s, t = !1) : n[a] = e[a];
+					let o = e[a] - u[a], s = i > 0 ? r[a] * i : Infinity;
+					Math.abs(o) > s ? (n[a] = u[a] + Math.sign(o) * s, t = !1) : n[a] = e[a];
 				}
-				t && (l = void 0), c = { ...n }, await s.write(a(n)), t || await new Promise((e) => setTimeout(e, i));
+				t && (d = void 0), u = { ...n }, await l.write(a(n)), t || await new Promise((e) => setTimeout(e, i));
+			}
+		})(), await f;
+	}
+	async function h(e, t) {
+		let n = f;
+		f = (async () => {
+			try {
+				await n;
+			} catch {}
+			let r = { ...u }, o = i > 0 ? Math.max(1, Math.round(t / i)) : 1;
+			d = void 0;
+			for (let t = 1; t <= o; t++) {
+				let n = s(t / o, c), d = { ...u };
+				for (let t of Object.keys(e)) d[t] = Math.round(r[t] + (e[t] - r[t]) * n);
+				u = d, await l.write(a(d)), t < o && await new Promise((e) => setTimeout(e, i));
 			}
-		})(), await u;
+		})(), await f;
 	}
 	return {
-		async home() {
-			d({ ...t }), await f();
+		async home(e) {
+			e != null && e > 0 ? await h({ ...t }, e) : (p({ ...t }), await m());
 		},
-		async shiftHeadTo(e) {
-			d({ s1: e }), await f();
+		async shiftHeadTo(e, t) {
+			t != null && t > 0 ? await h({ s1: e }, t) : (p({ s1: e }), await m());
 		},
-		async rollHeadTo(e) {
-			d({ s2: e }), await f();
+		async rollHeadTo(e, t) {
+			t != null && t > 0 ? await h({ s2: e }, t) : (p({ s2: e }), await m());
 		},
-		async pitchHeadTo(e) {
-			d({ s3: e }), await f();
+		async pitchHeadTo(e, t) {
+			t != null && t > 0 ? await h({ s3: e }, t) : (p({ s3: e }), await m());
 		},
-		async liftHeadTo(e) {
-			d({ s5: e }), await f();
+		async liftHeadTo(e, t) {
+			t != null && t > 0 ? await h({ s5: e }, t) : (p({ s5: e }), await m());
 		},
-		async rotateBodyTo(e) {
-			d({ s4: e }), await f();
+		async rotateBodyTo(e, t) {
+			t != null && t > 0 ? await h({ s4: e }, t) : (p({ s4: e }), await m());
+		},
+		async moveTo(e, t) {
+			t != null && t > 0 ? await h(e, t) : (p(e), await m());
 		},
 		get State() {
-			return structuredClone(l ?? c);
+			return structuredClone(d ?? u);
 		},
 		set State(e) {
-			l = {
-				...c,
+			d = {
+				...u,
 				...e
 			};
 		},
 		async sendServoState() {
-			await f();
+			await m();
 		},
 		destroy() {
-			s.destroy();
+			l.destroy();
 		}
 	};
 }
+async function l(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 { e as BaudRate, t as HomePosition, n as SafeRange, r as ServoSpeed, a as buildDirectPacket, s as openNova };
+export { e as BaudRate, t as HomePosition, n as SafeRange, r as ServoSpeed, a as buildDirectPacket, c as openNova, l as runScript };

package/package.json

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