soldermaskdocs

Placement and routing

This page explains how the placer arranges parts, how the router joins them with copper, and how ground is poured over both layers.

Placement

The placer is a simulated anneal. It moves one part at a time and keeps a move that lowers the cost. While the anneal is hot, it sometimes keeps a move that raises the cost, so it can climb out of a poor arrangement.

Each build anneals six placements. Lightcycle, the default router, routes all six and puts them in order by what it laid. If none reaches every pin, three more are annealed, routed and ranked with them. The build then tries them in that order, up to three.

Under the A* router nothing is routed to rank them. On an unpoured two-layer board the routability model orders them. On a poured or four-layer board an analytic congestion score orders them, and ties go to the placer's cost.

Under the command line and the app, the anneals run at once, one per core.

What the cost charges

TermCharge
WirelengthThe half-perimeter of each net's pins, in mm. A ground net counts a quarter.
Copper on copper4000 per mm² of overlapping pad copper: a short
Body on body400 per mm² of overlapping body: two parts in one space
Courtyard on courtyard20 per mm²: advice, since people butt passives together
Air between partsEach courtyard grows 0.25 mm a side before overlap is measured, so parts sit 0.5 mm apart
Decoupling2 per mm when a capacitor sits more than 2.0 mm from the pin it serves
ESD4 per mm when an ESD part sits more than 3.0 mm from the connector pin it guards. A two-pin TVS on a supply guards that supply.
Edge pull8 per mm between a connector or an antenna module and the nearest edge. A part the design puts at an edge is pulled to that edge instead.
The back of the board4 per part on the back, and 1 per net with pins on both sides (a quarter for ground)
An antenna's keepout4000 per mm² of copper and 400 per mm² of body inside it, on either side
An area the design asked to keep clearThe same as an antenna's keepout

A decoupling capacitor or a crystal and the chip it serves count as one unit. They keep their real courtyards, so the air does not push them apart.

Three more terms exist and are off by default:

  • a crystal near its clock pins
  • a ring of room around fine-pitch chips
  • a pad no track can reach, beside another part's mounting hole (see Pads beside a hole)

How the anneal moves

  1. Parts start on a coarse grid. One of the six may start from a precedent instead.
  2. Each move picks one free part and does one of four things:
    • turns it by 90, 180 or 270 degrees (15% of moves)
    • swaps it with another part on the same side (10%)
    • flips it to the other side (10%, only when the back is in play)
    • nudges it (the rest)
  3. A nudge is a random step whose size is the current temperature. The temperature cools from half the board's longer side to 0.02 mm.
  4. A board gets 8,000 moves per free part, at least 20,000 and at most 1,000,000.
  5. After the anneal, the whole placement slides to the centre of the board. This is a rigid move, so wirelength and overlap do not change.
  6. Connectors and antenna modules are then seated at their edge, and any part the design puts at an edge is seated at that one.

Parts stay 1.5 mm inside the edge. A connector or an antenna module sits flush with it instead, and a connector's courtyard may pass the outline.

The anneal is seeded. The same design, pins and seed always give the same placement. The anneal also has a compiled core in Rust (mould/src/anneal.rs), which gives the same placement as the Python loop, bit for bit.

The placer's report is cost, worst_overlap_mm2, off_board_mm, antenna_copper_mm2 and clean. A board with areas kept clear adds keepout_mm2. The command line prints it.

Settings

SettingDefaultWhat it does
--seed / rules.seed1The anneal seed
constraints.board.sides21 keeps every part on the front
SOLDERMASK_SPACING_MM0.5The air between parts. 0 packs courtyards together; auto works it out from the board's room.
SOLDERMASK_MOVES_PER_PART8000Moves per free part. 0 gives a fixed 20,000.
SOLDERMASK_ROT36010 keeps every part at 0 or 90 degrees
SOLDERMASK_SWAP_P0.1The share of moves that swap two parts. 0 turns swaps off.
SOLDERMASK_SIZE_TARGET0.45Cuts a roomy board down until its parts cover this share, at most 0.45. 0 keeps the design's size.
constraints.board.sizebalancedcompact or roomy. See When the board is too big.
SOLDERMASK_ANNEALautoauto runs the compiled core when it is built. python forces the Python loop. rust fails if the core is not built.
SOLDERMASK_ANNEAL_WORKERSOne a coreHow many anneals run at once. The library alone runs one.
SOLDERMASK_ANTENNA_KEEPOUT10 stops the placer charging for parts under an antenna
SOLDERMASK_ESD_W4The ESD term's weight per mm. 0 turns it off.
SOLDERMASK_FINE_RING_MM0 (off)The ring of room around a chip whose pads are 0.55 mm apart or less, in mm
SOLDERMASK_PADACCESS_W0 (off)Weight charging a pad no track can reach. 20 turns it on. See Pads beside a hole.
SOLDERMASK_PRECEDENT / --no-precedenton0 lists precedents but never starts an anneal from one
SOLDERMASK_PRECEDENT_BAR0.6The score a precedent needs to start an anneal

Configuration lists every environment variable.

Pinned parts

A placement can be an input. A keyboard's switches sit on 18 mm centres, and a connector may have to sit over a hole in the case. Parts pinned in constraints.pinned, or dragged in the workbench, stay where they were put.

  • A pinned part is never moved, turned, centred or seated at an edge.
  • It still counts in the cost, so the free parts are placed around it.
  • With every part pinned there is one placement. The model still rates it.
  • A route of a fully pinned board goes into the corpus marked as pinned.

Antenna keepouts

A radio module's footprint shows where its antenna is: the body reaches past the pads on one side. That stretch, the full width of the body, is a copper keepout on both layers.

  • The router keeps copper out of it, and the KiCad board carries it as a rule area.
  • The placer charges any part inside it, on either side of the board.
  • Edge seating never brings an antenna over a part, and centring never moves a part under one.
  • The board's notes say what was kept clear, for example the 19.0×7.1 mm past its pads on the side it faces.
  • A part left with copper in the zone is a gap naming the part, its side and its pads.

When there is no keepout

A module whose footprint does not show which way it faces gets no keepout, and a note says so. Connectors and chips get none. A module whose antenna is a trace on its own board, such as a Raspberry Pi Pico, also gets none.

Pads beside a hole

A pad can sit inside the keep-clear band of another part's mounting hole. No track can then end on it, and the router reports the pad as bound. The pad-access term charges a placement for each such pad. It is off by default. Set SOLDERMASK_PADACCESS_W to 20 to turn it on.

What it checksHow
A netted padA grid of sample points over the pad's access area, which is the copper grown by half the narrowest track
Another part's holeThe clearance the router holds: half the drill, plus 0.25 mm, plus half the track
The edgeThe 0.30 mm edge band, counted only beside a hole
  • The charge starts when half the sample points are blocked and reaches its full weight when all are.
  • A part's own holes never charge its own pads.
  • A board with no hole on any part is not affected.
  • The compiled core and the Python loop give the same cost.

What it does not cover

Declared keepouts are charged already, and the term does not model nets wider than the narrowest track. About one part in six cannot be freed by moving it, so some pads stay bound. The CHANGELOG holds the measurements.

Parts at an edge you choose

You can name the edge a part goes on without fixing where along it. List the part under edges in the design's constraints, with left, right, top or bottom.

  • The anneal pulls the part to that edge, whatever kind of part it is.
  • After the anneal, the part is seated flush with that edge. A connector is turned to open off the board.
  • If the part cannot be seated where the anneal left it, it slides along the edge to the nearest room. A note says how far.
  • Centring never slides it off that edge.
  • A part that is not at its edge is a gap. So is a connector at its edge that cannot face out, and a named part the board does not have.

A pinned part keeps its pin. If the pin is not at the named edge, a gap says the pin won.

Areas you keep clear

You can ask for rectangles of the board to stay bare, for a standoff, a heatsink or a label. List them under keepouts in the design's constraints. See design.json.

Each rectangle is kept clear on every copper layer, the inner planes included.

  • The placer charges any part inside it, on either side, as it charges one under an antenna.
  • The router lays no track or via there.
  • The pour does not fill there, and no stitching via goes there.
  • The KiCad board carries it as a rule area that refuses tracks, vias, pads and pour.
  • The notes say what was kept clear.

A part the placer could not clear, or one you pinned inside, is a gap naming the part and the rectangle. If its pads are inside, KiCad's DRC counts them as errors and the verdict fails.

When the board grows

A rectangle keeps its coordinates from the board's lower-left corner. If the placer grows the board, the rectangle does not move with the middle. The sizer never cuts the board smaller than a rectangle reaches. Set board.fixed to keep the size.

Mounting holes

Ask for mounting holes and the build drills them at the board's corners, one a corner. Set board.mounting_holes in the design's constraints, or say "mounting holes" in the prompt.

ValueHoles
trueFour M3
2Two M3, on a diagonal
{"count": 3, "screw": "M2.5"}Three M2.5
ScrewHoleCircle kept clear
M22.2 mm4.4 mm
M2.52.7 mm5.0 mm
M33.2 mm6.4 mm
M44.3 mm8.0 mm

Each hole is drilled and not plated. A square round it, the clear circle plus 0.25 mm a side, is kept clear like any area you keep clear. Parts, tracks, vias and the pour stay off it.

The holes follow the corners when the sizer grows or cuts the board. The sizer counts their squares as used area, and keeps each side long enough for two. A board too small for them gets no holes, and a gap says why.

A prompt can name a count and a screw, such as "two M2.5 mounting holes". "Standoff voltage" and "Cortex-M3" are not read as holes.

Both sides

A surface-mount part may go on the back when the front is out of room and the board cannot grow.

  • Who may go: any surface-mount part except connectors, switches, LEDs, displays and modules. Those stay where a person can reach them.
  • When: only when the parts cover more than 45% of the front and the board cannot grow. That is a fixed outline, or a board already at 150 mm a side. On a board with room, the anneal never offers a flip.
  • What it costs: see the cost table above. The charge keeps parts on the front unless the back saves an overlap.

A part on the back is its footprint mirrored about its own vertical axis, then turned by its angle. Every writer and reader uses that one convention: the router, the DSN, the KiCad board, the Gerbers and the assembly file. The notes name the parts on the back and say assembly is two-sided.

When the board is too small

The design picks the board's size before any footprint is known. If the parts cover more than 45% of the board, the board grows until they cover about 35%, up to 150 mm a side. A note says how much it grew. A board grows before any part goes on the back, because two-sided assembly costs JLCPCB's Standard service. A board with a fixed outline is not grown. Its parts may go on the back instead, and the note says so.

When the board is too big

The design's guess can also be too generous. The sizer cuts a roomy board down until its parts cover about 45% of it, near what people's boards carry. constraints.board.size sets how tight:

board.sizeThe board is cut when its parts cover underDown toA prompt that sets it says
compactabout 40%45%"as small as possible", "a tiny board"
balanced (default)about 34%45%nothing about size
roomyabout 26%35%"leave room around the parts", "spread the parts out"

A tighter board may need more vias. On the 60-design suite every board passed cut to 45% and cut to 35%. At 45% the cut boards carried 16% more signal vias than uncut. At 35% the via count did not change. compact has not been measured on its own.

The cut keeps the board's shape and rounds up to whole millimetres. It stops at the first of these:

  • the largest part, with 1.5 mm to spare on each side;
  • enough edge for the connectors, which may line up to half the perimeter;
  • every pinned part and keepout, which keep their coordinates;
  • 10 mm a side.

A note names the old size, the new size and what stopped the cut. A size somebody chose is kept instead, and the note says what the board would have been. The sizer keeps:

  • board.fixed in the constraints;
  • a size in the prompt, such as "a 50x30mm board" or "an Arduino shield";
  • board.size_asked in the design;
  • a board that carries mains, because nothing here checks the isolation gap a smaller board narrows.

A board carries mains when a net is declared above 60 V or a part says mains. The prompt counts too, when it mentions mains, a mains voltage or isolation.

An imported board and a placement handed in whole keep their own outline. SOLDERMASK_SIZE_TARGET=0 turns the sizer off.

Routing

Lightcycle lays the copper by default. The A* router goes first when a board names it. Routers explains each one and how to choose.

The rule a board is routed at

RouterTrackClearance
Lightcycle (default)0.127 mm0.127 mm
A* router0.127 mm0.127 mm

Vias are a 0.60 mm pad on a 0.30 mm drill.

Both routers route at the fab's floor of 0.127 mm, so no part pulls the clearance lower. Two of one part's own pads may still sit closer than that. That is the vendor's land pattern, which no placement or route can change. The verdict sets it aside, and the fab rules check says whether JLCPCB makes pads that close.

The rule is stored in board.json under routing.clearance_mm, in the corpus label, and in the .kicad_pro. So KiCad's DRC judges the board against the rule the router was given.

Escape stubs

A pad whose neighbours sit at the rule leaves a track room only on its own centre line. Lightcycle's 0.05 mm grid seldom lands there. So the build lays a straight escape stub, up to 1.5 mm long, out of each such pad first.

  • The stub is copper of the pad's net, and the route reaches the net at its far end.
  • Only a board Lightcycle routes first gets stubs. The A* router finds its own way out of a pad.
  • Stubs go down when the attempt loop routes a placement. The pass that ranks the six routes without them.
  • The notes say how many pads got a stub.
  • SOLDERMASK_ESCAPE=0 turns them off.

Track widths

  • A net that declares a current (current_a) gets the width IPC-2221 asks for, at a 10 °C rise on 1 oz copper. A 2 A rail gets 0.78 mm.
  • Every other net uses the router's track.
  • A floor you set (constraints.rules.min_track_mm) widens every net, and never narrows one. The notes say how many nets it widened, and warn where a track would overhang its pad.
CopperCarries at a 10 °C rise
0.127 mm track0.54 A
0.15 mm track0.60 A
0.25 mm track0.87 A
One 0.30 mm via1.9 A

What the build checks after routing

  1. Connectivity. The build walks the copper and names every pin a net never reaches, for example GND misses J1.B1.
  2. Retries. If a net is incomplete, the router tries the next placement, up to three. The build keeps the one with the fewest incomplete nets, then the fewest violations, and says which.
  3. Vias. via_report() compares the vias on each net with the current the net declares.
  4. Widths. width_report() flags any wire narrower than its net asked for, in amps: VBUS declares 2A and that copper carries 1A at a 10C rise.
  5. Heat. Each run narrower than its net asks is judged at the declared current. A 20 °C rise is a gap, and 100 °C fails the board. See Copper too narrow for its current.

Under the command line and the app, on a machine of 32 cores or more, the three placements are routed at once. Each runs in a process of its own, and the rest are stopped once one comes back clean in rank order.

Datasheet layout rules

A part's datasheet often says how to lay it out. The build checks a small set of those rules and reports them as advice.

FamilyWhat it checks
DecouplingEach supply pin the rule names has a capacitor within the limit
Switcher input capacitorThe distance from the input capacitor to the supply pin
Exposed padThe vias in a thermal pad. A part marked "no solder" is never flagged.
Capacitor pathNo via between a bypass capacitor and its chip
  • Each line gives the measured value, the limit, where the limit came from, and the datasheet's quote and page.
  • A datasheet rarely gives a distance. Most limits are what people's boards do or a pipeline default, and the line says which.
  • A rule is checked only when its quote and its numbers passed an audit. A part with no rule gets no line.
  • The lines are advice. They never change the verdict or the gaps.
  • SOLDERMASK_LAYOUT_RULES=0 turns the check off.

Placement-only boards

On a board with no copper yet, only the checks geometry allows run. The rest read not checkable.

When no router is installed

If the chosen router is not installed, the other one routes the board and the gaps say so once. If neither is installed, the board is placed and not routed.

A board with no router

The gaps read no router is installed: the board is placed and not routed (soldermask setup). Run soldermask setup to install Lightcycle, or soldermask setup --astar for the A* router. See Routers for what each needs.

Tracks and the corners on them

A router returns segments, not tracks. fillet.chain() joins them back into tracks, grouped by net, layer and width, and stops at a T. That moves no copper.

fillet.round_corners() then replaces each 45° corner with an arc that meets both segments smoothly. The radius is three track widths, cut down to fit: no corner may use more than half of the shorter segment beside it.

Each arc is a real arc everywhere it is written:

OutputHow the arc is written
.kicad_pcbAn (arc (start) (mid) (end)) track
GerberG75/G02/G03 circular interpolation
2D viewAn SVG A command
3D viewA tessellated curve

Two guards keep an arc from breaking the board:

  • Clearance. Each arc is checked against other nets' pads, tracks, vias and the board edge. The radius shrinks until it clears, and the corner stays sharp if nothing fits.
  • Contact. An arc must still touch every pad, via or track of its own net that the sharp corner touched. If it would not, the radius shrinks the same way.

The pour's DRC runs on the rounded copper, so the copper that passes is the copper that ships. fillet.paths_for() is the one call every writer makes, so they all round the same corners.

The corpus keeps square corners

Only the three paths that write the board a person receives round its corners. Labelling and experiment paths keep the router's own geometry, so no corpus label moves.

Copper you drew yourself

A track drawn in the workbench is a constraint, the way a pinned part is. It is stored in constraints.tracks and constraints.vias. Lightcycle keeps it as drawn and routes around it. The A* router cannot take it, so Lightcycle routes such a board even when the A* router is named.

  • A hand route that reaches both pads finishes the net.
  • A hand route that stops short is a start. The router completes the net around it.
  • The build's notes count the hand-drawn tracks on the board. The gaps list names any that did not come back.

A precedent

Before annealing, soldermask/precedent.py looks for a corpus board with the same parts. The corpus is indexed by tools/annotate_boards.py into .cache/boards/annotations.jsonl.

  1. Each part of the design is paired with a part of a candidate board. A shared part number counts first, then a family (an LDO, an ESP32), then a footprint.
  2. A board scores on how much of the design it covers and how much of it the design uses. So a breakout beats a larger product that happens to contain it.
  3. A precedent that scores 0.6 or more, and carries every chip of the design, starts one of the six anneals.
  4. That anneal begins from the precedent's placement, scaled to this board's outline, at a quarter of the usual temperature. The other five start on the grid.

A precedent is a start, not a pin. Its anneal is ranked with the rest, so a precedent that places badly loses to a plain anneal. A part you pinned stays pinned.

The board says what happened. A note names the precedent, its repository and licence, and how many parts it explains. board.json lists the ranked precedents under precedents, and the workbench shows them under Precedents. With no index file, the build runs as if precedents did not exist.

A ground pour

Every board with a ground net of two or more pins pours ground over both outer layers. soldermask --no-pour routes ground as traces instead.

  1. Ground leaves the router. The router gets the netlist without ground. The ground pads stay on the board as copper to keep clear of.
  2. Stitching vias go in. Vias on a 6 mm grid tie the front pour to the back one.
  3. KiCad fills the pour. The KiCad board gets a zone on each layer over the whole outline, with thermal reliefs. kicad-cli fills it and runs DRC.
  4. Islands are stitched. A ground pad cut off from the main pour gets a via beside it and a short track to it. A chip's exposed pad gets its via at its own centre instead, unless another net's track runs there. Fill, check and stitch run up to three times.
  5. A pad still cut off is routed. It goes to the router as a two-pin net with the nearest ground pad the pour reached. This copper is kept only if it comes back clean.
  6. The last resort. If that fails, all of ground is routed as traces.

The fab gets the copper KiCad filled. kicad.read_fills() reads the filled shapes back, and the same shapes go to the Gerbers, the picture and the page. The pour stops 0.30 mm inside the outline, where the router's copper stops.

A pour is never silently missing

If the pour cannot be filled (no kicad-cli, or a failed fill), it stands down and ground is routed as traces. The build says so. If the fill worked but cannot be read back, the board is saved without the pour, and that is a gap.

The verdict under a pour

A poured board is clean when three things hold:

  • The router reached every pin of every net it was given.
  • The pour reaches every pad of the poured nets.
  • KiCad's DRC finds nothing wrong with the copper.

DRC judges the copper, not the router's own count. A footprint's own touching pads, such as a USB-C receptacle's, are one part's pads to KiCad's DRC, not a violation.

A pour in two pieces counts as a copper error (pour_split), even when every pad is reached.

The pour's row in the routing report carries these numbers:

FieldMeaning
islands_before, islands_afterGround pads the fill did not reach, before and after stitching
vias_addedStitching vias added to rescue islands
starvedPads the fill reaches by fewer spokes than KiCad wants. A weaker joint, not a failure.
solid_padsPads joined to the pour solid because one spoke was all KiCad could give them
pads_routedCut-off pads that were routed as their own net
cosmetic_by_kindDRC findings the verdict sets aside, by kind

The verdict sets aside silkscreen, courtyard, text and library findings. It also sets aside three findings inside one part's own land pattern, which no placement or route can change:

  • its unconnected pads drawn touching, such as a USB-C receptacle's A1 and B12
  • a pad nearer the part's own unplated hole than the hole rule, such as a USB-C receptacle's pads by its pegs
  • two of its pads closer than the clearance but apart, such as an LGA's corner pads

A pad the fill reaches by one thermal spoke is joined to the pour solid instead. KiCad's DRC counts a one-spoke pad as an error, so a person opening the board would see one. The build refills and checks again, and keeps the change only if DRC finds nothing worse. It tries up to three rounds, since a changed fill can leave the next pad one spoke. Every other pad keeps its thermal relief. A solid pad has more copper than a spoke, and is slower to heat with an iron. Set SOLDERMASK_UNSTARVE=0 to keep every relief.

Power pours

Power rails are routed as tracks first. A board can still fail on its copper alone: a run too hot for its current, or pour errors. Such a board is then built again with its power rails poured, and the build with fewer copper failures is kept. A note says when a board was built twice and why.

  1. The first build routes every rail as a track. A board that passes is built once.
  2. A copper-only failure triggers the second build. A missing part, an ERC error or a dropped connection does not, since rerouting changes none of them.
  3. The second build pours each rail whose current needs a track of 0.5 mm or more.
  4. The build with fewer copper failures is kept.

Pouring every board's rails from the start gained one board and lost two at declared currents. With every current doubled it gained six and lost none, all six failing on their copper. The CHANGELOG has the runs.

SettingWhat it does
SOLDERMASK_POWER_FALLBACK=0Builds once, with rails as tracks
SOLDERMASK_POWER_POUR=1Pours the rails from the first build
SOLDERMASK_POWER_POUR=VM,+12VPours the rails named
SOLDERMASK_POWER_POUR=0Pours no rail, and so no second build
SOLDERMASK_POWER_SHAPEThe zone's shape: hull, tree or mould

The routability model and a poured board

The routability model was trained on two-layer boards whose ground was routed as traces. A poured board is an easier route than anything it has seen. So for a poured board, or one of four layers, it falls back to the analytic estimate. The note on the page says why.

Four layers

A board can be built on four copper layers. Ask for "a four-layer board" in the prompt, pass --layers 4, or set board.layers to 4.

LayerWhat it holds
F.CuSignals, with ground poured round them
In1.CuA solid ground plane
In2.CuSignals, with ground poured round them
B.CuSignals, with ground poured round them
  1. Ground takes In1.Cu. It leaves the router, as it does on two layers.
  2. Every surface ground pad gets a via first. The via goes beside the pad, with a short track to it, before any signal is routed. A chip's exposed pad gets its via at its own centre.
  3. Lightcycle routes every other net on F.Cu, In2.Cu and B.Cu.
  4. Signals win where the vias wall one in. If the vias left a signal open, the signals are routed again with no vias down. Where that leaves fewer nets open, the vias are laid clear of that copper.
  5. KiCad fills the planes and pours. Islands, stitching and the re-route then run as on two layers. Where step 4 made a second board, both are poured, and the one with fewer connections open is kept.
SettingWhat it does
SOLDERMASK_SIGNALS_FIRST=0Keeps the vias as first laid (step 4 off)
SOLDERMASK_POUR_EP_SITES=0Leaves an exposed pad to the fill and the fallback

A through-hole pad reaches the ground plane without a via. SOLDERMASK_PLANES=gnd+power puts the busiest power rail on In2.Cu as a second plane instead. That rail then leaves the router too, and other rails stay as tracks with a note naming them. On the 305-design pool, signals on In2.Cu routed more boards: 276 against 270. The CHANGELOG has the run. The Gerbers add In1_Cu.g1 and In2_Cu.g2, the names KiCad gives them.

What four layers does not change

The A* router routes on every layer of the file it reads, so it refuses a board with planes, and Lightcycle routes it instead. With rules.pour off there is no plane, and all four layers carry signals. The fab rules check holds a four-layer board to JLCPCB's one- and two-layer rows, and says so. A prompt that asks for another count is built on two or four, and the gaps say which.

On this page