place_footprint
Place a footprint on a PCB with pads, silkscreen, and 3D model copied from a KiCad library. Use it to add real components for routing and DRC, or omit library for a pad-less marker.
Instructions
Place a footprint on the PCB.
Name a library and a footprint to place the real thing: its pads, silkscreen,
courtyard and 3D model are copied from the library file exactly as KiCad
would place them, a footprint in KiCad 7's form taking the reference and value
in its own (fp_text reference|value ...), where one holding %V or %R, which KiCad
reads there as a variable, is refused. Without them you get a marker carrying
only the reference and value, which has NO PADS and so cannot be routed or
checked; that is the older behaviour and it is kept for callers that only want a
placeholder.
Use list_lib_footprints to see what a library holds.
The footprint is turned to its rotation as KiCad's own rotate turns it: every
pad and text turns with it (a pad's angle is its library angle plus the
footprint's), and a keep-upright text that would read upside down is turned
half a turn with its justification mirrored, so it stays readable on the same
side of its anchor. Angles are written as KiCad writes them: the footprint's
between -180 and 180 and left out at 0, each pad's and text's absolute. Off the
quarter turns the result reads as KiCad's placement without matching pcbnew's
save byte for byte: footprint-relative coordinates stay as the library writes
them where pcbnew re-derives them through two RotatePoint roundings, an fp_rect
stays where pcbnew writes an fp_poly, and arc mid points stay as written. A
library footprint without a Datasheet or Description field is placed without
it, so KiCad reads that hidden field at its default on F.Fab, whereas pcbnew
writes it, on B.Fab for a placement on the back.
Zones the footprint owns (keepouts, say) and a KiCad 10 footprint's points are
stored in board coordinates (format( ZONE ), pcb_io_kicad_sexpr.cpp:2628-2637 at
9.0.8), so they land where KiCad's placement puts them: moved with the footprint,
turned about it and, on the back, mirrored with it.
A footprint carrying what this tool does not move with it (a dimension, image,
table or barcode, or a child no KiCad it knows reads), or on the back what it does
not flip (see move_footprint), is refused and nothing is written.
Args:
reference: Reference designator (e.g. "R2")
value: Component value (e.g. "4.7K")
x: X position in mm
y: Y position in mm
rotation: The footprint's angle in degrees, counter-clockwise as seen on
screen; any finite value (270 is stored as -90, 360 as 0). inf and nan
are refused and nothing is written.
layer: F.Cu or B.Cu; any other layer is refused. B.Cu places the footprint
flipped as KiCad's own flip does, then turns it to rotation
(FOOTPRINT::Flip, pcbnew/footprint.cpp:2491-2550 at 9.0.8).
library: Footprint library nickname (e.g. "Resistor_SMD"), or a path to a
.pretty directory. A nickname is resolved as update_pcb_from_schematic
resolves it: the project's fp-lib-table beside the board, .pretty
directories beside the board, KICAD_FP_LIB, the user's global
fp-lib-table (with the libraries the Plugin and Content Manager
installed), then KiCad's stock footprints. Optional; omit for a
pad-less marker.
footprint: Footprint name within that library (e.g. "R_0805_2012Metric").
Required when library is given.
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| layer | No | F.Cu | |
| value | Yes | ||
| library | No | ||
| pcb_path | No | ||
| rotation | No | ||
| footprint | No | ||
| reference | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |