Skip to content
This repository has been archived by the owner on Oct 27, 2021. It is now read-only.

Kicad Library Convention

Jump to bottom
Oliver edited this page Nov 1, 2017 · 49 revisions

Deprecated

This version of the KLC is out of date. The KiCad library information can now be found on the official KiCad website. Refer to the new KLC here

KiCad Library Convention

Revision 2.0.12, September 2017
Devised by Carl Poirier, Oliver Walters
With help from members of:
kicad-lib-committers
kicad-developers

This document outlines the requirements for contributing schematic-symbols and footprints to the official KiCad library repositories. Users wishing to submit or update symbols and/or footprints should be familiar with these rules.

If a user believes there should be an exception to a certain rule when submitting a pull request, this will be a matter for discussion with the KiCad library team.

Not all of the rules listed below can apply in all circumstances, and so exceptions can be made at the discretion of the library team, if these exceptions are justified.

If the rules are uncertain on a given issue, users should try to match the convention of existing symbols and footprints when submitting a pull request.

FAQ

There is a list of Frequently Asked Questions which covers library questions that are asked (frequently) when submiting symbols and footprints. It is a good idea to read through those questions before submitting for the first time.

KLC Helper Scripts

There are a set of Python Scripts which can be used to check if a symbol/footprint meets these rules. When a Pull Request is made to the KiCad libraries, the symbols / footprints are automatically checked using these scripts. It can be helpful to run them yourself before submitting a PR, as it will help speed up the merging process.

Note: Not all of the rules are checked by these scripts, and any submissions will still require manual checking by a member of the KiCad library team.

1. General Rules

  1. Writing uses C-style naming with the first letter of each word being capitalized, e.g. Socket_Strip_Straight_2x06
  2. Every acronym has all of its letters capitalized
  3. Manufacturer name is capitalized as normal, using only standard ASCII characters e.g. NEC, Microchip, Wurth
  4. When dimensions are used in part name, they are in millimeters, decimal places separated by a dot e.g. C_Rect_L13mm_W4mm_P10mm
  5. Filename is the same as the part name
  6. Reference fields are prefilled with the reference designator appropriate for the part (IEEE 315-1975)
  7. Filenames, symbol names, footprint names and model names must contain only valid characters, as below:
    1. Alphanumeric characters (A-Z, a-z, 0-9)
    2. Underscore _
    3. Hyphen / dash -
    4. Period / dot .
  8. Library files use Unix-style line endings (LF) rather than DOS-style (CR+LF)

Symbol Libraries

2. Symbol Library Names (.lib files)

KiCad symbol library files (.lib file extension) contain multiple schematic symbols. Library naming should follow the order of elements given below, as far as is practical. Elements should be separated by underscore _ character. Some elements may be omitted if not required, and extra elements should be appended as required.

  1. Manufacturer name e.g. Microchip, Texas
  2. Category or family of parts, e.g. Capacitors, Spartan6, etc.
  3. Extra library features e.g. CMOS

3. Symbol Names

Symbol names should consist of only allowed characters as specified in KLC 1.7. Symbol naming should follow the order of elements given below, as appropriate. Some elements may be omitted if not required, and any other elements added to the end of the list.

  1. Type of symbol (as required)
    1. May be shortened for common components e.g. Conn_ for Connector
    2. Reference designator may be substituted for common parts e.g. D, C, LED (IEEE 315-1975)
  2. Add the manufacturer name if it is required to differentiate from other similar parts
  3. Manufacturer Part Number (MPN) should be given preference, unless the symbol is generic
  4. Part number, including extension for specific footprint (JEDEC for common devices, e.g. 1N4001)
  5. Any modification to the original symbol, indicated by appending the reason e.g. different pin ordering Q_NPN_EBC, Q_NPN_BCE
  6. Indicate quantity of elements for symbols arrays e.g. resistor array with 8 elements: Resistor_x8

Further information on symbol naming is available in the Frequently Asked Questions.

4. General Rules for Symbols

  1. Pin placement
    1. Using a 100mil grid, pin origin must lie on grid nodes (IEC-60617)
    2. Pins should have a length of at least 100mils (2.54mm)
    3. Pin length should not be more than 300mils (7.62mm)
    4. Pin length can be incremented in steps of 50mils (1.27mm) if required e.g. for long pin numbers
    5. Shorter pins may be allowed for simple symbols such as resistors, capacitors, diodes, etc
  2. Symbol visual style
    1. Origin is placed in the middle of symbol
    2. Symbol body has a line width of 10mils (0.254mm)
    3. Fill style of symbol body is set to Fill background
    4. IEC-style symbols are used whenever possible
  3. Pin stacking. Placing pins in the same position results in the circuits being connected. Pins may be placed in the same location under certain circumstances:
    1. Pins must not be of type No Connect
    2. Pins are logically connected in the symbol
    3. Pins must have the same name
    4. Pins must have the same electrical type
    5. Only one pin must be visible (all others set to invisible)
    6. Stacks of type Output, Power Output and Power Input are special cases. One visible pin must have the correct type, and all other pins in the stack must be passive and invisible.
  4. Pins should be grouped logically, rather than physically
    1. Pin location should not necessarily follow footprint pinout
    2. Pins with similar functions should be placed together, e.g. SPI_MISO, SPI_MOSI, SPI_SCK, SPI_CS and UART_TX, UART_RX
    3. Ports should be ordered from top to bottom, unless this conflicts with the above requirements
  5. Whenever possible, pins should be arranged by function:
    1. Positive Power pins should be placed at top of the symbol, e.g. Vcc, Vdd, Vin, V+, etc
    2. Negative Power and Ground pins should be placed at the bottom of the symbol, e.g. GND, Vss, V-, etc
    3. Input/Control/Logic pins should be placed on the left of the symbol, e.g. opamp +/-, NPN base, SPI pins on an DAC, transformer primary, UART Tx/Rx pins, etc.
    4. Output/Controlled/Driver pins should be placed on the right of the symbol, e.g. opamp output, DAC output, transformer secondary, RS232 Tx/Rx, etc.
  6. Pin Electrical type should be set to match the appropriate pin function
    1. Power and Ground pins should be set to either POWER INPUT or POWER OUTPUT
    2. Other pin types should be set as appropriate
  7. Hidden connection pins are not allowed for schematic symbols
    1. All symbol connection points must be visible
    2. No hidden power pins (e.g. for logic gates)
    3. As an exception, unused pins should be named NC, electrical type Not Connected and should be Invisible
  8. All text fields use a common size of 50mils (1.27mm)
    1. Value field
    2. Reference field
    3. Footprint field
    4. Datasheet field
    5. Pin names and numbers
  9. Default symbol fields contain the correct information
    1. The Reference field contains the appropriate Reference Designator (RefDes) and is visible.
      1. For power-flag symbols (e.g. +5V, GND) the RefDes must always be #PWR (with leading # character)
      2. For graphical symbols (no pins or footprint) the RefDes must be set to #SYM and must be invisible.
    2. The Value field contains the name of the symbol and is visible. (Exception: For power and graphical symbols, the value field must be invisible)
    3. The Footprint field is filled according to rule 4.12 (below) and is invisible
    4. The Datasheet field is left blank and is invisible
    5. The symbol contains no other custom fields
  10. Part meta-data is filled in as appropriate. This meta-data is stored in the <libname>.dcm file, and must be filled in for each symbol and each of the symbol's aliases
    1. Description field contains comma-separated device information
      1. For symbols with a default footprint, the human-readable footprint name should be appended to the description e.g. SOIC-8
    2. Part name should not be included in the Description field
    3. For parts with different symbols associated with different footprints, shortform footprint name should be specified in the description field (e.g. DIP8)
    4. Keywords field contains space-separated keyword values
    5. Documentation field contains URL to part documentation if applicable, or is left blank
  11. Footprint association
    1. The footprint field should be set to invisible
    2. For components with a single default footprint, the Footprint field is filled with a valid entry of the format Footprint_Library:Footprint_Name
    3. For components with multiple possible footprints, the Footprint field should be left blank
    4. Footprint filters should be added as appropriate to match all possible footprints (see KLC 4.13 below)
    5. Filters should be used even if a default footprint is given
    6. The footprint field should be empty for power and graphical symbols
  12. Footprint filters should match all appropriate footprints
    1. Filters use * wildcards to match multiple footprints e.g. TO*220* matches TO220, TO-220_Reverse, TO-220-5
    2. Filters should end with a * wildcard to allow matching of modified packages e.g. _HandSoldering
    3. Filters should not match the pin count - this is performed by KiCad's internal footprint association
    4. Filters should match dimension information (where required) to be as specific as possible, e.g.
      1. DIP*W7.62mm* to match DIP-22_W7.62mm and not a DIP-22 with different width
      2. SOIC*3.9x8.7mm*Pitch1.27mm* to match SOIC-14_3.9x8.7mm_Pitch1.27mm
  13. Power-Flag Symbols
    1. Power-flag symbols are designated by setting Reference field to #PWR
    2. Contain exactly one pin, which is invisible, and must be set to electrical type Power Input
    3. Pin name must match the symbol name
  14. Graphical Symbols
    1. Reference field must be set to #SYM and must be invisible
    2. No pins or footprint association

Example Images:



Footprint Libraries

5. Footprint Library Naming Conventions

Each footprint library is a directory with the .pretty extension. Footprint libraries contain multiple footprint files with the .kicad_mod extension.

  1. Footprint library organisation:

    1. Footprints are organised firstly by package type or function e.g. QFN or Potentiometers
    2. Larger libraries may be further divided by sub-type e.g. Resistors_SMD or Resistors_THT
    3. Manufacturer specific libraries are named Type_Manufacturer e.g. Connectors_JST

  2. Footprint library naming

    1. Library name elements should be separated by underscore _ character
    2. Library name elements should follow the ordering below (elements can be added or omitted as appropriate)
      1. Library type e.g. Resistors, Capacitors, Connectors (should be in plural form)
      2. Package type e.g. SOIC, SMD, THT, QFN, etc
      3. Manufacturer
      4. Extra library features

Note: Not all naming elements above will be necessarily used, and extra naming elements may be required. Some examples of library names are below:

  • LEDs.pretty
  • Connectors_Hirose.pretty
  • Housings_SSOP.pretty

6. Footprint Naming Conventions

Each footprint is specified in a .kicad_mod file within the .pretty directory. Footprint naming should follow the order of elements given below, as far as is practical. Elements should be separated by underscore _ character. Some elements may be omitted if not required, and extra elements may be appended as required.

  1. Specific package type first, not separated by anything e.g TSSOP, C
  2. Package name and number of pins are separated using a hyphen. e.g. SOT-89, SOT-23-5. Variation from standard package is included here e.g. Exposed pad under package: QFP-48-1EP
  3. Package dimensions specified as widthxheight e.g. 3.5x2.0mm
  4. Pitch specified in mm e.g. Pitch1.27mm
  5. Orientation e.g. Horizontal, Angled, etc
  6. Any modification to the original footprint, indicated by appending the reason:
    1. e.g. Longer pads used to facilitate hand soldering of a QFN component: QFN-52_HandSoldering
    2. e.g. Thermal pad designated with ThermalPad

Note: Manufacturer specific footprints that deviate from the above naming convention should be named as follows: Manufacturer_FootprintName e.g. Texas_S-PVQFN-N48

7. General Rules for Footprints

  1. Follows datasheet recommendation unless intentional variation, for example longer pads for hand soldering
  2. Pin-1 should be placed at the top-left. Where this is impractical, it should be placed closest to the top (IPC-7351)
  3. Silkscreen Layer (IPC-7351C)
    1. Reference Designator is supplied on F.SilkS layer
      1. Text size = 1.00mm
      2. Text thickness = 0.15mm
      3. Must be fully visible after component placement
    2. Silkscreen clearance
      1. Silkscreen must not be placed over pads or areas of exposed copper
      2. Silkscreen-pad clearance must be at least 0.2mm or greater than the pad-mask-expansion (whichever is greater)
    3. For SMD components, silkscreen is completely visible after board assembly (must not be under component)
    4. For THT components, silkscreen outline must be visible after board assembly. Silkscreen may be added under component to aid in assembly
    5. Silkscreen line width is 0.12mm (0.1mm is allowed for high density, 0.15mm for low density) - IPC-7351C
    6. Pin-1 designator is provided on Silkscreen layer where appropriate
    7. Pin-1 designator must always be visible after board assembly
    8. Pin-1 designator should follow IPC-7351C where possible
  4. Fabrication Layer
    1. Component value (footprint name) should be provided on F.Fab layer
      1. Text size = 1.00mm
      2. Text thickness = 0.15mm
    2. Component outline should be provided on the appropriate F.Fab layer
      1. Outline uses line width of between 0.10mm and 0.15mm (recommended 0.10mm)
      2. Outline should be simplified for complex shapes
      3. Pin-1 designation is provided on F.Fab layer where appropriate
    3. Reference Designator should also be provided on F.Fab layer
      1. Centered on component (inside component outline)
      2. Size of text matched to component size (should fit inside component outline)
      3. Recommended text size = 1.00mm
      4. Allowable text size = 0.1mm to 2.00mm
      5. Allowable text thickness = 0.01mm to 0.20mm (should be approximately 15% of text size, with allowances for variation for aesthetic reasons)
      6. To get second instance of RefDes, add text labeled "%R"
      7. Rotation of second RefDes should be aligned with the major axis of the component outline
  5. Courtyard Layer (IPC-7251, IPC-7351C)
    1. Footprint courtyard is provided on the F.CrtYd layer
    2. Courtyard uses 0.05mm line width
    3. Courtyard lines are placed on a grid of 0.01mm
    4. Clearance is measured from exterior of pads and package outline
      1. Default courtyard clearance is 0.25mm
      2. Components smaller than 0603 should have a clearance of 0.15mm
      3. Connectors, canned capacitors, crystals, should have a clearance of 0.5mm
      4. BGA footprints should have a clearance of 1.0mm
  6. Footprints should not be duplicated to match a different pin ordering. This is to be handled in the symbol libraries.
  7. Footprints that contain multiple pads or other conductive elements that are physically connected require special attention:
    1. Multiple pads that are physically connected must share the same number
    2. Thermal vias (if present) must share the same number as the thermal pad
    3. If thermal vias are used, a copper pad on the B.Cu (bottom copper) layer should be added. This pad must be at least large enough to fully surround all thermal pads with a margin of >= 0.5mm. Note: If the footprint datasheet gives a conflicting suggestion here, the datasheet should be given preference
  8. Keepout Areas - until KiCad has a native method to define keepout areas within a footprint, keepouts should be defined as follows:
    1. Area shape should be drawn on the Dwgs.User layer
    2. Area should be diagonally hatched
    3. Descriptive text can be added on the Cmts.User layer

8. Rules for Surface Mount Devices (SMD) Footprints

The following rules apply specifically to SMD footprints (the general rules in section 7 also apply).

  1. Footprint Placement type should be set to Surface mount
  2. Footprint anchor should be placed in the middle of the footprint (IPC-7351). Generally this is the centroid calculated with respect to the device lead ends.
    1. If the datasheet specifies an origin for Pick-and-Place, this should be used in preference.
  3. Pad construction for SMT pads has two options:
    1. Normal pads for device pin/lead connections should use the following layers:
      1. Front Copper (F.Cu)
      2. Front Mask (F.Mask)
      3. Front Paste (F.Paste)
    2. Pads which require specific stencil opening shape and aperture design (e.g. thermal pads)
      1. Construct copper shape with pad(s) which use only F.Cu and F.Mask layers
      2. Add required stencil opening(s) with pad(s) which only use F.Paste layer, and do not have a pad number

Note: The layer requirements for surface mount pads often require adjustment based on paste/stencil requirements. The manufacturer datasheet should be followed in preference to these layer suggestions if there is a conflict.

Example Images:

9. Rules for Through Hole Technology (THT) Footprints

The following rules apply specifically to THT footprints (the general rules in section 7 also apply).

  1. Footprint Placement type should be set to Through hole
  2. Footprint anchor should be set on Pin-1
  3. Pin-1 should be set to rectangular, and other pads circular/oval. Exception: Non-polarised parts (e.g. THT resistors) do not require rectangle for Pin-1
  4. Pad layer settings:
    1. All copper layers
    2. Front Mask (F.Mask)
    3. Back Mask (B.Mask)
  5. Minimum drilled hole diameter is the maximum lead diameter plus 0.20mm (IPC-2222 Class 2)
  6. Minimum annular ring width should be at least 0.15mm (IPC-2221)

Example Images:

10. Footprint properties

  1. Footprint name must match its filename. (.kicad_mod files)
  2. Footprint meta-data should be filled in as appropriate
    1. Documentation field contains comma-separated device information. Where appropriate, URL to footprint datasheet should be included
    2. Keywords field contains space-separated keyword values
  3. Other properties should be left to default values, unless required for a specific reason e.g. datasheet specification
    1. Move and Place: Free
    2. Auto Place: 0 and 0
    3. Local Clearance Values: 0
  4. 3D Shape files should be named the same as their footprint and are placed in a folder named the same as the footprint library replacing the .pretty with .3dshapes
    1. Only WRL files are allowed (.wrl)
    2. PATH prefix ${KISYS3DMOD}/ is recommended
    3. Variations of the same footprint can refer to the same 3D model (e.g. R_0805_HandSoldering should use the same 3D model as R_0805)
    4. 3D model references should be added even if the model does not yet exist (this helps with library maintenance)
    5. 3D models should be scaled 1:1:1

Example Images:

Changelog

Revision 2.0.12 - 7 September 2017

  1. Fixed typo in 3.3
  2. Added clarity to 7.3

Revision 2.0.11 - 6 September 2017

  1. Added extra information to 7.7 re: thermal vias
  2. Added extra information to 8.3 re: required layers for stencil design

Revision 2.0.10 - 4 August 2017

  1. Reduced minimum text size requirement for F.Fab RefDes

Revision 2.0.9 - 31 July 2017

  1. Added section about keepout zones

Revision 2.0.8 - 24 July 2017

  1. Added extra information for Silkscreen clearance
  2. Removed redundant rule information (3.3 / 3.7)
  3. Fixed formatting issues for 1.8

Revision 2.0.7 - 9 July 2017

  1. Added rule for Unix-style line endings

Revision 2.0.6 - 30 June 2017

  1. Added exception description for solderpaste / stencil requirements

Revision 2.0.5 - 28 June 2017

  1. Improved wording for RefDes text size requirement

Revision 2.0.4 - 22 June 2017

  1. Updated symbol naming information

Revision 2.0.3 5 June 2017

  1. Added rules for power-flag symbols

Revision 2.0.2 4 June 2017

  1. Added extra rule for pin-stacking

Revision 2.0.1, 23 May 2017

  1. Specified only WRL 3D models allowed

Revision 2.0, April 2017

  1. Major rearranging / improvement of KLC
  2. Added introductory text and link to kicad-library-utils
  3. Separated rules for THT and SMD footprints
  4. Added rules for Footprint Filters
  5. Added examples for many rules
  6. Improved readability for rules, added bullet-points
  7. Added example images for some rules

Revision 1.1, October 1st 2016

  1. Specified IPC-7351C dimensions for silkscreen, courtyard and reference designator

Revision 1.0, November 15th 2015

  1. Fixed some repetition
  2. Added rule 3.8 from the checklib scripts
  3. Tagged as 1.0 for the KiCad 4.0.0 release

Revision 0.11, April 6th 2015

  1. Updated rule 1.4 about dimensions. Units in millimeters are now implicit

Revision 0.10, March 1st 2015

  1. Moved the footprint value property to the fabrication layer
  2. Pin length is enforced only for black-box symbols
  3. Some reorganization has been done

Revision 0.9, February 14th 2015

  1. Added section and rules about footprint properties
  2. Specified the path to 3d models
  3. Moved the reference fields rule to the general section

Revision 0.8, January 19th 2015

  1. More thorough rule about courtyard has been split over 6.6 and 6.7

Revision 0.7, September 18th 2014

  1. Added rule 6.6 for courtyard

Revision 0.6, September 14th 2014

  1. Specified in 6.8 that value and reference designators must be placed on silkscreen

Revision 0.5, August 6th 2014

  1. Specified in 6.5 that only the outline must be completely visible after assembly
  2. Rule 3.8 moved from section 1 since it pertains only to symbols

Revision 0.4, July 30th 2014

  1. Completion of convention for symbols
  2. Rule 6.7 moved from section 1 since it pertains only to footprints

Revision 0.3, June 8th 2014

  1. Specified that pin ordering duplicates are to be handled in symbol libraries
  2. Specified the rules for footprint silkscreen

Revision 0.2, May 19th 2014

  1. Minor clarifications to few items
  2. Exposed pad is now considered as a variation of a package, thus separated by hyphen instead of plus sign
  3. Added 2-level numbering

Revision 0.1, May 8th 2014

  1. Initial Commit

These Wiki pages can be edited directly only by the KiCad Library owners and maintainers.

If you are not a member and want to add or edit something please clone Wiki pages to your Git repository and prepare merge request. Your request will be reviewed and included as soon as possible.

Clone this wiki locally