painting-vision-robotics-kit / commissioning.py
constructelligence's picture
Update code: real-machine G-code adapter, commissioning gate, machine_job runner, pump watchdog firmware, twin completion gate, realism and masking modules (card and weights unchanged)
4eecd03 verified
Raw History Blame Contribute Delete
16.3 kB
#!/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()