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
Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.
quill/arm:quill/510-precision-numbers-that-mean-what-they-sa → main 9 commits fork
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 | ||
| 1061 | 1061 | Every change to how closely the arm follows is judged by one scorecard, measured on the arm server |
| 1062 | 1062 | (`src/precision.ts`) while a stream drives it: |
| 1063 | 1063 | |
| 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. | |
| 1066 | 1072 | - **Time to arrive**: from a target being set, the joint more than 12 ticks from it, to the first read-back within |
| 1067 | 1073 | 12 ticks. A target that moves during the chase extends the same chase. For 1 s after arriving the joint is watched: |
| 1068 | 1074 | **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 | ||
| 1071 | 1077 | a fixed list: `release-park` (the connection was lost and the arm parks), `hold-expired` (the dead-man held it short), |
| 1072 | 1078 | `zone`, `cap` (a joint limit), `stale-drop`, `maxStep-drop`, `jam`, `STOP`, `turn-end`, `reconnect`. A release is a |
| 1073 | 1079 | 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. | |
| 1077 | 1086 | |
| 1078 | 1087 | **Refusals and the page's snap-backs (#457).** Every frame the relay or the arm server drops, clamps or refuses (the |
| 1079 | 1088 | `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 | ||
| 1092 | 1101 | |
| 1093 | 1102 | Where to read it: |
| 1094 | 1103 | |
| 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. | |
| 1097 | 1107 | - **`/precision` in the terminal** (`$FORGE_APP_SSH`), owner and moderators: the same, as text. |
| 1098 | 1108 | - **`GET /precision` on the app** (the relay), owner and moderators, signed in as for `/admin`: the arm's scorecard |
| 1099 | 1109 | 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: | ||
| 1102 | 1112 | `/metrics`): unauthenticated, for the crew's scripts on that network. It holds timing and position aggregates |
| 1103 | 1113 | only: no names, tokens or commands. |
| 1104 | 1114 | |
| 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. | |
| 1106 | 1116 | The sweep's targets are fixed; the measured numbers move a little with the machine's timers. |
| 1107 | 1117 | |
| 1108 | 1118 | `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 | ||
| 1118 | 1128 | `bench/precision.ts` replays a fixed gesture script on the fake bus, through the real Governor, with servos that |
| 1119 | 1129 | follow their goals at 1500 ticks/s, and prints the same scorecard (`--json` for the whole card). Every precision pull |
| 1120 | 1130 | 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: | |
| 1122 | 1132 | |
| 1123 | 1133 | |
| 1124 | 1134 | p95 tracking error 8.96 ° (worst joint: shoulder_lift) |
| @@ -1138,7 +1148,24 @@ by cause: cap 1, maxStep-drop 1 | ||
| 1138 | 1148 | |
| 1139 | 1149 | |
| 1140 | 1150 | 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. | |
| 1142 | 1169 | |
| 1143 | 1170 | ## Video trial |
| 1144 | 1171 |
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 | ||
| 31 | 31 | |
| 32 | 32 | ## Reading the latency hops |
| 33 | 33 | |
| 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: | |
| 35 | 35 | |
| 36 | 36 | | Hop | From → to, timed by | |
| 37 | 37 | | --- | --- | |
| @@ -40,8 +40,9 @@ Who sees what: a visitor's page says only "Pi update pending" while the commits | ||
| 40 | 40 | | `bus→move` | the arm server's own: a `Goal_Position` write to the first read-back past 3 ticks | |
| 41 | 41 | | `read-back→relay` | the arm server stamps each status with its read time; the relay compares on arrival | |
| 42 | 42 | | `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`) | | |
| 43 | 44 | |
| 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. | |
| 45 | 46 | |
| 46 | 47 | ## Reading a session's trace |
| 47 | 48 | |
| @@ -55,7 +56,7 @@ The owner can test a joint's P (the position gain, 1–64) on the real arm, with | ||
| 55 | 56 | |
| 56 | 57 | 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; |
| 57 | 58 | 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. | |
| 59 | 60 | |
| 60 | 61 | 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. |
| 61 | 62 |
Software/so101/bench/limits-search.test.ts +1 −1
| @@ -5,7 +5,7 @@ import { run, table } from "./limits-search.ts"; | ||
| 5 | 5 | test("on the fake bus a joint's search ends in a table, and the arm's settings end at the 'after' limits", async () => { |
| 6 | 6 | const arm = await fakeArm(); |
| 7 | 7 | 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 | |
| 9 | 9 | const md = table(found); |
| 10 | 10 | expect(md.split("\n")).toHaveLength(3); |
| 11 | 11 | 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 | ||
| 81 | 81 | await sleep(150); |
| 82 | 82 | } |
| 83 | 83 | 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"); | |
| 85 | 86 | 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 }; | |
| 87 | 88 | } |
| 88 | 89 | |
| 89 | 90 | /** 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[] { | ||
| 39 | 39 | } |
| 40 | 40 | |
| 41 | 41 | 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. */ | |
| 42 | 43 | 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}`; | |
| 44 | 45 | } |
| 45 | 46 | |
| 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 | ||
| 46 | 50 | /** Drives every joint through its targets and answers the lines, one per joint. Throws, naming why, where it must stop. */ |
| 47 | 51 | export async function sweep(url: string, hold = HOLD_MS, out: (s: string) => void = () => {}): Promise<string[]> { |
| 48 | 52 | const status = await get<Status>(url, "/status"); |
| @@ -50,7 +54,7 @@ export async function sweep(url: string, hold = HOLD_MS, out: (s: string) => voi | ||
| 50 | 54 | const why = stopped(status); |
| 51 | 55 | if (why) throw new Error(`refusing to start: ${why} is in force`); |
| 52 | 56 | 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)}`); | |
| 54 | 58 | const lines: string[] = []; |
| 55 | 59 | let total = before.snapBacks.total; |
| 56 | 60 | for (const joint of status.joints) { |
| @@ -81,7 +85,7 @@ export async function sweep(url: string, hold = HOLD_MS, out: (s: string) => voi | ||
| 81 | 85 | lines.push(l); |
| 82 | 86 | } |
| 83 | 87 | 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)}`); | |
| 85 | 89 | return lines; |
| 86 | 90 | } |
| 87 | 91 |
Software/so101/bench/precision-report.test.ts +18 −13
| @@ -8,21 +8,25 @@ const row = (daysAgo: number, o: Partial<Row>): Row => ({ | ||
| 8 | 8 | commit: "abc", |
| 9 | 9 | sessions: 1, |
| 10 | 10 | seconds: 60, |
| 11 | trackingP95Deg: 5, | |
| 12 | trackingMaxDeg: 9, | |
| 11 | settleErrorP95Deg: 5, | |
| 12 | settleErrorN: 20, | |
| 13 | lagP95Ms: 80, | |
| 14 | lagN: 100, | |
| 13 | 15 | arriveP95Ms: 400, |
| 16 | arriveN: 20, | |
| 17 | commandToMotionP95Ms: 20, | |
| 18 | commandToMotionN: 30, | |
| 14 | 19 | snapBacks: 1, |
| 15 | 20 | releases: 10, |
| 16 | latencyP95Ms: 20, | |
| 17 | 21 | worstJoint: "elbow_flex", |
| 18 | 22 | ...o, |
| 19 | 23 | }); |
| 20 | 24 | |
| 21 | 25 | 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" }), | |
| 26 | 30 | ]; |
| 27 | 31 | |
| 28 | 32 | 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 | ||
| 31 | 35 | |
| 32 | 36 | | | this week | last week | change | |
| 33 | 37 | |---|---|---|---| |
| 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 | | |
| 38 | 43 | |
| 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. | |
| 40 | 45 | |
| 41 | 46 | **Worst joint:** shoulder_pan (last week: wrist_flex) |
| 42 | 47 | |
| @@ -46,7 +51,7 @@ Hours measured: 2 this week, 2 last. Lower is better in every row; each is the w | ||
| 46 | 51 | |
| 47 | 52 | test("an empty history and a missing experiment print dashes, not a crash", () => { |
| 48 | 53 | 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) | – |"); | |
| 50 | 55 | expect(text).toContain("none measured"); |
| 51 | 56 | expect(text).toContain("none named"); |
| 52 | 57 | }); |
Software/so101/bench/precision-report.ts +33 −16
| @@ -12,33 +12,47 @@ const WEEK_MS = 7 * 24 * 3600_000; | ||
| 12 | 12 | const HOURS = 14 * 24; |
| 13 | 13 | const README = join(import.meta.dir, "../../README.md"); |
| 14 | 14 | |
| 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. */ | |
| 16 | 16 | export interface Week { |
| 17 | 17 | hours: number; |
| 18 | trackingP95Deg: number | null; | |
| 18 | settleErrorP95Deg: number | null; | |
| 19 | settleErrorN: number; | |
| 20 | lagP95Ms: number | null; | |
| 21 | lagN: number; | |
| 19 | 22 | arriveP95Ms: number | null; |
| 20 | latencyP95Ms: number | null; | |
| 23 | arriveN: number; | |
| 24 | commandToMotionP95Ms: number | null; | |
| 25 | commandToMotionN: number; | |
| 21 | 26 | snapBacksPer100: number | null; |
| 27 | /** The n of the snap-back rate. */ | |
| 28 | releases: number; | |
| 22 | 29 | worstJoint: string | null; |
| 23 | 30 | } |
| 24 | 31 | |
| 25 | 32 | 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); | |
| 26 | 34 | |
| 27 | 35 | export function week(rows: readonly Row[], from: number, to: number): Week { |
| 28 | 36 | const mine = rows.filter((r) => { |
| 29 | 37 | const t = Date.parse(r.at); |
| 30 | 38 | return t > from && t <= to; |
| 31 | 39 | }); |
| 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]; | |
| 35 | 43 | return { |
| 36 | 44 | 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)), | |
| 38 | 49 | 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)), | |
| 40 | 53 | 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, | |
| 42 | 56 | }; |
| 43 | 57 | } |
| 44 | 58 | |
| @@ -58,19 +72,22 @@ function delta(now: number | null, before: number | null, digits: number, unit: | ||
| 58 | 72 | export function report(card: Pick<Scorecard, "hours" | "commit">, now: number, open: string | null): string { |
| 59 | 73 | const cur = week(card.hours, now - WEEK_MS, now); |
| 60 | 74 | 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)} |`; | |
| 63 | 79 | return [ |
| 64 | 80 | `## Precision, week to ${new Date(now).toISOString().slice(0, 10)}`, |
| 65 | 81 | "", |
| 66 | 82 | "| | this week | last week | change |", |
| 67 | 83 | "|---|---|---|---|", |
| 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, ""), | |
| 72 | 89 | "", |
| 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.`, | |
| 74 | 91 | "", |
| 75 | 92 | `**Worst joint:** ${cur.worstJoint ?? "none measured"}${prev.worstJoint ? ` (last week: ${prev.worstJoint})` : ""}`, |
| 76 | 93 | "", |
Software/so101/bench/precision.test.ts +10 −7
| @@ -8,14 +8,17 @@ test("the gesture script is fixed: the same frames every run", () => { | ||
| 8 | 8 | |
| 9 | 9 | test("a short script on the fake bus gives a scorecard with every headline number", async () => { |
| 10 | 10 | const card = await bench([ |
| 11 | // each pose held well past REST_MS (250 ms) to arrive and rest even on a loaded machine | |
| 11 | 12 | { 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 | |
| 15 | 16 | ]); |
| 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); | |
| 19 | 21 | 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 | |
| 21 | 24 | }, 10_000); |
Software/so101/bench/precision.ts +18 −6
| @@ -13,7 +13,7 @@ import WebSocket from "ws"; | ||
| 13 | 13 | import { FeetechBus } from "../src/bus.ts"; |
| 14 | 14 | import { wallMs } from "../src/clock.ts"; |
| 15 | 15 | 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"; | |
| 17 | 17 | import type { Scorecard } from "../src/precision-history.ts"; |
| 18 | 18 | import { startServer } from "../src/server.ts"; |
| 19 | 19 | |
| @@ -97,18 +97,30 @@ export async function bench(script: readonly Step[] = gesture()): Promise<Card> | ||
| 97 | 97 | } |
| 98 | 98 | |
| 99 | 99 | 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})`; | |
| 100 | 102 | |
| 101 | 103 | /** The scorecard as text: the headline, then a line per joint, then the snap-backs by cause. */ |
| 102 | 104 | export function render(card: Card): string { |
| 103 | 105 | 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")}`, | |
| 106 | 109 | `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}`, | |
| 108 | 112 | "", |
| 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", | |
| 110 | 114 | ...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(" "), | |
| 112 | 124 | ), |
| 113 | 125 | "", |
| 114 | 126 | `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; } | ||
| 62 | 62 | .bars li span:nth-child(2) { color: var(--blue); } |
| 63 | 63 | .bars li b { color: var(--fg); font-weight: 600; } |
| 64 | 64 | .bars.precision li { grid-template-columns: minmax(8rem, 15rem) 1fr; } |
| 65 | .bars.precision li small { color: var(--dim); font-size: .85em; } | |
| 65 | 66 | .inline { display: inline; margin: 0; } |
| 66 | 67 | .empty { color: var(--dim); } |
| 67 | 68 | @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 | ||
| 39 | 39 | t = 91_000; |
| 40 | 40 | const id = facts.turn({ kind: "turn", ended: { who: person("bob"), reason: "time is up" }, started: null }, snap()); |
| 41 | 41 | 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 } } } })!); | |
| 43 | 43 | const [row] = facts.turns(); |
| 44 | 44 | expect(row).toMatchObject({ seconds: 60, waitSeconds: 30, ended: "time is up", releases: 4, snapBacks: { jam: 2, STOP: 1 }, jams: 2, arriveP95Ms: 120, commit: "c" }); |
| 45 | 45 | expect(row!.who).toMatch(/^[0-9a-f]{16}$/); |
| @@ -52,10 +52,10 @@ test("a turn nobody saw begin is not invented", () => { | ||
| 52 | 52 | }); |
| 53 | 53 | |
| 54 | 54 | 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 }); | |
| 56 | 56 | expect(parseCard({ session: null, window: null })).toBeNull(); |
| 57 | 57 | 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 }); | |
| 59 | 59 | }); |
| 60 | 60 | |
| 61 | 61 | 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 { | ||
| 43 | 43 | const by = (card.snapBacks as { byCause?: Record<string, unknown> } | null)?.byCause ?? {}; |
| 44 | 44 | const snapBacks: Partial<Record<Cause, number>> = {}; |
| 45 | 45 | 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; | |
| 47 | 47 | return { releases: count(card.releases), snapBacks, jams: snapBacks.jam ?? 0, arriveP95Ms: typeof p95 === "number" && Number.isFinite(p95) ? p95 : null }; |
| 48 | 48 | } |
| 49 | 49 |
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 = new Map<number, { position: number; still: boolean }>(); | |
| 19 | readonly = 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..get(id); | |
| 25 | if (!known?.still || this..has(id) || Math.abs(target - known.position) <= MOVE_TICKS) continue; | |
| 26 | this..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..get(id); | |
| 38 | this..set(id, { position, still: before !== undefined && Math.abs(position - before.position) <= MOVE_TICKS }); | |
| 39 | const wait = this..get(id); | |
| 40 | if (!wait) continue; | |
| 41 | if (at - wait.at > MAX_WAIT_MS) this..delete(id); | |
| 42 | else if (Math.abs(position - wait.from) > MOVE_TICKS) { | |
| 43 | timed.push(Math.max(0, at - wait.at)); | |
| 44 | this..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..clear(); | |
| 53 | } | |
| 54 | } |
Software/so101/src/jam-stream.test.ts +2 −1
| @@ -53,7 +53,8 @@ describe("a jam is load without progress", () => { | ||
| 53 | 53 | }, 10_000); |
| 54 | 54 | |
| 55 | 55 | 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); | |
| 57 | 58 | const asked = performance.now(); |
| 58 | 59 | const push = setInterval(() => ws.send(JSON.stringify({ 1: START + 300, 2: START + 300 })), 20); |
| 59 | 60 | let s = await get<Status>("/status"); |
Software/so101/src/precision-history.test.ts +49 −15
| @@ -1,4 +1,5 @@ | ||
| 1 | 1 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; |
| 2 | import { Database } from "bun:sqlite"; | |
| 2 | 3 | import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs"; |
| 3 | 4 | import { tmpdir } from "node:os"; |
| 4 | 5 | import { join } from "node:path"; |
| @@ -20,8 +21,12 @@ describe("the history", () => { | ||
| 20 | 21 | const history = new PrecisionHistory({ file, commit: "abc1234", now: () => now }); |
| 21 | 22 | for (const short of [10, 100]) { |
| 22 | 23 | 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 | } | |
| 25 | 30 | t.release(now + 20); |
| 26 | 31 | t.snapBack("jam", now + 20, 1, short); |
| 27 | 32 | now += 60_000; |
| @@ -33,25 +38,53 @@ describe("the history", () => { | ||
| 33 | 38 | expect(card.commit).toBe("def5678"); |
| 34 | 39 | expect(card.sessions).toHaveLength(2); |
| 35 | 40 | 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); | |
| 37 | 43 | 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); | |
| 41 | 47 | again.close(); |
| 42 | 48 | }); |
| 43 | 49 | |
| 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 | ||
| 44 | 73 | test("the window is the last ten minutes, and a session that measured nothing is not stored", () => { |
| 45 | 74 | let now = 0; |
| 46 | 75 | const history = new PrecisionHistory({ commit: "abc1234", now: () => now }); |
| 47 | 76 | const t = history.begin(); |
| 48 | 77 | 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 }); | |
| 51 | 80 | history.end(t); |
| 52 | 81 | 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); | |
| 55 | 88 | expect(history.scorecard().sessions).toHaveLength(1); |
| 56 | 89 | }); |
| 57 | 90 | |
| @@ -83,11 +116,11 @@ describe("GET /precision on the arm server", () => { | ||
| 83 | 116 | afterAll(() => Promise.race([server.close(), sleep(500)])); |
| 84 | 117 | const card = async () => (await (await fetch(`${base}/precision`)).json()) as Scorecard; |
| 85 | 118 | |
| 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 () => { | |
| 87 | 120 | const ws = new WebSocket(`ws://127.0.0.1:${server.port}/follow`); |
| 88 | 121 | await new Promise((r) => ws.once("open", r)); |
| 89 | 122 | ws.send(JSON.stringify({ "1": 2100 })); |
| 90 | await sleep(150); | |
| 123 | await sleep(500); // there and at rest: a settle error | |
| 91 | 124 | for (const t of [2450, 2800, 3150]) { |
| 92 | 125 | ws.send(JSON.stringify({ "1": t })); |
| 93 | 126 | await sleep(60); |
| @@ -102,7 +135,7 @@ describe("GET /precision on the arm server", () => { | ||
| 102 | 135 | await sleep(400); |
| 103 | 136 | const live = await card(); |
| 104 | 137 | 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); | |
| 106 | 139 | ws.send(JSON.stringify({ "1": 3100 })); // 357 ticks away at 90°/s: still on its way when the stop comes |
| 107 | 140 | await sleep(80); |
| 108 | 141 | 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", () => { | ||
| 123 | 156 | expect(causes.jam).toBe(1); |
| 124 | 157 | expect(causes.STOP).toBe(1); |
| 125 | 158 | expect(after.window.releases).toBe(1); |
| 126 | expect(after.window.trackingP95Deg).not.toBeNull(); | |
| 159 | expect(after.window.settleErrorDeg.n).toBeGreaterThan(0); | |
| 127 | 160 | }); |
| 128 | 161 | |
| 129 | 162 | 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", () => { | ||
| 158 | 191 | expect(pong.t1).toBeGreaterThanOrEqual(t0); |
| 159 | 192 | expect(heard.find((m) => m.joints)!.readAt).toBeGreaterThanOrEqual(t0 - 1000); |
| 160 | 193 | 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 | |
| 162 | 195 | watch.close(); |
| 163 | 196 | }); |
| 164 | 197 | |
| @@ -192,6 +225,7 @@ describe("the 5 Hz trace", () => { | ||
| 192 | 225 | history.sampleTrace(t); |
| 193 | 226 | tick(200); |
| 194 | 227 | } |
| 228 | t.sample(1, 2048, 1000); // it arrives: a session that measured something, so it is kept | |
| 195 | 229 | history.end(t); |
| 196 | 230 | }; |
| 197 | 231 |
Software/so101/src/precision-history.ts +68 −26
| @@ -9,7 +9,7 @@ import { existsSync, readFileSync } from "node:fs"; | ||
| 9 | 9 | import { join } from "node:path"; |
| 10 | 10 | import type { PExperiment } from "./tuning-run.ts"; |
| 11 | 11 | 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"; | |
| 13 | 13 | |
| 14 | 14 | /** The deployed commit: the forge's or CI's variable when set, else the checkout's HEAD, else "unknown". Never a shell. */ |
| 15 | 15 | 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 { | ||
| 70 | 70 | } |
| 71 | 71 | } |
| 72 | 72 | |
| 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). */ | |
| 74 | 74 | export interface Row { |
| 75 | 75 | at: string; |
| 76 | 76 | commit: string; |
| 77 | 77 | sessions: number; |
| 78 | 78 | seconds: number; |
| 79 | trackingP95Deg: number | null; | |
| 80 | trackingMaxDeg: number | null; | |
| 79 | settleErrorP95Deg: number | null; | |
| 80 | settleErrorN: number; | |
| 81 | lagP95Ms: number | null; | |
| 82 | lagN: number; | |
| 81 | 83 | arriveP95Ms: number | null; |
| 84 | arriveN: number; | |
| 85 | commandToMotionP95Ms: number | null; | |
| 86 | commandToMotionN: number; | |
| 82 | 87 | snapBacks: number; |
| 83 | 88 | releases: number; |
| 84 | latencyP95Ms: number | null; | |
| 85 | 89 | worstJoint: string | null; |
| 86 | 90 | } |
| 87 | 91 | |
| @@ -103,8 +107,47 @@ export interface Scorecard { | ||
| 103 | 107 | hours: Row[]; |
| 104 | 108 | } |
| 105 | 109 | |
| 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 | }); | |
| 108 | 151 | |
| 109 | 152 | export class PrecisionHistory { |
| 110 | 153 | readonly commit: string; |
| @@ -121,13 +164,18 @@ export class PrecisionHistory { | ||
| 121 | 164 | this. = options.now ?? Date.now; |
| 122 | 165 | this. = openDb(options.file ?? ":memory:"); |
| 123 | 166 | this..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`; | |
| 126 | 169 | this..run(`CREATE TABLE IF NOT EXISTS sessions (id INTEGER PRIMARY KEY, at TEXT NOT NULL, ${columns}, card TEXT NOT NULL)`); |
| 127 | 170 | this..run("CREATE TABLE IF NOT EXISTS traces (session INTEGER PRIMARY KEY, t0 INTEGER NOT NULL, hz INTEGER NOT NULL, joints TEXT NOT NULL)"); |
| 128 | 171 | this..run("CREATE TABLE IF NOT EXISTS tunings (id INTEGER PRIMARY KEY, commit_id TEXT NOT NULL, result TEXT NOT NULL)"); |
| 129 | 172 | // An hour's roll-up keeps the worst of its sessions' p95s: one bad session in the hour is what the trend must show. |
| 130 | 173 | this..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..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..run(`ALTER TABLE ${table} ADD COLUMN ${c} ${fold === "sum" ? "INTEGER NOT NULL DEFAULT 0" : "REAL"}`); | |
| 178 | } | |
| 131 | 179 | } |
| 132 | 180 | |
| 133 | 181 | /** A drive session starts: its tracker, whose records also feed the window. */ |
| @@ -166,24 +214,21 @@ export class PrecisionHistory { | ||
| 166 | 214 | this.last = card; |
| 167 | 215 | const trace = this..get(tracker); |
| 168 | 216 | this..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; | |
| 171 | 218 | 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(", "); | |
| 174 | 223 | const iso = new Date(at).toISOString(); |
| 175 | this..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..query(`INSERT INTO sessions (at, ${names}, card) VALUES (${marks(row.length + 2)})`).run(iso, ...row, JSON.stringify(card)); | |
| 176 | 225 | 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(", "); | |
| 177 | 227 | this. |
| 178 | 228 | .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`, | |
| 187 | 232 | ) |
| 188 | 233 | .run(hour, ...row); |
| 189 | 234 | if (trace && trace.samples > 0) { |
| @@ -197,10 +242,7 @@ export class PrecisionHistory { | ||
| 197 | 242 | |
| 198 | 243 | /** The stored rows, oldest first. */ |
| 199 | 244 | 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 ?`; | |
| 204 | 246 | const rows = this..query(sql).all(limit) as Stored[]; |
| 205 | 247 | return rows.reverse().map(fromStored); |
| 206 | 248 | } |
Software/so101/src/precision-panel.test.ts +28 −16
| @@ -8,23 +8,35 @@ import { Lobby } from "./lobby.ts"; | ||
| 8 | 8 | import { precisionSection, readPrecision, sparkline } from "./precision-panel.ts"; |
| 9 | 9 | import { startRelay, type RunningRelay } from "./relay.ts"; |
| 10 | 10 | |
| 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: [] }); | |
| 13 | 14 | |
| 14 | 15 | describe("reading /precision", () => { |
| 15 | 16 | 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]); | |
| 18 | 21 | 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]); | |
| 20 | 23 | expect(p.worstJoint).toBe("wrist_flex"); |
| 21 | 24 | expect(readPrecision(scorecard())!.worstJoint).toBe("elbow_flex"); |
| 22 | 25 | }); |
| 23 | 26 | |
| 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 } }; | |
| 26 | 37 | 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>"); | |
| 28 | 40 | expect(precisionSection(p, esc)).toContain("browser→relay"); |
| 29 | 41 | expect(readPrecision(scorecard())!.hops).toEqual([]); |
| 30 | 42 | }); |
| @@ -32,7 +44,7 @@ describe("reading /precision", () => { | ||
| 32 | 44 | test("anything that is not a scorecard is null; a field of the wrong type is a gap, never an error", () => { |
| 33 | 45 | expect(readPrecision("nope")).toBeNull(); |
| 34 | 46 | 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: [] })!; | |
| 36 | 48 | expect(p.headline[0]!.value).toBeNull(); |
| 37 | 49 | expect(p.headline[0]!.trend).toEqual([null]); |
| 38 | 50 | }); |
| @@ -76,14 +88,14 @@ describe("the Precision panel on /admin", () => { | ||
| 76 | 88 | return { base: `http://127.0.0.1:${relay.port}`, asked: () => asked }; |
| 77 | 89 | }; |
| 78 | 90 | |
| 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 } }))); | |
| 81 | 93 | expect((await fetch(`${base}/admin`)).status).toBe(404); |
| 82 | 94 | expect(asked()).toBe(0); |
| 83 | 95 | const html = await (await fetch(`${base}/admin`, { headers: owner })).text(); |
| 84 | 96 | 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>"); | |
| 87 | 99 | expect(html).toContain("elbow_flex"); |
| 88 | 100 | expect(html).toContain("commit abc1234"); |
| 89 | 101 | }); |
| @@ -96,7 +108,7 @@ describe("the Precision panel on /admin", () => { | ||
| 96 | 108 | }); |
| 97 | 109 | |
| 98 | 110 | 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 } }))); | |
| 100 | 112 | for (const headers of [{}, guest]) { |
| 101 | 113 | const refused = await fetch(`${base}/precision`, { headers }); |
| 102 | 114 | expect(refused.status).toBe(404); |
| @@ -105,7 +117,7 @@ describe("the Precision panel on /admin", () => { | ||
| 105 | 117 | expect(asked()).toBe(0); |
| 106 | 118 | const res = await fetch(`${base}/precision?hours=336`, { headers: owner }); |
| 107 | 119 | 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 } } }); | |
| 109 | 121 | expect(asked()).toBe(1); |
| 110 | 122 | expect((await fetch(`${base}/precision?hours=0`, { headers: owner })).status).toBe(400); |
| 111 | 123 | expect((await fetch(`${base}/precision?hours=1;x`, { headers: owner })).status).toBe(400); |
| @@ -117,7 +129,7 @@ describe("the Precision panel on /admin", () => { | ||
| 117 | 129 | const { base } = await boot(() => Response.json({})); |
| 118 | 130 | arm!.stop(true); |
| 119 | 131 | 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?.(); | |
| 121 | 133 | const again = await startRelay({ port: 0, simulation: `http://127.0.0.1:${arm.port}`, lobby }); |
| 122 | 134 | const url = `http://127.0.0.1:${again.port}/precision/trace`; |
| 123 | 135 | try { |
Software/so101/src/precision-panel.ts +35 −16
| @@ -1,9 +1,11 @@ | ||
| 1 | 1 | /** |
| 2 | 2 | * 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. | |
| 5 | 6 | */ |
| 6 | 7 | |
| 8 | import { MIN_N_FOR_P95 } from "./precision.ts"; | |
| 7 | 9 | import { readTuningResult, tuningList, type TuningResult } from "./tuning-panel.ts"; |
| 8 | 10 | |
| 9 | 11 | const SPARK = "▁▂▃▄▅▆▇█"; |
| @@ -13,6 +15,8 @@ export interface Headline { | ||
| 13 | 15 | label: string; |
| 14 | 16 | unit: string; |
| 15 | 17 | value: number | null; |
| 18 | /** How many samples `value` is of (releases, for the snap-back rate); null when not known. */ | |
| 19 | n: number | null; | |
| 16 | 20 | /** The same number, session by session, oldest first; null where a session did not measure it. */ |
| 17 | 21 | trend: Array<number | null>; |
| 18 | 22 | } |
| @@ -25,7 +29,7 @@ export interface PrecisionPanel { | ||
| 25 | 29 | /** The P experiments kept, newest first. */ |
| 26 | 30 | tunings: TuningResult[]; |
| 27 | 31 | /** 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 }>; | |
| 29 | 33 | } |
| 30 | 34 | |
| 31 | 35 | 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 { | ||
| 40 | 44 | const rows = card.sessions.slice(-TREND).map(obj); |
| 41 | 45 | const last = rows.at(-1) ?? {}; |
| 42 | 46 | // 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 | }; | |
| 44 | 53 | const rate = (r: Record<string, unknown>) => { |
| 45 | 54 | const snaps = num(r.snapBacks), releases = num(r.releases); |
| 46 | 55 | return snaps !== null && releases ? Number(((snaps / releases) * 100).toFixed(1)) : null; |
| 47 | 56 | }; |
| 57 | const windowRate = num(window.snapBacksPer100Releases); | |
| 48 | 58 | const hops = Object.entries(obj(window.hops)).flatMap(([name, h]) => { |
| 49 | 59 | 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) }] : []; | |
| 52 | 63 | }); |
| 53 | 64 | return { |
| 54 | 65 | hops, |
| @@ -57,17 +68,21 @@ export function readPrecision(body: unknown): PrecisionPanel | null { | ||
| 57 | 68 | sessions: rows.length, |
| 58 | 69 | tunings: (Array.isArray(card.tunings) ? card.tunings : []).slice(0, 20).map(readTuningResult).filter((t): t is TuningResult => t !== null), |
| 59 | 70 | 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"), | |
| 64 | 76 | ], |
| 65 | 77 | }; |
| 66 | 78 | } |
| 67 | 79 | |
| 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. */ | |
| 69 | 81 | export const headlineValue = (h: Headline): string => (h.value === null ? "—" : `${h.value}${h.unit && h.unit !== "°" ? " " : ""}${h.unit}`); |
| 70 | 82 | |
| 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 | ||
| 71 | 86 | /** A row of block characters, lowest to highest; a gap for a session that did not measure it. */ |
| 72 | 87 | export function sparkline(values: ReadonlyArray<number | null>): string { |
| 73 | 88 | const known = values.filter((v): v is number => v !== null); |
| @@ -85,21 +100,25 @@ export function precisionSection(p: PrecisionPanel | null | undefined, esc: (s: | ||
| 85 | 100 | .map((h) => { |
| 86 | 101 | const value = headlineValue(h); |
| 87 | 102 | 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>`; | |
| 89 | 105 | }) |
| 90 | 106 | .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>`; | |
| 92 | 108 | } |
| 93 | 109 | |
| 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 | ||
| 94 | 113 | /** What is said where the hops would be, when none was timed: the simulation has no link to time. */ |
| 95 | 114 | export const NO_HOPS = "No link hops timed: they are measured against the real arm only, while someone drives it."; |
| 96 | 115 | |
| 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}`); | |
| 99 | 118 | |
| 100 | 119 | /** The hops that were timed, each with its p50 and p95; nothing when none was. */ |
| 101 | 120 | function hopList(hops: PrecisionPanel["hops"], esc: (s: string) => string): string { |
| 102 | 121 | 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(""); | |
| 104 | 123 | return `<h3>Latency by hop, p50 / p95</h3><ol class="bars precision" aria-label="Latency by hop">${rows}</ol>`; |
| 105 | 124 | } |
Software/so101/src/precision.test.ts +93 −34
| @@ -1,5 +1,5 @@ | ||
| 1 | 1 | 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"; | |
| 3 | 3 | |
| 4 | 4 | describe("percentile", () => { |
| 5 | 5 | test("nearest rank, unsorted input, none for an empty list", () => { |
| @@ -10,26 +10,91 @@ describe("percentile", () => { | ||
| 10 | 10 | }); |
| 11 | 11 | }); |
| 12 | 12 | |
| 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", () => { | |
| 15 | 21 | 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° | |
| 21 | 34 | 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 | |
| 25 | 38 | 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); | |
| 27 | 54 | }); |
| 28 | 55 | |
| 29 | 56 | test("a joint with no target yet is not counted", () => { |
| 30 | 57 | 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(); | |
| 33 | 98 | }); |
| 34 | 99 | }); |
| 35 | 100 | |
| @@ -91,27 +156,24 @@ describe("bus to motion", () => { | ||
| 91 | 156 | t.sample(1, 2003, 20); // not yet |
| 92 | 157 | t.sample(1, 2010, 35); |
| 93 | 158 | 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); | |
| 97 | 161 | }); |
| 98 | 162 | }); |
| 99 | 163 | |
| 100 | 164 | 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", () => { | |
| 102 | 166 | const t = new Tracker(0); |
| 103 | 167 | for (const ms of [4, 6, 8, 10]) expect(t.hop(RELAY_HOP, ms, 100)).toBe(true); |
| 104 | 168 | expect(t.hop(READ_BACK_HOP, 3, 100)).toBe(true); |
| 105 | 169 | expect(t.hop(RELAY_HOP, -1, 100)).toBe(false); |
| 106 | 170 | expect(t.hop(RELAY_HOP, Number.NaN, 100)).toBe(false); |
| 107 | 171 | 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); | |
| 111 | 173 | 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 }); | |
| 115 | 177 | expect(summarize(t.records, 101).hops[RELAY_HOP]!.n).toBe(0); |
| 116 | 178 | }); |
| 117 | 179 | }); |
| @@ -141,13 +203,11 @@ describe("snap-backs", () => { | ||
| 141 | 203 | t.sample(1, 3000, 30); // nor an arrival |
| 142 | 204 | t.sample(2, 3000, 30); |
| 143 | 205 | const [one, two] = summarize(t.records).joints; |
| 144 | expect(one!.errorTicks.n).toBe(1); | |
| 145 | 206 | expect(one!.arriveMs.n).toBe(0); |
| 146 | expect(two!.errorTicks.n).toBe(2); | |
| 147 | 207 | expect(two!.arriveMs).toMatchObject({ n: 1, p50: 30 }); |
| 148 | 208 | 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 | |
| 151 | 211 | t.target(1, 2000, 50); |
| 152 | 212 | t.sample(1, 2000, 60); |
| 153 | 213 | expect(summarize(t.records).joints[0]!.arriveMs).toMatchObject({ n: 1, p50: 10 }); |
| @@ -164,14 +224,13 @@ describe("the window", () => { | ||
| 164 | 224 | test("records go to the sinks too, and trim drops what is older", () => { |
| 165 | 225 | const window = emptyRecords(); |
| 166 | 226 | 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); | |
| 170 | 229 | t.snapBack("zone", 0); |
| 171 | 230 | 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 }); | |
| 173 | 232 | 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); | |
| 176 | 235 | }); |
| 177 | 236 | }); |
Software/so101/src/precision.ts +102 −32
| @@ -2,7 +2,12 @@ | ||
| 2 | 2 | * The precision instrument: how closely the real arm follows what its driver asks of it. Plain data in (targets, |
| 3 | 3 | * read-backs, bus writes, snap-backs, each with its time in ms), plain data out (a scorecard). |
| 4 | 4 | * |
| 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 | |
| 6 | 11 | * time to arrive from a target being set (with the joint out of reach of it) to the first read-back within |
| 7 | 12 | * ARRIVE_TICKS; then, for SETTLE_MS: the overshoot past the target, the settling time (until the |
| 8 | 13 | * last entry into the band) and the oscillations (each exit and re-entry is one) |
| @@ -11,6 +16,8 @@ | ||
| 11 | 16 | * the relay times on a clock it aligns with the arm server's (src/hops.ts): relay→Pi, from the stamp on |
| 12 | 17 | * a forwarded command, and read-back→relay, from the read time on a status |
| 13 | 18 | * |
| 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 | * | |
| 14 | 21 | * One `Tracker` per drive session; `summarize` folds any span of its records into the same numbers, which is how the |
| 15 | 22 | * rolling window and the stored session rows are made. |
| 16 | 23 | */ |
| @@ -21,6 +28,14 @@ import { JOINTS } from "./sts3215.ts"; | ||
| 21 | 28 | export const ARRIVE_TICKS = 12; |
| 22 | 29 | /** Ticks a joint must move past where it was written from to count as started. */ |
| 23 | 30 | 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; | |
| 24 | 39 | /** How long after arriving the joint is watched for overshoot and oscillation, ms. */ |
| 25 | 40 | export const SETTLE_MS = 1000; |
| 26 | 41 | /** The rolling window, ms. */ |
| @@ -52,10 +67,12 @@ export const READ_BACK_HOP = "read-back→relay"; | ||
| 52 | 67 | /** 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. */ |
| 53 | 68 | export const BROWSER_HOP = "browser→relay"; |
| 54 | 69 | 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]; | |
| 56 | 73 | export const MAX_HOP_MS = 60_000; |
| 57 | 74 | |
| 58 | export type Kind = "error" | "arrive" | "overshoot" | "settle" | "busToMove"; | |
| 75 | export type Kind = "settleError" | "lag" | "arrive" | "overshoot" | "settle" | "busToMove"; | |
| 59 | 76 | /** Timestamped samples, by joint and kind: [at, value]. */ |
| 60 | 77 | export interface Records { |
| 61 | 78 | joints: Map<number, Record<Kind, Array<readonly [number, number]>>>; |
| @@ -76,6 +93,7 @@ export function percentile(values: readonly number[], p: number): number | null | ||
| 76 | 93 | } |
| 77 | 94 | |
| 78 | 95 | export interface Spread { |
| 96 | /** How many samples: every number is read with it. */ | |
| 79 | 97 | n: number; |
| 80 | 98 | p50: number | null; |
| 81 | 99 | p95: number | null; |
| @@ -86,15 +104,16 @@ const round = (v: number | null, digits = 2) => (v === null ? null : Number(v.to | ||
| 86 | 104 | const spread = (values: readonly number[], digits = 2): Spread => ({ |
| 87 | 105 | n: values.length, |
| 88 | 106 | 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), | |
| 90 | 108 | max: round(values.length ? Math.max(...values) : null, digits), |
| 91 | 109 | }); |
| 92 | 110 | |
| 93 | 111 | export interface JointCard { |
| 94 | 112 | id: number; |
| 95 | 113 | joint: string | null; |
| 96 | errorTicks: Spread; | |
| 97 | errorDeg: Spread; | |
| 114 | settleErrorTicks: Spread; | |
| 115 | settleErrorDeg: Spread; | |
| 116 | lagMs: Spread; | |
| 98 | 117 | arriveMs: Spread; |
| 99 | 118 | overshootTicks: Spread; |
| 100 | 119 | settleMs: Spread; |
| @@ -103,13 +122,15 @@ export interface JointCard { | ||
| 103 | 122 | } |
| 104 | 123 | |
| 105 | 124 | 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. */ | |
| 109 | 132 | 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. */ | |
| 113 | 134 | worstJoint: string | null; |
| 114 | 135 | joints: JointCard[]; |
| 115 | 136 | snapBacks: { total: number; byCause: Record<Cause, number>; sizeDeg: Spread }; |
| @@ -121,21 +142,22 @@ export interface Card { | ||
| 121 | 142 | export function summarize(records: Records, since = -Infinity): Card { |
| 122 | 143 | const after = (list: ReadonlyArray<readonly [number, number]>) => list.filter(([at]) => at >= since).map(([, v]) => v); |
| 123 | 144 | 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[] }; | |
| 127 | 146 | 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); | |
| 130 | 149 | const arrive = after(r.arrive); |
| 131 | allArrive.push(...arrive); | |
| 132 | 150 | 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); | |
| 134 | 155 | joints.push({ |
| 135 | 156 | id, |
| 136 | 157 | 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), | |
| 139 | 161 | arriveMs: spread(arrive, 0), |
| 140 | 162 | overshootTicks: spread(after(r.overshoot), 0), |
| 141 | 163 | settleMs: spread(after(r.settle), 0), |
| @@ -147,14 +169,14 @@ export function summarize(records: Records, since = -Infinity): Card { | ||
| 147 | 169 | const byCause = Object.fromEntries(CAUSES.map((c) => [c, 0])) as Record<Cause, number>; |
| 148 | 170 | for (const s of snaps) byCause[s.cause]++; |
| 149 | 171 | 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) }; | |
| 153 | 174 | 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]!, | |
| 156 | 179 | snapBacksPer100Releases: releases ? round((snaps.length / releases) * 100, 1) : null, |
| 157 | latencyP95Ms: measured.length ? measured.reduce((sum, h) => sum + h.p95!, 0) : null, | |
| 158 | 180 | worstJoint: worst ? (worst.joint ?? String(worst.id)) : null, |
| 159 | 181 | joints, |
| 160 | 182 | 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 { | ||
| 163 | 185 | }; |
| 164 | 186 | } |
| 165 | 187 | |
| 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 | ||
| 166 | 191 | /** Drops what is older than `since` from every list. */ |
| 167 | 192 | export function trim(records: Records, since: number): void { |
| 168 | 193 | const keep = <T>(list: T[], at: (x: T) => number) => { |
| @@ -186,6 +211,10 @@ interface Joint { | ||
| 186 | 211 | settling?: { start: number; arrived: number; target: number; dir: number; overshoot: number; inside: boolean; lastEntry: number; crossings: number }; |
| 187 | 212 | /** A write not yet seen as motion. */ |
| 188 | 213 | 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]>; | |
| 189 | 218 | } |
| 190 | 219 | |
| 191 | 220 | /** One drive session's measurements; every record also goes to the sinks (the rolling window). */ |
| @@ -200,10 +229,11 @@ export class Tracker { | ||
| 200 | 229 | this. = sinks; |
| 201 | 230 | } |
| 202 | 231 | |
| 203 | (id: number, kind: Kind, at: number, value: number): void { | |
| 232 | (id: number, kind: Kind | null, at: number, value: number): void { | |
| 204 | 233 | for (const records of [this.records, ...this.]) { |
| 205 | 234 | 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; | |
| 207 | 237 | r[kind].push([at, value]); |
| 208 | 238 | if (r[kind].length > KEEP) r[kind].shift(); |
| 209 | 239 | } |
| @@ -211,14 +241,18 @@ export class Tracker { | ||
| 211 | 241 | |
| 212 | 242 | (id: number): Joint { |
| 213 | 243 | let j = this..get(id); |
| 214 | if (!j) this..set(id, (j = {})); | |
| 244 | if (!j) this..set(id, (j = { trace: [] })); | |
| 215 | 245 | return j; |
| 216 | 246 | } |
| 217 | 247 | |
| 218 | 248 | /** The driver's target for a joint, ticks, as the server commands it. */ |
| 219 | 249 | target(id: number, ticks: number, at: number): void { |
| 220 | 250 | const j = this.(id); |
| 251 | this.(id, null, at, 0); // a joint driven is on the card, its spreads at n = 0 until something is measured | |
| 221 | 252 | 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(); | |
| 222 | 256 | if (j.settling && Math.abs(ticks - j.settling.target) > ARRIVE_TICKS) this.(id, j); |
| 223 | 257 | if (j.present === undefined) { |
| 224 | 258 | // Not read yet: a chase from an unknown place, confirmed or dropped by the first read-back. |
| @@ -244,6 +278,7 @@ export class Tracker { | ||
| 244 | 278 | /** A read-back of Present_Position. */ |
| 245 | 279 | sample(id: number, present: number, at: number): void { |
| 246 | 280 | const j = this.(id); |
| 281 | const previous = j.present; | |
| 247 | 282 | j.present = present; |
| 248 | 283 | if (j.written && Math.abs(present - j.written.from) > MOVE_TICKS) { |
| 249 | 284 | this.(id, "busToMove", at, at - j.written.at); |
| @@ -251,7 +286,11 @@ export class Tracker { | ||
| 251 | 286 | } |
| 252 | 287 | if (j.target === undefined) return; |
| 253 | 288 | const error = j.target - present; |
| 254 | this.(id, "error", at, Math.abs(error)); | |
| 289 | this.(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.(id, "lag", at, lag); | |
| 293 | } | |
| 255 | 294 | if (j.pending && j.pending.from === null) { |
| 256 | 295 | // The first read-back: already there is no chase (it cannot be timed); otherwise the chase is on from here. |
| 257 | 296 | if (Math.abs(error) <= ARRIVE_TICKS) j.pending = undefined; |
| @@ -280,6 +319,18 @@ export class Tracker { | ||
| 280 | 319 | if (at - s.arrived >= SETTLE_MS) this.(id, j, at); |
| 281 | 320 | } |
| 282 | 321 | |
| 322 | /** Settle error: written once per rest, when the joint and its target have both stayed put for REST_MS. */ | |
| 323 | (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.(id, "settleError", at, Math.abs(j.target! - present)); | |
| 332 | } | |
| 333 | ||
| 283 | 334 | /** The settle watch ends: overshoot, settling time and oscillations are written. */ |
| 284 | 335 | (id: number, j: Joint, at = j.settling!.arrived): void { |
| 285 | 336 | const s = j.settling!; |
| @@ -321,7 +372,7 @@ export class Tracker { | ||
| 321 | 372 | |
| 322 | 373 | /** Forget the targets (a hold or a jam re-pins the joints): nothing is being chased now. */ |
| 323 | 374 | forget(id?: number): void { |
| 324 | for (const [jid, j] of this.) if (id === undefined || id === jid) (j.target = undefined), (j.pending = undefined), (j.settling = undefined); | |
| 375 | for (const [jid, j] of this.) if (id === undefined || id === jid) (j.target = undefined), (j.pending = undefined), (j.settling = undefined), (j.rest = undefined), (j.trace = []); | |
| 325 | 376 | } |
| 326 | 377 | |
| 327 | 378 | /** 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 { | ||
| 336 | 387 | for (const [id, j] of this.) if (j.settling) this.(id, j, at); |
| 337 | 388 | } |
| 338 | 389 | } |
| 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", () => { | ||
| 449 | 449 | } |
| 450 | 450 | }); |
| 451 | 451 | |
| 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 | ||
| 452 | 485 | 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 () => { |
| 453 | 486 | const SKEW = 7000; |
| 454 | 487 | const armClock = () => wallMs() + 5000; |
Software/so101/src/relay.ts +7 −1
| @@ -67,7 +67,8 @@ import { ArmEdges } from "./arm-edges.ts"; | ||
| 67 | 67 | import { parseCard, type Facts } from "./facts.ts"; |
| 68 | 68 | import { MachineFeed } from "./machine-feed.ts"; |
| 69 | 69 | 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"; | |
| 71 | 72 | import { perServo } from "./machine-log.ts"; |
| 72 | 73 | import { parseFrame } from "./safety.ts"; |
| 73 | 74 | import { acceptsGzip, GzipCache, worthCompressing } from "./compress.ts"; |
| @@ -296,6 +297,8 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> { | ||
| 296 | 297 | recording = false; |
| 297 | 298 | } |
| 298 | 299 | }; |
| 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(); | |
| 299 | 302 | const connect = () => { |
| 300 | 303 | armLink?.close(); |
| 301 | 304 | armLink = null; |
| @@ -308,6 +311,7 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> { | ||
| 308 | 311 | metrics, |
| 309 | 312 | onStatus: (status) => { |
| 310 | 313 | if (!onArm()) return; |
| 314 | for (const ms of firstMotion.status(status.joints, performance.now())) armLink?.report(MOTION_HOP, ms); | |
| 311 | 315 | if (facts) for (const edge of edges.observe(status)) facts.event(edge); // a write only at the moment a jam or block begins |
| 312 | 316 | machine.status(status); |
| 313 | 317 | 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> { | ||
| 949 | 953 | const rate = new FrameRate(); |
| 950 | 954 | /** A frame as it goes to the arm server: carrying the STOP epoch it was sent under. */ |
| 951 | 955 | const stamped = (frame: string, release: boolean) => { |
| 956 | if (real) firstMotion.command(parseFrame(frame) ?? new Map(), performance.now()); | |
| 952 | 957 | // `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. |
| 953 | 958 | const sentAt = real ? armLink?.armNow() ?? null : wallMs(); |
| 954 | 959 | 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> { | ||
| 1001 | 1006 | machine.note("sent", "follow frame", { values: values(capped) }); |
| 1002 | 1007 | arm.send(stamped(capped, release)); |
| 1003 | 1008 | }); |
| 1009 | browser.on("close", () => real && firstMotion.forget()); | |
| 1004 | 1010 | arm.on("close", (code, why) => browser.close(sendable(code) ? code : 1011, why.length ? why.toString() : "the arm server went away")); |
| 1005 | 1011 | // A browser that closed the stream on purpose leaves the arm holding; one that vanished leaves it parking. |
| 1006 | 1012 | 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", () => { | ||
| 266 | 266 | |
| 267 | 267 | test("/precision prints the scorecard /admin shows, line by line as text, or the refusal; without a reader it says so", async () => { |
| 268 | 268 | 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 } }; | |
| 271 | 271 | const body = { commit: "abc1234", window: { worstJoint: "wrist\x1b[31m_roll", hops }, sessions: [row(1), row(3)] }; |
| 272 | 272 | const asked: Array<[string, unknown]> = []; |
| 273 | 273 | const fetcher = (async (url: string, init: RequestInit) => (asked.push([url, init.headers]), Response.json(body))) as unknown as typeof fetch; |
| 274 | 274 | const card = await cardReader({ PORT: "8102" }, fetcher)(); |
| 275 | 275 | expect(asked[0]![0]).toBe("http://127.0.0.1:8102/precision"); |
| 276 | 276 | 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"); | |
| 279 | 280 | 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"); | |
| 282 | 283 | expect(lines.join("\n")).not.toContain("relay→Pi"); |
| 283 | 284 | expect(precisionLines({ ...card.panel!, hops: [] }).at(-1)).toContain("real arm only"); |
| 284 | 285 | 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"; | ||
| 53 | 53 | import { readServos, type ServoPanel } from "./servo-panel.ts"; |
| 54 | 54 | import { readTuning, tuningSentence, type TuningView } from "./tuning-panel.ts"; |
| 55 | 55 | 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"; | |
| 57 | 57 | import { presenceText } from "./ui/lobby-panel.js"; |
| 58 | 58 | import { entryLine, jointRows, linkRows, stateRows } from "./ui/machine.js"; |
| 59 | 59 | |
| @@ -279,8 +279,8 @@ export function precisionLines(p: PrecisionPanel): string[] { | ||
| 279 | 279 | 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}`)]; |
| 280 | 280 | const width = Math.max(...p.headline.map((h) => h.label.length)); |
| 281 | 281 | 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}`), | |
| 284 | 284 | "latency by hop:", |
| 285 | 285 | ...(p.hops.length ? hopLines(p.hops).map((l) => plain(` ${l}`)) : [` ${NO_HOPS}`]), |
| 286 | 286 | ]; |
Software/so101/src/tuning-endpoint.test.ts +7 −5
| @@ -15,11 +15,11 @@ let server: RunningServer | undefined; | ||
| 15 | 15 | let fake: FakeBus; |
| 16 | 16 | let base = ""; |
| 17 | 17 | |
| 18 | async function boot(sweeps?: SweepResult[], hold = 60) { | |
| 18 | async function boot(sweeps?: SweepResult[], hold = 60, watchdogMs = 60) { | |
| 19 | 19 | fake = new FakeBus([1, 2]); |
| 20 | 20 | fake.servos.get(1)![21] = 16; // P_Coefficient |
| 21 | 21 | 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", | |
| 23 | 23 | tuningHoldMs: hold, |
| 24 | 24 | ...(sweeps ? { tuningSweep: async () => sweeps.shift()! } : {}), |
| 25 | 25 | }); |
| @@ -28,7 +28,7 @@ async function boot(sweeps?: SweepResult[], hold = 60) { | ||
| 28 | 28 | afterEach(() => Promise.race([server?.close(), sleep(500)])); |
| 29 | 29 | const post = (body: unknown) => fetch(`${base}/tuning/p`, { method: "POST", body: JSON.stringify(body) }); |
| 30 | 30 | const finished = async () => { |
| 31 | for (let i = 0; i < 200; i++) { | |
| 31 | for (let i = 0; i < 800; i++) { | |
| 32 | 32 | const s = (await (await fetch(`${base}/tuning`)).json()) as { running: unknown; last: any }; |
| 33 | 33 | if (!s.running && s.last) return s.last; |
| 34 | 34 | await sleep(25); |
| @@ -90,14 +90,16 @@ test("a run is refused while someone drives, and nothing is written", async () = | ||
| 90 | 90 | // the stream goes on writing goals as the governor ramps; the run writes neither P nor the lock around it |
| 91 | 91 | const tuning = fake.writes.slice(writes).filter((w) => w.address === STS3215.P_Coefficient.address || w.address === STS3215.Lock.address); |
| 92 | 92 | expect(tuning).toEqual([]); |
| 93 | expect(fake.servos.get(1)![21]).toBe(16); | |
| 93 | 94 | ws.close(); |
| 94 | 95 | await sleep(100); |
| 95 | 96 | }); |
| 96 | 97 | |
| 97 | 98 | 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 | |
| 99 | 101 | expect((await post({ joint: 1, p: 24 })).status).toBe(202); |
| 100 | 102 | const last = await finished(); |
| 101 | 103 | if (last.error) throw new Error(last.error); |
| 102 | 104 | 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"; | ||
| 2 | 2 | |
| 3 | 3 | /** What one sweep of a joint measured. */ |
| 4 | 4 | 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). */ | |
| 5 | 6 | p95Error: number; |
| 6 | 7 | overshoot: number; |
| 7 | 8 | timeToArrive: number; |
Software/so101/src/tuning-sweep.ts +3 −2
| @@ -58,7 +58,8 @@ export async function sweepJoint(joint: number, source: SweepSource): Promise<Sw | ||
| 58 | 58 | for (let waited = 0; source.lastCard() === before && waited < 3000; waited += 25) await sleep(25); // the server closes the session after the socket |
| 59 | 59 | const card = source.lastCard(); |
| 60 | 60 | 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"); | |
| 62 | 63 | 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 }; | |
| 64 | 65 | } |
new above
offline