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.
The symbols in the KiCAD library can be roughly categorized into two types:
- Generic symbols - these symbols do not have an associated footprint. They can be matched to compatible footprints as appropriate. They are not not associated with a particular manufacturer part number (MPN).
- Atomic parts - these are fully defined parts, with a defined footprint and associated with a unique part number.
Generic symbols allow flexibility in the design workflow. These symbols can be first added to the schematic, and the footprint selected before PCB layout. Using generic symbols allow a small number of library elements to represent a large number of possible components.
An example of the use of generic symbols is the Resistor and Capacitor symbols present in the KiCAD library. These symbols do not have an assigned footprint, as there are many possible footprints that are compatible. They also do not have a defined MPN as there are millions of matching part numbers.
Footprint Filters
The symbol should provide a list of wildcard filters which match the compatible footprints for that symbol. These wildcard symbols use ? and * characters to designate search patterns, where ? matches a single character and * matches multiple characters.
e.g. for a resistor, one such filter would be R_*.
Atomic parts completely define a unique part, matching a schematic symbol to a single unique footprint. An atomic part should be associated with a manufacturer part number.
Associated Footprint
An atomic part must have an associated footprint (which is present in the footprint libraries).
MPN Naming
Atomic parts should be named according to the manufacturer part number.
Footprint Variants
For parts that are available in different footprints, a unique part should be created for each variant. These variants should be named according to the manufacturer datasheet.
Parameter Variants
For parts with variations of operational parameters (e.g. voltage output of a linear regulator family), an ALIAS should be created for each variant. These aliases should be named according to the manufacturer datasheet.
Avoid Overspecification
Some elements of the MPN can be ignored when creating a part ALIAS as described above. For example, the packaging of the part (tape / reel / etc) may be ignored to reduce library clutter. In such a case, the relevent characters in the part name can be replaced with a 'wildcard' character e.g. x.
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.
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 a first example, consider LTC4357 which 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.
Another example is when two equivalent parts have different MPNs. On Semi MC33078P and ST MC33078N are both versions of the same dual opamp in a DIP8 package, but they have different MPNs.
In this case, the symbol should be named MC33078N with MC33078P as an ALIAS. Both MPNs will then be in KiCad and allow selection of either MPN.
The last example is when a part has different pinouts in the same package. MCP6566 is available with 3 different pinouts all in the same SOT-23-5 package.
Three symbols should be created, named MCP6566, MCP6566R, and MCP6566U. The pinouts will all be different and, if neither has an ALIAS, they can each be assigned the same default footprint.
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 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)
Caveats
Pin stacking should be treated with care, and the following extra conditions must be observed:
When stacking Output, Power Output or Power Input pins, only one pin can be used with this electrical type. Other stacked pins must be set to Passive (and made invisible). This is because multiple output and power pins connected to the same net will cause ERC issues.
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).