KLC: S4.4: Clarify electrical pin type for I2C busses

[antoniovazquezblanco]

There has been a long ongoing discussion about electrical pin types in particular cases. A clear example is I2C clock lines as they can be defined as multiple types depending on the criteria used.

I don't know if we can come up with a rule to cover all the possible cases. For that reason I think that those particular cases that we don't agree on, a decission must be taken and documented for the sake of consitency.

An example and I think the longest discussion about I2C clock pin types I have found:
KiCad/kicad-symbols#350

[poeschlr]

I don't want to get the KLC to that level of hand-holding to be honest. We might want to add a bit more specialized wording but if we list what type some pins with a particular functionality should have then we will end up with a very long list in after a while.

---

Maybe something like this should be specific enough and still generic:

• Choose the electrical type of a pin in such a manner as that it is as specific as possible while not giving any false positives no matter how the pin is used. (In accordance with the intended use-cases given in the datasheet)
• Take a look at other similar parts to get an idea how this was handled in the past.
• Because of KiCad limitations this means that especially for multi purpose pins a use-case specific pin type is left for the user to make. (Will require a project specific symbol)

We can in addition link to further documentation:

• Section of the official EESchema documentation (12.8.4) http://docs.kicad-pcb.org/5.0.0/en/eeschema.html#pin-creation-and-editing
• FAQ entry on the user forum: https://forum.kicad.info/t/electrical-type-of-schematic-symbol-pins/9439

[poeschlr]

I also just noticed that the last point does not really fit into this section:

Pins must not be 'double inverted' by assigning the inverting graphical symbol and also having a bar above the name of the pin

Has nothing to do with electrical type. (Should maybe be moved to S4.1)

[antoniovazquezblanco]

I understand your position. Maybe going to that level of detail is not a good way to proceed.

In any case, there has been a history of non-agreement about the issue and there is a number of non-consistent symbols in the library so I feel the need to unify them for better library quality. Given that you are the one coordinating the librarians at the moment I would ask you to evaluate the arguments available and to please provide a recommendation in favour of one of the solutions.

I would even try to check this with the library check scripts in order to avoid future quality degradation of the symbols. In this sense, checking for a rule that doesn't exist as such is not a very good way to proceed...

Can you guide me in a way fordward to unlock those stuck contributions and to improve quality?

Thank you and sorry for the push on the situation

[poeschlr]

My main point is that the KLC should not be a place to look for documentation. It might be a better approach to improve the official documentation instead.

In any case, there has been a history of non-agreement about the issue and there is a number of non-consistent symbols in the library so I feel the need to unify them for better library quality.

I read the full thread you linked. It is a bit of a trainwreck to be honest. There was a lot of talk about unrelated stuff in there which makes it extremely hard to follow. And the discussion really went in circles.

I think the reason behind this is that ERC is not really flexible enough to deal with pins like I2C clocks of slave devices with clock stretching. I would think that such a pin is a combination of an input pin plus a open collector. But such a pin type does not exist in kicad. So the next best thing is either choose more "restrictive" and go with input (will be the correct choice when you see the pin type as only used for ERC) or go more generalized and use Bi-directional. (this might be the choice if you want to see the pin type as also informing the user about information flow)

I think the rule-set i posted above will force the choice of input as it is the most specialized type that does not result in false positives. (The pin never is a output on its own so bi directional would be too generalized making ERC practically unusable)

The current rule set does indeed not specify anything that would be of use here as it simply gives a few examples without giving the reason behind their choice.

I would even try to check this with the library check scripts in order to avoid future quality degradation of the symbols.

I really like the general idea behind it but i fear it might be a bit naive to think that simply adding more and more checks will improve the overall quality of the lib. I really see the danger of getting to a stage where travis basically throws more false positives than useful results. (Even the current pin type checks are more often than not simply wrong. Without context the pin name it self is simply not enough to make a decision.)

[poeschlr]

For further guidance we could also give an ordering of pin type "specialization" (or restrictiveness)

Here my interpretation of the order from most general to most specialized:

• Unspecified (Not allowed in the official library)
• passive
• bi directional
• input, output
• tri-state, open collector, open emitter (specialization of output)
• power output
• power input (If common for power output and power input side then input takes precedence)
• not connected

[evanshultz]

I think that's a generally good way to abstract pin types instead of listing pin types bus-by-bus or case-by-case, but there are a few thoughts:

1. Of the two philosophies about pin type mentioned above, signal/information flow versus ERC, the user doesn't see the pin types when building a schematic. Only the ERC engine will consider pin types that can affect the user, so why isn't making ERC as helpful as possible the primary objective in picked type?
2. Analog and digital (or logic) pins may be best considered with unique lists. Some pin types would only really apply to logic pins while other pin types would have a different meaning in the two domains.
3. This doesn't resolve the item I brought up, which is that making an I2C slave device's SCL pin Input type is the best way for the ERC engine to help the user. Yes, there are various perspectives that have merit. In the list above, Open Collector would be more specific than Input type and this is likely to be the best choice in most cases but not with an I2C slave device.
4. Some pins are power and can go both ways. For example, the VREF pin on a MCU's ADC can often be connected to an internal reference or accept an external one. Which pin would be used then? Power Input would be the most specific in the list above but there are cases where the internal reference can source a bit of current so then the user will need a Power Flag on the net. Some users would select Bidirectional in that case but I think that's unhelpful since that pin won't be connected to other pins which could cause contention according to the ERC engine.
5. Passive is quite low (actually towards the top, but you know what I mean) on the list but it's a good choice for decoupling pins which can't source current and other "analog" pins. In that case, the pin could be driven by a digital gate or drive a signal to a digital gate but won't cause false negatives. This is another point in favor of segregating "digital"/logic pins from other types when considering pin type.

I'd like to contribute an idea instead of only complain and play devil's advocate, but I don't have any better suggestions right now.

[poeschlr]

Regarding your points:

1: I thought my description made it clear that i try to find simple rules to make ERC as useful as possible (with generic symbols)

2: Yes the priority list should probably be more like a tree. (Is however hard to show with text only. So this will need a graphic)

3: It would actually. (at least my intended interpretation of the algorithm) The algorithm would stop at input as it is the most specialized that does not give a false positive. (It would go over bi directional as input still fulfills all requirements.)

4: From my priority list: power input (If common for power output and power input side then input takes precedence) -> meaning if a pin can be both then it is to be defined as the worst case. In this case power input. (Generic symbols that encompass all possible usecases have limitations. More useful definitions require usecase or project specific symbols. These are however the responsibility of the user)

5: Another problem of having a linear representation. I think a more detailed tree view (or even forest view) would solve that.