kicad-lib-committers team mailing list archive
-
kicad-lib-committers team
-
Mailing list archive
-
Message #00008
Re: Library style and organization work RFC
Nice to see that some spark is still glowing. Let me get some tinder...
Tony, your input for the dicussion is again very well thought and full
of insight, not to mention the habit of professionally documenting it
all. Felix, welcome on board and I agree 100%. Bernd, thanks for your
library work and enthusiasm to make it even better. 73 de oh2jcp ;)
To me the main annoyance was drawing style inconsistencies in the
symbols, but the following includes some other points that need fixing
for the future.
25.09.2012 19:34, Phinitnan Chanasabaeng kirjoitti:
Hello,
In my opinion, we should discuss and agree on a set of rule and style
before start working. It should be well documented with clear version
number just like in .lib and .mod specification. This will help users
whether they should upgrade their library or not in case of major changes
in the specification. I would like to propose my idea how the new library
would be restructured and recreated here and will summarize it in detail as
a blueprint (and a odt document) after the discussion.
0. Definitions
0.1 Directory structure - the directory consists of symbol, footprint,
model, document and probably readme, changelog, etc files.
library ------
|---- symbol ---> symbol libraries
|---- footprint ---> footprint libraries
|---- model ---> 3d models
|----source
|---- document ---> datasheet, application note,
pictures, etc.
I think we would need a fifth definition for a component/part.
Symbol => Schematic representation. This is the logic for the net list
and an abstract interface for a human.
Footprint => 2D PCB object with a bounding box, outline, solder and
mechanical board level details.
Model => 3D representation of a real physical object.
Documentation => datasheet, SPICE model, version, production status, etc.
Component/Part => The rule how Symbol-Footprint-Model-Documentation are
related. A representation of a real component/part, like 2N222 or
2N3055. Gate swap and pin swap model contained here.
Why so complex? To get flexibility and to get around copying. Also this
is the only way to get the whole verified for correctness. It needs more
effort in the design phase, but less effort in the maintenance and use
phase. (Some larger software projects might be good examples) Current
data structures in KiCad don't allow this, but we should start building
the data for the future and then "downsample" for the current use. Say
collecting the data in odf spreadsheet and scripting it into the current
library format for release. Any python gurus? A spreadsheet interface
could also mobilise some less technically inclined for the cause. We
just would have to make a fill up form for it. Or maybe a dynamic web
form at kicad-pcb.org/library...
Let me give a few examples:
NPN bipolar transistor.
Symbol: Looks like a NPN BJT. Contains pin functions E, B, C. Special
versions for the ones with housing connected to E, B, C or special
terminal. Their use is optional. That would mean five symbols for all
NPN BJTs. Pin numbers are _not_in_ the symbol, they are rendered when a
component/part is defined and the pin functionality-number mapping gets
known.
Footprint: Any of the available with enough pads.
Model: May be tied to the footprint, but one footprint may have more
than one model as the height is not in the footprint. Models with
vertical heatsink as an example.
1)
Component/part: PN2222 tells that pin E=1, B=2, C=3, footprint and model
are TO-92 and links to the documentation. No gate or pin swap available.
2)
Component/part: Change PN2222 to 2SC945. No need to change the symbol,
just update the BOM and the net list automatically changes to E=1, B=3,
C=2. Autorouter does the pin swap between pins 2 and 3.
3)
For some odd reason one wants to use a plugin NPN-BJT in a DIP-8
IC-socket... the collector and emitter currents are so high that one has
to use at least 2 pins for them, but for mechanical reasons pins 1-4 are
connected to emitter and 5-7 to collector with 8 to the base. Routing
DRC is happy as long as two of the pins of each bank are routed and
autorouter is free to pick any of the available for a best fit. Pin swap
is available.
4)
Nice three winding coupled inductor for your latest PFC converter.
Calculations and point to point test setup measurements tell that ETD49
is good enough for 2kW. Slap a standard 20 pin ETD49 bobbin on the PCB
and your three winding transformer symbol piled up from inductors in the
schematic is just fine. Pin mapping is just the one liner in your
component/part definition file with the documentation showing the
winding details.
0.2 Grid unit (GU) - 25 mil
1. Symbol library and symbol naming scheme
1.1 Library naming - as the symbols are put in library files, this is
the way symbols are categorized.Therefore, I think, the way libraries are
named should reflect its category as much as possible. Here is the scheme I
proposed:
{main-category}-{manufacturer, standard}-{other fields separated by
"-"}.lib
the main category and manufacturer fields are required. The other
fields can be added to describe the lib. For example, "device-en60617.lib",
"connector-molex.lib", "microcontroller-microchip.lib", etc. "generic"
should be used in {manufacturer} field for any standard components. The
file name should be in lower case.
1.2 For symbol naming, I proposed:
{name}-{other fields separated by "-"}-{footprint}-{pin quantity}
Only {name} is required here. For examples, "MCP73832-SOT-5,
2N2222-A-TO92", etc. For fundamental devices, there should be a set of name
to be derived from such as "RESISTOR, CAPACITOR", etc. All other libraries
of fundamental devices should use this name set. I'm not sure whether lower
or upper case is suitable.
Agreed, but do we need that much data in the name? Eagle style "heavy
symbol" system is quite ugly when it grows a to a bit more than two
capacitor manufacturers. Even capacitor cases are standardised. For
microcontrollers and special function stuff with only one source it
makes sense and is the only way.
2. Line style - the style proposed by Vesa can be used. But the DU unit and
other line weight should be specified. This line style will be used in both
symbol and footprint drawing. The line weight should be chosen based on
physical print quality (especially, on PCB silkscreen layer).
I'd say footprint side is a lot less critical than schematics as there
is not much data on the same layer. That makes separating objects by
line widths unneeded. Just rendering time option depending on the process.
3. Symbol drawing style
3.1 Block model - all symbols will be drawn as blocks
3.1.1 Fundamental symbols - devices such as resistor, capacitor,
logic, etc, will be separated into 2 types
3.1.1.1 Symbol - this block is 16x16GU. It is used in schematic
as a normal symbol. Drawing and all interface pins should fit inside this
block.
3.1.1.2 Building block - this block is 8x8GU. There is no
assigned pin as it is used to build the other block symbols.
3.1.2 Block Symbol is a blank block or block built from building
block with assigned pins. A specific width and height ratio should be used
(except the square block). I propose the golden ratio (1.618). The closest
even number from multiplication/division of width/height will be used.
3.1.3 Orientation - For fundamental symbols, should they be placed
horizontally? For block symbol, see pin position and orientation.
Agreed. Some very interesting ideas, like the golden ratio. Are you
going to make some example drawings? Eventually the drawing style will
end up being somewhat after the standard and the rest by the test and
vote. I haven't seen good looking schematics from any CAD that would
have conformed strictly to the standard. Strictly standard compliance
library would almost have to be a separate one to be pleasant :D
3.2 Name and designator
3.2.1 Designator - what standard should be used? or should it be
redefined (based on available standards) especially for kicad?
3.2.2 Position - Designator will be placed at the middle-top and
name at the middle-bottom of the symbol. At least 1GU space to any nearby
line or pin should be added.
I've been using top-right for the designator and left-bottom for the
name. Those are usually the empty areas and are easy to find by the
glance as one finds them by following either vertical or horizontal
line. Corner is like an arrowhead that catches ones attention and there
it is, the needed data.
3.3 Pin
3.3.1 length for block symbols - 12GU (300 mil, current pin length
used by kicad)
3.3.2 Pin to pin space - 4GU (100 mil)
3.3.3 Pin to corner space - 4GU (100 mil)
3.3.4 Position and orientation
3.3.4.1 Positioned by its function - group the same function
together
3.3.4.1.1 Input pin - start from top-left of the block,
counter-clockwise
3.3.4.1.2 Output and Bidirectional pin - start with output
pin from top-right, clockwise
3.3.4.1.3 Power input - Distributed at the center of top
3.3.4.1.4 Power output - Distributed at the center of bottom
3.3.4.2 Positioned by its footprint - the 1st pin is placed at
top-left of the block
3.3.5 Pin naming and numbering
3.3.5.1 Left,top = 1, right,bottom = 2
3.3.5.2 Anode = 1, Cathode = 2
3.3.5.3 Control = 1, input = 2, output = 3
3.3.5.4 GND = 1, input = 2, output = 3
3.3.5.5 BCE = 123
3.3.5.6 GDS = 123
3.3.5.6 Pin name should be exactly the same as noted in the
datasheet
For pin legths we need to take tha total count of numbers in account.
Otherwise four number pins will overflow and the one number ones would
look empty. For some special purpose IC's the in-out-power pin
directions would have to be relaxed. The purpose of the schematic is to
be clear and readable and in the special purpose IC's the surroundings
are so tightly defined that pin locations have to be picked according to
the surroundings. PFC IC's are a good example. For logic the opposite is
true and that's what you wrote.
The numbering is something we can't always pick as it depends on the
physical world. Schematic doesn't care about it anyway. Schematic is
just for the human. What ends up in to the netlist is something I don't
care as long as the machine reads it ;)
3.4 Symbol property
3.4.1 For symbol with multiple units, the power unit should be
created explicitly.
3.4.2 Symbol description - The value should be put in all fields,
especially keyword. See below
3.4.2.1 Keyword - this field should be changed to "Tag" and
will be used for the search tool. It is probably used for footprint lookup.
3.4.2.2 DocFileName - should refer to a file in the document
directory or a download link
3.4.3 Alias is obsolete, do not use it.
3.4.4 Footprint filter - I'm sure how this works but if possible
the words put here will be used to search in the module keyword.
3.5 Symbol field property
3.5.1 Symbol with {footprint} in its name should be mapped to the
exact footprint in the footprint library.
3.5.2 Datasheet should referred to a file in the document directory
or a link to download website. (DocFileName
I'd say no to copying of any data. If the value is in the value field,
that's it. It's the UI's job to present the data as conveniently as
possible.
4. Footprint creation
4.1 Naming scheme
4.1.1 Consider the IPC7351B, I once implemented it in my local
library. It was good for machine, but not for human, It was very difficult
to understand. I had to look through the footprint list to find the one I
wanted. However, it is still possible to implement using footprint filter
and/or keywords. To be discussed.
4.1.2 For file naming scheme, see the symbol scheme above. JEDEC
name can be use as the {main-category}.
Øyvind Aabling did quite a good job here. His system is very human
readable and I'd like to follow that. IPC7351B is a "design by
committee" so it must be equally annoying to everybody that nobody can
be jealous of somebody's enjoyment. It can be included as a tag to
become an option.
4.2 Pin number identification - for a footprint without pin number, put
the component faced-up on the floor, the most pin count side on the left.
The top-left is the 1st pin and count around the component
counter-clockwise.
Exactly.
4.3 Footprint orientation depends on the first pin of the footprint.
The first pin should be at top-left position. The footprint should be
aligned horizontally first. If the 1st pin is not at top-left, align it
vertically.
4.4 Silkscreen drawing - to be discussed
5. Model
5.1 Model name should be the same as footprint name.
5.2 Each available footprint should have a model assigned to it.
Agreed. Documentation part should include draft-checked-production
status and the same for 3D model.
6. Library organisation - I have been thinking about this for quite a
while, how the new library should be organized. Open as kicadlib.org or
well organized and verified by set of maintainers. To me, the only problem
of kicad is it library consistency. I wouldn't use kicad for a large or
commercial project even the main components are ready. I would proposed
that kicad-lib-maintainer should be responsible for organizing and
verifying all submit libraries to maintain its quality.
I'm sure kicadlib.org won't go anywhere or at least the one with a
similar idea will pop up the moment it does... A few of grumpy lib
maintainers would probably do fine with the verifying and organising
work. Those maintainers would just have to clearly state that we don't
accept anything, but stuff that conforms to the following
guidelines/standard/whatever. Just for the fun of it I'd gladly accept
an "old radio style" symbol set for those few components that were
available 50 years ago. Only if it's good enough of course ;D
-Vesa
Follow ups
References
