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

Migrated from github.com/Trevato/SO-ARM100

workbenchthis machine

The relay keeps the arm's first /servo-params read as the factory baseline under FORGE_APP_DATA, owner-only at GET /servo-params/factory #462

Merged opened this

Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.

Merged

smith/arm:smith/459-the-relay-keeps-the-arm-s-first-servo-pa → main 1 commit fork

  • Merged. smith/459-the-relay-keeps-the-arm-s-first-servo-pa was merged into main as 075a6c9.

Review

Sign in to review this change.
5 files changed +192 −3
Software/README.md +4
@@ -909,6 +909,10 @@ The app reaches the Pi through the forge's egress list; 100.89.95.68:8082,
909909 :8083 and :8084 are in `forge.json`'s `egress`. Camera 2 would need
910910 another three ports, and those ports in the egress list too.
911911
912 ## Servo factory baseline
913
914 The first time the relay's link to the arm server is up with nobody holding a turn, it reads `GET /servo-params` once and, if every servo answered, keeps it as `servo-factory.json` (`{ recordedAt, armRun, servos }`) under `FORGE_APP_DATA`; it is never overwritten, and a partial read is retried on the next connect. The owner reads it at `GET /servo-params/factory` (404 for anyone else, or before it is recorded), and #450's factory restore and the tuning pulls read from it.
915
912916 ## Metrics
913917
914918 `GET /metrics.prom` on the relay answers Prometheus text (`text/plain; version=0.0.4`, `no-store`, with the usual
Software/so101/bench/fake-serve.ts +1 −1
@@ -68,6 +68,6 @@ try {
6868 } catch (err) {
6969 console.error(`${(err as Error).message}; cameras stay MJPEG`);
7070 }
71 const relay = await startRelay({ host, port, simulation: `http://127.0.0.1:${simulation.port}`, remote, problem, lobby, cameras, leaders, video, summaryEveryMs: 60_000, holdFile: join(dir, "hold.json") });
71 const relay = await startRelay({ host, port, simulation: `http://127.0.0.1:${simulation.port}`, remote, problem, lobby, cameras, leaders, video, summaryEveryMs: 60_000, holdFile: join(dir, "hold.json"), baselineFile: join(dir, "servo-factory.json") });
7272 const { mode, host: armHost } = relay.link();
7373 console.log(`arm on http://${host}:${relay.port} (${mode === "simulated" ? "simulated" : `arm ${armHost}: ${mode}`}; data in ${dir}${local ? "; local: every visitor drives as the owner" : ""})`);
Software/so101/src/relay.ts +39 −2
@@ -67,6 +67,7 @@ import { browserCookie } from "./browser-id.ts";
6767 import { AccountError, sessionCookie, visitor } from "./accounts.ts";
6868 import { CameraSocket } from "./camera-socket.ts";
6969 import { OFFLINE_FRAME } from "./offline-frame.ts";
70 import { ServoBaseline } from "./servo-baseline.ts";
7071 import { handleAdmin, handleLift } from "./admin-routes.ts";
7172 import { parseFps, type FeedOptions } from "./camera-feed.ts";
7273 import { CameraError, CameraHub } from "./cameras.ts";
@@ -127,6 +128,8 @@ export interface RelayOptions {
127128 video?: Record<number, VideoSources>;
128129 /** Keep STOP's hold here, and restore it on start; without one it is in memory. */
129130 holdFile?: string;
131 /** Keep the arm's first complete /servo-params read here (servo-factory.json); without one nothing is recorded. */
132 baselineFile?: string;
130133 /** Every driver's leader calibration; without one they are kept in memory. */
131134 leaders?: LeaderCalibrations;
132135 /** How often the arm's status is read for the pages on /live (and sent to them when it changed). */
@@ -251,6 +254,24 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
251254 let problem: string | null = options.problem ?? null;
252255 /** Requests in flight to the arm server: cut when the link drops, so nothing waits on a dead one. */
253256 const inFlight = new Set<AbortController>();
257 const baseline = new ServoBaseline(options.baselineFile);
258 let armRun = "";
259 let recording = false;
260 /** One read per connect: set when the read was made, cleared when the link comes up again. */
261 let tried = false;
262 /** Read /servo-params once for the factory baseline, only while nobody holds a turn; any trouble is left for the next connect. */
263 const recordBaseline = async () => {
264 if (recording || !remote || mode() !== "live" || !armRun || lobby?.turns.snapshot().driver) return;
265 recording = tried = true;
266 try {
267 const res = await fetch(`${remote.http}/servo-params`, { signal: AbortSignal.timeout(readTimeoutMs), cache: "no-store" });
268 if (res.ok && !lobby?.turns.snapshot().driver && baseline.record(await res.json(), armRun)) console.log("servo baseline recorded");
269 } catch {
270 // quietly: the next connect tries again
271 } finally {
272 recording = false;
273 }
274 };
254275 const connect = () => {
255276 armLink?.close();
256277 armLink = null;
@@ -262,9 +283,18 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
262283 timings: options.link,
263284 metrics,
264285 onStatus: (status) => onArm() && machine.status(status),
265 onMachine: (entries, run) => onArm() && machine.arm(entries, run),
286 onMachine: (entries, run) => {
287 if (!onArm()) return;
288 machine.arm(entries, run);
289 armRun = run;
290 if (!baseline.recorded() && !tried) void recordBaseline();
291 },
266292 onChange: (state, previous) => {
267 if (state === "live") console.log(`arm server ${host}: live`);
293 if (state === "live") {
294 console.log(`arm server ${host}: live`);
295 tried = false;
296 if (!baseline.recorded()) void recordBaseline();
297 }
268298 else console.error(`arm server ${host}: ${state === "offline" ? "offline; simulating" : "reconnecting"} (${armLink?.problem})`);
269299 if (previous === "live") for (const c of inFlight) c.abort(new Error(armLink?.problem ?? "the link dropped"));
270300 },
@@ -578,6 +608,13 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
578608 return json(res, 405, { error: "POST a name" });
579609 }
580610 const route = `${req.method} ${url.pathname}`;
611 if (route === "GET /servo-params/factory") {
612 if (!(lobby ? lobby.who(req)?.owner : false)) return json(res, 404, { error: "not found" });
613 const text = baseline.text();
614 if (!text) return json(res, 404, { error: "no baseline recorded yet" });
615 res.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
616 return res.end(text);
617 }
581618 let by = "the arm's page";
582619 if (OWNER_READS.has(route) && !(lobby ? lobby.who(req)?.owner : false)) return json(res, 404, { error: "not found" });
583620 if (!reading && lobby) {
Software/so101/src/servo-baseline.test.ts added +113
@@ -0,0 +1,113 @@
1 import { afterEach, expect, test } from "bun:test";
2 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
3 import { createServer, type Server } from "node:http";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { WebSocketServer } from "ws";
7 import { sign } from "./identity.ts";
8 import { Lobby } from "./lobby.ts";
9 import { parseRemote, startRelay, type RunningRelay } from "./relay.ts";
10
11 const KEY = "k".repeat(64);
12 const later = Date.now() + 600_000;
13 const as = (name: string, role: "user" | "admin") => {
14 const identity = `id-${name}|${name}|${role}|${later}`;
15 return { "x-forge-identity": identity, "x-forge-signature": sign(identity, KEY) };
16 };
17 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
18 const row = (id: number, error?: string) => ({ id, joint: `j${id}`, registers: { P_Coefficient: 32 + id }, ...(error ? { error } : {}) });
19
20 let dir = "";
21 let relay: RunningRelay | undefined;
22 let lobby: Lobby | undefined;
23 let arm: Server | undefined;
24 let wss: WebSocketServer | undefined;
25 afterEach(async () => {
26 await relay?.close();
27 lobby?.close();
28 for (const c of wss?.clients ?? []) c.terminate();
29 arm?.closeAllConnections();
30 await new Promise((r) => (arm ? arm.close(r) : r(0)));
31 if (dir) rmSync(dir, { recursive: true, force: true });
32 dir = "";
33 relay = lobby = arm = wss = undefined;
34 });
35
36 /** A fake arm server: /watch pushes a status and its run; GET /servo-params answers `reads` in turn, counted. */
37 async function boot(reads: unknown[]) {
38 dir ||= mkdtempSync(join(tmpdir(), "so101-baseline-"));
39 const calls = { n: 0 };
40 wss = new WebSocketServer({ noServer: true });
41 arm = createServer((req, res) => {
42 if (req.url !== "/servo-params") return void res.writeHead(404).end();
43 const body = reads[Math.min(calls.n++, reads.length - 1)];
44 res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(body));
45 });
46 arm.on("upgrade", (req, socket, head) => wss!.handleUpgrade(req, socket, head, (ws) => {
47 const push = () => ws.readyState === ws.OPEN && (ws.send('{"joints":[]}'), ws.send('{"machine":[],"run":"run-1"}'));
48 push();
49 const t = setInterval(push, 20);
50 ws.on("close", () => clearInterval(t));
51 }));
52 await new Promise<void>((r) => arm!.listen(0, "127.0.0.1", r));
53 const port = (arm.address() as { port: number }).port;
54 const start = async (driver = false) => {
55 lobby = new Lobby({ identityKey: KEY, adminFile: join(dir, "admin.json"), turnsFile: join(dir, "turns.json") });
56 if (driver) lobby.takeControl({ id: "id-bob", name: "bob", owner: false });
57 relay = await startRelay({ port: 0, simulation: "http://127.0.0.1:1", remote: parseRemote({ ARM_SERVER: `ws://127.0.0.1:${port}` })!, lobby, baselineFile: join(dir, "servo-factory.json"), link: { backoffMs: [20], staleMs: 300 } });
58 return `http://127.0.0.1:${relay.port}`;
59 };
60 return { calls, start, file: join(dir, "servo-factory.json") };
61 }
62
63 test("the first connect records the baseline, and a later connect leaves it alone", async () => {
64 const { calls, start, file } = await boot([[row(1), row(2)], [row(1), row(9)]]);
65 const base = await start();
66 await sleep(300);
67 const kept = JSON.parse(readFileSync(file, "utf8"));
68 expect(kept).toMatchObject({ armRun: "run-1", servos: [row(1), row(2)] });
69 expect(typeof kept.recordedAt).toBe("string");
70 for (const c of wss!.clients) c.terminate(); // the link drops and comes back
71 await sleep(300);
72 expect(calls.n).toBe(1);
73 expect(JSON.parse(readFileSync(file, "utf8"))).toEqual(kept);
74 // the owner reads it; anyone else, and a stranger, is told there is no such page
75 const owner = await fetch(`${base}/servo-params/factory`, { headers: as("trevato", "admin") });
76 expect(owner.status).toBe(200);
77 expect(await owner.json()).toEqual(kept);
78 expect((await fetch(`${base}/servo-params/factory`, { headers: as("bob", "user") })).status).toBe(404);
79 expect((await fetch(`${base}/servo-params/factory`)).status).toBe(404);
80 });
81
82 test("a partial read is not saved and the next connect tries again; 404 until one is", async () => {
83 const { calls, start, file } = await boot([[row(1), row(2, "no answer")], [row(1), row(2)]]);
84 const base = await start();
85 await sleep(300);
86 expect(calls.n).toBe(1);
87 expect(existsSync(file)).toBe(false);
88 expect((await fetch(`${base}/servo-params/factory`, { headers: as("trevato", "admin") })).status).toBe(404);
89 for (const c of wss!.clients) c.terminate();
90 await sleep(400);
91 expect(JSON.parse(readFileSync(file, "utf8")).servos).toEqual([row(1), row(2)]);
92 });
93
94 test("a restart keeps the file", async () => {
95 const { start, file } = await boot([[row(1)], [row(7)]]);
96 await start();
97 await sleep(300);
98 const kept = readFileSync(file, "utf8");
99 await relay!.close();
100 lobby!.close();
101 const base = await start();
102 await sleep(300);
103 expect(readFileSync(file, "utf8")).toBe(kept);
104 expect(await (await fetch(`${base}/servo-params/factory`, { headers: as("trevato", "admin") })).text()).toBe(kept);
105 });
106
107 test("nothing is read while someone holds a turn", async () => {
108 const { calls, start, file } = await boot([[row(1)]]);
109 await start(true);
110 await sleep(300);
111 expect(calls.n).toBe(0);
112 expect(existsSync(file)).toBe(false);
113 });
Software/so101/src/servo-baseline.ts added +35
@@ -0,0 +1,35 @@
1 /**
2 * The factory baseline: the arm's first complete GET /servo-params, kept once under FORGE_APP_DATA as servo-factory.json
3 * ({ recordedAt, armRun, servos }). It is written atomically and never overwritten; a read in which any servo has an
4 * `error` is not kept, and the relay tries again on the next connect.
5 */
6
7 import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
8
9 export class ServoBaseline {
10 constructor(private readonly file: string | undefined) {}
11
12 /** The recorded file's text, or null when none is recorded (or the relay keeps none). */
13 text(): string | null {
14 try {
15 return this.file ? readFileSync(this.file, "utf8") : null;
16 } catch {
17 return null;
18 }
19 }
20
21 recorded(): boolean {
22 return !this.file || existsSync(this.file);
23 }
24
25 /** Keep `servos` if it is a whole read and nothing is recorded yet; true when it was written. */
26 record(servos: unknown, armRun: string): boolean {
27 if (!this.file || this.recorded()) return false;
28 if (!Array.isArray(servos) || !servos.length) return false;
29 if (!servos.every((s) => s && typeof s === "object" && !("error" in s))) return false;
30 const temp = `${this.file}.${process.pid}.tmp`;
31 writeFileSync(temp, JSON.stringify({ recordedAt: new Date().toISOString(), armRun, servos }, null, 2) + "\n");
32 renameSync(temp, this.file);
33 return true;
34 }
35 }

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs