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
Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.
smith/arm:smith/459-the-relay-keeps-the-arm-s-first-servo-pa → main 1 commit fork
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, | ||
| 909 | 909 | :8083 and :8084 are in `forge.json`'s `egress`. Camera 2 would need |
| 910 | 910 | another three ports, and those ports in the egress list too. |
| 911 | 911 | |
| 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 | ||
| 912 | 916 | ## Metrics |
| 913 | 917 | |
| 914 | 918 | `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 { | ||
| 68 | 68 | } catch (err) { |
| 69 | 69 | console.error(`${(err as Error).message}; cameras stay MJPEG`); |
| 70 | 70 | } |
| 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") }); | |
| 72 | 72 | const { mode, host: armHost } = relay.link(); |
| 73 | 73 | 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"; | ||
| 67 | 67 | import { AccountError, sessionCookie, visitor } from "./accounts.ts"; |
| 68 | 68 | import { CameraSocket } from "./camera-socket.ts"; |
| 69 | 69 | import { OFFLINE_FRAME } from "./offline-frame.ts"; |
| 70 | import { ServoBaseline } from "./servo-baseline.ts"; | |
| 70 | 71 | import { handleAdmin, handleLift } from "./admin-routes.ts"; |
| 71 | 72 | import { parseFps, type FeedOptions } from "./camera-feed.ts"; |
| 72 | 73 | import { CameraError, CameraHub } from "./cameras.ts"; |
| @@ -127,6 +128,8 @@ export interface RelayOptions { | ||
| 127 | 128 | video?: Record<number, VideoSources>; |
| 128 | 129 | /** Keep STOP's hold here, and restore it on start; without one it is in memory. */ |
| 129 | 130 | holdFile?: string; |
| 131 | /** Keep the arm's first complete /servo-params read here (servo-factory.json); without one nothing is recorded. */ | |
| 132 | baselineFile?: string; | |
| 130 | 133 | /** Every driver's leader calibration; without one they are kept in memory. */ |
| 131 | 134 | leaders?: LeaderCalibrations; |
| 132 | 135 | /** 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> { | ||
| 251 | 254 | let problem: string | null = options.problem ?? null; |
| 252 | 255 | /** Requests in flight to the arm server: cut when the link drops, so nothing waits on a dead one. */ |
| 253 | 256 | 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 | }; | |
| 254 | 275 | const connect = () => { |
| 255 | 276 | armLink?.close(); |
| 256 | 277 | armLink = null; |
| @@ -262,9 +283,18 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> { | ||
| 262 | 283 | timings: options.link, |
| 263 | 284 | metrics, |
| 264 | 285 | 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 | }, | |
| 266 | 292 | 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 | } | |
| 268 | 298 | else console.error(`arm server ${host}: ${state === "offline" ? "offline; simulating" : "reconnecting"} (${armLink?.problem})`); |
| 269 | 299 | if (previous === "live") for (const c of inFlight) c.abort(new Error(armLink?.problem ?? "the link dropped")); |
| 270 | 300 | }, |
| @@ -578,6 +608,13 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> { | ||
| 578 | 608 | return json(res, 405, { error: "POST a name" }); |
| 579 | 609 | } |
| 580 | 610 | 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 | } | |
| 581 | 618 | let by = "the arm's page"; |
| 582 | 619 | if (OWNER_READS.has(route) && !(lobby ? lobby.who(req)?.owner : false)) return json(res, 404, { error: "not found" }); |
| 583 | 620 | 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 | } |
new above
offline