4.1.1 Overview
This document describes the creation of component symbols, including
style conventions, and hints/tips and things to look out for when
drawing symbols for the gEDA/gaf system.
4.1.2 Component Symbol Creation
Component symbols (from here on known as symbols) are drawn
using lepton-schematic
. You can start with a blank page or a known-to-be
good symbol that is similar to the one you want to create.
4.1.2.1 Preparing
Before you open lepton-schematic
to create your symbol, there are a few
questions you should ask yourself, that will effect how you create
your symbol:
- Is this symbol purely for aesthetic purposes (a graphic)? If so,
several steps are simplified.
- Do I want to simulate the component in question, with e.g. SPICE?
- Do I want to use this symbol in a schematic that includes power
distribution? This will become important when deciding what pins to
draw.
- Does this symbol represent a component that comes several in a
package? This is called slotting in gEDA’s language, and has
special rules.
Once you’ve answered those questions, the following guide will be more
useful to you.
To start building your symbol:
- Open
lepton-schematic
.
- The default empty page has boxes on it. Use the selection tool (the
one that looks like a black mouse cursor) to select everything on the
page. Hit the Delete key to delete it.
- Zoom in at least one step (View → Zoom, or hit
the Z key).
- Make sure the snap-to-grid functionality is ON (Options
→ Toggle Snap On/Off, or O S).
- Make sure grid snap size is set to 100 (Options
→ Snap Grid Spacing..., or O Shift-S).
4.1.2.2 Drawing your Symbol
Use the ‘line’, ‘box’, ‘circle’, and ‘arc’ tools
(in the ‘Add’ menu) to create a simplified visual representation
of your device. Make sure that the only color you use is
graphic
(green). Do not place any pins on the device until the
next step.
To check what color you are using to draw, go to Edit
→ Color... (or hit E O).
4.1.2.3 Placing Pins on your Symbol
If you have decided your symbol is graphical in nature (e.g., does not
connect to anything, is just artwork), you can skip this step.
Add your first pin.
- Select Add → Pin, or hit A P. Once that
is done, click from the end of your pin, to one of the edges of your
symbol. A ’0’ and the word ’unknown’ should pop up near your new pin.
Please note that the direction you draw your pins is important. If
you draw them starting from the edge of your symbol to outside of your
symbol, you will end up with text outside of the symbol!
- Click on the selection tool, and use it to select the pin you just
drew. The pin and text with it should change colors, and boxes should
be drawn around the ends of the pin.
- Select Edit → Edit..., or hit E E (or
right click, and hit ‘Edit...’). This will bring up the edit
dialog for this pin.
In the Edit dialog for a pin, you should see four attributes
(name=value pairs) already associated with your new pin. These
attributes can be edited by clicking on the attribute in the list at
the top of the edit window, then clicking on the field you want to
edit. Note that when selected, the ‘Add Attribute’ section of
this dialog does not reflect what has been selected, as it is only
meant for addition, not for editing.
Let’s look at each attribute already associated with your pin, and
edit some of the values. I recommend expanding the size of the edit
window until all attributes are visible.
- All pins should have a pinseq attribute. This number dictates
the order pins are looked at on this symbol in SPICE,
lepton-netlist
, and
other tools. For our first pin, start this sequence number at
1
, incrementing it on each new pin, as we add them.
- All pins should have a pinnumber attribute. This is the number
of the pin, on the package of the item you are drawing a symbol for.
pinnumber values can be alphanumeric (i.e. like
E
or
C
).
- All pins should have a pinlabel attribute. This attribute is
the name or label of the pin (not the pin number).
- All pins should have a pintype attribute. This attribute
describes the kind of a pin.
- pinseq and pinnumber attributes of several pins can be
automatically numbered by Attributes →
Autonumber Text....
Possible pintype values are: in, out, io,
oc, oe, pas, tp, tri, clk,
pwr. See pintype attribute for more info.
4.1.2.4 Adding attributes to your symbol
Every symbol needs some attributes (name=value pairs) in order
to be useful in lepton-schematic
, and in other tools.
First we’re going to add all of the attributes we want, then make the
ones that need to be invisible invisible.
- A device=DEVICENAME attribute should be placed somewhere in the
symbol. The devicename should consist of nothing but capital
letters, dashes, numbers, and underscores. If the object is a graphic
then device= should be set to none (device=none).
- A graphical=1 attribute 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 per the
previous step.
- A description=TEXT attribute should exist somewhere in the
symbol. The TEXT value should provide a one line description
of the symbol.
- A footprint=PACKAGENAME attribute should exist somewhere in the
symbol which might be used with a pcb netlister. PACKAGENAME
is a pcb footprint or package type like
DIP14
or DIP40
.
Please see the footprint naming conventions page for further detail. If you are
using gEDA / PCB, also see the
PCB documentation and
gnetlist/docs/README.pcb for more info on this attribute and how it is
used.
- A refdes= attribute should be placed inside all non-graphical
symbols. This attribute should default to U? for integrated
circuits, and T? for transistors. 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.
- A numslots= attribute should be placed inside of all symbols,
to prevent a warning when you will check your symbol by gsymcheck.
numslots=1 works fine.
Now that those have been added, make the numslots,
footprint, description, graphical and
device attributes invisible. Leave only the value of the
refdes attribute visible, and place it somewhere at the top of
your symbol.
4.1.2.5 Finishing
- Add a label to your symbol by selecting Add →
Text... or pressing A T. Type out your label, and move it to
the top of your symbol.
- Translate the symbol to the origin using Edit →
Symbol Translate... or press E T.
- Enter
0
into the entry field and press ‘OK’.
- Save the symbol using File → Save or
File → Save As...
- Place the symbol in one of the directories specified as a symbol
library in a suite configuration file (one of the gafrc files).
For an explanation of how to set up symbol libraries, see the
Legacy configuration files still in use. Once this is done, the symbol should be
visible immediately and can be selected and placed with the
Add → Select Component... menu item. On
Debian, placing files in /usr/share/gEDA/sym/local/ works, but
requires permissions setup.
Note: Translating the symbol to the origin is a required step. 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.
4.1.4 Symbol Requirements
This section describes the various requirements which must be met in
order to create a valid symbol which will display and netlist in the
gEDA/gaf system.
4.1.4.1 Pins
- All pins should have a pinseq attribute. This number dictates
the order pins are looked at on this symbol in spice,
lepton-netlist
, and
other tools. This is just a sequence number, and should increment
sequentially starting at 1.
- All pins should have a pinnumber attribute attached to them.
This is the number of the pin, on the package of the item you are
drawing a symbol for. The pin number can be alphanumeric (i.e. like
E
or C
).
- All pins should have a pinlabel attribute attached to them.
This attribute is the name or label of the pin (not the pin number).
This attribute is also used when a symbol is used in a hierarchical
schematic.
- All pins should have pintype attribute attached to them. This
attribute describes the kind of a pin. Possible values are:
in, out, io, oc, oe, pas,
tp, tri, clk, pwr. See pintype attribute for more info.
4.1.4.2 Add attributes
For more information on the attributes presented here, please see the
Master attribute list.
- A device=DEVICENAME attribute should be placed somewhere in the
symbol and made invisible. Typically the devicename is in all
caps (capital letters). This attribute should not be used as a label.
Use a separate text object for the label. If the object is a graphic
then device= should be set to none (device=none).
- A graphical=1 attribute 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 per the
previous requirement.
- A description=TEXT attribute should exist somewhere in the
symbol. The TEXT value should provide a one line description
of the symbol.
- A footprint=PACKAGENAME attribute should exist somewhere in the
symbol which might be used with a pcb netlister. PACKAGENAME
is a pcb footprint or package type like DIP14 or DIP40. Please see
the footprint naming
conventions page for further detail. If you are using gEDA / PCB,
also see the PCB
documentation and gnetlist/docs/README.pcb for more info on this
attribute and how it is used.
- A refdes=U? attribute should be placed inside all non-graphical
symbols. 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.
- The label= and name= attributes should not exist
anywhere in the symbol. They are obsolete.
- The netname= attribute should not be attached anywhere in the
symbol. It is only used in schematics.
4.1.4.3 Slotting
- If a component has multiple slots in a package (such as a 7400 (NAND)
which has 4 NANDs per package) then you need a numslots=#
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 described
below.
- If a component has multiple slots in a physical package then you also
need to include a slotdef=#:#,#,#... for every slot. The first
# corresponds to the slot number. If a device has 4 slots then
there should be slotdef=1:..., slotdef=2:...,
slotdef=3:..., and slotdef=4:..., attributes existing
somewhere in the symbol and made invisible. The subsequent #
have a one-to-one correspondence to pinseq=# attributes and
specify what corresponding pinnumber=# should be when that slot
is set. See the attached 7400-1.sym as an
example of how this should all work.
- It is recommended that all symbols which have slots have a
slot=1 attribute inside the symbol.