
[[libedit-symbols]]
== LibEdit - Symbols

=== Overview

A symbol consist of the following elements

* A graphical representation (geometrical shapes, texts).
* Pins.
* Fields or associated text used by the post processors: netlist,
  symbols list.

Two fields are to be initialized: reference and value. The name of the
design associated with the symbol, and the name of the associated
footprint, the other fields are the free fields, they can generally
remain empty, and could be filled during schematic capture.

However, managing the documentation associated with any symbol
facilitates the research, use and maintenance of libraries. The
associated documentation consists of

* A line of comment.
* A line of key words such as TTL CMOS NAND2, separated by spaces.
* An attached file name (for example an application note or a pdf file).
+
The default directory for attached files:
+
kicad/share/library/doc
+
If not found:
+
kicad/library/doc
+
Under linux:
+
/usr/local/kicad/share/library/doc
+
/usr/share/kicad/library/doc
+
/usr/local/share/kicad/library/doc

Key words allow you to selectively search for a symbol according to
various selection criteria. Comments and key words are displayed in
various menus, and particularly when you select a symbol from the
library.

The symbol also has an anchoring point. A rotation or a mirror is
made relative to this anchor point and during a placement this point
is used as a reference position. It is thus useful to position this
anchor accurately.

A symbol can have aliases, i.e. equivalent names. This allows you to
considerably reduce the number of symbols that need to be created
(for example, a 74LS00 can have aliases such as 74000, 74HC00,
74HCT00...).

Finally, the symbols are distributed in libraries (classified by
topics, or manufacturer) in order to facilitate their management.

[[position-a-symbol-anchor]]
=== Position a symbol anchor

The anchor is at the coordinates (0,0) and it is shown by the blue axes
displayed on your screen.

image::images/eeschema_libedit_anchor.png[alt="eeschema_libedit_anchor_png",scaledwidth="95%"]

The anchor can be repositioned by selecting the icon
image:images/icons/anchor.png[icons/anchor_png]
and clicking on the new desired anchor position. The drawing will be
automatically re-centered on the new anchor point.

[[symbol-aliases]]
=== Symbol aliases

An alias is another name corresponding to the same symbol in the
library. Symbols with similar pin-out and representation can then be
represented by only one symbol, having several aliases (e.g. 7400
with alias 74LS00, 74HC00, 74LS37 ).

The use of aliases allows you to build complete libraries quickly. In
addition these libraries, being much more compact, are easily loaded by
KiCad.

To modify the list of aliases, you have to select the main editing
window via the icon
image:images/icons/part_properties.png[icons/part_properties_png]
and select the alias folder.

image::images/eeschema_libedit_alias.png[alt="eeschema_libedit_alias_png",scaledwidth="70%"]

You can thus add or remove the desired alias. The current alias cannot
obviously be removed since it is edited.

To remove all aliases, you have firstly to select the root symbol.
The first symbol in the alias list in the window of selection of the
main toolbar.

[[symbol-fields-1]]
=== Symbol fields

The field editor is called via the icon
image:images/icons/text.png[icons/text.png].

There are four special fields (texts attached to the symbol), and
configurable user fields

image::images/eeschema_libedit_field_properties.png[alt="eeschema_libedit_field_properties_png",scaledwidth="70%"]

Special fields

* Reference.
* Value. It is the symbol name in the library and the default value
  field in schematic.
* Footprint. It is the footprint name used for the board. Not very
  useful when using CvPcb to setup the footprint list, but mandatory if
  CvPcb is not used.
* Sheet. It is a reserved field, not used at the time of writing.

[[symbol-documentation]]
=== Symbol documentation

To edit documentation information, it is necessary to call the main
editing window of the symbol via the icon
image:images/icons/part_properties.png[icons/part_properties_png]
and to select the document folder.

image::images/eeschema_libedit_description.png[alt="eeschema_libedit_description_png",scaledwidth="70%"]

Be sure to select the right alias, or the root symbol, because this
documentation is the only characteristic which differs between aliases.
The "Copy Doc" button allows you to copy the documentation information
from the root symbol towards the currently edited alias.

[[symbol-keywords]]
==== Symbol keywords

Keywords allow you to search in a selective way for a symbol
according to specific selection criteria (function, technological
family, etc.)

The Eeschema research tool is not case sensitive. The most current key
words used in the libraries are

* CMOS TTL for the logic families
* AND2 NOR3 XOR2 INV... for the gates (AND2 = 2 inputs AND gate, NOR3 = 3
  inputs NOR gate).
* JKFF DFF... for JK or D flip-flop.
* ADC, DAC, MUX...
* OpenCol for the gates with open collector output. Thus if in the
  schematic capture software, you search the symbol: by keywords
  NAND2 OpenCol Eeschema will display the list of symbols having these
  2 key words.

[[symbol-documentation-doc]]
==== Symbol documentation (Doc)

The line of comment (and keywords) is displayed in various menus,
particularly when you select a symbol in the displayed symbols
list of a library and in the ViewLib menu.

If this Doc. file exists, it is also accessible in the schematic capture
software, in the pop-up menu displayed by right-clicking on the
symbol.

[[associated-documentation-file-docfilename]]
==== Associated documentation file (DocFileName)

Indicates an attached file (documentation, application schematic)
available ( pdf file, schematic diagram, etc.).

[[footprint-filtering-for-cvpcb]]
==== Footprint filtering for CvPcb

You can enter a list of allowed footprints for the symbol. This list
acts as a filter used by CvPcb to display only the allowed footprints. A
void list does not filter anything.

image::images/eeschema_libedit_footprint.png[alt="eeschema_libedit_footprint_png",scaledwidth="70%"]

Wild-card characters are allowed.

S014* allows CvPcb to show all the footprints with a name starting by
SO14.

For a resistor, R? shows all the footprints with a 2 letters name
starting by R.

Here are samples: with and without filtering

With filtering

image::images/eeschema_cvpcb_with_filtering.png[alt="eeschema_cvpcb_with_filtering_png",scaledwidth="60%"]

Without filtering

image::images/eeschema_cvpcb_without_filtering.png[alt="eeschema_cvpcb_without_filtering_png",scaledwidth="60%"]


[[symbol-library]]
=== Symbol library

You can easily compile a graphic symbols library file containing
frequently used symbols. This can be used for the creation of symbols
(triangles, the shape of AND, OR, Exclusive OR gates, etc.) for saving
and subsequent re-use.

These files are stored by default in the library directory and have a
'.sym' extension. These symbols are not gathered in libraries like the
normal symbols because they are generally not so many.

[[export-or-create-a-symbol]]
==== Export or create a symbol

A symbol can be exported with the button
image:images/icons/export.png[icons/export_png].
You can generally create only one graphic, also it will be a good idea
to delete all pins, if they exist.

[[import-a-symbol]]
==== Import a symbol

Importing allows you to add graphics to a symbol you are editing. A
symbol is imported with the button
image:images/icons/import.png[Import graphic icon].
Imported graphics are added as they were created in existing graphics.

