EEPROM calibration write failed: fix your stereo camera board first

The capture looked fine: the dataset folder filled with board pairs, the solver ran to the end, and the run still died on a banner reading EEPROM write failed, with a number where the calibration should be. The banner misleads. The memory is almost never the fault — the tool computed a calibration, measured its epipolar residual, found it above the gate its release enforces, and refused to flash. Here you will read that residual correctly, price it in depth error, and fix the two capture defects that push it up: target quality and pose coverage. You finish able to tell a ten-minute board rebuild from a firmware version case that belongs with the vendor.

What the refusal actually means

A stereo depth camera keeps its calibration in a small EEPROM on the camera board: intrinsics for each imager, distortion coefficients, and the rotation and translation between the two imagers. Depth is computed from those numbers at every power-on, so the write path is guarded. When the solver finishes, the utility measures the result's epipolar residual: after rectification, a matched corner in the left image must sit on the same image row as its partner in the right image, and the residual is the mean distance from that row, in pixels. If the residual exceeds the limit compiled into that release, the utility refuses to flash and prints the number with a prompt to recalibrate.

A refusal at 0.14 px therefore pins that release's gate below 0.14 px. The same run saved its dataset without complaint because capture, solving and writing are separate stages — images on disk prove the capture worked, not that the calibration passed. Open the saved pairs before recapturing anything: glare, blur and a board parked in the centre of every frame are visible at a glance.

Keep one other failure apart. An OpenCV assertion reading !_src.empty(), raised by a colour-conversion call such as cv2.cvtColor, means the frame grab returned an empty image — the device was not streaming, or the wrong stream handle reached the call. That failure happens before any calibration math and has nothing to do with the EEPROM.

Price the residual in depth error

An epipolar residual and a disparity error are first-order cousins: a rectification offset of Δd pixels biases disparity by about the same amount, and stereo depth error follows.

Example geometry, chosen to match a compact stereo head: 1,280 px wide images, 70° horizontal FOV, 7.5 cm baseline. The focal length is f = 1280 / (2 × tan 35°) = 1280 / 1.4004 = 914 px, so f × B = 914 px × 0.075 m = 68.6 px·m. Three points on the scale:

• 1 px at 0.5 m: 0.25 m² / 68.6 px·m = 3.6 mm of depth error
• the refused run's 0.14 px at 1.0 m: 1.00 m² × 0.14 / 68.6 px·m = 2.0 mm
• 1 px at 1.0 m: 1.00 m² / 68.6 px·m = 14.6 mm

The decision: aim at 0.1 px, and treat any rebuild above 0.2 px as a capture defect still in place rather than a number to retry. Rerunning the same board under the same light reproduces the same residual; only a changed capture moves it. The gate sits below what the depth arithmetic alone demands because the residual also guards rectification across the whole frame — reprojection residuals are a second, related number, with their own targets in camera calibration residual values: average and max.

Cause 1, and the usual one: the board

Start with the target, the one part you can inspect with your eyes and a ruler. Two defects lead the list: gloss and warp. A glossy surface throws specular highlights that saturate marker corners exactly where the detector needs sub-pixel precision, so corners drop out or bias. Print matte: plain 160-200 gsm paper beats glossy photo stock, and matte photo paper beats both. When boards refuse to detect at all, the lighting and focus fixes for undetected calibration boards apply to ChArUco unchanged.

Warp does larger damage. At 0.5 m working distance, one image pixel spans Z / f = 0.5 / 914 = 0.55 mm on the target, so a 0.5 mm dent — exactly what glued-on cardboard produces while the glue dries — moves a corner by about 0.9 px, six times the residual you are trying to beat. Mount the print on rigid, flat stock and hold flatness to better than 0.5 mm across the pattern. How many squares the target needs for your standoff is its own calculation: the calibration target size guide sizes it.

Check print scale while the ruler is out. Measure ten squares edge to edge: a 24.5 mm design must read 245 mm, and a print that grew 2% reads 250 mm. Enter the measured size, not the nominal one — a grid pitch that disagrees with the print inflates every fitted parameter, as the grid-pitch calibration error fix works through.

A flat monitor removes warp entirely and makes the fastest diagnostic: if the write passes with the target on screen and fails with your board, the board was the defect. Keep brightness moderate, switch off night-mode and blue-light filters that grey the whites, and shoot with a short exposure so no refresh band lands in the frame.

Cause 2: pose coverage

The solver can separate focal length, distortion and the stereo rotation only from varied poses. Cover the frame: centre, all four corners, every edge, tilted about 30° in both axes, at two or three distances across the working range. Twenty to forty clean pairs is the working range, and forty blurred pairs measure less than ten sharp ones. A capture that stalls waiting for more frames is reporting a missing region — the board-coverage fix for a stalled calibration maps which regions to shoot.

Blur is the quiet contributor. Hold the board still for each pair and lock the camera on a camera stand so the only moving part between frames is the board; stands and stages for exactly this sit in the accessories finder. Set the standoff on purpose rather than by habit — the 3D camera working distance and positioning guide plans it.

The rewrite sequence

1. Print the target matte on rigid stock, flat to better than 0.5 mm, or bring up the monitor.
2. Measure ten squares edge to edge and enter the measured size in the unit the argument expects — 245 mm across ten squares means 24.5 mm each.
3. Capture 20-40 pairs: centre, corners, edges, ±30° tilt, two or three distances, camera locked on the stand.
4. Read the residual at the end of the run. Goal 0.1 px; above 0.2 px, change the capture and reshoot — do not rerun the same set.
5. Write, then read the calibration back and check the stored left-to-right translation against a caliper measurement of the mechanical baseline. The bar is agreement within about 1%: 7.508 cm stored against a 7.5 cm mechanical nominal is 0.08 mm apart and passes.
6. Validate depth on a flat plate and quantify the edge error with the flat-plane distortion check — a calibration that passes its gate can still tilt if the board was bowed one way.

When the residual is clean and the write still refuses

A rebuild that lands far under the gate — 0.05 px, say — and still refuses moves the suspect from capture to versions. The write routine lives in the calibration utility and talks to the device firmware; when a release renames or reworks that routine, a current utility fails against older firmware and the other way round. Update utility and firmware together from the vendor's current release, start the device from a known state as the flaky-test known-state guide describes, and rerun the sequence. A second identical unit settles it faster than any log: the same bench writing cleanly on unit two sends unit one to support.

A successful write followed by nonsense depth, or stored values that go stale across power cycles, points at corruption rather than rejection. That is a different repair — the stereo camera EEPROM recovery procedure walks the recover-and-recalibrate path.

Prevention checklist

• Board: matte print on rigid stock, flat to better than 0.5 mm — gloss and dents bias corners by up to a pixel.
• Board: measured square size entered, not nominal — print scaling shifts every fitted parameter.
• Capture: camera locked on a stand; only the board moves between pairs.
• Capture: 20-40 pairs across centre, corners, edges, ±30° tilt and two or three distances.
• Capture: short exposure, still board, no glare — reject any pair you would not annotate by hand.
• Write: residual goal 0.1 px; investigate above 0.2 px instead of retrying the same set.
• Write: read-back check — stored baseline translation within 1% of the caliper measurement.
• Records: log utility and firmware versions with the calibration date; the version path is invisible months later.

The decisions, and where to go next

Three cases cover the banner. A refusal with a residual above 0.2 px is a capture problem, and the board is the first suspect: rebuild matte and rigid, recapture with full coverage, expect about 0.1 px. A refusal with a clean residual is a version problem: update utility and firmware together, and retest on a second unit. A read-back full of garbage is corruption: run the recovery path. The 3D topic hub collects the surrounding guides — target sizing, residual targets, working distance — and the 3D sensor finder filters stereo, structured-light and profiler sensors by type when the head itself is due for replacement. The system configurator plans the stand and staging around whichever sensor you land on.