Fixing Atmel (now Microchip) MCU libs

[evanshultz]

@fauxpark has done a ton of work already. Here is what is left to consider.

• [x] 1. Shrink and align the boxes
• [x] 2. Move obsolete symbols to /obsolete
• [x] 3. Make sure all non-obsolete symbols have DCM metadata
• [x] 4. Pin types for all pins, especially the special-function ones that aren't power or GPIO.
• [ ] 5. Pin placement when you shrink symbols. Should all GPIO be on the left side, right side, distributed as evenly as possible, something else?
• [ ] 6. Align pin placement across symbols regardless of package. In some cases the symbol body size could be different between parts in the same family. For example, some parts could use both 100mil and 150mil pin lengths because the pin numbers use 2- or 3-characters depending on the package. So make two different body sizes with aligned pins or use 150mil for all pins so the body visually is a match?
• [ ] 7. Do all XTAL pins go on the same side? How far apart are they so a crystal symbol fits there nicely.
• [x] 8. Pin text offset should be 20mil.
• [x] 9. Place power and ground pins next to each other or leave a space between them (like the GND and EP pins, for example).
• [x] 10. Pin length should be 100mil if pin numbers have <3 characters (usually 99 pins or less). All NC pins can be 100mil.
• [x] 11. Place refdes and MPN inside the symbol outline if it's large enough?
• [x] 12. Rename AT89S2051/S4051-PU and AT89S2051/S4051-SU symbols to have a "24" in them (datasheet indicates that this is the clock speed i.e. the AT89Sxxxx versions run at 24MHz). So rename as AT89S2051/S4051-24PU and AT89S2051/S4051-24SU.
• [x] 13. Review/fix description, keywords, and datasheet for all symbols.
• [ ] 14. Remove MPN suffixes the current library considers extraneous, such as packaging and lead finish.
• [ ] 15. Ensure proper wildcarding of Microchip PNs; for example, PIC16F18344-GZ should be PIC16F18344-xGZ.
• [ ] 16. Ensure descriptions are unique. For example, add voltage supply ranges to differentiate V and non-V version of the same part.
• [ ] 17. Spread apart CAP* pins to fit a capacitor symbol between them? (ATxmega128B3)
• [x] 18. PDI_CLK should be Input type and PDI_DATA should be Bidirectional type.
• [ ] 19. Align VCC and VDD pin naming to that specified in the datasheet.
• [ ] 20. Assign footprints that match the actual package type (VQFN instead of just QFN). This should result in unique 3D models because of height differences. Also update the descriptions based on package type.
• [ ] 21. Rename MCU_Microchip_AVR to MCU_Microchip_AT90.

See https://github.com/KiCad/kicad-symbols/pull/373 and https://github.com/KiCad/kicad-symbols/pull/382 for some previous discussion on those points. To keep it all together, though, let's move all discussion here.

[fauxpark]

The pin name offsets should already be done.

RE renaming the 8051 symbols - should we just remove that bit from all symbols instead, or add more aliases for clock speed? Right now it seems there is mostly just one set of symbols defined for each device.

[evanshultz]

@fauxpark Now that https://github.com/KiCad/kicad-symbols/pull/389 has been merged, I checked off a few more items from the list above. Please confirm that the checked off items are correct, and also if there are any more items to add. If you're willing to keep going it would be great!

[fauxpark]

"Make sure all non-obsolete symbols have DCM metadata" can also be checked off - every symbol and alias has an entry in the DCM.

I'm continuing on in #504, which should check off "Shrink and align the boxes" and "Place refdes and MPN inside the symbol outline if it's large enough".

[fauxpark]

Second point (obsolete symbols) is finally done 👍 thanks @poeschlr.

I'll look at pin types next.

[evanshultz]

Just merged https://github.com/KiCad/kicad-symbols/pull/702, which counts towards the 4th item above.

[Elijahg]

Thanks for keeping the library up to date, but what was the reasoning behind removing the pin descriptions from the schematic symbol? It was extremely useful to have the various pin functions on the symbol to save hunting through the datasheet and cross-checking for each pin. This seems a step forward in neatness, but a huge step back in terms of functionality & ease of use. I'm going to revert to the previous library for now because of this.

[fauxpark]

There is a tradeoff here between completeness and compactness. Many of these devices have a lot of alternate pin functions, and keeping them all would result in unreasonably large and messy-looking symbols. The 100-pin ATmegas, for example, already take up most of the vertical space on an A4 sheet:

I have gone for a happy medium where each pin is described by the primary function (so mostly port numbers etc.) but also added some of the more common functions like XTAL, RESET and so on. This is admittedly a little arbitrary but I have tried to keep it consistent.

Having looked through all of these datasheets myself I can say you don't exactly have to "hunt" for the pin functions - they're reliably in the first couple of pages, and there is usually a table of contents as well if they aren't. When you're working with MCUs like these you should really have the datasheet open anyway for exactly this reason.

[Elijahg]

I completely agree symbols do get pretty massive for larger chips. That said, the length of the symbol won't change even with pin descriptions included, it only makes it a bit wider. Perhaps it would be better to keep it on the smaller chips and have a cutoff at say ~50 pins? I can't emphasise enough the importance of clarity in software, especially when ambiguity can cause an expensive mistake. I've been working with AVRs for a fair while, and short of knowing what pin does what, I know what each peripheral needs and don't really need the datasheet with pin descriptions.

Perhaps a better option would be mousing over particular pins showing a tooltip with the peripherals described, obviously this would require support in Eeschema. I think Fritzing(!) used to do something similar, though only for the port identifier.

I realise also you've kept descriptions for pins that are essentially required (reset, xtal) but perhaps a compromise toward more but not all descriptions would be better. For example PCINT isn't really needed on every pin as (almost) all pins are PCINT anyway. Describing pins by their most important function (I realise that is subjective) such as UART RX/TX, SPI, I2C, external interrupts, timer pins, ADC etc wouldn't use any more space than it does now, but would help clarity.

[poeschlr]

The future plan for kicad is to have pin alternatives where one can have alternative pin names and electrical types for each pin. Until this is implemented (Might not be before version 7) i agree with the way @fauxpark described. (He was not the first to go that way. @hackscribble started this with his rework of the NXP libs. This is at least a year ago if not two.)

[rossbishop]

I think the concept of the tooltips would be quite a sensible way to see extended pin descriptions to save on sheet space.

[poeschlr]

No matter what you can come up here. It will not be possible to be included before version 6 of kicad as it will require changes to the symbol file format. Here on the library we do not discuss such things.

So now my dreaded final point as the head of libraries:

• No more wishfull thinking here please. This is what the bugtracker is for!
• Newly added symbols for MCUs only contain the main identifier for the pin names. It is allowed to add one function to the pins if it is one that is expected to be used in every design (Reset, XTAL, JTAG, ...)
• Old MCU symbols can not change in this manner until we open the lib up for v6 development as it would require moving around pins.
• It is desirable to split up larger MCU symbols into multi unit symbols (one unit per gpio port plus one for the power supply part)

[evanshultz]

@fauxpark Is item 4 now checked off?

It looks like the 5th and 6th items will break symbols so they can't be done now. Is there anything left? Are there pin names that should be simplified now, or save the effort and wait until symbols can be shrunk (my preference)?

[fauxpark]

Yes, I believe so.

@SchrodingersGat noted in #1023 that some of the simpler ATtiny symbols are a little too tall - shrinking these would move the pins, but not rearrange them. Does that still count?

I think adding at most SPI/ICSP, and maaaybe I2C and UART to the pin names might be helpful but this may also require resizing a couple of symbols (not 100% certain).

[evanshultz]

Yes, if the pin position changes at all we'll consider it a breaking change since the schematic will lose connectivity if the symbol is updated.

I would also support a small subset of alternate pin functions, but we'd want to come to a consensus about what to add. And if it makes sense to invest the time at the point when we would get started before the glorious new file format is planned to be released. (Of course, we should add about 1 year to the planned KiCad release date to be in the ballpark of reality.)

I added another item above, to remove the parts of the MPN that we are currently considering extraneous.

[jaxter184]

Looking through the library, it seems some of the ATtiny chips are missing. The one in particular that I was looking for was the ATtiny404, but I also don't see the ATtiny412 or ATtiny417. Were these excluded on purpose? Or are they under a different name perhaps?

Also, not sure if there's a designated place for this type of question, but while I'm already here: how do I go about contributing to the KiCAD libraries? Is there some sort of style guide for symbols and footprints?

[fauxpark]

Looking through the library, it seems some of the ATtiny chips are missing. The one in particular that I was looking for was the ATtiny404, but I also don't see the ATtiny412 or ATtiny417. Were these excluded on purpose? Or are they under a different name perhaps?

I'm getting to them 😉 They weren't excluded, no one has submitted them yet. I've been working to improve the AVR libraries and I'm just getting to the adding-new-symbols stage now.

Also, not sure if there's a designated place for this type of question, but while I'm already here: how do I go about contributing to the KiCAD libraries? Is there some sort of style guide for symbols and footprints?

Yes, these are called the Kicad Library Conventions (KLC). You can have a look at it here: http://kicad-pcb.org/libraries/klc/.

[evanshultz]

Added more items to the list in the first comment from https://github.com/KiCad/kicad-symbols/pull/1093.

[fauxpark]

Hmm...

Remove MPN suffixes the current library considers extraneous, such as packaging and lead finish.

Lead finish can definitely go, but for these symbols, different packaging sometimes means different pinout, and even if TQFP and QFN have the same pinout (as in the mega32U4 and many others), there is still the extra pin on the QFN for the EP. Thus the packaging code is pretty much never extraneous here.

[poeschlr]

I think there is a misunderstanding. The package in which the part comes should stay encoded in the MPN (or added as cleartext to the base part number if there is no clear encoding for the package)

However there is often a second packaging option. One level up. Some manufacturers have different order numbers depending on how many parts you get when ordering one unit. (So do you get a tray of 100, a reel of 1000 or a single piece. Sometimes the number of parts per unit is the same but the container is different.)

[fauxpark]

I forgot about that. The only alternate packaging option is -R for tape & reel, which none of the currently submitted symbols include.

[antoniovazquezblanco]

Checked item number 18 in the main list due to the merge of https://github.com/KiCad/kicad-symbols/pull/1507

[chschlue]

I took the liberty and added task 21

We currently have _ATmega, _ATtiny and _AVR which consists of AT90s. All of these are AVRs.