klc.kicad.orgFull KLC - Library Conventions | KiCad

EDA Library Conventions | KiCad EDA Version 3.0.43 Library maintainer rules & guidelines KLC Home KiCad Revision History The KiCad Library Convention (KLC) is a set of requirements for contributing to the official KiCad libraries. Users wishing to submit or update library files should be familiar with these guidelines. The KLC are a set of guidelines , rather than rules . Electronic component libraries are diverse and complex, and exceptions can be made at the discretion of the library team. Where the KLC deviates from a particular datasheet or manufacturer recommendation, the datasheet should take preference unless there is a good reason not to do so (which should be clarified by a librarian). Where the KLC is unclear, users should attempt to match the convention of existing library components, or seek further clarification. Refer to the contribution guidelines for introductory information on contributing to the KiCad libraries. KLC Helper Scripts The KiCad library team has developed a set of Python scripts which can be used to help test if library components conform to the KLC requirements. When a merge request is made to the libraries, the contributed files are automatically checked using these scripts. It can be helpful to run these scripts on your local machine before submitting a PR, as it will help speed up the process of merging your contribution(s) into the library. To run the footprint checker script, for instance, cd into the "kicad-library-utils/klc-check" directory, then run the Python script ./check_footprint.py path_to_fp1.kicad_mod path_to_fp2.kicad_mod -vv . This will carefully check your footprint according to the KLC requirements laid out below, notifying you of any discrepancies, errors, or violations. See more usage examples in the readme at the link above. Note: While many of the KLC guidelines are checked by these scripts, there are some which are not covered. Additionally, any PR requires manual checking by a member of the library team. General Library Guidelines The general library guidelines apply to all library elements (symbols / footprints / models / templates / 3D models). However, these guidelines may be overridden in some cases by specific exceptions described in further sections. G1 - General Guidelines G1.1 Only standard characters are used for naming libraries and components Filenames, symbol names, footprint names, model names, 3D model names, and template names must contain only valid characters, as determined below: Alphanumeric characters ( A-Z , a-z , 0-9 ) Underscore _ Hyphen / dash - Period / dot . Comma , Plus symbol + This character set ensures that symbols will be compatible with all filesystems, and will not cause any issues due to character rendering. Further, filenames and symbol names must not use the space character . This can cause issues with string escaping and is best avoided. G1.2 Each library is limited to 250 items Libraries with more than 250 items can result in long library loading times. Additionally, such broad categorization of components means that it can be hard to locate a particular component in the libraries. A library size limit of 250 items ensures that libraries are quick to load and components are easy to locate. If a given library exceeds 250 components, it should be split and further subcategorized according to component functionality. G1.3 Libraries are organized by functionality Rather than grouping components (e.g. symbols, footprints) by their manufacturer, KiCad libraries are organized by component functionality. This grouping strategy has a number of key benefits: Similar components are grouped together, allowing alternative parts to be easily substituted If possible, symbols should be derived from existing symbols to reduce library size Generic parts which are produced by multiple manufacturers are supported Library organization should follow the general form as described below, with each element separated by the underscore ( _ ) character: Library function Library sub-function Tertiary qualifier Manufacturer name Component series name Extra library descriptors Note: Some of the elements listed above may be omitted if not required. For specific examples, refer to the guidelines for organizing symbol libraries and footprint libraries . G1.4 English language should be used throughout libraries KiCad software is used by people who speak many different languages. The KiCad software provides translations for these languages, but the library files do not provide translations . Library files should be written using English, excepting where specific component names are non-English (for non-English manufacturers). Where potential differences in spelling and grammar exist, American English should be given preference. Color instead of Colour G1.5 Plural naming is to be avoided In general, plural naming (e.g. for libraries) should be avoided, as pluralisation of some words is inconsistent. Non pluralized names should be used in preference: Sensor_Temperature instead of Sensors_Temperature Memory_Flash instead of Memories_Flash TerminalBlock instead of TerminalBlocks G1.6 Capitalization conventions Acronyms should be capitalized MCU (microcontroller) FPGA (field programmable gate array) Manufacturer names should be capitalized according to the manufacturer Microchip ROHM Texas NEC Unless separated by delimiters such as _ , - , . , words should be separated using CamelCase convention, with the first letter of each word capitalised TestPoint BatteryHolder G1.7 Library files use Unix style line endings Library files must always be commited to GitLab using Unix-style line endings. This means that lines are terminated using the LF (line feed) character, rather than the DOS style CR+LF line endings. KiCad library files must be compatible across multiple operating systems, and users should be able to contribute without generating unnecessary noise in the files by constantly changing line endings. When using the KiCad libraries on a Windows PC, the line endings in the library files may be automatically converted to CR+LF . This is fine, as long as any contributions made to the libraries observe the LF line ending requirements. This issue is addressed by insisting that all KiCad libraries include a .gitattributes file. This file ensures that the line endings are automatically converted by Git. An example of a simple .gitattributes file which ensures footprint files have correct line endings is as follows: *.kicad_mod text=auto Note: The KiCad library repositories should already have the correct .gitattributes file in place to achieve this G1.8 Contributions to the official library must be made using the current stable version Contributions of library assets must be created in the latest stable version of KiCad. This is to avoid problems caused by changes in how assets are stored in different versions of KiCad. (Changes in how line ordering is determined, how strings are escaped, etc.) Another reason is to avoid including features not supported by the latest stable release. G1.9 Dimensional units When specifying a dimension (e.g. in a footprint name) the units must always be provided: 3mm - millimeters 1in - inches When specifying areas or volumes, the coordinate order is X-Y[-Z] , which is equivalent to width-height[-thickness] . When specifying multidimensional units (e.g. width x height x thickness ) then the units only need to be appended once 3x4x7mm - 3mm x 4mm x 7mm Metric units are preferred, where appropriate Linear dimensions should be specified in millimeters Angular dimensions should be specified in degrees Temperature should be specified in degrees Celsius G2 - Generic and Fully Specified Symbols G2.1 Definition of terms: Generic and fully specified symbols KiCad has two workflows regarding what a symbol represents and when it is assigned a footprint. It can be done in the library in which case the symbol represents an exact part or using the "Assign Footprints" tool at the...