I wonder why so few users ask for extended or better ways to add “descriptions” to libraries, symbols, footprints and more.
At the moment, we have “description” fields in symbols and footprints, but very limited:
Only a single line, no formatting
Hyperlinks can’t be combined with text: Either text or hyperlink. Only one hyperlink.
Descriptions for libraries are even worse: They are not stored in the library but in user-local config files (sym-lib-table and fp-lib-table). To transport this information to another installation, I need to open the source *-lib-table, search and cut the relevant part of the library list, then edit the target lib-table. Not for the faint-hearted, error-prone and very inconvenient.
Eagle supports formatted multi-line descriptions with hyperlinks since version 5 (!) for pretty much everything: Symbols, footprints, libraries, schematics, design rules… I make extensive use of this feature.
Maybe your MO is very different from that for most of us using KiCad.
When I design, I first find the IC or device that I want to use using Digikey or manufacturer’s website. Then I (usually make) or find the symbol and the footprint.
I am not using KiCad libraries as a source for component information.
You can add your own fields. Attached is a python program that prompts the user for the path name of a kicad_sym file, parses through it and creates a new field called Description2 that contains the same entry as the symbol name. I made this a few Kicad versions ago when I found the migrate symbol function had overwritten my edits to the primary description field and when I couldn’t get the BOM tool to include a ${Symbol} column. I made a new Description2 field in all of my schematic symbols that should be immutable to any future library migration changes.
Perhaps you can use my example to create a python script to add any field name you’d like to your symbols. . . Kicad_SymAI.py (2.6 KB)
My assumption: The feature you are used from eagle is not very well (to they the least) supported by kicad. Not by the entry of the auxiliary (documentation) data, and more important not by displaying this additional data as informational text in the GUI. As a result the existing user base has developed other workflows, and the documentation does not happen inside the symbols/footprints/libraries. And because there are other workflows the demand for eagle-like information stored in the footprint/symbol is not big.
I can feel your eagle–>kicad transition pain in that point as I (and my collegues) also used symbol/footprint internal documentation very extensively in eagle. It eases the usage very much, and it allows to document learned things directly inside the symbol/footprint, so it can’t be overlooked the next time you use that symbol/footprint.
As you have recognized in the current developer base / user base there seems no big interest to implement such a boring feature. That’s a bit sad (for me), but I have given up on this topic.
Another example for such lacking interest is my feature request for a small comments/description field in the DRC constraints: DRC constraints: add comments-section (#14248) · Issues · KiCad / KiCad Source Code / kicad · GitLab
Only supported by 2 upvotes in now nearly 3 years.
Regarding all the hints/advice from the other kicad users: yes, it works in principle. I can add any and as much additional fields to symbols/footprints in normal as well as in database libraries. But to be honest this is no match to the way eagle allows to enter auxiliary text and displays this additional information to the user. Kicad currently relies completely on the “data entered into a field” approach, and that doesn’t allow the flexibility of a free text/html-field. comparison picture below.
And now paragraph as reasoning why the entering of auxiliary information is useful:
writing short descriptive summary of a part into the symbol definition allows easier reuse of the symbols. Writing this as bullet list is much more easy to read than the long line of words in kicad
yes, a datasheet exists (normally) for every part. But who has not overlooked a important information, small written on page 34 of a 50 page datasheet? Or the values from the datasheet are too optimistic. Or… In the end the first prototype using this part must be reworked.
To prevent this for the next device you are designing: write a thick note into the symbol definition, so this note is visible in the add symbol dialog, and later on
completely relying on external data (datasheet, external documentation file): this must always explicitly opened. Not as convenient.
using fields: it’s hard to find descriptive field names. At first it seems obvious to use electrical parameters. But this means to have many different fields, depending on the type of the part: C (voltage, material, temperature), R(power), voltage regulator (U,I), OPV (U, frequency). This is good for searching (matching parameters), but not user friendly in a table presentation (too much columns) if you search for something based on visually looking on your libraries.
I’ve also felt strange why KiCad does not allow to save the library description to the library itself, and instead saves it to some “unreachable” place. Adding meta data support to libraries can be a good quality of life improvement in KiCad.
I think nobody complains about this because everyone is kind of used to this strangeness, including me. For me, the library name itself is a “good description”, if named properly.
Btw, not everyone wants to create database libraries just to have library descriptions.
my original posting is not about component information, but information about the footprint or symbol. Basic documentation needs to cover why did I what? What is special in this version of a footprint? Caveats? Reasons for intentional deviations from external docs? And so on. I’m aware that many people don’t care about documenting their work, I do.
I have never used Eagle so don’t feel about what kind of descriptions you write.
Will it be very far away from what you need if you just decide that Eco1 layer is for all such kind comments in footprint and Eco2 for such kind comments at PCB (since some time you can destine for it one of extra user layers).
If I do something special with one untypical symbol at schematic I write short info about it at schematic as if I will ever use the same untypical symbol I will start from copying old schematic part into new schematic.
works only for footprints (as symbols don’t have extra layers)
text is normally hided
the board must be visually scanned by the pcb designer
it sort of works, but as said it’s no match to the eagle approach
If I do something special with one untypical symbol at schematic I write short info about it at schematic as if I will ever use the same untypical symbol I will start from copying old schematic part into new schematic.
I do this also now with kicad. But this approach does not work well for groups with >= 2…3 designers, if more than one developer is using the symbols and pulls them in from the libraries (which is the case if not every developers knows every company design). This was the reason for inventing a “library concept” at all instead of always copying portions of already existing designs.
Edited it, and put a link to some random html page into the “datasheet” field.
Hovered over the resistor and pressed “d”.
KiCad then shoves the field content to your OS, which starts a browser with the URL.
I’m pretty sure that this would work for any mime type your operating system can handle.
Is that a usable method for you?
Maybe this could be further formalized, for example that other fields then the Datasheet link also support such links. (May I call such a link an URI I’m not sure whether a path name falls into that category.
I’m also a bit split about the usefulness of this (for library symbols). Documentation is good, but more documentation is not necessarily better. KiCad has defined links for datasheets and spice models by default, and adding more different types of documentation also breeds room for confusion. You can work with environment variables in datasheet links, but if you set something up locally, put your project on the internet and someone clones it, does it all still work then?
For my own projects, extra documentation usually starts as text box notes inside the schematic. When a project becomes more elaborate (Which is only a small part of my projects), then most of these text notes get transferred to a text file, spreadsheet, or whatever other form best suits that information.
My OP is mainly about documenting library content as I wrote in my posting before.
Examples:
PCB manufacturing instructions like special stencil thickness being the reason for changed solder paste dimensions.
Status (untested, reviewed by …, unfinished, known issues like “Warning, does not fit: The footprint was designed according to the data sheet, but the pins of the supplied parts have a different angle”)
More details about sources of information, e.g. “ST data sheet specifies huge 2x3mm² pad size (likely based on old IPC-SM-782A), NXP specifies 1.8x2.5mm² looking more reasonable.”
Reasons for this specific implementation, e.g. “pads made smaller larger than IEC-61188-6-1 on special request of …”
Component processing options (“For use in foobar DIN rail mount enclosures. Bend pins by 90° 7mm from the body and cut bent part to 3mm”)
Component usage instructions (e.g. zones needed to be added in the PCB, required mounting hardware)
Additional information “pad design optimized for 3kV isolation voltage”
Descriptions simply too long for a single line: “Universal DPDT toggle switch, vertical, 7.3mm M6 thread, fits C&K long product number, NKK series long product number, APEM series long product number, TE/Tyco Alcoswitch foobar series long product number. Notes: The foobar data sheet specifies wrong measures. The NKK data sheet doesn’t specify the -487 appendix but it is required for…”.
Legal information “this part is designed based on confidential information from $bigcustomer and must not be used in designs for other applications”
Descriptions are also good for schematics or PCBs, but not that important.
Smart Power Module (SPM®){return}{return}500V 3.0A 3-phase FRFET inverter including high voltage integrated circuit (HVIC){return}Source: http://www.fairchildsemi.com/ds/FS/FSB50450.pdf
I once had a proposal / idea for a “melee” library. The idea was to put the huge backlog of symbols and footprints that are committed on gitlab, but still need to be checked / verified into a separate library. The goal is twofold: First, making all those parts available to KiCad users is a significant increase in the size of KiCad’s libraries. It also encourages a lot of KiCad users to provide testing of these parts, and feedback.
But you have to be careful with such a Library (hence my Idea to make it a separate install). Such a library would also need extra info, and ideally coupled to the gitlab issues for all the symbols and footprints for providing feedback.
KiCad is also (planning for?) cascaded library tables. (I’m still on KiCad V8, don’t know if this made it into V9 or is planned for V10) In such a more complex library stack, it also becomes more useful to add more metadata to the libraries. Take for example the AKL (Alternative KiCad Library, installable through the P&C Manager). At the moment all parts in that library have “AKL” in their name, but apart from that they are just intermixed with KiCad’s default library (if both are installed) and this is not very ergonomic. Having more information about such libraries embedded in the libraries would be good here too.
@dsa-t : I wanted to try a multiline symbol description, and see how this is entered and later on displayed. So i can judge this new enhancement.
But I get stopped already during the text enter phase (used the symbol properties dialog–>description field): I always get “The field cannot contain line feed character(s)”. (tested with “Shift+ENTER” and with {return} ).
How should I enter a linefeed character?
But it would not be my own preference. I’ve made a "KICAD_DATASHEET_DIR environment variable that points to elsewhere where I collect my datasheets, and for some projects I create a datasheets directory in the project itself.
