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

Migrated from github.com/Trevato/SO-ARM100

workbenchthis machine

/admin 'Try this P' runs the tuning experiment on the arm while nobody drives and keeps every result in the precision history #506

Merged opened this

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

Merged

smith/arm:smith/486-admin-try-this-p-runs-the-tuning-experim → main 4 commits fork

  • Merged. smith/486-admin-try-this-p-runs-the-tuning-experim was merged into main as ffbf834.

Review

Sign in to review this change.
18 files changed +564 −21
Software/so101/README.md +10
@@ -38,3 +38,13 @@ Who sees what: a visitor's page says only "Pi update pending" while the commits
3838 | `read-back→browser` | the same stamp, carried to the page (on the relay's clock), compared there |
3939
4040 `latencyP95Ms` is the sum of the p95s that were measured. The link hops are timed against the real arm only, and only the current driver's page reports its clock (at most once a second); with the simulation, or nobody driving, the list is empty and says so.
41
42 ## Trying a P coefficient
43
44 The owner can test a joint's P (the position gain, 1–64) on the real arm, with nobody at it. On `/admin`, in Servos, type a P beside a joint and press **Try this P**; in the terminal, `/tune <joint> <P>` (for example `/tune shoulder_pan 24`). The arm server then:
45
46 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;
47 2. writes the P (the guarded `PUT /servo-params` path) and sweeps again;
48 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.
49
50 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.
Software/so101/src/admin-page.ts +1 −1
@@ -182,7 +182,7 @@ export const adminCsp = (canEdit: boolean): string =>
182182 `default-src 'none'; style-src 'sha256-${sha(STYLE)}'; script-src 'sha256-${sha(scriptFor(canEdit))}'; connect-src 'self'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'`;
183183
184184 /** The fixed lines a redirect back may ask for; nothing from the request is echoed. */
185 export const DONE = { saved: "Saved.", paused: "Paused: nobody new gets a turn.", resumed: "Open again: the next in line has control.", ended: "Turn ended.", taken: "You have control.", restored: "Line restored.", lifted: "Lifted.", reportRemoved: "Line removed; report closed.", reportMuted: "Author muted; report closed.", reportDismissed: "Report dismissed." } as const;
185 export const DONE = { saved: "Saved.", paused: "Paused: nobody new gets a turn.", resumed: "Open again: the next in line has control.", ended: "Turn ended.", taken: "You have control.", restored: "Line restored.", lifted: "Lifted.", reportRemoved: "Line removed; report closed.", reportMuted: "Author muted; report closed.", reportDismissed: "Report dismissed.", tuning: "The P experiment is running on the arm: reload to follow it." } as const;
186186 export type Done = keyof typeof DONE;
187187
188188 export interface Target { id: string; name: string }
Software/so101/src/admin-relay.test.ts +14
@@ -168,3 +168,17 @@ test("writing servo params and the factory restore are the owner's; anyone else
168168 expect((await fetch(`${base}${path}`, { method, body: "{}", headers: as("trevato", "admin") })).status).not.toBe(404);
169169 }
170170 });
171
172 test("the P experiment is the owner's; anyone else gets 404, on the route and on the admin form", async () => {
173 const base = await boot();
174 for (const [method, path] of [["POST", "/tuning/p"], ["GET", "/tuning"]] as const) {
175 expect((await fetch(`${base}${path}`, { method, body: method === "POST" ? "{}" : undefined })).status).toBe(404);
176 expect((await fetch(`${base}${path}`, { method, body: method === "POST" ? "{}" : undefined, headers: as("bob", "user") })).status).toBe(404);
177 expect((await fetch(`${base}${path}`, { method, body: method === "POST" ? "{}" : undefined, headers: as("trevato", "admin") })).status).not.toBe(404);
178 }
179 expect((await fetch(`${base}/admin`, form(as("bob", "user"), { action: "tune-p", joint: "1", p: "24" }))).status).toBe(404);
180 // the owner's form reaches the arm, which nothing answers here: a sentence, not a redirect
181 const owner = await fetch(`${base}/admin`, form(as("trevato", "admin"), { action: "tune-p", joint: "1", p: "24" }));
182 expect(owner.status).toBe(400);
183 expect(await owner.text()).toContain("did not answer");
184 });
Software/so101/src/admin-routes.ts +12 −1
@@ -18,6 +18,9 @@ export type AskVideo = () => readonly VideoCard[];
1818 /** Asks the arm for its servos' control registers; only called for the owner. */
1919 export type AskServos = () => Promise<ServoPanel | null>;
2020
21 /** Asks the arm server to run the P experiment; answers why not as a sentence, or null when it began. */
22 export type TuneP = (joint: number, p: number) => Promise<string | null>;
23
2124 /** What a POST needs once the caller is known to be allowed on the page. */
2225 export interface AdminSession {
2326 who: Person;
@@ -78,7 +81,7 @@ const REPORT_ACTIONS = new Set(["report-remove", "report-mute", "report-dismiss"
7881 type ReadBody = (req: IncomingMessage, limit?: number) => Promise<Buffer>;
7982
8083 /** The owner's page. Anyone else is told so; a change is a form post, answered with a redirect back. */
81 export async function handleAdmin(lobby: Lobby, req: IncomingMessage, res: ServerResponse, url: URL, readBody: ReadBody, askPrecision?: AskPrecision, askServos?: AskServos, askVideo?: AskVideo, versions?: () => Versions): Promise<void> {
84 export async function handleAdmin(lobby: Lobby, req: IncomingMessage, res: ServerResponse, url: URL, readBody: ReadBody, askPrecision?: AskPrecision, askServos?: AskServos, askVideo?: AskVideo, versions?: () => Versions, tune?: TuneP): Promise<void> {
8285 const session = await serveAdminPage(lobby, req, res, url, askPrecision, askServos, askVideo, versions);
8386 if (!session) return;
8487 const { who, canEdit, show } = session;
@@ -143,6 +146,14 @@ export async function handleAdmin(lobby: Lobby, req: IncomingMessage, res: Serve
143146 done = act === "report-remove" ? "reportRemoved" : act === "report-mute" ? "reportMuted" : "reportDismissed";
144147 break;
145148 }
149 case "tune-p": {
150 const [joint, p] = [form.get("joint") ?? "", form.get("p") ?? ""];
151 if (!/^\d{1,3}$/.test(joint) || !/^\d{1,3}$/.test(p)) throw new AdminError("give a joint and a whole number for P");
152 const refused = tune ? await tune(Number(joint), Number(p)) : "the arm is not reachable from here";
153 if (refused) throw new AdminError(refused);
154 done = "tuning";
155 break;
156 }
146157 default:
147158 throw new AdminError("no such action");
148159 }
Software/so101/src/precision-history.ts +24
@@ -7,6 +7,7 @@
77 import { Database } from "bun:sqlite";
88 import { existsSync, readFileSync } from "node:fs";
99 import { join } from "node:path";
10 import type { PExperiment } from "./tuning-run.ts";
1011 import { emptyRecords, summarize, trim, Tracker, WINDOW_MS, type Card, type Cause } from "./precision.ts";
1112
1213 /** The deployed commit: the forge's or CI's variable when set, else the checkout's HEAD, else "unknown". Never a shell. */
@@ -47,8 +48,15 @@ export interface Row {
4748 worstJoint: string | null;
4849 }
4950
51 /** One P experiment as kept: the run's own numbers, tagged with the commit that ran it. */
52 export interface TuningRow extends PExperiment {
53 commit: string;
54 }
55
5056 export interface Scorecard {
5157 commit: string;
58 /** The P experiments, newest first. */
59 tunings: TuningRow[];
5260 /** The session being driven now, or null. */
5361 session: Card | null;
5462 /** The last ten minutes, sessions pooled. */
@@ -67,6 +75,8 @@ export class PrecisionHistory {
6775 readonly #now: () => number;
6876 readonly #window = emptyRecords();
6977 #current: Tracker | null = null;
78 /** The card of the drive session that ended last: how a sweep reads its own numbers. */
79 last: Card | null = null;
7080
7181 constructor(options: { file?: string; commit?: string; now?: () => number } = {}) {
7282 this.commit = options.commit ?? deployedCommit();
@@ -76,6 +86,7 @@ export class PrecisionHistory {
7686 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,
7787 snap_backs INTEGER NOT NULL, releases INTEGER NOT NULL, latency_p95_ms REAL, worst_joint TEXT`;
7888 this.#db.run(`CREATE TABLE IF NOT EXISTS sessions (id INTEGER PRIMARY KEY, at TEXT NOT NULL, ${columns}, card TEXT NOT NULL)`);
89 this.#db.run("CREATE TABLE IF NOT EXISTS tunings (id INTEGER PRIMARY KEY, commit_id TEXT NOT NULL, result TEXT NOT NULL)");
7990 // An hour's roll-up keeps the worst of its sessions' p95s: one bad session in the hour is what the trend must show.
8091 this.#db.run(`CREATE TABLE IF NOT EXISTS hours (at TEXT NOT NULL, ${columns}, PRIMARY KEY (at, commit_id))`);
8192 }
@@ -107,6 +118,7 @@ export class PrecisionHistory {
107118 tracker.finish(at);
108119 if (this.#current === tracker) this.#current = null;
109120 const card = summarize(tracker.records);
121 this.last = card;
110122 const measured = card.joints.some((j) => j.errorTicks.n > 0) || card.snapBacks.total > 0;
111123 if (!measured) return card;
112124 const seconds = Number(((at - tracker.startedAt) / 1000).toFixed(1));
@@ -140,12 +152,24 @@ export class PrecisionHistory {
140152 return rows.reverse().map(fromStored);
141153 }
142154
155 /** Keep one finished P experiment. */
156 addTuning(result: PExperiment): void {
157 this.#db.query("INSERT INTO tunings (commit_id, result) VALUES (?, ?)").run(this.commit, JSON.stringify(result));
158 }
159
160 /** The kept experiments, newest first. */
161 tunings(limit = 20): TuningRow[] {
162 const rows = this.#db.query("SELECT commit_id, result FROM tunings ORDER BY id DESC LIMIT ?").all(limit) as Array<{ commit_id: string; result: string }>;
163 return rows.map((r) => ({ ...(JSON.parse(r.result) as PExperiment), commit: r.commit_id }));
164 }
165
143166 /** `hours`: how many hourly rows, newest kept (two weeks of them compare one week with the last). */
144167 scorecard(hours = 48): Scorecard {
145168 const now = this.#now();
146169 trim(this.#window, now - WINDOW_MS);
147170 return {
148171 commit: this.commit,
172 tunings: this.tunings(),
149173 session: this.#current ? summarize(this.#current.records) : null,
150174 window: summarize(this.#window, now - WINDOW_MS),
151175 sessions: this.rows("sessions"),
Software/so101/src/precision-panel.test.ts +11
@@ -117,3 +117,14 @@ describe("the Precision panel on /admin", () => {
117117 expect((await fetch(`${base}/precision`, { headers: owner })).status).toBe(502);
118118 });
119119 });
120
121 test("the P experiments are listed newest first as joint, P from→to, before→after and kept or put back", () => {
122 const run = (to: number, kept: boolean) => ({ joint: 2, from: 16, to, kept, before: { p95Error: 10, overshoot: 5 }, after: { p95Error: 8, overshoot: 4 }, commit: "abc1234", at: "2026-10-21T10:00:00.000Z" });
123 const panel = readPrecision({ commit: "abc", sessions: [], tunings: [run(24, true), run(16, false), { joint: "x" }] })!;
124 expect(panel.tunings).toHaveLength(2);
125 const html = precisionSection(panel, (s) => s.replace(/</g, "&lt;"));
126 expect(html).toContain("shoulder_lift (2) · P 16→24 · error 10→8, overshoot 5→4 · kept");
127 expect(html).toContain("P 16→16");
128 expect(html).toContain("put back");
129 expect(html.indexOf("→24")).toBeLessThan(html.indexOf("put back"));
130 });
Software/so101/src/precision-panel.ts +7 −2
@@ -4,6 +4,8 @@
44 * the stored sessions, oldest first, and the worst joint named. Plain text and characters; no script.
55 */
66
7 import { readTuningResult, tuningList, type TuningResult } from "./tuning-panel.ts";
8
79 const SPARK = "▁▂▃▄▅▆▇█";
810 const TREND = 24;
911
@@ -20,6 +22,8 @@ export interface PrecisionPanel {
2022 worstJoint: string | null;
2123 sessions: number;
2224 headline: Headline[];
25 /** The P experiments kept, newest first. */
26 tunings: TuningResult[];
2327 /** Each link hop with a measurement, as the window (else the last session) has it. */
2428 hops: Array<{ name: string; p50: number | null; p95: number | null }>;
2529 }
@@ -51,6 +55,7 @@ export function readPrecision(body: unknown): PrecisionPanel | null {
5155 commit: text(card.commit) ?? "unknown",
5256 worstJoint: text(window.worstJoint) ?? text(last.worstJoint),
5357 sessions: rows.length,
58 tunings: (Array.isArray(card.tunings) ? card.tunings : []).slice(0, 20).map(readTuningResult).filter((t): t is TuningResult => t !== null),
5459 headline: [
5560 { label: "Tracking error, p95", unit: "°", value: pick(window.trackingP95Deg, last.trackingP95Deg), trend: rows.map((r) => num(r.trackingP95Deg)) },
5661 { label: "Time to arrive, p95", unit: "ms", value: pick(window.arriveP95Ms, last.arriveP95Ms), trend: rows.map((r) => num(r.arriveP95Ms)) },
@@ -75,7 +80,7 @@ export function sparkline(values: ReadonlyArray<number | null>): string {
7580 export function precisionSection(p: PrecisionPanel | null | undefined, esc: (s: string) => string): string {
7681 const head = `<section aria-labelledby="precision"><h2 id="precision">Precision</h2>`;
7782 if (!p) return `${head}<p class="empty">The arm server did not answer <code>/precision</code>.</p></section>`;
78 if (!p.sessions && p.headline.every((h) => h.value === null)) return `${head}<p class="empty">Nothing measured yet: drive the arm and the numbers appear. Commit ${esc(p.commit)}.</p></section>`;
83 if (!p.sessions && !p.tunings.length && p.headline.every((h) => h.value === null)) return `${head}<p class="empty">Nothing measured yet: drive the arm and the numbers appear. Commit ${esc(p.commit)}.</p></section>`;
7984 const items = p.headline
8085 .map((h) => {
8186 const value = headlineValue(h);
@@ -83,7 +88,7 @@ export function precisionSection(p: PrecisionPanel | null | undefined, esc: (s:
8388 return `<li><span>${esc(h.label)}</span><span><b>${esc(value)}</b>${spark ? ` <span aria-hidden="true">${spark}</span>` : ""}</span></li>`;
8489 })
8590 .join("");
86 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>${hopList(p.hops, esc)}</section>`;
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>`;
8792 }
8893
8994 /** What is said where the hops would be, when none was timed: the simulation has no link to time. */
Software/so101/src/relay.ts +27 −5
@@ -75,8 +75,9 @@ import { CameraSocket } from "./camera-socket.ts";
7575 import { OFFLINE_FRAME } from "./offline-frame.ts";
7676 import { ServoBaseline } from "./servo-baseline.ts";
7777 import type { PiSync } from "./pi-deploy.ts";
78 import { handleAdmin, handleLift } from "./admin-routes.ts";
78 import { handleAdmin, handleLift, type TuneP } from "./admin-routes.ts";
7979 import { readPrecision } from "./precision-panel.ts";
80 import { readTuning } from "./tuning-panel.ts";
8081 import { readServos } from "./servo-panel.ts";
8182 import { parseFps, type FeedOptions } from "./camera-feed.ts";
8283 import { CameraError, CameraHub } from "./cameras.ts";
@@ -176,9 +177,9 @@ const PAGE = /^\/(?:index\.html)?$/;
176177 const STATIC = /^\/(?:index\.html)?$|^\/(?:model|vendor|ui)\//;
177178 const LEADER = "/leader/calibration";
178179 /** Admins only: clearing an emergency stop and changing the settings (the safety limits among them). */
179 const ADMIN_ONLY = new Set(["POST /estop/clear", "PUT /settings", "POST /settings/table-here", "POST /settings/table-touch", "POST /settings/joint-zero", "PUT /servo-params", "POST /servo-params/factory"]);
180 const ADMIN_ONLY = new Set(["POST /estop/clear", "PUT /settings", "POST /settings/table-here", "POST /settings/table-touch", "POST /settings/joint-zero", "PUT /servo-params", "POST /servo-params/factory", "POST /tuning/p"]);
180181 /** Routes only the owner may reach; anyone else is told there is no such page. */
181 const OWNER_READS = new Set(["GET /servo-params", "PUT /servo-params", "POST /servo-params/factory"]);
182 const OWNER_READS = new Set(["GET /servo-params", "PUT /servo-params", "POST /servo-params/factory", "GET /tuning", "POST /tuning/p"]);
182183 /** The driver's, and any admin's at any time. */
183184 const ADMIN_TOO = new Set(["POST /stop", "POST /resume", "POST /estop"]);
184185 /** What still goes to the arm server while the link is reconnecting: stopping it. */
@@ -487,11 +488,32 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
487488 }
488489 return json(res, 200, options.piSync?.versions() ?? null);
489490 };
491 /** The arm's P experiment state for the admin page; null when it does not answer in time. */
492 const askTuning = async () => {
493 try {
494 const answer = await fetch(`${remote && onArm() ? remote.http : simulation}/tuning`, { cache: "no-store", signal: AbortSignal.timeout(Math.min(readTimeoutMs, 1000)) });
495 return readTuning(answer.status, await answer.json().catch(() => null));
496 } catch {
497 return null;
498 }
499 };
500 /** The admin page's "Try this P": the arm server runs it, and says why not in a sentence. */
501 const tuneP: TuneP = async (joint, p) => {
502 try {
503 const answer = await fetch(`${remote && onArm() ? remote.http : simulation}/tuning/p`, { method: "POST", body: JSON.stringify({ joint, p }), signal: AbortSignal.timeout(Math.min(readTimeoutMs, 3000)) });
504 if (answer.status === 202) return null;
505 const body = (await answer.json().catch(() => null)) as { error?: unknown } | null;
506 return typeof body?.error === "string" ? body.error.replace(/[\p{Cc}\p{Cf}]/gu, "").slice(0, 200) : `the arm server answered ${answer.status}`;
507 } catch (err) {
508 return `the arm server did not answer (${reason(err)})`;
509 }
510 };
490511 /** The arm's servo registers for the owner's admin page; null when the arm does not answer in time. */
491512 const askServos = async () => {
492513 try {
493514 const answer = await fetch(`${remote && onArm() ? remote.http : simulation}/servo-params`, { cache: "no-store", signal: AbortSignal.timeout(Math.min(readTimeoutMs, 3000)) });
494 return readServos(answer.status, await answer.json().catch(() => null));
515 const panel = readServos(answer.status, await answer.json().catch(() => null));
516 return { ...panel, tuning: await askTuning() }; // a sweep holds the arm, so /servo-params says 409 while the progress is the news
495517 } catch {
496518 return null;
497519 }
@@ -716,7 +738,7 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
716738 const cameraAdmin = ADMIN_CAMERA.exec(url.pathname);
717739 if (cameraAdmin) return await administer(req, res, cameraAdmin[1] === undefined ? null : Number(cameraAdmin[1]));
718740 if (lobby && url.pathname === "/admin/lift") return await handleLift(lobby, req, res, readBody);
719 if (lobby && (url.pathname === "/admin" || url.pathname === "/admin/health")) return await handleAdmin(lobby, req, res, url, readBody, askPrecision, askServos, videoCards, options.piSync ? () => options.piSync!.versions() : undefined);
741 if (lobby && (url.pathname === "/admin" || url.pathname === "/admin/health")) return await handleAdmin(lobby, req, res, url, readBody, askPrecision, askServos, videoCards, options.piSync ? () => options.piSync!.versions() : undefined, tuneP);
720742 if (url.pathname === "/admin/versions") return versionsRead(req, res);
721743 if (url.pathname === "/precision") return await precisionRead(req, res, url);
722744 if (url.pathname === LEADER) return await leaderCalibration(req, res);
Software/so101/src/server.ts +60 −1
@@ -40,6 +40,9 @@
4040 * GET /precision the precision scorecard (src/precision.ts): tracking error, time to arrive, snap-backs by cause,
4141 * latency by hop, for the session being driven, the last 10 minutes, and the stored sessions and hours;
4242 * ?hours=1-720 hourly rows (48 by default)
43 * POST /tuning/p {"joint": id, "p": 1-64} run the P experiment (src/tuning-run.ts) on that joint while nobody drives: sweep, write, sweep, keep or put back; 202 at once,
44 * 409 while a run is under way or anything drives, 423 on E-stop or hold; the result joins GET /precision's tunings
45 * GET /tuning the run's phase while one is under way, and the last outcome
4346 * POST /precision/snap-back {"cause": one of CAUSES, "sizeDeg"}: a snap-back only the page saw, counted beside the server's own (400 for any other cause)
4447 * GET /model.json the arm model: joints, the model's floor (floorZ) and the enforced table (tableZ), where the URDF is served
4548 * GET /leader-map.js the leader calibration mapping, for the browser (src/leader-map.js)
@@ -70,7 +73,7 @@ import { dirname, extname, join, resolve } from "node:path";
7073 import type { Duplex } from "node:stream";
7174 import { createHash, randomUUID } from "node:crypto";
7275 import { fileURLToPath } from "node:url";
73 import { ParamsError, factoryValues, readServoParams, recordFactory, validateWrite, writeServoParams } from "./servo-params.ts";
76 import { TUNABLE, ParamsError, factoryValues, readServoParams, recordFactory, validateWrite, writeServoParams } from "./servo-params.ts";
7477 import { WebSocketServer, type WebSocket } from "ws";
7578 import { browserModule } from "./browser-modules.ts";
7679 import { Clock, CommandGate, HELD_CLOSE, isRelease, sentAtOf } from "./command-gate.ts";
@@ -84,6 +87,9 @@ import { Metrics } from "./metrics.ts";
8487 import { wallMs } from "./clock.ts";
8588 import { ARRIVE_TICKS, LINK_HOPS, parseSnapBack, READ_BACK_HOP, RELAY_HOP, type Cause, type Tracker } from "./precision.ts";
8689 import { deployedCommit, PrecisionHistory } from "./precision-history.ts";
90 import { Tuning, TuningRefused } from "./tuning.ts";
91 import { sweepJoint } from "./tuning-sweep.ts";
92 import type { SweepResult, TuningDeps } from "./tuning-run.ts";
8793 import { MotionError, moveToPose, playTrajectory, recordTrajectory, STALL_SPAN_TICKS } from "./motion.ts";
8894 import { assertPoseName, parsePoseFile, serializePoseFile, type PoseFile } from "./poses.ts";
8995 import { MAX_ZERO_OFFSET_DEG, zeroOffsetDeg } from "./joint-zero.ts";
@@ -109,6 +115,10 @@ export interface ServerOptions {
109115 heartbeatMs?: number;
110116 /** The commit the precision history tags its rows with; found from the environment or the checkout when not given. */
111117 commit?: string;
118 /** How long each sweep target is held, ms (1500); tests shorten it. */
119 tuningHoldMs?: number;
120 /** Replaces the stream sweep of the P experiment; tests give it the numbers to decide on. */
121 tuningSweep?: (joint: number) => Promise<SweepResult>;
112122 /** Starting values for the safety settings, before what is stored (src/safety.ts). */
113123 safety?: Partial<SafetySettings>;
114124 /** Speed used to catch up with the first frame of a stream, ticks/s. */
@@ -330,6 +340,34 @@ export async function startServer(bus: FeetechBus, options: ServerOptions = {}):
330340 driver = null;
331341 current = null;
332342 };
343 const tuning = new Tuning();
344 /** The P experiment's hands: sweeps through the stream, reads and writes through the guarded servo-params path. */
345 const tuningDeps: TuningDeps = {
346 isIdle: () => !driver && !estop && !gate.held,
347 sweep: async (joint) =>
348 options.tuningSweep
349 ? options.tuningSweep(joint)
350 : sweepJoint(joint, { url: `http://127.0.0.1:${(http.address() as { port: number }).port}`, bounds: (id) => bounds().get(id), holdMs: options.tuningHoldMs ?? 1500, lastCard: () => precision.last, halted: () => (estop ? stopped(estop) : gate.held ? holding(gate.held) : null) }),
351 readParams: async (id) => ({ P: (await readServoParams(bus, [id]))[0]?.registers.P_Coefficient ?? NaN }),
352 writeParams: async (id, { P }) => {
353 // Taking the arm may have to wait for a stream that is still closing; the old P must get back even so.
354 for (let tries = 0; ; tries++) {
355 try {
356 claim("move");
357 break;
358 } catch (err) {
359 if (tries >= 25 || !(err instanceof HttpError) || err.status !== 409) throw err;
360 await new Promise((r) => setTimeout(r, 200));
361 }
362 }
363 try {
364 await writeServoParams(bus, id, { P_Coefficient: P });
365 machine.note("sent", "servo params tuning", { id, P });
366 } finally {
367 release();
368 }
369 },
370 };
333371 const describe = (d: Driver) => ({ stream: "a stream", move: "a move", play: "a playback", record: "a recording", park: "the park move" })[d];
334372
335373 // ------------------------------------------------------------------ the safety envelope (src/safety.ts)
@@ -821,6 +859,27 @@ export async function startServer(bus: FeetechBus, options: ServerOptions = {}):
821859 release();
822860 }
823861 }
862 case "GET /tuning":
863 return json(res, 200, tuning.state);
864 case "POST /tuning/p": {
865 const body = await readBody(req);
866 const { joint, p } = body;
867 if (typeof joint !== "number" || !ids.includes(joint)) throw new HttpError(400, `joint must be one of ${ids.join(", ")}`);
868 const { min, max } = TUNABLE.P;
869 if (typeof p !== "number" || !Number.isInteger(p) || p < min || p > max) throw new HttpError(400, `p must be a whole number from ${min} to ${max}`);
870 if (estop) throw new HttpError(423, stopped(estop));
871 if (gate.held) throw new HttpError(423, holding(gate.held));
872 try {
873 tuning.start({ joint, p }, tuningDeps, (result) => {
874 precision.addTuning(result);
875 machine.note("state", "tuning", { joint, from: result.from, to: result.to, kept: result.kept });
876 });
877 } catch (err) {
878 if (err instanceof TuningRefused) throw new HttpError(err.status, err.message);
879 throw err;
880 }
881 return json(res, 202, tuning.state);
882 }
824883 case "GET /poses":
825884 return json(res, 200, loadPoses());
826885 case "GET /recordings":
Software/so101/src/servo-panel.test.ts +13
@@ -75,3 +75,16 @@ test("while someone drives, the owner reads a sentence", async () => {
7575 const text = await (await fetch(`http://127.0.0.1:${relay.port}/admin`, { headers: as("trevato", "admin") })).text();
7676 expect(text).toContain("Someone is driving the arm");
7777 });
78
79 test("each joint has a Try this P field, and the run's progress or refusal shows as a sentence", () => {
80 const rows = [{ id: 2, joint: "shoulder_lift", registers: { P_Coefficient: 16 }, error: null }];
81 const esc = (s: string) => s.replace(/</g, "&lt;");
82 const idle = servosSection({ rows }, esc);
83 expect(idle).toContain('name="action" value="tune-p"');
84 expect(idle).toContain('name="joint" value="2"');
85 expect(idle).toContain("Try this P</button>");
86 const busy = servosSection({ notice: "Someone is driving", tuning: { running: { joint: 2, p: 24, phase: "second sweep with the new P" }, last: null } }, esc);
87 expect(busy).toContain("Trying P 24 on shoulder_lift (2): second sweep with the new P");
88 const stopped = servosSection({ rows, tuning: { running: null, last: { joint: 2, p: 24, error: "sweep stopped: STOP", result: null } } }, esc);
89 expect(stopped).toContain("stopped: sweep stopped: STOP");
90 });
Software/so101/src/servo-panel.ts +15 −4
@@ -4,6 +4,9 @@
44 * answer shows its error in its row; a 409 (someone is driving) or an unreachable arm is one sentence. No script.
55 */
66
7 import { TUNABLE } from "./servo-params.ts";
8 import { tuningSentence, type TuningView } from "./tuning-panel.ts";
9
710 export interface ServoRow {
811 id: number;
912 joint: string | null;
@@ -12,7 +15,7 @@ export interface ServoRow {
1215 }
1316
1417 /** Either the joints as read, or why there is nothing to show. */
15 export type ServoPanel = { rows: ServoRow[] } | { notice: string };
18 export type ServoPanel = ({ rows: ServoRow[] } | { notice: string }) & { tuning?: TuningView | null };
1619
1720 const MAX_ROWS = 32;
1821 const obj = (v: unknown): Record<string, unknown> => (typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : {});
@@ -38,12 +41,20 @@ export function readServos(status: number, body: unknown): ServoPanel {
3841 export function servosSection(p: ServoPanel | null | undefined, esc: (s: string) => string): string {
3942 const head = `<section aria-labelledby="servos"><h2 id="servos">Servos</h2>`;
4043 if (!p) return `${head}<p class="empty">The arm server did not answer <code>/servo-params</code>.</p></section>`;
41 if ("notice" in p) return `${head}<p class="empty">${esc(p.notice)}</p></section>`;
44 const said = tuningSentence(p.tuning);
45 const status = said ? `<p role="status"><b>${esc(said)}</b></p>` : "";
46 if ("notice" in p) return `${head}<p class="empty">${esc(p.notice)}</p>${status}</section>`;
4247 if (!p.rows.length) return `${head}<p class="empty">The arm server listed no servos.</p></section>`;
4348 const cols = [...new Set(p.rows.flatMap((r) => Object.keys(r.registers)))];
4449 const th = cols.map((c) => `<th scope="col">${esc(c.replaceAll("_", " "))}</th>`).join("");
4550 const body = p.rows
46 .map((r) => `<tr><th scope="row">${esc(r.joint ?? "?")} (${r.id})</th>${cols.map((c) => `<td>${c in r.registers ? r.registers[c] : "—"}</td>`).join("")}<td>${r.error ? `<b>${esc(r.error)}</b>` : ""}</td></tr>`)
51 .map((r) => `<tr><th scope="row">${esc(r.joint ?? "?")} (${r.id})</th>${cols.map((c) => `<td>${c in r.registers ? r.registers[c] : "—"}</td>`).join("")}<td>${r.error ? `<b>${esc(r.error)}</b>` : ""}</td><td>${tryForm(r.id, Boolean(p.tuning?.running))}</td></tr>`)
4752 .join("");
48 return `${head}<div class="scroll"><table aria-label="Servo control registers"><caption>Each joint's control registers, read just now; read-only.</caption><thead><tr><th scope="col">Joint</th>${th}<th scope="col">Error</th></tr></thead><tbody>${body}</tbody></table></div></section>`;
53 return `${head}<div class="scroll"><table aria-label="Servo control registers"><caption>Each joint's control registers, read just now.</caption><thead><tr><th scope="col">Joint</th>${th}<th scope="col">Error</th><th scope="col">Try this P</th></tr></thead><tbody>${body}</tbody></table></div>${status}<p class="empty">Try this P sweeps the joint, writes the P, sweeps again and keeps it only if the tracking error and the overshoot are no worse and one is better; otherwise the old P is written back. Nobody can drive meanwhile.</p></section>`;
54 }
55
56 /** The field and button for one joint: the owner's form posts to /admin, which asks the arm server to run it. */
57 function tryForm(id: number, busy: boolean): string {
58 const { min, max } = TUNABLE.P;
59 return `<form method="post" action="/admin" class="inline"><input type="hidden" name="action" value="tune-p"><input type="hidden" name="joint" value="${id}"><input name="p" type="number" inputmode="numeric" min="${min}" max="${max}" step="1" required aria-label="P to try on joint ${id}"> <button${busy ? " disabled" : ""}>Try this P</button></form>`;
4960 }
Software/so101/src/terminal.test.ts +30 −1
@@ -12,7 +12,7 @@ import { identify, sign } from "./identity.ts";
1212 import { Lobby } from "./lobby.ts";
1313 import { startRelay, type RunningRelay } from "./relay.ts";
1414 import { startServer, type RunningServer } from "./server.ts";
15 import { alignReader, cardReader, Door, servosLines, servosReader, emptyRoom, hear, precisionLines, liveUrl, machineEntry, machineLines, machineUrl, healthLines, plain, poster, reader, terminalHeaders, typed } from "./terminal.ts";
15 import { alignReader, cardReader, Door, tuningReader, servosLines, servosReader, emptyRoom, hear, precisionLines, liveUrl, machineEntry, machineLines, machineUrl, healthLines, plain, poster, reader, terminalHeaders, typed } from "./terminal.ts";
1616 import { jointRows } from "./ui/machine.js";
1717 import { Turns } from "./turns.ts";
1818
@@ -727,3 +727,32 @@ describe("the terminal's presence line", () => {
727727 expect(room.presence).toBe("12 here · 4 signed in · 8 watching");
728728 });
729729 });
730
731 describe("/tune", () => {
732 test("a joint by name or number and a P is a run; alone it asks for the state; anything else is usage", () => {
733 expect(typed(emptyRoom(), "/tune shoulder_pan 24")).toEqual({ tune: { joint: 1, p: 24 } });
734 expect(typed(emptyRoom(), "/tune 2 16")).toEqual({ tune: { joint: 2, p: 16 } });
735 expect(typed(emptyRoom(), "/tune")).toEqual({ tune: null });
736 for (const bad of ["/tune nope 5", "/tune 1", "/tune 1 x", "/tune 1 2 3"]) expect(typed(emptyRoom(), bad)).toEqual({ print: expect.stringContaining("usage: /tune") });
737 });
738
739 test("the owner starts a run and reads it; a guest is refused both ways", async () => {
740 const printed: string[] = [];
741 const asked: unknown[] = [];
742 const post = async (path: string, body?: unknown) => (asked.push([path, body]), { status: 202, error: null });
743 const view = { running: { joint: 1, p: 24, phase: "second sweep with the new P" }, last: null };
744 const door = new Door("ws://127.0.0.1:1/live", {}, (l) => printed.push(l), post as never, null, null, null, null, null, async () => ({ error: null, view }));
745 door.input("/tune shoulder_pan 24");
746 door.input("/tune");
747 await new Promise((r) => setTimeout(r, 20));
748 expect(asked).toEqual([["/tuning/p", { joint: 1, p: 24 }]]);
749 expect(printed[0]).toContain("trying P 24");
750 expect(printed[1]).toContain("second sweep with the new P");
751 const guest = await tuningReader({ PORT: "8102" }, (async () => Response.json({ error: "not found" }, { status: 404 })) as unknown as typeof fetch)();
752 expect(guest).toEqual({ error: "tuning is for the owner", view: null });
753 const refused: string[] = [];
754 new Door("ws://127.0.0.1:1/live", {}, (l) => refused.push(l), (async () => ({ status: 404, error: "not found" })) as never).input("/tune 1 24");
755 await new Promise((r) => setTimeout(r, 20));
756 expect(refused).toEqual(["error: not found"]);
757 });
758 });
Software/so101/src/terminal.ts +49 −4
@@ -37,6 +37,8 @@
3737 * /versions owner or moderator: the app's and the Pi's commits and the last sync (GET /admin/versions)
3838 * /precision owner or moderator: the precision scorecard /admin shows (GET /precision, src/precision-panel.ts)
3939 * /servos owner: each joint's servo control registers /admin shows (GET /servo-params, src/servo-panel.ts); 404 to anyone else
40 * /tune <joint> <P> owner: the P experiment /admin's Servos "Try this P" runs (POST /tuning/p): sweep, write, sweep, keep or put back; 404 to anyone else
41 * /tune owner: the run's progress and the last result (GET /tuning, src/tuning-panel.ts)
4042 * /machine [off] the Machine panel (/machine, src/machine-feed.ts): the joints, the link and the server as they are,
4143 * then every command in and out as it happens, in the page's own words (src/ui/machine.js); off stops it
4244 * /who /help /quit
@@ -48,6 +50,8 @@ import { REFERENCES, referenceLines, verdictLine } from "./joint-reference.ts";
4850 import { UNPRINTABLE } from "./chat.ts";
4951 import { ID, NAME, sign } from "./identity.ts";
5052 import { readServos, type ServoPanel } from "./servo-panel.ts";
53 import { readTuning, tuningSentence, type TuningView } from "./tuning-panel.ts";
54 import { JOINTS } from "./sts3215.ts";
5155 import { headlineValue, hopLines, NO_HOPS, readPrecision, sparkline, type PrecisionPanel } from "./precision-panel.ts";
5256 import { presenceText } from "./ui/lobby-panel.js";
5357 import { entryLine, jointRows, linkRows, stateRows } from "./ui/machine.js";
@@ -86,7 +90,7 @@ function appPort(env: Env): number {
8690 return port;
8791 }
8892
89 export type Path = "/stop" | "/resume" | "/settings/table-here" | "/settings/table-touch" | "/settings/joint-zero" | "/settings";
93 export type Path = "/stop" | "/resume" | "/settings/table-here" | "/settings/table-touch" | "/settings/joint-zero" | "/settings" | "/tuning/p";
9094 /** `tableOffsetMm` is the offset the server holds after a settings call, when it said. */
9195 export type Post = (path: Path, body?: Record<string, unknown>) => Promise<{ status: number; error: string | null; tableOffsetMm?: number; offsetDeg?: number; heightMm?: number; tiltDeg?: number; applied?: boolean }>;
9296
@@ -185,6 +189,25 @@ export function servosReader(env: Env, fetcher: typeof fetch = fetch): ReadServo
185189 };
186190 }
187191
192 /** What GET /tuning answered, read as the admin panel reads it; or why not (anyone but the owner is told there is no such route). */
193 export type Tuning = { error: string | null; view: TuningView | null };
194 export type ReadTuning = () => Promise<Tuning>;
195
196 /** GET the P experiment's state as /admin shows it, signed afresh; the server decides who may. */
197 export function tuningReader(env: Env, fetcher: typeof fetch = fetch): ReadTuning {
198 return async () => {
199 try {
200 const r = await fetcher(`${appUrl(env)}/tuning`, { headers: terminalHeaders(env), signal: AbortSignal.timeout(5000) });
201 const body = (await r.json().catch(() => null)) as { error?: unknown } | null;
202 if (r.status === 404) return { error: "tuning is for the owner", view: null };
203 const view = readTuning(r.status, body);
204 return view ? { error: null, view } : { error: plain(body?.error ?? `status ${r.status}`), view: null };
205 } catch (err) {
206 return { error: plain((err as Error).message), view: null };
207 }
208 };
209 }
210
188211 /** The commits and the last sync outcome, one line each; a mismatch is flagged. */
189212 export function versionLines(v: Record<string, unknown> | null): string[] {
190213 if (!v) return ["the Pi is not kept in step from here (no deploy key, or not production)"];
@@ -296,8 +319,9 @@ const said = (room: Room, m: unknown): string => {
296319 return from ? `${tag}${plain(from.name)}: ${plain(message?.text)}` : `· ${plain(message?.text)}`;
297320 };
298321
322 const TUNE_USAGE = "usage: /tune <joint, e.g. shoulder_pan or 1> <P, 1 to 64>, or /tune alone for the run so far";
299323 const ZERO_USAGE = "usage: /zero <joint, e.g. shoulder_pan> [degrees the model should read, default 0]";
300 export const HELP = "type to chat · /join /leave /ready /extend · /stop /resume (driver, owner) · /end [who] /table here|touch 1|2|3|<mm> /zero <joint> [deg] /align [joint] (owner) · /mute <who> /unmute <who> (owner, moderator) · /delete <who|#id> (owner, moderator) · /report <who|#id> · /reports /dismiss #<id> (owner, moderator) · /removed /restore #<id> /visitors (owner) · /health /precision /versions (owner, moderator) · /servos (owner) · /machine [off] · /who · /quit";
324 export const HELP = "type to chat · /join /leave /ready /extend · /stop /resume (driver, owner) · /end [who] /table here|touch 1|2|3|<mm> /zero <joint> [deg] /align [joint] (owner) · /mute <who> /unmute <who> (owner, moderator) · /delete <who|#id> (owner, moderator) · /report <who|#id> · /reports /dismiss #<id> (owner, moderator) · /removed /restore #<id> /visitors (owner) · /health /precision /versions (owner, moderator) · /servos /tune [<joint> <P>] (owner) · /machine [off] · /who · /quit";
301325
302326 /** The Machine feed's socket beside the lobby's: same app, same port. */
303327 export const machineUrl = (live: string): string => live.replace(/\/live$/, "/machine");
@@ -440,7 +464,7 @@ function target(room: Room, word: string): string | null {
440464 return ID.test(word) ? word : null;
441465 }
442466
443 export type Typed = { send: Frame } | { post: "/stop" | "/resume" } | { table: "here" | number | { touch: 1 | 2 | 3 } } | { zero: { joint: string; referenceDeg: number } } | { align: string | null } | { print: string } | { lines: string[] } | { machine: boolean } | { health: true } | { precision: true } | { servos: true } | { versions: true } | { quit: true } | null;
467 export type Typed = { send: Frame } | { post: "/stop" | "/resume" } | { table: "here" | number | { touch: 1 | 2 | 3 } } | { zero: { joint: string; referenceDeg: number } } | { align: string | null } | { print: string } | { lines: string[] } | { machine: boolean } | { health: true } | { precision: true } | { servos: true } | { tune: { joint: number; p: number } | null } | { versions: true } | { quit: true } | null;
444468
445469 /** What a typed line asks for. Validation the server repeats anyway; this only saves a round trip on a typo. */
446470 export function typed(room: Room, input: string): Typed {
@@ -457,6 +481,12 @@ export function typed(room: Room, input: string): Typed {
457481 if (!/^[a-z_]{1,24}$/.test(arg) || extra.length || !/^-?\d{1,3}(\.\d{1,3})?$/.test(deg)) return { print: ZERO_USAGE };
458482 return { zero: { joint: arg, referenceDeg: Number(deg) } };
459483 }
484 if (/^tune$/i.test(verb)) {
485 if (!arg) return { tune: null };
486 const joint = /^\d{1,3}$/.test(arg) ? Number(arg) : Object.entries(JOINTS).find(([, name]) => name === arg.toLowerCase())?.[0];
487 if (joint === undefined || rest.length !== 1 || !/^\d{1,3}$/.test(rest[0]!)) return { print: TUNE_USAGE };
488 return { tune: { joint: Number(joint), p: Number(rest[0]) } };
489 }
460490 const timed = /^mute$/i.test(verb) && rest.length === 1 && /^(10m|1h|24h|forever)$/i.test(rest[0]!);
461491 if (rest.length && !timed && /^unmute$/i.test(verb)) return { print: "usage: /unmute <name>" };
462492 const touching = /^table$/i.test(verb) && /^touch$/i.test(arg) && rest.length === 1;
@@ -553,12 +583,14 @@ export class Door {
553583 private readonly read: Read | null;
554584 private readonly readCard: ReadCard | null;
555585 private readonly readServos: ReadServos | null;
586 private readonly readTuning: ReadTuning | null;
556587 private readonly readVersions: ReadVersions | null;
557588 private readonly readAlign: ReadAlign | null;
558589
559590 /** `post` reaches the app's /stop and /resume, `read` its /admin/health, `readCard` its /precision; without them, the door says it cannot. */
560 constructor(url: string, headers: Record<string, string>, print: (line: string) => void, post: Post | null = null, read: Read | null = null, readCard: ReadCard | null = null, readServos: ReadServos | null = null, readVersions: ReadVersions | null = null, readAlign: ReadAlign | null = null) {
591 constructor(url: string, headers: Record<string, string>, print: (line: string) => void, post: Post | null = null, read: Read | null = null, readCard: ReadCard | null = null, readServos: ReadServos | null = null, readVersions: ReadVersions | null = null, readAlign: ReadAlign | null = null, readTuning: ReadTuning | null = null) {
561592 this.readAlign = readAlign;
593 this.readTuning = readTuning;
562594 this.readVersions = readVersions;
563595 this.read = read;
564596 this.readCard = readCard;
@@ -608,6 +640,7 @@ export class Door {
608640 else if ("health" in t) void this.health();
609641 else if ("precision" in t) void this.precision();
610642 else if ("servos" in t) void this.servos();
643 else if ("tune" in t) void this.tune(t.tune);
611644 else if ("versions" in t) void this.versions();
612645 else if ("machine" in t) this.watchMachine(t.machine);
613646 else this.send(t.send);
@@ -651,6 +684,18 @@ export class Door {
651684 for (const line of r.error || !r.panel ? [`error: ${r.error ?? "no servos"}`] : servosLines(r.panel)) this.print(line);
652685 }
653686
687 /** The server decides who may; with a joint and a P a run starts (a refusal is printed), else the run's state is. */
688 private async tune(run: { joint: number; p: number } | null): Promise<void> {
689 if (run) {
690 if (!this.post) return this.print("error: tuning is not available here");
691 const r = await this.post("/tuning/p", run);
692 return this.print(r.error ? `error: ${r.error}` : `trying P ${run.p} on ${JOINTS[run.joint] ?? run.joint}: /tune shows how it goes`);
693 }
694 if (!this.readTuning) return this.print("error: tuning is not available here");
695 const r = await this.readTuning();
696 this.print(r.error ? `error: ${r.error}` : plain(tuningSentence(r.view) ?? "no tuning run yet"));
697 }
698
654699 /** The server decides who may; a refusal is printed, success says the offset the server now holds. */
655700 private async table(what: "here" | number | { touch: 1 | 2 | 3 }): Promise<void> {
656701 if (!this.post) return this.print("error: the table is not available here");
Software/so101/src/tty.ts +2 −2
@@ -4,7 +4,7 @@
44 */
55
66 import { createInterface, type Interface } from "node:readline";
7 import { alignReader, cardReader, Door, HELP, liveUrl, poster, reader, servosReader, terminalHeaders, versionsReader } from "./terminal.ts";
7 import { alignReader, cardReader, Door, HELP, liveUrl, poster, reader, servosReader, terminalHeaders, tuningReader, versionsReader } from "./terminal.ts";
88
99 const env = process.env;
1010 const where = env.FORGE_APP_ENV === "preview" ? `preview of #${env.FORGE_APP_PULL ?? "?"}` : (env.FORGE_APP_ENV ?? "local");
@@ -17,7 +17,7 @@ const print = (line: string) => {
1717 rl?.prompt(true);
1818 };
1919
20 const door = new Door(liveUrl(env), terminalHeaders(env), print, poster(env), reader(env), cardReader(env), servosReader(env), versionsReader(env), alignReader(env));
20 const door = new Door(liveUrl(env), terminalHeaders(env), print, poster(env), reader(env), cardReader(env), servosReader(env), versionsReader(env), alignReader(env), tuningReader(env));
2121 print(`\x1b[1mSO-101 arm\x1b[0m · ${where} · ${HELP}`);
2222 try {
2323 await door.open(() => {
Software/so101/src/tuning-endpoint.test.ts added +100
@@ -0,0 +1,100 @@
1 import { afterEach, expect, test } from "bun:test";
2 import { mkdtempSync } from "node:fs";
3 import { tmpdir } from "node:os";
4 import { join } from "node:path";
5 import WebSocket from "ws";
6 import { FeetechBus } from "./bus.ts";
7 import { FakeBus } from "./fake-bus.ts";
8 import { startServer, type RunningServer } from "./server.ts";
9 import type { SweepResult } from "./tuning-run.ts";
10
11 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
12 const r = (p95Error: number, overshoot: number): SweepResult => ({ p95Error, overshoot, timeToArrive: 1 });
13 let server: RunningServer | undefined;
14 let fake: FakeBus;
15 let base = "";
16
17 async function boot(sweeps?: SweepResult[], hold = 60) {
18 fake = new FakeBus([1, 2]);
19 fake.servos.get(1)![21] = 16; // P_Coefficient
20 server = await startServer(new FeetechBus(fake), {
21 host: "127.0.0.1", port: 0, ids: [1, 2], posesFile: join(mkdtempSync(join(tmpdir(), "so101-tuning-")), "poses.json"), watchdogMs: 60, commit: "abc1234",
22 tuningHoldMs: hold,
23 ...(sweeps ? { tuningSweep: async () => sweeps.shift()! } : {}),
24 });
25 base = `http://127.0.0.1:${server.port}`;
26 }
27 afterEach(() => Promise.race([server?.close(), sleep(500)]));
28 const post = (body: unknown) => fetch(`${base}/tuning/p`, { method: "POST", body: JSON.stringify(body) });
29 const finished = async () => {
30 for (let i = 0; i < 200; i++) {
31 const s = (await (await fetch(`${base}/tuning`)).json()) as { running: unknown; last: any };
32 if (!s.running && s.last) return s.last;
33 await sleep(25);
34 }
35 throw new Error("the run did not finish");
36 };
37
38 test("a run that keeps leaves the new P, and the result is in the precision history tagged with the commit", async () => {
39 await boot([r(10, 5), r(8, 5)]);
40 expect((await post({ joint: 1, p: 24 })).status).toBe(202);
41 const last = await finished();
42 expect(last.result).toMatchObject({ joint: 1, from: 16, to: 24, kept: true });
43 expect(fake.servos.get(1)![21]).toBe(24);
44 const card = (await (await fetch(`${base}/precision`)).json()) as { tunings: Array<{ joint: number; kept: boolean; commit: string }> };
45 expect(card.tunings).toHaveLength(1);
46 expect(card.tunings[0]).toMatchObject({ joint: 1, kept: true, commit: "abc1234" });
47 });
48
49 test("a run that does not improve puts the old P back and is kept as such, newest first", async () => {
50 await boot([r(10, 5), r(12, 5), r(10, 5), r(8, 5)]);
51 await post({ joint: 1, p: 24 });
52 expect((await finished()).result.kept).toBe(false);
53 expect(fake.servos.get(1)![21]).toBe(16);
54 await post({ joint: 1, p: 20 });
55 for (let i = 0; i < 100 && ((await (await fetch(`${base}/precision`)).json()) as { tunings: unknown[] }).tunings.length < 2; i++) await sleep(25);
56 const card = (await (await fetch(`${base}/precision`)).json()) as { tunings: Array<{ to: number; kept: boolean }> };
57 expect(card.tunings.map((t) => [t.to, t.kept])).toEqual([[20, true], [16, false]]);
58 });
59
60 test("a second run while one is under way is a 409, and a bad body a 400", async () => {
61 await boot();
62 let release!: () => void;
63 const gate = new Promise<void>((resolve) => (release = resolve));
64 await server!.close();
65 fake = new FakeBus([1, 2]);
66 server = await startServer(new FeetechBus(fake), { host: "127.0.0.1", port: 0, ids: [1, 2], posesFile: join(mkdtempSync(join(tmpdir(), "so101-tuning-")), "poses.json"), tuningSweep: async () => (await gate, r(1, 1)) });
67 base = `http://127.0.0.1:${server.port}`;
68 expect((await post({ joint: 9, p: 24 })).status).toBe(400);
69 expect((await post({ joint: 1, p: 99 })).status).toBe(400);
70 expect((await post({ joint: 1, p: 24 })).status).toBe(202);
71 const second = await post({ joint: 2, p: 24 });
72 expect(second.status).toBe(409);
73 expect(((await second.json()) as { error: string }).error).toContain("already under way");
74 expect(((await (await fetch(`${base}/tuning`)).json()) as { running: { joint: number } }).running.joint).toBe(1);
75 release();
76 await finished();
77 });
78
79 test("a run is refused while someone drives, and nothing is written", async () => {
80 await boot([r(1, 1), r(1, 1)]);
81 const ws = new WebSocket(`ws://127.0.0.1:${server!.port}/follow`);
82 await new Promise((resolve) => ws.once("open", resolve));
83 ws.send(JSON.stringify({ 1: 2000 }));
84 await sleep(50);
85 const writes = fake.writes.length;
86 const res = await post({ joint: 1, p: 24 });
87 expect(res.status).toBe(409);
88 expect(((await res.json()) as { error: string }).error).toContain("driving");
89 expect(fake.writes.length).toBe(writes);
90 ws.close();
91 await sleep(100);
92 });
93
94 test("a real sweep through the stream ends with a result and the P that result says", async () => {
95 await boot(undefined, 120);
96 expect((await post({ joint: 1, p: 24 })).status).toBe(202);
97 const last = await finished();
98 if (last.error) throw new Error(last.error);
99 expect(fake.servos.get(1)![21]).toBe(last.result.kept ? 24 : 16);
100 }, 20000);
Software/so101/src/tuning-panel.ts added +75
@@ -0,0 +1,75 @@
1 /**
2 * The P experiment on /admin: the arm server's GET /tuning and the tunings in GET /precision read field by field, for
3 * they come over the network from another machine, and drawn as sentences. Plain text; no script.
4 */
5 import { JOINTS } from "./sts3215.ts";
6
7 export interface TuningResult {
8 joint: number;
9 from: number;
10 to: number;
11 kept: boolean;
12 /** p95 tracking error in degrees, or the arm's own unit; the sweep's number as measured. */
13 before: number;
14 after: number;
15 overshootBefore: number;
16 overshootAfter: number;
17 commit: string | null;
18 at: string | null;
19 }
20
21 export interface TuningView {
22 running: { joint: number; p: number; phase: string } | null;
23 last: { joint: number; p: number; error: string | null; result: TuningResult | null } | null;
24 }
25
26 const obj = (v: unknown): Record<string, unknown> => (typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : {});
27 const int = (v: unknown): number | null => (typeof v === "number" && Number.isInteger(v) && v >= 0 && v < 1000 ? v : null);
28 const num = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
29 const short = (v: unknown, max = 120): string => [...String(v).replace(/[\p{Cc}\p{Cf}]/gu, "")].slice(0, max).join("");
30
31 /** One experiment as /precision or /tuning gave it; null when it is not one. */
32 export function readTuningResult(v: unknown): TuningResult | null {
33 const r = obj(v), before = obj(r.before), after = obj(r.after);
34 const joint = int(r.joint), from = int(r.from), to = int(r.to);
35 const [b, a, ob, oa] = [num(before.p95Error), num(after.p95Error), num(before.overshoot), num(after.overshoot)];
36 if (joint === null || from === null || to === null || b === null || a === null || ob === null || oa === null || typeof r.kept !== "boolean") return null;
37 return { joint, from, to, kept: r.kept, before: b, after: a, overshootBefore: ob, overshootAfter: oa, commit: typeof r.commit === "string" ? short(r.commit, 12) : null, at: typeof r.at === "string" ? short(r.at, 24) : null };
38 }
39
40 /** The run state from GET /tuning; null when the arm did not answer with one. */
41 export function readTuning(status: number, body: unknown): TuningView | null {
42 if (status !== 200) return null;
43 const b = obj(body), running = obj(b.running), last = obj(b.last);
44 const run = int(running.joint) !== null && int(running.p) !== null ? { joint: int(running.joint)!, p: int(running.p)!, phase: short(running.phase, 80) } : null;
45 const lj = int(last.joint), lp = int(last.p);
46 const done = lj !== null && lp !== null ? { joint: lj, p: lp, error: typeof last.error === "string" ? short(last.error) : null, result: readTuningResult(last.result) } : null;
47 return { running: run, last: done };
48 }
49
50 const name = (joint: number) => JOINTS[joint] ?? `joint ${joint}`;
51 const label = (joint: number) => `${name(joint)} (${joint})`;
52
53 /** One experiment as a sentence's worth of facts: "shoulder_pan (1) P 16→24 · error 10→8 · kept". */
54 export function resultLine(r: TuningResult): string {
55 return `${label(r.joint)} · P ${r.from}→${r.to} · error ${r.before}→${r.after}, overshoot ${r.overshootBefore}→${r.overshootAfter} · ${r.kept ? "kept" : "put back"}`;
56 }
57
58 /** What is going on, or what just happened, as one sentence; null before any run. */
59 export function tuningSentence(t: TuningView | null | undefined): string | null {
60 if (!t) return null;
61 if (t.running) return `Trying P ${t.running.p} on ${label(t.running.joint)}: ${t.running.phase}. Reload to follow it; nobody can drive until it ends.`;
62 if (t.last?.error) return `The last try of P ${t.last.p} on ${label(t.last.joint)} stopped: ${t.last.error}. The old P is back.`;
63 if (t.last?.result) {
64 const r = t.last.result;
65 return `The last try of P ${t.last.p} on ${label(r.joint)} was ${r.kept ? "kept" : "put back"}: p95 error ${r.before}→${r.after}, overshoot ${r.overshootBefore}→${r.overshootAfter}.`;
66 }
67 return null;
68 }
69
70 /** The newest experiments, newest first, as the Precision panel lists them. */
71 export function tuningList(rows: readonly TuningResult[], esc: (s: string) => string): string {
72 if (!rows.length) return "";
73 const items = rows.map((r) => `<li><span>${esc(r.at ? r.at.slice(0, 16).replace("T", " ") : "")} · ${esc(r.commit ?? "unknown")}</span><span>${esc(resultLine(r))}</span></li>`).join("");
74 return `<h3>P experiments</h3><ol class="bars precision" aria-label="P experiments, newest first">${items}</ol>`;
75 }
Software/so101/src/tuning-sweep.ts added +57
@@ -0,0 +1,57 @@
1 /**
2 * One joint's test sweep, driven through the server's own /follow stream so the governor, the zones and the torque cap
3 * apply as they do to a person, and the stream's precision session measures it. The targets are bench/limits-sweep.ts's.
4 */
5 import WebSocket from "ws";
6 import type { Card } from "./precision.ts";
7 import type { SweepResult } from "./tuning-run.ts";
8
9 /** Ticks from the middle of the joint's bounds, each held for the hold time. */
10 export const OFFSETS = [0, 250, 0, -250, 0] as const;
11
12 /** The joint's targets: the offsets from the middle of its bounds, kept inside them. */
13 export function targets(lo: number, hi: number): number[] {
14 const mid = Math.round((lo + hi) / 2);
15 return OFFSETS.map((o) => Math.min(hi, Math.max(lo, mid + o)));
16 }
17
18 export interface SweepSource {
19 /** Where the stream is listening. */
20 url: string;
21 bounds(joint: number): { min: number; max: number } | undefined;
22 holdMs: number;
23 /** The card of the session that ended last, for the numbers. */
24 lastCard(): Card | null;
25 /** Why the sweep must stop now (an E-stop or a hold), or null. */
26 halted(): string | null;
27 }
28
29 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
30
31 /** Drive one joint through its targets and answer what the stream's session measured. Throws, naming why, if it is stopped. */
32 export async function sweepJoint(joint: number, source: SweepSource): Promise<SweepResult> {
33 const range = source.bounds(joint);
34 if (!range) throw new Error(`joint ${joint} has no bounds`);
35 const before = source.lastCard();
36 const ws = new WebSocket(`${source.url.replace(/^http/, "ws")}/follow`);
37 let closed: number | null = null;
38 ws.on("close", (code) => (closed = code));
39 await new Promise((resolve, reject) => (ws.once("open", resolve), ws.once("error", reject), ws.once("close", (c) => reject(new Error(`the stream was refused (${c})`)))));
40 try {
41 for (const t of targets(range.min, range.max)) {
42 ws.send(JSON.stringify({ [joint]: t }));
43 await sleep(source.holdMs);
44 const why = source.halted() ?? (closed !== null ? `the stream closed (${closed})` : null);
45 if (why) throw new Error(`sweep stopped: ${why}`);
46 }
47 } finally {
48 ws.close(1000);
49 await new Promise((r) => (ws.readyState === WebSocket.CLOSED ? r(null) : ws.once("close", r)));
50 }
51 for (let waited = 0; source.lastCard() === before && waited < 3000; waited += 25) await sleep(25); // the server closes the session after the socket
52 const card = source.lastCard();
53 const j = card === before ? undefined : card?.joints.find((x) => x.id === joint);
54 if (!j || j.errorDeg.p95 === null) throw new Error("the sweep measured nothing");
55 if (card!.snapBacks.total) throw new Error("sweep stopped: the arm refused or held back a target");
56 return { p95Error: j.errorDeg.p95, overshoot: j.overshootTicks.max ?? 0, timeToArrive: j.arriveMs.p95 ?? 0 };
57 }
Software/so101/src/tuning.ts added +57
@@ -0,0 +1,57 @@
1 /** The one P experiment that may run at a time on the arm server, its progress, and the last outcome. */
2 import { runPExperiment, type PExperiment, type TuningDeps } from "./tuning-run.ts";
3
4 export interface TuningState {
5 running: { joint: number; p: number; phase: string } | null;
6 /** The last run's result, or why it stopped; null before any. */
7 last: { joint: number; p: number; result: PExperiment } | { joint: number; p: number; error: string } | null;
8 }
9
10 /** A refusal the server answers with `status`. */
11 export class TuningRefused extends Error {
12 readonly status: number;
13 constructor(status: number, message: string) {
14 super(message);
15 this.status = status;
16 }
17 }
18
19 export class Tuning {
20 #state: TuningState = { running: null, last: null };
21
22 get state(): TuningState {
23 return structuredClone(this.#state);
24 }
25
26 /**
27 * Start the run in the background; a second while one is under way is a 409, as is one with someone driving.
28 * `done` is told each finished experiment.
29 */
30 start(request: { joint: number; p: number }, deps: TuningDeps, done: (result: PExperiment) => void): void {
31 if (this.#state.running) throw new TuningRefused(409, "a tuning run is already under way");
32 if (!deps.isIdle()) throw new TuningRefused(409, "someone is driving the arm; try again when nobody has a turn");
33 const running = { ...request, phase: "reading the joint" };
34 this.#state.running = running;
35 let sweeps = 0;
36 const watched: TuningDeps = {
37 ...deps,
38 sweep: async (joint) => {
39 running.phase = sweeps++ ? "second sweep with the new P" : "first sweep with the current P";
40 return deps.sweep(joint);
41 },
42 writeParams: async (id, values) => {
43 running.phase = `writing P ${values.P}`;
44 return deps.writeParams(id, values);
45 },
46 };
47 runPExperiment(request, watched).then(
48 (result) => {
49 this.#state.last = { ...request, result };
50 done(result);
51 },
52 (err) => {
53 this.#state.last = { ...request, error: err instanceof Error ? err.message : String(err) };
54 },
55 ).finally(() => (this.#state.running = null));
56 }
57 }

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs