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
Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.
smith/arm:smith/533-the-arm-keeps-a-5-hz-intent-and-read-bac → main 2 commits fork 1 thread · 1 unresolved
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 | ||
| 39 | 39 | |
| 40 | 40 | `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. |
| 41 | 41 | |
| 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 | ||
| 42 | 48 | ## Trying a P coefficient |
| 43 | 49 | |
| 44 | 50 | 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", () => { | ||
| 181 | 181 | expect(after.sessions.at(-1)).toMatchObject({ commit: "feed123", releases: 1 }); |
| 182 | 182 | }); |
| 183 | 183 | }); |
| 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"; | ||
| 8 | 8 | import { existsSync, readFileSync } from "node:fs"; |
| 9 | 9 | import { join } from "node:path"; |
| 10 | 10 | import type { PExperiment } from "./tuning-run.ts"; |
| 11 | import { JOINTS } from "./sts3215.ts"; | |
| 11 | 12 | import { emptyRecords, summarize, trim, Tracker, WINDOW_MS, type Card, type Cause } from "./precision.ts"; |
| 12 | 13 | |
| 13 | 14 | /** 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 | ||
| 33 | 34 | return "unknown"; |
| 34 | 35 | } |
| 35 | 36 | |
| 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 | ||
| 36 | 73 | /** One stored drive session, or one hour of them: the headline numbers. */ |
| 37 | 74 | export interface Row { |
| 38 | 75 | at: string; |
| @@ -75,6 +112,7 @@ export class PrecisionHistory { | ||
| 75 | 112 | readonly : () => number; |
| 76 | 113 | readonly = emptyRecords(); |
| 77 | 114 | : Tracker | null = null; |
| 115 | readonly = new Map<Tracker, TraceBuffer>(); | |
| 78 | 116 | /** The card of the drive session that ended last: how a sweep reads its own numbers. */ |
| 79 | 117 | last: Card | null = null; |
| 80 | 118 | |
| @@ -86,6 +124,7 @@ export class PrecisionHistory { | ||
| 86 | 124 | 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, |
| 87 | 125 | snap_backs INTEGER NOT NULL, releases INTEGER NOT NULL, latency_p95_ms REAL, worst_joint TEXT`; |
| 88 | 126 | this..run(`CREATE TABLE IF NOT EXISTS sessions (id INTEGER PRIMARY KEY, at TEXT NOT NULL, ${columns}, card TEXT NOT NULL)`); |
| 127 | this..run("CREATE TABLE IF NOT EXISTS traces (session INTEGER PRIMARY KEY, t0 INTEGER NOT NULL, hz INTEGER NOT NULL, joints TEXT NOT NULL)"); | |
| 89 | 128 | this..run("CREATE TABLE IF NOT EXISTS tunings (id INTEGER PRIMARY KEY, commit_id TEXT NOT NULL, result TEXT NOT NULL)"); |
| 90 | 129 | // An hour's roll-up keeps the worst of its sessions' p95s: one bad session in the hour is what the trend must show. |
| 91 | 130 | this..run(`CREATE TABLE IF NOT EXISTS hours (at TEXT NOT NULL, ${columns}, PRIMARY KEY (at, commit_id))`); |
| @@ -94,9 +133,15 @@ export class PrecisionHistory { | ||
| 94 | 133 | /** A drive session starts: its tracker, whose records also feed the window. */ |
| 95 | 134 | begin(): Tracker { |
| 96 | 135 | this. = new Tracker(this.(), [this.]); |
| 136 | this..set(this., new TraceBuffer(this..startedAt)); | |
| 97 | 137 | return this.; |
| 98 | 138 | } |
| 99 | 139 | |
| 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..get(tracker)?.take(tracker.levels()); | |
| 143 | } | |
| 144 | ||
| 100 | 145 | /** A link hop: in the session being driven when there is one, else in the rolling window alone. */ |
| 101 | 146 | hop(name: string, ms: number): boolean { |
| 102 | 147 | const at = this.(); |
| @@ -119,6 +164,8 @@ export class PrecisionHistory { | ||
| 119 | 164 | if (this. === tracker) this. = null; |
| 120 | 165 | const card = summarize(tracker.records); |
| 121 | 166 | this.last = card; |
| 167 | const trace = this..get(tracker); | |
| 168 | this..delete(tracker); | |
| 122 | 169 | const measured = card.joints.some((j) => j.errorTicks.n > 0) || card.snapBacks.total > 0; |
| 123 | 170 | if (!measured) return card; |
| 124 | 171 | const seconds = Number(((at - tracker.startedAt) / 1000).toFixed(1)); |
| @@ -139,6 +186,12 @@ export class PrecisionHistory { | ||
| 139 | 186 | worst_joint = CASE WHEN excluded.tracking_p95_deg >= coalesce(tracking_p95_deg, -1) THEN excluded.worst_joint ELSE worst_joint END`, |
| 140 | 187 | ) |
| 141 | 188 | .run(hour, ...row); |
| 189 | if (trace && trace.samples > 0) { | |
| 190 | const session = Number((this..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..query("INSERT INTO traces (session, t0, hz, joints) VALUES (?, ?, ?, ?)").run(session, trace.t0, TRACE_HZ, JSON.stringify(joints)); | |
| 193 | this..query("DELETE FROM traces WHERE session NOT IN (SELECT session FROM traces ORDER BY session DESC LIMIT ?)").run(TRACE_SESSIONS); | |
| 194 | } | |
| 142 | 195 | return card; |
| 143 | 196 | } |
| 144 | 197 | |
| @@ -152,6 +205,12 @@ export class PrecisionHistory { | ||
| 152 | 205 | return rows.reverse().map(fromStored); |
| 153 | 206 | } |
| 154 | 207 | |
| 208 | /** A kept session's trace, or null when it is unknown or evicted. */ | |
| 209 | trace(session: number): Trace | null { | |
| 210 | const r = this..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 | ||
| 155 | 214 | /** Keep one finished P experiment. */ |
| 156 | 215 | addTuning(result: PExperiment): void { |
| 157 | 216 | this..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", () => { | ||
| 112 | 112 | expect(asked()).toBe(1); |
| 113 | 113 | }); |
| 114 | 114 | |
| 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 | ||
| 115 | 139 | test("GET /precision says so when the arm does not answer", async () => { |
| 116 | 140 | const { base } = await boot(null); |
| 117 | 141 | expect((await fetch(`${base}/precision`, { headers: owner })).status).toBe(502); |
Software/so101/src/precision.ts +7
| @@ -324,6 +324,13 @@ export class Tracker { | ||
| 324 | 324 | for (const [jid, j] of this.) if (id === undefined || id === jid) (j.target = undefined), (j.pending = undefined), (j.settling = undefined); |
| 325 | 325 | } |
| 326 | 326 | |
| 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.) if (j.present !== undefined) out.push([id, j.target ?? j.present, j.present]); | |
| 331 | return out; | |
| 332 | } | |
| 333 | ||
| 327 | 334 | /** Ends any settle watch still open, so the last arrival's overshoot counts. */ |
| 328 | 335 | finish(at: number): void { |
| 329 | 336 | for (const [id, j] of this.) if (j.settling) this.(id, j, at); |
Software/so101/src/relay.ts +17
| @@ -470,6 +470,22 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> { | ||
| 470 | 470 | /** The arm's GET /precision (src/precision-history.ts), from whichever arm is live; `hours` already checked. */ |
| 471 | 471 | const armPrecision = async (hours: string | null) => |
| 472 | 472 | 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 | }; | |
| 473 | 489 | /** The arm's precision scorecard for the admin page, read field by field; null when the arm does not answer within a second. */ |
| 474 | 490 | const askPrecision = async () => { |
| 475 | 491 | try { |
| @@ -740,6 +756,7 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> { | ||
| 740 | 756 | if (lobby && url.pathname === "/admin/lift") return await handleLift(lobby, req, res, readBody); |
| 741 | 757 | 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); |
| 742 | 758 | if (url.pathname === "/admin/versions") return versionsRead(req, res); |
| 759 | if (url.pathname === "/precision/trace") return await traceRead(req, res, url); | |
| 743 | 760 | if (url.pathname === "/precision") return await precisionRead(req, res, url); |
| 744 | 761 | if (url.pathname === LEADER) return await leaderCalibration(req, res); |
| 745 | 762 | if (url.pathname === "/join") { |
Software/so101/src/server.ts +11 −1
| @@ -43,6 +43,7 @@ | ||
| 43 | 43 | * 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, |
| 44 | 44 | * 409 while a run is under way or anything drives, 423 on E-stop or hold; the result joins GET /precision's tunings |
| 45 | 45 | * 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) | |
| 46 | 47 | * 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) |
| 47 | 48 | * GET /model.json the arm model: joints, the model's floor (floorZ) and the enforced table (tableZ), where the URDF is served |
| 48 | 49 | * 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"; | ||
| 86 | 87 | import { Metrics } from "./metrics.ts"; |
| 87 | 88 | import { wallMs } from "./clock.ts"; |
| 88 | 89 | 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"; | |
| 90 | 91 | import { Tuning, TuningRefused } from "./tuning.ts"; |
| 91 | 92 | import { sweepJoint } from "./tuning-sweep.ts"; |
| 92 | 93 | import type { SweepResult, TuningDeps } from "./tuning-run.ts"; |
| @@ -891,6 +892,13 @@ export async function startServer(bus: FeetechBus, options: ServerOptions = {}): | ||
| 891 | 892 | if (!/^\d{1,3}$/.test(hours) || Number(hours) < 1 || Number(hours) > 720) throw new HttpError(400, "hours must be 1-720"); |
| 892 | 893 | return json(res, 200, precision.scorecard(Number(hours))); |
| 893 | 894 | } |
| 895 | case "GET /precision/trace": { | |
| 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 | } | |
| 894 | 902 | case "POST /precision/snap-back": { |
| 895 | 903 | // What only the page sees (a model or slider moved off the driver's target, a reconnect): counted beside the server's own. |
| 896 | 904 | const snap = parseSnapBack(await readBody(req)); |
| @@ -1242,6 +1250,7 @@ export async function startServer(bus: FeetechBus, options: ServerOptions = {}): | ||
| 1242 | 1250 | let releasing = false; |
| 1243 | 1251 | streamStats = stats; |
| 1244 | 1252 | const tracker = (tracking = precision.begin()); |
| 1253 | const tracing = setInterval(() => precision.sampleTrace(tracker), 1000 / TRACE_HZ); | |
| 1245 | 1254 | /** Snap-backs are counted once per episode: a joint held at its limit, a zone refusal, a run of stale frames. */ |
| 1246 | 1255 | const capped = new Set<number>(); |
| 1247 | 1256 | let refusing = false; |
| @@ -1547,6 +1556,7 @@ export async function startServer(bus: FeetechBus, options: ServerOptions = {}): | ||
| 1547 | 1556 | jams.clear(); |
| 1548 | 1557 | streamStats = null; |
| 1549 | 1558 | if (tracking === tracker) tracking = null; |
| 1559 | clearInterval(tracing); | |
| 1550 | 1560 | precision.end(tracker); |
| 1551 | 1561 | metrics.event("stream", { seconds: Number(((Date.now() - startedAt) / 1000).toFixed(1)), ...stats, ...(lost ? { lost: code } : {}) }); |
| 1552 | 1562 | 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"; | ||
| 12 | 12 | import { Lobby } from "./lobby.ts"; |
| 13 | 13 | import { startRelay, type RunningRelay } from "./relay.ts"; |
| 14 | 14 | 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"; | |
| 16 | 16 | import { jointRows } from "./ui/machine.js"; |
| 17 | 17 | import { Turns } from "./turns.ts"; |
| 18 | 18 | |
| @@ -756,3 +756,22 @@ describe("/tune", () => { | ||
| 756 | 756 | expect(refused).toEqual(["error: not found"]); |
| 757 | 757 | }); |
| 758 | 758 | }); |
| 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 @@ | ||
| 35 | 35 | * /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 |
| 36 | 36 | * /health owner or moderator: each open page's link as it last reported it (GET /admin/health, the page's Admin -> Health) |
| 37 | 37 | * /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) | |
| 38 | 39 | * /precision owner or moderator: the precision scorecard /admin shows (GET /precision, src/precision-panel.ts) |
| 39 | 40 | * /servos owner: each joint's servo control registers /admin shows (GET /servo-params, src/servo-panel.ts); 404 to anyone else |
| 40 | 41 | * /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 | ||
| 208 | 209 | }; |
| 209 | 210 | } |
| 210 | 211 | |
| 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 | ||
| 211 | 244 | /** The commits and the last sync outcome, one line each; a mismatch is flagged. */ |
| 212 | 245 | export function versionLines(v: Record<string, unknown> | null): string[] { |
| 213 | 246 | 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 => { | ||
| 321 | 354 | |
| 322 | 355 | const TUNE_USAGE = "usage: /tune <joint, e.g. shoulder_pan or 1> <P, 1 to 64>, or /tune alone for the run so far"; |
| 323 | 356 | 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"; | |
| 325 | 358 | |
| 326 | 359 | /** The Machine feed's socket beside the lobby's: same app, same port. */ |
| 327 | 360 | export const machineUrl = (live: string): string => live.replace(/\/live$/, "/machine"); |
| @@ -464,7 +497,7 @@ function target(room: Room, word: string): string | null { | ||
| 464 | 497 | return ID.test(word) ? word : null; |
| 465 | 498 | } |
| 466 | 499 | |
| 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; | |
| 468 | 501 | |
| 469 | 502 | /** What a typed line asks for. Validation the server repeats anyway; this only saves a round trip on a typo. */ |
| 470 | 503 | export function typed(room: Room, input: string): Typed { |
| @@ -551,6 +584,8 @@ export function typed(room: Room, input: string): Typed { | ||
| 551 | 584 | return { health: true }; |
| 552 | 585 | case "precision": |
| 553 | 586 | return { precision: true }; |
| 587 | case "trace": | |
| 588 | return /^\d{1,9}$/.test(arg) ? { trace: Number(arg) } : { print: "usage: /trace <session number, from /precision>" }; | |
| 554 | 589 | case "servos": |
| 555 | 590 | return { servos: true }; |
| 556 | 591 | case "versions": |
| @@ -584,11 +619,13 @@ export class Door { | ||
| 584 | 619 | private readonly readCard: ReadCard | null; |
| 585 | 620 | private readonly readServos: ReadServos | null; |
| 586 | 621 | private readonly readTuning: ReadTuning | null; |
| 622 | private readonly readTrace: ReadTrace | null; | |
| 587 | 623 | private readonly readVersions: ReadVersions | null; |
| 588 | 624 | private readonly readAlign: ReadAlign | null; |
| 589 | 625 | |
| 590 | 626 | /** `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; | |
| 592 | 629 | this.readAlign = readAlign; |
| 593 | 630 | this.readTuning = readTuning; |
| 594 | 631 | this.readVersions = readVersions; |
| @@ -639,6 +676,7 @@ export class Door { | ||
| 639 | 676 | else if ("align" in t) void this.align(t.align); |
| 640 | 677 | else if ("health" in t) void this.health(); |
| 641 | 678 | else if ("precision" in t) void this.precision(); |
| 679 | else if ("trace" in t) void this.trace(t.trace); | |
| 642 | 680 | else if ("servos" in t) void this.servos(); |
| 643 | 681 | else if ("tune" in t) void this.tune(t.tune); |
| 644 | 682 | else if ("versions" in t) void this.versions(); |
| @@ -677,6 +715,13 @@ export class Door { | ||
| 677 | 715 | for (const line of r.error || !r.panel ? [`error: ${r.error ?? "no scorecard"}`] : precisionLines(r.panel)) this.print(line); |
| 678 | 716 | } |
| 679 | 717 | |
| 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 | ||
| 680 | 725 | /** The server decides who may; a refusal is printed, else the joints' registers. */ |
| 681 | 726 | private async servos(): Promise<void> { |
| 682 | 727 | if (!this.readServos) return this.print("error: servos are not available here"); |
Software/so101/src/tty.ts +2 −2
| @@ -4,7 +4,7 @@ | ||
| 4 | 4 | */ |
| 5 | 5 | |
| 6 | 6 | 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"; | |
| 8 | 8 | |
| 9 | 9 | const env = process.env; |
| 10 | 10 | 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) => { | ||
| 17 | 17 | rl?.prompt(true); |
| 18 | 18 | }; |
| 19 | 19 | |
| 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)); | |
| 21 | 21 | print(`\x1b[1mSO-101 arm\x1b[0m · ${where} · ${HELP}`); |
| 22 | 22 | try { |
| 23 | 23 | await door.open(() => { |
new above
offline
Route exists on the arm only; the preview returns no such route. Proxy it in the relay and test that.