RFC - Symbol Naming Guidelines

[SchrodingersGat]

This issue follows on from #1386

Some references:

• Major fixes to linear library #1081
• Schematic library organization improvements #1082

[SchrodingersGat]

@evanshultz - Is there a desire by Wayne or someone else to make the KiCad library atomic? If there's a future plan then it might be good to get ready now. The references above don't talk about that and I did hear Wayne mentioning at FOSDEM that there could be plugins for Digi-Key or other vendors in the future. In that case, the KiCad library would only need to be (but wouldn't have to be) generic parts.

AFAIK there is no such push from above to have atomic libs. There is a push from all of us to have libs that are at least consistent and have a solid policy behind them.

To me, a fully atomic library part would have exact order codes, temperature rating, etc. This would quickly bloat the libraries.

Perhaps with the new library format we could support this using "VARIANT" functionality. i.e. we have a part say MCP2551_SOIC that has underneath it all the possible variants.

If we look at the basic requirements for a fully-defined library part, we need the following:

1. A schematic drawing for the part
2. A PCB footprint for the part
3. The pinout must match the footprint exactly
4. The symbol name must indicate the footprint type in some fashion, if options exist

There are some symbols that do not need to indicate the footprint style as there is only a single option. The ADM3053 only has one compatible footprint. This could be added to the library simply as ADM3053

Conversely, a symbol such as the MAX232 is available in different footprints (and different manufacturers!) This presents a more tricky case.

It doesn't matter if a part is offered by different manufacturers if the pinout is the same. If we go with using standard package suffix, we could e.g. have

• MAX232_DIP
• MAX232_SOIC

However if the pinouts vary between manufacturers, you could prefix the manufacturer name:

• Texas_MAX232_DIP

I do agree (mostly) that such a format allows for greater generalisation and means that the library policy is much easier to write and police.

e.g.

Each device must have a unique symbol for each possible package, where the package name is appended to the generic MPN

However, as @evanshultz notes:

Where is broke down for me (unfortunately, I was happy until then) were when I was fixing up linear.lib and got to parts like MCP6566 where the same package can have different pinouts.

In the case of the MCP6566 (and there are many cases like this).

I would suggest the following unique symbols

• MCP6566 - with no default FP, filters for SOT-23-5 and SC-70-5
• MCP6566R - with SOT-23-5 footprint associated
• MCP6566U - with SOT-23-5 footprint associated

1. The R/U variants only have one package option. Job done.
2. The MCP6566 has two package options. We could use filters here to allow both as they are pin compatible

(This is specific to this particular case. In cases where there is ambiguity there would need to be some discussion by the librarians - that's why we're here!).

For devices that have truly incompatible footprints, then you would have to add the footprint suffix.

e.g.

• LTC2850_DFN
• LTC2850_MS8

I am coming around to the idea of having a standardized footprint name and then letting the user select the exact MPN when it comes to BOM selection.

What do ya'll think of this summary?

[SchrodingersGat]

Looks like everyone is asleep - my turn again!

I much prefer to organise the libraries by function first (much as it is done currently). I think there should be more granularity in the libraries e.g. adc-dac.lib becomes adc.lib and dac.lib

We should map out a set of library files that we want, based on the current set which is mostly good.

When libs become too large, or start to specialize too much, we should break them off into (e.g.) manufacturer subsets.

e.g.

• display.lib <- general display symbols
• display_7seg.lib <- 7-segment displays

e.g.

• linear-reg.lib <- linear dc-dc regulators
• linear-reg_Texas.lib <- Texas Instruments linear regulators

i.e. function takes preference over manufacturer.

As part of this, the contents of each type of library needs to be identified. Currently there is no way of doing this natively in KiCad. I would like to see a description next to each library. That's one for the developers, I think.

TL;DR - libraries should be sorted by function

Note: Currently we have a lot of libs such as Microchip_pic18mcu.lib - I would argue that this too is an example of sorting by function!

[SchrodingersGat]

Variant Naming

It pays to consider a specific case when thinking about how footprint variants are handled. Let's look at the LTC3621.

This is a DC-DC switching converter with:

Two package types

• DCB (DFN)
• MS8 (MSOP)

Three output voltages

• 3.3V
• 5.0V
• Adjustable

Two switching frequencies

• 1.00MHz
• 2.25MHz

Two temperature ranges

• -40 to +125 (Automotive)
• -40 to +150 (Extended)

That's a lot of combinations. I don't think there exists a set of math equations to even solve for that.

If a user wanted to go ahead and add an alias for each of those options, that would be a great benefit to the libraries. But, I don't think that every contributor would want to do that. And, where do we draw the line?

Bare minimum, there needs to be two symbols in the library for the LTC3621 part, one each for the MSOP and DFN versions.

We could either name them according to the manufacturer naming:

• LTC3621_DCB (DFN)
• LTC3621_MS8E (MSOP-8)

Advantages

1. Matches datasheet
2. Manufacturers often have unique packages anyway, and their naming does not match standard naming convention

Or

• LTC3621_DFN
• LTC3621_MSOP

Advantages

1. Consistency between manufacturers

Either choice requires the same number of library symbols.

I think it is easier to enforce that each symbol only gets a unique symbol for each footprint, not for the other options (e.g. frequency / temp / etc). There are millions of combinations and either we draw the line in the sand here, or we argue about it on each submitted PR.

At the end of the day, a user can select the LTC3621 symbol, insert into the schematic, and then rename it to LTC3621IDCB#PBF if they so choose.

[SchrodingersGat]

If we want to make a concerted effort to improve the maintainability and documentation for the libraries, we could make a kicad.github.io page. I have integrated these for a couple of projects and they're very nice to use.

Why?

1. More flexible than the Wiki pages
2. Hosted from our github account
3. Presents a much more professional landing page for the libraries. Having a webpage would make them seem more legitimate, I feel.

Versioned Library Releases

Each library release could be added to a "Downloads" page - for improved user visibility.

This means that users can download a snapshot of the libs at a stable release point.

Library Browsing

We could (with the help of scripting) host a directory-tree-view of the available libraries. Github page are statically generated but we could rebuild them each time a PR is merged into the symbols or footprint libraries. Then we could generate example images of each footprint / symbol and present them as an overall snapshot of what is in the libraries at any time.

Documentation

We need a lot more documentation on the following:

• What's in the libraries
• How the libraries are organized
• How to get the libraries
• How to keep the libraries up to date
• How to contribute to the libraries

Each of these could have its own page with in-depth examples.

Thoughts?

[jkriege2]

Good morning around the globe @SchrodingersGat (i.e. yes I was asleep ;-)

I mostly agree with what you write above, but with a preference for not using the manufacturer package naming (so we achieve even better stdnardization over the whole lib). Still a few comments on some of the topics:

1. We should also discuss how to wrok with parts like LM317L (http://www.ti.com/lit/ds/symlink/lm317l.pdf), which is available in different 3-pin packages (TO-92, SOT89,...) all with the same pinout and also in different 8-pin-packages (SOIC,TSSOP,...) ... and even some more variants. Do we want one symbol per package (full package granularity), or do we summarize the packages as far as possible (fewer symbols, but possibly long names as e.g. LM31L_TO92_SOT89 + LM317L_SOIC_TSSOP).
2. I like the idea of breaking down the libs ... ideally, if KiCAD would support a description per lib file, it should also support a tag-tree per lib-file. In that tree we could encode the tree structure, e.g. ICs/Linear/OPAMP or ICs/Linear/Regulators/Positive and KiCAD could use that info to populate the component tree with not only two layers (lib+devices), but several layers, built up from the tags, until then we should ensure the file-names are at least remotely human-readable, as the sorting of filenames in the tree already gives such a structure ... only flattened out.
3. We should try and come up with a list of features (maybe component category-dependent) for which we would like to see variants (e.g. voltages for VRegs) an a list for which we never want to see variants (e.g. temperature-ratings for VRegs, RoHS, ...).
4. About the microcontrollers. Somehow I have the feeling they should be see as some kind of special case: Usually one does not select them by function, but you already have a family + manufacturer to use in mind (e.g. PIC18 or AVR or ARM ... in the end you do not only need the component, but usually also their toolchain and tools). Therefore I think the libs for them should be sorted that way (+ a lib to catch all that do not fit anywhere), e.g.:

• Microcontrollers_Atmel_megaAVR
• Microcontrollers_Atmel_tinyAVR
• Microcontrollers_Atmel_classicAVR
• Microcontrollers_Atmel_AVR32
• Microcontrollers_Atmel_ARM_SAM3
• Microcontrollers_Atmel_ARM_SAM4
• ...
• Microcontrollers_Microchip_PIC16
• Microcontrollers_Microchip_PIC18
• Microcontrollers_8051
• Microcontrollers_8048
• Processors_Z80
• Processors_AMD_x86
• Processors_Intel_x86
• ...
  As you see I made two more special cases: We should distinguish between microcontrollers (incl. periphery) and bare Processors (Z80, 80186, ...) in the naming and there are some general variants that are made by several manufacturers (8051s, ...) for those we don't need to split by manufacturer, I think.

What do you all think?

JAN

[suzizecat]

Hi all !

Since all these modifications implies changing libraries and parts names, i think that it should be a system to forward changes made in the libraries to schematics so, when a user load a new version of the libs he won't run into losing all his symbols in already existing schematic and keep pointing to a "real" symbol (not a cached one) but i think that it's for the dev team...

I agree with @jkriege2 with the MCUs libs, and i would suggest that those parts stay atomic since you'll often look for a specific MCU.

Plus, i also think that if we add the package whithin the component name, we should add the standard one if there is one. Therefore, i think that the manufacturer package name should be stated somewhere if needed to clear any misunderstanding, in the description maybe.

PS :

That's a lot of combinations. I don't think there exists a set of math equations to even solve for that.

I believe that it's just about some good old multiplication here 😛

[jkriege2]

Hi @suzizecat !

I don't think having such a forwarding will be possible ... the cached symbols are there exactly for that reason!

Plus, i also think that if we add the package whithin the component name, we should add the standard one if there is one. Therefore, i think that the manufacturer package name should be stated somewhere if needed to clear any misunderstanding, in the description maybe.

Which should we choose as the "standard" package, e.g. for an LM317???
and: So we should keep a double-list of packages? Waht if a symbol stands in for several manufacturer packages? List all those MPNs in the description?

Best,
JAN

[jkriege2]

PS: I will try and come up with an initial proposal for lib-names until tomorrow evening or early next week (or maybe even earlier ... I already started on that) ... maybe we can go on dicussing based on that?

[poeschlr]

Sadly a lot of people to not archive the cache lib (We get a lot of questions regarding that over on the forum.)
I think such a major change should be done with the introduction of kicad 5.x. As a solution we can for example branch the lib and get a new 5.x branch (or branch away a 4.x branch and keep the master branch as the branch where PR are merged into.)

[SchrodingersGat]

@jkriege2

1. We should also discuss how to wrok with parts like LM317L

I would vote for either full package granularity, where possible. It's a step towards atomic parts but without requiring each individual variant. From a design perspective, for bespoke ICs you generally pick the package first (or early in the design).

I would also rather have LM317L_T092 and LM317L_SOT89 rather than LM317_TO92_SOT89 - it quickly becomes messy. What if it matched three footprints, or four? Would we have LM317_TO92_SOT89_SOT23-3_TO-220?

2. I like the idea of breaking down the libs ... ideally, if KiCAD would support a description per lib file,

This would be great but I fear it will not be possible at least not for a while. We should to the best with what we have, and plan for future advancements with the new library format.

3. We should try and come up with a list of features (maybe component category-dependent) for which we would like to see variants

This is a good idea, I think it will be hard to make a ruling on this (but I am happy to be proven wrong!). We could step back and say that one-symbol-per-package-variant is all that we will accept too

---

What we should work towards here is not a complete rework of the libs, but a migration path towards the new features of the improved libraries. If we implement a semi-atomic part strategy where each package variant has its own symbol, then when the new libraries come we can add each variant then - and we'll be well prepared for it.

---

That's a lot of combinations. I don't think there exists a set of math equations to even solve for that.
@suzizecat I believe that it's just about some good old multiplication here 😛

Ah, you got me!

[SchrodingersGat]

Renaming libraries

Any major change should be held off until the next stable release (5.0 would be perfect).

I would ideally like to see the new library files implemented at the same time as merging the footprints. Then we could have the following repos:

• /footprints
• /symbols
• /packages3d

/kicad-library repo would stay for a while (at least a year) marked as deprecated and not accepting PRs - for legacy requirements. Same with all the .pretty repos

@jkriege2 - PS: I will try and come up with an initial proposal for lib-names until tomorrow evening or early next week (or maybe even earlier ... I already started on that) ... maybe we can go on dicussing based on that?

That would be great, and well appreciated - however bear in mind my points above - we cannot enact major change without major thought :)

[SchrodingersGat]

Symbol Naming (Reprise)

I am looking again at the LM317 datasheet.

If we are to create a new naming scheme for package variants, I still think this introduces an unnecessary level of complication.

On p1 of the datasheet we see four unique part numbers:

• LM317DCY (SOT-223)
• LM317KCS (TO-220)
• LM317KCT (TO-220)
• LM317KTT (TO-263)

Here we notice a few things

1. The manufacturer has already specified a coding scheme for the package variants
2. There are two TO-220 options available (how would we encode that?)

Further, a brief look at some other packages shows that not all manufacturers conform to the same package naming. What TI calls a TO-263, another may call something different. So we have to encode some scheme which can accommodate this. If the datasheet says one package but we use a different one, that's going to lead to confusion, at a minimum.

As a product engineer, how do I actually pick the package variant? I (personally) want to go into the selection window and see an option that directly matches the datasheet. I don't want to have to match up the datasheet with yet another naming scheme.

Yes, the manufacturer naming schemes are all different, and all terrible. But let's not add another layer of confusion!

---

For 'generic' parts, I really agree that we should use a standardised suffix such as _SOT-23-5 (etc). But where we are matching to a particular manufacturer datasheet, we should use their numbering.

---

The LM317 example above highlights one big problem with encoding our own scheme. In that datasheet there are two TO-220 packages with slightly different physical dimensions. To encode that (any many similar violations) we would need to allow for such names as LM317_TO220_VariantA or LM317_TO220_W10.36mm.

A user trying to select between the two options based on such names would then have to go back and cross-check with the datasheet anyhow! Using the datasheet naming scheme we avoid that entirely.

[ghost]

First of all you should answer a simple and fundamental question: "If KiCad standard libraries are for hobbyists/one-time-users or (semi-)professionals?".
The hobbyist will be happy when you use for example: LM317L_TO92, LM317L_SO8 (with correct pin association).
The professionals will be very angry, because they need a real, manufacturer part number for their BOM's. Even if they need a simple capacitor SMD 1206 100nF they need full manufacturer code, because using X5R type instead X7R may collapse their project.

Keeping in mind some words of Wayne (somewhere on dev mailing list), KiCad should acquire more attention of professionals.

[SchrodingersGat]

First of all you should answer a simple question: "If KiCad standard libraries are for hobbyists/one-time-users or (semi-)professionals?".

Professional use is what we are targeting. Hobby users will benefit from using quality libraries, whereas professional users will reject hobby-grade libraries out of hand.

The professionals will be very angry, because they need a real, manufacturer part number for their BOM's. Even if they need a simple capacitor SMD 1206 100nF they need full manufacturer code, because using X5R type instead X7R may collapse their project.

We are not going to support all R/C variants for example. Maybe one day, but that would require a much larger library team.

I see the value of atomic parts, and know personally the calamity that can be caused by incorrect part specification. This is always the responsibility of the person designing the schematic.

The KiCad standard libraries should be a launching point for professional design with KiCad. The higher standard we hold the libraries to, the more people will make use of them and contribute back to them.

KiCad should acquire more attention of professionals.

It does! I am of them - which is why I am pushing to have the libraries be improved upon greatly.

[SchrodingersGat]

The major argument for not specifying every single part variant in our libraries is thus:

1. It's a lot of work and we have only limited resources. Also, we're not getting paid.
2. The more data we enter, the more data we are responsible for.
3. Mapping schematic symbols to compatible footprints is close-enough for most applications (especially hobby grade!)
4. "Power users" should 100% check each and every symbol / footprint / MPN / SKU in any case. So it makes just as much sense to specify a generic base part name and then the responsibility for BOM management is passed to the user
5. Many companies use internal part numbering systems anyhow.
6. Part numbers and variants can change - requiring a lot of data management

It's all a matter of effort to reward. I think the discussion on this issue thus far is trending towards a workable solution somewhere in the middle of "useless libraries" and "too much work".

[jkriege2]

The LM 317 also demonstrates a big problem with using the manufacturer suffixes (I copied this from one of the other discussions):

Here's an example: LM317

• http://www.ti.com/lit/ds/symlink/lm317.pdf
• https://www.onsemi.com/pub/Collateral/LM317-D.PDF
• http://www.st.com/content/ccc/resource/technical/document/datasheet/group1/a0/db/e6/9b/6f/9c/45/7b/CD00000455/files/CD00000455.pdf/jcr:content/translations/en.CD00000455.pdf

Naming scheme:

• ST in TO-220: LM317T/LM317BT/LM317T-DG => we might use LM317T
• ST in D2PAK: LM317D2T => we might use LM317D2T
• ON-Semi in TO-220: LM317TG/LM317BTG => this might match ST-standard LM317T
• ON-Semi in D2PAK: LM317D2TG => this might match ST-standard LM317D2T
• TI in TO-220: LM317KCS/LM317KCT => does not match the LM317T of ST!!!
• TI in D2PAK: LM317KTT => does not match the LM317D2T of ST!!!

So, how do we work with this? Is LM317 then a generic part, or do we add all variants? What happens if we have a part that is only later also produced by another manufacturer with other suffixes? Do we add those too?

If we say assigning the correct MPN is a task of the lib-user at BOM stage, then adding generalized suffixes _TO92... still seems to me to be the only managable variant unless we want a large set of rules on how to handle such components ...

Note: I'm more the hobbyist and software-developer ... and I clearly see the benefit in grouping stuff as good as possible (to minimize work and ensure manageability) ... but if that approach is totally unusable to a professional electronics engineer let me know. In that case I feel that also the way that KiCAD is taylored towards a certain process would need to change. Currently it is designed (as I understand it), so you first design the schematic from more or less general parts and only then select the packages, when designing the PCB ...

Best,
JAN

[suzizecat]

Hi @jkriege2 ,

Which should we choose as the "standard" package, e.g. for an LM317???

You misunderstood me when i was talking about "standard FP", i wasn't talking about a "most usual package" but about the standard denomination, reffering to the "Variant Naming" post of SchrodingerGat

For my part, i used KiCAD as hobbyist and now in a professional way, but in a pretty small structure.
I do love having atomic parts in KiCAD because you're sure that your part got the right pin mapping and that you will have the right FP for it.

I got to say that i was stupidly caught in using an IRF9Z34N (a mosfet transistor), didn't found the right pin mapping in the datasheet and assumed it was GDS like other transistors i found when it was GSD (or something equivalent). That was my absolute first real design and it took me 2 mounth to find out where the problem was...
It was totally my fault, but what i'm thinking is that it's waymore conveignent when you can have your exact component in the lib since you wont do that kind of (pretty stupid and unprofessional since i was hobbyist) mistake.

For the LM317 problem, i would think to add the name of the manufacturer somewhere in the part name, but that wouldn't nice to maintain (at all) since it will be hard to have all manufacturers...

Best, Julien

PS :
I got a sneaky trick for ST datasheets, you should try right click the link pointing the DS and use "Copy the link address" (or equivalent) rather than going into the PDF and copying the address bar, then you got http://www.st.com/resource/en/datasheet/lm317.pdf for the LM317 which is way more convenient than their insanely long address...

[SchrodingersGat]

@jkriege2 the LM317 was a poor example choice (on my part) as this is a prime example of where the footprint suffix works really well.

The LM317 (and similar common parts) should be used with a suffix like _TO-220 (etc) as otherwise we need to maintain individual LM317 parts for each manufacturer. Your scheme makes the most sense in this example.

However any footprints where there are multiple pinouts in the same package cause issues. I really do not want to have naming conventions like _TO-220_Variant-B (or similar). Such names do not contain enough information to identify the correct footprint. We need a clear direction for these edge cases.

Let's consider another example - the PIC18F2xkx0 series. Here the PIC18F2xK80 device is available in SSOP/DIPSOIC with the same pinout. This symbol is complicated enough that we don't want to have to duplicate it for each item.

But how do we name it? PIC18F2xK80_SSOP_DIP_SOIC? This looks very messy to me..

Perhaps this problem can be held off until we have the ability to have variants with different footprint association? It becomes a moot point at that stage!

---

With the knowledge that in the future we will have to port our libraries over, and that we will have much more powerful library features, I propose the following:

1. We mandate that new parts must be "atomic" (one symbol for each footprint type) but beyond that they are generic.

2. Part variants should be named in a fashion MPN-BASE_PKG e.g LM317_SOIC or MAX232_DIP

3. These base parts allow users to drop into the schematic and then insert any precise MPN (or internal part number) that they want.

4. When the new library format comes around, we can add variants with multiple parameters, etc, etc

---

I will agree to the above if we can come up with a solution for a naming convention that handles the aforementioned issues:

a) How to deal with a part that has multiple pinout options for the same package?
b) How to deal with a part that matches multiple footprints with the same pinout?

[jkriege2]

Hi! @SchrodingersGat

• a) Hhmmm ... You're thinking about something like MCP601 in SOT23-5 (http://ww1.microchip.com/downloads/en/DeviceDoc/21314g.pdf)? There I would stick to the manufacturer in distinguishing them. Here I would use MCP601_SOT23 and MCP601R_SOT23 ... They list them as MCP601 and MCP601R on the first page of their DS, i.e. the R can be interpreted as part of the base-MPN... But I don't know how other manufacturers do that ...
• b)/PIC18F2xK80_SSOP_DIP_SOIC: yes that's messy, I ran into the same problem, when rworking regul.lib. There are already some symbols there that use this nomenclature ... it's far from perfect, but does what I felt was intended by the KLCs that stood at that point.

As the push for atomic parts seems very strong to me (at least what I see from these discussions), you suggested some allowances above ... but I have no clue how we could formulate them in a concise way and prevent too much clutter ... Did you have a set of concrete rules in mind (especially when to use them exactly)?

Best,
JAN

[bobc]

@SchrodingersGat

The major argument for not specifying every single part variant in our libraries is thus:

There is one other practical issue, KiCad hangs when there are "too many" components in a library. I don't know what the upper limit is, but I tried adding 130,000 atomically defined resistors and that broke KiCad. I cut the number down to about 5,000 and that seemed ok.

That shouldn't stop us from organising the libraries the way we want, just bear in mind we may need some fixes in KiCad code to improve scalability if we start to create really large numbers of components.

[gauravjuvekar]

Okay, slightly off topic here, but is there a reference on the actual file formats and capabilities of S-expression and SWEET fileformats for Kicad 5.x? The closest I could get to was https://forum.kicad.info/t/changes-to-eeschema-and-its-file-format-any-info-dates/3297/10 without actually going into the code.

[SchrodingersGat]

@gauravjuvekar here's what I have:

• https://lists.launchpad.net/kicad-developers/msg23302.html
• https://lists.launchpad.net/kicad-developers/msg27071.html
• https://lists.launchpad.net/kicad-developers/msg06448.html

From the sounds of things there is a large amount of code that has been written but is hidden from the development branch for now.

[poeschlr]

How should we handle part naming until this issue is decided?
(I have a few PR where the "new" style with MPN differentiation is used and some where _package is used.)

[gauravjuvekar]

@jkriege2
Very minor gripe, but what's with the capitalization of the library names?
battery_management.lib vs Power_Management.lib
logic_levelshifters.lib vs logic_Programmable.lib
Oscillators, Quarzes_Filters, Timers
microcontrollers_freescale_* vs dsps_Freescale

Also, about manufacturer names.
dsps_TI vs microcontrollers_texas_*

[jkriege2]

@gauravjuvekar I kept some letter-casing, as usually changing it in a GIT or SVN repository can be a real pain ... especially for windows ;-)

About the others: thanks, I will fix those

JAN

[evanshultz]

Regarding the long _package names such as PIC18F2xK80_SSOP_DIP_SOIC, why not force a limit of only one suffix? However, we know that all these parts can share the same symbol by definition, so there could be one symbol and 2 ALIAS. This would also mean only one symbol to be created and maintained in the library and would be more atomic (if we all like that). Of course, this would only apply to parts with multiple manufacturers to abstract away exact MPN when they conflict (like the MC33078 in DIP example I've given and the ones above).

Regard, the library list above, Jan, I will make a few edits. There are areas of the current and proposed library that appear to have gotten attention and other areas that need help. I suspect because we have different backgrounds and my experience is in a different place.

I also dislike having a library named sensors when that's such a specialized group of parts, for example, and then sensors_temperature, sensors_current, etc. That just allows things to get messy. I would want more qualification there. A one-level library like diode is OK with me, but sensors seems too generic.

I think we should look at this more like a _ system, where we group parts in two levels. For example, classes might be ic and passive and transistor. Here is an incomplete example of how this could look:

Capacitor
Capacitor Network
Common Mode Choke
Conn - Audio - Phono
Conn - Audio - RCA
Conn - Audio - XLR
Conn - Comm - HDMI
Conn - Comm - RJ
Conn - Comm - USB
Conn - DSUB
Conn - Misc - Header
Conn - Misc - Socket
Conn - Misc - Terminal
Conn - Power - AC Inlet
Crystal
Diode
Diode - Voltage Suppressor
Diode - Voltage Suppressor Array
Diode - Zener
Diode Array
Diode Bridge
Display
Encoder
Ferrite
Fuse
IC - ADC
IC - Analog
IC - Analog Switch
IC - Audio - Other
IC - CODEC
IC - Clock
IC - DAC
IC - DSP
IC - Digital - Pot
IC - Ethernet
IC - FPGA - CPLD
IC - Gatedriver
IC - Linear Regulator
IC - Logic
IC - Memory
IC - Misc
IC - Optocoupler
IC - Processor
IC - Reference
IC - SMPS Controller
IC - SMPS Regulator
IC - Transceiver
IC - USB
Inductor
LED
LED Array
Relay
Resistor - Fixed
Resistor - Network
Resistor - Variable
Switch
Switch - AC Power
Switch - Circuit Breaker
Switch - Rotary
Thermistor - NTC
Thermistor - PTC
Transformer - Communications
Transformer - Current Sense
Transformer - Power - Audio
Transformer - Power - Line Frequency
Transformer - Power - Switching
Transistor - Bipolar
Transistor - IGBT
Transistor - JFET
Transistor - MOSFET
Varistor

I'm not saying the above is better but just providing another idea about how things could be grouped. I feel like writing it out is easier to understand than a bunch of text.

[evanshultz]

A bit of work done on the list above, with notes. Perhaps this should actually be a wiki page instead of buried within the body of an issue?

To expand on what I mentioned above, I think all IC libraries should be prefixed with ic. So ic_smps_controller.lib and ic_opamp.lib and ic_interface_rs485.lib and ic_audio_adcs.lib. That's the classification I was describing above. It will pull things together at a higher level and give a much better guide for future people to understand the current libraries and for new libraries to be added.

[SchrodingersGat]

@Gasman2014 - I think a lot of the problems with how the libraries are organised/named could be helped if there were a really good management tool.

Agreed, the KiCad library management tools are a bit lacking. Personally I think the best approach is to improve the internal tools, otherwise it's duplicating effort. We could potentially look to expand the python functionality (currently only in PCB side) that way we can easily extend library tools with simple scripting.

[SchrodingersGat]

@jkriege2 thanks for your library suggestion above - I am opening a new issue to discuss reorganisation of the libs, and I will rename this issue as you suggest.

Please move any discussion to the library rearranging to the new thread

[SchrodingersGat]

@jkriege2 - For common ICs that are provided by different manufacturers we use MPNbase[-param]_PACKAGE, where PACKAGE=TO92,SOIC,TQFP,DIP,TO220,... and -param is optional to cover e.g. voltages/ADJ for voltage regulators. If there are multiple package options with the same pinout, we split these to single-package symbols (although this breaks the workflow behind KiCAD) Which components are generic needs to be checked/defined carefully during review by the librarians !!!

> (although this breaks the workflow behind KiCAD)

I disagree - the workflow behind KiCad allows users to use an atomic part, or to select the footprint from a list of filters. Both are acceptable, and there are cases where each option is the "best" option

> Which components are generic needs to be checked/defined carefully during review by the librarians !!!

Definitely. But it's not an undefined problem - there are obvious cases where a MPN matches multiple manufacturers, and obvious cases where a part is specific only to a single manufacturer.

It is the cases in the middle that will require attention.

As these edge cases become apparent, we can update the contributor guidelines, learning more as we go, and refining the process accordingly.

The world of electronics engineering is way too diverse to be able to have a single convention:

• Easy to use
• Concise
• Generic

(Pick one! :p )

[jkriege2]

OK @SchroedingersGat will you make the required updated to KLC?

cu
JAN

[evanshultz]

I'd like to sum up what I think I understand above. By repeating it in my own words I will hopefully be sure that it's all captured properly in my mind. This is mostly, I believe, Jan's info above with examples added. Please add more contributions or breaking cases or categories I've missed.

I've been working to clean up linear.lib so please forgive me for being focused on the problems found with opamps and comparators. A lot of notes and questions can be found at #1081.

There are several categories of parts. In all cases, some general rules are followed:

• Illegal characters are removed and ignored in symbol names.
• No temperature variants are listed, only the lowest-grade (usually 0-70C) version. Characters in the MPN that indicate temperature are to be replaced with x.
• Similarly, grades of parts are not listed individually. Grade is replaced by x in the middle of the MPN or ignored if at the end of the MPN.
• For ease of library maintenance, symbols may be combined that do not all share the same package. This means FPfilters may contain a large number of entries which don't apply to the symbol and all ALIASes, even though at least one FPfilter will work. The user will choose the appropriate package.
• Package type is always listed in the part description for the libraries DCM file.
• Truly generic parts like passive resistors and capacitors are kept as only generic parts.

Generic (?), compatible parts

The first class is for parts that have several vendors supplying the same part, but the base MPN is sufficient to capture the part type, it's package, and it's pinout. This is the simplest case because a single symbol will cover a large number of possible MPNs.

Examples:

• BC846 would cover NXP, On Semi, and Fairchild. While there are a number of different package options, KLC states that footprints should be used to differentiate instead of multiple symbols, so the footprint pin placement will allow these to be symbol-compatible.
• BAS16 would cover a huge number of vendors and packages of this generic diode well. A range of ALIASes could be added as well, such as BAS21, BAS316, 1N4148, etc. to cover for symbol-compatible packages and types. A large range of FPfilters should be given with no default footprint.

Different part numbers for different packages

This class of part is a generic part made by a number of different manufacturers with seemingly equivalent parts, but which don't share a full MPN for the same pacakage. These part will named using the base MPN followed by a suffix of the base package type. Without adding this extra info, it would be impossible to differentiate the package type or would result in a huge number of ALIAS entries to cover all possible MPNs (which in some case could result in the same MPN from different vendors designating a different package). Many basic opamps, regulators, and comparators fall into this category since these are common parts created long ago and multiple-sourcing has become critical.

Each different package type, even if pinout compatible, will be an ALIAS to avoid long symbol names. An underscore will separate these sections of the symbol name.

Examples:

• On Semi MC33078P and ST MC33078N are both versions of the same dual opamp in a DIP-8 package, but they have different MPNs. In this case, the symbol should be named MC33078_DIP. There could also be MC33078_SOIC, MC33078_SSOP, etc.
• 7805 regulator would be called 7805_TO220 and could cover MC7805, uA7805, L7805, LM7805, KA7805, NJM7805, etc., all in TO-220 (metal tab or plastic-encapsulated) package. LM340x-5 would be a separate symbol even though they're equivalent and share a datasheet.
• LM358 is offered in a number of packages with largely compatible pinouts (though not all vendors offer all package choices). However, ST's LM358 offers a DFN package which will require a 9th pin on the symbol. In this case, one symbol will be named LM358 and cover the bulk of LM358 parts, while another symbol named LM358_DFN will cover for ST's unique package. LM358_DFN will have a default footprint; LM358 will not but it will have an extensive FPfilter selection.
• Similarly, MCP6002 comes two packages that require a different number of pins. Several symbols will need to be created, MCP6002-xMS for MSOP, MCP6002-xP for DIP, MCP6002-xSN for SOIC, and MCP6002-xMC for DFN. The first three can all be the same symbol with two ALIASes and no default footprint. The DFN package will require a unique symbol with a default footprint. This symbol for a dual opamp in DFN cannot be an ALIAS for the dual opamp in DFN package mentioned above, because the DFN MCP6002 has the exposed pad connected to the negative voltage rail pin while the DFN LM358 has the exposed pad floating and not internally connected.

Single manufacturer with fully specified package/pinout/type/etc.

This category is for parts which come from only one company and are unique in the library. In some cases, a manufacturer will offer the same die in the same package but with different pinouts. In this case, the full MPN also differentiates these parts.

Examples:

• LPC11U34FBD48/311 would be LPC11U34FBD48311 (note the / is removed)
• AD797 opamp would have a symbol named AD797. This covers both DIP and SOIC packages as they share the same pinout, so there will be no default footprint but there will be two FPfilter entries. This one symbol also covers the A and B grades of AD797, which the user can hand-modify if they want to add the suffix after placing the symbol on a schematic.
• MCP6566 comes in three SOT23-5 package with 3 different pinouts. In this case, 3 symbols must be created and will be named MCP6001, MCP6001R, and MCP6001U. A default footprint should be selected for the latter two while the first would have no default footprint but two FPfilter entries as it's also available in SC-70-5. MCP6001U could also have an ALIAS for LM321.

[SchrodingersGat]

@evanshultz I think you have done a fine job of outlining the approaches. I have been trying to think of a way to define this in a brief fashion (for the purpose of the KLC / FAQ). Your input here helps with this.

There will be some edge cases where we will need to decide how to handle symbols but for the most part, I think the approaches you have outlined above are very good.

[ghost]

Couple of questions ...

No temperature variants are listed, only the lowest-grade (usually 0-70C) version. Characters in the MPN that indicate temperature are to be replaced with x.
Similarly, grades of parts are not listed individually. Grade is replaced by x in the middle of the MPN or ignored if at the end of the MPN.

Presumably other variations (e.g. voltage output of regulator) are to be handled with aliases, not x? In other words, the current wording in the FAQ still applies? ...

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.

Illegal characters are removed and ignored in symbol names.

Removed, or replaced with -? Taking LPC11U34FBD48/311 as an example, it might be more readable and recognisable as LPC11U34FBD48-311 rather than LPC11U34FBD48311.

[ghost]

Presumably other variations (e.g. voltage output of regulator) are to be handled with aliases, not x?

I think my question got answered here ...

#1474 (comment)
#1474 (comment)

Looks like all operational parameters will be wildcarded / ignored and aliases will not be used for them.

[jkriege2]

I'm not so sure ... did we come to a conclusion on that topic?

JAN

[hvraven]

I don't think that a general removal of all operational parameters is in any way sensible or helpful.

1. It can make it difficult to search for components as one can not simply type in the part number one is interested in. This could be fixed by changing KiCad to treat x as a wildcard (regexp .).
2. There are parts which do not share the same pin layout across all operational parameters. An example I stumbled upon recently is the TPS20xx series. It features multiple currents, but also multiple switches per housing and inverted input logic (the datasheet has a table on the 4th page). All of this is crammed into the last two digits (to further increase complexity there are 5-pin and 8-pin housings, but thats another story).

Of course adding all the required aliases can make the generation of components more time consuming. But most of this comes done to expanding a parameter matrix into a matching part number and description. This could be simplified a lot with better tools to generate those by filling variables.

[poeschlr]

In your example (TPS20xx) nearly no aliases will be required. As far as i see a lot of the mpn numbers will need to be symbols anyways because they have slight differences in functionality, pin numbers, ...
Such parts will always be an exception. (here we might need to add all possible mpns.)

I don't think anyone expects kicad to be a complete catalog for all possible parts. I agree that it would be nice to have a better search functionality though.

Just take ti as an example. Nearly all TI parts exist in industrial specification and in automotive specification.
The automotive specified parts just have a -Q1 suffix to their name. Adding this would mean we have double the number of entries in the lib.
In short there needs to be a clear line drawn what we have in the lib and what we mask with wildcards. If this is clearly documented users can work with that.

[hvraven]

I don't want to argue about automative specification, increased temperature ranges, etc. These are really just minor modifications and should be globbed as already discussed. But current / voltage ranges, for examples for regulators, are something completely different in my opinion. I would like to see them in the library as an alias. Maybe give the create the option to add them if he wants to go for the extra mile.

[hvraven]

I thought a bit more about this issue and got an idea which could fit both approaches (try to be generic vs. be as specific as possible). It would require changes to the kicad code, which I would be interested to do. But I would like to hear some opinions about the idea first.

The rough idea is to allow for a hierarchic structure of schematics. This would allow to have a generic element as a node, where the specialised variants would be leafs below that node. This would allow to choose the generic node if one doesn't care, while still giving the possibility to use the specialised variants (same is true for library maintanance, if one doesn't care about the specialisations one can leave them out/add them later).

To increase the usefulness of this approach I would like to add an optional footprint field to the alias description in the dcm files. This would allow an alias to override the selected default footprint. Then it is easy to have several variants which only differ by the footprint, i.e. SMD size.

I think the hierarchy could be implemented easily by adding an optional field to the descriptions which can reference a parent. This makes the current description a child of the specified parent.

[SchrodingersGat]

@lorem-ipsum that's a great idea - and is already defined as part of the planned .sweet format! Essentially any symbol can "inherit" from a parent. So the idea of generics and variants will be supported right out of the box :)

[hvraven]

@SchrodingersGat cool, that is great to hear. That saves me some work ;-)
As there wasn't a real decision in this thread anyway it probably makes sense to start this discussion again one the .sweet format is released.