OpenPnP Fiducial Detection Failing: 5 Fixes That Actually Work

If OpenPnP can't find your PCB fiducials, the entire job halts. After running PikkoBot machines through hundreds of boards, these are the five fixes that resolve nearly every "fiducial not found" error.

1. The board surface is too reflective

Glossy soldermask reflects the ring light back into the camera, washing out the fiducial circle. The fix is mechanical, not software:

• Wipe the PCB with isopropyl alcohol to remove handling residue.
• If the board is glossy green or red soldermask, angle the ring light source slightly using a thin diffuser ring (printable in PETG, ~30° angle).
• Switch the top camera exposure down by 20-30% in Machine Setup → Cameras → Top Camera → Device Settings. The histogram peak should sit at roughly 60% brightness, not 95%.

A telltale sign of this issue: detection works at the corners of the board but fails near the center where the reflection is strongest.

2. The vision pipeline's blob detector thresholds are wrong

OpenPnP's default fiducial detection pipeline uses a BlobDetector stage with conservative defaults. For 1.0 mm copper fiducials on standard soldermask, those defaults work. For anything non-standard, they don't.

Open the pipeline editor: Job → PCB Fiducials → right-click a fiducial → Edit Pipeline.

Adjust these stages in order:

Stage	What to check	Typical value
ImageCapture	Camera selected = Top Camera	—
Threshold	thresholdValue matches your soldermask brightness	100–140 (green), 60–80 (red)
BlobDetector	minArea and maxArea bracket your fiducial size in pixels²	For 1.0 mm fiducial at 0.05 mm/px: ~400–2000
BlobDetector	minCircularity	0.85 (relaxed for matte boards)
MaskCircle	Search radius around expected position	20–40 px

After each change, click Process Pipeline with a still board image to see what survives each stage.

3. The camera is out of focus

The top camera's lens has a fixed focal distance set during manufacturing. If you've adjusted it for component vision (closer focus), fiducial detection at PCB height will look blurry, and BlobDetector will reject the soft edges.

Quick test:

1. Jog the top camera over a fiducial.
2. Watch the live feed — sharp edges or fuzzy?
3. If fuzzy, you have two choices:
   • Adjust the camera focus ring for fiducial height (loses sharpness for component pickup verification — usually not worth it).
   • Better: retune the BlobDetector minCircularity down to 0.7 to accept softer edges, and tighten MaskCircle to compensate for false positives.

4. mm/pixel calibration drifted

OpenPnP needs to know how many millimeters one camera pixel represents. If this value is wrong by even 5%, the search window in MaskCircle won't be centered on the actual fiducial position.

Recalibrate using a known reference — a fiducial that you measured with calipers:

1. Place the reference board at staging plate height.
2. Machine Setup → Cameras → Top Camera → Calibration → mm/Pixel Calibration.
3. Follow the wizard with the known fiducial diameter.
4. Save. Re-run fiducial detection.

Symptom that points here: detection finds something but it's offset from the actual fiducial by 1–3 mm consistently.

5. The fiducial is not where OpenPnP thinks it is

If you've imported a PCB but the fiducial coordinates in the PCB file don't match the physical board (e.g., wrong origin, mirrored design, or you flipped the board), OpenPnP looks in empty space.

Verify by:

• Opening the PCB file in OpenPnP and noting the fiducial X/Y.
• Manually jog the head to that coordinate.
• Look at the live camera feed. The fiducial should be roughly centered.

If it's off by exactly the board's width or height, you've got an origin mismatch. Re-export the PCB with the origin set to the bottom-left fiducial.

Quick checklist

When fiducial detection fails, run through this:

• PCB cleaned with IPA
• Ring light not pointing directly into the camera
• Top camera exposure not maxed out
• Vision pipeline Threshold and BlobDetector reviewed in the pipeline editor
• Camera in focus at PCB height
• mm/pixel calibration done within the last month
• PCB file coordinates verified against physical board

If you've ticked every box and it still fails, the issue is usually the soldermask itself. Try a different test board or a different fiducial shape (1.5 mm circle instead of 1.0 mm).

---

For machine setup that comes pre-calibrated for fiducial detection out of the box, see the PikkoBot JUKI config — it includes a tuned pipeline for standard green and black soldermasks. For hands-on testing of camera and lighting outside OpenPnP, use the PikkoBot Debug Tool.