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

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

smith/arm:smith/576-setup-find-lerobot-calibration-in-its-ne → main 3 commits fork 1 thread · 1 unresolved

  • Merged. smith/576-setup-find-lerobot-calibration-in-its-ne was merged into main as 6da7fb9.

Review

Sign in to review this change.
6 files changed +107 −18
Software/so101/README.md +1 −1
@@ -12,7 +12,7 @@ bun install && bun so101 setup
1212
1313 Setup is full-screen: it finds both arms (and waits if only one shows up), asks you to wiggle the one you will hold
1414 (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
1616 is calibrated again, one at a time. Then the leader drives the follower, 60 Hz, space to STOP. Later, `bun so101 teleop`
1717 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:
1818 https://huggingface.co/docs/lerobot/so101
Software/so101/src/arm-calibration.test.ts +38 −1
@@ -1,5 +1,8 @@
11 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";
36
47 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: {} };
58
@@ -27,3 +30,37 @@ test("a joint with a missing or out-of-bounds homing_offset is not trusted", ()
2730 for (const homing_offset of [undefined, 2048, -2048, 1.5, "5"]) expect(parseLerobot({ shoulder_pan: { ...joint, homing_offset } }).size).toBe(0);
2831 expect(parseLerobot({ shoulder_pan: { ...joint, homing_offset: -2047 } }).get(1)?.offset).toBe(-2047);
2932 });
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 =
2424 | { id: number; state: "recalibrate"; why: string };
2525
2626 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);
2728 const cache = env.HF_HOME ? join(env.HF_HOME, "lerobot") : join(env.XDG_CACHE_HOME ?? join(home, ".cache"), "huggingface", "lerobot");
2829 return join(cache, "calibration", kind);
2930 }
@@ -44,19 +45,39 @@ export function parseLerobot(body: unknown): Map<number, Calibration> {
4445 return out;
4546 }
4647
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 {
4952 let best: { file: string; at: number } | null = null;
53 let entries;
5054 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 });
5856 } 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;

Low: newest .json across every folder under robots/ (or teleoperators/) 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, so parseLerobot would accept it. Setup does print the file it uses, which makes this visible. A follow-up could prefer folders whose name starts with so (or matches so101), and fall back to newest-anywhere only when none match.

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() };
6081 }
6182 }
6283
Software/so101/src/data-view.test.ts +2
@@ -237,6 +237,8 @@ async function piChart(sample?: { piTemp?: number; piUndervolt?: boolean }): Pro
237237 if (sample) facts.sample({ watchers: 0, drivers: 0, queue: 0, linkLive: true, fps: {}, ...sample });
238238 const { document, byId } = dom();
239239 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));
240242 await settle();
241243 return byId.get("c-pi")!;
242244 }
Software/so101/src/setup.test.ts +29 −1
@@ -7,7 +7,7 @@ import { FakeBus } from "./fake-bus.ts";
77 import { keyQueue } from "./keys.ts";
88 import { IDS } from "./local-teleop.ts";
99 import { foundSentence } from "./arms.ts";
10 import { ensureCalibrated, progress, recalibrateJoint, whoIsTheLeader } from "./setup.ts";
10 import { dryRun, ensureCalibrated, progress, recalibrateJoint, whoIsTheLeader } from "./setup.ts";
1111 import { STS3215 } from "./sts3215.ts";
1212
1313 const arm = () => {
@@ -180,3 +180,31 @@ test("progress marks the current and finished steps; foundSentence reads 0, 1 an
180180 expect(foundSentence(1)).toContain("I see 1 arm. Plug in the other one");
181181 expect(foundSentence(2)).toBe("I see 2 arms.");
182182 });
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 @@
22
33 import { SerialPort } from "serialport";
44 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";
66 import { FeetechBus } from "./bus.ts";
77 import { IDS, readLimits } from "./local-teleop.ts";
88 import { driveScreen } from "./local-teleop-run.ts";
@@ -30,8 +30,8 @@ export async function dryRun(write: (line: string) => void = console.log): Promi
3030 write(` 1. I see ${adapters.length} arm${adapters.length === 1 ? "" : "s"}: ${adapters.map((a) => `${a.path}${a.serial ? ` (#${a.serial})` : ""}`).join(", ")}`);
3131 write(` 2. ${savedRoles(saved, adapters) ? "leader remembered by serial number" : "you wiggle the arm you will hold; its serial number is remembered"} (${configFile()})`);
3232 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"}`);
3535 }
3636 write(" each servo's own limits are checked; only a joint out of range is calibrated again, one at a time");
3737 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
153153
154154 export async function ensureCalibrated(key: Keys, bus: FeetechBus, kind: "robots" | "teleoperators", who: string): Promise<void> {
155155 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);
157158 for (const v of verdicts) {
158159 if (v.state === "restore") {
159160 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
163164 else if (v.state === "recalibrate") await recalibrateJoint(key, bus, v.id, `${who}: ${v.why}`);
164165 }
165166 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}`] : [])]);
167168 await sleep(700);
168169 }
169170

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs