Reference manual
Copyright
This document is Copyright © 2010-2020 by its contributors as listed below. You may distribute it and/or modify it under the terms of either the GNU General Public License (http://www.gnu.org/licenses/gpl.html), version 3 or later, or the Creative Commons Attribution License (http://creativecommons.org/licenses/by/3.0/), version 3.0 or later.
All trademarks within this guide belong to their legitimate owners.
Contributors
Jean-Pierre Charras, Fabrizio Tappero, Wayne Stambaugh, Jon Evans
Feedback
Please direct any bug reports, suggestions or new versions to here:
-
About KiCad document: https://gitlab.com/kicad/services/kicad-doc/issues
-
About KiCad software: https://gitlab.com/kicad/code/kicad/issues
-
About KiCad translation: https://gitlab.com/kicad/code/kicad-i18n/issues
Introduction to Pcbnew
Initial configuration
When Pcbnew is run for the first time, if the global footprint table
file fp-lib-table is not found in the KiCad configuration folder, Pcbnew
will ask how to create this file:
| TODO: add screenshot |
| TODO: add instructions on what these options mean |
The default footprint library table includes all of the standard footprint libraries that are installed as part of KiCad.
The Pcbnew user interface
The main Pcbnew user interface is shown above, with some key elements indicated:
-
Top toolbars
-
Left toolbar
-
Message panel and status bar
-
Right toolbar (drawing and design tools)
-
Appearance panel
-
Selection filter panel
Navigating the editing canvas
The editing canvas is a view onto the board being designed. You can pan and zoom to different areas of the board, and also flip the view to show the board from the bottom.
By default, dragging with the middle or right mouse button will pan the canvas view, and scrolling the mouse wheel will zoom the view in or out. You can change this behavior in the Mouse and Touchpad section of the preferences (see Configuration and Customization for details).
Hotkeys
| TODO: Write this section |
Display and selection controls
Board layers
Layers in Pcbnew represent physical copper layers on a board, as well as graphical layers used for defining things such as silkscreen, solder mask, and the board edge. There is always one layer that is active in the editor. The active layer is drawn on top of other layers, and will be the layer assigned to newly-created objects. The active layer is indicated in the layer selector drop-down box in the top toolbar, and is also highlighted in the appearance panel. To change the active layer, you can click a layer name in the appearance panel, use the drop-down layer selector in the top toolbar, or use a hotkey. Layers can be hidden to simplify the board view. You can hide a layer even if it is the active layer.
The appearance panel
The appearance panel provides controls to manage the visibility, color, and opacity of objects in the Pcbnew drawing canvas. It has three tabs: the Layers tab contains controls for the board layers, the Objects tab contains controls for different types of graphical objects, and the Nets tab contains controls for the appearance of the ratsnest and copper items.
Layer controls
In the Layers tab of the appearance panel, each board layer is shown with its color and visibility state. The active layer is shown highlighted with an arrow indicator to the left of the color swatch. Left-click on a layer to choose it as the active layer. Left-click on the corresponding visibility icon to toggle the layer between visible and hidden. Double-click or middle-click on the color swatch to change the layer’s color.
| You must first create a custom color theme in Preferences before you can change layer colors in the appearance panel. |
Below the list of layers is an expandable panel that contains layer display options. The first
setting controls how non-active layers are displayed: normal, dimmed, or hidden. The layer display
mode can be used to simplify the view and focus on a single layer. Items on inactive layers cannot
be selected when the non-active layer display mode is "Dim" or "Hide". You can use the hotkey
Ctrl+H to cycle through these display modes quickly.
Flip board view will show the board as if you are looking from the bottom (that is, mirrored around the Y-axis). This option is also available in the View menu.
Object controls
The Objects tab of the appearance panel is similar to the Layers tab. The main differences are that some objects have no color setting, and that four types of objects (tracks, vias, pads, and zones) have opacity control sliders. The opacity setting here will be multiplied with any opacity set in the layer colors. By default, all objects are fully opaque except for zones, which are set to translucent in order to make it easier to see objects through filled zone areas.
Layer presets
Layer presets store which layers and objects are visible and hidden for easy recall. There are several built-in layer presets, and you can save your own custom presets. Custom presets are stored in the project settings for a board, as presets may be specific to a certain board stackup.
To load a preset, choose it from the Presets drop-down menu at the bottom of the appearance panel,
or use the quick switcher by holding down Ctrl and pressing Tab. Once the quick switcher
window appears, you can press Tab and Shift+Tab to cycle through the available presets. When
you let go of the Ctrl key, the highlighted preset will be loaded.
To save a custom preset, first use the visibility controls to choose which layers you want visible, then choose Save Preset… from the Presets drop-down menu. Give your preset a name, and it will now be available via the drop-down menu and the quick switcher. To modify a custom preset, follow the same process and save the modified version with the same name to overwrite the existing version. To delete a custom preset, choose the Delete Preset… option from the drop-down menu and select the preset to be deleted from the list.
Net and net class controls
The Nets tab of the appearance panel shows a list of all nets and net classes in the board. Each net has a visibility control that controls the visibility of that net in the ratsnest. Hiding nets in the ratsnest does not change the connectivity of the board and will not impact the design rule checker; it only is intended to make the ratsnest easier to understand.
Each net and net class can also have a color assigned. By default, this color applies to the ratsnest lines for the net (or for all the nets in the net class). Nets have no color by default; this is indicated by a checkerboard pattern in the color swatch. Double-click or right-click a net or net class color swatch to set the color.
| The Default net class cannot have a color assigned, as nets in this class will just use the default ratsnest color defined by the color theme. |
You can also select and highlight nets and net classes via the appearance panel: right-click on a net or net class to show these options in a menu.
Below the list of net classes is an expandable panel that contains net display options. The first option controls how net colors are applied. When "All" is selected, all copper items (pads, tracks, vias, and zones) belonging to a net or net class will take on the chosen color. When "Ratsnest" is selected (the default value), only the ratsnest is affected by net and net class colors. When "None" is selected, net and net class colors are ignored.
The second option controls how ratsnest lines are drawn. "All layers" means that ratsnest lines will be drawn between all unconnected items. "Visible layers" means that no ratsnest lines will be drawn to items that are on hidden layers, even when those items are unconnected.
Selection and the selection filter
Selecting items in the editing canvas is done with the left mouse button. Single-clicking on an object will select it, and dragging will perform a box selection. A box selection from left to right will only select items that are fully inside the box. A box selection from right to left will select any items that touch the box. A left-to-right selection box is drawn in yellow, and a right-to-left selection box is drawn in blue.
The selection action can be modified by holding modifier keys while clicking or dragging:
| Modifier Keys (Windows/Linux) | Modifier Keys (macOS) | Selection Effect |
|---|---|---|
|
|
Add item(s) to the existing selection. |
|
|
Remove item(s) to the existing selection. |
|
|
Toggle the selected state of item(s). |
|
|
Clarify selection from a pop-up menu. |
|
|
Highlight the net of selected pads or tracks |
The selection filter panel in the lower right corner of the Pcbnew window controls which types of objects can be selected with the mouse. Turning off selection of unwanted object types makes it easier to select items in a dense board. The "All items" checkbox is a shortcut to turn the other items on and off. The "Locked items" checkbox is independent of the rest, and controls whether or not items that have been locked can be selected. You can right-click any object type in the selection filter to quickly change the filter to only allow selecting that type of object.
When a connected copper item is selected, you can expand the selection to other copper items of the
same net using the Expand Selection command in the right-click context menu, or with the U hotkey
by default. The first time you run this command, the selection will be expanded to the nearest pad.
The second time, the selection will be expanded to all connected items on all layers.
Cross-probing from the schematic
KiCad allows bi-directional cross-probing between the schematic and the PCB. There are several different types of cross-probing.
Selection cross-probing is always enabled. Selecting a symbol in the schematic will select the corresponding footprint in the PCB (if one exists) and vice-versa. Selecting a pin in the schematic will select the corresponding pad in the PCB and vice-versa. By default, cross-probing will result in the display centering on the cross-probed item and zooming to fit. This behavior can be disabled in the Display Options section of the Preferences dialog.
Highlight cross-probing is enabled when the Highlight Net tool is active in both the schematic editor and the PCB editor. Highlighting a net in one editor will cause the corresponding net to be highlighted in the other. Highlighting a bus in the schematic editor will cause all nets in the bus to be highlighted in the PCB editor. Highlight cross-probing can be disabled in the Display Options section of the Preferences dialog.
Left toolbar display controls
The left toolbar provides options to change the display of items in Pcbnew.
|
Turns grid display on/off. Note: by default, hiding the grid will disable grid snapping. This behavior can be changed in the Display Options section of Preferences. |
|
Switch between polar and Cartesian coordinate display in the status bar. |
|
Display/entry of coordinates and dimensions in inches, mils, or millimeters. |
|
Switches between full-screen and small editing cursor (crosshairs). |
|
Turns the ratsnest display on/off. |
|
Switches between straight and curved ratsnest lines. |
|
Show zone filled areas. |
|
Show zone outlines only. |
|
Show zone filled areas as outlines. |
|
Switches display of pads between filled and outline mode. |
|
Switches display of vias between filled and outline mode. |
|
Switches display of tracks between filled and outline mode. |
|
Switches the non-active layer display mode between Normal and Dim. Note: this button will
be highlighted when the non-active layer display mode is either Dim or Hide. In both cases,
pressing the button will change the layer display mode to Normal. The Hide mode can only be
accessed via the controls in the Appearance Panel or via the hotkey |
|
Shows or hides the Appearance and Selection Filter panels on the right side of the editor. |
Creating PCBs
Basic PCB concepts
A printed circuit board in KiCad is generally made up of footprints representing electronic components and their pads, nets defining how those pads connect to each other, tracks, vias, and filled zones that form the copper connections between pads in each net, and various graphic shapes defining the board edge, silkscreen markings, and any other desired information.
Pcbnew normally keeps the information about nets on a PCB synchronized with an associated schematic, but nets can also be created and edited directly within Pcbnew.
Capabilities
Pcbnew is capable of creating printed circuit boards with up to 32 copper layers, 14 technical layers (silkscreen, solder mask, component adhesive, solder paste, etc) and 13 general-purpose drawing layers.
The internal measurement resolution of all objects in Pcbnew is 1 nanometer, and measurements are stored as 32-bit integers. This means it is possible to create boards up to appproximately 4 meters by 4 meters.
KiCad currently supports one board file per project / schematic.
Starting from a schematic
Creating a board from a schematic is the recommended workflow for KiCad. When you create a new project, KiCad will generate an empty board file with the same name as the project. To start designing the board after you have created a schematic, simply open the board file. You can do this either from the KiCad project manager, or by clicking the "Open PCB in board editor" button in Eeschema.
Starting from scratch
It is also possible to create a board with no matching schematic, although this workflow has some limitations and is not recommended for most users. To do this, you must start Pcbnew standalone (not from the KiCad project manager). Before beginning your design, it is a good idea to save the board file, which will also create a project file to store board settings. Use "Save As…" from the File menu to choose where to save your board file. A project file with the same name will be created in the same location you choose to save the board file in.
Board setup
Before beginning your board design, use the Board Setup dialog to configure the basic parameters of the board. To open Board Setup, click the icon in the top toolbar or choose "Board Setup…" from the File menu.
| TODO: Add screenshot of Board Setup |
Configuring board stackup
Configuring default text and graphic settings
Configuring design rules
Design rules control the behavior of the interactive router, the filling of copper zones, and the design rule checker. Design rules can be modified at any time, but it is recommended to establish all known design rules at the beginning of the board design process.
Constraints
Basic constraints are configured in the Constrants section of the Board Setup dialog. Constraints in this section apply to the entire board, and should be set to the values recommended by your board manufacturer.
Pre-defined Sizes
| TODO: Write this section |
Net Classes
| TODO: Write this section |
Custom Rules
| TODO: Write this section |
See Custom Design Rules in the Advanced Topics chapter for more information
Violation Severity
| TODO: Write this section |
Editing a board
Placement and drawing operations
Placement and drawing tools are located in the right toolbar. When a tool is activated, it stays
active until a different tool is selected, or the tool is canceled with the Esc key. The
selection tool is always activated when any other tool is canceled.
Some toolbar buttons have more than one tool available in a palette. These tools are indicated
with a small arrow in the lower-right corner of the button:
To show the palette, you can click and hold the mouse button on the tool, or click and drag the mouse. The palette will show the most recently used tool when it is closed.
|
Selection tool (the default tool). |
|
Net highlight tool: selecting pads, tracks, or vias with this tool will highlight the associated net while this tool is active. Clicking on empty space will remove the highlight. |
|
Local ratsnest tool: when the board ratsnest is hidden, selecting footprints with this tool will show the ratsnest for the selected footprint only. Selecting the same footprint again will hide its ratsnest. The local ratsnest setting for each footprint will remain in effect even after the local ratsnest tool is no longer active. |
|
Footprint placement tool: click on the board to open the footprint chooser, then click again after choosing a footprint to confirm its location. |
|
Route tracks / route differential pairs: These tools activate the interactive router and allow placing tracks and vias. The interactive router is described in more detail below. |
|
Add vias: allows placing vias without routing tracks. Vias placed on top of tracks using this tool will take on the net of the closest track segment, and will become part of that track (the via net will be updated if the pads connected to the tracks are updated). Vias placed anywhere else will take on the net of a copper zone at that location, if one exists. These vias will not automatically take on a new net if the net of the copper zone is changed. |
|
Add microwave shapes: these tools allow creation of some types of high-frequency circuit elements such as stubs, arcs, and serpentines. |
|
Add filled zone: Click to set the start point of a zone, then configure its properties before drawing the rest of the zone outline. Zone properties are described in more detail below. |
|
Add rule area: Rule areas, formerly known as keepouts, can restrict the placement of items and the filling of zones, and can also define named areas to apply specific custom design rules to. |
|
Draw lines. Note: Lines are graphical objects and are not the same as tracks placed with the Route Tracks tool. Graphical objects cannot be assigned to a net. |
|
Draw arcs: pick the center point of the arc, then the start and end points. |
|
Draw rectangles. Rectangles can be filled or outlines. |
|
Draw circles. Circles can be filled or outlines. |
|
Draw graphical polygons. Polygons can be filled our outlines. Note: Filled graphical polygons are not the same as filled zones: graphical polygons cannot be assigned to a net and will not keep clearance from other items. |
|
Add text. |
|
Add dimensions. Dimension types are described in more detail below. |
|
Add layer alignment mark. |
|
Deletion tool: click objects to delete them. |
|
Set drill/place origin. Used for fabrication outputs. |
|
Set grid origin. |
Snapping
When moving, dragging, and drawing board elements, the grid, pads, and other elements can have snapping points depending upon the settings in the user preferences. In complex designs, snap points can be so close together that it makes the current tool action difficult. Both grid and object snapping can be disabled while moving the mouse by using the modifier keys in the table below.
| Modifier Key | Effect |
|---|---|
|
Disable grid snapping. |
|
Disable object snapping. |
Editing object properties
All objects have properties that are editable in a dialog. Use the hotkey E or select
Properties from the right-click context menu to edit the properties of selected item(s). You can
only open the properties dialog if all the items you have selected are of the same type. To edit
the properties of different types of items at one time, see the section below on bulk editing
tools.
Working with footprints
| TODO: Write this section - covers footprint properties, updating from library, etc |
Working with pads
| TODO: Write this section - covers pad properties |
Working with zones
| TODO: Write this section |
Graphical objects
Graphical objects (lines, arcs, rectangles, circles, polygons, and text) can exist on any layer but
cannot be assigned to a net. Rectangles, circles, and polygons can be set to be filled or outlines
in their propeties dialogs. The line width property will control the width of the outline even for
filled shapes. Line width can be set to 0 for filled shapes to disable the outline.
Board outlines (Edge Cuts)
Pcbnew uses graphical objects on the Edge.Cuts layer to define the board outline. The outline
must be a continuous (closed) shape, but can be made up of different types of graphical object such
as lines and arcs, or be a single object such as a rectangle or polygon. If no board outline is
defined, or the board outline is invalid, some functions such as the 3D viewer and some design rule
checks will not be functional.
Dimensions
| TODO: Write this section |
Routing traces
| TODO: Write this section |
Interactive router settings
The interactive router settings can be accessed through the Route menu, or by right-clicking on the Route Tracks button in the toolbar. These settings control the router behavior when routing tracks as well as when dragging existing tracks.
| Setting | Description |
|---|---|
Mode |
Highlight collisions: disables most router features and allows manual placement of tracks and vias, with DRC violations (collisions) highlighted. Shove: moves other tracks and vias out of the way of the tracks being routed to avoid DRC violations. Walk around: prevents placing tracks and vias in locations that would cause a DRC violation, allowing you to "walk around" existing tracks and vias. |
Free angle mode |
Allows routing tracks at any angle, instead of just at 45-degree increments. This option is only available if the router mode is set to Highlight collisions. |
Jump over obstacles |
In Shove mode, allows the router to attempt to move colliding tracks behind solid obstacles (such as pads). |
Remove redundant tracks |
Automatically removes loops created in the currently-routed track, keeping only the most recently routed section of the loop. |
Optimize pad connections |
When this setting is enabled, the router attempts to avoid acute angles and other undesirable routing when exiting pads and vias. |
Smooth dragged segments |
When dragging tracks, attempts to combine track segments together to minimize direction changes. |
Allow DRC violations |
In Highlight collisions mode, allows placing tracks and vias that violate DRC rules. Has no effect in other modes. |
Optimize track being dragged |
Attempts to simplify tracks while they are being dragged. |
Use mouse path to set track posture |
Attempts to pick the track posture based on the mouse path from the routing start location. If the mouse moves mostly diagonally from the start location, the posture will be set to a diagonal start, and if the mouse moves mostly horizontally or vertically, the posture will be set to a vertical start. The posture guess is “locked” when the mouse moves far away from the routing start location, and can be “unlocked” by moving back to the start location. Note: Setting the posture manually using the Set Track Posture hotkey ( |
Fix all segments on click |
When enabled, clicking while routing will fix the position of all the track segments that have been routed, including the segment that ends at the mouse cursor. A new segment will be started from the mouse cursor location. When disabled, the last segment (the one that ends at the mouse cursor) will not be fixed in place and can be adjusted by further mouse movement. |
Differential pairs
| TODO: Write this section |
Forward and back annotation
| TODO: Write this section |
Geographical re-annotation
| TODO: Write this section |
Locking
Most objects can be locked through their properties dialogs or by using the right-click context menu. Locked objects cannot be selected unless the "Locked items" checkbox is enabled in the selection filter. Attempting to move locked items will result in a warning dialog:
Selecting "Override Locks" in this dialog will allow moving the locked items. Selecting "OK" will allow you to move any unlocked items in the selection; leaving the locked items behind. Selecting "Do not show again" will remember your choice for the rest of your session.
Bulk editing tools
| TODO: Write this section |
Cleanup tools
| TODO: Write this section |
Inspecting a board
Measurement tool
| TODO: Write this section |
Design rule checking
| TODO: Write this section |
Clearance and constraint resolution
| TODO: Write this section |
3D viewer
| TODO: Write this section |
Net inspector
| TODO: Write this section |
Generating outputs
Fabrication outputs
| TODO: Write this section |
Printing
| TODO: Write this section |
Exporting files
| TODO: Write this section NOTE: Bring IDF exporter docs in to here |
Footprints and footprint libraries
Managing footprint libraries
| TODO: Write this section |
Creating and editing footprints
| TODO: Write this section |
Custom pad shapes
Footprint attributes
| Mention net ties here |
Footprint wizards
For more information about creating new footprint wizards, see the Scripting section of the Advanced Topics chapter.
Advanced topics
Configuration and Customization
Pcbnew has a variety of preferences that can be configured through the Preferences dialog. Like all parts of KiCad, the preferences for Pcbnew are stored in the user configuration directory, and are independent between KiCad minor versions to allow multiple versions to run side-by-side with independent preferences.
The first sections of the Preferences dialog (Common, Mouse and Touchpad, and Hotkeys) are shared between all KiCad programs. These sections are described in detail in the KiCad manual under the "Common preferences" section. Note that even though the Hotkeys section is shared between all programs, there are many Pcbnew-specific hotkeys that only appear in the list when Pcbnew is running.
Display options
Grid style: Controls how the alignment grid is drawn.
Grid thickness: Controls how thick grid lines or dots are drawn.
Min grid spacing: Controls the minimum distance, in pixels, between two grid lines. Grid line that violate this minimum spacing will not be drawn, regardless of the current grid setting.
Snap to grid: Controls when drawing and editing operations will be snapped to coordinates on the active grid. "Always" will enable snapping even when the grid is hidden; "When grid shown" will enable snapping only when the grid is visible.
Grid snapping can be temporarily disabled by holding down Shift.
|
Cursor shape: Controls whether the editing cursor is drawn as a small crosshair or a full-screen crosshair (a set of lines covering the entire drawing canvas). The editing cursor shows where the next drawing or editing action will occur, and will be snapped to a grid location if snapping is enabled.
Always show crosshairs: Controls whether the editing cursor is shown all the time, or only when an editing or drawing tool is active.
Net names: Controls whether or not net name labels are drawn on copper objects. These labels are guides for editing only, and do not appear in fabrication outputs.
Show pad numbers: Controls whether or not pad number labels are drawn on footprint pads.
Show pad <no net> indicator: Controls whether or not pads with no net are indicated with a special marker.
Track clearance: Controls whether or not clearance outlines around tracks and vias are shown. Clearance outlines are shown as thin shapes around objects that indicate the minimum clearance to other objects, as defined by constraints and design rules.
Show pad clearance: Controls whether or not clearance outlines around pads are shown.
Center view on cross-probed items: When both Eeschema and Pcbnew are running, controls whether clicking a component or pin in Eeschema will center the Pcbnew view on the corresponding footprint or pad.
Zoom to fit cross-probed items: Controls whether the view will be zoomed to show a cross-probed footprint or pad.
Highlight cross-probed nets: Controls whether or not nets highlighted in Eeschema will be highlighted in Pcbnew when the highlight tool is activated in both tools.
Editing options
Lock pads of newly added footprints: Controls whether or not the pads of footprints will default to locked or unlocked (editable).
Flip board items L/R: Controls the direction board items will be flipped when moving them between the top and bottom layers.
Limit graphic lines to H, V and 45 degrees: Controls whether lines drawn with the graphic drawing tools can take on any angle. Note that this only affects drawing new lines: lines can be edited to take on any angle.
Magnetic points: This section controls object snapping, also called magnetic points. Object
snapping takes precedence over grid snapping when it is enabled. Object snapping only works to
objects on the active layer. Hold Alt to temporary disable object snapping.
Snap to pads: Controls when the editing cursor will snap to pad origins.
Snap to tracks: Controls when the editing cursor will snap to track segment endpoints.
Snap to graphics: Controls when the editing cursor will snap to graphic shape points.
Always show selected ratsnest: When enabled, the ratsnest for a selected footprint will always be shown even if the global ratsnest is hidden.
Show ratsnest with curved lines: Controls whether ratsnest lines are drawn straight or curved.
Show page limits: Controls whether or not the page boundary is drawn as a rectangle.
Mouse drag track behavior: Controls the action that will occur when you drag a track segment with the mouse: "Move" will move the track segment independent of any others. "Drag" will invoke the push-and-shove router to drag the track, respecting design rules and keeping other track segments attached.
Colors
Pcbnew supports switching between different color themes to match your preferences. Kicad 6.0 comes with two built-in color themes: "KiCad Default" is a new theme designed to have good contrast and balance for most cases, and is the default for new installations. "KiCad Classic" is the default theme from KiCad 5.1 and earlier versions. Both of these built-in themes cannot be modified, but you can create new themes to customize the look of Pcbnew as well as install themes made by other users.
Color themes are stored in JSON files located in the colors subdirectory of the KiCad
configuration directory. The "Open Theme Folder" button will open this location in your system
file manager, making it easy to manage your installed themes. To install a new theme, place it in
this folder and restart KiCad. The new theme will be available from the drop-down list of color
themes if the file is a valid color theme file.
To create a new color theme, choose New Theme… from the drop-down list of color themes. Enter a name for your theme, and then begin editing colors. The colors in the new theme will be copied from whatever theme was selected before you created the new theme.
To change a color, double-click or middle-click the color swatch in the list. The "Reset to Default" button will reset that color to its corresponding entry in the "KiCad Default" color theme.
Color themes are saved automatically; all changes are reflected immediately when you close the Preferences dialog. The window on the right side of the dialog shows a preview of how the selected theme will look.
Action plugins
| TODO: Write this section |
Origin & axes
Display origin: Determines which coordinate origin is used for coordinate display in the editing canvas. The page origin is fixed at the corner of the page. The drill/place file origin and the grid origin can be moved by the user.
X axis: Controls whether X-coordinates increase to the right or to the left.
Y axis: Controls whether Y-coordinates increase upwards or downwards.
Custom design rules
The custom design rule language is based on s-expressions and allows you to create design constraints that are not possible with the built-in constraints. Each design rule generally contains an expression defining what objects to match, adn a constraint defining the rule to be applied to the matched objects.
Custom rule syntax
| TODO: Write this section |
Custom design rule examples
| TODO: Write this section |
Scripting
Scripting allows you to automate tasks within KiCad using the Python language. It is possible to add functionality to Pcbnew through Python "action plugins" that can be added to the top toolbar. It is also possible to write standalone scripts that interact with KiCad files, for example, to generate fabrication outputs from a board file automatically.
This manual covers general scripting concepts. Users wishing to write or modify scripts should also use the Doxygen documentation located at https://docs.kicad.org/doxygen-python/namespaces.html.
KiCad can be built with support for Python 2 or Python 3. Release builds of KiCad 6 and later will generally be built with Python 3 support, as Python 2 is no longer maintained.
Python script locations
| TODO: fill this out with final 6.0 scripting locations for each platform |
Action plugins
| TODO: Write this section (how to install new action plugins) |
Footprint wizards
The footprint wizards are a collection of python scripts that can be accessed from the Footprint Editor. If you invoke the footprint dialog you select a given wizard that allows you to see the footprint rendered, and you have some parameters you can edit.
If the plugins are not properly distributed to your system package, you can find the latest versions in the KiCad source tree at gitlab.
Using the scripting console
Pcbnew comes with a built-in Python console that can be used to inspect and interact with the
board. To launch the console, use the 
icon in the top toolbar.
The Pcbnew Python API is not automatically loaded, so to load it, type import pcbnew into the
console. The command pcbnew.GetBoard() will then return a reference to the board currently
loaded in Pcbnew, which can be inspected and modified through the console.
| TODO: Document the other useful PyAlaMode functions |
Writing external scripts
| TODO: Write this section |
Writing action plugins
| TODO: Write this section |
Actions reference
Below is a list of every available action in Pcbnew: a command that can be assigned to a hotkey. Hotkeys that are shared between all KiCad applications are listed in the KiCad manual and are not included here.
PCB Editor
| Action | Default Hotkey | Description |
|---|---|---|
Align to Bottom |
Aligns selected items to the bottom edge |
|
Align to Vertical Center |
Aligns selected items to the vertical center |
|
Align to Horizontal Center |
Aligns selected items to the horizontal center |
|
Align to Left |
Aligns selected items to the left edge |
|
Align to Right |
Aligns selected items to the right edge |
|
Align to Top |
Aligns selected items to the top edge |
|
Distribute Horizontally |
Distributes selected items along the horizontal axis |
|
Distribute Vertically |
Distributes selected items along the vertical axis |
|
Place Off-Board Footprints |
Performs automatic placement of components outside board area |
|
Place Selected Footprints |
Performs automatic placement of selected components |
|
Flip Board View |
View board from the opposite side |
|
Sketch Graphic Items |
Show graphic items in outline mode |
|
Decrease Layer Opacity |
|
Make the current layer more transparent |
Increase Layer Opacity |
|
Make the current layer more transparent |
Switch to Copper (B.Cu) layer |
|
|
Switch to Inner layer 1 |
||
Switch to Inner layer 10 |
||
Switch to Inner layer 11 |
||
Switch to Inner layer 12 |
||
Switch to Inner layer 13 |
||
Switch to Inner layer 14 |
||
Switch to Inner layer 15 |
||
Switch to Inner layer 16 |
||
Switch to Inner layer 17 |
||
Switch to Inner layer 18 |
||
Switch to Inner layer 19 |
||
Switch to Inner layer 2 |
||
Switch to Inner layer 20 |
||
Switch to Inner layer 21 |
||
Switch to Inner layer 22 |
||
Switch to Inner layer 23 |
||
Switch to Inner layer 24 |
||
Switch to Inner layer 25 |
||
Switch to Inner layer 26 |
||
Switch to Inner layer 27 |
||
Switch to Inner layer 28 |
||
Switch to Inner layer 29 |
||
Switch to Inner layer 3 |
||
Switch to Inner layer 30 |
||
Switch to Inner layer 4 |
||
Switch to Inner layer 5 |
||
Switch to Inner layer 6 |
||
Switch to Inner layer 7 |
||
Switch to Inner layer 8 |
||
Switch to Inner layer 9 |
||
Switch to Next Layer |
|
|
Switch to Previous Layer |
|
|
Toggle Layer |
|
Switch between layers in active layer pair |
Switch to Component (F.Cu) layer |
|
|
Net Inspector |
Show the net inspector |
|
Highlight Ratsnest |
Show ratsnest of selected item(s) |
|
Sketch Pads |
Show pads in outline mode |
|
Curved Ratsnest Lines |
Show ratsnest with curved lines |
|
Repair Board |
Run various diagnostics and attempt to repair board |
|
Show Appearance Manager |
Show/hide the appearance manager |
|
Show pad numbers |
Show pad numbers |
|
Scripting Console |
Show the Python scripting console |
|
Show Ratsnest |
Show board ratsnest |
|
Sketch Text Items |
Show footprint texts in line mode |
|
Sketch Tracks |
|
Show tracks in outline mode |
Sketch Vias |
Show vias in outline mode |
|
Wireframe Zones |
Show only zone boundaries |
|
Fill Zones |
Show filled areas of zones |
|
Sketch Zones |
Show solid areas of zones in outline mode |
|
Toggle Zone Display |
|
Cycle between showing filled zones, wireframed zones and sketched zones |
Automatically zoom to fit |
Zoom to fit when changing footprint |
|
Convert to Arc |
Converts selected line segment to an arc |
|
Convert to Rule Area |
Creates a rule area from the selection |
|
Convert to Lines |
Creates graphic lines from the selection |
|
Convert to Polygon |
Creates a graphic polygon from the selection |
|
Convert to Tracks |
Converts selected graphic lines to tracks |
|
Convert to Zone |
Creates a copper zone from the selection |
|
Design Rules Checker |
Show the design rules checker window |
|
Open in Footprint Editor |
|
Opens the selected footprint in the Footprint Editor |
Append Board… |
Open another board and append its contents to this board |
|
Board Setup… |
Edit board setup including layers, design rules and various defaults |
|
Clear Net Highlighting |
Clear any existing net highlighting |
|
Drill/Place File Origin |
Place origin point for drill files and component placement files |
|
Specctra DSN… |
Export Specctra DSN routing info |
|
BOM… |
Create bill of materials from board |
|
IPC-D-356 Netlist File… |
Generate IPC-D-356 netlist file |
|
Drill Files (.drl)… |
Generate Excellon drill file(s) |
|
Gerbers (.gbr)… |
Generate Gerbers for fabrication |
|
Component Placement (.pos)… |
Generate component placement file(s) for pick and place |
|
Footprint Report (.rpt)… |
Create report of all footprints from current board |
|
Group |
Group the selected items so that they are treated as a single item |
|
Enter Group |
Enter the group to edit items |
|
Leave Group |
Leave the current group |
|
Hide Net |
Hide the ratsnest for the selected net |
|
Highlight Net |
|
Highlight all copper items of a net |
Highlight Nets |
Highlight all copper items of a net |
|
Netlist… |
Read netlist and update board connectivity |
|
Specctra Session… |
Import routed Specctra session (*.ses) file |
|
Lock |
Prevent items from being moved and/or resized on the canvas |
|
Add Footprint |
|
Add a footprint |
Add Layer Alignment Target |
Add a layer alignment target |
|
Remove Items |
Remove items from group |
|
Switch to Schematic Editor |
Open schematic in Eeschema |
|
Show Net |
Show the ratsnest for the selected net |
|
Toggle Last Net Highlight |
Toggle between last two highlighted nets |
|
Toggle Lock |
|
Lock or unlock selected items |
Switch Track Width to Previous |
|
Change track width to previous pre-defined size |
Switch Track Width to Next |
|
Change track width to next pre-defined size |
Ungroup |
Ungroup any selected groups |
|
Unlock |
Allow items to be moved and/or resized on the canvas |
|
Decrease Via Size |
|
Change via size to previous pre-defined size |
Increase Via Size |
|
Change via size to next pre-defined size |
Duplicate Zone onto Layer… |
Duplicate zone outline onto a different layer |
|
Merge Zones |
Merge zones |
|
Change Footprint… |
Assign a different footprint from the library |
|
Change Footprints… |
Assign different footprints from the library |
|
Cleanup Graphics… |
Cleanup redundant items, etc. |
|
Cleanup Tracks & Vias… |
Cleanup redundant items, shorting items, etc. |
|
Edit Text & Graphics Properties… |
Edit Text and graphics properties globally across board |
|
Edit Track & Via Properties… |
Edit track and via properties globally across board |
|
Global Deletions… |
Delete tracks, footprints and graphic items from board |
|
Remove Unused Pads… |
Remove or restore the unconnected inner layers on through hole pads and vias |
|
Swap Layers… |
Move tracks or drawings from one layer to another |
|
Update Footprint… |
Update footprint to include any changes from the library |
|
Update Footprints from Library… |
Update footprints to include any changes from the library |
|
Clearance Resolution… |
Show clearance resolution for the active layer between two selected objects |
|
Constraints Resolution… |
Show constraints resolution for the selected object |
|
Show Board Statistics |
Shows board statistics |
|
Add Aligned Dimension |
|
Add an aligned linear dimension |
Draw Arc |
|
Draw an arc |
Switch Arc Posture |
|
Switch the arc posture |
Add Center Dimension |
Add a center dimension |
|
Draw Circle |
|
Draw a circle |
Close Outline |
Close the in progress outline |
|
Decrease Line Width |
|
Decrease the line width |
Delete Last Point |
|
Delete the last point added to the current item |
Draw Graphic Polygon |
|
Draw a graphic polygon |
Increase Line Width |
|
Increase the line width |
Add Leader |
Add a leader dimension |
|
Draw Line |
|
Draw a line |
Limit Lines to 45 deg |
Limit graphic lines to H, V and 45 degrees |
|
Add Orthogonal Dimension |
Add an orthogonal dimension |
|
Place Imported Graphics |
|
|
Draw Rectangle |
Draw a rectangle |
|
Add Rule Area |
|
Add a rule area (keepout) |
Place the Footprint Anchor |
|
Set the coordinate origin point (anchor) of the footprint |
Add a Similar Zone |
|
Add a zone with the same settings as an existing zone |
Add Text |
|
Add a text item |
Add Vias |
|
Add free-standing vias |
Add Filled Zone |
|
Add a filled zone |
Add a Zone Cutout |
|
Add a cutout area of an existing zone |
Get and Move Footprint |
|
Selects a footprint by reference designator and places it under the cursor for moving |
Change Track Width |
Updates selected track & via sizes |
|
Create Array… |
|
Create array |
Delete Full Track |
|
Deletes selected item(s) and copper connections |
Duplicate and Increment |
|
Duplicates the selected item(s), incrementing pad numbers |
Fillet Tracks |
Adds arcs tangent to the selected straight track segments |
|
Change Side / Flip |
|
Flips selected item(s) to opposite side of board |
Mirror |
Mirrors selected item |
|
Move Exactly… |
|
Moves the selected item(s) by an exact amount |
Properties… |
|
Displays item properties dialog |
Rotate Counterclockwise |
|
Rotates selected item(s) counterclockwise |
Rotate Clockwise |
|
Rotates selected item(s) clockwise |
Copy with Reference |
Copy selected item(s) to clipboard with a specified starting point |
|
Move |
|
Moves the selected item(s) |
Move with Reference |
Moves the selected item(s) with a specified starting point |
|
Auto-finish Track |
|
Automagically finishes laying the current track. |
Break Track |
Splits the track segment into two segments connected at the cursor position. |
|
Custom Track/Via Size… |
|
Shows a dialog for changing the track width and via size. |
Route Differential Pair |
|
Route differential pairs |
Differential Pair Dimensions… |
Open Differential Pair Dimension settings |
|
Drag (45 degree mode) |
|
Drags the track segment while keeping connected tracks at 45 degrees. |
Drag (free angle) |
|
Drags the nearest joint in the track without restricting the track angle. |
Finish Track |
|
Stops laying the current track. |
Router Highlight Mode |
Switch router to highlight mode |
|
Break Track |
Splits the track segment into two segments connected at the cursor position. |
|
Place Blind/Buried Via |
|
Adds a blind or buried via at the end of currently routed track. |
Place Microvia |
|
Adds a microvia at the end of currently routed track. |
Place Through Via |
|
Adds a through-hole via at the end of currently routed track. |
Select Layer and Place Blind/Buried Via… |
|
Select a layer, then add a blind or buried via at the end of currently routed track. |
Select Layer and Place Through Via… |
|
Select a layer, then add a through-hole via at the end of currently routed track. |
Set Layer Pair… |
Change active layer pair for routing |
|
Interactive Router Settings… |
|
Open Interactive Router settings |
Router Shove Mode |
Switch router to shove mode |
|
Route Single Track |
|
Route tracks |
Switch Track Posture |
|
Switches posture of the currently routed track. |
Switch Corner Rounding |
|
Switches the corner type of the currently routed track. |
Undo last segment |
|
Stops laying the current track. |
Router Walkaround Mode |
Switch router to walkaround mode |
|
Deselect All Tracks in Net |
Deselects all tracks & vias belonging to the same net. |
|
Filter Selected Items… |
Remove items from the selection by type |
|
Select/Expand Connection |
|
Selects a connection or expands an existing selection to junctions, pads, or entire connections |
Select All Tracks in Net |
Selects all tracks & vias belonging to the same net. |
|
Sheet |
Selects all footprints and tracks in the schematic sheet |
|
Items in Same Hierarchical Sheet |
Selects all footprints and tracks in the same schematic sheet |
|
Decrease Amplitude |
|
Decrease meander amplitude by one step. |
Increase Amplitude |
|
Increase meander amplitude by one step. |
End Track |
|
Stops laying the current meander. |
Length Tuning Settings… |
|
Sets the length tuning parameters for currently routed item. |
Decrease Spacing |
|
Decrease meander spacing by one step. |
Increase Spacing |
|
Increase meander spacing by one step. |
New Track |
|
Starts laying a new track. |
Tune length of a differential pair |
|
|
Tune skew of a differential pair |
|
|
Tune length of a single track |
|
|
Add Microwave Polygonal Shape |
Create a microwave polygonal shape from a list of vertices |
|
Add Microwave Gap |
Create gap of specified length for microwave applications |
|
Add Microwave Line |
Create line of specified length for microwave applications |
|
Add Microwave Stub |
Create stub of specified length for microwave applications |
|
Add Microwave Arc Stub |
Create stub (arc) of specified size for microwave applications |
|
Footprint Checker |
Show the footprint checker window |
|
Copy Footprint |
||
Create Footprint… |
Create a new footprint using the Footprint Wizard |
|
Cut Footprint |
||
Delete Footprint from Library |
||
Edit Footprint |
Show selected footprint on editor canvas |
|
Export Footprint… |
||
Footprint Properties… |
Edit footprint properties |
|
Import Footprint… |
||
New Footprint… |
|
Create a new, empty footprint |
Paste Footprint |
||
Show Footprint Tree |
Toggles the footprint tree visibility |
|
Paste Default Pad Properties to Selected |
Replace the current pad’s properties with those copied earlier |
|
Copy Pad Properties to Default |
Copy current pad’s properties |
|
Push Pad Properties to Other Pads… |
Copy the current pad’s properties to other pads |
|
Default Pad Properties… |
Edit the pad properties used when creating new pads |
|
Renumber Pads… |
Renumber pads by clicking on them in the desired order |
|
Edit Pad as Graphic Shapes |
|
Ungroups a custom-shaped pad for editing as individual graphic shapes |
Add Pad |
Add a pad |
|
Finish Pad Edit |
|
Regroups all touching graphic shapes into the edited pad |
Create Corner |
|
Create a corner |
Remove Corner |
Remove corner |
|
Position Relative To… |
|
Positions the selected item(s) by an exact amount relative to another |
Geographical Reannotate… |
Reannotate PCB in geographical order |
|
Fill |
Fill zone(s) |
|
Fill All |
|
Fill all zones |
Unfill |
Unfill zone(s) |
|
Unfill All |
|
Unfill all zones |
3D Viewer
| Action | Default Hotkey | Description |
|---|---|---|
Add Floor |
Adds a floor plane below the board (slow) |
|
Anti-aliasing |
Render with improved quality on final render (slow) |
|
Toggle SMD 3D models |
|
Toggle 3D models with 'Surface mount' attribute |
Toggle Through Hole 3D models |
|
Toggle 3D models with 'Through hole' attribute |
Toggle Virtual 3D models |
|
Toggle 3D models with 'Virtual' attribute |
Flip Board |
Flip the board view |
|
Home view |
|
Home view |
CAD Color Style |
Use a CAD color style based on the diffuse color of the material |
|
Use Diffuse Only |
Use only the diffuse color property from model 3D model file |
|
Use All Properties |
Use all material properties from each 3D model file |
|
Move board Down |
|
Move board Down |
Move board Left |
|
Move board Left |
Move board Right |
|
Move board Right |
Move board Up |
|
Move board Up |
No 3D Grid |
No 3D Grid |
|
Center pivot rotation |
|
Center pivot rotation (middle mouse click) |
Post-processing |
Apply Screen Space Ambient Occlusion and Global Illumination reflections on final render (slow) |
|
Procedural Textures |
Apply procedural textures to materials (slow) |
|
Render Shadows |
Render Shadows |
|
Reset view |
|
Reset view |
Rotate 45 degrees over Z axis |
|
|
Rotate X Clockwise |
Rotate X Clockwise |
|
Rotate X Counterclockwise |
Rotate X Counterclockwise |
|
Rotate Y Clockwise |
Rotate Y Clockwise |
|
Rotate Y Counterclockwise |
Rotate Y Counterclockwise |
|
Rotate Z Clockwise |
Rotate Z Clockwise |
|
Rotate Z Counterclockwise |
Rotate Z Counterclockwise |
|
3D Grid 10mm |
3D Grid 10mm |
|
3D Grid 1mm |
3D Grid 1mm |
|
3D Grid 2.5mm |
3D Grid 2.5mm |
|
3D Grid 5mm |
3D Grid 5mm |
|
Show 3D Axis |
Show 3D Axis |
|
Show Model Bounding Boxes |
Show Model Bounding Boxes |
|
Reflections |
Render materials with reflective properties on final render (slow) |
|
Refractions |
Render materials with refractive properties on final render (slow) |
|
Toggle adhesive display |
Toggle display of adhesive layers |
|
Toggle board body display |
Toggle board body display |
|
Toggle comments display |
Toggle display of comments and drawings layers |
|
Toggle ECO display |
Toggle display of ECO layers |
|
Toggle orthographic projection |
Enable/disable orthographic projection |
|
Toggle realistic mode |
Toggle realistic mode |
|
Toggle silkscreen display |
Toggle display of silkscreen layers |
|
Toggle solder mask display |
Toggle display of solder mask layers |
|
Toggle solder paste display |
Toggle display of solder paste layers |
|
Toggle zone display |
Toggle zone display |
|
View Back |
|
View Back |
View Bottom |
|
View Bottom |
View Front |
|
View Front |
View Left |
|
View Left |
View Right |
|
View Right |
View Top |
|
View Top |