OpenPnP Fiducial Detection Failing: 5 Fixes That Actually Work

Fiducial detection is the backbone of accurate placement. When OpenPnP can't find your board's fiducials, the entire assembly process stops. Before you blame the software, work through these five fixes in order—they resolve the vast majority of detection failures.

Fix 1: Adjust Camera Settings

The most common cause of fiducial detection failure is poor camera image quality. Fiducials are small (typically 1mm diameter pads), and the vision pipeline needs clear, high-contrast images to detect them reliably.

What to check:

• Exposure: Too dark and the fiducial blends into the board. Too bright and the reflective copper pad blows out, losing edge definition. Aim for a middle ground where the fiducial pad is clearly visible against the substrate.
• Gain: High gain introduces noise that confuses edge detection. Keep gain as low as possible while maintaining acceptable brightness.
• White balance: Consistent white balance ensures the vision pipeline sees consistent colors across sessions.

Diagnostic steps:

1. Open the top camera live view in OpenPnP
2. Place a test board under the camera
3. Navigate to a fiducial location manually
4. Adjust exposure until the fiducial pad is clearly visible with distinct edges
5. Run the fiducial detection test in OpenPnP

PikkoBot advantage: PikkoBot's camera system has pre-calibrated exposure settings for common fiducial sizes. The settings are stored per-board-profile, so switching between boards recalibrates automatically.

Fix 2: Check Fiducial Pad Size

OpenPnP's vision pipeline has a minimum fiducial size threshold. If your fiducials are too small, the detector won't find them.

Minimum recommended sizes:

• Diameter: 1mm (0.8mm absolute minimum)
• Annular ring: 0.2mm minimum around the pad
• Copper area: At least 0.5mm² visible copper

Common mistakes:

• Using fiducials from a library that specifies 0.5mm pads (too small for reliable detection)
• Fiducials placed near board edges where lighting is uneven
• Fiducials covered by solder mask overlap (check your Gerber output)

What to do:

If your fiducials are undersized, add larger ones to your PCB design. Most EDA tools have fiducial footprints in their libraries—use the 1.5mm or 2mm variants. Place at least 2 fiducials (3 is better for rotation compensation) in unobstructed areas of the board.

Fix 3: Improve Lighting

Ambient lighting is the enemy of consistent fiducial detection. A desk lamp, overhead fluorescent, or sunlight from a window can all create uneven illumination that defeats the vision pipeline.

Solutions:

• Ring light: A ring light mounted around the camera provides even, shadow-free illumination. This is the single most impactful improvement you can make.
• Light tent: For very consistent results, place the entire machine in a light tent that blocks external light.
• Light shields: Simple 3D-printed shields around the camera area can block stray light without enclosing the entire machine.

What to check:

• Is the ring light centered on the camera axis?
• Are all LEDs in the ring light functioning? (Dead LEDs create shadows)
• Is the ring light at the correct height? (Too close = hotspots, too far = insufficient illumination)

PikkoBot advantage: PikkoBot's integrated ring light system is designed specifically for fiducial detection. The 360-degree illumination eliminates shadow artifacts that cause detection failures on machines with single-point lighting.

Fix 4: Tune Vision Pipeline Settings

OpenPnP's vision pipeline is configurable. Default settings work for most cases, but edge cases require tuning.

Key settings to adjust:

• Detection threshold: Controls how much contrast is needed between the fiducial and background. Lower values detect fainter fiducials but increase false positives.
• Blur kernel size: Pre-processing blur that reduces noise. Too much blur hides fine fiducials. Too little blur amplifies noise.
• Edge detection parameters: The Canny edge detector's low and high thresholds affect which edges are detected.

Step-by-step tuning:

1. Open Machine → Vision → Fiducial Vision in OpenPnP
2. Load a test image of your board's fiducial
3. Run the pipeline and observe the detection result
4. If detection fails:
   • Check the pipeline debug output for which stage failed
   • Adjust the failed stage's parameters
   • Re-run the test
5. Test with 5-10 different board positions to ensure robustness

Common tuning scenarios:

• Fiducial detected but position is wrong: Usually a calibration issue, not a pipeline issue. Re-run camera calibration.
• Fiducial not detected at all: Check exposure and lighting first. If those are correct, lower the detection threshold.
• False detections (finding fiducials where there aren't any): Raise the detection threshold or increase the minimum fiducial size.

Fix 5: Clean the Camera Lens

It sounds obvious, but a dirty camera lens causes more fiducial detection failures than any software configuration issue. Dust, flux residue, and fingerprints scatter light and reduce contrast.

Cleaning procedure:

1. Power off the camera (or the entire machine)
2. Use a lens cleaning cloth (microfiber, not paper towels)
3. Apply a small amount of lens cleaning solution
4. Wipe gently in circular motions
5. Inspect with a bright light at an angle to check for remaining residue
6. Power on and test

Prevention:

• Cover the camera when not in use
• Keep the machine in a clean environment
• Avoid working with flux near the camera (flux fumes condense on optics)
• Clean the lens monthly as part of regular maintenance

The Diagnostic Flowchart

When fiducials won't detect, work through this order:

Fiducial detection fails
├── Clean camera lens (Fix 5)
│   ├── Fixed → Done
│   └── Not fixed → Continue
├── Check camera settings (Fix 1)
│   ├── Adjusted exposure/gain → Fixed
│   └── Settings look correct → Continue
├── Verify fiducial size (Fix 2)
│   ├── Too small → Enlarge fiducials in PCB design
│   └── Size adequate → Continue
├── Improve lighting (Fix 3)
│   ├── Add ring light → Fixed
│   └── Already have ring light → Continue
└── Tune vision pipeline (Fix 4)
    ├── Adjusted thresholds → Fixed
    └── Still failing → Check camera calibration

Time estimate: Working through all five fixes takes 30-60 minutes. Fix 5 alone (cleaning the lens) resolves about 30% of cases in under 2 minutes.

PikkoBot's Fiducial Vision System

PikkoBot's vision system is designed to minimize fiducial detection issues:

• Pre-calibrated camera settings: Stored per-board-profile, eliminating the need to adjust exposure for each new board design.
• Integrated ring light: 360-degree illumination designed for consistent fiducial detection across different board materials and finishes.
• High-resolution camera: Sufficient resolution to detect fiducials down to 0.8mm diameter reliably.
• Vision pipeline presets: Pre-tuned detection parameters for common fiducial sizes (1mm, 1.5mm, 2mm).

These features don't eliminate the need for proper setup, but they significantly reduce the time from unboxing to first successful fiducial detection.

Prevention is Better Than Debugging

The best fiducial detection fix is prevention:

1. Standardize fiducial size: Use 1.5mm or 2mm fiducials across all your designs
2. Use consistent placement: Fiducials in the same relative position on every board
3. Document your settings: Save OpenPnP board profiles after successful calibration
4. Maintain your machine: Clean the camera monthly, check ring light LEDs quarterly
5. Test before production: Always run fiducial detection on a fresh board before starting a batch

Fiducial detection is a solved problem—when the fundamentals are right. Clean optics, good lighting, proper fiducial size, and calibrated settings. Get these four things right, and detection becomes reliable and boring. Exactly what you want in production.

---

Related Documentation

For the complete calibration sequence (top camera, bottom camera, nozzles, and fiducials), see the OpenPnP v4 Calibration Guide.

New to PikkoBot? Start with the Getting Started guide.