Physical Assembly

# labs/assembly_plan.py
"""The assembly plan: an ordered list of steps, each naming what must be done first."""
import json
import sys
from pathlib import Path

PLAN_FILE = Path("configs/assembly_steps.json")

DEFAULT_PLAN = [
    {"id": "standoffs", "desc": "Press four M2.5 brass standoffs into the base plate.",
     "tools": ["M2.5 driver", "standoffs"], "requires": []},
    {"id": "mount_shoulder", "desc": "Bolt the MG996R shoulder to the base plate, heads underneath.",
     "tools": ["M3 driver"], "requires": []},
    {"id": "mount_pi", "desc": "Seat the Pi 4B on the standoffs. Do not overtighten.",
     "tools": ["M2.5 driver"], "requires": ["standoffs", "mount_shoulder"],
     "why": "the tray covers the shoulder's four M3 heads"},
    {"id": "mount_led_ring", "desc": "Press the LED ring into the diffuser recess, JST tail down.",
     "tools": ["hot glue"], "requires": ["mount_eye_tilt"],
     "why": "the ring sits over the tilt bracket's two M2 screws"},
    {"id": "cable_eye", "desc": "Route eye servos to GPIO 12/13 and the ring data line, 330 ohm inline, to GPIO 10.",
     "tools": ["zip ties", "heatshrink"], "requires": ["mount_led_ring", "mount_pi"],
     "why": "both bundles leave the head through the neck channel"},
    # ...twelve more, ending at final_check
]


def load_plan(path: Path = PLAN_FILE) -> list[dict]:
    """Read the plan. On a machine that has never run this, write the default first."""
    if not path.exists():
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(json.dumps(DEFAULT_PLAN, indent=2) + "\n")
        print(f"wrote {path} ({len(DEFAULT_PLAN)} steps). Edit it to match your build.")
    return json.loads(path.read_text())

$ uv run python -m labs.assembly_plan
wrote configs/assembly_steps.json (17 steps). Edit it to match your build.
17 steps, 0 plan problem(s)

$ uv run python -m labs.assembly_plan   # second run
17 steps, 0 plan problem(s)

The program writes the file it reads, once, and never again. That removes the setup ritual nobody remembers three months later, and it makes the JSON the thing you own: reorder it, delete the fan step, add a rear panel, and the code is untouched. The requires list is the part doing new work. A flat ordered list already implies an order, but implies it silently, so an edit that moves a step past its prerequisite reads exactly like an edit that did not. Naming the prerequisite makes the order checkable, and it gives every step somewhere to record why it sits where it does, in the sentence you will want at two in the morning.

# labs/assembly_plan.py — continued
def plan_problems(steps: list[dict]) -> list[str]:
    """Faults you can find before touching hardware: bad ids, and order that contradicts requires."""
    problems: list[str] = []
    position: dict[str, int] = {}
    for i, step in enumerate(steps):
        if step["id"] in position:
            problems.append(f"step id {step['id']!r} appears twice")
            continue
        position[step["id"]] = i
    for i, step in enumerate(steps):
        for need in step.get("requires", []):
            if need not in position:
                problems.append(f"step {step['id']!r} requires {need!r}, which is not in the plan")
            elif position[need] > i:
                problems.append(f"step {step['id']!r} at position {i + 1} requires "
                                f"{need!r} at position {position[need] + 1}")
    return problems


if __name__ == "__main__":
    steps = load_plan()
    problems = plan_problems(steps)
    for problem in problems:
        print(f"  [x] {problem}")
    print(f"{len(steps)} steps, {len(problems)} plan problem(s)")
    sys.exit(1 if problems else 0)

$ uv run python -m labs.assembly_plan   # after an evening of editing the JSON
  [x] step 'cable_eye' at position 7 requires 'mount_led_ring' at position 12
  [x] step 'cable_audio' requires 'mount_pi4', which is not in the plan
17 steps, 2 plan problem(s)

Two different mistakes, both from the same editing session. The first is an ordering fault: the head cabling got dragged up the file while the ring was left below it, so the plan now tells you to dress a cable that runs from a part you have not fitted. The second is a typo in an id, and it is the one worth catching hardest, because a misspelled prerequisite is a dependency that silently does not exist. Both checks run in a tenth of a second on a laptop, before a single fastener has gone in.

The two passes are not interchangeable. The first builds position for every id in the file; only then can the second ask whether a named prerequisite exists and where it sits. Do it in one pass and a step that requires something declared four lines below it looks identical to a step that requires something declared nowhere, and you get a fake error on a correct plan.

# labs/assembly_checklist.py
"""Interactive assembly checklist: saves after every confirmed step, resumes from disk."""
import argparse
import json
import os
import sys
from pathlib import Path

from labs.assembly_plan import load_plan, plan_problems

PROGRESS_FILE = Path("glados/data/assembly_progress.json")


def load_progress(path: Path = PROGRESS_FILE) -> set[str]:
    """The ids already confirmed. A build that has never run is an empty set, not a crash."""
    if not path.exists():
        return set()
    return set(json.loads(path.read_text()).get("done", []))


def save_progress(done: set[str], path: Path = PROGRESS_FILE) -> None:
    """Write the set as a sorted list, and land the file in one move."""
    path.parent.mkdir(parents=True, exist_ok=True)
    temp = path.with_suffix(".tmp")
    temp.write_text(json.dumps({"done": sorted(done)}, indent=2) + "\n")
    os.replace(temp, path)

$ uv run python -m labs.progress_demo
loaded    []
saved     glados/data/assembly_progress.json
{
  "done": [
    "mount_shoulder",
    "standoffs"
  ]
}
reloaded  ['mount_shoulder', 'standoffs']

A set is the right type in memory: membership is what every question asks, and adding an id twice, which happens the moment you re-confirm a step, cannot duplicate anything. A set is also not a JSON type, so something has to translate on the way out, and sorted() does the translation and buys a stable file as well. Two runs that finish the same steps produce byte-identical JSON, so the file diffs cleanly and you can read it without a tool.

The temporary file and os.replace are there because of what this file is. It is the only record of an hour of physical work, and it gets rewritten seventeen times in an evening. Writing directly means the file spends a few milliseconds truncated each time, and a crash inside that window leaves nothing readable behind. os.replace is atomic on a single filesystem: the new file is complete before it takes the name, and the reader either sees all of the old one or all of the new one.

# labs/assembly_checklist.py — continued
def partition(steps: list[dict], done: set[str]) -> tuple[list[dict], list[tuple[dict, list[str]]]]:
    """Split what is left into steps you can do now and steps something else is holding up."""
    ready: list[dict] = []
    blocked: list[tuple[dict, list[str]]] = []
    for step in steps:
        if step["id"] in done:
            continue
        missing = [need for need in step.get("requires", []) if need not in done]
        if missing:
            blocked.append((step, missing))
        else:
            ready.append(step)
    return ready, blocked


def status(steps: list[dict], done: set[str]) -> str:
    ready, blocked = partition(steps, done)
    lines = [f"{len(done)}/{len(steps)} done, {len(ready)} ready, {len(blocked)} blocked"]
    for step in ready:
        lines.append(f"  ready    {step['id']}")
    for step, missing in blocked:
        lines.append(f"  blocked  {step['id']:<20} waiting on {', '.join(missing)}")
    return "\n".join(lines)

$ uv run python -m labs.assembly_checklist --status
2/17 done, 6 ready, 9 blocked
  ready    mount_pi
  ready    mount_pca
  ready    mount_eye_pan
  ready    mount_elbow
  ready    mount_audio
  ready    mount_adc
  blocked  mount_eye_tilt       waiting on mount_eye_pan
  blocked  mount_led_ring       waiting on mount_eye_tilt
  blocked  mount_wrist_gripper  waiting on mount_elbow
  blocked  cable_eye            waiting on mount_led_ring, mount_pi
  blocked  cable_arm            waiting on mount_wrist_gripper, mount_pca
  blocked  cable_audio          waiting on mount_audio, mount_pi
  blocked  cable_adc            waiting on mount_adc, mount_pi
  blocked  power_rail           waiting on cable_arm, cable_eye, cable_adc
  blocked  final_check          waiting on power_rail, cable_audio

Nothing in the program remembers that two steps are finished. It reads the file, then derives everything from the plan and that set: done by membership, ready by a prerequisite test, blocked by what fails the test and why. Six things you could do next is real information on a build with parts spread over a desk, and it is information a linear list cannot give you, because a list only knows what comes next in it.

# labs/assembly_checklist.py — continued
def walk(steps: list[dict], done: set[str]) -> None:
    """Offer every step whose prerequisites are met, in plan order, saving after each."""
    total = len(steps)
    for position, step in enumerate(steps, start=1):
        if step["id"] in done:
            continue
        missing = [need for need in step.get("requires", []) if need not in done]
        if missing:
            print(f"[skip] Step {position}/{total}: {step['id']} is blocked by {', '.join(missing)}")
            continue
        print(f"[{100 * len(done) // total:3d}%] Step {position}/{total}: {step['desc']}")
        print(f"       tools: {', '.join(step['tools'])}")
        if step.get("why"):
            print(f"       after: {', '.join(step['requires'])} — {step['why']}")
        try:
            answer = input("       done? [enter=yes  s=skip  q=quit]: ").strip().lower()
        except (EOFError, KeyboardInterrupt):
            answer = "q"
        if answer == "q":
            print(f"\nstopped at {len(done)}/{total}. Run again to pick this up.")
            return
        if answer == "s":
            print(f"       skipped {step['id']}")
            continue
        done.add(step["id"])
        save_progress(done)
    remaining = total - len(done)
    print(f"\n{len(done)}/{total} done" + ("" if remaining else " — the body is assembled."))

$ uv run python -m labs.assembly_checklist --reset   # first evening; the PCA9685 is still in the post
progress cleared
[  0%] Step 1/17: Press four M2.5 brass standoffs into the base plate.
       tools: M2.5 driver, standoffs
       done? [enter=yes  s=skip  q=quit]: [  5%] Step 2/17: Bolt the MG996R shoulder to the base plate, heads underneath.
       tools: M3 driver
       done? [enter=yes  s=skip  q=quit]: [ 11%] Step 3/17: Seat the Pi 4B on the standoffs. Do not overtighten.
       tools: M2.5 driver
       after: standoffs, mount_shoulder — the tray covers the shoulder's four M3 heads
       done? [enter=yes  s=skip  q=quit]: [ 17%] Step 4/17: Mount the PCA9685 on its own standoffs beside the Pi.
       tools: M2.5 driver
       after: standoffs — it shares the base plate's standoff row
       done? [enter=yes  s=skip  q=quit]:        skipped mount_pca
[ 17%] Step 5/17: Drop the pan servo into the eye socket, horn centred.
       tools: M2 driver, servo horn
       done? [enter=yes  s=skip  q=quit]: [ 23%] Step 6/17: Screw the tilt bracket onto the pan horn.
       tools: M2 driver
       after: mount_eye_pan — the bracket bolts to the horn
       done? [enter=yes  s=skip  q=quit]:
stopped at 4/17. Run again to pick this up.

The --reset on that command threw away the two ids the persistence demo put on disk, which is the only honest way to start a real build after experimenting with the file. The flag itself arrives in the next stage, along with the argument parsing around it.

save_progress runs inside the loop, after every confirmation, and that single placement is what makes the whole thing survivable. Close the laptop, lose power, kill the terminal: the last step you pressed enter on is already on disk. Save once at the end instead and the program is a paper list with extra steps.

The percentage is computed before the current step is added, so it reports work finished and never work in progress. Step 4 shows 17 percent because three steps were done when it was offered. Skipping is a separate answer from confirming for a physical reason: a part that has not arrived is not an optional step, it is a step you will come back to, and marking it done to make the number go up is how a missing standoff becomes a mystery two weeks later.

# labs/assembly_checklist.py — continued
def main() -> None:
    parser = argparse.ArgumentParser(description="GLaDOS physical assembly checklist")
    parser.add_argument("--status", action="store_true", help="print what is done, ready and blocked")
    parser.add_argument("--reset", action="store_true", help="forget every confirmed step")
    args = parser.parse_args()

    steps = load_plan()
    problems = plan_problems(steps)
    if problems:
        print(f"plan is not buildable — {len(problems)} problem(s):")
        for problem in problems:
            print(f"  [x] {problem}")
        sys.exit(1)

    if args.reset:
        PROGRESS_FILE.unlink(missing_ok=True)
        print("progress cleared")
    done = load_progress()
    if args.status:
        print(status(steps, done))
        return
    walk(steps, done)


if __name__ == "__main__":
    main()

$ uv run python -m labs.assembly_checklist   # third evening, multimeter still packed
[ 76%] Step 14/17: Wire I2S BCLK/LRCLK/DIN to GPIO 18/19/21 and the mic USB through the grommet.
       tools: soldering iron, grommet
       after: mount_audio, mount_pi — both ends have to exist before the wire between them
       done? [enter=yes  s=skip  q=quit]: [ 82%] Step 15/17: Wire the MCP3008 to SPI4 on GPIO 4/5/6/7 and the divider taps to the rails.
       tools: multimeter
       after: mount_adc, mount_pi — both ends have to exist before the wire between them
       done? [enter=yes  s=skip  q=quit]:        skipped cable_adc
[skip] Step 16/17: power_rail is blocked by cable_adc
[skip] Step 17/17: final_check is blocked by power_rail

14/17 done

$ uv run python -m labs.assembly_checklist   # multimeter found
[ 82%] Step 15/17: Wire the MCP3008 to SPI4 on GPIO 4/5/6/7 and the divider taps to the rails.
       tools: multimeter
       after: mount_adc, mount_pi — both ends have to exist before the wire between them
       done? [enter=yes  s=skip  q=quit]: [ 88%] Step 16/17: Land the 5 V motion rail on the capacitor bank and tie every ground together.
       tools: crimper, wire stripper
       after: cable_arm, cable_eye, cable_adc — nothing gets a rail until its signal wire is dressed and anchored
       done? [enter=yes  s=skip  q=quit]: [ 94%] Step 17/17: Power disconnected: tug every connector, look for a strand touching the Pi.
       tools: flashlight
       after: power_rail, cable_audio — it is the inspection of everything above it
       done? [enter=yes  s=skip  q=quit]:
17/17 done — the body is assembled.

Skipping the divider wiring cost two more steps, and the program said so instead of letting you find out with a screwdriver. That is the whole return on the requires lists: the consequence of a skip propagates on its own, and the two lines it prints name the missing prerequisite, not just the fact that something is missing. The last step is gated behind every wiring step in the plan, which is deliberate. A visual inspection that happens before the last connector goes in has inspected a machine that no longer exists.