Board Fiducials and the Fiducial Locator

Every fiducial check runs on a mark somebody chose, and on a machine you assembled yourself that somebody is you. Homing & Fiducial covers the 1 mm dot on the datum board, which sets the machine's XY datum once. This page covers the marks on your own PCB: how they are sized, where they go, and what each number in the Fiducial Locator does when a check fails.

Opulo's design guide for the LumenPnP platform asks for a 1 mm round copper pad with at least a 2 mm soldermask opening, three of them, at the outer edges of the board and as far apart as the design allows. KiCad ships that footprint as Fiducial:Fiducial_1mm_Mask2mm. A Vertex 4 places down to 0402 and takes boards up to 210 × 390 mm, so most of what people bring to it fits the same prescription.

What The Locator Solves For

The Fiducial Locator measures each marked placement, then solves an affine transform between board coordinates and machine coordinates. How much it can solve depends on how many marks you gave it:

• Two fiducials: location, rotation, and a single averaged scaling difference across both axes.
• Three fiducials: the same, plus separate X and Y scaling and axis non-squareness.
• More than three: the same estimates as three, averaged, which washes out measurement noise. Four or more is the recommendation.

Feed it fewer than two and it stops with The panel/board side contains only 1 placements marked as fiducials, but at least 2 are required.

Before measuring, OpenPnP plans the visit with a travelling salesman solve that starts at the current camera position and ends at the board origin, so the order the fiducials are checked in is not the order they appear in the placements list.

The Mark Itself Is One Round Pad

A fiducial is a Part with a Package, and the Package's footprint is what the vision system reads. Create it once per mark size:

1. Open the Package, go to the Footprint tab.
2. Leave Body Width and Body Length at 0. Only the pad definition is used, and a body box adds nothing the detector can work with.
3. Add one pad at X = 0, Y = 0, with Width and Length equal to the fiducial diameter and Roundness at 100%. A 1 mm round fiducial is a 1 × 1 mm pad at full roundness.
4. Create a Part for that Package, and assign it to each fiducial placement.

The locator takes the search diameter from the pad bounding box, using the larger of width and height. Then the stock pipeline builds a band around it: the DetectCircularSymmetry stage ships with an inner margin of 0.4 and an outer margin of 0.2, which works out to accepting circles from 60% to 120% of the footprint diameter. A 1 mm pad is therefore matched anywhere between 0.6 mm and 1.2 mm as seen by the camera. The stage also carries its own pixel clamps of 10 and 100 px, looks for one circle per pass, and scores candidates by ring variance.

Two boards with different fiducial sizes need two Parts and two Packages. The band is not wide enough to cover both.

The Five Numbers Behind A Check

Setting	Lives in	Stock value	What it decides
Pad diameter	Package footprint	1 mm for Fiducial:Fiducial_1mm_Mask2mm	Centre of the accepted diameter band
Max. Distance	Pipeline, maxDistance slider	4.0 mm, range 0 to 10	Search radius around the expected location
Max. Vision Passes	Fiducial Vision Settings	3	How many times the camera re-centres and re-measures
Max. Linear Offset	Fiducial Vision Settings	0.2 mm	Stops iterating once a pass moves the reading less than this
Scaling, shearing, board origin tolerances	<tolerances> in machine.xml	5%, 5%, 5 mm	Sanity limits on the solved transform

Two of these get misunderstood often.

Set Max. Distance to your mounting tolerance. If the board lands a couple of millimetres off when you drop it on the staging plates, the search radius needs to cover that. Too small and a hand-mounted board fails a check it should pass; too large and round holes elsewhere in the camera view become candidates, which the OpenPnP wiki warns about specifically for tented vias and mouse-bite holes. If your pipeline predates the slider (it arrived in 2.3), the locator logs Setting maxDistance override because this pipeline does not have a maxDistance stage and falls back to the value in machine.xml.

Max. Linear Offset is an exit condition. The loop stops as soon as a pass moves the reading less than 0.2 mm, and it will stop after 3 passes regardless. Treat 0.2 mm as the residual that can survive a check and plan the placement budget around it.

There is also an averaging switch, off by default. With it on, and at least two measurements after the first pass, the locator takes the arithmetic average of the matches and discards the first pass as the least reliable of the set.

Error Messages, Translated

• Fiducial FID1 does not have a valid part assigned. The placement exists but no Part is attached, so there is no Package to read a diameter from.
• Package FIDUCIAL-1X2 does not have a valid footprint. and Package FIDUCIAL-1X2 has an invalid or empty footprint. The Package has no pad, or the body dimensions were set with no pad definition behind them.
• Unable to locate FID1 on ftp.board.xml The camera reached the expected location, ran the pipeline, and found nothing inside the search radius. Either the mark was never in frame or the search radius is smaller than the mounting error.
• FiducialVisionSettings ReferenceNozzleTip N045 fidcuial vision settings Stock Fiducial Vision Settings are disabled. (The misspelling is in the source.) Tick Enabled.
• Fiducial locator results are invalid for ftp.board.xml because: the board origin moved 12.4121mm which is greater than the allowed amount of 5.0000mm, ... Potential remidies include setting the initial board X, Y, Z, and Rotation in the Boards panel; using a different set of fiducials; or changing the allowable tolerances in the <tolerances> section of the fiducial-locator section in machine.xml. That typo is also in the source. The failure means the solved transform is not plausible: scaling or shearing past 5%, or an origin that jumped more than 5 mm from where it was captured. In practice this is a board location that was never captured, and the remedies listed are the fix, in that order.

Reflective Fiducials And The Parallax Mode

HASL-finished marks are the awkward case. The solder coating edges round off under surface tension, the pad reflects the camera's own diffuser back at the lens, and the mark reads as partly dark or misshapen. Re-centering handles part of it, because when the camera sits directly over the mark the lighting is symmetric and any scale error cancels out around the circle.

When that is not enough, the locator has a parallax mode. It measures from two viewpoints placed symmetrically either side of the expected location and takes the midpoint, so the angled-view error cancels. Two numbers drive it:

• Parallax Diameter. Roughly half the diameter of the LED ring you are using. Camera and LEDs sit at about the same height, so light bounces back onto the board at the middle of that distance. The reflected band has to be wider than the mark for this to work at all.
• Parallax Angle. 0° favours X, 90° favours Y. Pick the faster axis of the machine, or jog the crosshairs to measure a specific pair of LEDs that reflects cleanly.

If the reflections are coming off the pad rather than worsening detection, the fix is mechanical: a thin matte solder coating, or an eraser on a HASL pad to knock the gloss down. The same reflectance problem from the other direction is covered in bottom vision on shiny parts.

Distance Between Fiducials Matters More Than Size

Rotation error scales with the perpendicular measurement error and inversely with the baseline you spread the marks across:

A 0.1 mm centering residual measured across a 100 mm baseline tilts the board 0.1 / 100 = 0.001 rad, or 0.057°. A corner 125 mm out from the rotation centre then moves 0.125 mm. Widen the baseline to 200 mm and the same residual tilts the board half as much and the corner moves half as far.

For scale, IPC-7351 hands an 0402 its whole placement budget of 0.1 mm, and the same rotation term eats into that budget on every part. That arithmetic is the reason to put the marks on the outer corners rather than tightening the diameter. The placement accuracy breakdown works through the rest of that budget.

Panels use the same rules in two stages. Outer panel fiducials are checked first for coarse alignment, and the inner board fiducials then for precision. Because the coarse pass has already taken up the mounting error, you can relax the keepout around tightly packed board fiducials, as long as you also shrink Max. Distance so the board locator never searches outside its own zone.

Verifying Instead Of Trusting

1. Home first. Steppers de-power when idle and lose position, so every job starts with a homing cycle. The datum mark OpenPnP creates for that cycle is a FIDUCIAL-HOME part that defaults to a 1 mm circular footprint, the same number you designed into the board.
2. Run the fiducial scan. The machine visits the marks, finds each centre, and adjusts the board for the angular offset it measures.
3. Check the result on a placement. Select any placement and use jog camera to position. If the reticle lands dead centre on the footprint, the transform is right. If it lands consistently off, the board location or the fiducial measurements moved.
4. Leave Check Fids? ticked in the Job tab so the job re-checks at the start of a run rather than trusting a location captured an hour ago.
5. Re-run the scan and compare. Two identical results mean the marks are being read consistently. A reading that drifts between runs points at the camera mount or at units per pixel rather than at the pipeline.
6. Look at what the detector saw. The stock pipeline carries two disabled debug stages named deb0 and deb1. Enable them and the run writes fidloc_source_ and fidloc_results_ images to the OpenPnP debug directory, which is faster than guessing about lighting.

A residual that is the same everywhere on the board and a residual that grows with distance from the origin are different faults, and the FAQ separates them. The configuration files themselves, including the machine.xml that holds the tolerance block, are covered in OpenPnP versus vendor software.

If there is genuinely no room for three 2 mm openings, the keepout can be relaxed. Watch what ends up next to the mark: a straight track will not be mistaken for a circle, but a tented via, a mouse-bite drill hole, or a track bend with a radius close to the fiducial radius can be. A board that cannot carry round marks at all can still use a board corner as its datum, since OpenPnP will take any feature that gives it both a position and an angle, but that feature then has to be re-captured after every flip.

Related: Homing & Fiducial, OpenPnP v4 Calibration, Bottom Camera Exposure.