STACKSPECT

A robotic arm that stacks pallets without tipping them over — and the instrumentation that proves it.

THEKER Robotics challenge · HackSpain '26

_{One episode, ×10. Truck source, empty pallet to full, nothing cut from the middle.}

A palletizing cell that closes the loop. The arm sees the package a source presents, picks it, weighs it in its own wrist, and only then decides where it goes — scoring every pose that fits by support, by trapped air, and by where it leaves the combined centre of gravity. Then it places it and watches the stack settle. Around it runs an observability platform, so that "is this commit better than the last one?" has an answer that is a number.

The cell runs — three sources, nine levels, a full 1200 × 800 mm europallet. What is not real is perception: the detector still reads the simulator's ground truth.

The work is on Simulation@dev — that repository's main is still the earlier skeleton, so links point at dev.

The scripted build existed so the platform received genuine episodes before anything could produce them for the right reasons. Simulation now sends the same rows for the right reasons, and the platform did not have to change to receive them.

Then. A Panda, a 210 × 140 mm model pallet, and a plan written by hand in YAML.

Now. A UR10e, a full europallet, and a plan nobody wrote down in advance.

sequenceDiagram
    autonumber
    participant SRC as Source
    participant EYE as Vision
    participant ARM as Arm
    participant PLN as Planner
    participant MSR as Measure
    participant TEL as Telemetry

    SRC->>EYE: presents one package, and stops
    EYE-->>ARM: Observation: pose, rough dims, confidence
    ARM->>EYE: picks it, then holds it plumb
    EYE-->>PLN: PackageSpec: dims, mass, CoG offset
    Note over EYE,PLN: measured AFTER the pick and BEFORE the plan
    PLN->>PLN: scores every pose that fits, 14 terms
    PLN-->>ARM: PlacementPlan: layer, slot, yaw, score
    ARM->>MSR: releases it, and the stack settles
    MSR-->>TEL: error, support, overhang, pallet CoG, margin
    TEL->>TEL: one row per package ATTEMPTED, written live
    MSR-->>SRC: next package

Measuring after the pick and before the plan is what forces the planner to be incremental: it cannot lay out the pallet in advance, because it does not know what the next package is until the arm is holding it.

Every stage shipped an oracle stub reading ground truth, so the loop could run end to end before any stage was real. Three of four have been replaced. A run is flagged oracle if any stub remains — so every run today is still flagged, honestly.

oracle is computed from which pieces were selected, never written by hand. The platform refuses to compare an oracle run against a measured one — that is exactly the comparison that would invalidate the work.

Universal Robots UR10e on a pedestal with an OnRobot VGP20 16-cup vacuum gripper — 1300 mm reach, 12.5 kg payload, a 2.55 kg tool, so 8.5 kg is the ceiling on a carton. The arm comes from MuJoCo Menagerie, but the kinematic chain is assembled in the repo rather than included wholesale, so the cell can be an industrial bay instead of Menagerie's empty floor.

Three sources, three tiers each — nine levels, declared in YAML, not in code:

A jam is reported as timeout, never as a source-specific failure: the vocabulary is closed and a source has no event of its own. Getting that wrong rejects the row and silently kills telemetry for the rest of the run.

Pick a level, press play, rewind. Two centre-of-mass markers, deliberately: the real ones MuJoCo integrates, and the ones the robot computed, error drawn between them. The mode selector is the part that matters — Execution calls the real entrypoint and may publish telemetry; Debug opens no episode and uploads nothing, and says so on its own badge. A demo that quietly writes to the production database poisons the benchmark it exists to show.

Nine levels × three seeds, on Simulation@dev at 6724d81, the real beam search (--beam-planner), --no-telemetry, measured off the simulator's own state.

Two columns because the arm has two honest modes, and conflating them would flatter it. In fast-forward it jumps between waypoints — release, settling and shake are simulated the same, the transit is not. With motion interpolated, every millimetre is integrated.

By tier, the shape is what you would want it to be — the easy levels are solved and the hard ones are the frontier:

Every failure came out of the closed vocabulary below. Not one run invented a cause.

The cell ships three, and the honest way to show what the search buys is to run all of them over the same nine levels and the same three seeds. The interpolated column is the one that counts — it is the one where the arm actually travels:

And the reason to distrust fast-forward is in the gap between the two modes. In fast-forward the grid baseline looks like the best of the three — 160 of 165 packages, more than the beam search places. Let the arm actually travel and it loses 70 of them. A planner that only stacks well when nothing is allowed to disturb the stack has not solved the problem; it has solved a picture of it.

The beam search pays for its completion rate in two places, and both are visible above: it places a little less precisely (3.1 mm mean against the heuristic's 2.6) and it rests fewer packages on solid ground (66 % against 73 %), because it deliberately bridges gaps the heuristic refuses. It also runs a tighter worst-case margin, +47 mm against +53 mm. Never negative, in any planner, in any mode.

Five commits back, at ebad291, the conveyor did not hand the carton over properly: the station sat at the downstream lip, so a carton stopped with 40 to 205 mm of it in the air. Running the beam search at both commits, same levels, same seeds, isolates what that cost:

Thirteen more packages survive to the end of an episode, and the worst landed placement on the page went from 16.0 mm to 5.1 mm. tests/test_cell.py now asserts every belt delivery lands fully supported, so the mechanism cannot come back unnoticed.

What real transit still costs is visible in the same table, and it is worth saying plainly. Between the two arm modes the beam search loses 3 episodes and 17 packages, its mean placement error loosens from 2.5 mm to 3.1 mm and its worst case from 5.1 mm to 9.7 mm, and every one of its five interpolated failures but two is a stack_collapse. The belt is no longer the cause of those; the remaining collapses are on table and truck levels. Moving the arm for real is still the hardest thing the cell does — it is simply no longer the belt's fault.

The baseline it had to clear — the scripted predecessor

Overhead — fill, overhang and CoG live in this view

Elevation — flatness and layers live in this one

10 boxes, 2 layers, a 210 × 140 mm pallet — a 1:5.7 model of a Euro pallet, because the Panda's gripper opens 80 mm and a real pallet is ungraspable. No planner earned this plan: which box goes where is written out in configs/pallet.yaml.

Placed	10 / 10
Placement error, mean · max	2.6 mm · 5.7 mm
Flatness of the top layer	0.1 mm
Maximum overhang	0.2 mm
CoG to the pallet centre	2.2 mm
Stability margin at the end	+58 mm
Pallet fill	77 %
Duration	204 s simulated

That was the floor to clear, on a puzzle solved by hand, off-line, knowing every box in advance. The planner has none of that — and on a pallet more than thirty times the area it holds the same millimetre-scale placement error and a margin that has not gone negative in 288 measured placements.

A pallet that is full is not a pallet that is good. What decides whether the load survives the forklift is where the combined centre of gravity sits relative to the stack's support polygon — a number that moves with every single box:

stability_margin  =  distance from the CoG to the nearest edge of the support polygon
                     negative  ->  it tips over

stability_margin and support_polygon are imported from the telemetry SDK and never reimplemented. A third copy would eventually disagree with the one the interface draws.

flowchart TB
    PANEL["control panel<br/>stdlib HTTP + SSE"] -. "execution / debug" .-> CELL
    subgraph CELL["THE CELL - Simulation@dev"]
        direction LR
        SRC["source<br/>table · conveyor · truck"] --> P["perceive<br/>STUB"] --> G["gauge<br/>wrist, in hand"] --> D["decide<br/>14-term score"] --> E["execute<br/>UR10e · VGP20"] --> S["settle<br/>measure"]
    end
    CELL == "episodes · placements · pallet states · events" ==> SDK
    subgraph TEL["TELEMETRY"]
        direction LR
        SDK["theker_telemetry"] --> DISK[("episodes.jsonl<br/>source of truth")]
        SDK --> DB[("Supabase<br/>Postgres · RLS · Realtime")]
    end
    DB -- "realtime" --> LIVE
    DB -- "SQL views" --> RUNS
    subgraph PLAT["PLATFORM"]
        direction LR
        LIVE["Live<br/>working right now?"]
        RUNS["Dashboard · Runs · Episode<br/>better than last commit?"]
    end
    style P stroke-dasharray: 6 4

The dependency runs one way only. The cell imports the telemetry SDK; the platform does not know MuJoCo exists, so rewriting the simulation never takes observability down with it. The jsonl on disk stays the source of truth: if the venue wifi dies mid-demo, the benchmark keeps running.

The same rule holds one level down: the placement heuristic imports numpy and nothing else, enforced by an assertion rather than by convention — the self-check's very first test is that no heavy module has crept into sys.modules. That is what lets the weights be tuned in milliseconds instead of minutes, and one convenience import would end it.

Four screens over the same pallet drawing; what changes is which episode it points at.

A pretty chart built on an invalid delta is exactly what a demo must not produce — hence the refusal below, in red, instead of a plausible-looking comparison.

_{Captured at 1440 px from real runs; both screens follow your theme, and so do the images. The interface is in Spanish.}