<HEAD> <TITLE> gEDA Symbol Creation Guide </TITLE> </HEAD>
This document is ALPHA quality and is under construction.
Component Symbol guide
This file discusses the creation of component symbols, including style
conventions, and hints/tips and things to look out for when drawing symbols.
<LI> Component symbol creation </LI>
Component symbols (from here on known as "symbols") are drawn
using gschem just like drawing a schematic sheet. <p>
<LI> Draw the symbol (see the style guide below for some conventions) </LI>
<LI> Translate the symbol to the origin </LI>
<LI> Zoom in at least one step </LI>
<LI> Make sure the snap is ON (this is critical) </LI>
<LI> Make sure grid snap size is set to 100 (this is critical)</LI>
<LI> Select "Symbol Translate..." or the press equivalent hotkey </LI>
<LI> Enter 0 into the entry field and press OK </LI>
This step is required! All symbols must be translated to the
origin. To translate a symbol elsewhere, enter a offset (in mils)
which is a even multiple of 100. Make sure all pins are snapped to
a 100 mil grid point.
<LI> Save the symbol using Save or SaveAs... The name can be anything
but I've started the following conventions
<LI> Symbols are named: symbolname-#.sym </LI>
<LI> Symbols end with a .sym extension </LI>
<LI> Symbols have a -# where # is a number. Typically # is
1 but if there are multiple symbols for a device then
this number simply increments </LI>
<LI> Symbol names are typically lowercase but letters which
are part of a part number are uppercase </LI>
<LI> The above case rule can be broken if the filename
looks incorrect or wrong.</LI>
<LI> Place the symbol in one of the directories specified by the
component-library keyword in a gschemrc file. Once this is done,
the symbol should be visible immediately and can be selected and placed
with the "Add/Select Component..." menu item.</LI>
<LI> Style Guide for symbols </LI>
The styles described here are preliminary and can be changed so
if you have an opinion, let me know. Please look at the current
symbol libraries for examples. If you find something inconsistent,
please let me know.<p>
Here are the current symbol conventions: <p>
<LI> Text labels should all be 10 pt in size. </LI>
<LI> Pin numbers (which are attributes) should all be 8 pt in size.</LI>
<LI> Text (labels not attributes) should be green. </LI>
<LI> Lines, boxes, arcs, and any other graphics should be green. </LI>
<LI> Pins should all be 300 mils (3 grid spaces) long. </LI>
<LI> Pins should be white. </LI>
<LI> Leave 400 mils (4 grid spaces) between (vertically) pins, unless
you are drawing a special symbol, then just try to make it look
<LI> Pin number attributes should be 50 mils above (or below; which
ever makes the most sense) the pin which they are attached to.
<LI> Polarity bubbles should be cyan</LI>
<LI> Do not draw power and ground pins. That information will be
conveyed using attributes (see netattrib.txt)</LI>
<LI> Expanding on above, symbols are symbolic, they do not represent
the physical package that the device comes in. Input pins
belong on the left and output pins belong on the right of the
symbol. Please do not mix inputs and outputs on the same side
of the symbol, unless absolutely necessary. You can have
pins on the top or bottom of a symbol.</LI>
<LI> A gEDA user didn't like the above, so the following is okay too:
Arrange the pins on a symbol logically so that they promote
an uncluttered schematic. Note that this is frequently
not the same pin arrangement as the physical device.</LI>
<LI> Attached attributes should be yellow. The color is set
automatically to yellow if the text item is attached. </LI>
<LI> Attributes can be attached to some part of the symbol. Either
a pin (if it's a pin number) or some other part of the symbol
such as a line if it's just a device= attribute. Attributes
used to be required to be attached to something to be attributes,
but now they just have to exist in the symbol file as name=value
<LI> Expanding a bit on the last sentence, as long as the text item
has the format name=value, it is considered an attribute.
Attributes inside a symbol do not have to be attached to anything.
In order to see hidden attributes in gschem select
Edit/Show Hidden Text.
<LI> Required Attributes </LI>
<LI> <strong>device=device_name</strong> should be
placed somewhere in the symbol and made invisible.
device= is the device name and is required. If the
object is a graphic then device= should be set to
none (device=none). It is no longer required to
attach this attribute anything; just having it
exist as device=name is good enough.
<LI> <strong>graphical=1</strong> should exist
somewhere in a symbol which is purely graphical (such
as a title block or decon symbol). Symbols which
have this attribute have no electrical or circuit
significance. Don't forget to set device=none.
<LI> All pins should have a <strong>pin#=#</strong>
attribute attached to the pin object. The first # is
a placeholder and increments sequentially starting
at 1. The second # is the actual pin number.
Both #'s are required! The order of pin#'s is
significant since the netlister will output pins
in sequential order starting at pin1 going through
pinN. Example: pin1=1, pin2=2, pin3=5.
<LI> All pins should also have the <strong>label=value</strong>
attribute attached to them. Please make this attribute
green (instead of the default attribute yellow). Right
now, the symbol libraries do not follow this convention,
but they will.
<LI> If a component has multiple slots in a package (such as
a 7400 (NAND) which has 4 NANDs per package) then you
need a <strong>numslots=#</strong> attribute.
The # is the number of slots the device has.
numslots= should be exist somewhere in the symbol
and made invisible. Additional slot related required
attributes are below.
<LI> If a component has multiple slots in a package then you
also need to attach a <strong>slot#=#,#,#...</strong>
for every slot the component has. The first #
corresponds to the slot number. If a device has
4 slots then there would be a slot1=, slot2=,
slot3=, and a slot4= attribute existing somewhere
in the symbol and made invisible. The subsequent #
have a one-to-one correspondence to pin# attributes
and specify what the pin# should be when that slot
is set. Yes this isn't obvious and will be changing
in the near future. See 7400-1.sym as an example
of how this should all work.
<LI> It is recommended that all symbols which have slots
have a <strong>slot=1</strong> attribute attached
in the same fashion as the device= attributed.
The default pin#=#'s should reflect the first slot.
You cannot override the pin#=# with a non-slot=1
when placing components (at least not yet).
<LI> <strong> footprint=package_name </strong> should exist
somewhere in the symbol which might be used with
the netlister. Attach this attribute just like the
device= attribute. package_name is the pcb footprint
or package type like DIP14 or DIP40. This is very new
and so I'm not 100% sure this attribute will be call
this or what the values should be, so it's not required
yet. None of the current libraries use this.
<LI> The label= attribute should not be attached anywhere in
the symbol. It is used for net name labels only! This
statement contradicts the above pin label= attribute.
For now, ignore this statement. </LI>
<LI> The name= attribute should not be attached anywhere in
the symbol. It's currently unused.</LI>
<LI> You can put a uref= attribute inside a symbol. Make only
the value visible and it will be promoted (attached
to the outside of the symbol (so it can be edited)
when the symbol is placed in a schematic.
<LI> Please look at the netattrib.txt doc file for info on
how to assign power/ground information </LI>
<LI> Hints/tips </LI>
<LI> Avoid drawing things off of the grid. If you do, you cannot move
the object(s) using the move command (if the grid is on) since
the object will be snapped to the grid. [This was an old bug,
which I think has been fixed, but avoid doing this anyway].
Use the symbol translate command instead (or move the object
with grid snap off). </LI>
<LI> If you need a finer grid then use Options/Snap Grid Spacing...
to set a finer grid snap spacing. Just remember to set this
back to 100 once you are ready to translate the symbol to the
<LI> If you want to translate a symbol from the origin to elsewhere,
then use the "Symbol translate" command and enter a non zero
number. Make sure this number is a multiple of 100 (ie 1000,
or 1100). </LI>
<LI> Pins *MUST* be snapped on the 100 spaced grid (at least
the end which will have nets connected to it) </LI>
<LI> Pins *MUST* be snapped on the 100 spaced grid (at least
the end which will have nets connected to it) (Yes this is
line a duplicate. I can't stress this point enough </LI>
<LI> Remember that pins are special objects; if you want to add
a pin, make sure it is a pin and not a line or net. Use
the Add/Pin command to place a pin.
<LI> Don't include nets inside symbols. That isn't implemented and
doesn't make much sense anyway. </LI>