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

Migrated from github.com/Trevato/SO-ARM100

workbenchthis machine

The arm keeps a 5 Hz intent-and-read-back trace per joint for its last 20 drive sessions and serves it at GET /precision/trace?session=<id> #541

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/533-the-arm-keeps-a-5-hz-intent-and-read-bac → main 2 commits fork 1 thread · 1 unresolved

  • Merged. smith/533-the-arm-keeps-a-5-hz-intent-and-read-bac was merged into main as 417ad8b.

Review

Sign in to review this change.
10 files changed +256 −7
Software/so101/README.md +6
@@ -39,6 +39,12 @@ Who sees what: a visitor's page says only "Pi update pending" while the commits
3939
4040 `latencyP95Ms` is the sum of the p95s that were measured. The link hops are timed against the real arm only, and only the current driver's page reports its clock (at most once a second); with the simulation, or nobody driving, the list is empty and says so.
4141
42 ## Reading a session's trace
43
44 While someone drives, the arm server samples every joint's intent (the driver's target, or the joint's own position when nothing is chased) and its read-back, in ticks, at 5 Hz, from a timer beside the stream, not from the frame path. A session records at most 10 minutes (3000 samples); the last 20 sessions are kept in `precision.sqlite`, and the 21st evicts the first. A session that measured nothing is not kept, so it has no trace.
45
46 `GET /precision/trace?session=<id>` answers `{ session, t0, hz, joints: { <name>: { intent: number[], actual: number[] } } }`, where `session` is the id of the session's row, `t0` its start in ms since the epoch, and the arrays are equally long, one entry every 1/`hz` s. A bad id is 400; an unknown or evicted one is 404. The relay serves it to the owner and moderators like `/precision` (anyone else: 404); in the terminal, `/trace <session>` prints each joint's sample count, seconds and worst gap.
47
4248 ## Trying a P coefficient
4349
4450 The owner can test a joint's P (the position gain, 1–64) on the real arm, with nobody at it. On `/admin`, in Servos, type a P beside a joint and press **Try this P**; in the terminal, `/tune <joint> <P>` (for example `/tune shoulder_pan 24`). The arm server then:
Software/so101/src/precision-history.test.ts +62
@@ -181,3 +181,65 @@ describe("GET /precision on the arm server", () => {
181181 expect(after.sessions.at(-1)).toMatchObject({ commit: "feed123", releases: 1 });
182182 });
183183 });
184
185 describe("the 5 Hz trace", () => {
186 const drive = (history: PrecisionHistory, tick: (ms: number) => void, samples: number) => {
187 const t = history.begin();
188 t.target(1, 2048, 0);
189 t.sample(1, 2000, 0);
190 for (let i = 0; i < samples; i++) {
191 t.sample(1, 2000 + i, 0);
192 history.sampleTrace(t);
193 tick(200);
194 }
195 history.end(t);
196 };
197
198 test("a short drive keeps one sample per tick at 5 Hz; the 21st session evicts the first; a session is capped at ten minutes", () => {
199 let now = 0;
200 const history = new PrecisionHistory({ commit: "abc1234", now: () => now });
201 drive(history, (ms) => (now += ms), 7);
202 const first = history.trace(1)!;
203 expect(first).toMatchObject({ session: 1, t0: 0, hz: 5 });
204 expect(first.joints.shoulder_pan!.intent).toEqual(Array(7).fill(2048));
205 expect(first.joints.shoulder_pan!.actual).toEqual([2000, 2001, 2002, 2003, 2004, 2005, 2006]);
206 for (let i = 0; i < 20; i++) drive(history, (ms) => (now += ms), 1);
207 expect(history.trace(1)).toBeNull();
208 expect(history.trace(2)).not.toBeNull();
209 expect(history.trace(21)).not.toBeNull();
210 drive(history, (ms) => (now += ms), 3100);
211 expect(history.trace(22)!.joints.shoulder_pan!.actual).toHaveLength(3000);
212 });
213
214 test("GET /precision/trace: 400 for a bad id, 404 for an unknown one, the trace of a driven session", async () => {
215 const dir = mkdtempSync(join(tmpdir(), "so101-trace-"));
216 const fake = new FakeBus([1]);
217 const server = await startServer(new FeetechBus(fake), { host: "127.0.0.1", port: 0, ids: [1], posesFile: join(dir, "poses.json"), watchdogMs: 5000, commit: "feed123", modelDir: "/nowhere" });
218 const base = `http://127.0.0.1:${server.port}`;
219 try {
220 const ws = new WebSocket(`ws://127.0.0.1:${server.port}/follow`);
221 await new Promise((r) => ws.once("open", r));
222 const opened = performance.now();
223 ws.send(JSON.stringify({ "1": 2100 }));
224 await sleep(1000);
225 const gone = new Promise((r) => ws.once("close", r));
226 ws.close();
227 await gone;
228 const elapsed = performance.now() - opened;
229 for (let i = 0; i < 50 && (await fetch(`${base}/precision/trace?session=1`)).status !== 200; i++) await sleep(20);
230 expect((await fetch(`${base}/precision/trace`)).status).toBe(400);
231 expect((await fetch(`${base}/precision/trace?session=x`)).status).toBe(400);
232 expect((await fetch(`${base}/precision/trace?session=999`)).status).toBe(404);
233 const trace = (await (await fetch(`${base}/precision/trace?session=1`)).json()) as { hz: number; joints: Record<string, { intent: number[]; actual: number[] }> };
234 expect(trace.hz).toBe(5);
235 // the timer is wired to the stream: one sample per 200 ms of its life, give or take the edges
236 const n = trace.joints.shoulder_pan!.intent.length;
237 expect(n).toBeGreaterThanOrEqual(Math.floor(elapsed / 200) - 2);
238 expect(n).toBeLessThanOrEqual(Math.ceil(elapsed / 200) + 2);
239 expect(n).toBeGreaterThanOrEqual(3);
240 expect(trace.joints.shoulder_pan!.actual).toHaveLength(trace.joints.shoulder_pan!.intent.length);
241 } finally {
242 await Promise.race([server.close(), sleep(500)]);
243 }
244 });
245 });
Software/so101/src/precision-history.ts +59
@@ -8,6 +8,7 @@ import { openDb, type Db } from "./sqlite.ts";
88 import { existsSync, readFileSync } from "node:fs";
99 import { join } from "node:path";
1010 import type { PExperiment } from "./tuning-run.ts";
11 import { JOINTS } from "./sts3215.ts";
1112 import { emptyRecords, summarize, trim, Tracker, WINDOW_MS, type Card, type Cause } from "./precision.ts";
1213
1314 /** The deployed commit: the forge's or CI's variable when set, else the checkout's HEAD, else "unknown". Never a shell. */
@@ -33,6 +34,42 @@ export function deployedCommit(env: Record<string, string | undefined> = process
3334 return "unknown";
3435 }
3536
37 /** The trace: 5 samples a second, 10 minutes a session, the last 20 sessions kept. */
38 export const TRACE_HZ = 5;
39 export const TRACE_MAX_SAMPLES = 10 * 60 * TRACE_HZ;
40 export const TRACE_SESSIONS = 20;
41
42 export interface Trace {
43 session: number;
44 t0: number;
45 hz: number;
46 joints: Record<string, { intent: number[]; actual: number[] }>;
47 }
48
49 /** One session's samples as they come in; a joint first read late is padded with its first value, so every series is as long as the session. */
50 class TraceBuffer {
51 readonly t0: number;
52 samples = 0;
53 readonly joints = new Map<number, { intent: number[]; actual: number[] }>();
54 constructor(t0: number) {
55 this.t0 = t0;
56 }
57 take(levels: Array<[number, number, number]>): void {
58 if (this.samples >= TRACE_MAX_SAMPLES) return;
59 const seen = new Set<number>();
60 for (const [id, intent, actual] of levels) {
61 let j = this.joints.get(id);
62 if (!j) this.joints.set(id, (j = { intent: Array(this.samples).fill(intent), actual: Array(this.samples).fill(actual) }));
63 j.intent.push(intent);
64 j.actual.push(actual);
65 seen.add(id);
66 }
67 this.samples++;
68 // a joint not read this tick (none today, but levels() may skip one) repeats its last value
69 for (const [id, j] of this.joints) if (!seen.has(id)) (j.intent.push(j.intent.at(-1)!), j.actual.push(j.actual.at(-1)!));
70 }
71 }
72
3673 /** One stored drive session, or one hour of them: the headline numbers. */
3774 export interface Row {
3875 at: string;
@@ -75,6 +112,7 @@ export class PrecisionHistory {
75112 readonly #now: () => number;
76113 readonly #window = emptyRecords();
77114 #current: Tracker | null = null;
115 readonly #traces = new Map<Tracker, TraceBuffer>();
78116 /** The card of the drive session that ended last: how a sweep reads its own numbers. */
79117 last: Card | null = null;
80118
@@ -86,6 +124,7 @@ export class PrecisionHistory {
86124 const columns = `commit_id TEXT NOT NULL, sessions INTEGER NOT NULL, seconds REAL NOT NULL, tracking_p95_deg REAL, tracking_max_deg REAL, arrive_p95_ms REAL,
87125 snap_backs INTEGER NOT NULL, releases INTEGER NOT NULL, latency_p95_ms REAL, worst_joint TEXT`;
88126 this.#db.run(`CREATE TABLE IF NOT EXISTS sessions (id INTEGER PRIMARY KEY, at TEXT NOT NULL, ${columns}, card TEXT NOT NULL)`);
127 this.#db.run("CREATE TABLE IF NOT EXISTS traces (session INTEGER PRIMARY KEY, t0 INTEGER NOT NULL, hz INTEGER NOT NULL, joints TEXT NOT NULL)");
89128 this.#db.run("CREATE TABLE IF NOT EXISTS tunings (id INTEGER PRIMARY KEY, commit_id TEXT NOT NULL, result TEXT NOT NULL)");
90129 // An hour's roll-up keeps the worst of its sessions' p95s: one bad session in the hour is what the trend must show.
91130 this.#db.run(`CREATE TABLE IF NOT EXISTS hours (at TEXT NOT NULL, ${columns}, PRIMARY KEY (at, commit_id))`);
@@ -94,9 +133,15 @@ export class PrecisionHistory {
94133 /** A drive session starts: its tracker, whose records also feed the window. */
95134 begin(): Tracker {
96135 this.#current = new Tracker(this.#now(), [this.#window]);
136 this.#traces.set(this.#current, new TraceBuffer(this.#current.startedAt));
97137 return this.#current;
98138 }
99139
140 /** The 5 Hz tick of a session being driven (a timer's, never the frame path's): the intent and read-back of every joint read so far. */
141 sampleTrace(tracker: Tracker): void {
142 this.#traces.get(tracker)?.take(tracker.levels());
143 }
144
100145 /** A link hop: in the session being driven when there is one, else in the rolling window alone. */
101146 hop(name: string, ms: number): boolean {
102147 const at = this.#now();
@@ -119,6 +164,8 @@ export class PrecisionHistory {
119164 if (this.#current === tracker) this.#current = null;
120165 const card = summarize(tracker.records);
121166 this.last = card;
167 const trace = this.#traces.get(tracker);
168 this.#traces.delete(tracker);
122169 const measured = card.joints.some((j) => j.errorTicks.n > 0) || card.snapBacks.total > 0;
123170 if (!measured) return card;
124171 const seconds = Number(((at - tracker.startedAt) / 1000).toFixed(1));
@@ -139,6 +186,12 @@ export class PrecisionHistory {
139186 worst_joint = CASE WHEN excluded.tracking_p95_deg >= coalesce(tracking_p95_deg, -1) THEN excluded.worst_joint ELSE worst_joint END`,
140187 )
141188 .run(hour, ...row);
189 if (trace && trace.samples > 0) {
190 const session = Number((this.#db.query("SELECT max(id) AS id FROM sessions").get() as { id: number }).id);
191 const joints = Object.fromEntries([...trace.joints].map(([id, j]) => [JOINTS[id] ?? String(id), j]));
192 this.#db.query("INSERT INTO traces (session, t0, hz, joints) VALUES (?, ?, ?, ?)").run(session, trace.t0, TRACE_HZ, JSON.stringify(joints));
193 this.#db.query("DELETE FROM traces WHERE session NOT IN (SELECT session FROM traces ORDER BY session DESC LIMIT ?)").run(TRACE_SESSIONS);
194 }
142195 return card;
143196 }
144197
@@ -152,6 +205,12 @@ export class PrecisionHistory {
152205 return rows.reverse().map(fromStored);
153206 }
154207
208 /** A kept session's trace, or null when it is unknown or evicted. */
209 trace(session: number): Trace | null {
210 const r = this.#db.query("SELECT session, t0, hz, joints FROM traces WHERE session = ?").get(session) as { session: number; t0: number; hz: number; joints: string } | null;
211 return r ? { session: r.session, t0: r.t0, hz: r.hz, joints: JSON.parse(r.joints) } : null;
212 }
213
155214 /** Keep one finished P experiment. */
156215 addTuning(result: PExperiment): void {
157216 this.#db.query("INSERT INTO tunings (commit_id, result) VALUES (?, ?)").run(this.commit, JSON.stringify(result));
Software/so101/src/precision-panel.test.ts +24
@@ -112,6 +112,30 @@ describe("the Precision panel on /admin", () => {
112112 expect(asked()).toBe(1);
113113 });
114114
115 test("GET /precision/trace on the public server: the owner gets the arm's trace and its 404; a stranger or guest gets 404 unasked; a bad id is 400", async () => {
116 const asks: string[] = [];
117 const { base } = await boot(() => Response.json({}));
118 arm!.stop(true);
119 arm = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: (req) => { const u = new URL(req.url); asks.push(u.pathname + u.search); return u.searchParams.get("session") === "1" ? Response.json({ session: 1, t0: 0, hz: 5, joints: {} }) : Response.json({ error: "no such session trace" }, { status: 404 }); } });
120 relay.close?.();
121 const again = await startRelay({ port: 0, simulation: `http://127.0.0.1:${arm.port}`, lobby });
122 const url = `http://127.0.0.1:${again.port}/precision/trace`;
123 try {
124 for (const headers of [{}, guest]) {
125 const refused = await fetch(`${url}?session=1`, { headers });
126 expect(refused.status).toBe(404);
127 expect(await refused.json()).toEqual({ error: "no such route" });
128 }
129 expect(asks).toEqual([]);
130 expect(await (await fetch(`${url}?session=1`, { headers: owner })).json()).toMatchObject({ session: 1, hz: 5 });
131 expect((await fetch(`${url}?session=2`, { headers: owner })).status).toBe(404);
132 for (const bad of ["", "?session=x", "?session=1;2", "?session=-1"]) expect((await fetch(`${url}${bad}`, { headers: owner })).status).toBe(400);
133 expect(asks).toEqual(["/precision/trace?session=1", "/precision/trace?session=2"]);
134 } finally {
135 await again.close();
136 }
137 });
138
115139 test("GET /precision says so when the arm does not answer", async () => {
116140 const { base } = await boot(null);
117141 expect((await fetch(`${base}/precision`, { headers: owner })).status).toBe(502);
Software/so101/src/precision.ts +7
@@ -324,6 +324,13 @@ export class Tracker {
324324 for (const [jid, j] of this.#joints) if (id === undefined || id === jid) (j.target = undefined), (j.pending = undefined), (j.settling = undefined);
325325 }
326326
327 /** Where each read joint is and where the driver wants it (its position when nothing is chased): what the 5 Hz trace samples. */
328 levels(): Array<[number, number, number]> {
329 const out: Array<[number, number, number]> = [];
330 for (const [id, j] of this.#joints) if (j.present !== undefined) out.push([id, j.target ?? j.present, j.present]);
331 return out;
332 }
333
327334 /** Ends any settle watch still open, so the last arrival's overshoot counts. */
328335 finish(at: number): void {
329336 for (const [id, j] of this.#joints) if (j.settling) this.#settled(id, j, at);
Software/so101/src/relay.ts +17
@@ -470,6 +470,22 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
470470 /** The arm's GET /precision (src/precision-history.ts), from whichever arm is live; `hours` already checked. */
471471 const armPrecision = async (hours: string | null) =>
472472 fetch(`${remote && onArm() ? remote.http : simulation}/precision${hours === null ? "" : `?hours=${hours}`}`, { cache: "no-store", signal: AbortSignal.timeout(Math.min(readTimeoutMs, 1000)) });
473 /** GET /precision/trace?session=<id>: a kept session's 5 Hz intent and read-back, the arm's own answer (its 400 and 404 too), for the owner and moderators. */
474 const traceRead = async (req: IncomingMessage, res: ServerResponse, url: URL) => {
475 if (!lobby || !lobby.who(req) || !lobby.moderates(req)) return json(res, 404, { error: "no such route" });
476 if (req.method !== "GET") {
477 res.setHeader("allow", "GET");
478 return json(res, 405, { error: "GET" });
479 }
480 const session = url.searchParams.get("session") ?? "";
481 if (!/^\d{1,9}$/.test(session)) return json(res, 400, { error: "session must be a number" });
482 try {
483 const answer = await fetch(`${remote && onArm() ? remote.http : simulation}/precision/trace?session=${session}`, { cache: "no-store", signal: AbortSignal.timeout(Math.max(readTimeoutMs, 3000)) });
484 return json(res, answer.status, await answer.json());
485 } catch (err) {
486 return json(res, 502, { error: `the arm did not answer /precision/trace (${reason(err)})` });
487 }
488 };
473489 /** The arm's precision scorecard for the admin page, read field by field; null when the arm does not answer within a second. */
474490 const askPrecision = async () => {
475491 try {
@@ -740,6 +756,7 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
740756 if (lobby && url.pathname === "/admin/lift") return await handleLift(lobby, req, res, readBody);
741757 if (lobby && (url.pathname === "/admin" || url.pathname === "/admin/health")) return await handleAdmin(lobby, req, res, url, readBody, askPrecision, askServos, videoCards, options.piSync ? () => options.piSync!.versions() : undefined, tuneP);
742758 if (url.pathname === "/admin/versions") return versionsRead(req, res);
759 if (url.pathname === "/precision/trace") return await traceRead(req, res, url);
743760 if (url.pathname === "/precision") return await precisionRead(req, res, url);
744761 if (url.pathname === LEADER) return await leaderCalibration(req, res);
745762 if (url.pathname === "/join") {
Software/so101/src/server.ts +11 −1
@@ -43,6 +43,7 @@
4343 * POST /tuning/p {"joint": id, "p": 1-64} run the P experiment (src/tuning-run.ts) on that joint while nobody drives: sweep, write, sweep, keep or put back; 202 at once,
4444 * 409 while a run is under way or anything drives, 423 on E-stop or hold; the result joins GET /precision's tunings
4545 * GET /tuning the run's phase while one is under way, and the last outcome
46 * GET /precision/trace?session=<id> a kept session's 5 Hz intent and read-back per joint, ticks: {session, t0, hz, joints} (400 bad id, 404 unknown or evicted; the last 20 sessions)
4647 * POST /precision/snap-back {"cause": one of CAUSES, "sizeDeg"}: a snap-back only the page saw, counted beside the server's own (400 for any other cause)
4748 * GET /model.json the arm model: joints, the model's floor (floorZ) and the enforced table (tableZ), where the URDF is served
4849 * GET /leader-map.js the leader calibration mapping, for the browser (src/leader-map.js)
@@ -86,7 +87,7 @@ import { MachineLog, perServo } from "./machine-log.ts";
8687 import { Metrics } from "./metrics.ts";
8788 import { wallMs } from "./clock.ts";
8889 import { ARRIVE_TICKS, LINK_HOPS, parseSnapBack, READ_BACK_HOP, RELAY_HOP, type Cause, type Tracker } from "./precision.ts";
89 import { deployedCommit, PrecisionHistory } from "./precision-history.ts";
90 import { deployedCommit, PrecisionHistory, TRACE_HZ } from "./precision-history.ts";
9091 import { Tuning, TuningRefused } from "./tuning.ts";
9192 import { sweepJoint } from "./tuning-sweep.ts";
9293 import type { SweepResult, TuningDeps } from "./tuning-run.ts";
@@ -891,6 +892,13 @@ export async function startServer(bus: FeetechBus, options: ServerOptions = {}):
891892 if (!/^\d{1,3}$/.test(hours) || Number(hours) < 1 || Number(hours) > 720) throw new HttpError(400, "hours must be 1-720");
892893 return json(res, 200, precision.scorecard(Number(hours)));
893894 }
895 case "GET /precision/trace": {

Route exists on the arm only; the preview returns no such route. Proxy it in the relay and test that.

896 const id = url.searchParams.get("session") ?? "";
897 if (!/^\d{1,9}$/.test(id)) throw new HttpError(400, "session must be a number");
898 const trace = precision.trace(Number(id));
899 if (!trace) throw new HttpError(404, "no such session trace");
900 return json(res, 200, trace);
901 }
894902 case "POST /precision/snap-back": {
895903 // What only the page sees (a model or slider moved off the driver's target, a reconnect): counted beside the server's own.
896904 const snap = parseSnapBack(await readBody(req));
@@ -1242,6 +1250,7 @@ export async function startServer(bus: FeetechBus, options: ServerOptions = {}):
12421250 let releasing = false;
12431251 streamStats = stats;
12441252 const tracker = (tracking = precision.begin());
1253 const tracing = setInterval(() => precision.sampleTrace(tracker), 1000 / TRACE_HZ);
12451254 /** Snap-backs are counted once per episode: a joint held at its limit, a zone refusal, a run of stale frames. */
12461255 const capped = new Set<number>();
12471256 let refusing = false;
@@ -1547,6 +1556,7 @@ export async function startServer(bus: FeetechBus, options: ServerOptions = {}):
15471556 jams.clear();
15481557 streamStats = null;
15491558 if (tracking === tracker) tracking = null;
1559 clearInterval(tracing);
15501560 precision.end(tracker);
15511561 metrics.event("stream", { seconds: Number(((Date.now() - startedAt) / 1000).toFixed(1)), ...stats, ...(lost ? { lost: code } : {}) });
15521562 release(); // whatever the bus did, the arm is free for the next driver
Software/so101/src/terminal.test.ts +20 −1
@@ -12,7 +12,7 @@ import { identify, sign } from "./identity.ts";
1212 import { Lobby } from "./lobby.ts";
1313 import { startRelay, type RunningRelay } from "./relay.ts";
1414 import { startServer, type RunningServer } from "./server.ts";
15 import { alignReader, cardReader, Door, tuningReader, servosLines, servosReader, emptyRoom, hear, precisionLines, liveUrl, machineEntry, machineLines, machineUrl, healthLines, plain, poster, reader, terminalHeaders, typed } from "./terminal.ts";
15 import { traceLines, traceReader, alignReader, cardReader, Door, tuningReader, servosLines, servosReader, emptyRoom, hear, precisionLines, liveUrl, machineEntry, machineLines, machineUrl, healthLines, plain, poster, reader, terminalHeaders, typed } from "./terminal.ts";
1616 import { jointRows } from "./ui/machine.js";
1717 import { Turns } from "./turns.ts";
1818
@@ -756,3 +756,22 @@ describe("/tune", () => {
756756 expect(refused).toEqual(["error: not found"]);
757757 });
758758 });
759
760 describe("/trace", () => {
761 const body = { session: 3, t0: 0, hz: 5, joints: { shoulder_pan: { intent: [10, 20, 30], actual: [10, 15, 28] } } };
762 test("prints each joint's samples, seconds and worst gap; says why when refused; asks the right URL", async () => {
763 expect(typed(emptyRoom(), "/trace 3")).toEqual({ trace: 3 });
764 expect(typed(emptyRoom(), "/trace x")).toEqual({ print: "usage: /trace <session number, from /precision>" });
765 expect(traceLines(body)).toEqual(["session 3 at 5 Hz", " shoulder_pan: 3 samples, 0.6 s, worst gap 5 ticks"]);
766 const asked: string[] = [];
767 const ok = (async (u: string) => (asked.push(u), Response.json(body))) as unknown as typeof fetch;
768 expect((await traceReader({ PORT: "8102" }, ok)(3)).lines).toHaveLength(2);
769 expect(asked).toEqual(["http://127.0.0.1:8102/precision/trace?session=3"]);
770 const refused = (async () => Response.json({ error: "no such route" }, { status: 404 })) as unknown as typeof fetch;
771 expect((await traceReader({ PORT: "8102" }, refused)(3)).error).toBe("traces are for the owner and moderators");
772 const printed: string[] = [];
773 new Door("ws://127.0.0.1:1/live", {}, (l) => printed.push(l)).input("/trace 3");
774 await new Promise((r) => setTimeout(r, 10));
775 expect(printed.join("\n")).toContain("not available here");
776 });
777 });
Software/so101/src/terminal.ts +48 −3
@@ -35,6 +35,7 @@
3535 * /align [joint] admin: list each joint's reference pose and offset; with a joint, record it at its reference (POST /settings/joint-zero) and say Done or record again
3636 * /health owner or moderator: each open page's link as it last reported it (GET /admin/health, the page's Admin -> Health)
3737 * /versions owner or moderator: the app's and the Pi's commits and the last sync (GET /admin/versions)
38 * /trace <session> owner or moderator: a kept session's 5 Hz trace, per joint (GET /precision/trace)
3839 * /precision owner or moderator: the precision scorecard /admin shows (GET /precision, src/precision-panel.ts)
3940 * /servos owner: each joint's servo control registers /admin shows (GET /servo-params, src/servo-panel.ts); 404 to anyone else
4041 * /tune <joint> <P> owner: the P experiment /admin's Servos "Try this P" runs (POST /tuning/p): sweep, write, sweep, keep or put back; 404 to anyone else
@@ -208,6 +209,38 @@ export function tuningReader(env: Env, fetcher: typeof fetch = fetch): ReadTunin
208209 };
209210 }
210211
212 /** What GET /precision/trace answered for one session, or why not. */
213 export type TraceView = { error: string | null; lines: string[] };
214 export type ReadTrace = (session: number) => Promise<TraceView>;
215
216 /** A trace as text: per joint, its sample count, the seconds they span and the worst gap between intent and read-back, ticks. */
217 export function traceLines(body: unknown): string[] | null {
218 const t = body as { session?: unknown; hz?: unknown; joints?: Record<string, { intent?: unknown; actual?: unknown }> } | null;
219 if (!t || typeof t.hz !== "number" || t.hz <= 0 || !t.joints || typeof t.joints !== "object") return null;
220 const lines = [`session ${plain(t.session)} at ${t.hz} Hz`];
221 for (const [name, j] of Object.entries(t.joints)) {
222 if (!Array.isArray(j.intent) || !Array.isArray(j.actual)) continue;
223 const worst = j.intent.reduce((m: number, v: unknown, i: number) => Math.max(m, Math.abs(Number(v) - Number(j.actual![i as never]))), 0);
224 lines.push(` ${plain(name)}: ${j.intent.length} samples, ${(j.intent.length / t.hz).toFixed(1)} s, worst gap ${worst} ticks`);
225 }
226 return lines;
227 }
228
229 /** GET a session's trace, signed afresh; the server decides who may. */
230 export function traceReader(env: Env, fetcher: typeof fetch = fetch): ReadTrace {
231 return async (session) => {
232 try {
233 const r = await fetcher(`${appUrl(env)}/precision/trace?session=${session}`, { headers: terminalHeaders(env), signal: AbortSignal.timeout(5000) });
234 const body = (await r.json().catch(() => null)) as { error?: unknown } | null;
235 const lines = r.ok ? traceLines(body) : null;
236 if (lines) return { error: null, lines };
237 return { error: r.status === 404 && body?.error === "no such route" ? "traces are for the owner and moderators" : plain(body?.error ?? `status ${r.status}`), lines: [] };
238 } catch (err) {
239 return { error: plain((err as Error).message), lines: [] };
240 }
241 };
242 }
243
211244 /** The commits and the last sync outcome, one line each; a mismatch is flagged. */
212245 export function versionLines(v: Record<string, unknown> | null): string[] {
213246 if (!v) return ["the Pi is not kept in step from here (no deploy key, or not production)"];
@@ -321,7 +354,7 @@ const said = (room: Room, m: unknown): string => {
321354
322355 const TUNE_USAGE = "usage: /tune <joint, e.g. shoulder_pan or 1> <P, 1 to 64>, or /tune alone for the run so far";
323356 const ZERO_USAGE = "usage: /zero <joint, e.g. shoulder_pan> [degrees the model should read, default 0]";
324 export const HELP = "type to chat · /join /leave /ready /extend · /stop /resume (driver, owner) · /end [who] /table here|touch 1|2|3|<mm> /zero <joint> [deg] /align [joint] (owner) · /mute <who> /unmute <who> (owner, moderator) · /delete <who|#id> (owner, moderator) · /report <who|#id> · /reports /dismiss #<id> (owner, moderator) · /removed /restore #<id> /visitors (owner) · /health /precision /versions (owner, moderator) · /servos /tune [<joint> <P>] (owner) · /machine [off] · /who · /quit";
357 export const HELP = "type to chat · /join /leave /ready /extend · /stop /resume (driver, owner) · /end [who] /table here|touch 1|2|3|<mm> /zero <joint> [deg] /align [joint] (owner) · /mute <who> /unmute <who> (owner, moderator) · /delete <who|#id> (owner, moderator) · /report <who|#id> · /reports /dismiss #<id> (owner, moderator) · /removed /restore #<id> /visitors (owner) · /health /precision /trace <session> /versions (owner, moderator) · /servos /tune [<joint> <P>] (owner) · /machine [off] · /who · /quit";
325358
326359 /** The Machine feed's socket beside the lobby's: same app, same port. */
327360 export const machineUrl = (live: string): string => live.replace(/\/live$/, "/machine");
@@ -464,7 +497,7 @@ function target(room: Room, word: string): string | null {
464497 return ID.test(word) ? word : null;
465498 }
466499
467 export type Typed = { send: Frame } | { post: "/stop" | "/resume" } | { table: "here" | number | { touch: 1 | 2 | 3 } } | { zero: { joint: string; referenceDeg: number } } | { align: string | null } | { print: string } | { lines: string[] } | { machine: boolean } | { health: true } | { precision: true } | { servos: true } | { tune: { joint: number; p: number } | null } | { versions: true } | { quit: true } | null;
500 export type Typed = { send: Frame } | { post: "/stop" | "/resume" } | { table: "here" | number | { touch: 1 | 2 | 3 } } | { zero: { joint: string; referenceDeg: number } } | { align: string | null } | { print: string } | { lines: string[] } | { machine: boolean } | { health: true } | { precision: true } | { trace: number } | { servos: true } | { tune: { joint: number; p: number } | null } | { versions: true } | { quit: true } | null;
468501
469502 /** What a typed line asks for. Validation the server repeats anyway; this only saves a round trip on a typo. */
470503 export function typed(room: Room, input: string): Typed {
@@ -551,6 +584,8 @@ export function typed(room: Room, input: string): Typed {
551584 return { health: true };
552585 case "precision":
553586 return { precision: true };
587 case "trace":
588 return /^\d{1,9}$/.test(arg) ? { trace: Number(arg) } : { print: "usage: /trace <session number, from /precision>" };
554589 case "servos":
555590 return { servos: true };
556591 case "versions":
@@ -584,11 +619,13 @@ export class Door {
584619 private readonly readCard: ReadCard | null;
585620 private readonly readServos: ReadServos | null;
586621 private readonly readTuning: ReadTuning | null;
622 private readonly readTrace: ReadTrace | null;
587623 private readonly readVersions: ReadVersions | null;
588624 private readonly readAlign: ReadAlign | null;
589625
590626 /** `post` reaches the app's /stop and /resume, `read` its /admin/health, `readCard` its /precision; without them, the door says it cannot. */
591 constructor(url: string, headers: Record<string, string>, print: (line: string) => void, post: Post | null = null, read: Read | null = null, readCard: ReadCard | null = null, readServos: ReadServos | null = null, readVersions: ReadVersions | null = null, readAlign: ReadAlign | null = null, readTuning: ReadTuning | null = null) {
627 constructor(url: string, headers: Record<string, string>, print: (line: string) => void, post: Post | null = null, read: Read | null = null, readCard: ReadCard | null = null, readServos: ReadServos | null = null, readVersions: ReadVersions | null = null, readAlign: ReadAlign | null = null, readTuning: ReadTuning | null = null, readTrace: ReadTrace | null = null) {
628 this.readTrace = readTrace;
592629 this.readAlign = readAlign;
593630 this.readTuning = readTuning;
594631 this.readVersions = readVersions;
@@ -639,6 +676,7 @@ export class Door {
639676 else if ("align" in t) void this.align(t.align);
640677 else if ("health" in t) void this.health();
641678 else if ("precision" in t) void this.precision();
679 else if ("trace" in t) void this.trace(t.trace);
642680 else if ("servos" in t) void this.servos();
643681 else if ("tune" in t) void this.tune(t.tune);
644682 else if ("versions" in t) void this.versions();
@@ -677,6 +715,13 @@ export class Door {
677715 for (const line of r.error || !r.panel ? [`error: ${r.error ?? "no scorecard"}`] : precisionLines(r.panel)) this.print(line);
678716 }
679717
718 /** The server decides who may; a refusal is printed, else the session's trace summary. */
719 private async trace(session: number): Promise<void> {
720 if (!this.readTrace) return this.print("error: traces are not available here");
721 const r = await this.readTrace(session);
722 for (const line of r.error ? [`error: ${r.error}`] : r.lines) this.print(line);
723 }
724
680725 /** The server decides who may; a refusal is printed, else the joints' registers. */
681726 private async servos(): Promise<void> {
682727 if (!this.readServos) return this.print("error: servos are not available here");
Software/so101/src/tty.ts +2 −2
@@ -4,7 +4,7 @@
44 */
55
66 import { createInterface, type Interface } from "node:readline";
7 import { alignReader, cardReader, Door, HELP, liveUrl, poster, reader, servosReader, terminalHeaders, tuningReader, versionsReader } from "./terminal.ts";
7 import { alignReader, cardReader, Door, HELP, liveUrl, poster, reader, servosReader, terminalHeaders, traceReader, tuningReader, versionsReader } from "./terminal.ts";
88
99 const env = process.env;
1010 const where = env.FORGE_APP_ENV === "preview" ? `preview of #${env.FORGE_APP_PULL ?? "?"}` : (env.FORGE_APP_ENV ?? "local");
@@ -17,7 +17,7 @@ const print = (line: string) => {
1717 rl?.prompt(true);
1818 };
1919
20 const door = new Door(liveUrl(env), terminalHeaders(env), print, poster(env), reader(env), cardReader(env), servosReader(env), versionsReader(env), alignReader(env), tuningReader(env));
20 const door = new Door(liveUrl(env), terminalHeaders(env), print, poster(env), reader(env), cardReader(env), servosReader(env), versionsReader(env), alignReader(env), tuningReader(env), traceReader(env));
2121 print(`\x1b[1mSO-101 arm\x1b[0m · ${where} · ${HELP}`);
2222 try {
2323 await door.open(() => {

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs