search

KiCad / kicad-library

The schematic and 3D libraries for KiCad 4.0. Note that the footprint libraries are the *.pretty repos themselves. This is an orphaned repo, the news about the v5 libs, http://kicad.org/post/kicad-official-libraries/.
Other
749 stars 950 forks source link

LDK130 naming inconsisctency #1386

Closed suzizecat closed 7 years ago

suzizecat commented 7 years ago

Hi !

I just found out that there is an inconsistency with the LDK130 family regulators. While the SOT versions are named like LDK130-xx_SOT23_SOT323 the DFN ones are named LDK130PUxxR_DFN6.

Even if i disagree with the fact of not using the full MPN in the naming (since when i look for a component from a distributor website, i just like to write down my reference and got my component and when i choose a component in KiCAD, writing the part name should get me the component on any distributor website) thoses two parts should be named with the same method.

Why not LDK130aaxxR (which is the full MPN which gives voltage and package) or LDK130-xx_DFN6 for the DFN versions ?

I would make the changes, but i would like to have some thought about it.

Best, Julien

SchrodingersGat commented 7 years ago

Why not LDK130aaxxR (which is the full MPN which gives voltage and package)

This is the way to go.

Refer to the KLC symbol naming guidelines and the FAQ.

The human-readable package name should be included in the symbol description

e.g. DFN package for the DFN version, etc, but use the MPN for the symbol name.

suzizecat commented 7 years ago

That what i thought. I'll open a PR then.

jkriege2 commented 7 years ago

huh ... when did the naming change? I thought we agreed on adding the _SOIC, _SOT23... extensions to distinguish different packages and not use the manufacturer specific extensions ... At least that was the status a few weeks ago, when I reworked regul.lib ...

Best, JAN

evanshultz commented 7 years ago

Jan, see the conversation starting here: https://github.com/KiCad/kicad-library/pull/1081#issuecomment-308462495.

jkriege2 commented 7 years ago

OK, seems I overread the package-extension part in @SchrodingersGat's proposal in that discussion...

Basically I'm fine with any approach, as long as we at some point decide on one and then stick to it and don't change it in such a hidden form (i.e. I really didn't notice that profound change!!!).

Best, JAN

PS: For the future, I think such changes should be discussed in a more general forum (e.g. open an issue for them), as then the decision and discussion can be easily found again and referenced (and is not hidden in a PR discussion!)

jkriege2 commented 7 years ago

One question: How do we deal then with the case where we have two groups of variants in pinout in a components (sometimes happens for voltage regulators), say two package variants have pinout 1 and three package variants have pinout 3. Do we need to make a symbol for each of the 5 variants then? This seems the only way to distinguish that properly in the symbol names, or can we have two symbols (one for each group), but then adding e.g. _TO92_TO220 and _DIP8_SO8 would be a better way to go than using the exact MPN, as these usually cannot be summarized in such a way (at least not generally) ...

JAN

jkriege2 commented 7 years ago

@SchrodingersGat What do you think on my last two comments?

suzizecat commented 7 years ago

@jkriege2 I don't really understand your second comment. If the MPN aren't the same, then i would create 2 main components then use aliases for the others.

If the MPN are the same (quite sneaky) you'll be forced to add something.

jkriege2 commented 7 years ago

@suzizecat You can't really use ALIASes ... let's take group two as an example: Either we have two separate symbol for that (one for DIP8 and one for SO8) + for vregs ALIASes on them for volateg ratings, or we have one symbol with ALIASes for voltage ratings and the user selects SO8 or DIP8 when populating the board. if we do all those separate symbols, the question is how to manage them, as they will quickly grow to massive amounts, also how to fix bugs in such a mess?

Best, JAN

SchrodingersGat commented 7 years ago

@jkriege2 I'm a bit confused by your question too. Can you point to an example where using the MPN is insufficient for identifying the exact package variant?

If there are differences in pinout then a new symbol needs to be created regardless.

jkriege2 commented 7 years ago

Let's take the LDK130-xx_SOT23_SOT323 in question here ... if we use MPN consistently, we should have one symbol (+voltage aliases) for SOT23 and one for SOT323, although these are all logically the same device, even with the same pinout, so no need to create (and later manage/bugfix) all those symbols in the lib. The _SOT23_SOT323 scheme has the nice advantage that all these variants are summarized in a single symbol and the user can choose which package-variant to use, when going from the schematic to the board (that's also how I understood the idea behind KiCAD). Also if we use the MPN-option, and you want to change to another package (i.e. use SOT323 instead of SOT23), you will have to delete the symbols from the schematic and add new ones with the correct footprint ... instead of simply choosing another (filtered) package ...

JAN

jkriege2 commented 7 years ago

To clarify more: I liked that naming scheme, as it allows to abstract a bit from the plethora of package-variants, one or more manufacturer(s) might create (the RoHS, temperature, MIL/Auto/Std, ... are captured by the x-wildcards mostly, or we simply cut the MPN after the base-part as we did before) ... I think that scheme makes managing the libs easier and you will find, what you're looking for, if you're searching by the base-part of the MPN. Having all these package variants separately (to allow for the MPN-style) will IMHO make the libs unmanageable/unbugfixable, unless all this is done by scripts. Also: How do we deal if the same part is produced by different manufacturers that add different letters to the MPN-base for the same package?

In addition if a part is available from different manufacturers, the _SOT23_SOT323-style can catch cases, where the manufacturers use different naming schemes for packages, but if we have full MPN (maybe temp-masked) this is no longer possible.

Here's an example: LM317

Naming scheme:

Best, JAN

poeschlr commented 7 years ago

I think there can be a difference in the naming scheme between a part that is supplied by only one manufacturer and one that is a quasi standard part supplied by nearly everyone.

If a part is specialized to one manufacturer i would vote for the current naming scheme of using the MPN (with wild-cards for packaging, temperature, ... options.) We could allow the _package as a suffix. I personally think having it in the description field should be enough.

For more general parts like the LM317 that is produced by a lot of guys, a generalized approach is ok. (Using the MPN does not make sense if you don't know who the manufacturer is. Having such a symbol multiplied for every manufacturer does not make sense for this library.) For such a symbol it does make sense to have general-part-name_package.

Yes i know this approach would mean we have not only the current two options of "atomic" and "generic" but a third option that is in between these two. (atomic in the sense that we have the footprint specified, generic in the sense that we don't have the full MPN in the name.)

jkriege2 commented 7 years ago

Hhmmm ... I think it would be better to have a simple concise set of rules than special cases and exceptions for everything (also they usually tend to grow in number ;-) ...

JAN

poeschlr commented 7 years ago

We either have a one size fits no one approach or a many sizes still don't fit everyone approach.

If we say the _package naming should be used for manufacturer specific atomic parts as well, we don't have a new option in the KLC. The only thing we would require is that for specialized parts the full MPN is given in the name followed by _package. (Yes this would mean redundant information.)

We would only need to add the rules that _package needs to be set as soon as the footprint field is filled out. And the second rule would be that for manufacturer specific parts the full MPN should be given with the wildcard scheme already laid out in the current set of rules.

jkriege2 commented 7 years ago

Maybe to clear the whole mess up, I'm trying to summarize all this (please edit this post if I missed something or misinterpreted something).

So we have these options of naming schemes, each with its pros and cons (or a combination of them):

1. use full MPN, no wildcards

2. use full MPN, RoHS/Temp/... wildcarded

3. use MPN-base + extension for package (extension only when required to distinguish variants, i.e. not for MCP3204 as all variants have the same pinout, but e.g. for LDK130 to distinguish between SOT323/SOT23 and DFN6-variant groups)

So what do you guys think? Option missed? Which one is best for users, for maintainers, for the project as a whole ...

Best, JAN

PS: @poeschlr @pointhi @SchrodingersGat @hackscribble PING ;-)

suzizecat commented 7 years ago

@jkriege2 I don't get one thing... For example, let's take the LDK130 in fixed variants. Right now you got 3 component in the lib plus a generous amount of aliases which allow us to maintain the whole family with only 3 parts. But you still got the atomic part of it by having all MPN.

For me the theoretically best thing would be to only have MPN since you are sure that the component you're manipulating actually exist and will go smoothly with its FP. Since this may be insane to maintain with some components like LM317 for which you'll have lots of variants in name and/or package, those "generic parts" should be just named LM317 with all FP variant filtered out. But for manufacturer specific parts, i think it should be better to stick to MPN with the package in the description.

Best, Julien

jkriege2 commented 7 years ago

For the LDK130 we now have four symbols, two for the 5-pin packages in fixed+ADJ and two for the 6-pins in fixed+ADJ and voltage aliases for each. When going to MPN we already need 6 symbols + ALIAS variants (i.e. 1.5x the number of symbols).

Best, JAN

PS: edited the correct numbers of symbols currently in lib

suzizecat commented 7 years ago

Well, we could wildcard the package number for the 5-pin variant and narrow this down to 2 symbol but the thing is that there isn't all the voltage variant in SOT23 and SOT323, so i thought it would be better to not allow the user to use an inexistant part (here the 2.5V variant in SOT323)

EDIT : BTW, you need a symbol for the ADJ version anyway since the pin naming is different (BP -> ADJ) as it was said in my PR

poeschlr commented 7 years ago

If we wild card the package part of the MPN nothing but the base MPN is left. Which is exactly what jan suggested as option 3. (Aliases for different voltages in the example of a voltage regulator are included in option 3)

suzizecat commented 7 years ago

Maybe we could have option 3 but adding the real MPN in aliases... In example, having a LDK130_SOT "main" component then all the LDK130Mxxx and LDK130Cxxx stuff in aliases.

I know i'm quite insistant on that, but i really think that it's best to have a reference with real part number, for at least 2 reason :

Staying with the LDK130, the problem, is that when you got 2 parts with different FP, this approach don't allow the use of aliases since you will be able to put a SOT-323 component with a SOT-23 footprint (i mean, you can do that by mistake).
It's also possible to let user take full responsibility to check his design against DS and see that his component and FP don't match, but IMHO, if KiCAD don't give, by default, a wrong FP, it would be for the best...

jkriege2 commented 7 years ago

The management problem will not be solved by the ALIASes ... who should ensure that all DCM-entries are really there? Who manages them? bugfixes them?

Why not have the symbols in the official lib as generic as possible. Then you can still make local ALIAses or copies from them for each atomic part.

I don't really see how all those MPN-parts should be managed and how quality can only remotely be assured in a community effor then .

Best, JAN

suzizecat commented 7 years ago

Well, these are two approach which are pretty different : using generic parts and let users create their own or use atomic part and have an insane amount of components...

The management problem will not be solved by the ALIASes ... who should ensure that all DCM-entries are really there? Who manages them? bugfixes them?

To begin, two (maybe stupid) questions :

With that settled, the real deal : For the management problem, i think that the component doesn't change very often (from the manufacturer POV) so unless the component is outdated, it won't be a problem to keep it in libs. Then, once the component is checked before being put in the lib, it shouldn't have to be "bugfixed"

Seeing what you wrote made me come with an idea, why not having some really generic part, like in the device lib which got a symbol common to a huge number of component (i.e an AOP symbol) but not directly related to any manufacturer ? In this case, this should allow the user to manually change the value of the component to get the right MPN if he wants to. Then we could add specific parts with precise MPN and descriptions in all manufacturer-specific libs (like ST, Altera, microchip, etc) so the user could find any specific part he's looking for.

In this case, these specific libs would be filled by the community, eventually using generic parts as model, as it's done at the moment : when you need it, you add it and submit it.

And, if someone really wants to have their own symbol, they always can use their custom libs anyway.

To be exact, i think that having well-filled libs in which you can find any part number you're looking for is the best and i'm always thankful to the dear dude who put the silly part i need in KiCAD libs. I like when i can get the exact component i need. In an other hand, i understand that it may become pretty hard to manage with the growing number of parts in libs...

Please note that i'm just giving my point of view and that i may not see all the maintaining problems. But i think that doing it that way wouldn't be more troublesome than it's right now...

ghost commented 7 years ago

My tuppence-worth ...

  1. In recent posts, discussion has shifted to policy decisions about what symbols and how many symbols should be in the schematics libraries. I'm using "symbols" to mean the base component symbol and its aliases. See footnote for some "straw man" policies.

  2. Until we have consensus on these policies, I think that discussion of naming conventions for symbols is secondary (important, but needs to be decided once we are clear on what sort of things we are naming).

  3. To inform the policies, we need to decide who are the target users of kicad-library (as distinct from all users of KiCad). The point has often been made that "commercial" users will usually create their own libraries, maintained under their own version control, with added fields to link with BOM management, etc. So who does that leave? ... "small-scale commercial", "education", "hobbyist", others?

  4. Whatever we end up with as the standard approach (approaches?), I think we need two user guides:

    • one aimed at users (how to find a symbol, use of wildcards in searches, how to tailor or annotate the symbol to make it more specific )
    • another aimed at contributors (understanding the policies etc, how to analyse a group of new candidate components to work out the best set of actual symbols and aliases to create)

  5. <ignoring my point 2 above> My experience as a library contributor has mostly been around MCUs. Using the MPN approach, there was some extra effort required to create the large number of aliases needed. I could equally have named the base components something like LPC111x_QFN-33_7x7mm. But looking at it from the point of view of a user searching for the right symbol for a specific MPN, the (possibly false) reassurance I would get from MPNs in symbol names / descriptions is that someone has checked that the symbol is actually correct for that specific MPN.

Footnote - some example symbol library policies

Policy 1. Maximise the number of real world components represented in the libraries.

Policy 2. Minimise the number of symbols required to achieve policy 1 by having only one symbol to represent all the real world variants that share the same following attributes: number of pins, mapping of pin names to pin numbers, physical package.

Policy 3. It is the user's responsibility to tailor or annotate the symbol to indicate other attributes (e.g. features, voltage rating, temperature rating)

suzizecat commented 7 years ago

Wow you're so clearer than me, it let me amazed 😄 This discussion drifted away from the LDK case to the overall library managing policy... Should we close this issue (which have been "fixed") and open something more adapted ?

SchrodingersGat commented 7 years ago

Wow! What a lot to come back to :)

This conversation is quickly moving towards a general "where are the libraries going" discussion. When I started work on KLC-2.x there was very little in terms of an overall plan for the libraries. The last year has seen a huge improvement in terms of both quality and consistency of the libs (symbols and footprints) but there's still a ways to go.

To inform the policies, we need to decide who are the target users of kicad-library.

This is a great starting point. When new users come to KiCad they are presented with these libraries. But who are "new users"?

  1. Hobbyists looking to use a free tool
  2. Educational users / students
  3. Professionals migrating from other tools
  4. ???

Personally, I fit into 3) having worked with both Altium and Eagle at University and then designing many boards with Altium / Eagle (and now exclusively KiCad) in a professional engineering setting. I too was presented with the KiCad libraries, and soon discovered that they were.. lacking.. from a professional point of view.

I started contributing here and there, and was happy to see my contributions used by others. Most of the library data I create for work end up being contributed, and I imagine there are others who do the same.

Having a comprehensive set of useful libraries makes KiCad very appealing out of the box. Here, useful means that they have to conform to some set of standards - that covers quality, as well as consistency.

I do not feel that we should be targeting the libraries at the hobbyist user. There is no downside to not enforcing a high quality on library contributions. Hobby users can then transition to being professional users without the transitional step of realising that the libraries they have been using are no longer of any use to them.

SchrodingersGat commented 7 years ago

One of the large problems we currently face that is driving this particular discussion is the overall organization of the libraries.

We have some libraries that are sorted by function, and some by manufacturer. This necessitates strange mixes of quasi-compatible symbol aliases and many decisions on where a certain symbol should "live".

This issue has been raised a few times now, and there has never been a clear consensus. I think part of this is due to the "flexibility" that KiCad library system offers:

Completely generic symbols

e.g. resistor symbol - this can match with millions of possible unique parts (and dozens of footprints). e.g. SPDT switch e.g. capacitor e.g. button

Generic symbols

e.g. LM7805 - Many manufacturers make this part e.g. 74xx series logic chips

Generic MPN Symbols

e.g. one symbol that covers all temperature ranges of a temperature sensor IC - MCP809xxx

Fully Defined (Atomic) Symbols

Uniquely matches a single MPN

IMO all of these options are viable and useful. Generic resistors are great, I wouldn't want to see all the possible resistors cluttering the libraries. Also, these symbols allow users to draw a schematic without actually specifying part values, etc.

The semi-generic symbols (e.g. 7805 regs) are handy because so many manufacturers make these in standard packaging. Having a generic library saves on having to have every single variant.

And there is no getting around having unique symbols. However, I fully agree that there needs to be a limit to the variants that we add to the libraries. I wouldn't want to see options like Pb-Free or Tape/Reel resulting in millions of almost-identical symbols.

But where does this leave us in terms of library management? I feel that we need to make allowances for all three options as above - but we will need a clear guide for when and where each style is appropriate.

It is probably also the right juncture to make a decision about how the libraries are organised. I would like to propose the following:

There are two types of symbol libraries supported.

Generic Symbol Libraries

These libraries contain symbols that are not particular to any manufacturer, and can be considered "general purpose". Examples as follows

Discrete Contains capacitors resistor, potentiometer symbols

Switches Symbols for various switch and button configurations

78xx Generic 78 series regulators.

etc.

These libraries are named as exampled above e.g. discrete. Symbols contained in these libraries do not have assigned footprints but they do have footprint filters to match appropriate footprints.

Where generic devices exist with different footprints, they can be named as such e.g.

This is because there is no manufacturer code to spec. against. These are truly "generic" libs.

Manufacturer Libraries

Manufacturer libraries contain symbols that are named based on their MPN. Some manufacturers will have a single library but some will have to be split into sub-libs based on function (large manufacturers have too many components to be contained in a single lib). These libraries are named such as:

Manufacturer_Function

e.g.

etc

Alternatively, we could use **Function_Manufacturer**

Within these libraries, symbols are named based on datasheet. Wildcards can be used (and are necessary as really, there are millions of combinations on symbols and we cannot have them all).

The level to which manufacturer parts are genericised by use of wildcards is a matter for discussion. At bare minimum, each footprint variant of a part needs its own symbol to preserve pin compatibility. Contributors could be allowed to add symbols such as:

We can either specify:

  1. Each symbol in a manufacturer library must have an assigned footprint. This means no symbols that cover multiple footprints (breaking my example above).
  2. Manufacturer symbols may have blank footprints with appropriate filters.

If you have Eagle installed have a look at the default libraries that come with it. This is kind of a similar approach, with a mix of generic and manufacturer-specific libs.

...

This has been a long comment. Thoughts?

SchrodingersGat commented 7 years ago

Some further thoughts on these issues:

1. We don't have to fix all this right now

Anything we do will be a progressive improvement, and a considered effort, rather than trying to fix all the problems at once.

2. The new library format will help

Some of the goodies that will appear in the new library format:

References:

3. It won't be perfect

But we can try to get as close as we can to a solution that works well.

4. It will need to be well documented

Whatever we end up with as the standard approach (approaches?), I think we need two user guides:

one aimed at users (how to find a symbol, use of wildcards in searches, how to tailor or annotate the symbol to make it more specific ) another aimed at contributors (understanding the policies etc, how to analyse a group of new candidate components to work out the best set of actual symbols and aliases to create)

Some documentation on how to both use and contribute to the libraries is sorely needed.

suzizecat commented 7 years ago

Well, that's pretty near my point of view, so i do agree ! 😄

jkriege2 commented 7 years ago

A few comments from me:

1. About library organization:

I think about the generic libs there is no debate. About the rest, I'm no so sure ... I like the sorting into categories (regul.lib, dc-dc.lib is a good example), but I also see the value of having the parts by manufacturer ... maybe KiCAD could provide two views on the symbols (as does e.g. Target3001!): But for that the function (maybe even with several levels, e.g. logic/TTL/74xx ... or linear/voltage regulators/positive/fixed) would have to be encoded somewhere together with the symbol. The second view could simply be sorting by lib... of course such a thing would require changes to the lib-format AND the software ... so that might take time ... Until then I personally find sorting parts with general function (regulators, dc-dc, adc, dac, opamps, TTL, CMOS ...) into their own lib very useful ... if I already know the MPN I can easily search for that anyways, but if I don't really know yet which specific ADC to use, I can easily browse there and maybe get an idea (if not the internet/manufacturers are not far ;-). The manufacturer-specific libs would then remain only for those parts that absolutely don't fit anywhere ... Here's a list of such libs that I would find useful (currently only some exist):

2. About naming

I would vote for a scheme where we get as few symbols (and Aliases) as possible, but for sure we should decide on fixed rules, otherwise this discussion will reappear again and again. I still like the postfix-idea best, as it is a standard that fits most needs best, allows easy derivation of user's own symbols, and keeps the libs at least remotely manageable + it is a clear rule that we can stick to (if we allow all possibilities, the discussion will never end, as it's never clear into which cat to put what).

BTW: Do you agree with my PRO/CON list above?`What would be (all) your point-of-view on those points?

Best, JAN

PS: Yes, I know I'm putting a lot of weight in manageability of the libs, as I fear without that and with too loose rules, we will be unable to maintain quality in the long-run (I know how long it took me to get regul.lib straightened out!) ... aleady the next major rework is lurking within 1-2 years: the new lib-format ... so we should also think of how we could transition with the best results and least effort!

evanshultz commented 7 years ago

Would anyone mind if I created a new thread for this topic and then pointed back to this discussion? For historical purposes, it may be best to have a canonical place to point our fingers when discussing and making big decisions.

1.

I agree on naming libraries by type. Manufacturer-specific libraries don't make any sense to me, either schematic or PCB. See comments at https://github.com/KiCad/Connectors_WAGO.pretty/issues/1 (those are for footprint libs, but this topic covers both) and https://github.com/KiCad/kicad-library/issues/1082.

Picking a symbol in Eeschema has a pretty powerful search already, even without the regex, which should give even more liberties to putting parts wherever we like since the user can always find them. Having all opamps in one library means much easier maintenance than if I have the same opamp symbol in a generic library and several manufacturer-specific libraries.

One other note: To support SPICE we'll have to have generic parts. Generic parts that allow a model to be attached with schematic text (like Micro-Cap and LTSpice) will be critical for simulatable schematics. Agree with Jan that there's no debate.

While I realize it's not complete, and it is a great start, there are a few parts that could waffle between categories. For example, where do OTAs go? OPAMP? Where does an audio ADC like AK5558 go? audio or adc_dac? When this starts to coalesce we'll need to consider edge cases thoroughly.

Does anyone dissent to this reorganization? While painful, I only see plusses and support above.

2.

I proposed and pushed for the generic scheme that Jan is professing above for the same reasons. It has the fewest number of symbols and gives the greatest flexibility in matching a given symbol with a footprint. Have that separation is a key part of KiCad. 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. That didn't come up earlier and we had no solution. Also, it ends up with long strings of text on the schematic that require manual editing to correct it to a real MPN. That's also a reason to support atomic parts.

I completely agree with Oliver that KiCad should target power users and still be usable by hobbyists. You just can't make a dumbed-down PCB design program that is still powerful. Unless every part is atomic, some user work will be required and is that really so bad? A big corporation will have automated checks and a PLM system, a small company will do everything by hand, and in the middle you have a range of solutions (probably developed based on a latest crisis). I do understand the desire to use the MPN to identify parts during selection, but I don't personally find that to be best.

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.

@jkriege2 I dislike your option #1 above, but I see both good and bad from the latter two options and as somewhere in the middle of them. If the semi-generic issues above could be worked around, I really want to support that style. I don't have a great solution yet but I'll be thinking about it.

@SchrodingersGat You mentioned 4 levels of libraries, from fully generic or only atomic. But then you mentioned making allowances for 3 options above. Did you mean 4 or am I misunderstanding?

SchrodingersGat commented 7 years ago

I have started a new thread here

@suzizecat sorry that your issue got so sidetracked. Bear with us :)

suzizecat commented 7 years ago

No problem, if it can help improve KiCAD (and i think it is)