Understanding power port components

Hi folks:

I am trying to understand which features of a power port component qualify it for which power port behaviors. Which might be in docs somewhere, but if so, I haven’t found it, so please point to it if it’s there.

The behaviors in question are:

  1. implied attachment to a power net
  2. being offered by the “Place power port” tool
  3. possibly other behaviors I don’t know about?

I see that a power port and its pin has the following attributes that might be involved:

Power port component:
[ ] Show pin number
[ ] Show pin name
[ ] Define as power symbol

The Component Name:
[string] Text
[ ] Invisible

The Field Reference:
[ ] Invisible

The single pin:
[string] Pin name
[choose] Electrical type: “Power input” seems to be what the provided power port pins use, but “Power output” is an available choice [Point 3 below]
[ ] Visible (“Schematic Properties”)

My guess is as follows:

  1. It’s the pin’s Electrical type = “Power input” that invokes automatic attachment to the net named by the pin’s name. Not affecting this behavior (my guess): The Component Name [note A], the component’s “Define as power symbol”, and the pin’s Visible property [note B].

  2. Component “Define as power symbol” determines whether the component gets offered by the “Place power port” tool. (And no other effect.)

Am I right about these? Also:

  1. Why do power port power supply pins have attribute Electrical type set to “Power input”? On the face of it, that type makes sense for a component that uses the power, but not for one that supplies the power. It seems that this aberration is what drives the needs for the PWR_FLAG component to provide a source for a net like VCC which connects to other components’ power input pins.

Other notes:

Note A: In the supplied power port components, it looks like the Component Name is set to match the pin name. I guess that’s because the pin is usually hidden to avoid visual clutter. However, as I guessed above, it’s the pin name that matters, and not the component name? It would be possible to create a component named “-5V”, with a pin “100V”, not Visible, and it would connect to the 100V net, right?

Note B: The schematic editor has a preference “Show hidden pins”, which appears to override the pin “Visible” setting unchecked. The fact that power pins can be hidden, thus affording surprise connections to some net, perhaps explains the many forum posts about issues with “hidden power pins”. I guess, but don’t know, that the hidden aspect does not actually influence whether or not the pin connects to a net, right?

(As a side note to developers, it’s unnecessarily vague and misleading to use different terms for the same thing in different parts of the UI. here Visible vs Hidden, and “Define as power symbol” vs inclusion on list of symbols offered by a tool. (Assuming I guessed these right.))

The powerport is simply a symbol with one hidden power input pin. This makes it such that it functions as a global label.

(The pin is hidden and power input to convert it into a label, not to avoid clutter. And yes this is a legacy “feature”. A better way might have been to have a special electrical type that states that this is a power label pin. But we need to live with this at least until the new schematic file format comes out.)

The second part is to define it as power symbol. (Tick mark in the symbol properties)
In addition to this the reference also starts with a #.
This ensures that kicad does not try to attach a footprint to it.
(I think the # part is the part that defines the not given a footprint stuff and the tickmark might be responsible for it being shown in the add power symbol dialog. But i am not sure about that. This fun experiment is left for the curious reader to find out them selves.)

1 Like

[quote=“gwideman, post:1, topic:8945”]
It’s the pin’s Electrical type = “Power input” that invokes automatic attachment to the net named by the pin’s name. Not affecting this behavior (my guess): The Component Name [note A], the component’s “Define as power symbol”, and the pin’s Visible property [note B]. [/quote]

Component “Define as power symbol” determines whether the component gets offered by the “Place power port” tool. (And no other effect.)[/quote]

“Define as power symbol” does the following.

  • It changes the symbol’s Reference field to #PWR and hides it, so EESchema doesn’t display the reference designators and you don’t really care what specific reference designator gets assigned.

  • The symbol’s Value field is what is used to name the net. So you don’t confuse yourself, the symbol’s name should match the Value field.

  • The Power symbol defines a global net with the name in the value field. This is important. Global nets are the same everywhere in the schematic hierarchy. A +3V3 symbol on Sheet X is the same net as from a +3V3 symbol on Sheet Y. (Global nets don’t have to be brought up and down through the hierarchy, which is a convenience and is expected behavior for a Power symbol.

  • I honestly don’t know whether “Define as power symbol” is used as a key to have it in the list of things presented when you choose the “place power port” tool. But I think you’re right, it does, as the only symbols visible in the chooser when you click that tool are power symbols.

  • The pin Electrical Type does not do what you suggest – it doesn’t attach itself to the named net. Pin Electrical Type is for ERC only. As noted above, it’s the Value field which sets the net name.

Here is why. Consider for the moment that the Power Symbol’s pin type is Power Output. What happens when you place two +3V3 symbols on your schematic? Remember they are the same net. Now you’ve got two drivers on the net, and we know what happens when you have to drivers on a net. (Bad things.)

The assumption you are making, and it’s an incorrect one, is that the Power Symbol is a power source – it is not. It is just a convenience that lets you connect a lot of pins to the same net without drawing lines everywhere. It is type Power Input and not plain Input or Passive because it expects to be connected to a Power Output for ERC reasons.

If your design requires a power source (and it does, electronics require power), then you have to provide one. For example, regulator output pins should be declared as Power Output, and if you place a Power Symbol on that output, now that output pin is connected to a global net. Another example: a barrel jack that connects to a wall wart. You might wish to declare its pins as Power Output so ERC is satisfied.

Now, the Power Flag PWR_FLG. This is an oddball Power Symbol but it serves a vital ERC function. It does not define a net name. It does not make a net global. Its one pin’s electrical type is Power Output. It is used to provide a driver (in the ERC sense) on a net that will be connected to a Power Input.

Classic example: you have an AC input that gets connected to a rectifier. The output of the rectifier goes to a regulator’s input. That input pin’s type is Power Input (as expected). But the pins diodes and capacitor in the rectifier are type Passive (as expected), so ERC will complain: “Power Input pin X on UY (regulator) has no driver” (or some such). You “know” it’s driven with power through the rectifier, but ERC is pedantic. So you have to place a PWR_FLG on the net that is the rectifier output/regulator input. The flag “supplies” the power source and ERC is happy.

A second example. An IC vendor may recommend a series resistor on a power pin. A reasonable IC symbol of course has the power pins declared as type Power Input, but the resistor’s pins are Passive, so ERC complains. Place a PWR_FLG on the net between the resistor and the power pin and now there’s a source so ERC is happy.

Now read Section 8.5 of the EESchema manual where this is all explained!

I have no idea what will happen, and it’s something I see no point in trying. Don’t try to be clever, you’ll just confuse yourself.

The hidden aspect absolutely does influence whether a pin connects to a net. See Section 5.5.4 ofthe EESchema manual: “Eeschema automatically connects invisible power pins of the same name to the power net of that name.” For reasons that have been discussed on this forum and elsewhere, this behavior is wholly evil and is to be avoided. Don’t use hidden pins on symbols. The reason EESchema includes this behavior is for legacy reasons – it was common back in the old days of +5V-only designs to hide the power pins on TTL parts to “improve schematic readability” and “reduce clutter.” Now with multiple-rail designs and ICs which have power pins which have different names but get connected to the same rail, hiding power pins and getting a default net name is a recipe for expensive disasters.

Oh, yes, the developers are aware of this. See discussions about calling a symbol a “part” or a “component” and whether you’re working in the Part Editor or the Symbol Library! And then there is the use of “modules” and “housings” and “packages” and “footprints” synonymously. As these inconsistencies are pointed out (and added to the bug list) they get fixed.


@Andy_P. I’ve linked to this post in the FAQ. Lots of good information since ‘pin not driven’ seems to be a FAQ. If you feel like it you could maybe redo this a little and make it a standalone thread? Then you could always edit the first post to keep it updated. If not, this is at least a good starting point for people to get a grip on the subject.

@hermit, glad to do so. I will try to edit for brevity.

1 Like

Hi Andy_P. First, thanks so much for dedicating considerable time to this thoughtful reply. I appreciate your experience and willingness to share it.

That said, so far as I can tell, your reply has a number of crucial details incorrect.

“Define as power symbol” … changes the symbol’s Reference field to #PWR and hides it

“Define as power symbol” does not change the symbol’s Reference field. That field has to be entered manually. In particular, the “#” has to be prepended manually. (Being the “#” which tells CvPcb not to link the symbol to a footprint.)

The symbol’s Value field is what is used to name the net. So you don’t confuse yourself, the symbol’s name should match the Value field.

First off, so far as I can tell, the symbol’s name IS the Value field. At least, hover over the symbol name > E > Clarify refers to it as “Field Value”, and invokes the Component Name dialog. And that becomes the name of the component when the listed in the library browser.

Next, and probably most important info in this entire discussion:

So far as I can tellThe Component Name (aka Value Field) does not name the net that this power port connects to. Instead, it’s the name of the pin that determines the name of the net.

This can be demonstated by creating two power symbols as follows:

Component Name: (Field Value): PwrA
Reference field: #RefA
Pin Name: PinA
Pin Num: 1
Pin Electrical Type: Power in
Pin Invisible: yes

Component Name: (Field Value): PwrB
Reference field: #RefB
Pin Name: PinA
Pin Num: 1
Pin Electrical Type: Power in
Pin Invisible: yes

Note that the Component Names are different but the pin names are the same (and invisible).

Use these on a schematic to connect components:

U1-1 POut1 (Power out) --> PwrA

PWRA --> U2-1 PIn1(Power in) Connects to U1-1 as expected

PWRB --> U3-1 PIn1 (Power in) Connects to U1-1 due to matching PinA on PwrA and PwrB

ERC and PCBNew ratsnest verify what I describe. As does the netlist:

    (net (code 1) (name PinA)
      (node (ref U1) (pin 1))
      (node (ref U2) (pin 1))
      (node (ref U3) (pin 1)))))

In short, the underlying KiCad mechanism that links the power ports is the same “invisible power pin” mechanism that is now thoroughly deprecated on regular components.

That doesn’t cast any shadow on power ports’ use of hidden power pins. When hidden power pins are provided on real components, they auto-connect the real components’ power pins to some net that was pre-chosen by the component author, and that’s not explicit on the schematic – which limits flexibility of using the component, and can be catastrophic if not noticed. Instead power ports afford an explicit connection from real component’s visible power pin to a net of your choosing, and provide a hidden connection only between same-named power ports. (Assuming power port has been named the same as its pin.)

Understanding all this (I think!), for sanity’s sake, one would certainly want to give the power port component a Name (aka Value) that matches the name of its one pin. But it’s not the Name/Value of the part that accomplishes the connection to the net, it’s the pin name.

For what it’s worth, the PWR_FLAG component has the following settings:

Pin name: pwr
Electrical Type: Power output: Satisfies the ERC check. (And fails ERC if the net to which it’s attached is connected to another Power output somewhere.)
Pin Visible: yes! (Prevents auto-joining to a net, unlike other power port symbols!) But actually the pin itself does not appear on the schematic due to zero length and symbol-level Pin name and Pin number set to invisible. Instead the PWR_FLAG appearance is provided by polyline.

OK, I hope I got all that right, and that this contributes to refining the docs on these issues. Thanks again for your willingness to engage.

– Graham


And a followup related question that may further illuminate how this works:

What is the difference between a Power Port component (from Place power port tool) and a Global Label (from Place global label)?

So far as I can see, the only difference is that the Power Port component

  • requires a library component and has a library-defined graphic
  • is offered by a different tool
  • attaches a specific net name, and “Power input” type to the net, with corresponding ERC

Other than that, they seem indistinguishable, and provide the same connection function.

So for example, when drawing a local power region provided by a local regulator, is there much motivation to create a custom Power Port component for those few connections, or can one just use Global labels?

– Graham

I think you have worked it all out, but yes a global label can perform the same function as a power port. I guess the reason for the special behaviour of power port symbols is to allow custom graphics that you can’t do with a global label. I won’t say it is a bodge but it is a “least coding effort” way round it. Unfortunately these sort of “special handling” might be simple for developers but rather opaque for users. I would prefer a “power port label” electrical type to make it absolutely clear, and code accordingly, even if that is more coding work.

The hidden power pin literally does create a net label, see https://github.com/KiCad/kicad-source-mirror/blob/master/eeschema/sch_component.cpp#L1826

For reference, the latest code to detect power ports reads as follows:

     * Return whether this pin forms an implicit power connection: i.e., is hidden
     * and of type POWER_IN.
    bool IsPowerConnection() const {

        return (
            ( !IsVisible() && GetType() == PIN_POWER_IN )
            ( (LIB_PART*)GetParent()->IsPower()  && GetType() == PIN_POWER_IN )
        ) ; }

github link

1 Like

Thanks bobc for commenting with a prompt to look at the source. Obviously a sensible suggestion for ground truth, but takes a lot of time.

Looking at the section of code you included, IsPowerConnection is a bit enigmatic:

  1. It returns True when the pin is both invisible and has type Power in. That accords with the current discussion.

  2. It also returns True in the pin type is Power in, and the enclosing part has attribute IsPower set! That implies that pin visibility is actually ignored if component IsPower is set, which it normally would be for a power port component.

I did a quick test of (2), but did not get the behavior implied by the source code.

That is, I created a symbol with component setting of “Define as power symbol”, and the single pin set to visible. The Place power port tool offered the symbol, and I used it as though it was a power port on a schematic. However, it did not cause eeschema to create a connection to the net named by the visible pin.

(Using 4.0.7)

So, I guess it’s more complicated than this snippet of code.


I wouldn’t normally suggest looking at the code in the first instance, there is a lot of code! I happened to look into it last time the topic came up so, so I knew where to look, otherwise it’s a bit needle & haystack.

Github source mirror reflects latest code, it seems that code was changed 5 months ago so it should be in nightly build, but probably not in 4.0.7. The change was related to Eagle import, https://github.com/KiCad/kicad-source-mirror/commit/aeb43b055cce793bb00f92e57b1fd26418682225

Hahah, yeah, I just plowed into the source code and discovered the same thing, and no, it’s not in the 4.0.7 release:
https://github.com/KiCad/kicad-source-mirror/blob/631f6d53d370b185175a59dcbc76478234a3f21b/eeschema/lib_pin.h ]

So the implications of this change haven’t yet hit the mainstream. At which time it’ll be yet more complicated for users to divine how the heck auto-join of nets works. Why there can’t just be a single explicit attribute “auto-join this &^%$# pin to net=[pinname]”, I don’t know. The current state of affairs is obtuse and misleading enough already (as Andy_P’s discussion illustrates), without it getting even more complicated. – Graham

And wait a sec, isn’t this new “ignore invisible pin” capability a problem waiting to happen?

It seems that the rationale for this is allow power port components that have visible pins. On the face of it, that’s an OK idea. However:

If those power port components, or schematics that use those components, are used in a KiCad version that predates the change, they won’t achieve the intended auto-join-to-net.

[Edited: I previously thought ther would be an issue with PWR_FLAG suddenly invoking auto-join to the “pwr” net due to its pin currently being set to visible. However, the power pin is also set to Power out, (its rasion d’etre), so the new logic clause won’t qualify it for auto-net-jjoin.]

And what would be the benefit of this new “visible pin” logic anyway?

On a power port component, you generally don’t want to see the pin name and number anyway, and can’t position them well even if you wanted to. The one benefit could be the actual pin appearance. Up to 4.0.7, power ports have to draw in all of the the appearance with polylines and so on. Even if the new logic means the pin can be shown, power ports will still need additional lines, so it’s not like there’s a great saving there.

So I guess I’m not understanding the benefit here to this change.

– Graham

First off, I’d like to say thanks for helping us to clarify how all of this works. Obviously I think I’m misunderstanding how the innards work, and I’ll also say that I’ve never created a Power Symbol from scratch, I’ve just copied what was already in the power.lib and modified it to suit my needs.

(Which brings up the question nobody has asked: why can’t we have generic Power Symbols with the graphics everyone likes but with no default net assigned, and after placement the user can just edit it to indicate the net name?)

Perhaps it’s worth stepping back a moment and looking at why such a thing as the Power Port exists. I think it’s obvious. Most electronics engineers are familiar with the arrow or circle of common power symbols, and everybody knows what the ground triangle symbol means. So any schematic capture program that doesn’t offer power symbols will be laughed at: “why can’t I draw this?” It’s really what users expect. Nobody wants to draw a line to each and every power pin on a board. That gets messy real quick, and likely why the draughtsmen drawing blueline schematics created the power symbol in the first place.

Once we’ve decided that we need power symbols, what should they be? Well, obviously they should indicate some special Power type, and they should be global to the design. Nobody wants to see +3V3 on one page being a different net than +3V3 on another.

But why differentiate between a Power net (defined by a Power Symbol) and any other global net (one which is given a global net label)? I think global nets were created to make multisheet designs easier to draw. Some schematic tools don’t require hierarchy for multisheet designs, so to have a net appear in more than one sheet it needs to be global in scope. And in a hierarchical design, some people simply don’t like having to add sheet labels to bring nets up through the hierarchy.

But anyway, while both Power Symbols and global netlabels define a net to be global in scope, the former adds a load to the net for ERC reasons; the latter does not.

If it’s a local power region, then the power net needs to be local in scope, not global. I will, therefore, argue the answer is “neither.” Why put a global label on a net that is, by definition, local? While the original motivation for Power Symbols was to unclutter a drawing, don’t use them here. Instead, just draw wires from the regulator output to the power pins of your various parts. Give the power net a local label, and put a PWR_FLG on the net at the regulator.

And remember: you do not have to draw a wire from pin to pin to establish connection! Draw a short wire on the regulator output, and place the (local) net label on it. And at each pin that needs to connect to that power net, draw a short wire and place the same label on it. Those wires need not connect physically (making a rat’s nest of the schematic); the net label establishes the connection.

You raise some excellent points.

  1. I found that if a global label name has the same name as a (global) power net, the netlist will join them. (Though I see that ERC doesn’t notice that connection.) I wonder the extent of interaction between same-named local label and either global label or power net?

  2. You note that global (and presumably local) labels don’t add a “load” (ie: “electrical type”) to the net, so far as ERC is concerned, yet Power port components do. That makes me wonder – what rationale is there for a power port to have an electrical type? Surely the character of the net should be determined by what real components are actually connected to it? Just like a global or local label.

So I’m starting to think that the only reason the Power port components have electrical type Power-in is because perhaps they were introduced at a time when KiCad already had the “auto-join for invisible-pin & Power-in” feature for real components (like 7400 series), and that feature was used as a quick-and-dirty way to get Power ports with no change to the code, just new library parts.

And a similar level of hack where the “#” reference prefix tells KiCad not to require a footprint, despite the fact that the component is marked as a Power port, which should imply no need for either a footprint or a reference.

The downside of this is that now users stumble over what exactly a Power port is, given that it apparently has an electrical nature – it’s not just a naming/wiring thing – and puzzlingly, that nature is “input”. And further, if you need to create your own, you have to slog through these obtuse rules that don’t on the face of it make sense, to get it to work.

So I get the impression that the Power port idea entails a modest implementation shortcut in the code, at a considerable expense of conceptual corruption in the application domain.

If this story is the reason why Power ports are the way they are, then it would be helpful if this was documented in the help/manual pages, instead of leaving the confusing impression that these quirks have some application domain rationale.

1 Like

Majority of users are confused by power symbols when they get ERC errors ‘Power input pin not driven by power output pin’. They then check the power symbol and realize that it has a power input pin rather than a power output pin. However, this is fairly normal since power symbols help to assign the power inputs to the same net. The error message results when an external power supply is used which is input through say a passive connector pin on the board. This is also normal. Changing the connector pin to power output will resolve the issue but will produce error message ‘the component is edited in library’ and will indicate the danger of undesired update. Ignore option is not acceptable since genuine occurrences of this error must be detected. Assigning a warning level, however, results in littering the ERC which is also a nuisance. My solution suggestion is a different method mimicking the actual (physical) rules of power flow from circuit theory by adding a external source pin to clarify matters. Create your own external source power symbols (i.e +5V_Ex) in your own library just by editing the power library symbols and changing the power input pin to power output pin. Now connect this external source to your power net at the power entrance point to the board (or any other convenient point but just once). This will solve the problem and will also replicate the actual physical power flow. Same goes for external signal sources as well. There may be some issues with regards to net names (e.g. +5V or +5V_Ex). This should not be a problem. What KiCad may do in future is introducing port pins for external power and signal sources which will have lower priority in establishing net names.

The PWR_FLAG already handily solves the problem, and indeed has solved the problem for many years.

But just once? - very optimistic.
The information of being power output is lost after:

  • going through PTC,
  • going through protection diode,
  • going through L in π filter,
  • going through ferrite bead used in VCC line,
  • going through 0R.

You forgot fuses, jumpers and net-ties, and probably a bunch more.
The only real solution I see is to add something to schematic symbols so they can be regarded as a short between nets for ERC purposes.

Thank you all for your comments. You are absolutely right. It will a temporary solution to get you past the initial stages of ERC check when you do not want to much litter. It is just a solution to power balance and as I mentioned it does not solve the problem with power net names. Once you’re past the initial ERC check you can remove them and check the ignore box. That is the reason I mentioned my suggestion to KiCAD teams for creating an external source category both for External signal and power outputs. You can also introduce fictitious components with power and signal output pins. This will eliminate the issues you listed but it is much more cumbersome and messy leaving you with a hidden components. I think the best solution will be external sources. In any case this boils down to Piotr’s solution. Power flag also works similarly but in principle it is not a source nor a component. Regards to all.

Please also note that components like fuses, links, power line filters, PTCs and the like may be assigned one power input pin and one power output pin to solve the problem. Also connectors and the like may be assigned power or signal output pins. However the following for component update menu must be provided. 1- As for connectors and the like menu must allow selection of leaving pin status unchanged (also some other component properties). 2- Since library editing is not a practical method. Components like PTCs, filters, etc. must have the suitable pin naming conventions.