Public: anyone can read this; the crew can change it.

Migrated from github.com/Trevato/SO-ARM100

workbenchthis machine

TOP: the joint sliders follow your finger and stay where you put them - no snapping back #77

Parked opened this in answer to
Closed without merging

vesper/arm:vesper/64-top-the-joint-sliders-follow-your-finger → main 7 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
17 files changed +750 −44
Software/README.md +24 −3
@@ -490,9 +490,9 @@ the app's own page.
490490 drives, your place in the line, the time left, the turn's one button, and
491491 the red **Stop**. Stop is there whenever you drive, and for the owner. Below
492492 that is a sheet with tabs at the bottom edge: **Chat**, **Queue**,
493 **Controls** (only on your turn, and it opens by itself when your turn
494 starts) and **Admin** (the owner: the room, the safe zone, the trims,
495 metrics and 3D calibration).
493 **Controls** (always there; disabled with the reason beside them when you
494 cannot drive, and it opens by itself when your turn starts) and **Admin**
495 (the owner: the room, the safe zone, the trims, metrics and 3D calibration).
496496
497497 - Controls, phone upright: a row of chips (J1 base, J2 shoulder, J3 elbow,
498498 J4 wrist, J5 roll, Grip) picks one joint. One tall lever drives it: push
@@ -533,6 +533,27 @@ metrics and 3D calibration).
533533 (`src/ui/reach.js`), and the server checks every frame against the zone
534534 as usual. Below the joystick come the joint sliders with hold-to-jog −/+,
535535 the poses, and the rest.
536 - Sliders and the 3D model: every move is streamed live while you drag (at
537 most 30 frames a second, the latest value winning, `src/ui/frames.js`).
538 A joint you move is yours (`src/ui/joint-hold.js`): the pose updates never
539 pull it back while you hold it, nor after you let go while the arm is still
540 getting there. On a slider a blue mark is your target and an amber mark is
541 where the arm really is; on the model a faint amber ghost is the real arm.
542 The arm server moves a stream at its speed limit and holds wherever the arm
543 is when the stream ends, so the page keeps sending the targets the arm has
544 not reached (every 250 ms, inside the 1 s dead-man) and ends the stream once
545 it is there, or 2 s after it stopped closing in. Idle, a slider is the arm.
546 These modules, and the model's ghost (`src/ui/ghost.js`), load after the
547 first view; until then the controls say "Loading the controls…". The page
548 is sent without the whole-line comments of its script (`src/page.ts`).
549 - When you cannot drive, the controls say why in words
550 (`src/ui/drive-gate.js`): "Join the queue to drive", "It's not your turn",
551 "Arm offline - reconnecting", "Stopped - resume first". A refused stream
552 says the same. The owner can always drive: their first command takes
553 control. With an arm server named, the simulation shown while it is offline
554 is never driven. The terminal (`src/tty.ts`) does not drive the arm at all:
555 it chats, joins and leaves the line, and the owner's `/end` and `/mute`
556 work there as before, so nothing about driving changes on it.
536557 - Chat: the page follows the visual viewport. The keyboard shrinks the
537558 sheet and the view, and never covers the box or the last message.
538559 Long-press a message (or right-click it) to delete it, or mute or ban its
Software/so101/src/admin-relay.test.ts +38
@@ -2,10 +2,14 @@ import { afterEach, expect, test } from "bun:test";
22 import { mkdtempSync, rmSync } from "node:fs";
33 import { tmpdir } from "node:os";
44 import { join } from "node:path";
5 import WebSocket from "ws";
56 import { validateChange } from "./admin.ts";
7 import { FeetechBus } from "./bus.ts";
8 import { FakeBus } from "./fake-bus.ts";
69 import { sign } from "./identity.ts";
710 import { Lobby } from "./lobby.ts";
811 import { startRelay, type RunningRelay } from "./relay.ts";
12 import { startServer } from "./server.ts";
913
1014 const KEY = "k".repeat(64);
1115 const later = Date.now() + 600_000;
@@ -102,3 +106,37 @@ test("reading /link never changes anything; the arm server switches when the set
102106 expect(after.host).toBe("127.0.0.1:1");
103107 expect(await (await fetch(`${base}/link`)).json()).toEqual(after);
104108 });
109
110 test("the owner drives with no queue and no turn: their first command takes control; anyone else is refused (#64)", async () => {
111 dir = mkdtempSync(join(tmpdir(), "so101-admin-relay-"));
112 const sim = await startServer(new FeetechBus(new FakeBus([1, 2, 3, 4, 5, 6])), { host: "127.0.0.1", port: 0, posesFile: join(dir, "poses.json") });
113 try {
114 lobby = new Lobby({ identityKey: KEY, adminFile: join(dir, "admin.json") });
115 relay = await startRelay({ port: 0, simulation: `http://127.0.0.1:${sim.port}`, lobby });
116 const base = `http://127.0.0.1:${relay.port}`;
117 const move = (headers: Record<string, string>) => fetch(`${base}/move`, { method: "POST", headers, body: '{"targets":{"1":2100},"speed":4000}' });
118 const bob = await move(as("bob", "user"));
119 expect(bob.status).toBe(403); // nobody's turn is bob's
120 await bob.body?.cancel();
121 expect(lobby.turns.driver).toBeNull();
122 const owner = await move(as("trevato", "admin"));
123 expect(owner.status).toBe(200);
124 await owner.body?.cancel();
125 expect(lobby.turns.driver?.id).toBe("id-trevato");
126
127 // Someone else's turn: the owner's stream is still taken, and the turn is theirs from then on.
128 lobby.turns.leave("id-trevato");
129 lobby.takeControl({ id: "id-bob", name: "bob", owner: false });
130 expect(lobby.turns.driver?.id).toBe("id-bob");
131 const ws = new WebSocket(`ws://127.0.0.1:${relay.port}/follow`, { headers: as("trevato", "admin") });
132 const opened = await new Promise<string>((r) => {
133 ws.once("open", () => r("open"));
134 ws.once("close", (code: number) => r(`closed ${code}`));
135 });
136 expect(opened).toBe("open");
137 expect(lobby.turns.driver?.id).toBe("id-trevato");
138 ws.close();
139 } finally {
140 await Promise.race([sim.close(), new Promise((r) => setTimeout(r, 500))]);
141 }
142 });
Software/so101/src/conflict-markers.test.ts added +18
@@ -0,0 +1,18 @@
1 import { expect, test } from "bun:test";
2 import { readdirSync, readFileSync, statSync } from "node:fs";
3 import { join } from "node:path";
4
5 /** Every text file of the app and its README: a merge that left its markers behind fails here, not in a reader's eyes. */
6 function files(dir: string): string[] {
7 return readdirSync(dir).flatMap((name) => {
8 if (name === "node_modules" || name.startsWith(".")) return [];
9 const path = join(dir, name);
10 return statSync(path).isDirectory() ? files(path) : /\.(ts|js|html|md|json)$/.test(name) ? [path] : [];
11 });
12 }
13
14 test("no merge conflict markers in the app's sources or its README", () => {
15 const root = join(import.meta.dir, "..");
16 const marked = [...files(root), join(root, "..", "README.md")].filter((f) => /^(<{7}|={7}|>{7})( |$)/m.test(readFileSync(f, "utf8")));
17 expect(marked).toEqual([]);
18 });
Software/so101/src/lobby.ts +2
@@ -150,6 +150,8 @@ export class Lobby {
150150 if (this.local) return null;
151151 if (!who) return { status: 401, error: "join to take control" };
152152 if (this.barred(who, req ? visitor(req) : null)) return { status: 403, error: "you are banned: you can still watch" };
153 // The owner always drives: a command from them takes control first, as Take control would (logged; any turn ends).
154 if (who.owner && !this.turns.isDriver(who.id)) this.takeControl(who);
153155 if (!this.turns.isDriver(who.id)) {
154156 const d = this.turns.driver;
155157 return { status: 403, error: d ? `${d.name} has control; take control to join the queue` : "take control first" };
Software/so101/src/page.test.ts added +22
@@ -0,0 +1,22 @@
1 import { expect, test } from "bun:test";
2 import { readFileSync } from "node:fs";
3 import { join } from "node:path";
4 import { servedPage } from "./page.ts";
5
6 const script = (html: string) => /<script type="module">([\s\S]*?)<\/script>/.exec(html)![1]!;
7
8 test("the served page's script is the same program as viewer.html's, without its whole-line comments", () => {
9 const source = readFileSync(join(import.meta.dir, "viewer.html"), "utf8");
10 const served = servedPage(source, "0123456789ab");
11 expect(served.length).toBeLessThan(source.length);
12 expect(script(served)).not.toMatch(/^[ \t]*\/\//m);
13 // The transpiler drops comments itself: the same output means no code, string or template literal was touched.
14 const t = new Bun.Transpiler({ loader: "js" });
15 expect(t.transformSync(script(served).replaceAll("/ui/0123456789ab/", "/ui/__VERSION__/"))).toBe(t.transformSync(script(source)));
16 expect(served).not.toContain("__VERSION__");
17 });
18
19 test("only the module script loses comment lines; a line of code keeps its comment; the rest of the page is as written", () => {
20 const html = '<p>\n // shown text\n</p>\n<script type="module">\n // gone\n const a = 1; // kept\n const u = "http://x/ui/__VERSION__/m.js";\n</script>\n';
21 expect(servedPage(html, "v1")).toBe('<p>\n // shown text\n</p>\n<script type="module">\n const a = 1; // kept\n const u = "http://x/ui/v1/m.js";\n</script>\n');
22 });
Software/so101/src/page.ts added +15
@@ -0,0 +1,15 @@
1 /**
2 * The browser app as sent (src/viewer.html): its own modules under their content's version, and the whole-line
3 * comments of its module script left out. Those are for people reading the source; a phone on 4G would download
4 * about 4 KB of them (gzipped) on every first visit for nothing. Comments at the end of a line of code stay.
5 */
6
7 const OPEN = '<script type="module">';
8
9 /** The page with its module script's whole-line `//` comments removed and `/ui/__VERSION__/` made `/ui/<version>/`. */
10 export function servedPage(html: string, version: string): string {
11 const start = html.indexOf(OPEN);
12 const end = start < 0 ? -1 : html.indexOf("</script>", start);
13 const page = start < 0 || end < 0 ? html : html.slice(0, start) + html.slice(start, end).replace(/^[ \t]*\/\/.*\n/gm, "") + html.slice(end);
14 return page.replaceAll("/ui/__VERSION__/", `/ui/${version}/`);
15 }
Software/so101/src/relay.test.ts +84
@@ -10,6 +10,8 @@ import { FeetechBus } from "./bus.ts";
1010 import { CameraHub } from "./cameras.ts";
1111 import { FakeBus } from "./fake-bus.ts";
1212 import { OFFLINE_FRAME } from "./offline-frame.ts";
13 import { Frames } from "./ui/frames.js";
14 import { ARRIVED_TICKS, KEEP_MS, idle, press, release, settle, slide, unfinished, type Hold } from "./ui/joint-hold.js";
1315 import { parseRemote, sameOrigin, startRelay, type Remote, type RunningRelay } from "./relay.ts";
1416 import { startServer, type RunningServer } from "./server.ts";
1517
@@ -49,6 +51,11 @@ const joints = async (base: string) => ((await (await fetch(`${base}/status`)).j
4951 const source = async (base: string) => ((await (await fetch(`${base}/status`)).json()) as { source: string }).source;
5052 const link = async (base: string) => (await (await fetch(`${base}/link`)).json()) as { mode: string; host: string | null; problem: string | null };
5153
54 /** Until the relay's link to the arm server is live (3 s at most). */
55 async function live(base: string) {
56 for (const until = Date.now() + 3000; Date.now() < until; await sleep(20)) if ((await link(base)).mode === "live") return;
57 throw new Error("the link never went live");
58 }
5259 /** The link's timings at 1/100: retries after 5–40 ms, offline after 600 ms (60 s). */
5360 const FAST = { backoffMs: [5, 10, 20, 40], staleMs: 60, offlineAfterMs: 600, connectTimeoutMs: 50, pollEveryMs: 10 };
5461
@@ -203,6 +210,75 @@ describe("relay", () => {
203210 expect(await (await fetch(`${base}/camera/1/state`)).json()).toEqual({ ok: true });
204211 });
205212
213 test("a slider drag through the relay moves the arm during the drag, not only at the end (#64)", async () => {
214 remote = await arm([1, 2, 6]);
215 relay = await startRelay({ port: 0, simulation: simBase, remote: remoteAt(remote.port) });
216 const at = async () => ((await (await fetch(`http://127.0.0.1:${remote!.port}/status`)).json()) as { joints: Array<{ id: number; position: number }> }).joints.find((j) => j.id === 1)!.position;
217 await live(`http://127.0.0.1:${relay.port}`); // the relay drives only over a live link
218 const start = await at();
219 const ws = new WebSocket(`ws://127.0.0.1:${relay.port}/follow`);
220 await new Promise((r, j) => (ws.once("open", r), ws.once("error", j)));
221 const pacer = new Frames((data) => ws.send(data));
222 // An input every 10 ms for 0.9 s, 4 ticks each: what a finger on the slider sends, paced to 30 Hz.
223 let target = start;
224 for (let i = 0; i < 90; i++) {
225 target += 4;
226 pacer.send({ 1: target });
227 await sleep(10);
228 }
229 const midway = await at(); // the finger is still down
230 expect(midway - start).toBeGreaterThan(150);
231 await sleep(600);
232 expect(Math.abs((await at()) - target)).toBeLessThanOrEqual(5); // and settles on the last value, within the governor's deadband
233 ws.close();
234 });
235
236 test("a slider flicked and let go stays where it was put: the arm gets there under the 90°/s limit and the 1 s dead-man (#64, broken since f5d990e)", async () => {
237 // The arm server as it runs: its own dead-man and speed limits, not the suite's fast watchdog.
238 const real = await startServer(new FeetechBus(new FakeBus([1, 2, 6])), { host: "127.0.0.1", port: 0, ids: [1, 2, 6], posesFile: join(mkdtempSync(join(tmpdir(), "so101-relay-")), "poses.json") });
239 try {
240 relay = await startRelay({ port: 0, simulation: simBase, remote: remoteAt(real.port) });
241 await live(`http://127.0.0.1:${relay.port}`);
242 const at = async () => ((await (await fetch(`http://127.0.0.1:${real.port}/status`)).json()) as { joints: Array<{ id: number; position: number }> }).joints.find((j) => j.id === 1)!.position;
243 /** A flick of 1200 ticks in 0.3 s and let go; `keep` is whether the page keeps sending until the arm is there. */
244 const flick = async (keep: boolean) => {
245 const start = await at();
246 const ws = new WebSocket(`ws://127.0.0.1:${relay!.port}/follow`);
247 await new Promise((r, j) => (ws.once("open", r), ws.once("error", j)));
248 const pacer = new Frames((data) => ws.send(data));
249 let hold: Hold = press(idle(), start);
250 let target = start;
251 for (let i = 0; i < 30; i++) {
252 target += 40;
253 hold = slide(hold, target, performance.now());
254 pacer.send({ 1: target });
255 await sleep(10);
256 }
257 hold = release(hold, performance.now());
258 if (keep) {
259 // The page's pump: every KEEP_MS, poll the pose, and send again what has not been reached.
260 for (;;) {
261 await sleep(KEEP_MS);
262 const pose = await at(), now = performance.now();
263 hold = settle(hold, pose, now);
264 const left = unfinished(new Map([[1, hold]]), { 1: pose }, now);
265 if (!Object.keys(left).length) break;
266 pacer.send(left);
267 }
268 } else await sleep(250); // what the page did: close the stream 250 ms after letting go
269 ws.close();
270 await sleep(1500);
271 return { target, end: await at() };
272 };
273 const before = await flick(false);
274 expect(before.target - before.end).toBeGreaterThan(300); // the arm holds where it got to, far short of the slider
275 const after = await flick(true);
276 expect(Math.abs(after.end - after.target)).toBeLessThanOrEqual(ARRIVED_TICKS);
277 } finally {
278 await shut(real);
279 }
280 }, 20000);
281
206282 test("set, with the camera down: the offline picture within 3 s while the arm stays live", async () => {
207283 remote = await arm([1, 2, 6]);
208284 hang = createTcpServer(() => {}); // a camera port that accepts and never answers
@@ -238,6 +314,14 @@ describe("relay", () => {
238314 expect((await link(base)).mode).toBe("offline");
239315 expect(await joints(base)).toBe(6);
240316 expect(await source(base)).toStartWith("simulated: offline, ");
317 // The simulation is shown, never driven: its numbers are not the arm's (#64).
318 const move = await fetch(`${base}/move`, { method: "POST", body: '{"targets":{"1":2000}}' });
319 expect(move.status).toBe(503);
320 expect(((await move.json()) as { error: string }).error).toContain("offline");
321 const ws = new WebSocket(`ws://127.0.0.1:${relay.port}/follow`);
322 const closed = await new Promise<{ code: number; why: string }>((r) => ws.on("close", (code, why) => r({ code, why: String(why) })));
323 expect(closed).toEqual({ code: 1013, why: "reconnecting to the arm…" });
324 expect((await (await fetch(`${simBase}/status`)).json() as { driving: string | null }).driving).toBeNull();
241325 });
242326
243327 test("the forge's egress proxy cannot reach the arm: its reason is the one the page and /status give", async () => {
Software/so101/src/relay.ts +10 −3
@@ -6,13 +6,15 @@
66 * (src/arm-link.ts) and answers every /status from it. When that connection drops, the relay never jumps to the
77 * simulation: it says "reconnecting" and keeps showing the last known pose while it retries. Driving is suspended
88 * (commands are refused and stream frames are not passed on, so the arm server's dead-man holds the arm); a stop
9 * still goes through. Only after 60 s down does the page go over to the simulation, labelled offline.
9 * still goes through. Only after 60 s down does the page go over to the simulation, labelled offline, and it is only
10 * shown: with an arm server named, nothing drives the simulation (commands answer 503, /follow closes 1013).
1011 * The page itself, the 3D model and the vendored scripts always come from here.
1112 * Inside a forge cell the only way out is the egress proxy (src/egress.ts): fetch finds it on its own, the WebSocket
1213 * to the arm server is told it, and when the proxy refuses or cannot dial, its reason is the one /link and /status give.
1314 *
1415 * With a lobby (src/lobby.ts), anyone may watch but only the person whose turn it is may command the arm: every
15 * request that is not a read, and the /follow stream, is refused for anyone else before it reaches an arm. When a
16 * request that is not a read, and the /follow stream, is refused for anyone else before it reaches an arm; the owner's
17 * first command takes control (src/lobby.ts), so the owner can always drive. When a
1618 * turn ends, that person's streams are closed and whatever they started is stopped. The driver and any admin may hit
1719 * the emergency stop (/estop) and /stop; only an admin may clear the stop or change the settings.
1820 *
@@ -622,6 +624,11 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
622624 // Who stopped or cleared the arm is the relay's to say, never the page's; every other command is held to the admin's speed cap.
623625 const raw = reading || route === "POST /estop" || route === "POST /estop/clear" ? undefined : await readBody(req);
624626 const body = reading ? undefined : !raw ? Buffer.from(JSON.stringify({ by })) : lobby ? capBody(url.pathname, raw, lobby.maxSpeedPercent) : raw;
627 // With an arm server named, the simulation shown while it is offline is only to look at: no command drives it.
628 if (remote && mode() === "offline" && !reading && !STOPS.has(route) && !LOCAL.test(url.pathname)) {
629 machine.note("clamp", "not passed on", { route, why: `the arm at ${remote.host} is offline` });
630 return json(res, 503, { error: `the arm at ${remote.host} is offline; ${RECONNECTING}…`, reconnecting: true });
631 }
625632 const logged = !reading && !LOCAL.test(url.pathname);
626633 if (logged) machine.note("sent", route, { by });
627634 const answered = (status: number) => logged && machine.note("received", route, { status });
@@ -765,7 +772,7 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
765772 void (async () => {
766773 let arm: WebSocket;
767774 let base: string;
768 if (remote && mode() === "reconnecting") {
775 if (remote && mode() !== "live") {
769776 return wss.handleUpgrade(req, socket, head, (browser) => browser.close(1013, `${RECONNECTING}…`));
770777 }
771778 try {
Software/so101/src/server.test.ts +12
@@ -169,6 +169,18 @@ describe("viewer page", () => {
169169 expect((await fetch(`${base}/ui/${version}/..%2Fserver.ts`)).status).toBe(404);
170170 });
171171
172 test("the page's script parses, and every module it imports from /ui/ is served (#64)", async () => {
173 const page = await (await fetch(`${base}/`)).text();
174 const script = /<script type="module">([\s\S]*?)<\/script>/.exec(page)?.[1];
175 expect(script).toBeDefined();
176 // A name declared twice (an import shadowing one of the page's own) stops the whole page: nothing drives.
177 expect(() => new Bun.Transpiler({ loader: "js" }).transformSync(script!)).not.toThrow();
178 // Imported up front or when needed: every one is there.
179 const modules = [...new Set([...script!.matchAll(/"(\/ui\/[0-9a-f]{12}\/[\w-]+\.js)"/g)].map((m) => m[1]!))];
180 for (const name of ["joint-hold", "drive-gate", "ghost", "frames"]) expect(modules.some((m) => m.endsWith(`/${name}.js`))).toBe(true);
181 for (const path of modules) expect((await fetch(`${base}${path}`)).status).toBe(200);
182 });
183
172184 test("is laid out for a phone: tabs under the thumb, an E-stop beside the status, room for the forge pill", async () => {
173185 const page = await (await fetch(`${base}/`)).text();
174186 for (const tab of ["chat", "queue", "controls", "admin"]) expect(page).toContain(`data-tab="${tab}"`);
Software/so101/src/server.ts +2 −1
@@ -63,6 +63,7 @@ import { assertPoseName, parsePoseFile, serializePoseFile, type PoseFile } from
6363 import { JOINTS, registerName, STS3215, ticksToDegrees } from "./sts3215.ts";
6464 import { largestStep, parseTrajectory, serializeTrajectory, type Trajectory } from "./trajectory.ts";
6565 import { accelRegister, bound, DEFAULT_SAFETY, Governor, jointBounds, motionLimits, parseFrame, SAFETY_KEYS, SafetyError, TICKS_PER_DEGREE, validateSafety, type SafetySettings } from "./safety.ts";
66 import { servedPage } from "./page.ts";
6667
6768 export interface ServerOptions {
6869 host?: string;
@@ -697,7 +698,7 @@ export async function startServer(bus: FeetechBus, options: ServerOptions = {}):
697698 case "GET /":
698699 case "GET /index.html":
699700 res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
700 return res.end(readFileSync(viewerPath, "utf8").replaceAll("/ui/__VERSION__/", `/ui/${uiVersion()}/`)); // read per request: a viewer change deploys with rsync alone
701 return res.end(servedPage(readFileSync(viewerPath, "utf8"), uiVersion())); // read per request: a viewer change deploys with rsync alone
701702 case "GET /leader-map.js":
702703 return file(res, join(here, "leader-map.js"), "no-cache");
703704 case "GET /status":
Software/so101/src/ui/drive-gate.js added +59
@@ -0,0 +1,59 @@
1 /**
2 * Whether this page may drive the arm now, and when not, why in words a person reads next to the controls.
3 * Plain ESM, served at /ui/ and imported by the tests. The server refuses the same things (src/lobby.ts,
4 * src/relay.ts, src/server.ts); this only says so before a slider moves, and turns a refusal into the same words.
5 */
6
7 export const WHY = {
8 join: "Join the queue to drive",
9 turn: "It's not your turn",
10 offline: "Arm offline - reconnecting",
11 stopped: "Stopped - resume first",
12 banned: "You are banned: you can still watch",
13 room: "Connecting to the room…",
14 };
15
16 /**
17 * @param {{
18 * relayed: boolean,
19 * link: string | null,
20 * reconnecting?: boolean,
21 * estop?: unknown,
22 * hello: { signin: boolean, you: { id: string, owner?: boolean } | null, banned?: boolean } | null,
23 * state: { driver: { id: string } | null, queue?: Array<{ id: string }> } | null,
24 * }} s
25 * `link` is /link's mode: "live", "reconnecting", "offline" (an arm server is named and the page shows the simulation)
26 * or "simulated" (none is named). `reconnecting` is /status saying so.
27 * @returns {string | null} null when the page may drive
28 */
29 export function driveBlock(s) {
30 // With an arm server named, the simulation's numbers are never driven: a link that is not live is a link to wait for.
31 if (s.relayed && (s.link === "reconnecting" || s.link === "offline")) return WHY.offline;
32 if (s.reconnecting) return WHY.offline;
33 if (s.estop) return WHY.stopped;
34 if (!s.relayed) return null;
35 const h = s.hello;
36 if (!h) return WHY.room;
37 if (!h.signin) return null; // a run on one's own machine: everyone drives
38 const you = h.you;
39 if (!you) return WHY.join;
40 if (h.banned) return WHY.banned;
41 if (you.owner) return null; // the owner always drives: the server hands them control on their first command
42 if (s.state?.driver?.id === you.id) return null;
43 return s.state?.queue?.some((x) => x.id === you.id) ? WHY.turn : WHY.join;
44 }
45
46 /**
47 * The words for a refused /follow stream (its close code and reason) or command (its HTTP status and error).
48 * @param {number} code a WebSocket close code (4000 + HTTP status for a refused handshake) or an HTTP status
49 * @param {string} [reason]
50 */
51 export function refusalWords(code, reason = "") {
52 const status = code >= 4000 && code < 5000 ? code - 4000 : code;
53 if (status === 423 || /emergency stop/i.test(reason)) return WHY.stopped;
54 if (code === 1013 && /reconnect|did not take|went away/i.test(reason)) return WHY.offline;
55 if (status === 503 || /reconnecting|offline/i.test(reason)) return WHY.offline;
56 if (status === 401) return WHY.join;
57 if (status === 403) return /banned/i.test(reason) ? WHY.banned : WHY.turn;
58 return reason || "the arm is busy";
59 }
Software/so101/src/ui/drive-gate.test.ts added +46
@@ -0,0 +1,46 @@
1 import { expect, test } from "bun:test";
2 import { WHY, driveBlock, refusalWords } from "./drive-gate.js";
3
4 const me = { id: "u-me", owner: false };
5 const owner = { id: "u-owner", owner: true };
6 const live = { relayed: true, link: "live" };
7 const hello = (you: typeof me | null, more = {}) => ({ signin: true, you, ...more });
8
9 test("only the person whose turn it is drives; the others are told why", () => {
10 expect(driveBlock({ ...live, hello: hello(me), state: { driver: { id: "u-me" } } })).toBeNull();
11 expect(driveBlock({ ...live, hello: hello(null), state: { driver: null } })).toBe(WHY.join);
12 expect(driveBlock({ ...live, hello: hello(me), state: { driver: { id: "u-bob" }, queue: [] } })).toBe(WHY.join);
13 expect(driveBlock({ ...live, hello: hello(me), state: { driver: { id: "u-bob" }, queue: [{ id: "u-me" }] } })).toBe(WHY.turn);
14 expect(driveBlock({ ...live, hello: hello(me, { banned: true }), state: { driver: null } })).toBe(WHY.banned);
15 expect(driveBlock({ ...live, hello: null, state: null })).toBe(WHY.room);
16 });
17
18 test("the owner drives with no queue and no turn, whoever else has control", () => {
19 expect(driveBlock({ ...live, hello: hello(owner), state: { driver: null, queue: [] } })).toBeNull();
20 expect(driveBlock({ ...live, hello: hello(owner), state: { driver: { id: "u-bob" } } })).toBeNull();
21 });
22
23 test("with an arm server named, a link that is down or a simulated fallback disables the controls: reconnecting", () => {
24 const driving = { hello: hello(owner), state: { driver: { id: "u-owner" } } };
25 expect(driveBlock({ relayed: true, link: "offline", ...driving })).toBe(WHY.offline);
26 expect(driveBlock({ relayed: true, link: "reconnecting", ...driving })).toBe(WHY.offline);
27 expect(driveBlock({ relayed: true, link: "live", reconnecting: true, ...driving })).toBe(WHY.offline);
28 expect(driveBlock({ relayed: true, link: "simulated", ...driving })).toBeNull(); // no arm server named: the simulation is the arm
29 });
30
31 test("an emergency stop disables them until it is cleared; a run on one's own machine drives otherwise", () => {
32 expect(driveBlock({ ...live, estop: { by: "x" }, hello: hello(owner), state: { driver: null } })).toBe(WHY.stopped);
33 expect(driveBlock({ relayed: false, link: null, hello: null, state: null })).toBeNull();
34 expect(driveBlock({ ...live, hello: { signin: false, you: null }, state: null })).toBeNull();
35 });
36
37 test("a refused stream or command shows why in words", () => {
38 expect(refusalWords(4401, "join to take control")).toBe(WHY.join);
39 expect(refusalWords(4403, "bob has control; take control to join the queue")).toBe(WHY.turn);
40 expect(refusalWords(4403, "you are banned: you can still watch")).toBe(WHY.banned);
41 expect(refusalWords(4423, "emergency stop (x): the arm holds until an admin clears it")).toBe(WHY.stopped);
42 expect(refusalWords(1013, "reconnecting to the arm…")).toBe(WHY.offline);
43 expect(refusalWords(503, "the arm at 10.0.0.1:8101 is offline; reconnecting to the arm…")).toBe(WHY.offline);
44 expect(refusalWords(1000, "your turn ended")).toBe("your turn ended");
45 expect(refusalWords(1013)).toBe("the arm is busy");
46 });
Software/so101/src/ui/frames.test.ts +34
@@ -46,3 +46,37 @@ describe("Frames", () => {
4646 expect(wire).toEqual([]);
4747 });
4848 });
49
50 test("a slider drag streams targets live, during the drag, at most 30 a second, and the last value is never lost (#64)", () => {
51 let now = 0;
52 const timers: Array<{ at: number; fn: () => void }> = [];
53 const sent: Array<{ at: number; frame: Record<string, number> }> = [];
54 const frames = new Frames((data) => sent.push({ at: now, frame: JSON.parse(data) }), { later: (fn, ms) => timers.push({ at: now + ms, fn }), cancel: () => {} });
55 const advance = (ms: number) => {
56 const end = now + ms;
57 for (;;) {
58 timers.sort((a, b) => a.at - b.at);
59 if (!timers[0] || timers[0].at > end) break;
60 const t = timers.shift()!;
61 now = t.at;
62 t.fn();
63 }
64 now = end;
65 };
66 // An input every 8 ms (a 120 Hz trackpad) for a second, 2 ticks each.
67 let value = 2000;
68 for (let t = 0; t < 1000; t += 8) {
69 value += 2;
70 frames.send({ 1: value });
71 advance(8);
72 }
73 const releasedAt = now;
74 advance(100);
75 const during = sent.filter((s) => s.at < releasedAt);
76 // A slot opens at the first send after the last one went: with an input every 8 ms that is every 40 ms, 25 a second.
77 expect(during.length).toBeGreaterThanOrEqual(24); // frames all through the drag, not one at the end
78 expect(during.length).toBeLessThanOrEqual(31);
79 for (let i = 1; i < sent.length; i++) expect(sent[i]!.at - sent[i - 1]!.at).toBeGreaterThanOrEqual(33);
80 expect(sent.at(-1)!.frame[1]).toBe(value);
81 expect(during.at(-1)!.frame[1]).toBeGreaterThan(value - 20); // the arm hears the finger within about a slot
82 });
Software/so101/src/ui/ghost.js added +28
@@ -0,0 +1,28 @@
1 /**
2 * The real arm, drawn faint over the 3D model while a joint the person moved is ahead of it (src/ui/joint-hold.js).
3 * Plain ESM, loaded with three.js. The ghost is a clone of the model sharing its geometry; its meshes never take a
4 * ray, so the drag controls always grab the model itself.
5 */
6
7 /**
8 * The ghost of `robot`: `ghost` when it is already that robot's, else a new one added beside it (and the old removed).
9 * @param {any} THREE
10 * @param {any} robot a URDFRobot in the scene
11 * @param {any} ghost the ghost so far, or null
12 */
13 export function ghostFor(THREE, robot, ghost) {
14 if (ghost?.userData.of === robot) return ghost;
15 ghost?.parent?.remove(ghost);
16 const g = robot.clone();
17 g.userData.of = robot;
18 const material = new THREE.MeshBasicMaterial({ color: 0xd29922, transparent: true, opacity: 0.3, depthWrite: false });
19 g.traverse((/** @type {any} */ o) => {
20 o.raycast = () => {};
21 if (o.isMesh) {
22 o.material = material;
23 o.castShadow = o.receiveShadow = false;
24 }
25 });
26 robot.parent.add(g);
27 return g;
28 }
Software/so101/src/ui/joint-hold.js added +106
@@ -0,0 +1,106 @@
1 /**
2 * A joint held at the person's target: while a slider or a joint of the 3D model is held, and after it is let go
3 * until the arm gets there. Plain ESM, served at /ui/ and imported by the tests. A hold is plain data; every
4 * function returns a new one. The slider and the model read the same hold, so both show the same intent.
5 *
6 * The arm server moves a stream's joints no faster than its speed limit (90°/s by default, src/safety.ts), and
7 * the hosted link takes ~0.4 s a command, so the pose the page polls is always behind the finger. Setting the
8 * control from it while held, or the instant it is let go, is what made it snap back. The arm's real pose is drawn
9 * as a separate mark (`markerAt`) and, on the model, as a ghost.
10 *
11 * Letting go does not end the person's intent: the arm is still on its way, and the arm server holds wherever it is
12 * when the stream ends or falls silent (the dead-man). So the page keeps re-sending the targets that are not
13 * reached yet (`unfinished`) and ends the stream once every joint has arrived, or has stopped closing in for
14 * SETTLE_MS (a jam, a joint limit, the safety zone): the arm then stays where it got to and the control follows it.
15 *
16 * A hold begins on pointerdown or on the first `input` (a keyboard, or a browser that cancelled the pointer mid-drag)
17 * and ends on pointerup, pointercancel or `change`. An `input` after that is a fresh target and settles like a release.
18 */
19
20 /** After a release, the target is kept this long after the arm last closed in on it. */
21 export const SETTLE_MS = 2000;
22 /** Within this many ticks of the target, the arm has arrived and the control follows it again. */
23 export const ARRIVED_TICKS = 15;
24 /** How often the unfinished targets are sent again: well inside the arm server's dead-man (1 s, src/safety.ts). */
25 export const KEEP_MS = 250;
26 /** Closer by at least this many ticks counts as closing in (a servo at rest jitters by a tick or two). */
27 const PROGRESS_TICKS = 3;
28
29 /** @typedef {{ held: boolean, target: number | null, since: number | null, best: number }} Hold */
30
31 /** @param {unknown} v @returns {v is number} */
32 const known = (v) => typeof v === "number" && Number.isFinite(v);
33
34 /** @returns {Hold} */
35 export const idle = () => ({ held: false, target: null, since: null, best: Infinity });
36
37 /** The finger (or the mouse) went down on the control, whose value is `value`. @param {Hold} hold @param {number} value @returns {Hold} */
38 export function press(hold, value) {
39 return { held: true, target: known(value) ? value : hold.target, since: null, best: Infinity };
40 }
41
42 /** The control's value changed under the person's hand. @param {Hold} hold @param {number} value @param {number} now @returns {Hold} */
43 export function slide(hold, value, now) {
44 if (!known(value)) return hold;
45 return hold.held ? { ...hold, target: value } : { held: false, target: value, since: now, best: Infinity };
46 }
47
48 /** Let go. @param {Hold} hold @param {number} now @returns {Hold} */
49 export function release(hold, now) {
50 return hold.held ? { ...hold, held: false, since: now, best: Infinity } : hold;
51 }
52
53 /** Whether the arm is at the target. @param {Hold} hold @param {number | null | undefined} pose */
54 export function arrived(hold, pose) {
55 return hold.target !== null && known(pose) && Math.abs(pose - hold.target) <= ARRIVED_TICKS;
56 }
57
58 /**
59 * Whether the person's target still owns the control: held, or let go with the arm not there yet and still
60 * closing in (it last did less than SETTLE_MS ago). @param {Hold} hold @param {number | null | undefined} pose @param {number} now @returns {boolean}
61 */
62 export function owns(hold, pose, now) {
63 if (hold.target === null) return false;
64 if (hold.held) return true;
65 if (hold.since === null || now - hold.since >= SETTLE_MS) return false;
66 return !arrived(hold, pose);
67 }
68
69 /** The value the control shows: the target while it owns it, else the arm's pose (null when neither is known). @param {Hold} hold @param {number | null | undefined} pose @param {number} now @returns {number | null} */
70 export function shown(hold, pose, now) {
71 if (owns(hold, pose, now)) return hold.target;
72 return known(pose) ? pose : hold.target;
73 }
74
75 /**
76 * The hold once a pose has been seen: a release whose arm closed in restarts the clock; one that arrived or stopped
77 * closing in for SETTLE_MS is forgotten. @param {Hold} hold @param {number | null | undefined} pose @param {number} now @returns {Hold}
78 */
79 export function settle(hold, pose, now) {
80 if (hold.target === null || hold.held) return hold;
81 let next = hold;
82 if (known(pose)) {
83 const d = Math.abs(pose - hold.target);
84 if (hold.best === Infinity) next = { ...hold, best: d }; // the first look after letting go: where the arm starts from
85 else if (d <= hold.best - PROGRESS_TICKS) next = { ...hold, best: d, since: now };
86 }
87 return owns(next, pose, now) ? next : idle();
88 }
89
90 /**
91 * The targets to keep sending: every let-go joint whose arm has not got there yet. Held joints are the input
92 * events' to send. @param {Map<number, Hold>} holds @param {Record<number, number | null | undefined>} poses @param {number} now
93 * @returns {Record<number, number>}
94 */
95 export function unfinished(holds, poses, now) {
96 /** @type {Record<number, number>} */
97 const out = {};
98 for (const [id, h] of holds) if (!h.held && h.target !== null && owns(h, poses[id], now)) out[id] = h.target;
99 return out;
100 }
101
102 /** Where a pose sits on a slider from `min` to `max`, 0 to 1; null when unknown. @param {number | null | undefined} pose @param {number} min @param {number} max @returns {number | null} */
103 export function markerAt(pose, min, max) {
104 if (!known(pose) || !(max > min)) return null;
105 return Math.min(1, Math.max(0, (pose - min) / (max - min)));
106 }
Software/so101/src/ui/joint-hold.test.ts added +112
@@ -0,0 +1,112 @@
1 import { describe, expect, test } from "bun:test";
2 import { ARRIVED_TICKS, SETTLE_MS, idle, markerAt, owns, press, release, settle, shown, slide, unfinished } from "./joint-hold.js";
3
4 /** A pose stream at 30 Hz from `from` to `to` over `ms`, applied the way the page's render does. */
5 function poseStream(hold: ReturnType<typeof idle>, start: number, ms: number, pose: (t: number) => number) {
6 const seen: number[] = [];
7 for (let t = start; t <= start + ms; t += 1000 / 30) {
8 hold = settle(hold, pose(t), t);
9 seen.push(shown(hold, pose(t), t)!);
10 }
11 return { hold, seen };
12 }
13
14 describe("a held slider", () => {
15 test("a 30 Hz pose stream does not move it: it shows the finger's value the whole time", () => {
16 let hold = press(idle(), 2500);
17 hold = slide(hold, 2600, 10);
18 // The arm lags, then the link drops to the simulation and reports 2048 for every joint: the slider stays put.
19 const { hold: after, seen } = poseStream(hold, 20, 3000, (t) => (t < 1500 ? 2400 + t / 100 : 2048));
20 expect(new Set(seen)).toEqual(new Set([2600]));
21 expect(after.held).toBe(true);
22 });
23
24 test("it follows the finger: each input is the new target", () => {
25 let hold = press(idle(), 2000);
26 for (const v of [2010, 2050, 2120]) hold = slide(hold, v, 0);
27 expect(shown(hold, 1990, 5)).toBe(2120);
28 });
29 });
30
31 describe("after letting go", () => {
32 test("it shows the target until the arm gets there, then follows the real pose", () => {
33 let hold = release(slide(press(idle(), 2000), 2400, 0), 100);
34 expect(shown(hold, 2100, 200)).toBe(2400); // still on its way: no snapping back
35 hold = settle(hold, 2400 - ARRIVED_TICKS, 300);
36 expect(hold).toEqual(idle()); // arrived: the slider is the arm's again
37 expect(shown(hold, 2391, 310)).toBe(2391);
38 });
39
40 test("or for 2 s at most, when the arm never gets there", () => {
41 let hold = release(slide(press(idle(), 2000), 2400, 0), 100);
42 expect(owns(hold, 2000, 100 + SETTLE_MS - 1)).toBe(true);
43 hold = settle(hold, 2000, 100 + SETTLE_MS);
44 expect(shown(hold, 2000, 100 + SETTLE_MS)).toBe(2000);
45 });
46
47 test("an input after the browser ended the gesture (pointercancel, Safari's change) is still a target, not ignored", () => {
48 let hold = release(press(idle(), 2000), 50);
49 hold = slide(hold, 2300, 60);
50 expect(hold.held).toBe(false);
51 expect(shown(hold, 2000, 500)).toBe(2300);
52 });
53
54 test("the keyboard (input with no press) drives too and settles the same way", () => {
55 const hold = slide(idle(), 2101, 0);
56 expect(shown(hold, 1900, 10)).toBe(2101);
57 expect(settle(hold, 2100, 20)).toEqual(idle()); // within ARRIVED_TICKS: arrived
58 });
59
60 test("an untouched slider simply shows the pose; nothing known shows nothing", () => {
61 expect(shown(idle(), 1234, 0)).toBe(1234);
62 expect(shown(idle(), null as unknown as number, 0)).toBeNull();
63 expect(slide(idle(), Number.NaN, 0)).toEqual(idle());
64 });
65 });
66
67 test("the real-pose marker sits where the arm is along the slider, clamped, and is absent when unknown", () => {
68 expect(markerAt(2048, 1048, 3048)).toBe(0.5);
69 expect(markerAt(10, 1048, 3048)).toBe(0);
70 expect(markerAt(9999, 1048, 3048)).toBe(1);
71 expect(markerAt(Number.NaN, 0, 1)).toBeNull();
72 expect(markerAt(5, 3, 3)).toBeNull();
73 });
74
75 describe("a slow arm (the server's 90°/s limit)", () => {
76 test("a target the arm is still closing in on keeps the control past 2 s: it never jumps back to where the arm is", () => {
77 let hold = release(slide(press(idle(), 1000), 3500, 0), 0);
78 // 2500 ticks at ~1000 ticks/s: about 2.5 s, polled at 5 Hz.
79 const seen: number[] = [];
80 for (let t = 0; t <= 2600; t += 200) {
81 const pose = Math.min(3500, 1000 + t);
82 hold = settle(hold, pose, t);
83 seen.push(shown(hold, pose, t)!);
84 }
85 expect(seen.slice(0, -1).every((v) => v === 3500)).toBe(true);
86 expect(seen.at(-1)).toBe(3500); // arrived: the arm's own value, which is the target
87 expect(hold).toEqual(idle());
88 });
89
90 test("an arm that stops short (a jam, a limit) gives the control back 2 s after it last closed in", () => {
91 let hold = release(slide(press(idle(), 1000), 3500, 0), 0);
92 hold = settle(hold, 1000, 0);
93 hold = settle(hold, 1500, 400);
94 hold = settle(hold, 1500, 400 + SETTLE_MS - 1);
95 expect(owns(hold, 1500, 400 + SETTLE_MS - 1)).toBe(true);
96 hold = settle(hold, 1500, 400 + SETTLE_MS);
97 expect(hold).toEqual(idle());
98 expect(shown(hold, 1500, 400 + SETTLE_MS)).toBe(1500);
99 });
100 });
101
102 test("unfinished: the let-go targets the arm has not reached, to keep sending; never a held one, an arrived one or a stale one", () => {
103 const holds = new Map([
104 [1, release(slide(press(idle(), 0), 2000, 0), 0)], // on its way
105 [2, release(slide(press(idle(), 0), 2000, 0), 0)], // arrived
106 [3, slide(press(idle(), 0), 2000, 0)], // still held: the input events send it
107 [4, release(slide(press(idle(), 0), 2000, 0), 0)], // let go long ago
108 [5, idle()],
109 ]);
110 expect(unfinished(holds, { 1: 1500, 2: 1995, 3: 1000, 4: 1000, 5: 1000 }, 100)).toEqual({ 1: 2000, 4: 2000 });
111 expect(unfinished(holds, { 1: 1500, 2: 1995, 3: 1000, 4: 1000, 5: 1000 }, SETTLE_MS)).toEqual({});
112 });
Software/so101/src/viewer.html +138 −37
@@ -164,7 +164,14 @@
164164 .j .v { grid-area: val; display: flex; align-items: baseline; gap: 6px; font-variant-numeric: tabular-nums; }
165165 .j small { color: var(--dim); font-size: 12px; } .j small.ld { color: var(--link); } .j small.ld:empty { display: none; }
166166 .j .slide { grid-area: slide; display: flex; align-items: center; gap: 6px; }
167 .j input[type=range] { flex: 1; min-width: 0; accent-color: var(--blue); height: var(--tap); margin: 0; }
167 .j .track { position: relative; flex: 1; min-width: 0; display: flex; align-items: center; }
168 .j input[type=range] { flex: 1; min-width: 0; accent-color: var(--blue); height: var(--tap); margin: 0; touch-action: pan-y; }
169 /* The arm's real pose: a thin mark under the thumb's travel (the thumb is about 16 px wide). */
170 .j .real, .j .aim { position: absolute; top: 28%; bottom: 28%; width: 3px; margin-left: -1.5px; left: calc(8px + var(--at, .5) * (100% - 16px)); background: var(--warn); border-radius: 2px; pointer-events: none; }
171 .j .aim { top: 18%; bottom: 18%; width: 2px; margin-left: -1px; background: var(--blue); }
172 .j small.arm { color: var(--warn); } .j small.arm:empty { display: none; }
173 .why { margin: 0 0 6px; font-size: 14px; font-weight: 650; color: var(--warn); } .why:empty { display: none; }
174 .why.flash { animation: why-flash .6s ease-out; } @keyframes why-flash { from { background: var(--bad-soft); } to { background: transparent; } }
168175 .j .jog button { min-width: var(--tap); padding: 0; font-size: 20px; line-height: 1; touch-action: none; -webkit-user-select: none; user-select: none; }
169176 .pose { display: inline-flex; gap: 4px; align-items: center; }
170177 #readout { color: var(--dim); font-size: 13px; display: flex; gap: 14px; flex-wrap: wrap; } #readout b { color: var(--fg); font-weight: 550; }
@@ -366,6 +373,7 @@
366373 </div>
367374 <p class="hint">Hold the pad to move the gripper: up reaches out, sideways swings around the base. The jog speed sets how fast.</p>
368375 </div>
376 <p id="driveWhy" class="why" role="status" aria-live="polite"></p>
369377 <div id="joints"></div>
370378 <div class="row" id="poses"></div>
371379 <div class="row" id="drive">
@@ -586,7 +594,9 @@
586594 async function pollLink() {
587595 const l = await api("/link").catch(() => null);
588596 if (l?.ok) {
597 const changed = linkNow !== l.mode;
589598 linkNow = l.mode;
599 if (changed) applyLock();
590600 const el = $("link");
591601 el.hidden = false;
592602 el.textContent = l.mode === "live" ? `Live arm · ${l.host}` : l.mode === "reconnecting" ? `Reconnecting to the arm… · ${l.host}`
@@ -785,7 +795,9 @@
785795 $("v3").onclick = () => pick("pane3");
786796
787797 // ---------------------------------------------------------------- the stream: the page as a leader
788 // Opened while a slider, a jog button, the joystick or a model joint is held; frames go at most every 33 ms; closed shortly after letting go.
798 // Opened while a slider, a jog button, the joystick or a model joint is held; frames go at most every 33 ms, the
799 // latest value per joint winning (src/ui/frames.js); closed shortly after letting go. A refusal, the page's own
800 // (src/ui/drive-gate.js) or the server's, is said in words next to the controls.
789801 const stream = {
790802 ws: null, closeTimer: null, halted: false,
791803 // one message per slot to the socket that is open, or the one about to be
@@ -795,7 +807,8 @@
795807 else if (ws?.readyState === 0) ws.addEventListener("open", () => ws.send(data), { once: true });
796808 }),
797809 open() {
798 if (!mayDrive()) return; // the server would refuse it: only the person whose turn it is streams
810 const why = block();
811 if (why) return void refused(why); // the server would refuse it too
799812 clearTimeout(this.closeTimer);
800813 if (this.ws && this.ws.readyState <= 1) return;
801814 if (this.halted) return; // the server ended this hold (Stop, or the arm is busy): nothing more until the next press
@@ -803,7 +816,11 @@
803816 ws.onclose = (e) => {
804817 if (this.ws !== ws) return;
805818 this.ws = null;
806 if (e.code === 1013 || e.code === 1000 || e.code >= 4000) { this.halted = true; msg(e.reason || "the arm is busy", true); }
819 this.frames.drop();
820 if (e.code === 1013 || e.code === 1000 || e.code >= 4000) {
821 this.halted = true; refused(gate ? gate.refusalWords(e.code, e.reason) : e.reason || "the arm is busy");
822 for (const [id, h] of holds) if (!h.held) holds.delete(id); // a stop or a refusal ends every intent: nothing is sent for it later
823 }
807824 };
808825 this.ws = ws;
809826 },
@@ -818,8 +835,38 @@
818835 this.open();
819836 if (this.ws) this.frames.flush(frame);
820837 },
821 end() { clearTimeout(this.closeTimer); this.closeTimer = setTimeout(() => { const ws = this.ws; this.ws = null; this.halted = false; ws?.close(); }, 250); },
838 end() {
839 clearTimeout(this.closeTimer);
840 this.closeTimer = setTimeout(() => {
841 if (holding()) return; // the arm is still on its way to a let-go target: the pump below ends the stream when it is there
842 const ws = this.ws; this.ws = null; this.halted = false; this.frames.drop(); ws?.close();
843 }, 250);
844 },
822845 };
846 // Each moved joint's hold by id, shared by slider and model (src/ui/joint-hold.js); `pose` is the arm's last report.
847 // That module and the drive gate (src/ui/drive-gate.js) load after the first view; until then the controls wait.
848 const holds = new Map(), pose = {};
849 let jh = null, gate = null, pumping = false;
850 const holding = () => [...holds.values()].some((h) => h.held) || (jh && Object.keys(jh.unfinished(holds, pose, performance.now())).length > 0);
851 // The pump: the arm server holds where the arm is when a stream ends or goes quiet, and under its speed limit the
852 // arm is still on its way when the finger lifts, so unreached and held targets go again on the open stream.
853 const pump = () => {
854 if (!stream.ws) return;
855 const left = jh.unfinished(holds, pose, performance.now());
856 for (const [id, h] of holds) if (h.held && h.target !== null) left[id] = h.target;
857 if (Object.keys(left).length) { pumping = true; stream.frames.send(left); }
858 else if (pumping) { pumping = false; stream.end(); }
859 };
860 const loadControls = () => Promise.all([import("/ui/__VERSION__/joint-hold.js"), import("/ui/__VERSION__/drive-gate.js")])
861 .then(([h, g]) => { jh = h; gate = g; setInterval(pump, h.KEEP_MS); applyLock(); }, () => setTimeout(loadControls, 2000));
862 const block = () => gate ? gate.driveBlock({ relayed, link: linkNow, reconnecting: Boolean(status?.reconnecting), estop: status?.estop, hello: lobby.hello, state: lobby.state }) : "Loading the controls…";
863 // A refusal from the server stays next to the controls for a while; what the page knows itself shows as long as it holds.
864 let refusal = null, refusalTimer = null;
865 function refused(why) {
866 refusal = why; clearTimeout(refusalTimer); refusalTimer = setTimeout(() => { refusal = null; showWhy(); }, 6000);
867 showWhy(); $("driveWhy").classList.remove("flash"); void $("driveWhy").offsetWidth; $("driveWhy").classList.add("flash");
868 }
869 function showWhy() { $("driveWhy").textContent = block() ?? refusal ?? ""; }
823870
824871 // ---------------------------------------------------------------- the arm
825872 let limits = {}, status = null, poses = {}, editing = false, settings = null, modelInfo = null;
@@ -1200,10 +1247,10 @@
12001247 function load3D() {
12011248 if (!modelInfo?.ok) return Promise.resolve(false);
12021249 return (model3D ??= (async () => {
1203 const [three, { STLLoader }, { default: URDFManipulator }, reach] = await Promise.all([
1204 import("three"), import("three/examples/jsm/loaders/STLLoader.js"), import("urdf-loader/manipulator"), import("/ui/__VERSION__/reach.js"),
1250 const [three, { STLLoader }, { default: URDFManipulator }, reach, ghostMod] = await Promise.all([
1251 import("three"), import("three/examples/jsm/loaders/STLLoader.js"), import("urdf-loader/manipulator"), import("/ui/__VERSION__/reach.js"), import("/ui/__VERSION__/ghost.js"),
12051252 ]);
1206 THREE = three; reachMath = reach;
1253 THREE = three; reachMath = reach; ghostFor = ghostMod.ghostFor;
12071254 if (!customElements.get("urdf-viewer")) customElements.define("urdf-viewer", URDFManipulator);
12081255 // The element leaves mesh loading to the page: binary STL through three's loader, the URDF's colour where it names one.
12091256 viewer.loadMeshFunc = (path, manager, material, done) => {
@@ -1240,21 +1287,48 @@
12401287 viewer.recenter();
12411288 $("reach").hidden = !tipLink();
12421289 });
1243 viewer.addEventListener("manipulate-start", (e) => { dragging = e.detail; stream.open(); });
1244 viewer.addEventListener("manipulate-end", () => { dragging = null; stream.end(); });
1290 // A dragged joint is the person's target, as a held slider is: drawn solid where the pointer put it, never pulled
1291 // back by the pose; the ghost (below) is where the arm really is.
1292 const modelTicks = (name) => { const id = IDS[name]; return id && limits[id] && viewer.robot ? clampTicks(id, toTicks(id, viewer.robot.joints[name].angle)) : null; };
1293 viewer.addEventListener("manipulate-start", (e) => {
1294 dragging = e.detail;
1295 const id = IDS[e.detail], t = modelTicks(e.detail);
1296 if (t !== null && jh) holds.set(id, jh.press(holds.get(id) ?? jh.idle(), t));
1297 stream.open();
1298 });
1299 viewer.addEventListener("manipulate-end", () => {
1300 const id = IDS[dragging];
1301 if (id && holds.has(id)) holds.set(id, jh.release(holds.get(id), performance.now()));
1302 dragging = null; stream.end();
1303 });
12451304 viewer.addEventListener("angle-change", (e) => {
12461305 if (dragging !== e.detail || !viewer.robot) return;
1247 const id = IDS[e.detail]; if (!id || !limits[id]) return;
1248 stream.send({ [id]: clampTicks(id, toTicks(id, viewer.robot.joints[e.detail].angle)) });
1306 const id = IDS[e.detail], t = modelTicks(e.detail); if (t === null || !jh) return;
1307 holds.set(id, jh.slide(holds.get(id) ?? jh.idle(), t, performance.now()));
1308 stream.send({ [id]: t });
1309 if (status) ghostOf(status);
12491310 });
1311 // The real arm, faint over the model while a joint is ahead of it (src/ui/ghost.js).
1312 let ghost = null, ghostFor = null;
1313 function ghostOf(d) {
1314 const robot = viewer.robot, now = performance.now();
1315 if (!robot?.parent || !ghostFor || !jh) return;
1316 const ahead = Boolean(dragging) || d.joints.some((j) => holds.has(j.id) && jh.owns(holds.get(j.id), j.position, now));
1317 if (!ahead && !ghost?.visible) return;
1318 ghost = ghostFor(THREE, robot, ghost);
1319 ghost.visible = ahead;
1320 if (ahead) for (const j of d.joints) { const name = NAMES[j.id]; if (name && j.position != null && limits[j.id] && ghost.joints[name]) ghost.joints[name].setJointValue(toRad(j.id, j.position)); }
1321 viewer.redraw();
1322 }
12501323 function applyModel(d) {
12511324 if (!viewer.robot || calib) return; // while calibrating, the model shows the pose to copy
12521325 for (const j of leaderMirrored() ? [] : d.joints) {
12531326 const name = NAMES[j.id];
12541327 if (!name || j.position == null || name === dragging || !limits[j.id]) continue;
12551328 if (reachState.timer && j.id <= 3) continue; // the joystick is ahead of the arm; snapping back would make it stutter
1256 viewer.setJointValue(name, toRad(j.id, j.position));
1329 viewer.setJointValue(name, toRad(j.id, holds.has(j.id) ? jh.shown(holds.get(j.id), j.position, performance.now()) : j.position)); // a target still being reached stays drawn
12571330 }
1331 ghostOf(d);
12581332 if (marker) {
12591333 const v = d.blocked ?? d.violation;
12601334 marker.visible = Boolean(v);
@@ -1544,17 +1618,19 @@
15441618
15451619 // ---------------------------------------------------------------- the room: the turn, the queue and the chat over /live
15461620 // Behind the hosted app's relay only the person whose turn it is may drive, and the server refuses everyone else.
1547 // The page follows suit: the Controls tab appears on your turn. Everything here arrives on one socket.
1621 // The page follows suit: the controls open on your turn, and say why they are disabled otherwise. Everything here arrives on one socket.
15481622 let wordsSent = false;
15491623 $("wordsForm").addEventListener("submit", (e) => { e.preventDefault(); wordsSent = true; say({ type: "words", words: $("wordsForm").elements.words.value.split(",").map((w) => w.trim()).filter(Boolean) }); });
15501624 const lobby = { ws: null, hello: null, state: null, offset: 0, retry: 500, mutedList: [], bannedList: [], admin: null, statusSeen: false };
1551 function mayDrive() { return !relayed || (lobby.hello !== null && (!lobby.hello.signin || (lobby.hello.you !== null && lobby.state?.driver?.id === lobby.hello.you.id))); }
1625 /** Whether the turn is yours: the driver's, or the owner's at any time (their first command takes control). */
1626 function mayDrive() { return !relayed || (lobby.hello !== null && (!lobby.hello.signin || (lobby.hello.you !== null && (Boolean(lobby.hello.you.owner) || lobby.state?.driver?.id === lobby.hello.you.id)))); }
15521627 function isOwner() { return !relayed || Boolean(lobby.hello?.you?.owner); }
15531628 const say = (m) => { if (lobby.ws?.readyState === 1) lobby.ws.send(JSON.stringify(m)); };
15541629 let drove = false;
15551630 function applyLock() {
1556 const can = mayDrive() && !status?.estop, owner = isOwner();
1557 $("t-controls").hidden = !mayDrive();
1631 const can = block() === null, owner = isOwner();
1632 $("t-controls").hidden = false; // in view for everyone: disabled, with the reason beside them, when you cannot drive
1633 showWhy();
15581634 $("t-admin").hidden = !owner;
15591635 $("t-chat").hidden = $("t-queue").hidden = !relayed;
15601636 for (const id of ["joints", "poses", "drive", "reach", "touch", "sticks"]) $(id).inert = !can;
@@ -1848,38 +1924,60 @@
18481924 function machineClose() { machine.panel?.close(); }
18491925
18501926 // ---------------------------------------------------------------- live status, sliders and jog
1927 // Each slider is the person's while they hold it, and after until the arm gets there (src/ui/joint-hold.js): the pose
1928 // the page polls is behind the finger, so it never overwrites a held slider; two thin marks show the target and the arm.
1929 // Every `input` is a target, streamed live; the hold ends however the browser ends the gesture.
18511930 const joints = $("joints");
18521931 const built = new Map();
1853 let sliding = null;
1932 const releaseAll = () => { const now = performance.now(); for (const [id, h] of holds) if (h.held && id !== IDS[dragging]) { holds.set(id, jh.release(h, now)); stream.end(); } };
1933 addEventListener("pointerup", releaseAll); addEventListener("pointercancel", releaseAll); addEventListener("blur", releaseAll);
18541934 function render(d) {
1935 const now = performance.now();
18551936 for (const j of d.joints) {
1856 let el = built.get(j.id);
1857 if (!el) {
1937 let row = built.get(j.id);
1938 const hold = () => holds.get(j.id) ?? jh.idle();
1939 if (!row) {
18581940 const lim = limits[j.id] ?? { min: 0, max: 4095 };
18591941 const div = document.createElement("div"); div.className = "j";
1860 div.innerHTML = `<b></b><div class="v"><span class="pos"></span><small class="ld"></small><small class="t"></small></div>
1861 <div class="slide"><span class="jog"><button data-d="-1" aria-label="less">−</button></span><input type="range" min="${lim.min + 30}" max="${lim.max - 30}" step="1"><span class="jog"><button data-d="1" aria-label="more">+</button></span></div>`;
1942 div.innerHTML = `<b></b><div class="v"><span class="pos"></span><small class="arm"></small><small class="ld"></small><small class="t"></small></div>
1943 <div class="slide"><span class="jog"><button data-d="-1" aria-label="less">−</button></span><span class="track"><input type="range" min="${lim.min + 30}" max="${lim.max - 30}" step="1"><i class="aim" aria-hidden="true" hidden></i><i class="real" aria-hidden="true" hidden></i></span><span class="jog"><button data-d="1" aria-label="more">+</button></span></div>`;
18621944 div.querySelector("b").textContent = j.joint ?? String(j.id);
18631945 const range = div.querySelector("input");
18641946 range.setAttribute("aria-label", j.joint ?? `joint ${j.id}`);
1865 range.addEventListener("pointerdown", () => { sliding = j.id; stream.open(); });
1866 range.addEventListener("input", () => { if (sliding === j.id) stream.send({ [j.id]: Number(range.value) }); });
1867 const done = () => { if (sliding === j.id) { sliding = null; stream.end(); } };
1868 range.addEventListener("pointerup", done); range.addEventListener("pointercancel", done); range.addEventListener("change", done);
1947 row = { div, pos: div.querySelector(".pos"), arm: div.querySelector(".arm"), ld: div.querySelector(".ld"), t: div.querySelector(".t"), aim: div.querySelector(".aim"), real: div.querySelector(".real"), range, buttons: div.querySelectorAll("button") };
1948 const r = row;
1949 range.addEventListener("pointerdown", () => { holds.set(j.id, jh.press(hold(), Number(range.value))); r.div.classList.add("drag"); stream.open(); });
1950 range.addEventListener("input", () => {
1951 const v = Number(range.value);
1952 holds.set(j.id, jh.slide(hold(), v, performance.now()));
1953 r.pos.textContent = String(v);
1954 stream.send({ [j.id]: v });
1955 });
1956 const done = () => { const h = holds.get(j.id); if (h?.held) { holds.set(j.id, jh.release(h, performance.now())); stream.end(); } };
1957 range.addEventListener("pointerup", done); range.addEventListener("pointercancel", done); range.addEventListener("lostpointercapture", done);
1958 // `change` ends a drag; from the keyboard it is the only end there is.
1959 range.addEventListener("change", () => { done(); stream.end(); });
18691960 for (const b of div.querySelectorAll(".jog button")) jog(b, j.id, () => Number(b.dataset.d));
18701961 joints.append(div);
1871 el = { div, pos: div.querySelector(".pos"), ld: div.querySelector(".ld"), t: div.querySelector(".t"), range, buttons: div.querySelectorAll("button") };
1872 built.set(j.id, el);
1962 built.set(j.id, row);
18731963 }
18741964 const hot = j.temperature >= 55, load = Math.abs(j.load ?? 0);
1875 el.pos.textContent = j.position ?? "—";
1876 el.pos.style.color = hot ? "var(--bad)" : load > 50 ? "var(--warn)" : "var(--fg)";
1877 el.t.textContent = `${j.temperature ?? "—"}°C · ${load.toFixed(0)}%${j.torque ? " ·T" : ""}`;
1878 if (sliding !== j.id && j.position != null) el.range.value = j.position;
1879 el.div.classList.toggle("jam", d.jammed?.includes(j.id));
1880 el.div.classList.toggle("drag", dragging === j.joint || sliding === j.id);
1965 const h = holds.get(j.id), mine = Boolean(h && jh.owns(h, j.position, now)), value = mine ? h.target : j.position;
1966 if (!h?.held && value != null) row.range.value = value; // held, the slider is the browser's and the finger's
1967 row.pos.textContent = value ?? "—";
1968 row.pos.style.color = hot ? "var(--bad)" : load > 50 ? "var(--warn)" : "var(--fg)";
1969 row.arm.textContent = mine && j.position != null ? `arm ${j.position}` : "";
1970 // Idle, the thumb is the arm. Moving and until the arm is there, two marks: your target and where the arm is.
1971 const lo = Number(row.range.min), hi = Number(row.range.max), at = mine ? jh.markerAt(j.position, lo, hi) : null, aim = mine ? jh.markerAt(h.target, lo, hi) : null;
1972 row.real.hidden = at === null; row.aim.hidden = aim === null;
1973 if (at !== null) row.real.style.setProperty("--at", String(at));
1974 if (aim !== null) row.aim.style.setProperty("--at", String(aim));
1975 row.real.title = `the arm is at ${j.position ?? "—"}`; row.aim.title = `your target: ${h?.target ?? "—"}`;
1976 row.t.textContent = `${j.temperature ?? "—"}°C · ${load.toFixed(0)}%${j.torque ? " ·T" : ""}`;
1977 row.div.classList.toggle("jam", d.jammed?.includes(j.id));
1978 row.div.classList.toggle("drag", dragging === j.joint || mine);
18811979 const locked = (d.driving !== null && d.driving !== "stream") || leaderStreaming(); // the page's own stream may run; a leader's may not be fought
1882 el.range.disabled = locked; for (const b of el.buttons) b.disabled = locked;
1980 row.range.disabled = locked; for (const b of row.buttons) b.disabled = locked;
18831981 }
18841982 }
18851983 function banner(d) {
@@ -1912,10 +2010,12 @@
19122010 function applyStatus(d) {
19132011 if (!started) return void (early = d);
19142012 {
1915 const wasStopped = Boolean(status?.estop);
2013 const was = `${Boolean(status?.estop)} ${Boolean(status?.reconnecting)}`;
19162014 status = d;
2015 const now = performance.now();
2016 for (const j of d.joints) { pose[j.id] = j.position; if (holds.has(j.id)) { const h = jh.settle(holds.get(j.id), j.position, now); if (h.target === null) holds.delete(j.id); else holds.set(j.id, h); } }
19172017 driver.seed(d.joints.filter((j) => j.position != null).map((j) => [j.id, j.position]));
1918 if (Boolean(d.estop) !== wasStopped) applyLock();
2018 if (`${Boolean(d.estop)} ${Boolean(d.reconnecting)}` !== was) applyLock();
19192019 // Stopped, reconnecting or no longer this person's turn: a held thumb lets go, and its zero goes out now.
19202020 if (!canDrive({ mayDrive: mayDrive(), estop: d.estop, reconnecting: d.reconnecting, limits })) driver.releaseAll();
19212021 // The round trip to the arm, which every command also makes: shown once it is long enough to feel.
@@ -1967,6 +2067,7 @@
19672067 limits = l; modelInfo = mi; started = true;
19682068 cameraFirst = !relayed || link?.mode === "live" || q.has("stream");
19692069 startViews();
2070 loadControls();
19702071 if (early) applyStatus(early);
19712072 poll();
19722073 if (relayed) pollLink();

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs