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

@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.

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

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.

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.

As Andy_P already answered, most cases are handled by the PWR_FLAG symbol.

I do not see this as a solution, but as a (temporary) hack. Making non-polarized schematic symbols polarized (and in an invisible way?) just to satisfy the current ERC is not a good solution.

The current power symbols in KiCad are also … organically grown over 30-odd years. For example they can not be edited, and if you want to make your own and change it’s name, then it does not work, because the actual global label is derived from the pin name and not the symbol name. It’s one of the kludges still left in KiCad, but KiCad has improved immensely over the last 5 years or so and I expect things like this to also get fixed in the (hopefully) not too distant future.

But a real fix should be in the KiCad software itself, and not by hacking into library symbols.

Symbols could have a flag telling ERC that symbol transmits power through it. That could be valid even for symbols having more than 2 pins (current sensing resistor, may be coil with taps). If I use a fraction of an ohm resistor to ensure LDO stability I see no problem to have this resistor defined with that flag set.

1 Like

That’s pretty much what I wrote 4 days ago:

But a simple “flag” would not suffice. For example it does not work for a common mode choke which has two inductors in it. Other parts where it does not work is for jumper blocks with multiple jumpers, such as for example used in plugs for adapting to different mains voltages or for “feed though capacitors”, which also have a distinct GND pin. Parts may also have mechanical pads you don’t want to include in this system.

I’m thinking more along the line of adding some pin list in text format of which pins should be shorted for ERC purposes.

The flag is too simple. You are right.
I was never thinking about ERC errors deeply as you probably know what is my solution to that problem that I once said I will not write it once more in each thread about ERC as I was doing in past :slight_smile: