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

Migrated from github.com/Trevato/SO-ARM100

workbenchthis machine

Precision numbers that mean what they say: settle error and following lag, not lead during motion; n on every number #522

Merged opened this in answer to

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

Merged

quill/arm:quill/510-precision-numbers-that-mean-what-they-sa → main 9 commits fork

  • Merged. quill/510-precision-numbers-that-mean-what-they-sa was merged into main as c43d3a8.

Review

Sign in to review this change.
28 files changed +669 −222
Software/README.md +37 −10
@@ -1061,8 +1061,14 @@ commands, and cannot move the arm. `GET /metrics` is unchanged and is still the
10611061 Every change to how closely the arm follows is judged by one scorecard, measured on the arm server
10621062 (`src/precision.ts`) while a stream drives it:
10631063
1064 - **Tracking error**, per joint: the commanded target minus Present_Position at every read-back (each jam-watch
1065 sample, 100 ms by default), in ticks and degrees; p50, p95 and max.
1064 - **Settle error**, per joint, the precision number: |target − Present_Position| once the joint has arrived or
1065 stopped, i.e. the joint has stayed within 3 ticks and its target has not moved, for 250 ms. One sample per rest, in
1066 ticks and degrees. It is never sampled while the arm moves: then a target that leads the arm measures how far ahead
1067 the finger is, not error (the old "tracking error" did exactly that and read 79.5° p95, #510).
1068 - **Following lag**, per joint, ms: while the target streams (frames at most 100 ms apart), at each read-back of a
1069 moving joint, how long ago the target passed where the joint is now, going the same way (the intent taken as a
1070 straight line between frames; looked for up to 2 s back). A target that jumps after a pause is a step: it is chased,
1071 not followed, and is timed by time to arrive.
10661072 - **Time to arrive**: from a target being set, the joint more than 12 ticks from it, to the first read-back within
10671073 12 ticks. A target that moves during the chase extends the same chase. For 1 s after arriving the joint is watched:
10681074 **overshoot** (ticks past the target on the far side), **settling time** (to the last entry into the band) and
@@ -1071,9 +1077,12 @@ Every change to how closely the arm follows is judged by one scorecard, measured
10711077 a fixed list: `release-park` (the connection was lost and the arm parks), `hold-expired` (the dead-man held it short),
10721078 `zone`, `cap` (a joint limit), `stale-drop`, `maxStep-drop`, `jam`, `STOP`, `turn-end`, `reconnect`. A release is a
10731079 dead-man hold or the end of a stream; the headline is snap-backs per 100 releases.
1074 - **Latency by hop**: for now the arm server's own, a Goal_Position write to the first read-back more than 3 ticks
1075 from where the joint was (`bus→move`). The headline is the sum of the measured hops' p95. The hops through the
1076 browser and the relay, on aligned clocks, are #458; the page's own snap-backs and refusals are below.
1080 - **Latency by hop**, as in `Software/so101/README.md`. The headline is **command → first confirmed motion**, timed by
1081 the relay (`src/first-motion.ts`): from a frame it forwards for a joint at rest to the first status from the arm that
1082 shows that joint moved more than 3 ticks: every hop between, as the driver feels it. It is measured against the real
1083 arm only.
1084 - **n on every number.** Each spread is `{n, p50, p95, max}`; with n under 20 its p95 is `null` (a p95 of a handful is
1085 its max), and the panel, the terminal and the bench print a dash beside the n.
10771086
10781087 **Refusals and the page's snap-backs (#457).** Every frame the relay or the arm server drops, clamps or refuses (the
10791088 `clamp` entries of the Machine log: joint limit, too far in one frame, zone, jam, too many frames, not passed on, the
@@ -1092,8 +1101,9 @@ the arm server's data directory on the Pi. An hour keeps the worst of its sessio
10921101
10931102 Where to read it:
10941103
1095 - **Admin → Precision** (`/admin`, owner and moderators): the four headline numbers, a sparkline each over the
1096 stored sessions, the worst joint and the commit.
1104 - **Admin → Precision** (`/admin`, owner and moderators): the five headline numbers (settle error, following lag,
1105 time to arrive, snap-backs per 100 releases, command → motion), each with its n and a sparkline over the stored
1106 sessions, the worst joint (the highest median settle error) and the commit.
10971107 - **`/precision` in the terminal** (`$FORGE_APP_SSH`), owner and moderators: the same, as text.
10981108 - **`GET /precision` on the app** (the relay), owner and moderators, signed in as for `/admin`: the arm's scorecard
10991109 as JSON, from whichever arm is live (the simulation on a preview). Anyone else gets the ordinary 404
@@ -1102,7 +1112,7 @@ Where to read it:
11021112 `/metrics`): unauthenticated, for the crew's scripts on that network. It holds timing and position aggregates
11031113 only: no names, tokens or commands.
11041114
1105 `bun Software/so101/bench/limits-sweep.ts [url]` drives each joint in turn through a fixed set of targets inside its bounds (the others held still) and prints that joint's p95 error, time to arrive, overshoot and snap-backs from `/precision`; with no url it runs on the fake bus, with a url it refuses to start unless nobody is driving and stops at once on STOP or any refusal.
1115 `bun Software/so101/bench/limits-sweep.ts [url]` drives each joint in turn through a fixed set of targets inside its bounds (the others held still) and prints that joint's largest settle error and time to arrive (a sweep has too few of each for a p95), with n, its overshoot and snap-backs from `/precision`; with no url it runs on the fake bus, with a url it refuses to start unless nobody is driving and stops at once on STOP or any refusal.
11061116 The sweep's targets are fixed; the measured numbers move a little with the machine's timers.
11071117
11081118 `bun run Software/so101/bench/real-probe.ts <url> --joint N [--step ticks]` steps one joint a little (60 ticks by default, toward the middle of its bounds, clamped inside them) over `/follow`, samples `/status` at about 50 Hz and prints the time to arrive within 12 ticks, the final error and the overshoot. It refuses to start unless nobody is driving and there is no STOP or E-stop, stops at once if one appears, and always returns the joint to its start pose, even after an abort.
@@ -1118,7 +1128,7 @@ Open experiment: none yet
11181128 `bench/precision.ts` replays a fixed gesture script on the fake bus, through the real Governor, with servos that
11191129 follow their goals at 1500 ticks/s, and prints the same scorecard (`--json` for the whole card). Every precision pull
11201130 quotes its numbers before and after. As of #436 (the time to arrive moves by a few hundred ms from run to run with
1121 the machine's timers; the rest within a few percent):
1131 the machine's timers; the rest within a few percent). The numbers of #436, before #510 replaced tracking error:
11221132
11231133 ```
11241134 p95 tracking error 8.96 ° (worst joint: shoulder_lift)
@@ -1138,7 +1148,24 @@ by cause: cap 1, maxStep-drop 1
11381148 ```
11391149
11401150 The shoulder lift's p95 is the script walking it at 1500 ticks/s against the 90 °/s speed limit: the Governor's lag,
1141 which is what the instrument is for.
1151 measured as error. As of #510 the same script reads:
1152
1153 ```
1154 p95 settle error — (n 13) (worst joint: shoulder_pan)
1155 p95 following lag 202 ms (n 437)
1156 p95 time to arrive 861 ms (n 39)
1157 snap-backs 1 in 2 releases: 50 per 100
1158 p95 command→motion — (n 0) (by hop: …; bus→move p50 17 ms, p95 42 ms, n 555)
1159 a p95 needs n ≥ 20
1160
1161 joint settle err p50/p95/max ° (n) lag p50/p95 ms (n) arrive p50/p95 ms (n) overshoot max settle p95 ms osc
1162 shoulder_pan 0 / — / 0 (3) 113 / 152 (152) 436 / — (7) 1 — 0
1163 shoulder_lift 0 / — / 0 (2) 53 / 72 (137) 21 / 59 (21) 10 59 0
1164 gripper 0 / — / 0 (2) 129 / 224 (148) 452 / — (8) 5 — 0
1165 ```
1166
1167 The fake servos land exactly, so settle error is 0; the lag is the Governor's pace. Command → motion needs the relay
1168 and the real arm, so the bench has none.
11421169
11431170 ## Video trial
11441171
Software/so101/README.md +4 −3
@@ -31,7 +31,7 @@ Who sees what: a visitor's page says only "Pi update pending" while the commits
3131
3232 ## Reading the latency hops
3333
34 `GET /precision` has `hops`, each with `p50`, `p95` and `max` in ms, over the last ten minutes and per drive session; on `/admin` (Precision) and with `/precision` in the terminal (owner and moderators) they are listed as "latency by hop", p50 then p95. Each is one crossing, timed on clocks aligned by a four-timestamp ping, so none is skewed by the machines' clocks:
34 `GET /precision` has `hops`, each with `n`, `p50`, `p95` (null below n = 20) and `max` in ms, over the last ten minutes and per drive session; on `/admin` (Precision) and with `/precision` in the terminal (owner and moderators) they are listed as "latency by hop", p50 then p95, with n. Each is one crossing, timed on clocks aligned by a four-timestamp ping, so none is skewed by the machines' clocks:
3535
3636 | Hop | From → to, timed by |
3737 | --- | --- |
@@ -40,8 +40,9 @@ Who sees what: a visitor's page says only "Pi update pending" while the commits
4040 | `bus→move` | the arm server's own: a `Goal_Position` write to the first read-back past 3 ticks |
4141 | `read-back→relay` | the arm server stamps each status with its read time; the relay compares on arrival |
4242 | `read-back→browser` | the same stamp, carried to the page (on the relay's clock), compared there |
43 | `command→motion` | the relay alone, on its own clock: a frame it forwards for a joint at rest to the first status showing that joint moved past 3 ticks (`src/first-motion.ts`) |
4344
44 `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.
45 `commandToMotionMs` is the headline latency: end to end as the driver feels it, measured, not a sum of p95s. 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.
4546
4647 ## Reading a session's trace
4748
@@ -55,7 +56,7 @@ The owner can test a joint's P (the position gain, 1–64) on the real arm, with
5556
5657 1. sweeps the joint through the fixed targets of `bench/limits-sweep.ts`, through its own `/follow` stream, so the speed limits, zones and gripper torque cap apply as for a driver;
5758 2. writes the P (the guarded `PUT /servo-params` path) and sweeps again;
58 3. keeps the new P only if p95 tracking error and overshoot are both no worse and one is better; otherwise, and on any failure or STOP, writes the old P back.
59 3. keeps the new P only if settle error (the largest of the sweep's rests: too few for a p95) and overshoot are both no worse and one is better; otherwise, and on any failure or STOP, writes the old P back.
5960
6061 Nobody can drive while it runs, and it will not start while someone does (409; 423 on an E-stop or hold). Only one run at a time. Progress shows in the Servos section (reload the page) and with `/tune` alone, which also gives the last result (`GET /tuning`). Every result is stored with the deployed commit and listed newest first in the Precision panel (joint, P from→to, error and overshoot before→after, kept or put back) and as `tunings` in `GET /precision`. All of it is the owner's: anyone else gets 404.
6162
Software/so101/bench/limits-search.test.ts +1 −1
@@ -5,7 +5,7 @@ import { run, table } from "./limits-search.ts";
55 test("on the fake bus a joint's search ends in a table, and the arm's settings end at the 'after' limits", async () => {
66 const arm = await fakeArm();
77 try {
8 const found = await run(arm.url, [1], 300);
8 const found = await run(arm.url, [1], 700); // each target held to arrive and rest (REST_MS), so every sweep has a settle error
99 const md = table(found);
1010 expect(md.split("\n")).toHaveLength(3);
1111 expect(md).toContain("| shoulder_pan | 90 → ");
Software/so101/bench/limits-search.ts +3 −2
@@ -81,9 +81,10 @@ async function sweepJoint(url: string, id: number, hold: number): Promise<SweepR
8181 await sleep(150);
8282 }
8383 const j = session?.joints.find((x) => x.id === id);
84 if (!j || j.errorDeg.p95 === null) throw new Error("the sweep measured nothing");
84 // The error is settle error, where the limits show: a rest per target, too few for a p95, and of so few the p95 is the max.
85 if (!j || j.settleErrorDeg.max === null) throw new Error("the sweep measured nothing");
8586 if (session!.snapBacks.total) throw new Error("stopped: the arm refused or held back a target");
86 return { p95Error: j.errorDeg.p95, overshoot: j.overshootTicks.max ?? 0, timeToArrive: j.arriveMs.p95 ?? 0 };
87 return { p95Error: j.settleErrorDeg.p95 ?? j.settleErrorDeg.max, overshoot: j.overshootTicks.max ?? 0, timeToArrive: j.arriveMs.p95 ?? j.arriveMs.max ?? 0 };
8788 }
8889
8990 /** One joint's search and the sweep at its starting limits. */
Software/so101/bench/limits-sweep.ts +7 −3
@@ -39,10 +39,14 @@ export function targets(lo: number, hi: number): number[] {
3939 }
4040
4141 const fmt = (v: number | null, unit = "") => (v === null ? "—" : `${v}${unit}`);
42 /** One joint's line: a sweep has a rest and an arrival per target, too few for a p95, so the line gives the max. */
4243 export function line(name: string, j: JointCard | undefined, snaps: number): string {
43 return `${name.padEnd(14)} p95 error ${fmt(j?.errorDeg.p95 ?? null, "°").padEnd(8)} arrive ${fmt(j?.arriveMs.p95 ?? null, " ms").padEnd(8)} overshoot ${fmt(j?.overshootTicks.max ?? null, " ticks").padEnd(10)} snap-backs ${snaps}`;
44 return `${name.padEnd(14)} max settle error ${fmt(j?.settleErrorDeg.max ?? null, "°").padEnd(8)} (n ${j?.settleErrorDeg.n ?? 0}) max arrive ${fmt(j?.arriveMs.max ?? null, " ms").padEnd(8)} overshoot ${fmt(j?.overshootTicks.max ?? null, " ticks").padEnd(10)} snap-backs ${snaps}`;
4445 }
4546
47 /** The card's headline, each p95 with its n (a dash below 20). */
48 const headline = (c: Card) => `p95 settle error ${fmt(c.settleErrorDeg.p95, "°")} (n ${c.settleErrorDeg.n}), arrive ${fmt(c.arriveMs.p95, " ms")} (n ${c.arriveMs.n}), snap-backs ${c.snapBacks.total}`;
49
4650 /** Drives every joint through its targets and answers the lines, one per joint. Throws, naming why, where it must stop. */
4751 export async function sweep(url: string, hold = HOLD_MS, out: (s: string) => void = () => {}): Promise<string[]> {
4852 const status = await get<Status>(url, "/status");
@@ -50,7 +54,7 @@ export async function sweep(url: string, hold = HOLD_MS, out: (s: string) => voi
5054 const why = stopped(status);
5155 if (why) throw new Error(`refusing to start: ${why} is in force`);
5256 const before = await card(url);
53 out(`before: p95 error ${fmt(before.trackingP95Deg, "°")}, arrive ${fmt(before.arriveP95Ms, " ms")}, snap-backs ${before.snapBacks.total}`);
57 out(`before: ${headline(before)}`);
5458 const lines: string[] = [];
5559 let total = before.snapBacks.total;
5660 for (const joint of status.joints) {
@@ -81,7 +85,7 @@ export async function sweep(url: string, hold = HOLD_MS, out: (s: string) => voi
8185 lines.push(l);
8286 }
8387 const end = await card(url);
84 out(`after: p95 error ${fmt(end.trackingP95Deg, "°")}, arrive ${fmt(end.arriveP95Ms, " ms")}, snap-backs ${end.snapBacks.total}`);
88 out(`after: ${headline(end)}`);
8589 return lines;
8690 }
8791
Software/so101/bench/precision-report.test.ts +18 −13
@@ -8,21 +8,25 @@ const row = (daysAgo: number, o: Partial<Row>): Row => ({
88 commit: "abc",
99 sessions: 1,
1010 seconds: 60,
11 trackingP95Deg: 5,
12 trackingMaxDeg: 9,
11 settleErrorP95Deg: 5,
12 settleErrorN: 20,
13 lagP95Ms: 80,
14 lagN: 100,
1315 arriveP95Ms: 400,
16 arriveN: 20,
17 commandToMotionP95Ms: 20,
18 commandToMotionN: 30,
1419 snapBacks: 1,
1520 releases: 10,
16 latencyP95Ms: 20,
1721 worstJoint: "elbow_flex",
1822 ...o,
1923 });
2024
2125 const hours: Row[] = [
22 row(10, { trackingP95Deg: 9, arriveP95Ms: 600, latencyP95Ms: 30, snapBacks: 2, releases: 10, worstJoint: "wrist_flex" }),
23 row(9, { trackingP95Deg: 7 }),
24 row(3, { trackingP95Deg: 4, arriveP95Ms: 500, latencyP95Ms: 25, snapBacks: 1, releases: 10, worstJoint: "shoulder_lift" }),
25 row(1, { trackingP95Deg: 6, arriveP95Ms: 450, latencyP95Ms: 15, snapBacks: 0, releases: 10, worstJoint: "shoulder_pan" }),
26 row(10, { settleErrorP95Deg: 9, arriveP95Ms: 600, commandToMotionP95Ms: 30, snapBacks: 2, releases: 10, worstJoint: "wrist_flex" }),
27 row(9, { settleErrorP95Deg: 7 }),
28 row(3, { settleErrorP95Deg: 4, lagP95Ms: 90, arriveP95Ms: 500, commandToMotionP95Ms: 25, snapBacks: 1, releases: 10, worstJoint: "shoulder_lift" }),
29 row(1, { settleErrorP95Deg: 6, lagP95Ms: null, lagN: 5, arriveP95Ms: 450, commandToMotionP95Ms: 15, snapBacks: 0, releases: 10, worstJoint: "shoulder_pan" }),
2630 ];
2731
2832 test("the report sets this week beside last, with the worst joint and the experiment", () => {
@@ -31,12 +35,13 @@ test("the report sets this week beside last, with the worst joint and the experi
3135
3236 | | this week | last week | change |
3337 |---|---|---|---|
34 | p95 tracking error | 6.00 ° | 9.00 ° | -3.00 ° |
35 | p95 time to arrive | 500 ms | 600 ms | -100 ms |
36 | p95 latency | 25 ms | 30 ms | -5 ms |
37 | snap-backs per 100 releases | 5.0 | 15.0 | -10.0 |
38 | p95 settle error | 6.00 ° (n 40) | 9.00 ° (n 40) | -3.00 ° |
39 | p95 following lag | 90 ms (n 105) | 80 ms (n 200) | +10 ms |
40 | p95 time to arrive | 500 ms (n 40) | 600 ms (n 40) | -100 ms |
41 | p95 command → motion | 25 ms (n 60) | 30 ms (n 60) | -5 ms |
42 | snap-backs per 100 releases | 5.0 (n 20) | 15.0 (n 20) | -10.0 |
3843
39 Hours measured: 2 this week, 2 last. Lower is better in every row; each is the worst hour's p95.
44 Hours measured: 2 this week, 2 last. Lower is better in every row; each p95 is the worst hour's, n is the week's samples, and an hour with n under 20 gives no p95.
4045
4146 **Worst joint:** shoulder_pan (last week: wrist_flex)
4247
@@ -46,7 +51,7 @@ Hours measured: 2 this week, 2 last. Lower is better in every row; each is the w
4651
4752 test("an empty history and a missing experiment print dashes, not a crash", () => {
4853 const text = report({ hours: [], commit: "abc" }, NOW, null);
49 expect(text).toContain("| p95 tracking error | – | – | – |");
54 expect(text).toContain("| p95 settle error | – (n 0) | – (n 0) | – |");
5055 expect(text).toContain("none measured");
5156 expect(text).toContain("none named");
5257 });
Software/so101/bench/precision-report.ts +33 −16
@@ -12,33 +12,47 @@ const WEEK_MS = 7 * 24 * 3600_000;
1212 const HOURS = 14 * 24;
1313 const README = join(import.meta.dir, "../../README.md");
1414
15 /** One week of hours, reduced to the four headline numbers: the worst hour of each p95, snap-backs pooled. */
15 /** One week of hours, reduced to the headline numbers: the worst hour of each p95, its n summed, snap-backs pooled. */
1616 export interface Week {
1717 hours: number;
18 trackingP95Deg: number | null;
18 settleErrorP95Deg: number | null;
19 settleErrorN: number;
20 lagP95Ms: number | null;
21 lagN: number;
1922 arriveP95Ms: number | null;
20 latencyP95Ms: number | null;
23 arriveN: number;
24 commandToMotionP95Ms: number | null;
25 commandToMotionN: number;
2126 snapBacksPer100: number | null;
27 /** The n of the snap-back rate. */
28 releases: number;
2229 worstJoint: string | null;
2330 }
2431
2532 const worst = (xs: (number | null)[]): number | null => xs.reduce<number | null>((m, x) => (x === null ? m : m === null || x > m ? x : m), null);
33 const sum = (xs: (number | null | undefined)[]): number => xs.reduce<number>((n, x) => n + (x ?? 0), 0);
2634
2735 export function week(rows: readonly Row[], from: number, to: number): Week {
2836 const mine = rows.filter((r) => {
2937 const t = Date.parse(r.at);
3038 return t > from && t <= to;
3139 });
32 const releases = mine.reduce((n, r) => n + r.releases, 0);
33 const snaps = mine.reduce((n, r) => n + r.snapBacks, 0);
34 const hot = mine.filter((r) => r.trackingP95Deg !== null && r.worstJoint).sort((a, b) => b.trackingP95Deg! - a.trackingP95Deg!)[0];
40 const releases = sum(mine.map((r) => r.releases));
41 const snaps = sum(mine.map((r) => r.snapBacks));
42 const hot = mine.filter((r) => r.settleErrorP95Deg !== null && r.worstJoint).sort((a, b) => b.settleErrorP95Deg! - a.settleErrorP95Deg!)[0];
3543 return {
3644 hours: mine.length,
37 trackingP95Deg: worst(mine.map((r) => r.trackingP95Deg)),
45 settleErrorP95Deg: worst(mine.map((r) => r.settleErrorP95Deg)),
46 settleErrorN: sum(mine.map((r) => r.settleErrorN)),
47 lagP95Ms: worst(mine.map((r) => r.lagP95Ms)),
48 lagN: sum(mine.map((r) => r.lagN)),
3849 arriveP95Ms: worst(mine.map((r) => r.arriveP95Ms)),
39 latencyP95Ms: worst(mine.map((r) => r.latencyP95Ms)),
50 arriveN: sum(mine.map((r) => r.arriveN)),
51 commandToMotionP95Ms: worst(mine.map((r) => r.commandToMotionP95Ms)),
52 commandToMotionN: sum(mine.map((r) => r.commandToMotionN)),
4053 snapBacksPer100: releases > 0 ? (snaps / releases) * 100 : null,
41 worstJoint: hot?.worstJoint ?? null,
54 releases,
55 worstJoint: hot?.worstJoint ?? mine.findLast((r) => r.worstJoint)?.worstJoint ?? null,
4256 };
4357 }
4458
@@ -58,19 +72,22 @@ function delta(now: number | null, before: number | null, digits: number, unit:
5872 export function report(card: Pick<Scorecard, "hours" | "commit">, now: number, open: string | null): string {
5973 const cur = week(card.hours, now - WEEK_MS, now);
6074 const prev = week(card.hours, now - 2 * WEEK_MS, now - WEEK_MS);
61 const line = (name: string, key: "trackingP95Deg" | "arriveP95Ms" | "latencyP95Ms" | "snapBacksPer100", digits: number, unit: string) =>
62 `| ${name} | ${num(cur[key], digits, unit)} | ${num(prev[key], digits, unit)} | ${delta(cur[key], prev[key], digits, unit)} |`;
75 type Key = "settleErrorP95Deg" | "lagP95Ms" | "arriveP95Ms" | "commandToMotionP95Ms" | "snapBacksPer100";
76 type N = "settleErrorN" | "lagN" | "arriveN" | "commandToMotionN" | "releases";
77 const cell = (w: Week, key: Key, n: N, digits: number, unit: string) => `${num(w[key], digits, unit)} (n ${w[n]})`;
78 const line = (name: string, key: Key, n: N, digits: number, unit: string) => `| ${name} | ${cell(cur, key, n, digits, unit)} | ${cell(prev, key, n, digits, unit)} | ${delta(cur[key], prev[key], digits, unit)} |`;
6379 return [
6480 `## Precision, week to ${new Date(now).toISOString().slice(0, 10)}`,
6581 "",
6682 "| | this week | last week | change |",
6783 "|---|---|---|---|",
68 line("p95 tracking error", "trackingP95Deg", 2, " °"),
69 line("p95 time to arrive", "arriveP95Ms", 0, " ms"),
70 line("p95 latency", "latencyP95Ms", 0, " ms"),
71 line("snap-backs per 100 releases", "snapBacksPer100", 1, ""),
84 line("p95 settle error", "settleErrorP95Deg", "settleErrorN", 2, " °"),
85 line("p95 following lag", "lagP95Ms", "lagN", 0, " ms"),
86 line("p95 time to arrive", "arriveP95Ms", "arriveN", 0, " ms"),
87 line("p95 command → motion", "commandToMotionP95Ms", "commandToMotionN", 0, " ms"),
88 line("snap-backs per 100 releases", "snapBacksPer100", "releases", 1, ""),
7289 "",
73 `Hours measured: ${cur.hours} this week, ${prev.hours} last. Lower is better in every row; each is the worst hour's p95.`,
90 `Hours measured: ${cur.hours} this week, ${prev.hours} last. Lower is better in every row; each p95 is the worst hour's, n is the week's samples, and an hour with n under 20 gives no p95.`,
7491 "",
7592 `**Worst joint:** ${cur.worstJoint ?? "none measured"}${prev.worstJoint ? ` (last week: ${prev.worstJoint})` : ""}`,
7693 "",
Software/so101/bench/precision.test.ts +10 −7
@@ -8,14 +8,17 @@ test("the gesture script is fixed: the same frames every run", () => {
88
99 test("a short script on the fake bus gives a scorecard with every headline number", async () => {
1010 const card = await bench([
11 // each pose held well past REST_MS (250 ms) to arrive and rest even on a loaded machine
1112 { at: 0, joints: { 1: 2048 } },
12 { at: 400, joints: { 1: 2348 } },
13 { at: 900, joints: { 1: 2000 } }, // 348 ticks back: within maxStep
14 { at: 1000, joints: { 1: 2900 } }, // 900 ticks in one frame: followed, not dropped
13 { at: 800, joints: { 1: 2348 } },
14 { at: 1800, joints: { 1: 2000 } }, // 348 ticks back: within maxStep
15 { at: 1900, joints: { 1: 2900 } }, // 900 ticks in one frame: followed, not dropped
1516 ]);
16 expect(card.trackingP95Deg).not.toBeNull();
17 expect(card.arriveP95Ms).toBeGreaterThan(0);
18 expect(card.latencyP95Ms).toBeGreaterThan(0);
17 expect(card.settleErrorDeg.n).toBeGreaterThan(0);
18 expect(card.arriveMs.n).toBeGreaterThan(0);
19 expect(card.arriveMs.p50).toBeGreaterThan(0);
20 expect(card.hops["bus→move"]!.n).toBeGreaterThan(0);
1921 expect(card.snapBacks.byCause["maxStep-drop"] ?? 0).toBe(0);
20 expect(render(card)).toContain("p95 tracking error");
22 expect(render(card)).toContain("p95 settle error");
23 expect(render(card)).toMatch(/p95 time to arrive +— \(n \d\)/); // a handful of arrivals: no p95
2124 }, 10_000);
Software/so101/bench/precision.ts +18 −6
@@ -13,7 +13,7 @@ import WebSocket from "ws";
1313 import { FeetechBus } from "../src/bus.ts";
1414 import { wallMs } from "../src/clock.ts";
1515 import { FakeBus } from "../src/fake-bus.ts";
16 import type { Card } from "../src/precision.ts";
16 import { MIN_N_FOR_P95, type Card, type Spread } from "../src/precision.ts";
1717 import type { Scorecard } from "../src/precision-history.ts";
1818 import { startServer } from "../src/server.ts";
1919
@@ -97,18 +97,30 @@ export async function bench(script: readonly Step[] = gesture()): Promise<Card>
9797 }
9898
9999 const show = (v: number | null, unit: string) => (v === null ? "—" : `${v} ${unit}`);
100 /** A spread's p95 with its n; a dash for a p95 of fewer than MIN_N_FOR_P95. */
101 const p95 = (s: Spread, unit: string) => `${show(s.p95, unit)} (n ${s.n})`;
100102
101103 /** The scorecard as text: the headline, then a line per joint, then the snap-backs by cause. */
102104 export function render(card: Card): string {
103105 const lines = [
104 `p95 tracking error ${show(card.trackingP95Deg, "°")} (worst joint: ${card.worstJoint ?? "—"})`,
105 `p95 time to arrive ${show(card.arriveP95Ms, "ms")}`,
106 `p95 settle error ${p95(card.settleErrorDeg, "°")} (worst joint: ${card.worstJoint ?? "—"})`,
107 `p95 following lag ${p95(card.lagMs, "ms")}`,
108 `p95 time to arrive ${p95(card.arriveMs, "ms")}`,
106109 `snap-backs ${card.snapBacks.total} in ${card.releases} releases: ${show(card.snapBacksPer100Releases, "per 100")}`,
107 `p95 latency ${show(card.latencyP95Ms, "ms")} (${Object.entries(card.hops).map(([hop, s]) => `${hop} p50 ${show(s.p50, "ms")}, p95 ${show(s.p95, "ms")}`).join("; ")})`,
110 `p95 command→motion ${p95(card.commandToMotionMs, "ms")} (by hop: ${Object.entries(card.hops).map(([hop, s]) => `${hop} p50 ${show(s.p50, "ms")}, p95 ${show(s.p95, "ms")}, n ${s.n}`).join("; ")})`,
111 `a p95 needs n ≥ ${MIN_N_FOR_P95}`,
108112 "",
109 "joint err p50/p95/max ° arrive p50/p95 ms overshoot max settle p95 ms osc",
113 "joint settle err p50/p95/max ° (n) lag p50/p95 ms (n) arrive p50/p95 ms (n) overshoot max settle p95 ms osc",
110114 ...card.joints.map((j) =>
111 [(j.joint ?? String(j.id)).padEnd(16), `${j.errorDeg.p50 ?? "—"} / ${j.errorDeg.p95 ?? "—"} / ${j.errorDeg.max ?? "—"}`.padEnd(21), `${j.arriveMs.p50 ?? "—"} / ${j.arriveMs.p95 ?? "—"}`.padEnd(19), String(j.overshootTicks.max ?? "—").padEnd(15), String(j.settleMs.p95 ?? "—").padEnd(15), j.oscillations].join(" "),
115 [
116 (j.joint ?? String(j.id)).padEnd(16),
117 `${j.settleErrorDeg.p50 ?? "—"} / ${j.settleErrorDeg.p95 ?? "—"} / ${j.settleErrorDeg.max ?? "—"} (${j.settleErrorDeg.n})`.padEnd(30),
118 `${j.lagMs.p50 ?? "—"} / ${j.lagMs.p95 ?? "—"} (${j.lagMs.n})`.padEnd(20),
119 `${j.arriveMs.p50 ?? "—"} / ${j.arriveMs.p95 ?? "—"} (${j.arriveMs.n})`.padEnd(23),
120 String(j.overshootTicks.max ?? "—").padEnd(15),
121 String(j.settleMs.p95 ?? "—").padEnd(15),
122 j.oscillations,
123 ].join(" "),
112124 ),
113125 "",
114126 `by cause: ${Object.entries(card.snapBacks.byCause).filter(([, n]) => n).map(([c, n]) => `${c} ${n}`).join(", ") || "none"}`,
Software/so101/src/admin-page.ts +1
@@ -62,6 +62,7 @@ th { color: var(--dim); font-weight: 600; }
6262 .bars li span:nth-child(2) { color: var(--blue); }
6363 .bars li b { color: var(--fg); font-weight: 600; }
6464 .bars.precision li { grid-template-columns: minmax(8rem, 15rem) 1fr; }
65 .bars.precision li small { color: var(--dim); font-size: .85em; }
6566 .inline { display: inline; margin: 0; }
6667 .empty { color: var(--dim); }
6768 @media (prefers-reduced-motion: reduce) { * { transition: none !important; } }
Software/so101/src/facts.test.ts +3 −3
@@ -39,7 +39,7 @@ test("a turn is written when it ends, with its wait in line, and takes its card
3939 t = 91_000;
4040 const id = facts.turn({ kind: "turn", ended: { who: person("bob"), reason: "time is up" }, started: null }, snap());
4141 expect(id).not.toBeNull();
42 facts.card(id!, parseCard({ session: { releases: 4, arriveP95Ms: 120, snapBacks: { total: 3, byCause: { jam: 2, STOP: 1, zone: 0 } } } })!);
42 facts.card(id!, parseCard({ session: { releases: 4, arriveMs: { n: 25, p95: 120 }, snapBacks: { total: 3, byCause: { jam: 2, STOP: 1, zone: 0 } } } })!);
4343 const [row] = facts.turns();
4444 expect(row).toMatchObject({ seconds: 60, waitSeconds: 30, ended: "time is up", releases: 4, snapBacks: { jam: 2, STOP: 1 }, jams: 2, arriveP95Ms: 120, commit: "c" });
4545 expect(row!.who).toMatch(/^[0-9a-f]{16}$/);
@@ -52,10 +52,10 @@ test("a turn nobody saw begin is not invented", () => {
5252 });
5353
5454 test("card parsing takes the session, else the window, and ignores what is not a card", () => {
55 expect(parseCard({ session: null, window: { releases: 2, arriveP95Ms: null, snapBacks: { byCause: { cap: 1, bogus: 9 } } } })).toEqual({ releases: 2, snapBacks: { cap: 1 }, jams: 0, arriveP95Ms: null });
55 expect(parseCard({ session: null, window: { releases: 2, arriveMs: { n: 3, p95: null }, snapBacks: { byCause: { cap: 1, bogus: 9 } } } })).toEqual({ releases: 2, snapBacks: { cap: 1 }, jams: 0, arriveP95Ms: null });
5656 expect(parseCard({ session: null, window: null })).toBeNull();
5757 expect(parseCard("nope")).toBeNull();
58 expect(parseCard({ session: { releases: -1, arriveP95Ms: "x" } })).toEqual({ releases: 0, snapBacks: {}, jams: 0, arriveP95Ms: null });
58 expect(parseCard({ session: { releases: -1, arriveMs: { p95: "x" } } })).toEqual({ releases: 0, snapBacks: {}, jams: 0, arriveP95Ms: null });
5959 });
6060
6161 test("rows older than 90 days are dropped, on open and with the samples", () => {
Software/so101/src/facts.ts +1 −1
@@ -43,7 +43,7 @@ export function parseCard(body: unknown): TurnCard | null {
4343 const by = (card.snapBacks as { byCause?: Record<string, unknown> } | null)?.byCause ?? {};
4444 const snapBacks: Partial<Record<Cause, number>> = {};
4545 for (const cause of CAUSES) if (count(by[cause]) > 0) snapBacks[cause] = count(by[cause]);
46 const p95 = card.arriveP95Ms;
46 const p95 = (card.arriveMs as { p95?: unknown } | null)?.p95;
4747 return { releases: count(card.releases), snapBacks, jams: snapBacks.jam ?? 0, arriveP95Ms: typeof p95 === "number" && Number.isFinite(p95) ? p95 : null };
4848 }
4949
Software/so101/src/first-motion.test.ts added +41
@@ -0,0 +1,41 @@
1 import { describe, expect, test } from "bun:test";
2 import { FirstMotion, MAX_WAIT_MS } from "./first-motion.ts";
3
4 const at = (id: number, position: number) => [{ id, position }];
5
6 describe("command → first confirmed motion", () => {
7 test("from the command to a joint at rest to the first status that shows it moved past MOVE_TICKS; later frames of the same move are not timed again", () => {
8 const m = new FirstMotion();
9 m.status(at(1, 2000), 0);
10 m.status(at(1, 2001), 40); // at rest
11 m.command(new Map([[1, 2300]]), 100);
12 m.command(new Map([[1, 2310]]), 133); // the same wait
13 expect(m.status(at(1, 2003), 140)).toEqual([]);
14 expect(m.status(at(1, 2020), 180)).toEqual([80]);
15 m.command(new Map([[1, 2400]]), 190); // moving: a command now would time the status gap, not the arm
16 expect(m.status(at(1, 2060), 220)).toEqual([]);
17 });
18
19 test("a joint not known to be at rest, a target within reach, a wait past MAX_WAIT_MS, or a forgotten one is not timed", () => {
20 const m = new FirstMotion();
21 m.command(new Map([[1, 2300]]), 0); // never seen
22 m.status(at(1, 2000), 10);
23 expect(m.status(at(1, 2100), 20)).toEqual([]);
24 m.status(at(1, 2100), 30);
25 m.command(new Map([[1, 2102]]), 40);
26 expect(m.status(at(1, 2110), 50)).toEqual([]);
27 m.status(at(1, 2110), 60);
28 m.command(new Map([[1, 2500]]), 70);
29 expect(m.status(at(1, 2200), 71 + MAX_WAIT_MS)).toEqual([]);
30 m.status(at(1, 2200), 3000);
31 m.command(new Map([[1, 2500]]), 3010);
32 m.forget();
33 expect(m.status(at(1, 2300), 3050)).toEqual([]);
34 });
35
36 test("a status that is not a list of joints, or a joint without a numeric position, is ignored", () => {
37 const m = new FirstMotion();
38 expect(m.status("nope", 0)).toEqual([]);
39 expect(m.status([null, { id: "1", position: 2 }, { id: 1, position: Number.NaN }], 0)).toEqual([]);
40 });
41 });
Software/so101/src/first-motion.ts added +54
@@ -0,0 +1,54 @@
1 /**
2 * Command → first confirmed motion, as the relay sees it: from a command it forwards for a joint at rest to the first
3 * status from the arm server that shows the joint has moved past MOVE_TICKS. That is the latency a driver feels, every
4 * hop between included. Plain data in (frames sent, statuses come in, each with the relay's time), plain data out (ms).
5 *
6 * A joint is at rest when two statuses in a row put it within MOVE_TICKS: a command to a joint already moving would
7 * time the gap between statuses, not the arm. Frames that come while a joint has yet to move extend the same wait, so a
8 * stream is timed by its first frame; a wait the joint never answers (a cap, a hold) is dropped after MAX_WAIT_MS.
9 */
10
11 import { MOVE_TICKS } from "./precision.ts";
12
13 /** Longest a command waits for its joint to move before it is not timed at all, ms. */
14 export const MAX_WAIT_MS = 2000;
15
16 export class FirstMotion {
17 /** The last read-back of each joint and whether it is at rest. */
18 readonly #known = new Map<number, { position: number; still: boolean }>();
19 readonly #waiting = new Map<number, { at: number; from: number }>();
20
21 /** A frame went to the arm server: joint id → target ticks. */
22 command(joints: ReadonlyMap<number, number>, at: number): void {
23 for (const [id, target] of joints) {
24 const known = this.#known.get(id);
25 if (!known?.still || this.#waiting.has(id) || Math.abs(target - known.position) <= MOVE_TICKS) continue;
26 this.#waiting.set(id, { at, from: known.position });
27 }
28 }
29
30 /** A status came in; the waits it ends, ms each. */
31 status(joints: unknown, at: number): number[] {
32 const timed: number[] = [];
33 if (!Array.isArray(joints)) return timed;
34 for (const j of joints as Array<{ id?: unknown; position?: unknown }>) {
35 if (!j || !Number.isInteger(j.id) || typeof j.position !== "number" || !Number.isFinite(j.position)) continue;
36 const id = j.id as number, position = j.position;
37 const before = this.#known.get(id);
38 this.#known.set(id, { position, still: before !== undefined && Math.abs(position - before.position) <= MOVE_TICKS });
39 const wait = this.#waiting.get(id);
40 if (!wait) continue;
41 if (at - wait.at > MAX_WAIT_MS) this.#waiting.delete(id);
42 else if (Math.abs(position - wait.from) > MOVE_TICKS) {
43 timed.push(Math.max(0, at - wait.at));
44 this.#waiting.delete(id);
45 }
46 }
47 return timed;
48 }
49
50 /** The stream ended: nothing it sent is waited for any more. */
51 forget(): void {
52 this.#waiting.clear();
53 }
54 }
Software/so101/src/jam-stream.test.ts +2 −1
@@ -53,7 +53,8 @@ describe("a jam is load without progress", () => {
5353 }, 10_000);
5454
5555 test("a joint held against a stop jams within 500 ms, and the page is told why", async () => {
56 const ws = await boot([2], 100);
56 // JAM_WINDOW_MS (300) of readings decides; sampled every 50 ms a late sample on a busy machine still lands inside 500
57 const ws = await boot([2], 50);
5758 const asked = performance.now();
5859 const push = setInterval(() => ws.send(JSON.stringify({ 1: START + 300, 2: START + 300 })), 20);
5960 let s = await get<Status>("/status");
Software/so101/src/precision-history.test.ts +49 −15
@@ -1,4 +1,5 @@
11 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
2 import { Database } from "bun:sqlite";
23 import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
34 import { tmpdir } from "node:os";
45 import { join } from "node:path";
@@ -20,8 +21,12 @@ describe("the history", () => {
2021 const history = new PrecisionHistory({ file, commit: "abc1234", now: () => now });
2122 for (const short of [10, 100]) {
2223 const t = history.begin();
23 t.target(1, 2048, now);
24 t.sample(1, 2048 - short, now + 10);
24 // Twenty rests, each `short` ticks from its target: enough for a p95.
25 for (let i = 0; i < 20; i++) {
26 const target = 2048 + (i % 2) * 200;
27 t.target(1, target, now + i * 1000);
28 for (let dt = 0; dt <= 300; dt += 50) t.sample(1, target - short, now + i * 1000 + dt);
29 }
2530 t.release(now + 20);
2631 t.snapBack("jam", now + 20, 1, short);
2732 now += 60_000;
@@ -33,25 +38,53 @@ describe("the history", () => {
3338 expect(card.commit).toBe("def5678");
3439 expect(card.sessions).toHaveLength(2);
3540 expect(card.sessions.map((r) => r.commit)).toEqual(["abc1234", "abc1234"]);
36 expect(card.sessions[1]!.trackingP95Deg).toBeCloseTo(8.79, 1);
41 expect(card.sessions[1]).toMatchObject({ settleErrorN: 20, lagN: 0, lagP95Ms: null, commandToMotionN: 0 });
42 expect(card.sessions[1]!.settleErrorP95Deg).toBeCloseTo(8.79, 1);
3743 expect(card.hours).toHaveLength(1);
38 expect(card.hours[0]).toMatchObject({ at: "2026-10-21T10:00:00.000Z", commit: "abc1234", sessions: 2, snapBacks: 2, releases: 2, worstJoint: "shoulder_pan" });
39 // the hour keeps the worse session's p95
40 expect(card.hours[0]!.trackingP95Deg).toBeCloseTo(8.79, 1);
44 expect(card.hours[0]).toMatchObject({ at: "2026-10-21T10:00:00.000Z", commit: "abc1234", sessions: 2, snapBacks: 2, releases: 2, worstJoint: "shoulder_pan", settleErrorN: 40 });
45 // the hour keeps the worse session's p95, and sums the n
46 expect(card.hours[0]!.settleErrorP95Deg).toBeCloseTo(8.79, 1);
4147 again.close();
4248 });
4349
50 test("a file from before settle error gains its columns: the old rows read as unmeasured, new ones are kept beside them", () => {
51 const file = join(mkdtempSync(join(tmpdir(), "so101-precision-old-")), "precision.sqlite");
52 const old = new Database(file);
53 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,
54 snap_backs INTEGER NOT NULL, releases INTEGER NOT NULL, latency_p95_ms REAL, worst_joint TEXT`;
55 old.run(`CREATE TABLE sessions (id INTEGER PRIMARY KEY, at TEXT NOT NULL, ${columns}, card TEXT NOT NULL)`);
56 old.run(`CREATE TABLE hours (at TEXT NOT NULL, ${columns}, PRIMARY KEY (at, commit_id))`);
57 old.run(`INSERT INTO sessions (at, commit_id, sessions, seconds, tracking_p95_deg, arrive_p95_ms, snap_backs, releases, latency_p95_ms, worst_joint, card) VALUES ('2026-10-20T10:00:00.000Z', 'old', 1, 30, 79.5, 400, 1, 2, 40, 'wrist_flex', '{}')`);
58 old.run(`INSERT INTO hours (at, commit_id, sessions, seconds, tracking_p95_deg, arrive_p95_ms, snap_backs, releases, latency_p95_ms, worst_joint) VALUES ('2026-10-21T10:00:00.000Z', 'new', 1, 30, 79.5, 400, 1, 2, 40, 'wrist_flex')`);
59 old.close();
60 const now = Date.UTC(2026, 9, 21, 10, 30);
61 const history = new PrecisionHistory({ file, commit: "new", now: () => now });
62 const t = history.begin();
63 t.target(1, 2048, now - 1000);
64 for (let at = now - 1000; at <= now - 600; at += 50) t.sample(1, 2040, at);
65 history.end(t);
66 const card = history.scorecard();
67 expect(card.sessions[0]).toMatchObject({ commit: "old", settleErrorP95Deg: null, settleErrorN: 0, arriveP95Ms: 400, snapBacks: 1 });
68 expect(card.sessions[1]).toMatchObject({ commit: "new", settleErrorN: 1, settleErrorP95Deg: null });
69 expect(card.hours[0]).toMatchObject({ commit: "new", sessions: 2, settleErrorN: 1, releases: 2 });
70 history.close();
71 });
72
4473 test("the window is the last ten minutes, and a session that measured nothing is not stored", () => {
4574 let now = 0;
4675 const history = new PrecisionHistory({ commit: "abc1234", now: () => now });
4776 const t = history.begin();
4877 t.target(1, 2048, 0);
49 t.sample(1, 2000, 0);
50 expect(history.scorecard().session?.joints[0]?.errorTicks.n).toBe(1);
78 for (let at = 0; at <= 300; at += 50) t.sample(1, 2000, at);
79 expect(history.scorecard().session?.joints[0]?.settleErrorTicks).toMatchObject({ n: 1, p50: 48, p95: null });
5180 history.end(t);
5281 now = HOUR;
53 expect(history.scorecard().window.trackingP95Deg).toBeNull();
54 expect(history.end(history.begin()).trackingP95Deg).toBeNull();
82 expect(history.scorecard().window.settleErrorDeg.n).toBe(0);
83 expect(history.end(history.begin()).settleErrorDeg.n).toBe(0);
84 const moved = history.begin();
85 moved.target(1, 2048, now);
86 moved.sample(1, 2000, now); // a target and one read-back: nothing measured
87 history.end(moved);
5588 expect(history.scorecard().sessions).toHaveLength(1);
5689 });
5790
@@ -83,11 +116,11 @@ describe("GET /precision on the arm server", () => {
83116 afterAll(() => Promise.race([server.close(), sleep(500)]));
84117 const card = async () => (await (await fetch(`${base}/precision`)).json()) as Scorecard;
85118
86 test("a stream's tracking error is measured, and a limit, a jump, a jam and a STOP are snap-backs with their cause", async () => {
119 test("a stream's following lag and settle error are measured, and a limit, a jump, a jam and a STOP are snap-backs with their cause", async () => {
87120 const ws = new WebSocket(`ws://127.0.0.1:${server.port}/follow`);
88121 await new Promise((r) => ws.once("open", r));
89122 ws.send(JSON.stringify({ "1": 2100 }));
90 await sleep(150);
123 await sleep(500); // there and at rest: a settle error
91124 for (const t of [2450, 2800, 3150]) {
92125 ws.send(JSON.stringify({ "1": t }));
93126 await sleep(60);
@@ -102,7 +135,7 @@ describe("GET /precision on the arm server", () => {
102135 await sleep(400);
103136 const live = await card();
104137 expect(live.commit).toBe("feed123");
105 expect(live.session?.joints.find((j) => j.id === 1)?.errorTicks.n).toBeGreaterThan(0);
138 expect(live.session?.joints.find((j) => j.id === 1)?.lagMs.n).toBeGreaterThan(0);
106139 ws.send(JSON.stringify({ "1": 3100 })); // 357 ticks away at 90°/s: still on its way when the stop comes
107140 await sleep(80);
108141 const gone = new Promise((r) => ws.once("close", r)); // before the stop: the socket may close before its answer comes
@@ -123,7 +156,7 @@ describe("GET /precision on the arm server", () => {
123156 expect(causes.jam).toBe(1);
124157 expect(causes.STOP).toBe(1);
125158 expect(after.window.releases).toBe(1);
126 expect(after.window.trackingP95Deg).not.toBeNull();
159 expect(after.window.settleErrorDeg.n).toBeGreaterThan(0);
127160 });
128161
129162 test("stamped frames time relay→Pi, unstamped ones are accepted and not counted, and the watch answers the clock ping and takes the read-back hop", async () => {
@@ -158,7 +191,7 @@ describe("GET /precision on the arm server", () => {
158191 expect(pong.t1).toBeGreaterThanOrEqual(t0);
159192 expect(heard.find((m) => m.joints)!.readAt).toBeGreaterThanOrEqual(t0 - 1000);
160193 const back = (await hops())[READ_BACK_HOP]!;
161 expect(back).toMatchObject({ n: 3, p50: 4, p95: 6 });
194 expect(back).toEqual({ n: 3, p50: 4, p95: null, max: 6 }); // too few for a p95
162195 watch.close();
163196 });
164197
@@ -192,6 +225,7 @@ describe("the 5 Hz trace", () => {
192225 history.sampleTrace(t);
193226 tick(200);
194227 }
228 t.sample(1, 2048, 1000); // it arrives: a session that measured something, so it is kept
195229 history.end(t);
196230 };
197231
Software/so101/src/precision-history.ts +68 −26
@@ -9,7 +9,7 @@ import { existsSync, readFileSync } from "node:fs";
99 import { join } from "node:path";
1010 import type { PExperiment } from "./tuning-run.ts";
1111 import { JOINTS } from "./sts3215.ts";
12 import { emptyRecords, summarize, trim, Tracker, WINDOW_MS, type Card, type Cause } from "./precision.ts";
12 import { emptyRecords, measuredAny, summarize, trim, Tracker, WINDOW_MS, type Card, type Cause } from "./precision.ts";
1313
1414 /** The deployed commit: the forge's or CI's variable when set, else the checkout's HEAD, else "unknown". Never a shell. */
1515 export function deployedCommit(env: Record<string, string | undefined> = process.env, root = join(import.meta.dirname, "../../.."), tree = join(import.meta.dirname, "..")): string {
@@ -70,18 +70,22 @@ class TraceBuffer {
7070 }
7171 }
7272
73 /** One stored drive session, or one hour of them: the headline numbers. */
73 /** One stored drive session, or one hour of them: the headline numbers, each p95 with its n (null below MIN_N_FOR_P95). */
7474 export interface Row {
7575 at: string;
7676 commit: string;
7777 sessions: number;
7878 seconds: number;
79 trackingP95Deg: number | null;
80 trackingMaxDeg: number | null;
79 settleErrorP95Deg: number | null;
80 settleErrorN: number;
81 lagP95Ms: number | null;
82 lagN: number;
8183 arriveP95Ms: number | null;
84 arriveN: number;
85 commandToMotionP95Ms: number | null;
86 commandToMotionN: number;
8287 snapBacks: number;
8388 releases: number;
84 latencyP95Ms: number | null;
8589 worstJoint: string | null;
8690 }
8791
@@ -103,8 +107,47 @@ export interface Scorecard {
103107 hours: Row[];
104108 }
105109
106 type Stored = { at: string; commit: string; sessions: number; seconds: number; tracking_p95_deg: number | null; tracking_max_deg: number | null; arrive_p95_ms: number | null; snap_backs: number; releases: number; latency_p95_ms: number | null; worst_joint: string | null };
107 const fromStored = (r: Stored): Row => ({ at: r.at, commit: r.commit, sessions: r.sessions, seconds: r.seconds, trackingP95Deg: r.tracking_p95_deg, trackingMaxDeg: r.tracking_max_deg, arriveP95Ms: r.arrive_p95_ms, snapBacks: r.snap_backs, releases: r.releases, latencyP95Ms: r.latency_p95_ms, worstJoint: r.worst_joint });
110 /** The headline columns, in order: name in sqlite, name in a Row, and how an hour folds its sessions (the worst p95; n summed). */
111 const HEADLINE = [
112 ["settle_error_p95_deg", "settleErrorP95Deg", "max"],
113 ["settle_error_n", "settleErrorN", "sum"],
114 ["lag_p95_ms", "lagP95Ms", "max"],
115 ["lag_n", "lagN", "sum"],
116 ["arrive_p95_ms", "arriveP95Ms", "max"],
117 ["arrive_n", "arriveN", "sum"],
118 ["motion_p95_ms", "commandToMotionP95Ms", "max"],
119 ["motion_n", "commandToMotionN", "sum"],
120 ["snap_backs", "snapBacks", "sum"],
121 ["releases", "releases", "sum"],
122 ] as const;
123 type Column = (typeof HEADLINE)[number][1];
124 /** Columns of rows written before #510 (tracking error during motion, the sum of hop p95s): kept in old files, no longer read or written. */
125 const RETIRED = "tracking_p95_deg REAL, tracking_max_deg REAL, latency_p95_ms REAL";
126 const SELECT = `at, commit_id, sessions, seconds, ${HEADLINE.map(([c]) => c).join(", ")}, worst_joint`;
127
128 type Stored = Record<string, unknown> & { at: string; commit_id: string; sessions: number; seconds: number; worst_joint: string | null };
129 const fromStored = (r: Stored): Row => ({
130 at: r.at,
131 commit: r.commit_id,
132 sessions: r.sessions,
133 seconds: r.seconds,
134 ...(Object.fromEntries(HEADLINE.map(([c, k, fold]) => [k, (r[c] as number | null) ?? (fold === "sum" ? 0 : null)])) as Record<Column, number>),
135 worstJoint: r.worst_joint,
136 });
137
138 /** A card's headline, as the columns hold it. */
139 const headline = (card: Card): Record<Column, number | null> => ({
140 settleErrorP95Deg: card.settleErrorDeg.p95,
141 settleErrorN: card.settleErrorDeg.n,
142 lagP95Ms: card.lagMs.p95,
143 lagN: card.lagMs.n,
144 arriveP95Ms: card.arriveMs.p95,
145 arriveN: card.arriveMs.n,
146 commandToMotionP95Ms: card.commandToMotionMs.p95,
147 commandToMotionN: card.commandToMotionMs.n,
148 snapBacks: card.snapBacks.total,
149 releases: card.releases,
150 });
108151
109152 export class PrecisionHistory {
110153 readonly commit: string;
@@ -121,13 +164,18 @@ export class PrecisionHistory {
121164 this.#now = options.now ?? Date.now;
122165 this.#db = openDb(options.file ?? ":memory:");
123166 this.#db.run("PRAGMA journal_mode = WAL");
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,
125 snap_backs INTEGER NOT NULL, releases INTEGER NOT NULL, latency_p95_ms REAL, worst_joint TEXT`;
167 const columns = `commit_id TEXT NOT NULL, sessions INTEGER NOT NULL, seconds REAL NOT NULL, ${RETIRED}, arrive_p95_ms REAL,
168 snap_backs INTEGER NOT NULL, releases INTEGER NOT NULL, worst_joint TEXT`;
126169 this.#db.run(`CREATE TABLE IF NOT EXISTS sessions (id INTEGER PRIMARY KEY, at TEXT NOT NULL, ${columns}, card TEXT NOT NULL)`);
127170 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)");
128171 this.#db.run("CREATE TABLE IF NOT EXISTS tunings (id INTEGER PRIMARY KEY, commit_id TEXT NOT NULL, result TEXT NOT NULL)");
129172 // An hour's roll-up keeps the worst of its sessions' p95s: one bad session in the hour is what the trend must show.
130173 this.#db.run(`CREATE TABLE IF NOT EXISTS hours (at TEXT NOT NULL, ${columns}, PRIMARY KEY (at, commit_id))`);
174 // A file from before settle error and following lag gains their columns; its old rows read as unmeasured there.
175 for (const table of ["sessions", "hours"]) {
176 const have = new Set((this.#db.query(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>).map((c) => c.name));
177 for (const [c, , fold] of HEADLINE) if (!have.has(c)) this.#db.run(`ALTER TABLE ${table} ADD COLUMN ${c} ${fold === "sum" ? "INTEGER NOT NULL DEFAULT 0" : "REAL"}`);
178 }
131179 }
132180
133181 /** A drive session starts: its tracker, whose records also feed the window. */
@@ -166,24 +214,21 @@ export class PrecisionHistory {
166214 this.last = card;
167215 const trace = this.#traces.get(tracker);
168216 this.#traces.delete(tracker);
169 const measured = card.joints.some((j) => j.errorTicks.n > 0) || card.snapBacks.total > 0;
170 if (!measured) return card;
217 if (!measuredAny(tracker.records)) return card;
171218 const seconds = Number(((at - tracker.startedAt) / 1000).toFixed(1));
172 const maxDeg = card.joints.reduce<number | null>((m, j) => (j.errorDeg.max === null ? m : Math.max(m ?? 0, j.errorDeg.max)), null);
173 const row = [this.commit, 1, seconds, card.trackingP95Deg, maxDeg, card.arriveP95Ms, card.snapBacks.total, card.releases, card.latencyP95Ms, card.worstJoint] as const;
219 const values = headline(card);
220 const row = [this.commit, 1, seconds, ...HEADLINE.map(([, k]) => values[k]), card.worstJoint] as const;
221 const names = `commit_id, sessions, seconds, ${HEADLINE.map(([c]) => c).join(", ")}, worst_joint`;
222 const marks = (n: number) => Array.from({ length: n }, () => "?").join(", ");
174223 const iso = new Date(at).toISOString();
175 this.#db.query(`INSERT INTO sessions (at, commit_id, sessions, seconds, tracking_p95_deg, tracking_max_deg, arrive_p95_ms, snap_backs, releases, latency_p95_ms, worst_joint, card) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(iso, ...row, JSON.stringify(card));
224 this.#db.query(`INSERT INTO sessions (at, ${names}, card) VALUES (${marks(row.length + 2)})`).run(iso, ...row, JSON.stringify(card));
176225 const hour = `${iso.slice(0, 13)}:00:00.000Z`;
226 const fold = HEADLINE.map(([c, , how]) => (how === "sum" ? `${c} = ${c} + excluded.${c}` : `${c} = max(coalesce(${c}, excluded.${c}), coalesce(excluded.${c}, ${c}))`)).join(", ");
177227 this.#db
178228 .query(
179 `INSERT INTO hours (at, commit_id, sessions, seconds, tracking_p95_deg, tracking_max_deg, arrive_p95_ms, snap_backs, releases, latency_p95_ms, worst_joint) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
180 ON CONFLICT (at, commit_id) DO UPDATE SET sessions = sessions + 1, seconds = seconds + excluded.seconds,
181 tracking_p95_deg = max(coalesce(tracking_p95_deg, excluded.tracking_p95_deg), coalesce(excluded.tracking_p95_deg, tracking_p95_deg)),
182 tracking_max_deg = max(coalesce(tracking_max_deg, excluded.tracking_max_deg), coalesce(excluded.tracking_max_deg, tracking_max_deg)),
183 arrive_p95_ms = max(coalesce(arrive_p95_ms, excluded.arrive_p95_ms), coalesce(excluded.arrive_p95_ms, arrive_p95_ms)),
184 latency_p95_ms = max(coalesce(latency_p95_ms, excluded.latency_p95_ms), coalesce(excluded.latency_p95_ms, latency_p95_ms)),
185 snap_backs = snap_backs + excluded.snap_backs, releases = releases + excluded.releases,
186 worst_joint = CASE WHEN excluded.tracking_p95_deg >= coalesce(tracking_p95_deg, -1) THEN excluded.worst_joint ELSE worst_joint END`,
229 `INSERT INTO hours (at, ${names}) VALUES (${marks(row.length + 1)})
230 ON CONFLICT (at, commit_id) DO UPDATE SET sessions = sessions + 1, seconds = seconds + excluded.seconds, ${fold},
231 worst_joint = CASE WHEN worst_joint IS NULL OR excluded.settle_error_p95_deg >= coalesce(settle_error_p95_deg, -1) THEN coalesce(excluded.worst_joint, worst_joint) ELSE worst_joint END`,
187232 )
188233 .run(hour, ...row);
189234 if (trace && trace.samples > 0) {
@@ -197,10 +242,7 @@ export class PrecisionHistory {
197242
198243 /** The stored rows, oldest first. */
199244 rows(table: "sessions" | "hours", limit = 48): Row[] {
200 const sql =
201 table === "sessions"
202 ? `SELECT at, commit_id AS "commit", sessions, seconds, tracking_p95_deg, tracking_max_deg, arrive_p95_ms, snap_backs, releases, latency_p95_ms, worst_joint FROM sessions ORDER BY id DESC LIMIT ?`
203 : `SELECT at, commit_id AS "commit", sessions, seconds, tracking_p95_deg, tracking_max_deg, arrive_p95_ms, snap_backs, releases, latency_p95_ms, worst_joint FROM hours ORDER BY at DESC LIMIT ?`;
245 const sql = table === "sessions" ? `SELECT ${SELECT} FROM sessions ORDER BY id DESC LIMIT ?` : `SELECT ${SELECT} FROM hours ORDER BY at DESC LIMIT ?`;
204246 const rows = this.#db.query(sql).all(limit) as Stored[];
205247 return rows.reverse().map(fromStored);
206248 }
Software/so101/src/precision-panel.test.ts +28 −16
@@ -8,23 +8,35 @@ import { Lobby } from "./lobby.ts";
88 import { precisionSection, readPrecision, sparkline } from "./precision-panel.ts";
99 import { startRelay, type RunningRelay } from "./relay.ts";
1010
11 const row = (trackingP95Deg: number | null, snapBacks: number, releases: number) => ({ at: "2026-10-21T10:00:00.000Z", commit: "abc1234", sessions: 1, seconds: 30, trackingP95Deg, trackingMaxDeg: 9, arriveP95Ms: 200, snapBacks, releases, latencyP95Ms: 40, worstJoint: "elbow_flex" });
12 const scorecard = (window: Record<string, unknown> = {}) => ({ commit: "abc1234", session: null, window: { trackingP95Deg: null, arriveP95Ms: null, snapBacksPer100Releases: null, latencyP95Ms: null, worstJoint: null, ...window }, sessions: [row(1, 1, 4), row(3, 0, 2), row(2, 2, 2)], hours: [] });
11 const row = (settleErrorP95Deg: number | null, snapBacks: number, releases: number) => ({ at: "2026-10-21T10:00:00.000Z", commit: "abc1234", sessions: 1, seconds: 30, settleErrorP95Deg, settleErrorN: 30, lagP95Ms: null, lagN: 12, arriveP95Ms: 200, arriveN: 25, snapBacks, releases, commandToMotionP95Ms: 40, commandToMotionN: 22, worstJoint: "elbow_flex" });
12 const none = { n: 0, p50: null, p95: null, max: null };
13 const scorecard = (window: Record<string, unknown> = {}) => ({ commit: "abc1234", session: null, window: { settleErrorDeg: none, lagMs: none, arriveMs: none, commandToMotionMs: none, snapBacksPer100Releases: null, releases: 0, worstJoint: null, ...window }, sessions: [row(1, 1, 4), row(3, 0, 2), row(2, 2, 2)], hours: [] });
1314
1415 describe("reading /precision", () => {
1516 test("the window's numbers when it has them, else the last session's, and a trend per number", () => {
16 const p = readPrecision(scorecard({ trackingP95Deg: 0.5, worstJoint: "wrist_flex" }))!;
17 expect(p.headline.map((h) => h.value)).toEqual([0.5, 200, 100, 40]);
17 const p = readPrecision(scorecard({ settleErrorDeg: { n: 21, p50: 0.2, p95: 0.5, max: 0.6 }, worstJoint: "wrist_flex" }))!;
18 expect(p.headline.map((h) => h.label)).toEqual(["Settle error, p95", "Following lag, p95", "Time to arrive, p95", "Snap-backs per 100 releases", "Latency, p95, command→motion"]);
19 expect(p.headline.map((h) => h.value)).toEqual([0.5, null, 200, 100, 40]);
20 expect(p.headline.map((h) => h.n)).toEqual([21, 12, 25, 2, 22]);
1821 expect(p.headline[0]!.trend).toEqual([1, 3, 2]);
19 expect(p.headline[2]!.trend).toEqual([25, 0, 100]);
22 expect(p.headline[3]!.trend).toEqual([25, 0, 100]);
2023 expect(p.worstJoint).toBe("wrist_flex");
2124 expect(readPrecision(scorecard())!.worstJoint).toBe("elbow_flex");
2225 });
2326
24 test("the hops that were timed are listed with p50 and p95, and an untimed one is left out", () => {
25 const hops = { "browser→relay": { n: 3, p50: 4, p95: 9, max: 9 }, "relay→Pi": { n: 0, p50: null, p95: null, max: null } };
27 test("a window with too few for a p95 shows a dash and its n, not the last session's number", () => {
28 const p = readPrecision(scorecard({ settleErrorDeg: { n: 7, p50: 0.3, p95: null, max: 0.4 } }))!;
29 expect(p.headline[0]).toMatchObject({ value: null, n: 7 });
30 const html = precisionSection(p, esc);
31 expect(html).toContain("<b>—</b> <small>n = 7</small>");
32 expect(html).toContain("a p95 needs n ≥ 20");
33 });
34
35 test("the hops that were timed are listed with p50, p95 (a dash below n = 20) and n, and an untimed one is left out", () => {
36 const hops = { "browser→relay": { n: 3, p50: 4, p95: null, max: 9 }, "relay→Pi": { n: 0, p50: null, p95: null, max: null } };
2637 const p = readPrecision(scorecard({ hops }))!;
27 expect(p.hops).toEqual([{ name: "browser→relay", p50: 4, p95: 9 }]);
38 expect(p.hops).toEqual([{ name: "browser→relay", n: 3, p50: 4, p95: null }]);
39 expect(precisionSection(p, esc)).toContain("4 / — ms</b> <small>n = 3</small>");
2840 expect(precisionSection(p, esc)).toContain("browser→relay");
2941 expect(readPrecision(scorecard())!.hops).toEqual([]);
3042 });
@@ -32,7 +44,7 @@ describe("reading /precision", () => {
3244 test("anything that is not a scorecard is null; a field of the wrong type is a gap, never an error", () => {
3345 expect(readPrecision("nope")).toBeNull();
3446 expect(readPrecision({ commit: 1, sessions: [] })).toBeNull();
35 const p = readPrecision({ commit: "x", sessions: [{ trackingP95Deg: "9" }], window: [] })!;
47 const p = readPrecision({ commit: "x", sessions: [{ settleErrorP95Deg: "9" }], window: [] })!;
3648 expect(p.headline[0]!.value).toBeNull();
3749 expect(p.headline[0]!.trend).toEqual([null]);
3850 });
@@ -76,14 +88,14 @@ describe("the Precision panel on /admin", () => {
7688 return { base: `http://127.0.0.1:${relay.port}`, asked: () => asked };
7789 };
7890
79 test("the owner sees the four headline numbers, the worst joint and the commit; a stranger gets 404 and the arm is not asked", async () => {
80 const { base, asked } = await boot(() => Response.json(scorecard({ trackingP95Deg: 0.5 })));
91 test("the owner sees the five headline numbers with their n, the worst joint and the commit; a stranger gets 404 and the arm is not asked", async () => {
92 const { base, asked } = await boot(() => Response.json(scorecard({ settleErrorDeg: { n: 20, p50: 0.4, p95: 0.5, max: 0.5 } })));
8193 expect((await fetch(`${base}/admin`)).status).toBe(404);
8294 expect(asked()).toBe(0);
8395 const html = await (await fetch(`${base}/admin`, { headers: owner })).text();
8496 expect(html).toContain(`<h2 id="precision">Precision</h2>`);
85 for (const label of ["Tracking error, p95", "Time to arrive, p95", "Snap-backs per 100 releases", "Latency, p95"]) expect(html).toContain(label);
86 expect(html).toContain("<b>0.5°</b>");
97 for (const label of ["Settle error, p95", "Following lag, p95", "Time to arrive, p95", "Snap-backs per 100 releases", "Latency, p95, command→motion"]) expect(html).toContain(label);
98 expect(html).toContain("<b>0.5°</b> <small>n = 20</small>");
8799 expect(html).toContain("elbow_flex");
88100 expect(html).toContain("commit abc1234");
89101 });
@@ -96,7 +108,7 @@ describe("the Precision panel on /admin", () => {
96108 });
97109
98110 test("GET /precision on the public server: the owner gets the arm's scorecard; a stranger or a signed-in guest gets 404 and the arm is not asked", async () => {
99 const { base, asked } = await boot(() => Response.json(scorecard({ trackingP95Deg: 0.5 })));
111 const { base, asked } = await boot(() => Response.json(scorecard({ settleErrorDeg: { n: 20, p50: 0.4, p95: 0.5, max: 0.5 } })));
100112 for (const headers of [{}, guest]) {
101113 const refused = await fetch(`${base}/precision`, { headers });
102114 expect(refused.status).toBe(404);
@@ -105,7 +117,7 @@ describe("the Precision panel on /admin", () => {
105117 expect(asked()).toBe(0);
106118 const res = await fetch(`${base}/precision?hours=336`, { headers: owner });
107119 expect(res.status).toBe(200);
108 expect(await res.json()).toMatchObject({ commit: "abc1234", window: { trackingP95Deg: 0.5 } });
120 expect(await res.json()).toMatchObject({ commit: "abc1234", window: { settleErrorDeg: { p95: 0.5 } } });
109121 expect(asked()).toBe(1);
110122 expect((await fetch(`${base}/precision?hours=0`, { headers: owner })).status).toBe(400);
111123 expect((await fetch(`${base}/precision?hours=1;x`, { headers: owner })).status).toBe(400);
@@ -117,7 +129,7 @@ describe("the Precision panel on /admin", () => {
117129 const { base } = await boot(() => Response.json({}));
118130 arm!.stop(true);
119131 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?.();
132 relay?.close?.();
121133 const again = await startRelay({ port: 0, simulation: `http://127.0.0.1:${arm.port}`, lobby });
122134 const url = `http://127.0.0.1:${again.port}/precision/trace`;
123135 try {
Software/so101/src/precision-panel.ts +35 −16
@@ -1,9 +1,11 @@
11 /**
22 * The Precision panel of /admin: the arm server's GET /precision (src/precision-history.ts) read field by field, for
3 * the answer comes over the network from another machine, and drawn as four headline numbers, each with a sparkline of
4 * the stored sessions, oldest first, and the worst joint named. Plain text and characters; no script.
3 * the answer comes over the network from another machine, and drawn as five headline numbers, each with its n and a
4 * sparkline of the stored sessions, oldest first, and the worst joint named. A p95 of fewer than 20 is not given (the arm
5 * server sends null): the panel shows a dash and the n. Plain text and characters; no script.
56 */
67
8 import { MIN_N_FOR_P95 } from "./precision.ts";
79 import { readTuningResult, tuningList, type TuningResult } from "./tuning-panel.ts";
810
911 const SPARK = "▁▂▃▄▅▆▇█";
@@ -13,6 +15,8 @@ export interface Headline {
1315 label: string;
1416 unit: string;
1517 value: number | null;
18 /** How many samples `value` is of (releases, for the snap-back rate); null when not known. */
19 n: number | null;
1620 /** The same number, session by session, oldest first; null where a session did not measure it. */
1721 trend: Array<number | null>;
1822 }
@@ -25,7 +29,7 @@ export interface PrecisionPanel {
2529 /** The P experiments kept, newest first. */
2630 tunings: TuningResult[];
2731 /** Each link hop with a measurement, as the window (else the last session) has it. */
28 hops: Array<{ name: string; p50: number | null; p95: number | null }>;
32 hops: Array<{ name: string; n: number; p50: number | null; p95: number | null }>;
2933 }
3034
3135 const num = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
@@ -40,15 +44,22 @@ export function readPrecision(body: unknown): PrecisionPanel | null {
4044 const rows = card.sessions.slice(-TREND).map(obj);
4145 const last = rows.at(-1) ?? {};
4246 // The window when it measured something, else the last stored session: the panel never goes blank between drives.
43 const pick = (fromWindow: unknown, fromRow: unknown) => num(fromWindow) ?? num(fromRow);
47 // The value and its n come from the same place.
48 const measure = (label: string, unit: string, spread: unknown, p95: string, n: string): Headline => {
49 const w = obj(spread);
50 const fromWindow = (num(w.n) ?? 0) > 0;
51 return { label, unit, value: fromWindow ? num(w.p95) : num(last[p95]), n: fromWindow ? num(w.n) : num(last[n]), trend: rows.map((r) => num(r[p95])) };
52 };
4453 const rate = (r: Record<string, unknown>) => {
4554 const snaps = num(r.snapBacks), releases = num(r.releases);
4655 return snaps !== null && releases ? Number(((snaps / releases) * 100).toFixed(1)) : null;
4756 };
57 const windowRate = num(window.snapBacksPer100Releases);
4858 const hops = Object.entries(obj(window.hops)).flatMap(([name, h]) => {
4959 const spread = obj(h);
50 const n = text(name, 24);
51 return n && num(spread.p95) !== null ? [{ name: n, p50: num(spread.p50), p95: num(spread.p95) }] : [];
60 const label = text(name, 24);
61 const n = num(spread.n) ?? 0;
62 return label && n > 0 && num(spread.p50) !== null ? [{ name: label, n, p50: num(spread.p50), p95: num(spread.p95) }] : [];
5263 });
5364 return {
5465 hops,
@@ -57,17 +68,21 @@ export function readPrecision(body: unknown): PrecisionPanel | null {
5768 sessions: rows.length,
5869 tunings: (Array.isArray(card.tunings) ? card.tunings : []).slice(0, 20).map(readTuningResult).filter((t): t is TuningResult => t !== null),
5970 headline: [
60 { label: "Tracking error, p95", unit: "°", value: pick(window.trackingP95Deg, last.trackingP95Deg), trend: rows.map((r) => num(r.trackingP95Deg)) },
61 { label: "Time to arrive, p95", unit: "ms", value: pick(window.arriveP95Ms, last.arriveP95Ms), trend: rows.map((r) => num(r.arriveP95Ms)) },
62 { label: "Snap-backs per 100 releases", unit: "", value: pick(window.snapBacksPer100Releases, rate(last)), trend: rows.map(rate) },
63 { label: "Latency, p95, bus→motion", unit: "ms", value: pick(window.latencyP95Ms, last.latencyP95Ms), trend: rows.map((r) => num(r.latencyP95Ms)) },
71 measure("Settle error, p95", "°", window.settleErrorDeg, "settleErrorP95Deg", "settleErrorN"),
72 measure("Following lag, p95", "ms", window.lagMs, "lagP95Ms", "lagN"),
73 measure("Time to arrive, p95", "ms", window.arriveMs, "arriveP95Ms", "arriveN"),
74 { label: "Snap-backs per 100 releases", unit: "", value: windowRate ?? rate(last), n: windowRate !== null ? num(window.releases) : num(last.releases), trend: rows.map(rate) },
75 measure("Latency, p95, command→motion", "ms", window.commandToMotionMs, "commandToMotionP95Ms", "commandToMotionN"),
6476 ],
6577 };
6678 }
6779
68 /** A headline number with its unit, or a dash when nothing measured it. */
80 /** A headline number with its unit, or a dash when nothing measured it or too little for a p95. */
6981 export const headlineValue = (h: Headline): string => (h.value === null ? "—" : `${h.value}${h.unit && h.unit !== "°" ? " " : ""}${h.unit}`);
7082
83 /** The sample size beside a number: "n = 7", or nothing when it is not known. */
84 export const sampleSize = (n: number | null): string => (n === null ? "" : `n = ${n}`);
85
7186 /** A row of block characters, lowest to highest; a gap for a session that did not measure it. */
7287 export function sparkline(values: ReadonlyArray<number | null>): string {
7388 const known = values.filter((v): v is number => v !== null);
@@ -85,21 +100,25 @@ export function precisionSection(p: PrecisionPanel | null | undefined, esc: (s:
85100 .map((h) => {
86101 const value = headlineValue(h);
87102 const spark = sparkline(h.trend);
88 return `<li><span>${esc(h.label)}</span><span><b>${esc(value)}</b>${spark ? ` <span aria-hidden="true">${spark}</span>` : ""}</span></li>`;
103 const n = sampleSize(h.n);
104 return `<li><span>${esc(h.label)}</span><span><b>${esc(value)}</b>${n ? ` <small>${esc(n)}</small>` : ""}${spark ? ` <span aria-hidden="true">${spark}</span>` : ""}</span></li>`;
89105 })
90106 .join("");
91 return `${head}<p>Worst joint: <b>${esc(p.worstJoint ?? "—")}</b> · last 10 minutes, else the last session · trend over ${p.sessions} session${p.sessions === 1 ? "" : "s"} · commit ${esc(p.commit)}</p><ol class="bars precision" aria-label="Precision, headline numbers">${items}</ol>${tuningList(p.tunings, esc)}${hopList(p.hops, esc)}</section>`;
107 return `${head}<p>Worst joint: <b>${esc(p.worstJoint ?? "—")}</b> · ${esc(P95_RULE)} · last 10 minutes, else the last session · trend over ${p.sessions} session${p.sessions === 1 ? "" : "s"} · commit ${esc(p.commit)}</p><ol class="bars precision" aria-label="Precision, headline numbers">${items}</ol>${tuningList(p.tunings, esc)}${hopList(p.hops, esc)}</section>`;
92108 }
93109
110 /** Why a number may be a dash beside its n. */
111 export const P95_RULE = `a p95 needs n ≥ ${MIN_N_FOR_P95}`;
112
94113 /** What is said where the hops would be, when none was timed: the simulation has no link to time. */
95114 export const NO_HOPS = "No link hops timed: they are measured against the real arm only, while someone drives it.";
96115
97 /** One line per timed hop: name, then p50 and p95 in ms. */
98 export const hopLines = (hops: PrecisionPanel["hops"]): string[] => hops.map((h) => `${h.name} p50 ${h.p50 ?? "—"} · p95 ${h.p95} ms`);
116 /** One line per timed hop: name, then p50 and p95 in ms, and n. */
117 export const hopLines = (hops: PrecisionPanel["hops"]): string[] => hops.map((h) => `${h.name} p50 ${h.p50 ?? "—"} · p95 ${h.p95 ?? "—"} ms · n = ${h.n}`);
99118
100119 /** The hops that were timed, each with its p50 and p95; nothing when none was. */
101120 function hopList(hops: PrecisionPanel["hops"], esc: (s: string) => string): string {
102121 if (!hops.length) return `<p class="empty">${esc(NO_HOPS)}</p>`;
103 const rows = hops.map((h) => `<li><span>${esc(h.name)}</span><span><b>${esc(`${h.p50 ?? "—"} / ${h.p95} ms`)}</b></span></li>`).join("");
122 const rows = hops.map((h) => `<li><span>${esc(h.name)}</span><span><b>${esc(`${h.p50 ?? "—"} / ${h.p95 ?? "—"} ms`)}</b> <small>${esc(sampleSize(h.n))}</small></span></li>`).join("");
104123 return `<h3>Latency by hop, p50 / p95</h3><ol class="bars precision" aria-label="Latency by hop">${rows}</ol>`;
105124 }
Software/so101/src/precision.test.ts +93 −34
@@ -1,5 +1,5 @@
11 import { describe, expect, test } from "bun:test";
2 import { ARRIVE_TICKS, CAUSES, emptyRecords, MAX_HOP_MS, READ_BACK_HOP, RELAY_HOP, percentile, SETTLE_MS, summarize, trim, Tracker } from "./precision.ts";
2 import { ARRIVE_TICKS, CAUSES, emptyRecords, followingLag, MAX_HOP_MS, MAX_LAG_MS, MIN_N_FOR_P95, MOTION_HOP, READ_BACK_HOP, RELAY_HOP, percentile, REST_MS, SETTLE_MS, summarize, trim, Tracker } from "./precision.ts";
33
44 describe("percentile", () => {
55 test("nearest rank, unsorted input, none for an empty list", () => {
@@ -10,26 +10,91 @@ describe("percentile", () => {
1010 });
1111 });
1212
13 describe("tracking error", () => {
14 test("is target minus read-back, in ticks and degrees, per joint and pooled", () => {
13 /** Twenty-one read-backs of 0, 1, … 20 ticks: what a spread with a p95 needs. */
14 const restAt = (t: Tracker, id: number, target: number, present: number, at: number) => {
15 t.target(id, target, at);
16 for (let dt = 0; dt <= REST_MS + 50; dt += 50) t.sample(id, present, at + dt);
17 };
18
19 describe("settle error", () => {
20 test("is |target − read-back| once the joint has stayed put for REST_MS, one sample per rest, in ticks and degrees", () => {
1521 const t = new Tracker(0);
16 t.target(1, 2048, 0);
17 // 20 read-backs 0..19 ticks short of the target on joint 1; joint 2 always 114 ticks (10°) short.
18 for (let i = 0; i < 20; i++) t.sample(1, 2048 - i, i * 10);
19 t.target(2, 2162, 0);
20 for (let i = 0; i < 20; i++) t.sample(2, 2048, i * 10);
22 restAt(t, 1, 2048, 2048 - 11, 0);
23 const j = summarize(t.records).joints[0]!;
24 expect(j.settleErrorTicks).toEqual({ n: 1, p50: 11, p95: null, max: 11 });
25 expect(j.settleErrorDeg.p50).toBeCloseTo(11 / (4096 / 360), 2);
26 });
27
28 test("a p95 is given from MIN_N_FOR_P95 samples on, and pooled across joints for the headline; the worst joint has the highest median", () => {
29 const t = new Tracker(0);
30 for (let i = 0; i < MIN_N_FOR_P95 - 1; i++) restAt(t, 1, 2048 + (i % 2) * 500, 2048 + (i % 2) * 500 - i, i * 1000);
31 expect(summarize(t.records).settleErrorDeg).toMatchObject({ n: 19, p95: null });
32 restAt(t, 1, 3000, 3000 - 19, 30_000);
33 restAt(t, 2, 2162, 2048, 0); // 114 ticks: 10°
2134 const card = summarize(t.records);
22 const [j1, j2] = card.joints;
23 expect(j1!.errorTicks).toEqual({ n: 20, p50: 9, p95: 18, max: 19 });
24 expect(j2!.errorDeg.p95).toBeCloseTo(10.02, 1);
35 expect(card.joints[0]!.settleErrorTicks).toEqual({ n: 20, p50: 9, p95: 18, max: 19 });
36 expect(card.settleErrorDeg.n).toBe(21);
37 expect(card.settleErrorDeg.p95).toBeCloseTo(19 / (4096 / 360), 2); // nearest rank: the 20th of 21
2538 expect(card.worstJoint).toBe("shoulder_lift");
26 expect(card.trackingP95Deg).toBeCloseTo(10.02, 1);
39 });
40
41 test("never sampled while the arm moves or the target does, and a joint that stopped short counts as stopped", () => {
42 const t = new Tracker(0);
43 t.sample(1, 1000, 0);
44 t.target(1, 1500, 0);
45 for (let at = 20, p = 1000; at <= 400; at += 20, p += 20) t.sample(1, p, at); // moving: nothing
46 expect(summarize(t.records).joints[0]!.settleErrorTicks.n).toBe(0);
47 for (let at = 420; at <= 800; at += 20) t.sample(1, 1380, at); // stuck 120 short: stopped
48 expect(summarize(t.records).joints[0]!.settleErrorTicks).toMatchObject({ n: 1, p50: 120 });
49 t.target(1, 1600, 810);
50 t.sample(1, 1380, 820);
51 t.target(1, 1700, 830); // the target moves on: not at rest
52 t.sample(1, 1380, 1100);
53 expect(summarize(t.records).joints[0]!.settleErrorTicks.n).toBe(1);
2754 });
2855
2956 test("a joint with no target yet is not counted", () => {
3057 const t = new Tracker(0);
31 t.sample(1, 2000, 0);
32 expect(summarize(t.records).trackingP95Deg).toBeNull();
58 for (let at = 0; at < 1000; at += 50) t.sample(1, 2000, at);
59 expect(summarize(t.records).settleErrorDeg.n).toBe(0);
60 });
61 });
62
63 describe("following lag", () => {
64 test("a synthetic trace with a known lag and settle error gives back exactly those numbers", () => {
65 const t = new Tracker(0);
66 const LAG = 120;
67 t.sample(1, 1000, 0);
68 // The intent sweeps 1 tick a ms, framed every 30 ms, from 1000 to 2000; read back every 20 ms, the arm is the intent
69 // LAG ms late, and stops 10 short of the end.
70 const arm = (at: number) => Math.min(1990, Math.max(1000, 1000 + at - LAG));
71 for (let at = 0; at <= 1600; at += 10) {
72 if ((at % 30 === 0 && at <= 1000) || at === 1000) t.target(1, 1000 + at, at);
73 if (at % 20 === 10) t.sample(1, arm(at), at);
74 }
75 const card = summarize(t.records);
76 expect(card.lagMs.n).toBeGreaterThanOrEqual(MIN_N_FOR_P95);
77 expect(card.lagMs).toMatchObject({ p50: LAG, p95: LAG, max: LAG });
78 expect(card.joints[0]!.settleErrorTicks).toEqual({ n: 1, p50: 10, p95: null, max: 10 });
79 });
80
81 test("a step is chased, not followed: no lag, and time to arrive times it", () => {
82 const t = new Tracker(0);
83 t.sample(1, 1000, 0);
84 t.target(1, 1000, 0);
85 t.target(1, 1300, 500);
86 for (let at = 520, p = 1050; p <= 1300; at += 20, p += 50) t.sample(1, p, at);
87 const card = summarize(t.records);
88 expect(card.lagMs.n).toBe(0);
89 expect(card.arriveMs.n).toBe(1);
90 });
91
92 test("followingLag: the latest pass in the joint's direction, interpolated between frames; none past MAX_LAG_MS", () => {
93 const trace = [[0, 0], [20, 20], [40, 40], [60, 20]] as const;
94 expect(followingLag(trace, 30, 1, 100)).toBe(70);
95 expect(followingLag(trace, 30, -1, 100)).toBe(50);
96 expect(followingLag(trace, 50, 1, 100)).toBeNull();
97 expect(followingLag(trace, 30, 1, 40 + MAX_LAG_MS + 1)).toBeNull();
3398 });
3499 });
35100
@@ -91,27 +156,24 @@ describe("bus to motion", () => {
91156 t.sample(1, 2003, 20); // not yet
92157 t.sample(1, 2010, 35);
93158 const card = summarize(t.records);
94 expect(card.joints[0]!.busToMoveMs.p50).toBe(25);
95 expect(card.hops["bus→move"]!.p95).toBe(25);
96 expect(card.latencyP95Ms).toBe(25);
159 expect(card.joints[0]!.busToMoveMs).toEqual({ n: 1, p50: 25, p95: null, max: 25 });
160 expect(card.hops["bus→move"]!.p50).toBe(25);
97161 });
98162 });
99163
100164 describe("link hops", () => {
101 test("relay→Pi and read-back→relay get p50/p95 beside bus→move, and latencyP95Ms adds all three; a negative or absurd one is not counted", () => {
165 test("each hop gets its n, p50 and (from MIN_N_FOR_P95 crossings) p95; command→motion is the headline; a negative or absurd one is not counted", () => {
102166 const t = new Tracker(0);
103167 for (const ms of [4, 6, 8, 10]) expect(t.hop(RELAY_HOP, ms, 100)).toBe(true);
104168 expect(t.hop(READ_BACK_HOP, 3, 100)).toBe(true);
105169 expect(t.hop(RELAY_HOP, -1, 100)).toBe(false);
106170 expect(t.hop(RELAY_HOP, Number.NaN, 100)).toBe(false);
107171 expect(t.hop(RELAY_HOP, MAX_HOP_MS + 1, 100)).toBe(false);
108 t.sample(1, 2000, 0);
109 t.wrote(1, 10);
110 t.sample(1, 2010, 35);
172 for (let i = 1; i <= 20; i++) t.hop(MOTION_HOP, i * 10, 100);
111173 const card = summarize(t.records);
112 expect(card.hops[RELAY_HOP]).toMatchObject({ n: 4, p50: 6, p95: 10 });
113 expect(card.hops[READ_BACK_HOP]).toMatchObject({ n: 1, p95: 3 });
114 expect(card.latencyP95Ms).toBe(10 + 3 + 25);
174 expect(card.hops[RELAY_HOP]).toEqual({ n: 4, p50: 6, p95: null, max: 10 });
175 expect(card.hops[READ_BACK_HOP]).toMatchObject({ n: 1, p50: 3 });
176 expect(card.commandToMotionMs).toEqual({ n: 20, p50: 100, p95: 190, max: 200 });
115177 expect(summarize(t.records, 101).hops[RELAY_HOP]!.n).toBe(0);
116178 });
117179 });
@@ -141,13 +203,11 @@ describe("snap-backs", () => {
141203 t.sample(1, 3000, 30); // nor an arrival
142204 t.sample(2, 3000, 30);
143205 const [one, two] = summarize(t.records).joints;
144 expect(one!.errorTicks.n).toBe(1);
145206 expect(one!.arriveMs.n).toBe(0);
146 expect(two!.errorTicks.n).toBe(2);
147207 expect(two!.arriveMs).toMatchObject({ n: 1, p50: 30 });
148208 t.forget();
149 t.sample(2, 2500, 40);
150 expect(summarize(t.records).joints[1]!.errorTicks.n).toBe(2); // nothing counted for either after forgetting both
209 for (let at = 40; at <= 400; at += 40) t.sample(2, 2500, at);
210 expect(summarize(t.records).joints[1]!.settleErrorTicks.n).toBe(0); // at rest, but chasing nothing: no settle error
151211 t.target(1, 2000, 50);
152212 t.sample(1, 2000, 60);
153213 expect(summarize(t.records).joints[0]!.arriveMs).toMatchObject({ n: 1, p50: 10 });
@@ -164,14 +224,13 @@ describe("the window", () => {
164224 test("records go to the sinks too, and trim drops what is older", () => {
165225 const window = emptyRecords();
166226 const t = new Tracker(0, [window]);
167 t.target(1, 2048, 0);
168 t.sample(1, 2000, 0);
169 t.sample(1, 2040, 1000);
227 restAt(t, 1, 2048, 2000, 0);
228 restAt(t, 1, 2048, 2040, 1000);
170229 t.snapBack("zone", 0);
171230 trim(window, 500);
172 expect(summarize(window).joints[0]!.errorTicks).toMatchObject({ n: 1, max: 8 });
231 expect(summarize(window).joints[0]!.settleErrorTicks).toMatchObject({ n: 1, max: 8 });
173232 expect(summarize(window).snapBacks.total).toBe(0);
174 expect(summarize(t.records).joints[0]!.errorTicks.n).toBe(2);
175 expect(summarize(t.records, 500).joints[0]!.errorTicks.n).toBe(1);
233 expect(summarize(t.records).joints[0]!.settleErrorTicks.n).toBe(2);
234 expect(summarize(t.records, 500).joints[0]!.settleErrorTicks.n).toBe(1);
176235 });
177236 });
Software/so101/src/precision.ts +102 −32
@@ -2,7 +2,12 @@
22 * The precision instrument: how closely the real arm follows what its driver asks of it. Plain data in (targets,
33 * read-backs, bus writes, snap-backs, each with its time in ms), plain data out (a scorecard).
44 *
5 * tracking error commanded target minus Present_Position, per joint, at every read-back of a drive session
5 * settle error |target − Present_Position| once the joint has arrived or stopped: still (within MOVE_TICKS) for
6 * REST_MS with the target still too; one sample per rest. This is the precision number. It is never
7 * sampled while the arm moves: then a target that leads the arm says how far ahead the finger is
8 * following lag while the target streams (frames at most STREAM_GAP_MS apart), at each read-back of a moving joint:
9 * how long ago the target passed where the joint is now, going the same way. A step target is not
10 * followed but chased, and is timed by time to arrive
611 * time to arrive from a target being set (with the joint out of reach of it) to the first read-back within
712 * ARRIVE_TICKS; then, for SETTLE_MS: the overshoot past the target, the settling time (until the
813 * last entry into the band) and the oscillations (each exit and re-entry is one)
@@ -11,6 +16,8 @@
1116 * the relay times on a clock it aligns with the arm server's (src/hops.ts): relay→Pi, from the stamp on
1217 * a forwarded command, and read-back→relay, from the read time on a status
1318 *
19 * Every spread carries n, its sample size, and its p95 is null below MIN_N_FOR_P95: a p95 of a handful is the max.
20 *
1421 * One `Tracker` per drive session; `summarize` folds any span of its records into the same numbers, which is how the
1522 * rolling window and the stored session rows are made.
1623 */
@@ -21,6 +28,14 @@ import { JOINTS } from "./sts3215.ts";
2128 export const ARRIVE_TICKS = 12;
2229 /** Ticks a joint must move past where it was written from to count as started. */
2330 export const MOVE_TICKS = 3;
31 /** How long a joint and its target must stay still for the joint to count as at rest, ms. */
32 export const REST_MS = 250;
33 /** Target frames at most this far apart are a stream the joint follows; further apart, a step it chases, ms. */
34 export const STREAM_GAP_MS = 100;
35 /** How far back a target is looked for when timing following lag, ms. */
36 export const MAX_LAG_MS = 2000;
37 /** Below this many samples a p95 is not given. */
38 export const MIN_N_FOR_P95 = 20;
2439 /** How long after arriving the joint is watched for overshoot and oscillation, ms. */
2540 export const SETTLE_MS = 1000;
2641 /** The rolling window, ms. */
@@ -52,10 +67,12 @@ export const READ_BACK_HOP = "read-back→relay";
5267 /** The two the page's clock lets the relay time: a frame's `t` against its arrival, and a status's read time against its arrival at the page. */
5368 export const BROWSER_HOP = "browser→relay";
5469 export const PAGE_HOP = "read-back→browser";
55 export const LINK_HOPS: readonly string[] = [RELAY_HOP, READ_BACK_HOP, BROWSER_HOP, PAGE_HOP];
70 /** The headline latency, timed by the relay: a command forwarded to the first status showing that joint moved past MOVE_TICKS (src/first-motion.ts). */
71 export const MOTION_HOP = "command→motion";
72 export const LINK_HOPS: readonly string[] = [RELAY_HOP, READ_BACK_HOP, BROWSER_HOP, PAGE_HOP, MOTION_HOP];
5673 export const MAX_HOP_MS = 60_000;
5774
58 export type Kind = "error" | "arrive" | "overshoot" | "settle" | "busToMove";
75 export type Kind = "settleError" | "lag" | "arrive" | "overshoot" | "settle" | "busToMove";
5976 /** Timestamped samples, by joint and kind: [at, value]. */
6077 export interface Records {
6178 joints: Map<number, Record<Kind, Array<readonly [number, number]>>>;
@@ -76,6 +93,7 @@ export function percentile(values: readonly number[], p: number): number | null
7693 }
7794
7895 export interface Spread {
96 /** How many samples: every number is read with it. */
7997 n: number;
8098 p50: number | null;
8199 p95: number | null;
@@ -86,15 +104,16 @@ const round = (v: number | null, digits = 2) => (v === null ? null : Number(v.to
86104 const spread = (values: readonly number[], digits = 2): Spread => ({
87105 n: values.length,
88106 p50: round(percentile(values, 50), digits),
89 p95: round(percentile(values, 95), digits),
107 p95: values.length < MIN_N_FOR_P95 ? null : round(percentile(values, 95), digits),
90108 max: round(values.length ? Math.max(...values) : null, digits),
91109 });
92110
93111 export interface JointCard {
94112 id: number;
95113 joint: string | null;
96 errorTicks: Spread;
97 errorDeg: Spread;
114 settleErrorTicks: Spread;
115 settleErrorDeg: Spread;
116 lagMs: Spread;
98117 arriveMs: Spread;
99118 overshootTicks: Spread;
100119 settleMs: Spread;
@@ -103,13 +122,15 @@ export interface JointCard {
103122 }
104123
105124 export interface Card {
106 /** The headline numbers; null where nothing was measured. */
107 trackingP95Deg: number | null;
108 arriveP95Ms: number | null;
125 /** The headline numbers, every joint pooled, each with its n. Settle error is the precision number. */
126 settleErrorDeg: Spread;
127 lagMs: Spread;
128 arriveMs: Spread;
129 /** The relay's command→motion hop. */
130 commandToMotionMs: Spread;
131 /** Out of `releases`, which is its n; null with none. */
109132 snapBacksPer100Releases: number | null;
110 /** End to end: the sum of every measured hop's p95. */
111 latencyP95Ms: number | null;
112 /** The joint with the highest p95 tracking error. */
133 /** The joint with the highest median settle error. */
113134 worstJoint: string | null;
114135 joints: JointCard[];
115136 snapBacks: { total: number; byCause: Record<Cause, number>; sizeDeg: Spread };
@@ -121,21 +142,22 @@ export interface Card {
121142 export function summarize(records: Records, since = -Infinity): Card {
122143 const after = (list: ReadonlyArray<readonly [number, number]>) => list.filter(([at]) => at >= since).map(([, v]) => v);
123144 const joints: JointCard[] = [];
124 const allErrors: number[] = [];
125 const allArrive: number[] = [];
126 const allBus: number[] = [];
145 const all = { settle: [] as number[], lag: [] as number[], arrive: [] as number[], bus: [] as number[] };
127146 for (const [id, r] of [...records.joints].sort(([a], [b]) => a - b)) {
128 const errors = after(r.error);
129 allErrors.push(...errors);
147 const settle = after(r.settleError);
148 const lag = after(r.lag);
130149 const arrive = after(r.arrive);
131 allArrive.push(...arrive);
132150 const bus = after(r.busToMove);
133 allBus.push(...bus);
151 all.settle.push(...settle);
152 all.lag.push(...lag);
153 all.arrive.push(...arrive);
154 all.bus.push(...bus);
134155 joints.push({
135156 id,
136157 joint: JOINTS[id] ?? null,
137 errorTicks: spread(errors, 0),
138 errorDeg: spread(errors.map((t) => t / TICKS_PER_DEGREE)),
158 settleErrorTicks: spread(settle, 0),
159 settleErrorDeg: spread(settle.map((t) => t / TICKS_PER_DEGREE)),
160 lagMs: spread(lag, 0),
139161 arriveMs: spread(arrive, 0),
140162 overshootTicks: spread(after(r.overshoot), 0),
141163 settleMs: spread(after(r.settle), 0),
@@ -147,14 +169,14 @@ export function summarize(records: Records, since = -Infinity): Card {
147169 const byCause = Object.fromEntries(CAUSES.map((c) => [c, 0])) as Record<Cause, number>;
148170 for (const s of snaps) byCause[s.cause]++;
149171 const releases = records.releases.filter((at) => at >= since).length;
150 const worst = joints.filter((j) => j.errorDeg.p95 !== null).sort((a, b) => b.errorDeg.p95! - a.errorDeg.p95!)[0];
151 const hops: Record<string, Spread> = { ...Object.fromEntries(LINK_HOPS.map((name) => [name, spread(after(records.hops.get(name) ?? []), 2)])), "bus→move": spread(allBus, 0) };
152 const measured = Object.values(hops).filter((h) => h.p95 !== null);
172 const worst = joints.filter((j) => j.settleErrorDeg.p50 !== null).sort((a, b) => b.settleErrorDeg.p50! - a.settleErrorDeg.p50!)[0];
173 const hops: Record<string, Spread> = { ...Object.fromEntries(LINK_HOPS.map((name) => [name, spread(after(records.hops.get(name) ?? []), 2)])), "bus→move": spread(all.bus, 0) };
153174 return {
154 trackingP95Deg: round(percentile(allErrors.map((t) => t / TICKS_PER_DEGREE), 95)),
155 arriveP95Ms: round(percentile(allArrive, 95), 0),
175 settleErrorDeg: spread(all.settle.map((t) => t / TICKS_PER_DEGREE)),
176 lagMs: spread(all.lag, 0),
177 arriveMs: spread(all.arrive, 0),
178 commandToMotionMs: hops[MOTION_HOP]!,
156179 snapBacksPer100Releases: releases ? round((snaps.length / releases) * 100, 1) : null,
157 latencyP95Ms: measured.length ? measured.reduce((sum, h) => sum + h.p95!, 0) : null,
158180 worstJoint: worst ? (worst.joint ?? String(worst.id)) : null,
159181 joints,
160182 snapBacks: { total: snaps.length, byCause, sizeDeg: spread(snaps.flatMap((s) => (s.sizeDeg === null ? [] : [s.sizeDeg]))) },
@@ -163,6 +185,9 @@ export function summarize(records: Records, since = -Infinity): Card {
163185 };
164186 }
165187
188 /** Whether anything at all was recorded: a session with nothing is not kept. */
189 export const measuredAny = (records: Records): boolean => records.snaps.length > 0 || [...records.joints.values()].some((r) => Object.values(r).some((list) => list.length > 0));
190
166191 /** Drops what is older than `since` from every list. */
167192 export function trim(records: Records, since: number): void {
168193 const keep = <T>(list: T[], at: (x: T) => number) => {
@@ -186,6 +211,10 @@ interface Joint {
186211 settling?: { start: number; arrived: number; target: number; dir: number; overshoot: number; inside: boolean; lastEntry: number; crossings: number };
187212 /** A write not yet seen as motion. */
188213 written?: { at: number; from: number };
214 /** Where the joint and its target have stayed since `since`; `counted` once its settle error is written. */
215 rest?: { since: number; present: number; target: number; counted: boolean };
216 /** The targets of the last MAX_LAG_MS and a little more, oldest first: [at, ticks]. */
217 trace: Array<readonly [number, number]>;
189218 }
190219
191220 /** One drive session's measurements; every record also goes to the sinks (the rolling window). */
@@ -200,10 +229,11 @@ export class Tracker {
200229 this.#sinks = sinks;
201230 }
202231
203 #put(id: number, kind: Kind, at: number, value: number): void {
232 #put(id: number, kind: Kind | null, at: number, value: number): void {
204233 for (const records of [this.records, ...this.#sinks]) {
205234 let r = records.joints.get(id);
206 if (!r) records.joints.set(id, (r = { error: [], arrive: [], overshoot: [], settle: [], busToMove: [] }));
235 if (!r) records.joints.set(id, (r = { settleError: [], lag: [], arrive: [], overshoot: [], settle: [], busToMove: [] }));
236 if (kind === null) continue;
207237 r[kind].push([at, value]);
208238 if (r[kind].length > KEEP) r[kind].shift();
209239 }
@@ -211,14 +241,18 @@ export class Tracker {
211241
212242 #joint(id: number): Joint {
213243 let j = this.#joints.get(id);
214 if (!j) this.#joints.set(id, (j = {}));
244 if (!j) this.#joints.set(id, (j = { trace: [] }));
215245 return j;
216246 }
217247
218248 /** The driver's target for a joint, ticks, as the server commands it. */
219249 target(id: number, ticks: number, at: number): void {
220250 const j = this.#joint(id);
251 this.#put(id, null, at, 0); // a joint driven is on the card, its spreads at n = 0 until something is measured
221252 j.target = ticks;
253 j.trace.push([at, ticks]);
254 // One frame older than the look-back is kept: it is where the oldest segment starts.
255 while (j.trace.length > 2 && j.trace[1]![0] < at - MAX_LAG_MS) j.trace.shift();
222256 if (j.settling && Math.abs(ticks - j.settling.target) > ARRIVE_TICKS) this.#settled(id, j);
223257 if (j.present === undefined) {
224258 // Not read yet: a chase from an unknown place, confirmed or dropped by the first read-back.
@@ -244,6 +278,7 @@ export class Tracker {
244278 /** A read-back of Present_Position. */
245279 sample(id: number, present: number, at: number): void {
246280 const j = this.#joint(id);
281 const previous = j.present;
247282 j.present = present;
248283 if (j.written && Math.abs(present - j.written.from) > MOVE_TICKS) {
249284 this.#put(id, "busToMove", at, at - j.written.at);
@@ -251,7 +286,11 @@ export class Tracker {
251286 }
252287 if (j.target === undefined) return;
253288 const error = j.target - present;
254 this.#put(id, "error", at, Math.abs(error));
289 this.#rest(id, j, present, at);
290 if (previous !== undefined && present !== previous) {
291 const lag = followingLag(j.trace, present, Math.sign(present - previous), at);
292 if (lag !== null) this.#put(id, "lag", at, lag);
293 }
255294 if (j.pending && j.pending.from === null) {
256295 // The first read-back: already there is no chase (it cannot be timed); otherwise the chase is on from here.
257296 if (Math.abs(error) <= ARRIVE_TICKS) j.pending = undefined;
@@ -280,6 +319,18 @@ export class Tracker {
280319 if (at - s.arrived >= SETTLE_MS) this.#settled(id, j, at);
281320 }
282321
322 /** Settle error: written once per rest, when the joint and its target have both stayed put for REST_MS. */
323 #rest(id: number, j: Joint, present: number, at: number): void {
324 const r = j.rest;
325 if (!r || Math.abs(present - r.present) > MOVE_TICKS || Math.abs(j.target! - r.target) > MOVE_TICKS) {
326 j.rest = { since: at, present, target: j.target!, counted: false };
327 return;
328 }
329 if (r.counted || at - r.since < REST_MS) return;
330 r.counted = true;
331 this.#put(id, "settleError", at, Math.abs(j.target! - present));
332 }
333
283334 /** The settle watch ends: overshoot, settling time and oscillations are written. */
284335 #settled(id: number, j: Joint, at = j.settling!.arrived): void {
285336 const s = j.settling!;
@@ -321,7 +372,7 @@ export class Tracker {
321372
322373 /** Forget the targets (a hold or a jam re-pins the joints): nothing is being chased now. */
323374 forget(id?: number): void {
324 for (const [jid, j] of this.#joints) if (id === undefined || id === jid) (j.target = undefined), (j.pending = undefined), (j.settling = undefined);
375 for (const [jid, j] of this.#joints) if (id === undefined || id === jid) (j.target = undefined), (j.pending = undefined), (j.settling = undefined), (j.rest = undefined), (j.trace = []);
325376 }
326377
327378 /** Where each read joint is and where the driver wants it (its position when nothing is chased): what the 5 Hz trace samples. */
@@ -336,3 +387,22 @@ export class Tracker {
336387 for (const [id, j] of this.#joints) if (j.settling) this.#settled(id, j, at);
337388 }
338389 }
390
391 /**
392 * How long ago the streamed target passed `present` going in `dir` (+1 up, −1 down), ms; null when it did not within
393 * MAX_LAG_MS, or when the latest pass was a step (frames further apart than STREAM_GAP_MS), which is chased, not followed.
394 * Between two frames the intent is taken to move in a straight line.
395 */
396 export function followingLag(trace: ReadonlyArray<readonly [number, number]>, present: number, dir: number, at: number): number | null {
397 for (let i = trace.length - 1; i > 0; i--) {
398 const [t1, v1] = trace[i]!;
399 const [t0, v0] = trace[i - 1]!;
400 if (t1 < at - MAX_LAG_MS) return null;
401 const passed = dir > 0 ? v0 < present && present <= v1 : v0 > present && present >= v1;
402 if (!passed) continue;
403 if (t1 - t0 > STREAM_GAP_MS) return null;
404 const crossed = t0 + ((present - v0) / (v1 - v0)) * (t1 - t0);
405 return Math.max(0, at - crossed);
406 }
407 return null;
408 }
Software/so101/src/relay.test.ts +33
@@ -449,6 +449,39 @@ describe("relay", () => {
449449 }
450450 });
451451
452 test("command→motion: the relay times a frame it forwards to the first status that shows the joint moved, and reports it to the arm server", async () => {
453 const hops: Record<string, number[]> = {};
454 let position = 2000;
455 const wss = new WebSocketServer({ noServer: true });
456 camera = createServer((_req, res) => res.writeHead(404).end());
457 camera.on("upgrade", (req, socket, head) =>
458 wss.handleUpgrade(req, socket, head, (ws) => {
459 ws.on("message", (d) => {
460 const body = JSON.parse(String(d)) as { ping?: number; hop?: string; ms?: number[] };
461 if (req.url === "/follow") return void setTimeout(() => (position = 2100), 30); // the arm starts moving 30 ms after the frame
462 if (typeof body.ping === "number") ws.send(JSON.stringify({ pong: { t0: body.ping, t1: wallMs(), t2: wallMs() } }));
463 if (body.hop) (hops[body.hop] ??= []).push(...body.ms!);
464 });
465 }),
466 );
467 const pump = setInterval(() => wss.clients.forEach((c) => c.send(JSON.stringify({ readAt: wallMs(), joints: [{ id: 1, position }] }))), 10);
468 try {
469 relay = await startRelay({ port: 0, simulation: simBase, remote: remoteAt(await listening(camera)), link: { ...FAST, staleMs: 500, syncEveryMs: 20 } });
470 const ws = new WebSocket(`ws://127.0.0.1:${relay.port}/follow`);
471 await new Promise((r, j) => (ws.once("open", r), ws.once("error", j)));
472 await sleep(100);
473 ws.send(stamper()({ 1: 2300 }));
474 await sleep(150);
475 expect(hops["command→motion"]).toHaveLength(1);
476 expect(hops["command→motion"]![0]!).toBeGreaterThanOrEqual(29);
477 expect(hops["command→motion"]![0]!).toBeLessThan(120);
478 ws.close();
479 } finally {
480 clearInterval(pump);
481 for (const c of wss.clients) c.terminate();
482 }
483 });
484
452485 test("a page whose clock is 7 s behind has its hops timed on the relay's clock: browser→relay from a frame's t, read-back→browser from the status it got", async () => {
453486 const SKEW = 7000;
454487 const armClock = () => wallMs() + 5000;
Software/so101/src/relay.ts +7 −1
@@ -67,7 +67,8 @@ import { ArmEdges } from "./arm-edges.ts";
6767 import { parseCard, type Facts } from "./facts.ts";
6868 import { MachineFeed } from "./machine-feed.ts";
6969 import { refusalBatch } from "./refusals.ts";
70 import { BROWSER_HOP, PAGE_HOP, parseSnapBack } from "./precision.ts";
70 import { BROWSER_HOP, MOTION_HOP, PAGE_HOP, parseSnapBack } from "./precision.ts";
71 import { FirstMotion } from "./first-motion.ts";
7172 import { perServo } from "./machine-log.ts";
7273 import { parseFrame } from "./safety.ts";
7374 import { acceptsGzip, GzipCache, worthCompressing } from "./compress.ts";
@@ -296,6 +297,8 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
296297 recording = false;
297298 }
298299 };
300 /** Command → first confirmed motion on the real arm (src/first-motion.ts): frames forwarded, statuses received, on this clock. */
301 const firstMotion = new FirstMotion();
299302 const connect = () => {
300303 armLink?.close();
301304 armLink = null;
@@ -308,6 +311,7 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
308311 metrics,
309312 onStatus: (status) => {
310313 if (!onArm()) return;
314 for (const ms of firstMotion.status(status.joints, performance.now())) armLink?.report(MOTION_HOP, ms);
311315 if (facts) for (const edge of edges.observe(status)) facts.event(edge); // a write only at the moment a jam or block begins
312316 machine.status(status);
313317 void push(); // on to the pages as it comes, at the arm's 25 Hz: no wait for the next tick
@@ -949,6 +953,7 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
949953 const rate = new FrameRate();
950954 /** A frame as it goes to the arm server: carrying the STOP epoch it was sent under. */
951955 const stamped = (frame: string, release: boolean) => {
956 if (real) firstMotion.command(parseFrame(frame) ?? new Map(), performance.now());
952957 // `sentAt` is the send time on the arm server's clock (ours plus the offset the link keeps), so it can time the hop; none until the offset is known.
953958 const sentAt = real ? armLink?.armNow() ?? null : wallMs();
954959 return JSON.stringify({ ...(JSON.parse(frame) as object), ...(release ? { type: "release" } : {}), epoch, ...(sentAt === null ? {} : { sentAt: Number(sentAt.toFixed(3)) }) });
@@ -1001,6 +1006,7 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
10011006 machine.note("sent", "follow frame", { values: values(capped) });
10021007 arm.send(stamped(capped, release));
10031008 });
1009 browser.on("close", () => real && firstMotion.forget());
10041010 arm.on("close", (code, why) => browser.close(sendable(code) ? code : 1011, why.length ? why.toString() : "the arm server went away"));
10051011 // A browser that closed the stream on purpose leaves the arm holding; one that vanished leaves it parking.
10061012 browser.on("close", (code) => (overLimit || code === 1000 || code === 1005 || code === HELD_CLOSE ? arm.close(1000) : arm.close(LOST_CLOSE, "the driver's connection was lost")));
Software/so101/src/terminal.test.ts +7 −6
@@ -266,19 +266,20 @@ describe("terminal table", () => {
266266
267267 test("/precision prints the scorecard /admin shows, line by line as text, or the refusal; without a reader it says so", async () => {
268268 expect(typed(emptyRoom(), "/precision")).toEqual({ precision: true });
269 const row = (trackingP95Deg: number) => ({ trackingP95Deg, arriveP95Ms: 200, snapBacks: 1, releases: 4, latencyP95Ms: 40, worstJoint: "elbow_flex" });
270 const hops = { "browser→relay": { n: 4, p50: 3.5, p95: 8 }, "read-back→browser": { n: 2, p50: 6, p95: 11.25 }, "relay→Pi": { n: 0, p50: null, p95: null } };
269 const row = (settleErrorP95Deg: number) => ({ settleErrorP95Deg, settleErrorN: 24, arriveP95Ms: 200, arriveN: 30, snapBacks: 1, releases: 4, commandToMotionP95Ms: 40, commandToMotionN: 25, worstJoint: "elbow_flex" });
270 const hops = { "browser→relay": { n: 24, p50: 3.5, p95: 8 }, "read-back→browser": { n: 2, p50: 6, p95: null }, "relay→Pi": { n: 0, p50: null, p95: null } };
271271 const body = { commit: "abc1234", window: { worstJoint: "wrist\x1b[31m_roll", hops }, sessions: [row(1), row(3)] };
272272 const asked: Array<[string, unknown]> = [];
273273 const fetcher = (async (url: string, init: RequestInit) => (asked.push([url, init.headers]), Response.json(body))) as unknown as typeof fetch;
274274 const card = await cardReader({ PORT: "8102" }, fetcher)();
275275 expect(asked[0]![0]).toBe("http://127.0.0.1:8102/precision");
276276 const lines = precisionLines(card.panel!);
277 expect(lines[0]).toMatch(/^Tracking error, p95 +3° +▁█$/);
278 expect(lines).toContain("worst joint wrist[31m_roll · last 10 minutes, else the last session · trend over 2 sessions · commit abc1234");
277 expect(lines[0]).toMatch(/^Settle error, p95 +3° \(n = 24\) +▁█$/);
278 expect(lines[1]).toMatch(/^Following lag, p95 +— +$|^Following lag, p95 +—$/);
279 expect(lines).toContain("worst joint wrist[31m_roll · a p95 needs n ≥ 20 · last 10 minutes, else the last session · trend over 2 sessions · commit abc1234");
279280 expect(lines).toContain("latency by hop:");
280 expect(lines).toContain(" browser→relay p50 3.5 · p95 8 ms");
281 expect(lines).toContain(" read-back→browser p50 6 · p95 11.25 ms");
281 expect(lines).toContain(" browser→relay p50 3.5 · p95 8 ms · n = 24");
282 expect(lines).toContain(" read-back→browser p50 6 · p95 — ms · n = 2");
282283 expect(lines.join("\n")).not.toContain("relay→Pi");
283284 expect(precisionLines({ ...card.panel!, hops: [] }).at(-1)).toContain("real arm only");
284285 const refused = await cardReader({ PORT: "8102" }, (async () => Response.json({ error: "no such route" }, { status: 404 })) as unknown as typeof fetch)();
Software/so101/src/terminal.ts +3 −3
@@ -53,7 +53,7 @@ import { ID, NAME, sign } from "./identity.ts";
5353 import { readServos, type ServoPanel } from "./servo-panel.ts";
5454 import { readTuning, tuningSentence, type TuningView } from "./tuning-panel.ts";
5555 import { JOINTS } from "./sts3215.ts";
56 import { headlineValue, hopLines, NO_HOPS, readPrecision, sparkline, type PrecisionPanel } from "./precision-panel.ts";
56 import { headlineValue, hopLines, NO_HOPS, P95_RULE, readPrecision, sampleSize, sparkline, type PrecisionPanel } from "./precision-panel.ts";
5757 import { presenceText } from "./ui/lobby-panel.js";
5858 import { entryLine, jointRows, linkRows, stateRows } from "./ui/machine.js";
5959
@@ -279,8 +279,8 @@ export function precisionLines(p: PrecisionPanel): string[] {
279279 if (!p.sessions && p.headline.every((h) => h.value === null)) return [plain(`nothing measured yet: drive the arm and the numbers appear · commit ${p.commit}`)];
280280 const width = Math.max(...p.headline.map((h) => h.label.length));
281281 return [
282 ...p.headline.map((h) => plain(`${h.label.padEnd(width)} ${headlineValue(h)} ${sparkline(h.trend)}`).trimEnd()),
283 plain(`worst joint ${p.worstJoint ?? "—"} · last 10 minutes, else the last session · trend over ${p.sessions} session${p.sessions === 1 ? "" : "s"} · commit ${p.commit}`),
282 ...p.headline.map((h) => plain(`${h.label.padEnd(width)} ${headlineValue(h)}${h.n === null ? "" : ` (${sampleSize(h.n)})`} ${sparkline(h.trend)}`).trimEnd()),
283 plain(`worst joint ${p.worstJoint ?? "—"} · ${P95_RULE} · last 10 minutes, else the last session · trend over ${p.sessions} session${p.sessions === 1 ? "" : "s"} · commit ${p.commit}`),
284284 "latency by hop:",
285285 ...(p.hops.length ? hopLines(p.hops).map((l) => plain(` ${l}`)) : [` ${NO_HOPS}`]),
286286 ];
Software/so101/src/tuning-endpoint.test.ts +7 −5
@@ -15,11 +15,11 @@ let server: RunningServer | undefined;
1515 let fake: FakeBus;
1616 let base = "";
1717
18 async function boot(sweeps?: SweepResult[], hold = 60) {
18 async function boot(sweeps?: SweepResult[], hold = 60, watchdogMs = 60) {
1919 fake = new FakeBus([1, 2]);
2020 fake.servos.get(1)![21] = 16; // P_Coefficient
2121 server = await startServer(new FeetechBus(fake), {
22 host: "127.0.0.1", port: 0, ids: [1, 2], posesFile: join(mkdtempSync(join(tmpdir(), "so101-tuning-")), "poses.json"), watchdogMs: 60, commit: "abc1234",
22 host: "127.0.0.1", port: 0, ids: [1, 2], posesFile: join(mkdtempSync(join(tmpdir(), "so101-tuning-")), "poses.json"), watchdogMs, commit: "abc1234",
2323 tuningHoldMs: hold,
2424 ...(sweeps ? { tuningSweep: async () => sweeps.shift()! } : {}),
2525 });
@@ -28,7 +28,7 @@ async function boot(sweeps?: SweepResult[], hold = 60) {
2828 afterEach(() => Promise.race([server?.close(), sleep(500)]));
2929 const post = (body: unknown) => fetch(`${base}/tuning/p`, { method: "POST", body: JSON.stringify(body) });
3030 const finished = async () => {
31 for (let i = 0; i < 200; i++) {
31 for (let i = 0; i < 800; i++) {
3232 const s = (await (await fetch(`${base}/tuning`)).json()) as { running: unknown; last: any };
3333 if (!s.running && s.last) return s.last;
3434 await sleep(25);
@@ -90,14 +90,16 @@ test("a run is refused while someone drives, and nothing is written", async () =
9090 // the stream goes on writing goals as the governor ramps; the run writes neither P nor the lock around it
9191 const tuning = fake.writes.slice(writes).filter((w) => w.address === STS3215.P_Coefficient.address || w.address === STS3215.Lock.address);
9292 expect(tuning).toEqual([]);
93 expect(fake.servos.get(1)![21]).toBe(16);
9394 ws.close();
9495 await sleep(100);
9596 });
9697
9798 test("a real sweep through the stream ends with a result and the P that result says", async () => {
98 await boot(undefined, 120);
99 // Each target held past REST_MS, inside the dead-man's patience: a rest per target, so a settle error.
100 await boot(undefined, 900, 1000); // 250 ticks take the governor about 450 ms
99101 expect((await post({ joint: 1, p: 24 })).status).toBe(202);
100102 const last = await finished();
101103 if (last.error) throw new Error(last.error);
102104 expect(fake.servos.get(1)![21]).toBe(last.result.kept ? 24 : 16);
103 }, 20000);
105 }, 30000);
Software/so101/src/tuning-run.ts +1
@@ -2,6 +2,7 @@ import { TUNABLE } from "./servo-params.ts";
22
33 /** What one sweep of a joint measured. */
44 export interface SweepResult {
5 /** Settle error, degrees: the p95, or the max where the sweep had too few rests for one (src/tuning-sweep.ts). */
56 p95Error: number;
67 overshoot: number;
78 timeToArrive: number;
Software/so101/src/tuning-sweep.ts +3 −2
@@ -58,7 +58,8 @@ export async function sweepJoint(joint: number, source: SweepSource): Promise<Sw
5858 for (let waited = 0; source.lastCard() === before && waited < 3000; waited += 25) await sleep(25); // the server closes the session after the socket
5959 const card = source.lastCard();
6060 const j = card === before ? undefined : card?.joints.find((x) => x.id === joint);
61 if (!j || j.errorDeg.p95 === null) throw new Error("the sweep measured nothing");
61 // The error is settle error, where P shows: a sweep has a rest per target, too few for a p95, and of so few the p95 is the max.
62 if (!j || j.settleErrorDeg.max === null) throw new Error("the sweep measured nothing");
6263 if (card!.snapBacks.total) throw new Error("sweep stopped: the arm refused or held back a target");
63 return { p95Error: j.errorDeg.p95, overshoot: j.overshootTicks.max ?? 0, timeToArrive: j.arriveMs.p95 ?? 0 };
64 return { p95Error: j.settleErrorDeg.p95 ?? j.settleErrorDeg.max, overshoot: j.overshootTicks.max ?? 0, timeToArrive: j.arriveMs.p95 ?? j.arriveMs.max ?? 0 };
6465 }

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs