horizon-eda / horizon-pool-convention Goto Github PK

Discussion from #12 and #15 continues here.

The most-used packages in the pool will be generic ones, i.e. packages with standardised names used by multiple manufacturers. The pool’s folder structure mirrors their importance by placing them right into packages, using the manufacturer sub-folder for other, more special packages.

As it came up during the discussions linked above, this distinction currently isn’t very well-defined in the convention. Problems can arise when different vendors have different ideas about some otherwise generic packages. This can include varying physical dimensions (and thus a different package layer and courtyard) or different pad dimensions for the land patterns.

When creating a package for the pool, you wouldn’t notice there are differences between vendors just from looking at your particular part’s data sheet, so what should the process be for new generic footprints? We want to arrive at a situation where the generic package is the most useful and covers most manufacturers. True universality cannot be guaranteed as checking every existing part with the package name in question won’t be feasible, so we’ll have to find a best-effort solution.

I see three main ways of approaching this:

1. Require a contributor to check drawings from multiple manufacturers before adding a generic package. Reviewers for a PR containing a generic package would naturally have to check a number of drawings from different vendors, too.
2. Don’t restrict generic footprints, but require later contributors to move packages which are, in retrospect, not generic to manufacturer folders, e.g. if the new part’s land patterns don’t agree with the existing package’s. Naturally, you’d have to check with at least a third manufacturer whether the existing package or your new one should be the generic one.
3. Always create new packages as manufacturer-specific. When creating new parts, check existing packages from other manufacturers and promote a package to generic if the drawings agree.

Neither solution is perfect, but I’m tempted to prefer the second one because you’d have to validate the footprint for every new part anyway. With the first option, the bar for a generic footprint would be raised significantly and we might end up with lots of identical copies in different manufacturer folders. The last option provides a way around this, but appears to be the most complicated and brittle to me.

I'd suggest adding a checklist, giving information about how to contribute to the master pool. Especially oriented for first time contributors.

KiCad's convention requires that a THT footprint's pin 1 pad is rectangular, except for non-polarized parts. The pool's parts currently have consistent pads for everything.

This PR made me think of putting this question up for discussion.

There should be some rules clarifying exactly when one physical part should correspond to multiple units/symbols. The classic cases like a hex inverter or quad op-amp won't be questioned, but there are a lot more to consider. Maybe a general rule isn't possible, but some guideline would still be helpful then.

Here's my attempt of a somewhat ordered list of the special cases. Additional suggestions are welcome, I probably missed some which should be considered.

1. Analogue/glue logic ICs
   1. Multiple identical “gates” in one package, like a dual op-amp or dual shift register. Following the common approach, these would have a separate power unit and multiple identical units.
   2. Multiple different “gates”, e. g. different logic in one package or a comparator plus reference. They are still probably used separately, so it makes sense to keep them as separate units IMHO.
   3. Single gates/op amps/comparators/etc. Personally, I'd use a functional and a power supply unit here as well. The units from a/b can be reused here and swapping out a single gate for a dual one in a schematic later on will be much easier.
   4. Single op-amps with extra pins, e. g. for frequency compensation, shutdown, balance. These often require external circuitry referenced to the op-amp's supply, so should we break the symmetry here and include the power pins as well within the one, single unit?
2. Large digital ICs
   1. MCUs could be split with each port being one unit plus another unit for all power supply, clocking and analogue stuff. Personally, I'm against that as the ports are not really separate and quite often you'll have functionality spread across several ports.
   2. FPGAs could be split similarly. Here, I/O banks often even have separate supplies. I don't have much experience here.
3. Discrete/passive networks
   1. Resistor/capacitor networks. If the components are not internally connected, these make sense to end up as multiple units IMHO. If not, the schematic might get a bit convoluted.
   2. Multiple transistors in one package. These are mostly used for thermal matching, so I'd keep them together.
   3. Diode networks are mostly for ESD protection, where the individual diodes would end up in the same place on the schematic anyway, so I'd keep them together as well.
   4. Multi-colour LEDs. Does not make much sense to separate them IMHO.
4. Misc stuff
   1. Optocouplers, both single and multi. Multiple optocouplers from one package should be their own units IMHO. Do we want to split the transmitting and receiving part? I've seen this in some schematics and liked it pretty much, but it could get confusing with more than one optocoupler per package.
   2. Relays, similarly. I'd personally split coil and each set of contacts.
   3. Switches. I'm not really sure about these, but my gut feeling says to keep them in one unit. Except maybe for stacked rotary switches?
   4. Multi-section potentiometers. These can look pretty awkward in schematics if kept together so I'd use separate units.

I'm interested in what you people think of this topic and what arguments you have for general or specific cases. Anyway, I'm not really fond of putting a huge table in the convention for which parts should be split and which shouldn't. I'd hope that could be condensed into some short guideline.

I’ve been orienting packages such that pin 1 is near the top left, which is in line with IPC-7351 and KiCad’s rules. However, it currently isn’t part of our convention. I have dedicated an issue to it because I think this rule, even with KiCad’s exceptions, has a few implications worth discussing.

Multi-row connectors

If taken by the letter, the ‘pin 1 in the upper left corner’ implies a tall female DB-25 and a wide male DB-25 footprint. Having male and female variants of the same connector at 90° to each other isn’t really intuitive.

To solve this, I’d add a prioritised rule to prefer tall footprints rather than wide ones. This is in line with the existing packages in the pool. This additional rule would have to come after a two-terminal exception like KiCad has, though.

Right-angle parts

We already have a special rule for electro-mechanical parts, advocating a package origin in a place that makes sense mechanically. In the same vein, I’d specify that the user-facing side of right-angle parts (connectors, LEDs, potentiometer, …) should be on the left.

If the female DB-25 from the previous example were a right-angle connector, its pin 1 would now be on the bottom. However, I’d still prefer that to having male and female connectors look in different directions.

Proposed rules

In summary, I’d add the following package orientation rule set, in order of priority:

• Right-angle parts must have their user-facing edge facing left.
• Two-terminal devices must have their pads next to each other, with pin 1 on the left.
• Prefer tall footprints to wide footprints.
• Pin 1 should be near the top left corner. If that is ambiguous, prefer pin 1 on top.

Open questions

Naturally, there are a lot of different cases to consider. The rules above would, for example, lead a slightly non-intuitive orientation of a tab-down TO-220 (with the mounting hole below the 3 pads). I think, however, that these rules should cover the majority cases well enough. If I did overlook something important, please point it out!

Currently, the convention calls for no dash in the package name:

[…] A primary identification feature (like LED or DIP8 or TO220). Note that there is no dash included (SO8 instead of SO-8, etc.).

IIRC that was based on existing packages at the time by @carrotIndustries. As discussed here, we might want to change that to the opposite as the variant with a dash is by far more common. The file names would include the dash, too (for example DIP-20_7.62mm_lead_span_2.54mm_pitch).

Right now, the pool contains a mixture. Some files are in all caps like the MPN, some files lowercase. I know the file name isn't really important but this should be clarified.

I've recently realized that NXP and Diodes Incorporated have two different packages called SOD123F. They're similar, but I think they're different enough to want different land patterns. I've created a footprint for the NXP version, with an eye towards contributing it to horizon-pool, and I'm not sure what to call it. I started with packages/diode/SOD123F similar to the existing packages/diodes/SOD123, but after realizing there were two versions I'm not so sure.

NXP's document recommends a pad width of 1.2mm. The Diodes document says the maximum lead width is 1.05mm, so their recommended pad width is 1.8mm. Those are far enough apart I'm not sure it's reasonable to use the same package for both of them.

Looking at documents from a few other companies, it seems like NXP is the odd one out. Maybe that points to packages/manufacturer/nxp/SOD123F_nxp being the preferred answer? Or would it be packages/manufacturer/nexperia/SOD123F_nexperia?

Currently, there is no rule where the origin of a package should be. For reference: KiCAD has the following rules:

• For SMT, the anchor should be in the center, if the datasheet doesn't explicitly specify one (http://kicad-pcb.org/libraries/klc/F6.2/).
• For THT, it should be at pin 1 (http://kicad-pcb.org/libraries/klc/F7.2/).

Personally, I'd use the exact same rule for SMT components.

I'm not sure if the THT rule is the best one here, though. While it apparently has it's reasons in the pick and place business, it is pretty inconvenient in my opinion.

• Rotating parts is awkward.
• Electromagnetical parts like pushbuttons, potentiometers come with a very logical choice for the footprint origin. Also, a well-placed origin would be very convenient for edge-aligned connectors.

The only discussion of the KiCAD people about this issue I found is this one. It doesn't go into much detail and I don't know much about pick and place, so it would be best if someone knew how much freedom in choosing the origin we actually have.

Sorry that it has taken me so long to open this issue. Now, it's finally here for you all to discuss!

There should be a rule where power pins have to be placed in symbols. KiCad says that they must be on the top and bottom of a symbol. I already had started a discussion with @carrotIndustries about this question before I started this convention attempt.

In my opinion, the “always on top/bottom” rule isn't optimal, but finding a concise alternative isn't easy. In the issue linked above I proposed some, which I want to summarise along with some subjective pros and cons.

• Positive on top, negative on bottom (the KiCad way)
  • Pro:
    • People are used to this convention.
    • Good usability for analogue ICs.
  • Con:
    • Symbols are unnecessarily large, because pin names get in each other's ways (I don't like the aesthetics of this one).
    • Placing bypass caps on the supply rails is awkward.
• Use the alignment taking up the least space in the schematic, including external components used in most cases (e. g. for microcontrollers: bypass capacitors, crystal, etc.)
  • Pro:
    • Tidy and space-saving schematics guaranteed.
  • Con:
    • Not that objective and hard to check.
• Separate power unit for all cases except where the power pins have more like an analogue function (e. g. voltage regulators)
  • Pro:
    • Having the power supply separate from the signal flow/main logic can boost readability.
    • Having a power schematic sheet gets straightforward and natural.
    • Supplying different voltage levels to an IC is easier. Putting a filter between VDD and VDDA of a chip is cleaner than ever.
  • Con:
    • Favours schematic fragmentation and might hinder readability.
    • More error prone: It's more likely to forget a power component than to miss an unconnected pin already on the schematic (although the ERC should check for this?).

I'd like to hear some more possibilities from you where the power pins could be and how we can boil that down into a rule.

KiCad specifies:

The courtyard should include any extra required clearance for mating connectors (for example).

which IMO makes a lot of sense to adopt. Some thoughts from my side:

• If there are multiple possibilities (e. g. vertical and right-angle screw terminal plugs for a terminal block) occupying a different amount of space on the PCB, there should be alternate packages differing in their courtyard polygons.
• Do we only consider the “full plugged” state or also the space needed to remove or insert a plug?
• It makes sense to exclude connectors which have to be edge-mount here. What about connectors which are primarily used on a PCB edge? It is relatively easy to consider the space needed for a SD card, but estimating a plugged USB cable's courtyard effect would be near impossible.

Another matter of personal preference. I like underscores for spaces in filenames better, since hyphens are themselves often used as a minus sign or a separator in part/package names. Yet the pool currently uses hyphens, so that would be quite a change. Opinions?

There are some parts with exposed pads currently in the pool (QFN, …). Their exposed pads are all named PAD, which I'd like to keep, but extend to other “pad types”.

IMO, there should be a list of allowed pad names. These come to my mind:

• PAD for exposed pads
• TAB for horizontally mounted power transistors (TO220, etc.)
• SHIELD for cable or connector shields
• CASE for modules or where they serve a mainly mechanical purpose (with no electrical connection)

I'm a bit unsure whether SHIELD/CASE are good names resp. whether they make the distinction clear. Maybe MECH would be an option?