This page ariose in the aftermath of noticing, on November 8, 2011, some confusion in my brain between the roles of pin names and pin and pad numbers. This page is, I hope, free of errors arising from that confusion. I have a page with more on the episode of confusion if you are really curious.—]
Pins and Pads, Names and Numbers
This is another attempt to help you get absolutely on top of the internal workings of KiCad, so that when "things happen", you have a chance of dealing with them.
This is an essay that you should probably read after doing some "messing about" with KiCad. You should certainly have read the introductory tutorial, so that each of us is using terminology the same way as the other. Even KiCad experts should scan that before trying to read what follows.
This tutorial is not typical of most the others in KiCadHowTo. They tend to be more "hands on" oriented. They take you through exercises which illustrate things. They are full of "click here", "do this", "do that" stuff. The tutorial you are reading now spends much more time looking at concepts and the mechanism behind how KiCad does the things it does for you.
While the "hands on" stuff is more accessible, the material here is important. If you can grasp what I am trying to show you, many "mysteries" of KiCad will fall into place for you. You will be in charge of your projects, because you will understand what is going on. Without the concepts here, there will be times when you tear your hair!
You, Gentle Reader, are in one of three groups…
- Those who have not met power ports
- Those who've met them, but not yet mastered them
- Those for who power ports hold no terrors
If you are in the first group, you may still find parts of what follows interesting and useful. By all means study it. Don't worry too much about the power ports stuff yet, though. There is [[[sk1pwrprt1 | a tutorial about them for you when you are ready for them. (Don't put it off too long, though. They are useful… if perhaps a little hard to grasp at first.)
If you are in the third group, please feel free to criticize things you see here, and help the next reader by showing me how to make it better. Please!
There would be no reason to make the following little circuit… but it will do just fine for making a whole bunch of points.
All we have in the circuit above is a diode, two resistors, and a symbol for a 555 timer chip. (It is a "well known" chip, but you don't need to know anything about it that I won't tell you here in due course.)
Over at the right hand side of that drawing are two more components: A "Vcc" power port, and a "power flag", "PWR_FLAG". As I said, not every reader need worry too much about these on his or her first pass through this essay. If for now you are ignoring the power port stuff (which includes the power flag stuff), then come back and read this essay again one day, after you get started with power ports.
You will come across more than one power port component… and you may go on to make some of your own. They are indeed components. But they are "special" components. (It is a bit like saying that 747s are a special sort of airplane. They are airplanes, in every sense of the word, but all 747s have certain "extra" features which put them in a distinct subset of "airplanes".)
The power flag, which has the component name "PWR_FLAG" is another "special" component, and happily we just need one component in this class… although, just like, say, the resistor component (name "R"), we may have several instances of "PWR_FLAG" on a given schematic.
The following is also part of the schematic for the project at the heart of this tutorial. It is all about power port issues, which is why I am showing it as a separate illustration.
The following is the PCB which provides what the schematics above call for. Again: Remember that the PCB doesn't actually do anything useful. We are just looking at how KiCad works, and this schematic and PCB are quite sufficient to address aspects of that.
If you don't want to do everything discussed here, consider undertaking the following tiny "design challenge": It is perfectly acceptable to use KiCad to design a circuit and PCB which has just one resistor, one diode, and just one track on. The track connects one pin of the resistor to one pin of the diode.
A project like that might seem utterly pointless… but if you are a KiCad beginner, give it a try! (It is also more than enough for a non-beginner to run various experiments with.) It will "exercise" many of the basic skills you will need for projects that have more than didactic value. And, although this next activity is beyond the scope of the simple introductory exercise, KiCad will also allow you to go back, revise the schematic (add another resistor, say), and then work forward to create a revised version of the board with two resistors and a diode. Again: this is more than enough to exercise the relevant skills.
The Big Picture
Elsewhere on this site the whole process of creating schematics and PCB layouts is covered in detail.
Here, I would like to take a step back for a moment, look at the big picture, and then "zoom in" and focus on the mechanisms which "behind the scenes" integrate the parts of your project.
When you start a new project, you….
- Use the KiCad central project manager to set up a ".pro" file
- Use eeSchema to draw the circuit diagram
- Use CVpcb
- Use PCBnew to draw the artwork defining the PCB
That's what happens "on the surface". Let's…..
Delve a little deeper
The ".pro" file holds core information linking all of the other files in the project. It holds information which is needed by all the programs which work together to bring you the KiCad experience.
(The file extension, ".pro", often goes in quotes as the next word is often "file", and I want to help save you misreading the two as the single word "profile". That's all. And that's why the other extensions lack the guotes.)
During many phases of the project, KiCad will draw on library files. These may be in various places in your storage. (i.e on your hard disk, etc.) There are .lib files and .mod files for the libraries. Most (all?) of the other files discussed here are best kept in a folder dedicated to the project.
The ".pro" file is updated from time to time, for instance when you ask the project to include a .lib or .mod file that it wasn't previously using in this project. (Not every KiCad project uses every .lib and .mod file that you have. Careful use of this selectivity can pay dividends!)
During eeSchema, you will produce….
- a .sch file describing the circuit diagram, aka schematic
- a .net file describing the project's netlist
(The .net file, and others, get updated from time to time by various programs in the KiCad system.)
During CVpcb…
… the .cmp file is created. For each instance of each component an entry is made, saying "for that instance of that component, use such and such a footprint". No check is made at this stage that the footprint is suitable for the component. You will be told of problems in that department when you read the netlist while running PCBnew. That fact suggests that the PCBnew "Read netlist" command invokes a "read .cmp" at the same time. Or perhaps the contents of .cmp are fetched by PCBnew at some other stage. Or perhaps any time .net or .cmp are changed, "stuff" is passed across to the other file. One or another of these mechanisms seems to be operating, anyway.
You can see that this is true by, while using CVpcb, making an unsuitable choice for a component's footprint and then going on to PCBnew and doing a "read netlist".
The following is exactly true for devices which do not contain multiple gates, e.g. things like resistors, transistors, simple switches, not things like, say, a 7400 quad NAND. It is also true, even for a 7400, but you have to think more broadly about "the component" in that case, taking into consideration all of the gates within the device, and any other pins.
All that a footprint needs to be "suitable" for a given component is to have pad numbers which match the pin numbers in the component. Not "the same number of pins/ pads". That will also match, but there's more: the "numbers" given to the pins and must match the numbers given to the pads. In a simple device, say a resistor, this will be ultra simple: Two pins, numbered "1" and "2" and two pads, also numbered "1" and "2". However, more complex devices may use different schemes. A "number" can even be something like "Vcc"! Numbers will never be more than 4 characters long. All of this stuff about "numbers" is separate from stuff about the separate names properties.
As I was saying, you can see that KiCad doesn't check that you've selected suitable footprints during CVnew. Make a deliberate bad choice. Assign the footprint named "1pin" to the "R" (resistor) component creating "R1" in our simple design, for instance.
Save the .cmp file.
Start up PCBnew.
Read the netlist.
Details may differ in your case, but you'll see something like….
The important bit is that last line: "Module [R1]: Pad [2] not found".
Remember: The word "module" appears in a few places where "footprint" would also "fit", and is more widely used. Thus that error message, in a verbose alternate form, might be….
"The footprint you tried to use for the device in your design which, by "annotate" (or otherwise), had "R1" assigned to its "reference field, i.e. "property", doesn't have a pad numbered '2', whereas the component of which "R1" is an instance does have a pin numbered '2'."
Whew!
By the way: If you had assigned, say, a DIP-8_300 footprint to R1, the system would not have complained. The DIP-8_300 footprint has the pads needed to match the pins of a "R"-type component, pins numbered '1' and '2', and so no error is flagged. It would be a bit silly to use a DIP-8, as it has six other pads which would be surplus to your requirements, and the pads numbered '1' and '2' aren't very well positioned for putting a resistor on the PCB… but the system would not complain, if you tried to do this.
Right! That's enough of that little exploration down the rabbit hole!
Back to our "sketchy" tour of a normal project's progress….
We'd run CVpcb.
(We hadn't, officially, started PCBnew, and read the netlist… just talked about what might happen if we did in some (bad) circumstances).
Right! So let's go to the next step after running CVpcb and assigning footprints to the components….
Run PCBnew
The first time in a given project that you run PCBnew you start with a blank "page". When you "read the netlist", you also, unless I am very mistaken, read the .cmp file… but that happens "invisibly".
In any case, after reading the netlist, you are left with a "pile" of footprints, all on top of each other, with rat's nest lines further complicating the issue.
You will in due course, move things around, and draw tracks on the design, to implement the connections required by the rat's nest lines. That information will be saved in a .brd file.
So what?
The point of this essay is…
… to look at the internals of KiCad's operation. The sketch of the design process, above, was to "set the stage".
Now that we have set the stage, we're going to go through the process again, looking at how, under the hood, KiCad "knows things".
The process of examining KiCad's internals is enormously helped by the fact that it use simple text files for all those essential ingredients…. the….
- ".pro" file
- .net file
- .cmp file
- .brd file
The .lib and .mod files consulted by KiCad during the design file are also simple text files.
Simple formats for essential files is a hallmark and benefit of open source software. Ever try to access a Microsoft product's files directly, when you wanted something Microsoft hasn't deigned to provide for?
Having said that, you certainly don't need to delve into the files. I'm going to tell you what's there! <^_^> But the fact remains that you can, if you wish to.
Whatever you do, don't use a huge word processor, not even Open Office's wordprocessor, to read simple text files. Windows comes with little "Notepad", which is very adequate. Take my advice, if you are a Windows user? Install Textpad. (I use it for almost all of the writing I do. Only for correspondence which will go out "the old fashioned way" do I fire up a wordprocessor. Elephant gun… mouse… you know.) (I have other suggestions for good, light, free (or inexpensive) Windows apps for you, too.
Here we go… again…
So… Back to the beginning. A deeper look at our diode, two resisotrs, one 555 project…
eeSchema created the .sch file and the .net file.
The former consists of machine-friendly records of where to draw the different things on the page… components and lines, etc. It contains records of the orientation for each component.
Each component, as you should know from other studies as a field called "reference". The "reference" field is a cornerstone in the foundations of KiCad.
The reference field can be filled "by hand", or you can let the annotate tool assign values to the reference property (field) of each component.
No matter where the reference field data comes from, what is in that field for each component of the design must be unique. (If, say, you accidentally have "R1" as the reference for two of your resistors, even if every component has something in it's reference field, when you try to save the netlist, eeSchema will tell you that "some items are not annotated", and offer to run the annotation tool for you. (Which is quite capable of finding and replacing the instances of references being used twice.)
I said that what's in the "reference" field is a cornerstone. Throughout the rest of the design process, whenever KiCad needs to save information about, say, the diode in your circuit, it will simply use what's in the "reference" field to specify what is being talked about.
Here's something not in the .net file.
The .net file does not know what a diode's representation on the schematic looks like.
When eeSchema goes to draw the diode we've referenced as "D1", it looks in .sch file, finds the entry for "D1". Part of that entry says "when you want to draw this, use the "DIODE" component drawing rules, from whatever .lib file you first find a "DIODE" definition, when you go down the list of .lib files chosen for this project. Wow! If you think about what I just said… and get to the point that you understand how all the "bits" fit together, you will see that KiCad is both "powerful" (a word I avoid!), flexible, and robust. The .sch file record for D1 will also say where to draw it, and which way it ought to be turned. But how to draw it, there, is in the .lib file. Notice the efficiency of this, among other things: You might have 10 resistors, all of the same sort, in a design. You don't have to how "how to draw that" stored 10 time… just ten links to one definition of how a resistor is drawn. This brings along another advantage. What if you don't like the symbol used for resistors? Change it. Once. (Or better yet, save an alternative specification in a .lib file of your own, "above" the standard one.) "Instantly", the system's idea of what it should draw is changed… for all 10 resistors.
That's good. And it covers (I hope!) things at one level… at the level of whole components.
Now we are going to "drill down" to a deeper level.
We know where, say, D1 is going on the schematic.
What about connections to D1's pins?
Each pin of each component has a number. (It also has a name, as does the component! The pin name and the component name and the pin number are all different things, and it is very easy to confuse one with another. Not least as "Vcc" is acceptable as a pin "number". (While you can use "Vcc" for a "number", it usually isn't necessary and it would be wise to usually use digits when making up pin number identifiers.)
The numbers of the pins of a component start out with default values stored in the component's .lib file entry, but you can alter the default values, once you have created your [[co1inst | instance] of a specific component. (Your edits will be local to the instance of the component you are altering, they won't automatically propagate to all of the instances of that type of component in your design.)
I'm not done with that yet, but must step back and remind you: A schematic is not just a bunch of components. It is also connections. Either direct component-to-component connections, or connections specified by lines.
The .net file, keeps track of these connections. For a small part of our diode/ two resistors/ 555 circuit, our "study" circuit, the .net file, in a simplified form, says…
( /D1
( 1 VCC )
( 2 N-001 )
)
( /R1
( 1 N-001 )
( 2 N-002 )
)
( /R2
( 1 N-002 )
( 2 N-008 )
)
That's (simplified versions) of three records from the .net file. The record for the diode (reference: D1), the first resistor (reference: R1), and the second resistor (reference: R2)
The record show that each device has pins which were given the number IDs "1" and "2".
It shows that pin 2 of R1 connects to something called "N-002". And…
It shows that pin 1 of R2 // also connects to "N-002".
"N-002" is something created by KiCad's internals. It is a "net". Anything in our design which is connected to other things in our design will be shown as being connected to some "net"…. all of them to the same net, if they are connected to each other.
Notice that the .net file, the "net list", does not need to record how R1:p2 and R2:p1 are connected. It is only "interested" in the fact that they are connected. (If they are connected by a line, rather than by direct contact, there will be something in the .sch file to keep track of the existence of the line, and also where it runs on the "page".)
Take a breather. A surfeit ojf details, perhaps… but not "rocket science" so far?
We've made a good start. We're beginning to see how the graphic of the schematic, by means of a .net file, a .sch file, and .lib files can be "boiled down" to machine-friendly text files.
We're mostly just going to continue with that story. The basic ideas are mostly in place. We just have to look at how other things are taken care of by similar mechanisms.
Re-filled your coffee cup? Things are about to get a little hairy….
"Connection" between schematic and PCB design
The schematic has a symbol ("component") for a 555 timer. The PCB design has a DIP-8 footprint.
Lines on the schematic will result in rat's nest lines for the (human) PCB designer, going to the right pins of the DIP-8. They will be turned into tracks, by the human.
How does this magic work?
(For the moment, forget that you have ever heard of power ports, if you have. They are a similar… but different… story, to come.)
The "secret" is hinted at by the fact that you need to choose footprints which have sets of pads which have the same numbers as the numbers on the pins of the components in the schematic.
Think back to what we know about the netlist. It has things like….
( /D1
( 1 VCC )
( 2 N-001 )
)
( /R1
( 1 N-001 )
( 2 N-002 )
)
( /R2
( 1 N-002 )
( 2 N-008 )
)
in it. Now: Does it matter if you draw the diode as it would be drawn on a schematic, or as two holes and a silkscreen graphic? No, of course not.
The netlist is just as useful for specifying elements of what should be in the PCB layout… and how they should be connected… as it is for specifying aspects of the schematic.
As you will have no doubt guessed, there is a file to say where the diode's footprint should go, how it should be oriented. This is the .brd file.
And, as with the symbols on the schematic, the footprints on the PCB design are not specified in either the .net file or the .cmp file. The .cmp file has things like….
BeginCmp
Reference = D1;
ValeurCmp = DIODE;
IdModule = R4;
EndCmp
… in it. The "D1" says "link this information with what is in the .net file about the device with its "reference" property set to "D1". Use the footprint defined under the name "R4" in one of the .mod files.
By the way… sorry… the entry "DIODE" in the above, which I will explain in a moment, has nothing to do with the entry "DIODE" which we saw earlier. (The .sch file had "DIODE" in the field telling eeSchema to fetch symbol drawing rules for D1 from the entry for the "DIODE" component (i.e. the component with that name) from the first .lib file to //have/ a "DIODE" entry.)
The "DIODE" entry in the .cmp file entry for D1 is much less interesting. It is just "filling a space", in fact. The "ValeurCmp" field… you won't see it called by that "unfriendly" name, unless you go looking at the applications internals… is where, for a resistor, you might put "580 ohms". As diodes don't have simple "values" the way, say, a resistor does, the field is often used to indicate what sort of diode should go here, e.g. you might find "1N4001" in the "value" field. (There are of course, other, more rigorous ways to list part numbers for the devices used.)
While it is in some ways tedious, that "double use" of "DIODE" does make a nice illustration of the fact that KiCad is not going to "fall over" if a word gets used for different things in different places. The context of the usage is quite sufficient to keep everything "working".
And, when it come to the use of terms by the various programs of KiCad, a wonderful discipline is evident… Terms are used precisely, with care take to avoid ambiguity and sloppy-speak.
So! What connects to the pins in the schematic drawing and what connects to the pads in the PCB is defined by the numbers given to the pins, and the fact that the footprint used to mount a particular device on the PCB will have a set of pads with numbers to match the pin numbers of the underlying component.
So far so good.
KiCad is helping you… really!
Once you understand what we just covered, you can afford to "look" at something which would have confused you earlier.
The 555 has an invisible pin named "GND". It is pin 1. The pads on the footprint we re using… a DIP-8_300… don't have names at all (They can acquire net names… but that's not not the same thing, and they don't "come with" the footprint.)
The footprint's pads have numbers. The footprint is a very general "thing"… you can use a DIP-8_300 to put lots of things on a PCB. (The "magic" is what CVpcb and the .cmp file do). The DIP-8_300 footprint has 8 pads, numbered 1 to 8. All of the components which can be put on the PCB with a DIP-8_300 footprint have //pins numbered 1 to 8. See where this is going?
Until we get to power ports, things are quite simple. (They aren't too bad after we factor in power ports… which we will do in a moment.)
One of "the secrets":
Whatever is happening to or with pin number '1' of the component in the schematic will be happening to or with pad number '1' of the footprint on the PCB.
Ta! Da!
Now. Power ports.
You need to be careful.
Re-read the "secret" above.
Power ports, even though they are components, are "special" components.
Most (all?) of them consist of a single pin.
In the component's properties (as distinct from the pin's properties), there is a box you can tick to make it a power port.
When you have done this, a little "magic" happens.
The power port pin's number becomes unimportant. And the pin's name… usually not terribly important to KiCad, even though it is useful to you, becomes vital to how KiCad behaves with the power port, things it is connected to, and things it may not seem to be connected to, but to which it is connected after all!
(By the way… the "electrical type" for the pin of a power port is usually (always?) "power input"… even for the "GND" power port. An exception: the "PWR_FLAG" power port, a "special" special component in several ways, has a pin of type "Power Output".)
First a "simple" consequence / use of a power port. The "GND" power port is often used this way….
If you have two or more lines on your schematic which are not connected, but each of them has a GND power port connected to it, then circuit will behave as if there is an invisible line on the drawing connecting those lines. When you come to do the PCB design for the project, the rat's nest lines will guide you to connect up the things that the "invisible" line would connect.
It would be a silly way to do it, but the two circuits below are equivalent…. D1 does connect to R1 in both cases. (The triangle is a "GND" power port.)
In other drawings, this way to make "invisible lines" is helpful. The "invisible lines" save us from having long and confusing lines connecting widely separated things on the schematic.
ILLUSTRATION NEEDED HERE
If you have a line on the drawing with a power port connected to it, and any invisible pins on any components, and if those pins are named with the same name as the power port's pin, then when you come to do the PCB design for the project, the rat's nest lines will guide you to connect up the pad with the same number as the invisible pin to all the other things the line connected to the power port connects to.
NOTE WELL the chance for confusion which has crept in.
When we weren't dealing with power ports or any invisible lines or pins, everything was simple. Connections all depended on pin and pad numbers.
It is only in association with power ports that the names on certain pins and pads come into the "what connects to what" story.
A little tedious, maybe… but it does open up some great possibilities which….
- would have been hard to do another way
- are wroth the tedium
(Remember also that we are talking about pin and pad names here. The components and footprints have names too, but those names are not involved. Which component or footprint connects to which other components and footprints depends on the identifier in the "reference" field or property of the component or footprint, as discussed earlier.)
A detail…. multiple power ports on a single line….
So far, you know that invisible pins can be connected to other things, if only you know their names.
What if one of the components in your project has an invisible pin named Vcc and another component has an invisible pin named Vdd… and you want to connect both of them to the place where 5 volts will be supplied to the board? For once, the answer is simple: A line can have more than one power port on it. In this case, just put Vcc and Vdd power ports on the line.
And there's a different problem, sort of the above "backwards"….
What happens when you have two independent circuits on the board? Circuits which should not have a common ground? (This commonly arises when you are using opto-isolators, for instance. In that case, you can have a Vcc1 and Vcc2 and GND1 and GND2.
Well! That's enough of that!
I apologize: That tutorial isn't quite as "tight" as I would like it to be, but there is important "stuff" there. I will try to make it better someday, but, in the meantime, for those of you willing to make an effort, the Good Stuff can be had.