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
Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.
vesper/arm:vesper/565-the-story-page-an-engaging-write-up-of-t → main 2 commits fork
9 files
changed +662
−0
README.md +1
| @@ -4,6 +4,7 @@ | ||
| 4 | 4 | |
| 5 | 5 | - **Watch:** open the link. You don't need an account. You see the camera, the arm's live 3D model and the chat. |
| 6 | 6 | - **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:** [](https://arm--forge-trevato-apps.open-platform.sh/story) ([](docs/story.md)): how it works, how to build your own with the [](https://huggingface.co/docs/lerobot/so101), and what the crew measured. | |
| 7 | 8 | - **Code:** this forge repository is the app's home. The app lives in [](Software/so101), and [](Software/README.md) explains how to run it on your own arm. |
| 8 | 9 | |
| 9 | 10 | github.com/Trevato/SO-ARM100 is deprecated: issues, pulls and new work go here. The upstream hardware project is [](https://github.com/TheRobotStudio/SO-ARM100); its README follows. |
Software/so101/README.md +9
| @@ -2,6 +2,15 @@ | ||
| 2 | 2 | |
| 3 | 3 | `bench/fake-serve.ts` is the hosted app (the page, the room, the relay); `so101 serve` is the arm server on the Pi. |
| 4 | 4 | |
| 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 [](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 | ||
| 5 | 14 | ## The Pi's own health |
| 6 | 15 | |
| 7 | 16 | `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 @@ | ||
| 50 | 50 | * WS /camera/<id>/ws the same feed as whole binary frames (JPEG; the offline PNG when its source is down), latest frame wins |
| 51 | 51 | * GET /data?from&to&step[&compare=1], ?turn=<id> the facts as series, for the owner and moderators (403 to anyone else) |
| 52 | 52 | * 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) | |
| 53 | 54 | * GET /admin/camera-list the owner's page for the camera list |
| 54 | 55 | * POST /admin/cameras {"name", "source"}, DELETE /admin/cameras/<id> the owner changes the list; viewers see it within seconds |
| 55 | 56 | * 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"; | ||
| 82 | 83 | import type { PiSync } from "./pi-deploy.ts"; |
| 83 | 84 | import { serveData } from "./data-api.ts"; |
| 84 | 85 | import { serveDataPage } from "./data-page.ts"; |
| 86 | import { serveStory, weekNumbers, type StoryNumbers } from "./story.ts"; | |
| 85 | 87 | import { handleAdmin, handleLift, type TuneP } from "./admin-routes.ts"; |
| 86 | 88 | import { readPrecision } from "./precision-panel.ts"; |
| 87 | 89 | import { readTuning } from "./tuning-panel.ts"; |
| @@ -759,6 +761,14 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> { | ||
| 759 | 761 | return json(res, 200, { resumed: gate.resume(), held: null }); |
| 760 | 762 | }; |
| 761 | 763 | |
| 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 | ||
| 762 | 772 | const http = createServer(async (req, res) => { |
| 763 | 773 | for (const [name, value] of Object.entries(FLOOR)) res.setHeader(name, value); |
| 764 | 774 | try { |
| @@ -775,6 +785,7 @@ export async function startRelay(options: RelayOptions): Promise<RunningRelay> { | ||
| 775 | 785 | if (cameraAdmin) return await administer(req, res, cameraAdmin[1] === undefined ? null : Number(cameraAdmin[1])); |
| 776 | 786 | if (lobby && url.pathname === "/admin/lift") return await handleLift(lobby, req, res, readBody); |
| 777 | 787 | 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; | |
| 778 | 789 | if (url.pathname === "/admin/versions") return versionsRead(req, res); |
| 779 | 790 | if (lobby && url.pathname === "/admin/data") return serveDataPage(lobby, req, res); |
| 780 | 791 | 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><b>raw</b></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><x></code> <strong>b</strong> <em>c</em> <a href="https://e.example/f?g=1&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("<script>alert("x")</script> & 'q'"); | |
| 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 <!-- camera --></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, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, """).replace(/'/g, "&9;"); | |
| 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(/&/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'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 @@ | ||
| 176 | 176 | #say { display: flex; gap: 8px; padding: 8px calc(12px + var()) 8px calc(12px + var()); border-top: 1px solid var(); } |
| 177 | 177 | #say input { flex: 1; min-width: 0; } |
| 178 | 178 | #sayNote { color: var(); font-size: 13px; padding: 10px calc(12px + var()) 10px calc(12px + var()); border-top: 1px solid var(); } #sayNote:empty { display: none; } |
| 179 | #storyLink { font-size: 13px; padding: 4px calc(12px + var()) 6px calc(12px + var()); border-top: 1px solid var(); } #storyLink a { display: inline-flex; align-items: center; min-height: 32px; color: var(); } #shell.driving #storyLink { display: none; } | |
| 179 | 180 | |
| 180 | 181 | /* queue */ |
| 181 | 182 | #queue { list-style: none; margin: 0; padding: 0; display: grid; gap: 4px; } |
| @@ -330,6 +331,7 @@ | ||
| 330 | 331 | <button type="button" id="newMsgs" hidden>New messages ↓</button> |
| 331 | 332 | <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> |
| 332 | 333 | <div id="sayNote"></div> |
| 334 | <footer id="storyLink"><a href="/story">How this arm works, and how to build your own</a></footer> | |
| 333 | 335 | </div> |
| 334 | 336 | <div class="tab" id="tab-queue" role="tabpanel" aria-labelledby="t-queue" hidden> |
| 335 | 337 | <h2>Driving</h2> |
| @@ -341,6 +343,7 @@ | ||
| 341 | 343 | <h2>Waiting</h2> |
| 342 | 344 | <ol id="queue" aria-label="Queue"></ol> |
| 343 | 345 | <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> | |
| 344 | 347 | <h2>Leader arm</h2> |
| 345 | 348 | <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> |
| 346 | 349 | <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 [](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 [](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: [](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 | [](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. |
new above
offline