Some thoughts on the underlying data model (symbols)


Have been directed to this discussion from another thread (the MOSFET thread).
It is my opinion, that having to decide the pin mapping while drawing a schematic is the wrong place and wrong moment. A schematic is an abstraction (not as abstract as a block diagram) and further and final design is done in footprint assignment and layout.

So my vote is that symbols do have pins with functions (like gate, drain, source) and not pin numbers (like 1, 2, 3) because the later will break the schematics just by using a different MOSFET than initially intended.

There are better examples, that demonstrate the problem:
I take a power OpAmp ALM2402-Q1 (
I drop that one into the schematics and connect the pins by function. They are IN(X)+, IN(X)-, OUT(X), OTF/SH_DN, VCC_O(X), VCC, GND.
All done, DRC runs fine.
Now, assign the footprint …
Ooops! There are two packages available. And they have different pin mappings! One is OUT(X) is pin 11 & 7, the other one is 13 & 9.
So by assigning a footprint, I have to select the package and this changes the mapping of function <-> pin. And it didn’t break the schematics, because there is no word of “pin number” but all is defined by “function pin”. Even after having done the layout and I decide to change package, the only thing that broke is the footprint (no wonder, I changed it).

So a part in the library needs to have a mapping table function -> pin for a specific package(you’ll find the same problem with transistors). And if there are more than one package available, you need more tables.

Certainly, most of the cases are simple. There is just one assignment function -> pin, even with more than one package.
Finding the example I gave was easy. I expected I’ll find something quickly with a power opamp and the first try was a hit. So not so rare.

How this is implemented in KiCAD? At the moment, I don’t care. I’m just expressing what I expect.
The MOS-FET example has been chewed on long enough, my example is a different look at a similar problem when the model of using pin numbers during layout is used.

Function, not pin number! :heart_eyes:

There is a little nasty detail that may not be overseen. The part name changes by switching a package. It still is a ALM2402-Q1, but now it is either ALM2402QDRRRQ1 or ALM2402QPWPRQ1 (minus the reel). So it might end in ALM2402Q1-DDR or ALM2402Q1-PWP


1 Like

Your suggestion is missing a crucial detail. What thing holds the information about the mapping from function to pad? All you say is that it should not be the symbol, good what then? Something must define that!

No, you just missed the words “mapping” and “table” in my post.


You missed to detail where this table or mapping is stored. Right now it sounds as if by selecting a footprint this magically changes. If you do not have a fully specified library what will hold this info? (after all we are discussing the generic workflow here)

I think words do no longer really work for communicating such detailed things. Might i suggest the use of some diagram that shows which entity holds which information?

As nickm said,


  • I can just take a generic symbol and use it in the schematic
    • without any need to think about pins at this stage.
  • I can choose or change the pin mapping later
    • without actually replacing the symbol with another symbol using the same means as the orginal symbol was chosen, or with a complicated UI (as it is done now).

This must be easy and quick (unlike it is now). For example, at the moment, if I delete and replace a symbol with a new one, the symbol/footprint connection will be broken (the timestamp changed).

Basically the implementation could be as simple as having knowledge about pin mapping variants and an ability to choose between them, for example from a drop-down menu. I don’t care if this is done with the existing file format. It could very well be as long as alternative pin mappings are kept and found somewhere. After that it could be done with the current file format, with different symbols for different mappings, everything should just be done behind the scenes without need for the user to do anything else than normal pcb layout update from schematic. So, basically, from the user’s point of view:

  • select the pin variant with a simple UI
  • update the layout without changing any settings in the update dialog, just like with any other simple change

And that’s it. Naturally the layout must be edited after that, but this can’t be avoided anyways if the tracks have been drawn already.

1 Like

Or, as he said, “I don’t care”. That’s for the developers to decide. Normal users can’t know what the best implementation would be.

1 Like

The reason why i asked is because i suspect that there are contradictions in the suggestion. These will be easy to see even with a crude diagram (and can then be resolved accordingly)

Also see the title of the discussion. I would assume the idea was to discuss the data model why would it be called that otherwise?

An easy to use “replace symbol” feature is planned for v6 as far as i am aware. And the extension of the symbol field editor with the symbol library reference editor is also already requested.
Both of these should make this quite painless. (And not only the generic workflow but also the fully specified one.)

Right now do not replace the symbol by deleting it and placing a new one. Use this:

By the way if the different pin mappings are named very similarly (only differ by some suffix) then this is quite easy to do as the symbol chooser is opened with the current symbol already preselected (so you do not really need to search in the library in that case).

Seems we do agree. The point of my initial posting was to make clear what the requirements are and most of all, where they come from.
That’s a well proven procedure in software design.
Make requirements, make clear where and why they exist. If all agree on the requirements, we can talk about implementing them.
Yes, there will be some kind of dialog when you assign a footprint and the software detects that there are two packages available. UI-design is not my strength, I do embedded. I’m open to suggestions.
But first we have to fully understand how things should work and why they should exist.

I really don’t know the data model of KiCAD (yes, I have poked around a bit with an editor to fix broken stuff). But if those who do the data model understand what the users want, they might make different suggestions or get upset and crazy because all will break down. I don’t know! We will hear!


Sometimes - or actually always - it’s better to find out the high level requirements first. What the original poster actually needs is an easier way to create schematics, not a new implementation. Implementation should matter only to those who do low level work with it. @EL84 can correct me if I’m wrong but he(?) doesn’t need different implementation, he needs easier workflow. And it’s premature to go into the implementation details before the highest level needs are clear. (Well, I do that continously, think about both high level and low level stuff simultaneously, and that’s a problem…)

That would probably be enough for me, as long as I don’t have to browse through all symbols but can easily find and choose the pin mapping variant (possibly even without browsing at all, although I could probably live with what you described, “the symbol chooser is opened with the current symbol already preselected”). I’m not sure if a file format change or extra information would be needed somewhere. We’ll see in pre-6.0 nightlies if those changes are enough without adding something new.

That’s a good trick to remember. Works for a single symbol. Unfortunately Edit Symbol Fields or Edit Symbol Library References dialogs don’t allow selecting certain instances of certain symbol and changing the symbol.

I ideal vision may be:

  • symbol stay generic and toward electrical sense. They can have default or any number of properties/fields.
  • footprint stay generic and toward the packaging and mechanical sense. They can have default or any number of properties/fields.
  1. For mapping problem like symbol to footprint it can be as following property:
Symbol A.Footprint = SOT-23-5:G1 ~ D1 S1 S1
                              |  | |  |  + Footprint Pin5 to S pin on symbol
                              |  | |  + Footprint Pin4 to S pin on symbol
                              |  | + Footprint Pin3 to D pin on symbol
                              |  + Footprint Pin2 is not used/float
                              + Footprint Pin1 to G pin on symbol

Symbol A.Footprint2 = SOT-23-5:G2 ~ D2 S2 S2

NOTE: I just try to show the maximum flexibility if we want 1 symbol for 2 footprints. This is not much actually need in practical as far I know of. But who knows!

  1. For mapping problem like symbol to multiple simulation models (two in this example):
Symbol B.spice = FETXYZ:G1 D1 S1
                         |  |  + spice Pin3 to S1 pin on symbol
                         |  + spice Pin2 to D1 on symbol
                         + spice Pin1 to G1 pin on symbol

Symbol B.spice2 = FETXYZ:G2 D2 S2
                         |  |  + spice Pin3 to S2 pin on symbol
                         |  + spice Pin2 to D2 on symbol
                         + spice Pin1 to G2 pin on symbol
  1. For footprint 3D files mapping properties:
FootprintA.model = FileA.wrl: XScale YScale ZScale XRot YRot ZRot Xofs YOfs ZOfs
FootprintA.model2 = FileB.step:  XScale YScale ZScale XRot YRot ZRot Xofs YOfs ZOfs
FootprintA.model3 = ASpecialCaseCustom.wrl: XScale YScale ZScale XRot YRot ZRot Xofs YOfs ZOfs
  1. If there is a new V6 style of another layer of mapping. I would like follow. Let say we define a atomic part using this V6 new layer of mapping for QS5K2TR. This mapping only need to store all the properties information that is needed for overwriting the generic symbol properties and/or generic footprint properties. So when we apply the QS5K2TR mapping, the symbol and/or footprint properties would updated.

    • Symbol fields: footprint, footprint2, … footprintN; spice, spice2, …,spiceN fields will be overwrite if the mapping are defined in the “V6 map file”.
    • Footprint fields: model, model2, … modelN files may be update to special 3D model from manufacture if exist in the “V6 map file”.

    This allow user the have OPTIONAL V6 mapping or not. KiCad still function with/without the V6 mapping. File format change or not isn’t a problem.

This also mean we can just use current BOM extact, import, build features to mass custom edit and properties files event after apply the “V6 map file” still not quite give design to the state designer needed to.

The trick for 100 symbol is (I think):
Method1) Search and replace in text file
Method2) Extract to text CSV file BOM, edit it, import it back.
Method3) Edit the “BOM” like table in KiCad V5. Can do copy and paste to fall back into Method2.

I’m not searching for a hackish solution or a solution for large designs. I can do what I need to do with the current UI, it just isn’t as fluent as it could be (in v5.1). Waiting for 6.0…

I have posted my proposal to the developers list at launchpad (with diagrams, as Rene Poeschl had suggested) – for their comments and consideration.

You can view the slides (PDF) at

I expect further discussion on this over there, so please join that thread if you are interested to pursue the topic closely.

Thanks for the discussions and sharing!

That’s a well worked proposal, but I doubt one particular assumption. For a new user, they already struggle with symbol and footprints libraries, those are at least familiar entities. Now you are adding a new entity for them to get their brain round, which is quite abstract.

For the current situation, the user says there is no suitable symbol, we say “oh just create a new symbol”. They say “how the heck do I do that?”, and we tell them.

In the new situation, the user says there is no suitable symbol, we say “oh just create a pin mapping”. They say “what the heck is that and how do I do it?”, and we tell them.

So I’m afraid to say, while the solution may be technically elegant, in that it optimises the number of symbols required, I don’t think it will really help new users, and in fact adds an extra layer of complexity which generally makes explaining the process harder.

Probably with this new scheme I would still recommend new users create a new symbol because they need to practice that. Only when they understand symbol and footprint libraries and reach an intermediate level, would I introduce the concept of pin mapping libraries.

I think that proposal is really aimed at making the “use generic symbols for everything” workflow easier. This is because apparently exchanging a symbol is way harder than exchanging the pin mapping. (I guess if there would be an easy to use option to exchange the symbol used then such suggestions would not be made.)

Also notice that wayne basically said: “Nothing new in this suggestion” as the inheritance feature already takes care of this stuff.

I have been trying to follow the developer mailing list discussions but it’s difficult to see what all these features mean in practice. The developers probably have idea, implementation, use cases and even UI in mind. All I have is an abstact idea which people talk about. The discussion may have gone forward for years in several mailing list threads. Searching through the mailing list archives is nigh impossible, even when you know what you are searching for.

It would be much easier to accept what Wayne or you say if we had a concrete example - an end user need, a workflow and a step by step explanation how it works with a UI. For example, do we get rid of all those GSD - DSG - GDS etc. transistors and how that “inheritance” actually takes care of the one functional pin -> several physical pins problem.

And Wayne mentioned only pin mapping, not inheritance. I don’t see how that would solve the problem. EL84’s proposal and pin remapping (swapping pins on the fly) are two different answers to two different problems.

The big mistake @EL84 made was selling his suggestion as talking about the data model. Do a programmer this means the backed representation of data or the file format.

I am not sure if this really was the intention. Some (you included) suggested above that they really talk about how the user could interact with the underlying data model. But if that is the case then this was not communicated explicitly. (And programmers like all people are not yet able to read the mind of others. So they can only work with the information that is there in an explicit way.)

Where is the difference between right click->exchange symbol and select lets say pmos_GSD or right click exchange mapping and select pmos_GSD? (the right click-> exchange symbol interface will come with v6. This is because v6 will also need right click -> update symbol from lib and that one is just a specialization of the former.)
It is the same user interaction, both options need the mapping in the lib somehow (one as part of a symbol that just so happens to inherit the graphical representation of some central entity the other by using a separate file to represent only the mapping)

And the inheritance stuff can even be used to give the user a exchange mapping feature by simply filtering the options of the exchange symbol feature to list only parts that inherit the graphics from the same element.

There is however a catch. Wayne mentioned sometime in the past that inheritance might not get fully implemented in v6. So it might be that the full feature set will only come in v7. (But that does not change with any other suggestion as i would guess that the priority list will stay “get feature parity but with new file format” for v6.)

Everywhere I see a list of symbols - the symbol editor, add symbol dialog etc. - there are several pin number variants cluttering the list. I would rather have one generic symbol and choose the pin mapping separately, rather than having several “generic” symbols which actually aren’t generic because they leak implementation detail (symbol<->footprint pin mapping) into the user interface, and espcially into the symbol name itself.

I think it has been already said that those symbols which are meant to be generic actually aren’t generic because you’re required to know the footprint pin numbering when you select the symbol, or have a symbol name which conveys wrong information.

And some symbol groups don’t even have all possible pin order combinations.

1 Like

May be we need two views:

  1. Generic symbols View: All symbol with original pins (Not pin map data show)
  2. Atomic View: All symbol + pin map data applied

Default view may be Atomic for normal users that need quickly design a board.