KLC Addition - PWR and GND pins

[SchrodingersGat]

Nominally we suggest PWR pins are located at the top of a symbol, and GND pins at the bottom. However this is not stated in the KLC rules.

I suggest that rule 3.5 be updated as follows:

Old Rule 3.5

Whenever possible, inputs are on the left and outputs are on the right.

New Rule 3.5

Wherever possible, pins should be arranged by function:
* Power pins should be placed at the top of the symbol
* Ground pins should be placed at the bottom of the symbol
* Inputs should be placed on the left of the symbol
* Outputs should be placed on the right of the symbol

[CarlPoirier]

Sounds good, can't we put that in one short sentence?

Whenever possible, power pins are placed at the top, ground at the bottom, inputs on the left and outputs on the right.

Maybe it is clearer using sub-bullets?

[SchrodingersGat]

I would lean towards bullets for clarity, especially as many users are English as a second language. Thoughts?

[CarlPoirier]

Then we better split most rules into bullets!

[SchrodingersGat]

I can tackle this.

[diggit]

I agree on bullets.

There are negative and positive power pins. Ground is power pin too. I'd mention control/controlled pins too. Wee can add examples...

Wherever possible, pins should be arranged by function:

• Positive power pins should be placed at the top of the symbol (VCC, VIN, VDD,...)
• Ground and negative power pins should be placed at the bottom of the symbol (GND, VSS, ...)
• Input or control pins should be placed on the left of the symbol (OP-AMP +-, SPI, I2C, UART,...)
• Output or controlled pins should be placed on the right of the symbol (Vout, RS-485, Ethernet, ADC in, DAC out,...)

[jkriege2]

Hi!

I only see obne (special case) problem with these rules: What happens if you try to design a 7905 or comparable neg. regulator ... is the GND pin now at the bottom or at the top?

Otherwise: That would be a great addition!

Best, JAN

[SchrodingersGat]

Great suggestions @diggit

I have mocked up some changes here: https://github.com/SchrodingersGat/kicad-library/wiki/KLC

Let me know what you think - @CarlPoirier if you're happy with this I'll transfer it to the KiCad page

[SchrodingersGat]

@jkriege2 regarding the exception above - I have added a section in the text specifically relating to exceptions. There are always going to be exceptions to every rule!

[SchrodingersGat]

I have also added a draft for 3.10 as requested in https://github.com/KiCad/kicad-library/issues/884

[diggit]

As agreed in #869, 3.2 2. bullet should be improved. There were ideas, but not exact formulation. maybe sth like this...

• Length can be increased in steps of 50mils to accommodate long pin numbers and graphic pin styles.

[SchrodingersGat]

@diggit I have updated 3.2.2 as requested

[CarlPoirier]

It's great. In 4.4 I'd put the examples on the same line such as in 3.10.4. Rule 3.10 is nice as well. Once it goes live, don't forget to put your name at the top besides mine!

[SchrodingersGat]

Updated

@CarlPoirier @diggit @jkriege2 let me know if there is anything else that needs changing, otherwise I'll transfer it across :)

[jkriege2]

Hi!

just some comments:

1. in 3.2.bullet2, also add (1.27mm) after 50mil for consistency with the first line
2. Do we have a rule for the filled background and 0.01" line-thickness of box symbols now? I didn't spot it ...
3. What about the line-width issue I raised here: https://github.com/KiCad/kicad-library/issues/885
4. 10.6 should maybe be reformulated ... don't really know what it should tell me (see also https://forum.kicad.info/t/survey-footprint-attributes/2405/11). Maybe this:

   For SMT components (mostly SMD pads) the attributes field is set to Normal+Insert, for THT components to Normal and for any other components (e.g. edge connectors, logos, ...) to Virtual.

Best, JAN

[ghost]

BTW. In the KLC Wiki page https://github.com/KiCad/kicad-library/wiki/Kicad-Library-Convention you could include some graphical examples of some rules for better understanding.

[jkriege2]

@keruseykaryu I also had that idea ... but no time so far to prepare some ... I can see if I find some images in the next days/weeks and we discuss them as a new issue? Then we can go forward with the changes above and add the images in a second discussion. OK?

Best, JAN

[jkriege2]

Please note that I updated my post above (reformulated new rule)! JAN

[SchrodingersGat]

@keruseykaryu yes this is a fantastic idea - visual examples would be very helpful.

@jkriege2 good suggestions:

• I have added (1.27mm) to 3.2
• I have included background fill and 0.01" width into 3.3 (Now called Symbol visual style)
• Regarding line width for text in footprints, I have added this to rules 6.5 and 6.8
• 10.6 has been fixed - this was super vague previously, good catch. I have updated this.

[SchrodingersGat]

I have also spotted an inconsistency in the rules.

3.5 -> Refdes must be placed on Silkscreen layer, size=1.0mm

10.5 -> Refdes must be placed on the Fabrication layer, size = 2.0mm

This is one that has been the cause of much debate, but we must have the refdes on the silkscreen layer, surely? How should we resolve this?

I would suggest removing rules 10.4 and 10.5 as they are covered in 3.5 and 3.6. Further, these are not really "properties" of the footprint more than graphical elements.

[jkriege2]

Hi!

1. about the REFDES: Currently we have it with size 1mm on SilkScreen. I think it would be great to have it with this size on both layers, but as I understand that cannot be done automatically. So for now I would set size to 1mm for both and say SHOULD for FabLayer ... Maybe we can even tell in one sentence hoe to achieve the second label on f.fab (as user-text %R on F.Fab).
2. We are still missing a rule for pin-numbering (I suggested a draft there: https://github.com/KiCad/kicad-library/issues/884):

3.11 Symbols must have all pins of the package explicitly available. If they are not connected, they should be marked as such, named NC and set to be invisible. This is required to allow for the use of KiCAD's pin count filter.

3.12 Exposed pads of a device must have their own pin, typically number max. pintcount+1, e.g. pin 9 for a SOIC-8 with exposed pad. The name of this pin is often set to PAD or or a name indicating its function, e.g. GND/PAD

Best, JAN

[jkriege2]

Hi!

I'm also opening an issue to discuss possible images: https://github.com/KiCad/kicad-library/issues/891 If you like some, just copy them from there into your draft!

Best, JAN

[CarlPoirier]

Just to clarify:

Both the value and refdes need to be on the fabrication layer. This has been discussed on the mailing list and in the forum thread I linked in the first email. Rule 10.5 and right, 3.5 should have been removed.

Carl

[jkriege2]

Then to comply with the current usage in the lib, I would suggest this altered rule:

10.5 Reference designator has a height of 1.0mm is placed on both the fabrication and the silkscreen layer. With current KiCAD versions, this can be achieved by placing the default REFDES label on fabrication layer and a user-defined text label with the contents %R on the silkscreen layer.

What do you think? I formated the changes in a bold font and the instructions in an italic font.

best, JAN

[jkriege2]

Hi!

due to a comment on a bug in my images´, I started pondering a bit with the counter-clockwise-rule for pins ... and I'm not so sure about it. I would see the following example as a logical pin-ordering (and would expect it like that): Here all IO-ports are on the right and are ordered top-to-bottom, the way we read (top-to-bottom), which seems to me to be the direction to expect.

In this example, there is also a clock-wise ordering, which is a bit strange as it is different from how we read (it is top-right -> bottom-right -> bottom-left -> top-left): Here maybe having PA/PB/PC on the left (to->bottom) and the rest on the right (bttom->top) might be better, which would conform to the CCW-rule.

In all I would maybe suggest to alter that rule:

Ports should be ordered as follows:

• when all ports are on the right, they should be ordered top-to-bottom,
• if they are distributed over more edges, they should be ordered in a counter-clockwise-fashion, starting at the tope-left.

What do you think on that topic?

best, JAN

[SchrodingersGat]

What about simplifying:

Port pins should be ordered from top to bottom

[SchrodingersGat]

I have now expanded "General Rules for Footprints" and added "Rules for SMD Footprints" and "Rules for THT footprints".

Additionally, there were previously three rule groups governing naming of footprints - these have been consolidated into a single group. There are no auto-checks for these groups currently.

[SchrodingersGat]

Also, I find rule 7.2 very hard to parse:

Pad 1 is on the left first, then at the top, except at the top for PLCC (IPC-7351).

@CarlPoirier as you are the one who wrote this, is there a better way of expressing this?

[CarlPoirier]

I can't remember a case where placing the pad 1 on the left would not result in it being at the top at the same time. So I'd say:

Pad 1 should be placed at the top left. If impossible, it should be placed closest to the top (IPC-7351).

[SchrodingersGat]

I have made a further update to https://github.com/SchrodingersGat/kicad-library/wiki/KLC addressing these latest issues

[evanshultz]

@jkriege2 I really like your idea above. It makes sense to me. 2 quick notes:

• Typo of "address" in the blue bubble
• Maybe change "stuff" to something more concrete if you'd submit this screenshot for inclusion in KLC

[jkriege2]

Hi1

I would also suggest an adition to rules 6.x:

6.8 For some general classes of components, specific prefixes should be used, when generating new footprints as this way the fotprints for that class of component can easily be filtered. Generally the name for a new footprint should be oriented on the existing footprints for that class of component. Currently these are used:

• C_ for non-polarized capacitors
• CP_ for polarized capacitors (e.g. elcos, tantal caps, ...)
• Crystal_ for crystals
• D_ for diodes
• Fiducial_ for fiducials
• Filter_ for filters
• L_ for inductors
• Label_ for Labels
• LED_ for LEDs
• MountingHole_ for mounting holes
• Oscillator_ for (crystal) oscillators
• Potentiometer_ for potentiometers
• R_ for resistors
• Relay_ for relais
• Resonator_ for resonators
• RV_ for varistors
• SW_ for switches
• Transformer_ for transformers
• VALVE- for valves

What do you think? JAN

[jkriege2]

Hi!

we should really move forward on this! I just went through it again. In addition to my comments above, I spotted these:

1. KLC 3.11 We should emphasise that the FPFilters need to be there and set correctly EVEN IF the footprint field is filles
2. Maybe extend KLC 3.6 by examples (not really sure if it's necessary, but it might help newbies):
   • pins on devices such as resistors, caps, transistors, diodes, ... are usually PASSIVE
   • power supply pins such as VCC,V+,Vdd,... (also GND!) should be set to POWER_INPUT
   • IC I/O/BIDI/OpenCollector/OpenDrain/...-pins should be set as their function dictates
   • power-outputs (e.g. the output of a voltage regulator) should be POWER_OUTPUT
3. last point in KLC 3.12 change to (I've seen people adding geo-info to match a simple SOT-23, which will then never match): Filters should match as much dimension information as possible to be as specific as possible, if that is available in the appropriate footprint names. E.g.
4. Should we have a screenshot of some simple components (resistors, diodes, ...) as examples? Especially concerning the IEC-style of diodes ...? If so I could prepare some!
5. KLC 3.3 should also contain a reference to IEC-style (diodes, resistors...!): Use the IEC-style for electric/electronic symbols for this library.
6. KLC 6.1 change Capacitor to C_?
7. KLC 6.7 add example ", or _ThermalPad in combination with 1EP for bottom pads with thermal vias."

best, JAN

[jkriege2]

Hi!

one more extension request: Should we reformulate 10.2 from

Doc property contains a full description of footprint.

to

Footprint meta-data is filled in as appropriate.

• Documentation field contains comma-separated device information. You may add a URL to an appropriate datasheet here.
• Keywords field contains space-separated keyword values

Best, JAN

[jkriege2]

as discussed elsewhere we should also have

1.8 Library- and footprint-files use UNIX-sytle line-endings (i.e. \n = LF = 0x0A).

Best, JAN

[jkriege2]

I just played around with that last rule (and write check-code to check and fix it: https://github.com/KiCad/kicad-library-utils/pull/77). It turns out that KiCAD footprint editor on Windows reverts the line-endings to Widnows! I submitted a bugreport asking for a change of that behaviour: https://bugs.launchpad.net/kicad/+bug/1663990

Best, JAN

[SchrodingersGat]

Jan - updates here - https://github.com/SchrodingersGat/kicad-library/wiki/KLC

I am hoping to get this completed and include your images very soon.

Thanks for filing the bug report, that would be very handy.

Do you know if the symbol editor (eeschema) has the same behaviour on windows?

[jkriege2]

Hi!

nice work!

I just saw one thing: Aren't we missing now how to calculate the courtyard clearance in KLC 7.5 (i.e. from pad-outline or/and package outline)?

JAN

[jophut]

Not sure if this issue is the right place to post the following: I've written a piece of python code to identify pins on the same coordinate. Currently I've put it into KLC rule3_1.py, but maybe a new rule would be better? Would you be interested in a PR?

[jkriege2]

Hi!

yes, that might help in some cases ... please submit a PR, so we can discuss this issue/suggestion there!

Best & thanks, JAN

[jophut]

@jkriege2:

please submit a PR, so we can discuss this issue/suggestion there!

PR submitted: https://github.com/KiCad/kicad-library-utils/pull/85

[jkriege2]

@SchrodingersGat : I think we should clarify in 3.1 that these rules do not apply to devices such as diodes, resistors, ... any idea how we can make that into a concise statement?

[bobc]

as discussed elsewhere we should also have

1.8 Library- and footprint-files use UNIX-sytle line-endings (i.e. \n = LF = 0x0A).

I think you need to drop that rule, as the code change to KiCad is not likely to happen.

[bobc]

Given that this new KLC is a major change since the previous one (basically a rewrite), and also many of the rules have been renumbered, it should be versioned 2.0.

[SchrodingersGat]

@bobc thanks, 1.8 has been removed

[jkriege2]

Can we have the images inlined again? I liked that muhc more ... because the links are really non-obvious and somehow get lost in the text ...

JAN

[SchrodingersGat]

Hi all,

I think that KLC 2.0 is ready to go. Can you please have a read through to see if I have missed anything?

There is an update to the KLC scripts waiting too - https://github.com/KiCad/kicad-library-utils/pull/81

Thanks to @jkriege2 for the example images, they're great :)

[poeschlr]

All in all i really like the new klc. It is really detailed and i think there is a lot less ambiguity.

I have a question about the rule for courtyard clearance

Clearance is measured from package, pads, and silkscreen

Should the courtyard distance really be measured from silkscreen not from component body? The Silkscreen is by definition outside of the body outline. (Rule: Silkscreen is completely visible after board assembly)

About the silkscreen: In my pull request https://github.com/KiCad/Connectors_Phoenix.pretty/pull/44 You stated the following:

I agree that detail for connectors like this should be on Silk not Fab. Perhaps this needs to be clearly specified in KLC.

Did you change your mind or did you forget about that? I think details on silk would violate the current rule: "Silkscreen is completely visible after board assembly" Maybe make an "exception" similar to: Silkscreen underneath the footprint is allowed if it makes hand populating the component easier. Or maybe change the first rule to something similar to: Component outline, pin 1 mark and reference on Silkscreen are completely visible after board assembly.

[SchrodingersGat]

Hmmm good point I did forget about that @poeschlr

Perhaps Silkscreen is allowed for hand-loading of THT components. The rule is really to prevent issues with SMT design.

The Clearance is measured from... description is the one I'm having most trouble with....

[jkriege2]

About courtyard: The question is IMHO what the courtyard is used for: I presume it's for e.g. an autoplace or DRC to prevent components from overlapping. I would say: Measure from pads and outline, because usually teh Silkscreen will be inside, i.e. non-overlapping, only in some cases it may be outside and then it's more a problem of look, not function. Also if we measure from silkscreen we would also have to include the freely movable REFDES, which makes all courtyards ver large.

Abozt the KLC-images: Why are the now there only as links? I think those are easily overlooked ...

JAN

[SchrodingersGat]

I'm happy to measure from pads and outline - is this what the checker does currently?

Re: Images - I thought it looked messy with inline images, we can make the link text larger to make it more visible?