#!/usr/bin/env python3 """Commissioning: the checks a real machine must pass, and record, before it paints a wall. Simulation proved the software's logic; it cannot prove a machine. This is the bring-up sequence for a physical prototype, in the order it is done, each item with a pass criterion that is a number, not a feeling: ================= ========== =========================================================================================== item how passes when ================= ========== =========================================================================================== estop manual hard e-stop pressed during an air-cut move cuts motor AND pump power; coast <= 50 mm watchdog_relay manual USB unplugged during an air-cut move: the hardware watchdog relay drops the pump within 0.5 s and the carriage coasts <= ``max_coast_mm``. A GRBL board keeps running its buffered moves when the host dies; no host-side software can stop that. limits automatic GRBL $$: soft limits ($20=1), hard limits ($21=1), homing ($22=1), max travel ($130-$132) inside the machine file's travel, so firmware refuses what the file allows touch_off manual Y at which the tool face touches the wall, at three heights, agrees within 2 mm repeatability measured 20 moves to one target from alternating sides: 1-sigma <= 1.0 mm (planner assumes 2 mm) square measured 1000 mm square drawn with a marker: scale within 0.5 %, skew <= 0.1 degrees test_panel measured a 1220 x 2440 mm sheet painted wet: wet-film comb mean within +-15 % of target, coverage >= 95 % by a person, and the vision model's completion read within 5 points of the person ================= ========== =========================================================================================== A wall needs every item passed. A test panel needs every item except the test panel itself. Items expire (``estop`` and ``watchdog_relay`` after 30 days, ``touch_off`` after 1 day: the base moves; the rest after 90 days). The spray drone has its own list (``DRONE_ITEMS``): RTK fix, rangefinder against a tape, pump relay on water, a tethered hover hold from a flight log (``drone_log.flight_quality``), and a people-in-frame walk test. python3 commissioning.py status --machine prototype python3 commissioning.py program repeatability --machine machine.json > repeat.nc python3 commissioning.py record repeatability --machine prototype --x-mm 0.3,-0.2,... --by "A. Tester" python3 commissioning.py record square --machine prototype --sides-mm 999.2,1000.4,999.8,1000.1 --diagonals-mm 1414.6,1413.9 python3 commissioning.py limits --machine machine.json --settings grbl_settings.txt """ from __future__ import annotations import argparse import datetime as _dt import json import math import re from pathlib import Path import measurements HERE = Path(__file__).resolve().parent RECORD = HERE / "artifacts" / "machine_runs" / "commissioning.json" MAST_ITEMS = ("estop", "watchdog_relay", "limits", "touch_off", "repeatability", "square", "test_panel") DRONE_ITEMS = ("rtk_fix", "rangefinder", "pump_relay", "hover_hold", "people_walk") EXPIRES_DAYS = {"estop": 30, "watchdog_relay": 30, "touch_off": 1, "rtk_fix": 1, "rangefinder": 30, "pump_relay": 30, "hover_hold": 30, "people_walk": 30} DEFAULT_EXPIRY = 90 LIMITS = {"estop_coast_mm": 50.0, "max_coast_mm": 300.0, "relay_drop_s": 0.5, "touch_off_spread_mm": 2.0, "repeatability_mm": 1.0, "scale_pct": 0.5, "skew_deg": 0.1, "film_pct": 15.0, "coverage": 0.95, "model_vs_person_pts": 5.0, "rtk_hacc_m": 0.03, "rangefinder_m": 0.03, "hover_standoff_sigma_m": 0.06} def _load(record=None): p = Path(record) if record else RECORD return json.loads(p.read_text()) if p.exists() else {} def _save(data, record=None): p = Path(record) if record else RECORD p.parent.mkdir(parents=True, exist_ok=True) p.write_text(json.dumps(data, indent=1)) def store(machine, item, passed, values, by=None, record=None, date=None): """Record one item's result (pass or fail, both are kept: a failure is evidence too).""" if not str(by or "").strip(): raise ValueError("commissioning results need a named person (--by)") data = _load(record) entry = {"passed": bool(passed), "values": values, "by": by, "date": date or _dt.date.today().isoformat()} m = data.setdefault(machine, {}) m.setdefault("_history", []).append({"item": item, **entry}) m[item] = entry _save(data, record) return entry def ready(machine, for_="wall", record=None, today=None, platform="mast_arm"): """{ready, missing}: what stands between this machine and a wet run on a wall (or on a test panel).""" data = (record if isinstance(record, dict) else _load(record)).get(machine, {}) items = DRONE_ITEMS if platform == "spray_drone" else MAST_ITEMS need = [i for i in items if not (for_ == "test_panel" and i == "test_panel")] today = today or _dt.date.today() missing = [] for item in need: e = data.get(item) if not e: missing.append(f"{item}: not done") elif not e["passed"]: missing.append(f"{item}: failed on {e['date']}") elif (today - _dt.date.fromisoformat(e["date"])).days > EXPIRES_DAYS.get(item, DEFAULT_EXPIRY): missing.append(f"{item}: expired (done {e['date']}, valid {EXPIRES_DAYS.get(item, DEFAULT_EXPIRY)} days)") return {"ready": not missing, "missing": missing} def machine_with_record(machine, record=None): """The machine file with commissioning values merged in (the touch-off Y).""" e = _load(record).get(machine.name, {}).get("touch_off") if e and e["passed"]: machine.y_wall_mm = e["values"]["y_wall_mm"] return machine # ------------------------------------------------------------------ evaluators (pure: readings in, verdict out) def eval_estop(coast_mm, motors_off, pump_off): ok = motors_off and pump_off and coast_mm <= LIMITS["estop_coast_mm"] return ok, {"coast_mm": coast_mm, "motors_off": motors_off, "pump_off": pump_off} def eval_watchdog_relay(pump_drop_s, coast_mm): ok = pump_drop_s <= LIMITS["relay_drop_s"] and coast_mm <= LIMITS["max_coast_mm"] return ok, {"pump_drop_s": pump_drop_s, "coast_mm": coast_mm, "note": None if ok else "add or fix the hardware watchdog relay on the pump, and keep fewer/shorter " "moves buffered (shorter segments) so a dead host cannot drive far"} def parse_grbl_settings(text): out = {} for m in re.finditer(r"\$(\d+)=(-?[\d.]+)", text): out[int(m.group(1))] = float(m.group(2)) return out def eval_limits(settings, machine): """GRBL $$ against the machine file: firmware must refuse anything the machine file would not allow.""" s = parse_grbl_settings(settings) if isinstance(settings, str) else settings problems = [] for key, what in ((20, "soft limits"), (21, "hard limits"), (22, "homing")): if s.get(key) != 1: problems.append(f"${key} ({what}) is {s.get(key)!r}, must be 1") for key, axis, travel in ((130, "X", machine.x_travel_mm), (131, "Y", machine.y_travel_mm), (132, "Z", machine.z_travel_mm)): if key not in s: problems.append(f"${key} ({axis} max travel) missing") elif travel[1] > s[key] + 1e-6: problems.append(f"machine file lets {axis} go to {travel[1]:g} mm but firmware travel is {s[key]:g} mm") return not problems, {"problems": problems} def eval_touch_off(y_readings_mm): if len(y_readings_mm) < 3: raise ValueError("touch off at three heights (low, middle, high)") spread = max(y_readings_mm) - min(y_readings_mm) y = sorted(y_readings_mm)[len(y_readings_mm) // 2] ok = spread <= LIMITS["touch_off_spread_mm"] return ok, {"y_wall_mm": y, "spread_mm": round(spread, 2), "note": None if ok else "the base is not square to the wall, or the wall is not plumb: re-park / shim, " "or the planner's flat-wall assumption is wrong for this wall"} def eval_repeatability(x_mm, y_mm=None): fit = measurements.fit_repeatability(x_mm, y_mm) return fit["repeatability_sigma_mm"] <= LIMITS["repeatability_mm"], fit def eval_square(sides_mm, diagonals_mm, side_cmd_mm=1000.0): """Scale from the mean side, skew from the diagonals: d1 - d2 ~= sqrt(2) * a * theta for small skew theta.""" if len(sides_mm) != 4 or len(diagonals_mm) != 2: raise ValueError("four sides and two diagonals") scale_pct = (sum(sides_mm) / 4 / side_cmd_mm - 1) * 100 a = sum(sides_mm) / 4 skew_deg = math.degrees((diagonals_mm[0] - diagonals_mm[1]) / (math.sqrt(2) * a)) ok = abs(scale_pct) <= LIMITS["scale_pct"] and abs(skew_deg) <= LIMITS["skew_deg"] return ok, {"scale_pct": round(scale_pct, 3), "skew_deg": round(skew_deg, 4), "steps_per_mm_factor": round(side_cmd_mm / a, 5)} def eval_test_panel(film_um, target_um, person_coverage, model_coverage=None): mean = sum(film_um) / len(film_um) err_pct = (mean / target_um - 1) * 100 ok = abs(err_pct) <= LIMITS["film_pct"] and person_coverage >= LIMITS["coverage"] gap = None if model_coverage is None else abs(model_coverage - person_coverage) * 100 if gap is None or gap > LIMITS["model_vs_person_pts"]: ok = False return ok, {"film_mean_um": round(mean, 1), "film_err_pct": round(err_pct, 1), "film_readings": len(film_um), "person_coverage": person_coverage, "model_coverage": model_coverage, "model_gap_pts": None if gap is None else round(gap, 1), "note": None if gap is not None else "the vision model's read of the panel is required: it is what " "decides a wall is finished"} def eval_drone(item, **v): if item == "rtk_fix": ok = v.get("fix") == "rtk_fixed" and v["hacc_m"] <= LIMITS["rtk_hacc_m"] elif item == "rangefinder": errs = [abs(a - b) for a, b in zip(v["measured_m"], v["tape_m"])] v["max_err_m"] = round(max(errs), 3) ok = v["max_err_m"] <= LIMITS["rangefinder_m"] elif item == "hover_hold": ok = v["standoff_sigma_m"] <= LIMITS["hover_standoff_sigma_m"] else: # pump_relay, people_walk: observed pass/fail ok = bool(v.get("passed")) return ok, v # ------------------------------------------------------------------ test programs (G-code for the operator's sender) def program_repeatability(machine, target=(600.0, 1500.0), n=20, approach_mm=150.0, feed=6000): """Move to one target from alternating sides n times, pausing (M0) for a dial-indicator reading each time.""" x, z = target y = machine.y_retract_mm out = ["(repeatability: read the dial indicator at each M0)", "G21 G90 G94", f"G1 Y{y:g} F600"] for i in range(n): dx, dz = [(approach_mm, 0), (-approach_mm, 0), (0, approach_mm), (0, -approach_mm)][i % 4] out += [f"G1 X{x + dx:g} Z{z + dz:g} F{feed}", f"G1 X{x:g} Z{z:g} F{feed}", f"M0 (reading {i + 1} of {n})"] return "\n".join(out + ["M2"]) + "\n" def program_square(machine, origin=(100.0, 1000.0), side=1000.0, feed=3000): """A marker square on paper taped to the wall (marker on the tool plate, touching at y_wall_mm).""" if machine.y_wall_mm is None: raise ValueError("touch off first: the marker needs y_wall_mm") x0, z0 = origin pts = [(x0, z0), (x0 + side, z0), (x0 + side, z0 + side), (x0, z0 + side), (x0, z0)] out = ["(square: measure the four sides and both diagonals)", "G21 G90 G94", f"G1 Y{machine.y_retract_mm:g} F600", f"G1 X{x0:g} Z{z0:g} F{feed}", f"G1 Y{machine.y_wall_mm + 1:g} F300"] out += [f"G1 X{x:g} Z{z:g} F{feed}" for x, z in pts[1:]] return "\n".join(out + [f"G1 Y{machine.y_retract_mm:g} F600", "M2"]) + "\n" def _floats(t): return [float(v) for v in str(t).split(",") if v.strip()] def main(): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) ap.add_argument("--record", help="commissioning record (default artifacts/machine_runs/commissioning.json)") sub = ap.add_subparsers(dest="cmd", required=True) st = sub.add_parser("status") st.add_argument("--machine", required=True, help="machine name") st.add_argument("--platform", default="mast_arm") pr = sub.add_parser("program") pr.add_argument("which", choices=["repeatability", "square"]) pr.add_argument("--machine", help="machine JSON") li = sub.add_parser("limits") li.add_argument("--machine", required=True, help="machine JSON") li.add_argument("--settings", required=True, help="text file with GRBL's $$ output") li.add_argument("--by", required=True) rc = sub.add_parser("record") rc.add_argument("item", choices=MAST_ITEMS + DRONE_ITEMS) rc.add_argument("--machine", required=True, help="machine name") rc.add_argument("--by", required=True) for opt in ("--coast-mm", "--pump-drop-s", "--target-um", "--person-coverage", "--model-coverage", "--hacc-m", "--standoff-sigma-m"): rc.add_argument(opt, type=float) for opt in ("--y-mm", "--x-mm", "--sides-mm", "--diagonals-mm", "--film-um", "--measured-m", "--tape-m"): rc.add_argument(opt) rc.add_argument("--fix") rc.add_argument("--motors-off", action="store_true") rc.add_argument("--pump-off", action="store_true") rc.add_argument("--passed", action="store_true", help="observed pass (pump_relay, people_walk)") a = ap.parse_args() from controller_adapter import Machine if a.cmd == "status": r = ready(a.machine, record=a.record, platform=a.platform) panel = ready(a.machine, for_="test_panel", record=a.record, platform=a.platform) print(f"{a.machine}: walls {'READY' if r['ready'] else 'NOT ready'}; test panel {'ready' if panel['ready'] else 'not ready'}") for m in r["missing"]: print(" -", m) return if a.cmd == "program": machine = machine_with_record(Machine.load(a.machine), a.record) print(program_repeatability(machine) if a.which == "repeatability" else program_square(machine), end="") return if a.cmd == "limits": machine = Machine.load(a.machine) ok, values = eval_limits(Path(a.settings).read_text(), machine) print(json.dumps(store(machine.name, "limits", ok, values, a.by, a.record), indent=1)) raise SystemExit(0 if ok else 1) item = a.item if item == "estop": ok, v = eval_estop(a.coast_mm, a.motors_off, a.pump_off) elif item == "watchdog_relay": ok, v = eval_watchdog_relay(a.pump_drop_s, a.coast_mm) elif item == "touch_off": ok, v = eval_touch_off(_floats(a.y_mm)) elif item == "repeatability": ok, v = eval_repeatability(_floats(a.x_mm), _floats(a.y_mm) if a.y_mm else None) if ok: measurements.record("machine", "repeatability_sigma_mm", v["repeatability_sigma_mm"], "mm", f"commissioning: {v['moves']} repeated moves", by=a.by) elif item == "square": ok, v = eval_square(_floats(a.sides_mm), _floats(a.diagonals_mm)) elif item == "test_panel": ok, v = eval_test_panel(_floats(a.film_um), a.target_um, a.person_coverage, a.model_coverage) elif item == "rtk_fix": ok, v = eval_drone(item, fix=a.fix, hacc_m=a.hacc_m) elif item == "rangefinder": ok, v = eval_drone(item, measured_m=_floats(a.measured_m), tape_m=_floats(a.tape_m)) elif item == "hover_hold": ok, v = eval_drone(item, standoff_sigma_m=a.standoff_sigma_m) else: ok, v = eval_drone(item, passed=a.passed) print(json.dumps(store(a.machine, item, ok, v, a.by, a.record), indent=1)) raise SystemExit(0 if ok else 1) if __name__ == "__main__": main()