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

Migrated from github.com/Trevato/SO-ARM100

workbenchthis machine

The story page: an engaging write-up of the arm for anyone, with the Hugging Face SO-101 docs and the public repo #567

Merged opened this in answer to

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

Merged

vesper/arm:vesper/565-the-story-page-an-engaging-write-up-of-t → main 2 commits fork

  • Merged. vesper/565-the-story-page-an-engaging-write-up-of-t was merged into main as aef8f48.

Review

Sign in to review this change.
9 files changed +662 −0
README.md +1
@@ -4,6 +4,7 @@
44
55 - **Watch:** open the link. You don't need an account. You see the camera, the arm's live 3D model and the chat.
66 - **Drive:** in the Queue tab, choose "Have a forge account? Sign in instead" and sign in with your forge account (or join under a name you pick), then press Join. When your turn comes, the Controls tab appears. One person drives at a time. Turns last a few minutes and end early if the arm sits idle.
7 - **Story:** [the story of the arm](https://arm--forge-trevato-apps.open-platform.sh/story) ([`docs/story.md`](docs/story.md)): how it works, how to build your own with the [LeRobot SO-101 docs](https://huggingface.co/docs/lerobot/so101), and what the crew measured.
78 - **Code:** this forge repository is the app's home. The app lives in [`Software/so101`](Software/so101), and [`Software/README.md`](Software/README.md) explains how to run it on your own arm.
89
910 github.com/Trevato/SO-ARM100 is deprecated: issues, pulls and new work go here. The upstream hardware project is [TheRobotStudio/SO-ARM100](https://github.com/TheRobotStudio/SO-ARM100); its README follows.
Software/so101/README.md +9
@@ -2,6 +2,15 @@
22
33 `bench/fake-serve.ts` is the hosted app (the page, the room, the relay); `so101 serve` is the arm server on the Pi.
44
5 ## The story page: /story
6
7 `/story` on the hosted app is the arm explained for anyone: the hook, how it works (with a diagram of browser → forge → Pi → servos, and what latency, the queue, STOP and the safety zone mean), how to build your own (the [LeRobot SO-101 docs](https://huggingface.co/docs/lerobot/so101), this repository, `bun so101 setup`) and what the crew built. Anyone may read it; it is linked from the Chat tab's footer (hidden while you drive) and the Queue tab.
8
9 - **The text is `docs/story.md`** at the repository's root; edit it there and the page follows (it is read once per process). `src/story-markdown.ts` renders the small Markdown it uses, escaping every character; a link goes out only to `https:` or a path on this site. A ```` ```flow ```` fence is the diagram, one `Name: what it does` a line.
10 - **Two slots** the page fills: `<!-- camera -->` is the overhead camera live (the listed camera named Above or Overhead, else the first; `/camera/<id>/stream?fps=5`), or a line saying it is not connected; `<!-- numbers -->` is the last seven days from `facts.sqlite`: driving turns, snap-backs per 100 releases and p95 time to arrive (worked out at most once a minute), or a line saying nobody has driven yet.
11 - **Previews:** Open Graph and Twitter tags name `/story/arm.webp`, the repository's own photo of an SO-101 follower (`media/SO101_Follower.webp`, 2048×1536, served as it is and cached a day), with absolute URLs built from the request's host when it is a plain host name.
12 - **No script.** The style is inline and pinned by its hash in a `default-src 'none'` Content-Security-Policy that otherwise allows only this site's images; the security floor's headers stay on.
13
514 ## The Pi's own health
615
716 `GET /health/pi` on the arm server answers `{ tempC, underVoltage, underVoltageSince, throttled, at }`, read from `/sys/class/thermal/thermal_zone0/temp` and `/sys/devices/platform/soc/soc:firmware/get_throttled` (src/pi-health.ts; never a shell). `underVoltage` is bit 0x1 (now), `underVoltageSince` bit 0x10000 (since boot), `throttled` any of 0x2, 0x4, 0x8 (now). Anything the files do not give is `null`, so off a Pi it is 200 with nulls. The hosted app passes the route to the arm, so it shows once the Pi runs this commit.
Software/so101/src/relay.ts +11
@@ -50,6 +50,7 @@
5050 * WS /camera/<id>/ws the same feed as whole binary frames (JPEG; the offline PNG when its source is down), latest frame wins
5151 * GET /data?from&to&step[&compare=1], ?turn=<id> the facts as series, for the owner and moderators (403 to anyone else)
5252 * GET /admin/data the Data view: the facts drawn, for the owner and moderators (404 to anyone else)
53 * GET /story, /story/arm.webp the story of the arm for anyone, docs/story.md with the camera and the week's scorecard; its preview photo (src/story.ts)
5354 * GET /admin/camera-list the owner's page for the camera list
5455 * POST /admin/cameras {"name", "source"}, DELETE /admin/cameras/<id> the owner changes the list; viewers see it within seconds
5556 * GET|PUT|DELETE /leader/calibration the signed-in person's own leader calibration (src/leader-map.js), any time,
@@ -82,6 +83,7 @@ import { ServoBaseline } from "./servo-baseline.ts";
8283 import type { PiSync } from "./pi-deploy.ts";
8384 import { serveData } from "./data-api.ts";
8485 import { serveDataPage } from "./data-page.ts";
86 import { serveStory, weekNumbers, type StoryNumbers } from "./story.ts";
8587 import { handleAdmin, handleLift, type TuneP } from "./admin-routes.ts";
8688 import { readPrecision } from "./precision-panel.ts";
8789 import { readTuning } from "./tuning-panel.ts";
@@ -759,6 +761,14 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
759761 return json(res, 200, { resumed: gate.resume(), held: null });
760762 };
761763
764 /** The story's scorecard: the last seven days from the facts, worked out at most once a minute. */
765 let story: { at: number; numbers: StoryNumbers | null } | null = null;
766 const storyNumbers = (): StoryNumbers | null => {
767 const now = Date.now();
768 if (!story || now - story.at > 60_000) story = { at: now, numbers: facts ? weekNumbers(facts, now) : null };
769 return story.numbers;
770 };
771
762772 const http = createServer(async (req, res) => {
763773 for (const [name, value] of Object.entries(FLOOR)) res.setHeader(name, value);
764774 try {
@@ -775,6 +785,7 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
775785 if (cameraAdmin) return await administer(req, res, cameraAdmin[1] === undefined ? null : Number(cameraAdmin[1]));
776786 if (lobby && url.pathname === "/admin/lift") return await handleLift(lobby, req, res, readBody);
777787 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);
788 if (serveStory(req, res, url.pathname, { cameras: () => cameras.list(), numbers: storyNumbers })) return;
778789 if (url.pathname === "/admin/versions") return versionsRead(req, res);
779790 if (lobby && url.pathname === "/admin/data") return serveDataPage(lobby, req, res);
780791 if (url.pathname === "/data") return serveData(facts ?? undefined, lobby ?? undefined, req, res, url);
Software/so101/src/story-markdown.test.ts added +42
@@ -0,0 +1,42 @@
1 import { expect, test } from "bun:test";
2 import { inline, renderMarkdown, safeHref, slug } from "./story-markdown.ts";
3
4 test("blocks: headings with ids, paragraphs joined, lists, quotes and code", () => {
5 const html = renderMarkdown("# Title\n\nOne\ntwo.\n\n## How it works\n\n- a\n- b\n more\n\n1. x\n2. y\n\n> said\n\n```\n<b>raw</b>\n```");
6 expect(html.split("\n")).toEqual([
7 "<h1>Title</h1>",
8 "<p>One two.</p>",
9 '<h2 id="how-it-works">How it works</h2>',
10 "<ul><li>a</li><li>b more</li></ul>",
11 "<ol><li>x</li><li>y</li></ol>",
12 "<blockquote><p>said</p></blockquote>",
13 "<pre><code>&lt;b&gt;raw&lt;/b&gt;</code></pre>",
14 ]);
15 });
16
17 test("inline: code, bold, emphasis and links, everything else escaped", () => {
18 expect(inline("a `<x>` **b** *c* [d](https://e.example/f?g=1&h=2)")).toBe('a <code>&lt;x&gt;</code> <strong>b</strong> <em>c</em> <a href="https://e.example/f?g=1&amp;h=2" rel="noopener">d</a>');
19 expect(inline("[here](/story#build)")).toBe('<a href="/story#build">here</a>');
20 expect(inline(`<script>alert("x")</script> & 'q'`)).toBe("&lt;script&gt;alert(&quot;x&quot;)&lt;/script&gt; &amp; &#39;q&#39;");
21 });
22
23 test("a link goes only to https or a path on this site; anything else is plain text", () => {
24 for (const bad of ["javascript:alert`1`", "http://a.example", "//evil.example", "data:text/html,x", "mailto:a@b", "./x"]) {
25 expect(safeHref(bad)).toBe(false);
26 expect(inline(`[t](${bad})`)).toBe("t");
27 }
28 expect(safeHref("https://huggingface.co/docs/lerobot/so101")).toBe(true);
29 expect(safeHref("/")).toBe(true);
30 });
31
32 test("slots are filled by name, unknown ones vanish; a flow fence is the diagram", () => {
33 const html = renderMarkdown("<!-- camera -->\n\n<!-- nope -->\n\n```flow\nYou: press *go*\nThe arm\n```", { camera: () => "<img>" });
34 expect(html).toBe('<img>\n\n<figure class="flow"><ol><li><b>You</b><span>press <em>go</em></span></li><li><b>The arm</b><span></span></li></ol></figure>');
35 // a slot's name must be plain, and a comment in a paragraph is just text
36 expect(renderMarkdown("a <!-- camera -->", { camera: () => "X" })).toBe("<p>a &lt;!-- camera --&gt;</p>");
37 });
38
39 test("slugs are lower-case words joined with dashes", () => {
40 expect(slug("What the crew built")).toBe("what-the-crew-built");
41 expect(slug(" Build your own! ")).toBe("build-your-own");
42 });
Software/so101/src/story-markdown.ts added +117
@@ -0,0 +1,117 @@
1 /**
2 * The little Markdown docs/story.md is written in, to HTML, so the repository's story and the page's are one text.
3 * Blocks: # to ### headings, paragraphs, - lists, 1. lists, > quotes, ``` fences, and a slot, a line `<!-- name -->`
4 * that the page fills (the camera, the numbers). A fence whose info is `flow` is the diagram: one step a line,
5 * `Name: what it does`. Inline: `code`, **bold**, *emphasis*, [text](url). Every character of the source is escaped;
6 * a link goes out only to https: or to a path on this site, anything else stays plain text.
7 */
8
9 export const esc = (s: string): string => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
10
11 /** A link the page may carry: https anywhere, or a path here ("/…" but not "//…", which is another host). */
12 export const safeHref = (url: string): boolean => /^https:\/\/[^\s"'<>]+$/.test(url) || /^\/(?!\/)[^\s"'<>]*$/.test(url);
13
14 /** Fills a slot by name; an unknown name renders as nothing. */
15 export type Slots = Record<string, () => string>;
16
17 /** The ids a heading gets: its words, lower case, joined with dashes. */
18 export const slug = (text: string): string =>
19 text
20 .toLowerCase()
21 .replace(/[^a-z0-9]+/g, "-")
22 .replace(/^-|-$/g, "");
23
24 export function inline(text: string): string {
25 const out: string[] = [];
26 const pattern = /`([^`]+)`|\*\*([^*]+)\*\*|\*([^*]+)\*|\[([^\]]+)\]\(([^)\s]+)\)/g;
27 let last = 0;
28 for (const m of text.matchAll(pattern)) {
29 out.push(esc(text.slice(last, m.index)));
30 if (m[1] !== undefined) out.push(`<code>${esc(m[1])}</code>`);
31 else if (m[2] !== undefined) out.push(`<strong>${inline(m[2])}</strong>`);
32 else if (m[3] !== undefined) out.push(`<em>${inline(m[3])}</em>`);
33 else if (safeHref(m[5]!)) out.push(`<a href="${esc(m[5]!)}"${m[5]!.startsWith("https:") ? ' rel="noopener"' : ""}>${inline(m[4]!)}</a>`);
34 else out.push(inline(m[4]!));
35 last = m.index + m[0].length;
36 }
37 out.push(esc(text.slice(last)));
38 return out.join("");
39 }
40
41 function flow(lines: string[]): string {
42 const steps = lines
43 .filter((l) => l.trim())
44 .map((l) => {
45 const at = l.indexOf(":");
46 const [name, what] = at < 0 ? [l, ""] : [l.slice(0, at), l.slice(at + 1)];
47 return `<li><b>${inline(name.trim())}</b><span>${inline(what.trim())}</span></li>`;
48 });
49 return `<figure class="flow"><ol>${steps.join("")}</ol></figure>`;
50 }
51
52 export function renderMarkdown(source: string, slots: Slots = {}): string {
53 const lines = source.replace(/\r\n?/g, "\n").split("\n");
54 const html: string[] = [];
55 let para: string[] = [];
56 let list: { tag: "ul" | "ol"; items: string[] } | null = null;
57 let quote: string[] = [];
58 const flush = () => {
59 if (para.length) html.push(`<p>${inline(para.join(" "))}</p>`);
60 if (list) html.push(`<${list.tag}>${list.items.map((i) => `<li>${inline(i)}</li>`).join("")}</${list.tag}>`);
61 if (quote.length) html.push(`<blockquote><p>${inline(quote.join(" "))}</p></blockquote>`);
62 para = [];
63 list = null;
64 quote = [];
65 };
66 for (let i = 0; i < lines.length; i++) {
67 const line = lines[i]!;
68 const fence = /^```\s*([a-z]*)\s*$/.exec(line);
69 if (fence) {
70 flush();
71 const body: string[] = [];
72 while (++i < lines.length && !/^```\s*$/.test(lines[i]!)) body.push(lines[i]!);
73 html.push(fence[1] === "flow" ? flow(body) : `<pre><code>${esc(body.join("\n"))}</code></pre>`);
74 continue;
75 }
76 const slot = /^<!--\s*([a-z][a-z-]*)\s*-->$/.exec(line.trim());
77 if (slot) {
78 flush();
79 html.push(slots[slot[1]!]?.() ?? "");
80 continue;
81 }
82 const heading = /^(#{1,3})\s+(.+)$/.exec(line);
83 if (heading) {
84 flush();
85 const n = heading[1]!.length;
86 const text = heading[2]!.trim();
87 html.push(n === 1 ? `<h1>${inline(text)}</h1>` : `<h${n} id="${slug(text)}">${inline(text)}</h${n}>`);
88 continue;
89 }
90 const item = /^\s*(?:([-*])|(\d+)\.)\s+(.+)$/.exec(line);
91 if (item) {
92 const tag = item[1] ? "ul" : "ol";
93 if (para.length || quote.length || (list && list.tag !== tag)) flush();
94 list ??= { tag, items: [] };
95 list.items.push(item[3]!);
96 continue;
97 }
98 const q = /^>\s?(.*)$/.exec(line);
99 if (q) {
100 if (para.length || list) flush();
101 quote.push(q[1]!);
102 continue;
103 }
104 if (!line.trim()) {
105 flush();
106 continue;
107 }
108 if (list && /^\s+\S/.test(line)) {
109 list.items[list.items.length - 1] += ` ${line.trim()}`;
110 continue;
111 }
112 if (list || quote.length) flush();
113 para.push(line.trim());
114 }
115 flush();
116 return html.join("\n");
117 }
Software/so101/src/story.test.ts added +200
@@ -0,0 +1,200 @@
1 import { afterEach, expect, test } from "bun:test";
2 import { createHash } from "node:crypto";
3 import { readFileSync } from "node:fs";
4 import type { IncomingMessage } from "node:http";
5 import { CameraHub } from "./cameras.ts";
6 import { Facts } from "./facts.ts";
7 import { startRelay, type RunningRelay } from "./relay.ts";
8 import { HF_DOCS, PHOTO_HEIGHT, PHOTO_WIDTH, REPO, STORY_FILE, STORY_PHOTO, STORY_STYLE, originOf, pickCamera, renderStory, weekNumbers } from "./story.ts";
9 import type { Snapshot } from "./turns.ts";
10
11 const STORY = readFileSync(STORY_FILE, "utf8");
12 const sha = (text: string) => createHash("sha256").update(text).digest("base64");
13 const hrefs = (page: string) => [...page.matchAll(/href="([^"]*)"/g)].map((m) => m[1]!.replace(/&amp;/g, "&"));
14
15 let relay: RunningRelay | undefined;
16 let hub: CameraHub | undefined;
17 afterEach(async () => {
18 await relay?.close();
19 hub?.close();
20 relay = hub = undefined;
21 });
22
23 async function boot(facts?: Facts, cameras: string[] = ["Desk", "Above"]) {
24 hub = new CameraHub({ seed: cameras.map((name, i) => ({ name, source: `http://127.0.0.1:1/cam${i}/stream` })) });
25 relay = await startRelay({ port: 0, simulation: "http://127.0.0.1:1", cameras: hub, facts });
26 return `http://127.0.0.1:${relay.port}`;
27 }
28
29 test("docs/story.md has the hook, the four parts, both links and the one command, in plain words", () => {
30 expect(STORY).toMatch(/^# .*robot arm.*anyone/im);
31 expect(STORY).toContain("Wisconsin");
32 for (const part of ["## How it works", "## Build your own", "## What the crew built"]) expect(STORY).toContain(part);
33 for (const word of ["**Latency**", "**The queue**", "**STOP**", "**The safety zone**", "Snap-backs per 100 releases", "Time to arrive"]) expect(STORY).toContain(word);
34 expect(STORY).toContain(`(${HF_DOCS})`);
35 expect(STORY).toContain(`(${REPO})`);
36 expect(STORY).toContain("`bun so101 setup`");
37 expect(STORY).toContain("<!-- camera -->");
38 expect(STORY).toContain("<!-- numbers -->");
39 expect(STORY).toMatch(/```flow\nYour browser:[^\n]*\nThe forge:[^\n]*\nThe shop's Raspberry Pi:[^\n]*\nSix servos:/);
40 // short paragraphs: none runs past about five lines on a phone
41 for (const para of STORY.split(/\n\n+|\n(?=- )/)) if (!para.startsWith("```")) expect([para.slice(0, 40), para.length < 560]).toEqual([para.slice(0, 40), true]);
42 });
43
44 test("the page: the story with the live overhead camera, the diagram in four steps, and this week's numbers", () => {
45 const page = renderStory({ markdown: STORY, origin: "https://arm.example", camera: { id: 2, name: "Above" }, numbers: { sessions: 12, snapBacksPer100: 3.4, arriveP95Ms: 1240 } });
46 expect(page).toContain("<h1>A robot arm anyone on the internet can drive</h1>");
47 expect(page).toContain('<img src="/camera/2/stream?fps=5" width="640" height="360" alt=');
48 const flow = /<figure class="flow"><ol>([\s\S]*?)<\/ol><\/figure>/.exec(page)![1]!;
49 expect([...flow.matchAll(/<b>([^<]*)<\/b>/g)].map((m) => m[1])).toEqual(["Your browser", "The forge", "The shop&#39;s Raspberry Pi", "Six servos"]);
50 expect(page).toContain("<dt>Driving turns</dt><dd>12</dd>");
51 expect(page).toContain("<dt>Snap-backs per 100 releases</dt><dd>3.4</dd>");
52 expect(page).toContain("<dt>Time to arrive, p95</dt><dd>1.2 s</dd>");
53 expect(page).toContain('<h2 id="build-your-own">');
54 expect(page).toContain("<code>bun so101 setup</code>");
55 expect(page).not.toContain("<!--");
56 expect(page).not.toMatch(/<script/);
57 // it fits a phone: the viewport is set and nothing is wider than the column but the figures
58 expect(page).toContain('name="viewport" content="width=device-width, initial-scale=1');
59 });
60
61 test("with no camera and no driving yet, the page says so instead of showing nothing", () => {
62 const page = renderStory({ markdown: STORY, origin: null, camera: null, numbers: { sessions: 0, snapBacksPer100: null, arriveP95Ms: null } });
63 expect(page).not.toContain("<img");
64 expect(page).toContain("The camera is not connected right now");
65 expect(page).toContain("Nobody has yet");
66 const measured = renderStory({ markdown: STORY, origin: null, camera: null, numbers: { sessions: 2, snapBacksPer100: null, arriveP95Ms: null } });
67 expect(measured.match(/not yet measured/g)).toHaveLength(2);
68 });
69
70 test("the Open Graph tags give a large preview: title, description, the arm's photo by absolute URL with its size, and the page's URL", () => {
71 const page = renderStory({ markdown: STORY, origin: "https://arm--forge-trevato-apps.open-platform.sh", camera: null, numbers: null });
72 const meta = (key: string) => new RegExp(`<meta (?:property|name)="${key}" content="([^"]*)">`).exec(page)?.[1];
73 expect(meta("og:title")).toBe("A robot arm anyone on the internet can drive");
74 expect(meta("og:description")!.length).toBeGreaterThan(60);
75 expect(meta("og:description")!.length).toBeLessThan(200);
76 expect(meta("og:type")).toBe("article");
77 expect(meta("og:url")).toBe("https://arm--forge-trevato-apps.open-platform.sh/story");
78 expect(meta("og:image")).toBe("https://arm--forge-trevato-apps.open-platform.sh/story/arm.webp");
79 expect(meta("og:image:width")).toBe("2048");
80 expect(meta("og:image:height")).toBe("1536");
81 expect(meta("og:image:type")).toBe("image/webp");
82 expect(meta("twitter:card")).toBe("summary_large_image");
83 expect(meta("description")).toBe(meta("og:description"));
84 });
85
86 test("the origin comes only from a plain host; anything else and the tags fall back to paths", () => {
87 const req = (headers: Record<string, string>) => ({ headers }) as unknown as IncomingMessage;
88 expect(originOf(req({ host: "arm.example", "x-forwarded-proto": "https" }))).toBe("https://arm.example");
89 expect(originOf(req({ host: "arm.example" }))).toBe("https://arm.example");
90 expect(originOf(req({ host: "127.0.0.1:8102" }))).toBe("http://127.0.0.1:8102");
91 expect(originOf(req({ host: "a.example", "x-forwarded-host": "arm.example, evil" }))).toBe("https://arm.example");
92 for (const host of ['x"><script>', "a b", "", "evil.example/path", "-bad.example"]) expect(originOf(req({ host }))).toBeNull();
93 const page = renderStory({ markdown: STORY, origin: null, camera: null, numbers: null });
94 expect(page).toContain('<meta property="og:image" content="/story/arm.webp">');
95 });
96
97 test("the overhead camera is the one named Above or Overhead, else the first", () => {
98 expect(pickCamera([{ id: 1, name: "Camera 1" }, { id: 2, name: "Above" }])).toEqual({ id: 2, name: "Above" });
99 expect(pickCamera([{ id: 4, name: "Overhead cam" }, { id: 5, name: "x" }])!.id).toBe(4);
100 expect(pickCamera([{ id: 7, name: "Wrist" }])!.id).toBe(7);
101 expect(pickCamera([])).toBeNull();
102 });
103
104 test("the preview photo is the repository's own SO-101 picture, a WebP of the size the tags say", () => {
105 const photo = readFileSync(STORY_PHOTO);
106 expect(photo.subarray(0, 4).toString()).toBe("RIFF");
107 expect(photo.subarray(8, 16).toString()).toBe("WEBPVP8 ");
108 // a lossy VP8 frame header: 14-bit width and height after the start code
109 expect(photo.readUInt16LE(26) & 0x3fff).toBe(PHOTO_WIDTH);
110 expect(photo.readUInt16LE(28) & 0x3fff).toBe(PHOTO_HEIGHT);
111 expect(photo.length).toBeLessThan(300 * 1024); // previews fetch it at once
112 });
113
114 test("the week's numbers come from the kept turns: sessions, snap-backs per 100 releases, p95 arrive", () => {
115 let t = Date.now() - 3600_000;
116 const facts = new Facts({ commit: "c", now: () => t });
117 const snap = { now: 0, turnMs: 0, idleMs: 0, paused: false, maxQueue: 9, driver: null, queue: [] } as unknown as Snapshot;
118 const who = { id: "a-1", name: "ann", owner: false };
119 expect(weekNumbers(facts, t)).toEqual({ sessions: 0, snapBacksPer100: null, arriveP95Ms: null });
120 facts.turn({ kind: "turn", ended: null, started: who } as never, snap);
121 t += 60_000;
122 const id = facts.turn({ kind: "turn", ended: { who, reason: "done" }, started: null } as never, snap)!;
123 facts.card(id, { releases: 50, snapBacks: { jam: 2 }, jams: 2, arriveP95Ms: 900 });
124 expect(weekNumbers(facts, t + 1)).toEqual({ sessions: 1, snapBacksPer100: 4, arriveP95Ms: 900 });
125 // a turn over a week old is not this week's
126 expect(weekNumbers(facts, t + 8 * 86_400_000).sessions).toBe(0);
127 facts.close();
128 });
129
130 test("GET /story on the hosted app: anyone, no script, the security floor, and every link on it resolves", async () => {
131 const base = await boot();
132 const res = await fetch(`${base}/story`);
133 expect(res.status).toBe(200);
134 expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
135 expect(res.headers.get("x-content-type-options")).toBe("nosniff");
136 expect(res.headers.get("referrer-policy")).toBe("same-origin");
137 const csp = res.headers.get("content-security-policy")!;
138 expect(csp).toStartWith("default-src 'none';");
139 expect(csp).toContain(`style-src 'sha256-${sha(STORY_STYLE)}'`);
140 expect(csp).toContain("img-src 'self'");
141 expect(csp).not.toContain("script-src");
142 const page = await res.text();
143 expect(/<style>([\s\S]*?)<\/style>/.exec(page)![1]).toBe(STORY_STYLE);
144 expect(page).toContain(`content="http://127.0.0.1:${relay!.port}/story/arm.webp"`);
145 expect(page).toContain('src="/camera/2/stream?fps=5"'); // the one named Above
146 expect(page).toContain("The live scorecard shows here once people have driven");
147
148 const links = new Set(hrefs(page));
149 expect(links).toContain(HF_DOCS);
150 expect(links).toContain(REPO);
151 expect(links).toContain("https://arm--forge-trevato-apps.open-platform.sh");
152 for (const link of links) {
153 if (link.startsWith("https:")) {
154 expect(() => new URL(link)).not.toThrow();
155 continue;
156 }
157 const path = link.replace(base, "").split("#")[0]!;
158 if (path === "/") continue; // the viewer itself, from the simulation, which this test does not run
159 const answer = await fetch(base + path);
160 expect([link, answer.status]).toEqual([link, 200]);
161 await answer.arrayBuffer();
162 }
163 // every in-page anchor names a heading on it
164 for (const link of links) if (link.includes("#")) expect(page).toContain(`id="${link.split("#")[1]}"`);
165
166 const head = await fetch(`${base}/story`, { method: "HEAD" });
167 expect(head.status).toBe(200);
168 expect(await head.text()).toBe("");
169 const post = await fetch(`${base}/story`, { method: "POST", headers: { origin: base } });
170 expect(post.status).toBe(405);
171 });
172
173 test("GET /story/arm.webp serves the photo, cacheable; the page shows the scorecard once turns are kept", async () => {
174 const facts = new Facts({ commit: "c" });
175 const snap = { now: 0, turnMs: 0, idleMs: 0, paused: false, maxQueue: 9, driver: null, queue: [] } as unknown as Snapshot;
176 const who = { id: "a-1", name: "ann", owner: false };
177 facts.turn({ kind: "turn", ended: null, started: who } as never, snap);
178 facts.card(facts.turn({ kind: "turn", ended: { who, reason: "done" }, started: null } as never, snap)!, { releases: 20, snapBacks: {}, jams: 0, arriveP95Ms: 750 });
179 const base = await boot(facts, []);
180 const photo = await fetch(`${base}/story/arm.webp`);
181 expect(photo.status).toBe(200);
182 expect(photo.headers.get("content-type")).toBe("image/webp");
183 expect(photo.headers.get("cache-control")).toContain("max-age=86400");
184 expect(Buffer.from(await photo.arrayBuffer()).equals(readFileSync(STORY_PHOTO))).toBe(true);
185 const page = await (await fetch(`${base}/story`)).text();
186 expect(page).toContain("<dt>Driving turns</dt><dd>1</dd>");
187 expect(page).toContain("<dt>Snap-backs per 100 releases</dt><dd>0</dd>");
188 expect(page).toContain("<dt>Time to arrive, p95</dt><dd>0.8 s</dd>");
189 expect(page).toContain("The camera is not connected right now");
190 facts.close();
191 });
192
193 test("the arm's page links the story from the Chat tab's footer and the Queue tab, and the footer gives way while driving", () => {
194 const viewer = readFileSync(new URL("./viewer.html", import.meta.url), "utf8");
195 const chat = viewer.slice(viewer.indexOf('<div class="tab" id="tab-chat"'), viewer.indexOf('<div class="tab" id="tab-queue"'));
196 const queue = viewer.slice(viewer.indexOf('<div class="tab" id="tab-queue"'), viewer.indexOf('<div class="tab" id="tab-controls"'));
197 expect(chat).toMatch(/<footer id="storyLink"><a href="\/story">/);
198 expect(queue).toContain('<a href="/story">');
199 expect(viewer).toContain("#shell.driving #storyLink { display: none; }");
200 });
Software/so101/src/story.ts added +221
@@ -0,0 +1,221 @@
1 /**
2 * The story, /story: what the arm is, how it works, how to build one, and what the crew measured, for anyone. The text
3 * is docs/story.md (src/story-markdown.ts renders it); the page fills its two slots, the overhead camera live and the
4 * last seven days' scorecard from the kept facts. No script at all: the style is inline, pinned by its hash in a
5 * Content-Security-Policy that allows nothing else but this site's images. /story/arm.webp is its preview picture,
6 * the repository's own photo of an SO-101 follower, named in the Open Graph tags so a pasted link previews in Discord,
7 * iMessage and the like.
8 */
9
10 import { createHash } from "node:crypto";
11 import { readFileSync } from "node:fs";
12 import type { IncomingMessage, ServerResponse } from "node:http";
13 import { aggregate } from "./data-series.ts";
14 import type { Facts } from "./facts.ts";
15 import { esc, renderMarkdown } from "./story-markdown.ts";
16
17 export const STORY_FILE = new URL("../../../docs/story.md", import.meta.url);
18 /** The preview picture: media/SO101_Follower.webp, 2048×1536, as it is in the repository. */
19 export const STORY_PHOTO = new URL("../../../media/SO101_Follower.webp", import.meta.url);
20 export const PHOTO_WIDTH = 2048;
21 export const PHOTO_HEIGHT = 1536;
22 export const STORY_TITLE = "A robot arm anyone on the internet can drive";
23 export const STORY_DESCRIPTION = "A real robot arm in a Wisconsin shop, live on the web: how it works, how to build your own SO-101, and what an AI crew measured while making it better.";
24 export const HF_DOCS = "https://huggingface.co/docs/lerobot/so101";
25 export const REPO = "https://forge.open-platform.sh/trevato/arm";
26 const WEEK = 7 * 86_400_000;
27
28 export interface StoryCamera {
29 id: number;
30 name: string;
31 }
32 /** The last seven days' scorecard; null where nothing was measured. */
33 export interface StoryNumbers {
34 sessions: number;
35 snapBacksPer100: number | null;
36 arriveP95Ms: number | null;
37 }
38 export interface StoryView {
39 markdown: string;
40 /** "https://host" when the request's host is a plain host name, else null (the tags then use paths). */
41 origin: string | null;
42 camera: StoryCamera | null;
43 numbers: StoryNumbers | null;
44 }
45
46 export const STORY_STYLE = `
47 :root { color-scheme: dark light; --bg: #0b0d10; --panel: #11161d; --fg: #e8eaed; --dim: #9aa4ae; --line: #2a313a; --accent: #f0883e; --link: #79b8ff; }
48 @media (prefers-color-scheme: light) { :root { --bg: #fbfaf7; --panel: #fff; --fg: #1f2328; --dim: #59636e; --line: #d8dee4; --accent: #bc4c00; --link: #0969da; } }
49 * { box-sizing: border-box; }
50 body { margin: 0; background: var(--bg); color: var(--fg); font: 18px/1.65 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; -webkit-text-size-adjust: 100%; }
51 .top, main, footer { max-width: 40rem; margin: 0 auto; padding-left: max(1.1rem, env(safe-area-inset-left)); padding-right: max(1.1rem, env(safe-area-inset-right)); }
52 .top { display: flex; justify-content: space-between; align-items: center; gap: 1rem; padding-top: max(.8rem, env(safe-area-inset-top)); font-size: .9rem; }
53 .top a { min-height: 44px; display: inline-flex; align-items: center; }
54 a { color: var(--link); text-underline-offset: .15em; }
55 a:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 2px; }
56 .go { display: inline-flex; align-items: center; min-height: 44px; padding: 0 1rem; border-radius: 999px; background: var(--accent); color: #fff; font-weight: 650; text-decoration: none; }
57 h1 { font-size: clamp(2rem, 7vw, 2.9rem); line-height: 1.1; letter-spacing: -.02em; margin: 1.2rem 0 1rem; text-wrap: balance; }
58 h2 { font-size: 1.45rem; line-height: 1.25; margin: 2.6rem 0 .6rem; }
59 p, ul, ol, blockquote { margin: 0 0 1rem; }
60 ul, ol { padding-left: 1.3rem; }
61 li { margin: 0 0 .55rem; }
62 strong { font-weight: 650; }
63 code { font: .88em ui-monospace, SFMono-Regular, Menlo, monospace; background: var(--panel); border: 1px solid var(--line); border-radius: 5px; padding: .05em .3em; white-space: nowrap; }
64 pre { overflow-x: auto; background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: .8rem; }
65 pre code { border: 0; padding: 0; white-space: pre; }
66 figure { margin: 1.4rem 0; }
67 .live img { display: block; width: 100%; height: auto; aspect-ratio: 16 / 9; object-fit: cover; background: var(--panel); border-radius: 12px; border: 1px solid var(--line); }
68 figcaption { color: var(--dim); font-size: .85rem; margin-top: .45rem; }
69 .flow ol { list-style: none; padding: 0; margin: 0; display: grid; gap: 1.6rem; counter-reset: step; }
70 .flow li { position: relative; margin: 0; background: var(--panel); border: 1px solid var(--line); border-radius: 12px; padding: .75rem .9rem; display: grid; gap: .2rem; }
71 .flow li b { font-size: 1rem; }
72 .flow li span { color: var(--dim); font-size: .88rem; line-height: 1.45; }
73 .flow li + li::before { content: "↓"; position: absolute; top: -1.55rem; left: 50%; transform: translateX(-50%); color: var(--accent); font-weight: 700; line-height: 1.5rem; }
74 @media (min-width: 760px) {
75 .flow { margin-left: calc(50% - 50vw + 1.5rem); margin-right: calc(50% - 50vw + 1.5rem); max-width: 64rem; }
76 .flow ol { grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 1.5rem; }
77 .flow li + li::before { content: "→"; top: 50%; left: -1.25rem; transform: translateY(-50%); }
78 }
79 @media (min-width: 1100px) { .flow { margin-left: -12rem; margin-right: -12rem; } }
80 .numbers { background: var(--panel); border: 1px solid var(--line); border-radius: 12px; padding: .9rem 1rem; margin: 0 0 1.2rem; }
81 .numbers p { margin: 0; color: var(--dim); font-size: .85rem; }
82 .numbers dl { display: grid; grid-template-columns: repeat(auto-fit, minmax(9rem, 1fr)); gap: .8rem; margin: .6rem 0 0; }
83 .numbers dt { color: var(--dim); font-size: .8rem; line-height: 1.3; }
84 .numbers dd { margin: .15rem 0 0; font-size: 1.7rem; font-weight: 650; font-variant-numeric: tabular-nums; line-height: 1.2; }
85 footer { border-top: 1px solid var(--line); margin-top: 3rem; padding-top: 1rem; padding-bottom: max(2rem, env(safe-area-inset-bottom)); color: var(--dim); font-size: .9rem; display: flex; flex-wrap: wrap; gap: .2rem 1.2rem; }
86 footer a { min-height: 44px; display: inline-flex; align-items: center; }
87 `;
88
89 const sha = (text: string) => createHash("sha256").update(text).digest("base64");
90 export const storyCsp = (): string => `default-src 'none'; style-src 'sha256-${sha(STORY_STYLE)}'; img-src 'self'; form-action 'none'; frame-ancestors 'none'; base-uri 'none'`;
91
92 /** The camera the story shows: the one looking down (named Above or Overhead), else the first listed. */
93 export function pickCamera(list: readonly StoryCamera[]): StoryCamera | null {
94 return list.find((c) => /\b(above|overhead|top)\b/i.test(c.name)) ?? list[0] ?? null;
95 }
96
97 /** The page's own origin, for the absolute URLs the preview tags need; only a plain host[:port] is believed. */
98 export function originOf(req: IncomingMessage): string | null {
99 const host = String(req.headers["x-forwarded-host"] ?? req.headers.host ?? "").split(",")[0]!.trim().toLowerCase();
100 if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*(:\d{1,5})?$/.test(host)) return null;
101 const proto = String(req.headers["x-forwarded-proto"] ?? "").split(",")[0]!.trim();
102 const local = /^(localhost|127\.0\.0\.1)(:\d+)?$/.test(host);
103 return `${proto === "http" || (local && proto !== "https") ? "http" : "https"}://${host}`;
104 }
105
106 /** The last seven days of driving, from the facts the Data view reads (src/data-series.ts). */
107 export function weekNumbers(facts: Facts, now = Date.now()): StoryNumbers {
108 const from = now - WEEK;
109 const { overview } = aggregate({ from, to: now, step: 86_400, now, oldest: facts.oldest(), turns: facts.turns(from, now), events: [], samples: [] });
110 return { sessions: overview.sessions, snapBacksPer100: overview.snapBacksPer100, arriveP95Ms: overview.arriveP95Ms };
111 }
112
113 const seconds = (ms: number) => `${(ms / 1000).toFixed(ms < 10_000 ? 1 : 0)} s`;
114
115 function cameraSlot(camera: StoryCamera | null): string {
116 if (!camera) return `<figure class="live"><figcaption>The camera is not connected right now. <a href="/">Watch the arm's page</a> to see it when it is.</figcaption></figure>`;
117 return `<figure class="live"><img src="/camera/${camera.id}/stream?fps=5" width="640" height="360" alt="The arm on its bench, live from the camera above it"><figcaption>Live from the camera above the bench, right now. Anything moving is someone driving.</figcaption></figure>`;
118 }
119
120 function numbersSlot(numbers: StoryNumbers | null): string {
121 if (!numbers || numbers.sessions === 0) return `<section class="numbers" aria-label="The scorecard"><p>The live scorecard shows here once people have driven this week. Nobody has yet: <a href="/">you could be first</a>.</p></section>`;
122 const cell = (label: string, value: string) => `<div><dt>${label}</dt><dd>${value}</dd></div>`;
123 return `<section class="numbers" aria-label="The scorecard"><p>The last 7 days, live from the arm</p><dl>${[
124 cell("Driving turns", String(numbers.sessions)),
125 cell("Snap-backs per 100 releases", numbers.snapBacksPer100 === null ? "not yet measured" : String(numbers.snapBacksPer100)),
126 cell("Time to arrive, p95", numbers.arriveP95Ms === null ? "not yet measured" : seconds(numbers.arriveP95Ms)),
127 ].join("")}</dl></section>`;
128 }
129
130 export function renderStory(view: StoryView): string {
131 const body = renderMarkdown(view.markdown, { camera: () => cameraSlot(view.camera), numbers: () => numbersSlot(view.numbers) });
132 const at = (path: string) => esc((view.origin ?? "") + path);
133 return `<!doctype html>
134 <html lang="en">
135 <head>
136 <meta charset="utf-8">
137 <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
138 <meta name="referrer" content="same-origin">
139 <title>${esc(STORY_TITLE)}</title>
140 <meta name="description" content="${esc(STORY_DESCRIPTION)}">
141 <meta name="theme-color" content="#0b0d10">
142 <link rel="canonical" href="${at("/story")}">
143 <meta property="og:type" content="article">
144 <meta property="og:site_name" content="The arm">
145 <meta property="og:title" content="${esc(STORY_TITLE)}">
146 <meta property="og:description" content="${esc(STORY_DESCRIPTION)}">
147 <meta property="og:url" content="${at("/story")}">
148 <meta property="og:image" content="${at("/story/arm.webp")}">
149 <meta property="og:image:type" content="image/webp">
150 <meta property="og:image:width" content="${PHOTO_WIDTH}">
151 <meta property="og:image:height" content="${PHOTO_HEIGHT}">
152 <meta property="og:image:alt" content="An SO-101 robot arm: black 3D-printed links, six servos and a gripper, on a white table">
153 <meta name="twitter:card" content="summary_large_image">
154 <style>${STORY_STYLE}</style>
155 </head>
156 <body>
157 <nav class="top" aria-label="Site"><a href="/">← The arm, live</a><a class="go" href="/">Drive it</a></nav>
158 <main>
159 <article>
160 ${body}
161 </article>
162 </main>
163 <footer><a href="/">Drive the arm</a><a href="${esc(HF_DOCS)}" rel="noopener">LeRobot SO-101 docs</a><a href="${esc(REPO)}" rel="noopener">The code, public</a></footer>
164 </body>
165 </html>
166 `;
167 }
168
169 export interface StorySource {
170 cameras: () => readonly StoryCamera[];
171 numbers: () => StoryNumbers | null;
172 /** The story's Markdown; docs/story.md by default. */
173 markdown?: () => string;
174 }
175
176 let kept: string | null = null;
177 const readStory = (): string => (kept ??= readFileSync(STORY_FILE, "utf8"));
178 let photoKept: Buffer | null = null;
179 const readPhoto = (): Buffer => (photoKept ??= readFileSync(STORY_PHOTO));
180
181 /** GET or HEAD /story and /story/arm.webp; true when it answered. */
182 export function serveStory(req: IncomingMessage, res: ServerResponse, path: string, source: StorySource): boolean {
183 if (path !== "/story" && path !== "/story/arm.webp") return false;
184 if (req.method !== "GET" && req.method !== "HEAD") {
185 res.writeHead(405, { "content-type": "application/json", "cache-control": "no-store", allow: "GET, HEAD" });
186 res.end(JSON.stringify({ error: "GET" }));
187 return true;
188 }
189 const head = req.method === "HEAD";
190 if (path === "/story/arm.webp") {
191 let photo: Buffer;
192 try {
193 photo = readPhoto();
194 } catch {
195 res.writeHead(404, { "content-type": "application/json", "cache-control": "no-store" });
196 res.end(JSON.stringify({ error: "the photo is not on this machine" }));
197 return true;
198 }
199 res.writeHead(200, { "content-type": "image/webp", "content-length": photo.length, "cache-control": "public, max-age=86400" });
200 res.end(head ? undefined : photo);
201 return true;
202 }
203 let markdown: string;
204 try {
205 markdown = (source.markdown ?? readStory)();
206 } catch {
207 res.writeHead(404, { "content-type": "application/json", "cache-control": "no-store" });
208 res.end(JSON.stringify({ error: "the story is not on this machine" }));
209 return true;
210 }
211 let numbers: StoryNumbers | null = null;
212 try {
213 numbers = source.numbers();
214 } catch (err) {
215 console.error(`story numbers: ${(err as Error).message}`);
216 }
217 const html = renderStory({ markdown, origin: originOf(req), camera: pickCamera(source.cameras()), numbers });
218 res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "public, max-age=60", "content-security-policy": storyCsp() });
219 res.end(head ? undefined : html);
220 return true;
221 }
Software/so101/src/viewer.html +3
@@ -176,6 +176,7 @@
176176 #say { display: flex; gap: 8px; padding: 8px calc(12px + var(--safe-r)) 8px calc(12px + var(--safe-l)); border-top: 1px solid var(--line); }
177177 #say input { flex: 1; min-width: 0; }
178178 #sayNote { color: var(--dim); font-size: 13px; padding: 10px calc(12px + var(--safe-r)) 10px calc(12px + var(--safe-l)); border-top: 1px solid var(--line); } #sayNote:empty { display: none; }
179 #storyLink { font-size: 13px; padding: 4px calc(12px + var(--safe-r)) 6px calc(12px + var(--safe-l)); border-top: 1px solid var(--line); } #storyLink a { display: inline-flex; align-items: center; min-height: 32px; color: var(--dim); } #shell.driving #storyLink { display: none; }
179180
180181 /* queue */
181182 #queue { list-style: none; margin: 0; padding: 0; display: grid; gap: 4px; }
@@ -330,6 +331,7 @@
330331 <button type="button" id="newMsgs" hidden>New messages ↓</button>
331332 <form id="say" hidden><input id="sayText" type="text" maxlength="500" autocomplete="off" enterkeyhint="send" placeholder="Say something" aria-label="Message"><button class="go">Send</button></form>
332333 <div id="sayNote"></div>
334 <footer id="storyLink"><a href="/story">How this arm works, and how to build your own</a></footer>
333335 </div>
334336 <div class="tab" id="tab-queue" role="tabpanel" aria-labelledby="t-queue" hidden>
335337 <h2>Driving</h2>
@@ -341,6 +343,7 @@
341343 <h2>Waiting</h2>
342344 <ol id="queue" aria-label="Queue"></ol>
343345 <p class="note">A turn lasts a few minutes and ends early when the arm sits idle. When yours comes, the Controls tab appears.</p>
346 <p class="note">New here? <a href="/story">Read the story of this arm</a>: how it works, what keeps it safe, and how to build your own.</p>
344347 <h2>Leader arm</h2>
345348 <div class="row"><button id="leaderBtn" title="read a leader arm plugged into this computer or phone (Chrome, Edge)">Connect leader arm</button><label class="switch" id="teleopRow" hidden title="on your turn, the arm follows the leader live"><input type="checkbox" role="switch" id="teleop"> Teleop</label><button id="leaderCal" hidden title="teach this page your own leader arm: once, kept with your name">Calibrate leader</button></div>
346349 <p class="lag" id="teleopLag" hidden></p>
docs/story.md added +58
@@ -0,0 +1,58 @@
1 # A robot arm anyone on the internet can drive
2
3 In a workshop in Wisconsin, a small robot arm sits on a bench under a camera. It has six motors, a gripper like a lobster's claw, and no idea who will move it next.
4
5 It could be you. Open [the arm's page](https://arm--forge-trevato-apps.open-platform.sh) on your phone or laptop, join the line, and when your turn comes the arm in the shop moves when you move. No download, no account needed to watch, nothing to install.
6
7 <!-- camera -->
8
9 This is the story of how that works, how you can build one of your own, and how a crew of AI agents keeps making it better.
10
11 ## How it works
12
13 When you drag a slider or press a key, your browser sends a small message: "shoulder to here, elbow to there". That message crosses the internet to the shop, and the arm's answer comes back, in a fraction of a second.
14
15 ```flow
16 Your browser: sends where you want each joint to go, many times a second
17 The forge: the server that hosts the app; it keeps the line and checks it's really your turn
18 The shop's Raspberry Pi: a credit-card-sized computer beside the arm; it checks every move is safe
19 Six servos: small motors that each turn one joint, and report back where they are
20 ```
21
22 A few words you'll meet on the way:
23
24 - **Latency** is the delay between your press and the arm moving. Messages travel fast, but not instantly: there is the trip to the server, the trip to the shop, and the time the motor takes to start turning. The arm measures all of it, every turn, and the crew works to keep it short.
25 - **The queue** is the line. Only one person drives at a time, so everyone else waits their turn. A turn lasts a few minutes and ends early if the arm sits idle, so the line keeps moving.
26 - **STOP** is the big red button. The driver, or whoever is looking after the arm, can press it (or the space bar, or Esc) at any moment. The arm freezes and holds still until someone chooses to carry on. It even gets through while the connection is shaky.
27 - **The safety zone** is an invisible line around the table and the arm's own base. Before any move, the Pi works out where every part of the arm would end up. If a move would push the arm into the table or into its own base, the Pi flags it, and when the owner switches the zone to *enforce*, it refuses the move outright. Speed is capped too, and if your connection drops, the arm holds still for a second and then slowly moves back to a resting pose.
28
29 A *servo* is a motor that knows its own position: tell it "go to 90 degrees" and it goes there and stays. The arm's six servos share one cable, like beads on a string, and the Pi talks to each one by its number.
30
31 ## Build your own
32
33 The arm is an **SO-101**, an open design by The Robot Studio. Open means anyone can see the plans, print the parts and build one. You can 3D-print the pieces yourself or buy a kit, and you need two arms: a *leader* you move by hand, and a *follower* that copies it.
34
35 - **Start with Hugging Face.** The [LeRobot SO-101 guide](https://huggingface.co/docs/lerobot/so101) walks through parts, assembly and calibration step by step. LeRobot is Hugging Face's free toolkit for robots that learn.
36 - **Then take this code.** Everything running this arm is in a public repository: [forge.open-platform.sh/trevato/arm](https://forge.open-platform.sh/trevato/arm). The app is in `Software/so101`, and the hardware files are at the top.
37 - **Plug in two arms and run `bun so101 setup`.** It finds both arms, reuses any calibration you already have, and starts you driving the follower from the leader on your own desk. (That one command is being built right now; until it lands, `Software/README.md` in the repository has the steps.)
38
39 Once your follower moves, put it on a Raspberry Pi with a camera and you can share it the way this one is shared.
40
41 ## What the crew built
42
43 Most of this arm's software was written by a crew of AI agents, working with the arm's owner. The owner says what matters ("the arm snaps back when I let go", "the page feels slow"). An agent picks up the task, writes the change and its tests, and opens a pull request. A person reads it and merges it, and the live arm runs the new code within minutes. In its first week the crew landed well over a hundred of these changes.
44
45 The rule they work by: measure first, then fix, then measure again. So the arm keeps a scorecard.
46
47 <!-- numbers -->
48
49 - **Snap-backs per 100 releases.** When you let go of a slider, the arm should stop where you left it. A *snap-back* is when it jumps somewhere else instead. Fewer is better, and zero is the goal.
50 - **Time to arrive.** From your last move to the arm settling on the spot you asked for. The number shown is the *p95*: 95 of every 100 moves arrive at least this fast.
51
52 Some of what the scorecard caught along the way: a quick flick of a slider used to leave the arm 42 steps short of its target, never arriving. After one fix it lands within 10 steps, in about a second. The jam detector once mistook a fast, hard start for a stuck motor, 17 times. That false alarm was behind two of every three snap-backs, until the crew taught it the difference.
53
54 None of it is finished. That's the fun part.
55
56 ## Come and drive
57
58 [Open the arm](https://arm--forge-trevato-apps.open-platform.sh), say hello in the chat, and join the line. If the shop is dark, it's night in Wisconsin. The arm is still there, and you can still drive it.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs