Frequently asked questions
The answer, as often happens, is it depends.
Search outstanding Issues and Pull Requests
If there are outstanding issues and/or pull requests for the repository, search those to see if anyone else has found the same issue - maybe they have addressed it previously.
Find the original author
It may be possible to ascertain the original author of the file(s). Perhaps there is a particular (and valid) reason they have submitted the file in a particular way.
Find the source of the file
Many files in the KiCad library are generated from script sources. If this is the case, you should alter the original script, and not the output files themselves.
Run KLC scripts with the --fix option
Some errors can be automatically* fixed with the KLC python scripts, by using the --fix command line option. If you fix a file with this, ensure that the file is thoroughly checked before resubmitting
Manually edit the file
The KiCad library is community driven. Show some community spirit :)
It is very helpful to submit a screenshot of the symbol(s) or footprint(s) you are submitting. This helps the library team to quickly check for common issues.
Please ensure that any pull requests are branched from the latest version of the KiCad library.
Please keep in mind that the library team is small, and it may take a few days to get to a new PR. When there are outstanding KLC issues (as reported by the automated checking scripts) please fix these first. If the PR remains unanswered, don't hesitate to contact the library team using IRC or the mailing list.
If you want to submit multiple types of symbols or footprints, it is best to make these separate pull requests so that issues can be addressed and fixed individually.
Currently there are a number of symbols and footprints in the official libraries that are not KLC compliant. This is a known issue and the libraries are slowly being improved by a very small team of active librarians. Community assistance is greatly appreciated, and will help to ensure that KiCad users have a large repository of high-quality well-vetted schematic symbols and PCB footprints to draw upon.
Pull requests are subjected to a set of Python scripts to run automatic validation checks. While these scripts cannot check every element of the KLC, and so pull requests also require manual checking by a librarian, they are invaluable for testing for common errors or problems in files.
Users can run these scripts locally, which greatly speeds up the submission process. Scripts are available in the KiCad Library Utils repository.
Associating footprints to schematic symbols can often be confusing to new users. KiCad schematic symbols support both a default footprint and footprint filters.
Default Footprint
The footprint field of a KiCad schematic symbol is a text field that refers to a default footprint file associated with the symbol. This should be a valid footprint path of the format Library:Footprint, where Library is the name of the library (excluding the .pretty extension) and Footprint is the name of the footprint file (excluding the .kicad_mod extension).
The default footprint field should be used when a symbol has (only) one footprint. It should be left blank for devices that have multiple possible footprints.
For example, the INA19x operational amplifier is available in a SOT-23-5 footprint, and so the corresponding footprint field should be set to (for example) TO_SOT_Packages_SMD:SOT-23-5
If a default footprint is not specified, a footprint must be associated with each symbol before placing on a PCB.
Footprint Filters Each symbol also supports a list of footprint filters which specify allowable footprints for the symbol.
Footprint filters use the asterisk (*) symbol as a wildcard to allow matching various footprint names. This allows matches for variants of the same footprint e.g. SOIC-8* will match SOIC-8 and SOIC-8_HandSoldering.
For example MCP6004 is available in DIP / SOIC / SSOP packages (with the same pinout). To simplify footprint association, each package type can be added as a filter to the symbol:
*DIP*W7.62mm**SOIC*Pitch1.27mm**SSOP*Pitch0.65mm*
Symbols that have a default footprint should still provide a valid footprint filter to allow for alternate versions of the footprint (e.g. hand soldering variant).
Where components have multiple footprint options, a separate symbol should be drawn for each footprint option. Each symbol should have the appropriate aliases added if required.
Exception: Generic symbols can have multiple footprints assigned, but ONLY IF all footprint options are pin-compatible.
Variant Naming
- For symbols specific to a given manufacturer, the symbol name should follow the recommendations of the manufacturer.
- The naming convention for generic symbols drawn to match package variants is to append the simplified package name to the end of the symbol name, e.g.
SOIC-8,DIP-14,QFN-24
As an example, consider the LTC4357. This is available in a 6-pin DFN package and an 8-pin MSOP.
This requires two symbols to be added, which should be named following the naming convention in the datasheet:
LTC4357xDCBLTC4357xMS8
Each symbol should then have the correct default footprint associated.
Hidden Power Pins
While KiCad supports the use of hidden pins, they are not allowed for official KiCad library parts. The current KiCad version (4.x) performs net connection by position only which means that hidden pins can be connected without being obvious to the user. In the general case, hidden pins should be avoided.
One subtle functionality of hidden pins is to connect power pins of multiple components to the same voltage rail, without requiring each connection to be made manually on the schematic. Pins that are marked as special power pins are automatically connected to nets with the same name.
Some libraries (e.g. 74xx.lib) extensively use this feature (these libraries are in need of an overhaul to fix this). Symbols in this library are automatically supplied from the VCC rail, which causes multiple problems:
- Connections are non-obvious
- These logic symbols cannot be powered from separate rails
Hidden power pins such as this are not allowed for KLC compliant symbols.
Pin Stacking
The current KiCad version (4.x) does not support mapping a single schematic pin to multiple footprint pins. While this feature will be present in future versions, there are currently two solutions to this problem:
- Add each pin to the schematic symbol (requires connection of each pin)
- Place all pins in the same location (pin-stacking)
Pins located in the same position in a schematic symbol are all connected to the same net. Connecting to the top pin ensures connection to all other pins (even if they are invisible).
Pin stacking is allowed under the KLC under the following strict conditions:
- Pins all have the same name
- Pins all have the same electrical type
- Pins all have the same graphical style
- Pins are not of the
No Connectelectrical type - Only one pin is visible (all other pins set to invisible)
NC Pins
It can be useful to add NC (No Connect) pins to a symbol and set them to invisible such that they do not clutter the schematic. However, it must be noted that these pins cannot be stacked (as this would connect them together).
For symbols with multiple units that are drawn separately, which share common power pins, an extra power unit should be drawn which is separate from the individual units.
For example, MCP6004 (a quad op-amp) should be drawn as four identical amplifier units with a single power-supply unit having only the Vdd and Vss pins.
This approach should not be taken for single-unit symbols - power pins should in this case be drawn on the same symbol.
3D model files may be submitted to the library if the following requirements are met:
- The submitter has permission to provide the file(s)
- The files can be added to the KiCad library with permissive licensing
- Files are of high quality and low file size
- File types are either STEP or WRL files
- Source files (scripts, or MCAD source documents) are provided to the 3D Model Source repository
- Files are aligned with the corresponding footprints and scaled at 1:1:1
The silkscreen layer is used to show the outline of the the component on the PCB, and mark the position of Pin-1 (where applicable).
The silkscreen layer also contains the component RefDes (Reference Designator) which is used to locate components on the board after assembly. The RefDes must be placed outside the boundary of the component and must be visible after assembly.
For surface mount components, silkscreen should not be placed under the component, as this can result in poor coplanarity between the component and the board.
For through hold components, silkscreen is allowed under the component to assist with hand-loading and orientation of components.
For footprints with Pin-1 or polarization requirements, the silkscreen should mark this location. KLC follows IPC-7351C recommendations for silkscreen polarisation markers (as far as possible).
Some examples of polarisation marking for various footprints are shown below:
The fabrication layer shows the outline of the component, and any special geometric features. The fabrication layer should also contain two text items:
- A second copy of the RefDes, which should typically be centered on the component
- The VALUE of the component
Footprint polarisation should also be included on the fabrication layer. In general for IC devices (QFP / DIP / etc.) this is shown as a bevel on the corner closest to the location of Pin-1. The size of this bevel should be 1mm or 25% of the package size, whichever is smaller. However this may vary depending on the component type.
Some examples of polarisation markings for various footprints are shown below:
The courtyard layer denotes the total board space required for a component. This includes room for insertion of a mating connector, mounting hardware, etc. This layer should contain one (or more, if necessary) closed polygons which define the maximum required footprint space.
If a manufacturer footprint deviates from the "standard" footprints available, then this should be submitted as a separate footprint and marked as manufacturer-specific. In such a case, the naming convention is Manufacturer_MPN.kicad_mod
For example, the 10-pin SON package from Texas Instruments (http://www.ti.com/lit/ml/mpds117k/mpds117k.pdf) should be named Texas_S-PVSON-N10. This naming overrides general naming convention as defined by the KLC.
Sometimes (often!) manufacturers will have specific requirements for a footprint that do not entirely conform to the KLC. A common example is special stencil (solder paste) requirements for certain pads which will throw KLC errors.
In such a case, the specific KLC rules can be ignored (at the discretion of the library team).
When there are multiple variants of a footprint that use the same physical package, all of the footprints should use the same model. This will result in a warning from the KLC scripts which, in this case, may be ignored.
Users should not submit multiple 3D models for slight variations of the same footprint (e.g. a HandSoldering variant of an 0805 resistor should use the same model as the WaveSoldering variant).