Public: anyone can read this; the crew can change it.
Migrated from github.com/Trevato/SO-ARM100
workbenchthis machine
setup: find LeRobot calibration in its nested folders (calibration/robots/so_follower/*.json) #577
Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.
smith/arm:smith/576-setup-find-lerobot-calibration-in-its-ne → main 3 commits fork 1 thread · 1 unresolved
6 files
changed +107
−18
Software/so101/README.md +1 −1
| @@ -12,7 +12,7 @@ bun install && bun so101 setup | ||
| 12 | 12 | |
| 13 | 13 | Setup is full-screen: it finds both arms (and waits if only one shows up), asks you to wiggle the one you will hold |
| 14 | 14 | (remembered by USB serial number in `~/.config/so101/arms.json`), checks each servo's calibrated range, and reuses LeRobot's |
| 15 | files in `~/.cache/huggingface/lerobot/calibration/` when a servo has forgotten its range. Only a joint that is out of range | |
| 15 | files when a servo has forgotten its range. It searches `~/.cache/huggingface/lerobot/calibration/{robots,teleoperators}` and the folders inside them, up to four deep (LeRobot nests them, e.g. `robots/so_follower/so101_follower.json`), takes the newest `.json`, and prints which file it uses. `HF_LEROBOT_CALIBRATION` (LeRobot's own variable) names the calibration folder when yours is elsewhere, and then replaces the default. Only a joint that is out of range | |
| 16 | 16 | is calibrated again, one at a time. Then the leader drives the follower, 60 Hz, space to STOP. Later, `bun so101 teleop` |
| 17 | 17 | skips the questions (`bun so101 teleop --leader P --follower P [--save]` names the ports, and `--save` remembers them). `bun so101 setup --dry-run` shows the plan without touching an arm. Assembly and calibration background: |
| 18 | 18 | https://huggingface.co/docs/lerobot/so101 |
Software/so101/src/arm-calibration.test.ts +38 −1
| @@ -1,5 +1,8 @@ | ||
| 1 | 1 | import { expect, test } from "bun:test"; |
| 2 | import { judge, parseLerobot } from "./arm-calibration.ts"; | |
| 2 | import { mkdirSync, mkdtempSync, utimesSync, writeFileSync } from "node:fs"; | |
| 3 | import { tmpdir } from "node:os"; | |
| 4 | import { join } from "node:path"; | |
| 5 | import { judge, findLerobot, lerobotDirs, parseLerobot } from "./arm-calibration.ts"; | |
| 3 | 6 | |
| 4 | 7 | const lerobot = { shoulder_pan: { id: 1, drive_mode: 0, homing_offset: 5, range_min: 800, range_max: 3200 }, gripper: { id: 6, range_min: 5, range_max: 6 }, bogus: {} }; |
| 5 | 8 | |
| @@ -27,3 +30,37 @@ test("a joint with a missing or out-of-bounds homing_offset is not trusted", () | ||
| 27 | 30 | for (const homing_offset of [undefined, 2048, -2048, 1.5, "5"]) expect(parseLerobot({ shoulder_pan: { ...joint, homing_offset } }).size).toBe(0); |
| 28 | 31 | expect(parseLerobot({ shoulder_pan: { ...joint, homing_offset: -2047 } }).get(1)?.offset).toBe(-2047); |
| 29 | 32 | }); |
| 33 | ||
| 34 | { | |
| 35 | const joint = { id: 1, drive_mode: 0, homing_offset: 10, range_min: 500, range_max: 3500 }; | |
| 36 | ||
| 37 | test("finds calibration/robots/so_follower/*.json and names the file", () => { | |
| 38 | const root = mkdtempSync(join(tmpdir(), "lerobot-")); | |
| 39 | const dir = join(root, ".cache", "huggingface", "lerobot", "calibration", "robots", "so_follower"); | |
| 40 | mkdirSync(dir, { recursive: true }); | |
| 41 | writeFileSync(join(dir, "so101_follower.json"), JSON.stringify({ shoulder_pan: joint })); | |
| 42 | const where = lerobotDirs("robots", root, {}); | |
| 43 | const found = findLerobot(where); | |
| 44 | expect(found.file).toBe(join(dir, "so101_follower.json")); | |
| 45 | expect(found.calibration.get(1)).toEqual({ min: 500, max: 3500, offset: 10 }); | |
| 46 | expect(findLerobot(lerobotDirs("teleoperators", root, {})).file).toBeNull(); | |
| 47 | }); | |
| 48 | ||
| 49 | test("HF_LEROBOT_CALIBRATION points at the calibration folder", () => { | |
| 50 | expect(lerobotDirs("teleoperators", "/h", { HF_LEROBOT_CALIBRATION: "/c" })).toBe("/c/teleoperators"); | |
| 51 | }); | |
| 52 | ||
| 53 | test("the newest file wins across folders, and files deeper than the limit are not looked at", () => { | |
| 54 | const root = mkdtempSync(join(tmpdir(), "lerobot-")); | |
| 55 | const old = join(root, "a"); | |
| 56 | const fresh = join(root, "b", "c"); | |
| 57 | const deep = join(root, "1", "2", "3", "4", "5", "6"); | |
| 58 | for (const d of [old, fresh, deep]) mkdirSync(d, { recursive: true }); | |
| 59 | writeFileSync(join(old, "old.json"), "{}"); | |
| 60 | utimesSync(join(old, "old.json"), 1, 1); | |
| 61 | writeFileSync(join(fresh, "new.json"), JSON.stringify({ shoulder_pan: joint })); | |
| 62 | writeFileSync(join(deep, "too-deep.json"), "{}"); | |
| 63 | expect(findLerobot(root).file).toBe(join(fresh, "new.json")); | |
| 64 | expect(findLerobot(join(root, "1")).file).toBeNull(); | |
| 65 | }); | |
| 66 | } |
Software/so101/src/arm-calibration.ts +31 −10
| @@ -24,6 +24,7 @@ export type Verdict = | ||
| 24 | 24 | | { id: number; state: "recalibrate"; why: string }; |
| 25 | 25 | |
| 26 | 26 | export function lerobotDirs(kind: "robots" | "teleoperators", home: string = homedir(), env: Record<string, string | undefined> = process.env): string { |
| 27 | if (env.HF_LEROBOT_CALIBRATION) return join(env.HF_LEROBOT_CALIBRATION, kind); | |
| 27 | 28 | const cache = env.HF_HOME ? join(env.HF_HOME, "lerobot") : join(env.XDG_CACHE_HOME ?? join(home, ".cache"), "huggingface", "lerobot"); |
| 28 | 29 | return join(cache, "calibration", kind); |
| 29 | 30 | } |
| @@ -44,19 +45,39 @@ export function parseLerobot(body: unknown): Map<number, Calibration> { | ||
| 44 | 45 | return out; |
| 45 | 46 | } |
| 46 | 47 | |
| 47 | /** The newest calibration file in `dir`, parsed; an empty map when there is none. */ | |
| 48 | export function newestLerobot(dir: string): Map<number, Calibration> { | |
| 48 | const MAX_DEPTH = 4; | |
| 49 | ||
| 50 | /** The newest `.json` under `dir` and its mtime; a folder that cannot be read is skipped, its siblings still count. */ | |
| 51 | function newestJson(dir: string, depth = 0): { file: string; at: number } | null { | |
| 49 | 52 | let best: { file: string; at: number } | null = null; |
| 53 | let entries; | |
| 50 | 54 | try { |
| 51 | for (const name of readdirSync(dir)) { | |
| 52 | if (!name.endsWith(".json")) continue; | |
| 53 | const file = join(dir, name); | |
| 54 | const at = statSync(file).mtimeMs; | |
| 55 | if (!best || at > best.at) best = { file, at }; | |
| 56 | } | |
| 57 | return best ? parseLerobot(JSON.parse(readFileSync(best.file, "utf8"))) : new Map(); | |
| 55 | entries = readdirSync(dir, { withFileTypes: true }); | |
| 58 | 56 | } catch { |
| 59 | return new Map(); | |
| 57 | return null; | |
| 58 | } | |
| 59 | for (const entry of entries) { | |
| 60 | const file = join(dir, entry.name); | |
| 61 | let found: { file: string; at: number } | null = null; | |
| 62 | try { | |
| 63 | if (entry.isDirectory()) found = depth < MAX_DEPTH ? newestJson(file, depth + 1) : null; | |
| 64 | else if (entry.isFile() && entry.name.endsWith(".json")) found = { file, at: statSync(file).mtimeMs }; | |
| 65 | } catch { | |
| 66 | continue; | |
| 67 | } | |
| 68 | if (found && (!best || found.at > best.at)) best = found; | |
| 69 | } | |
| 70 | return best; | |
| 71 | } | |
| 72 | ||
| 73 | /** The newest calibration file under `dir`, however deep (LeRobot nests them: robots/so_follower/*.json), with what it holds. One walk, so the file named is the file parsed. */ | |
| 74 | export function findLerobot(dir: string): { file: string | null; calibration: Map<number, Calibration> } { | |
| 75 | const file = newestJson(dir)?.file ?? null; | |
| 76 | if (!file) return { file, calibration: new Map() }; | |
| 77 | try { | |
| 78 | return { file, calibration: parseLerobot(JSON.parse(readFileSync(file, "utf8"))) }; | |
| 79 | } catch { | |
| 80 | return { file, calibration: new Map() }; | |
| 60 | 81 | } |
| 61 | 82 | } |
| 62 | 83 |
Software/so101/src/data-view.test.ts +2
| @@ -237,6 +237,8 @@ async function piChart(sample?: { piTemp?: number; piUndervolt?: boolean }): Pro | ||
| 237 | 237 | if (sample) facts.sample({ watchers: 0, drivers: 0, queue: 0, linkLive: true, fps: {}, ...sample }); |
| 238 | 238 | const { document, byId } = dom(); |
| 239 | 239 | new Function("document", "fetch", "addEventListener", "setTimeout", "clearTimeout", DATA_SCRIPT)(document, (url: string) => fetch(base + url, { headers: owner }), () => {}, () => 0, () => {}); |
| 240 | // a fixed pause is too short on a loaded machine: wait for the chart to be drawn | |
| 241 | for (let i = 0; i < 100 && !byId.get("c-pi")!.children.length; i++) await new Promise((r) => setTimeout(r, 50)); | |
| 240 | 242 | await settle(); |
| 241 | 243 | return byId.get("c-pi")!; |
| 242 | 244 | } |
Software/so101/src/setup.test.ts +29 −1
| @@ -7,7 +7,7 @@ import { FakeBus } from "./fake-bus.ts"; | ||
| 7 | 7 | import { keyQueue } from "./keys.ts"; |
| 8 | 8 | import { IDS } from "./local-teleop.ts"; |
| 9 | 9 | import { foundSentence } from "./arms.ts"; |
| 10 | import { ensureCalibrated, progress, recalibrateJoint, whoIsTheLeader } from "./setup.ts"; | |
| 10 | import { dryRun, ensureCalibrated, progress, recalibrateJoint, whoIsTheLeader } from "./setup.ts"; | |
| 11 | 11 | import { STS3215 } from "./sts3215.ts"; |
| 12 | 12 | |
| 13 | 13 | const arm = () => { |
| @@ -180,3 +180,31 @@ test("progress marks the current and finished steps; foundSentence reads 0, 1 an | ||
| 180 | 180 | expect(foundSentence(1)).toContain("I see 1 arm. Plug in the other one"); |
| 181 | 181 | expect(foundSentence(2)).toBe("I see 2 arms."); |
| 182 | 182 | }); |
| 183 | ||
| 184 | test("the nested LeRobot file is named in the dry run and in ensureCalibrated", async () => { | |
| 185 | const home = mkdtempSync(join(tmpdir(), "lerobot-")); | |
| 186 | const dir = join(home, "calibration", "robots", "so_follower"); | |
| 187 | mkdirSync(dir, { recursive: true }); | |
| 188 | const file = join(dir, "so101_follower.json"); | |
| 189 | writeFileSync(file, JSON.stringify({ shoulder_pan: { id: 1, homing_offset: 1, range_min: 800, range_max: 3200 } })); | |
| 190 | const old = process.env.HF_LEROBOT_CALIBRATION; | |
| 191 | process.env.HF_LEROBOT_CALIBRATION = join(home, "calibration"); | |
| 192 | try { | |
| 193 | const lines: string[] = []; | |
| 194 | await dryRun((line) => lines.push(line)); | |
| 195 | expect(lines).toContain(` 3. LeRobot robots calibration: 1 joints found in ${file}, reused where the servos disagree`); | |
| 196 | expect(lines).toContain(" 3. LeRobot teleoperators calibration: none found"); | |
| 197 | ||
| 198 | const { bus } = arm(); | |
| 199 | for (const id of IDS) { | |
| 200 | await bus.write(id, STS3215.Min_Position_Limit, 700); | |
| 201 | await bus.write(id, STS3215.Max_Position_Limit, 3300); | |
| 202 | } | |
| 203 | out.mockClear(); | |
| 204 | await ensureCalibrated(keyQueue(), bus, "robots", "follower"); | |
| 205 | expect(out.mock.calls.map((c: unknown[]) => String(c[0])).join("")).toContain(`Reference: ${file}`); | |
| 206 | } finally { | |
| 207 | if (old === undefined) delete process.env.HF_LEROBOT_CALIBRATION; | |
| 208 | else process.env.HF_LEROBOT_CALIBRATION = old; | |
| 209 | } | |
| 210 | }); |
Software/so101/src/setup.ts +6 −5
| @@ -2,7 +2,7 @@ | ||
| 2 | 2 | |
| 3 | 3 | import { SerialPort } from "serialport"; |
| 4 | 4 | import { adaptersOf, configFile, foundSentence, loadRoles, movement, saveRoles, savedRoles, WIGGLE_TICKS, type Adapter } from "./arms.ts"; |
| 5 | import { FULL_TURN, MIN_RANGE, judge, lerobotDirs, newestLerobot, type Verdict } from "./arm-calibration.ts"; | |
| 5 | import { FULL_TURN, MIN_RANGE, judge, findLerobot, lerobotDirs, type Verdict } from "./arm-calibration.ts"; | |
| 6 | 6 | import { FeetechBus } from "./bus.ts"; |
| 7 | 7 | import { IDS, readLimits } from "./local-teleop.ts"; |
| 8 | 8 | import { driveScreen } from "./local-teleop-run.ts"; |
| @@ -30,8 +30,8 @@ export async function dryRun(write: (line: string) => void = console.log): Promi | ||
| 30 | 30 | write(` 1. I see ${adapters.length} arm${adapters.length === 1 ? "" : "s"}: ${adapters.map((a) => `${a.path}${a.serial ? ` (#${a.serial})` : ""}`).join(", ")}`); |
| 31 | 31 | write(` 2. ${savedRoles(saved, adapters) ? "leader remembered by serial number" : "you wiggle the arm you will hold; its serial number is remembered"} (${configFile()})`); |
| 32 | 32 | for (const kind of ["robots", "teleoperators"] as const) { |
| 33 | const found = newestLerobot(lerobotDirs(kind)); | |
| 34 | write(` 3. LeRobot ${kind} calibration: ${found.size ? `${found.size} joints found, reused where the servos disagree` : "none found"}`); | |
| 33 | const { file, calibration } = findLerobot(lerobotDirs(kind)); | |
| 34 | write(` 3. LeRobot ${kind} calibration: ${calibration.size ? `${calibration.size} joints found in ${file}, reused where the servos disagree` : "none found"}`); | |
| 35 | 35 | } |
| 36 | 36 | write(" each servo's own limits are checked; only a joint out of range is calibrated again, one at a time"); |
| 37 | 37 | write(" 4. so101 teleop drives the follower from the leader at 60 Hz; space stops it"); |
| @@ -153,7 +153,8 @@ export async function recalibrateJoint(key: Keys, bus: FeetechBus, id: number, w | ||
| 153 | 153 | |
| 154 | 154 | export async function ensureCalibrated(key: Keys, bus: FeetechBus, kind: "robots" | "teleoperators", who: string): Promise<void> { |
| 155 | 155 | const present = await bus.syncRead(IDS, STS3215.Present_Position); |
| 156 | const verdicts: Verdict[] = judge(await readLimits(bus), present, newestLerobot(lerobotDirs(kind))); | |
| 156 | const { file, calibration } = findLerobot(lerobotDirs(kind)); | |
| 157 | const verdicts: Verdict[] = judge(await readLimits(bus), present, calibration); | |
| 157 | 158 | for (const v of verdicts) { |
| 158 | 159 | if (v.state === "restore") { |
| 159 | 160 | await bus.write(v.id, STS3215.Homing_Offset, v.range.offset); |
| @@ -163,7 +164,7 @@ export async function ensureCalibrated(key: Keys, bus: FeetechBus, kind: "robots | ||
| 163 | 164 | else if (v.state === "recalibrate") await recalibrateJoint(key, bus, v.id, `${who}: ${v.why}`); |
| 164 | 165 | } |
| 165 | 166 | const fixed = verdicts.filter((v) => v.state !== "ok").length; |
| 166 | show(2, [`${who}: ${fixed ? `${fixed} joint${fixed === 1 ? "" : "s"} fixed, the rest kept as calibrated` : "calibration is fine, kept as it is"}.`]); | |
| 167 | show(2, [`${who}: ${fixed ? `${fixed} joint${fixed === 1 ? "" : "s"} fixed, the rest kept as calibrated` : "calibration is fine, kept as it is"}.`, ...(file ? [`Reference: ${file}`] : [])]); | |
| 167 | 168 | await sleep(700); |
| 168 | 169 | } |
| 169 | 170 |
new above
offline
Low: newest
.jsonacross every folder underrobots/(orteleoperators/) wins, whatever the device. LeRobot keeps one folder per robot type (so_follower,koch_follower,so100_follower, …). An owner who has ever calibrated another arm more recently would get that file's homing offsets and ranges restored onto the SO-101 servos. The joint names are the same, soparseLerobotwould accept it. Setup does print the file it uses, which makes this visible. A follow-up could prefer folders whose name starts withso(or matchesso101), and fall back to newest-anywhere only when none match.