:experimental:

[[symbol-editor]]
== Symbol Editor

[[general-information-about-symbol-libraries]]
=== General Information About Symbol Libraries

A symbol is a schematic element which contains a graphical representation,
electrical connections, and text fields describing the symbol. Symbols used in a
schematic are stored in symbol libraries. KiCad provides a symbol editing tool
that allows you to create libraries, add, delete or transfer symbols between
libraries, export symbols to files, and import symbols from files. The symbol
editing tool provides a simple way to manage symbols and symbol libraries.

[[symbol-library-overview]]
=== Symbol Library Overview

A symbol library is composed of one or more symbols. Generally the
symbols are logically grouped by function, type, and/or manufacturer.

A symbol is composed of:

* Graphical items (lines, circles, arcs, text, etc.) that determine how
  symbol looks in a schematic.
* Pins which have both graphic properties (line, clock, inverted, low
  level active, etc.) and electrical properties (input, output,
  bidirectional, etc.) used by the Electrical Rules Check (ERC) tool.
* Fields such as references, values, corresponding footprint names for
  PCB design, etc.

Symbols can be derived from another symbol in the same library. Derived symbols
share the base symbol's graphical shape and pin definitions, but can override
the base symbol's property fields (value, footprint, footprint filters,
datasheet, description, etc.). Derived symbols can be used to define symbols
that are similar to a base part. For example, 74LS00, 74HC00, and 7437 symbols
could all be derived from a 7400 symbol. In previous versions of KiCad, derived
symbols were referred to as aliases.

Proper symbol designing requires:

* Defining if the symbol is made up of one or more units.
* Defining if the symbol has an alternate body style (also known as a
  De Morgan representation).
* Designing its symbolic representation using lines, rectangles,
  circles, polygons and text.
* Adding pins by carefully defining each pin's graphical elements,
  name, number, and electrical property (input, output, tri-state, power
  port, etc.).
* Determining if the symbol should be derived from another symbol with
  the same graphical design and pin definition.
* Adding optional fields such as the name of the footprint used by the PCB
  design software and/or defining their visibility.
* Documenting the symbol by adding a description string and links to
  data sheets, etc.
* Saving it in the desired library.

[[symbol-library-editor-overview]]
=== Symbol Library Editor Overview

The symbol library editor main window is shown below. It consists
of three tool bars for quick access to common features and a symbol
viewing/editing area. Not all commands are available on the tool bars
but can be accessed using the menus.

image::images/libedit_main_window.png[alt="Symbol Editor main window",scaledwidth="95%"]

[[main-toolbar]]
==== Main Toolbar

The main tool bar is located at the top of the main window. It
consists of the undo/redo commands, zoom commands, symbol properties dialogs,
and unit/representation management controls.

image::images/toolbar_libedit.png[alt="Symbol Editor toolbar",scaledwidth="95%"]

[width="100%",cols="20%,80%",]
|=======================================================================
|image:images/icons/new_component_24.png[New symbol icon]
|Create a new symbol in the selected library.

|image:images/icons/save_24.png[Save icon]
|Save the currently selected library. All modified symbols in the library will
be saved.

|image:images/icons/undo_24.png[Undo icon]
|Undo last edit.

|image:images/icons/redo_24.png[Redo icon]
|Redo last undo.

|image:images/icons/refresh_24.png[Refresh icon]|Refresh display.

|image:images/icons/zoom_in_24.png[Zoom in icon]|Zoom in.

|image:images/icons/zoom_out_24.png[Zoom out icon]|Zoom out.

|image:images/icons/zoom_fit_in_page_24.png[Zoom to fit page icon]|Zoom to fit symbol in display.

|image:images/icons/zoom_area_24.png[Zoom to selection icon]|Zoom to fit selection.

|image:images/icons/rotate_ccw_24.png[Rotate counterclockwise icon]|Rotate counter-clockwise.

|image:images/icons/rotate_cw_24.png[Rotate clockwise icon]|Rotate clockwise.

|image:images/icons/mirror_h_24.png[Mirror horizontally icon]|Mirror horizontally.

|image:images/icons/mirror_v_24.png[Mirror vertically icon]|Mirror vertically.

|image:images/icons/part_properties_24.png[Symbol properties icon]
|Edit the current symbol properties.

|image:images/icons/pin_table_24.png[Pin table icon]
|Edit the symbol's pins in a tablular interface.

|image:images/icons/datasheet_24.png[Datasheet icon]
|Open the symbol's datasheet. The button will be disabled if no datasheet is
defined for the current symbol.

|image:images/icons/erc_24.png[ERC icon]
|Test the current symbol for design errors.

|image:images/icons/morgan1_24.png[Normal body style icon]
|Select the normal body style. The button is disabled if the current
symbol does not have an alternate body style.

|image:images/icons/morgan2_24.png[Alternate body style icon]
|Select the alternate body style. The button is disabled if the current
symbol does not have an alternate body style.

|image:images/toolbar_libedit_part.png[alt="Unit dropdown",width="80%"]
|Select the unit to display. The drop down control will be disabled if
the current symbol is not derived from a symbol with multiple units.

|image:images/icons/pin2pin_24.png[Synchronized pin edit mode icon]
|Enable synchronized pins edit mode. When this mode is enabled, any pin
modifications are propagated to all other symbol units. Pin number changes are
not propagated. This mode is automatically enabled for symbols with multiple
interchangeable units and cannot be enabled for symbols with only one unit.

|image:images/icons/add_symbol_to_schematic_24.png[Add symbol to schematic icon]
Insert current symbol into schematic.

|=======================================================================

[[element-toolbar]]
==== Element Toolbar

The vertical toolbar located on the right hand side of the main window allows
you to place all of the elements required to design a symbol.

[width="100%",cols="10%,90%",]
|=======================================================================
|image:images/icons/cursor_24.png[Cursor icon]
|Select tool. Right-clicking with the select tool opens the context menu
for the object under the cursor. Left-clicking with the select tool
displays the attributes of the object under the cursor in the message
panel at the bottom of the main window. Double-left-clicking with the
select tool will open the properties dialog for the object under the
cursor.

|image:images/icons/pin_24.png[Pin icon]
|Pin tool. Left-click to add a new pin.

|image:images/icons/text_24.png[Text icon]
|Graphical text tool. Left-click to add a new graphical text item.

|image:images/icons/add_rectangle_24.png[Add rectangle icon]
|Rectangle tool. Left-click to begin drawing the first corner of a
graphical rectangle. Left-click again to place the opposite corner of
the rectangle.

|image:images/icons/add_circle_24.png[Add circle icon]
|Circle tool. Left-click to begin drawing a new graphical circle from
the center. Left-click again to define the radius of the circle.

|image:images/icons/add_arc_24.png[Add arc icon]
|Arc tool. Left-click to begin drawing a new graphical arc item from the
first arc end point. Left-click again to define the second arc end point.
Adjust the radius by dragging the arc center point.

|image:images/icons/add_line_24.png[Add line icon]
|Connected line tool. Left-click to begin drawing a new graphical line item
in the current symbol. Left-click for each additional connected line.
Double-left-click to complete the line.

|image:images/icons/anchor_24.png[Anchor icon]
|Anchor tool. Left-click to set the anchor position of the symbol.

|image:images/icons/delete_cursor_24.png[Delete icon]
|Delete tool. Left-click to delete an object from the current symbol.
|=======================================================================

[[options-toolbar]]
==== Options Toolbar

The vertical tool bar located on the left hand side of the main window allows
you to set some of the editor drawing options.

[width="100%",cols="10%,90%",]
|=======================================================================
|image:images/icons/grid_24.png[Grid icon]
|Toggle grid visibility on and off.

|image:images/icons/unit_inch_24.png[Inch unit icon]
|Set units to inches.

|image:images/icons/unit_mil_24.png[Millimeter unit icon]
|Set units to mils (0.001 inch).

|image:images/icons/unit_mm_24.png[Millimeter unit icon]
|Set units to millimeters.

|image:images/icons/cursor_shape_24.png[Cursor shape icon]
|Toggle full screen cursor on and off.

|image:images/icons/pin_show_etype_24.png[Show pintype icon]
|Toggle display of pin electrical types.

|image:images/icons/search_tree_24.png[Symbol tree icon]
|Toggle display of libraries and symbols.
|=======================================================================

[[library-selection-and-maintenance]]
=== Library Selection and Maintenance

The selection of the current library is possible via the
image:images/icons/search_tree_24.png[Symbol tree icon] icon
which shows you all available libraries and allows you to select one.
When a symbol is loaded or saved, it will be put in this library. The
library name of a symbol is the contents of its `Value` field.

[[select-and-save-a-symbol]]
==== Select and Save a Symbol

[[symbol-selection]]
===== Symbol Selection

Clicking the image:images/icons/search_tree_24.png[Symbol tree icon] icon
on the left tool bar toggles the treeview of libraries and symbols. Clicking on
a symbol opens that symbol.

[NOTE]
Some symbols are derived from other symbols. Derived symbol names are displayed
in __italics__ in the treeview. If a derived symbol is opened, its symbol
graphics will not be editable. Its symbol fields will be editable as normal. To
edit the graphics of a base symbol and all of its derived symbols, open the
base symbol.

[[save-a-symbol]]
===== Save a Symbol

After modification, a symbol can be saved in the current library or a different
library.

To save the modified symbol in the current library, click the
image:images/icons/save_24.png[Save icon] icon. The modifications will be
written to the existing symbol.

NOTE: Saving a modified symbol also saves all other modified symbols in the same
library.

To save the symbol changes to a new symbol, click **File** -> **Save As...**.
The symbol can be saved in the current library or a different library. A new
name can be set for the symbol.

To create a new file containing only the current symbol, click **File** ->
**Export** -> **Symbol...**. This file will be a standard library file which
will contain only one symbol.

[[creating-library-symbols]]
=== Creating Library Symbols

[[create-a-new-symbol]]
==== Create a New Symbol

A new symbol can be created by clicking the
image:images/icons/new_component_24.png[New symbol icon] icon.
You will be asked for a number of symbol properties.

* A symbol name (this name is used as the default value for the `Value` field in the schematic editor)
* An optional base symbol to derive the new symbol from. The new symbol will use
  the base symbol's graphical shape and pin configuration, but other symbol
  information can be modified in the derived symbol. The base symbol must be in
  the same library as the new derived symbol.
* The reference designator prefix (`U`, `C`, `R`...).
* The number of units per package, and whether those units are interchangeable
  (for example a 7400 is made of 4 units per package).
* If an alternate body style (sometimes referred to as a "De Morgan equivalent")
  is desired.
* Whether the symbol is a power symbol. Power symbols appear in the "Add Power Port"
  dialog in the Schematic editor, their `Value` fields are not editable in the
  schematic, they cannot be assigned a footprint and they are not added to the PCB,
  and they are not included in the bill of materials.
* Whether the symbol should be excluded from the bill of materials.
* Whether the symbol should be excluded from the PCB.
  
There are also several graphical options.

* The offset between the end of each pin and its pin name.
* Whether the pin number and pin name should be displayed.
* Whether the pin names should be displayed alongside the pins or at the ends of the
  pins inside the symbol body.

These properties can also be changed later in the <<symbol-properties, Symbol Properties window>>.

image::images/eeschema_new_symbol_properties.png[alt="New symbol properties",scaledwidth="50%"]

A new symbol will be created using the properties above and will
appear in the editor as shown below.

image::images/eeschema_libedit_new.png[alt="Newly created symbol",scaledwidth="95%"]

The blue cross in the center is the symbol anchor, which specifies the symbol
origin i.e. the coordinates (0, 0). The anchor can be repositioned by selecting
the image:images/icons/anchor_24.png[Anchor icon] icon and clicking on the new
desired anchor position.

[[create-a-symbol-from-another-symbol]]
==== Create a Symbol from Another Symbol

Often, the symbol that you want to make is similar to one already in
a symbol library. In this case it is easy to load and modify an
existing symbol.

* Load the symbol which will be used as a starting point.
* Save a new copy of the symbol using **File** -> **Save As...**. The Save As dialog
  will prompt for a name for the new symbol and the library to save it in.
* Edit the new symbol as required.
* Save the modified symbol.

[[symbol-properties]]
==== Symbol Properties

Symbol properties are set when the symbol is created but they can be modified
at any point. To change the symbol properties, click on the
image:images/icons/part_properties_24.png[Symbol properties icon] icon
to show the dialog below.

image::images/eeschema_properties_for_symbol.png[alt="Symbol Properties",scaledwidth="60%"]

It is important to correctly set the number of units per package and
the alternate symbolic representation, if enabled, because when pins are
edited or created the corresponding pins for each unit will be affected.
If you change the number of units per package after pin creation and editing,
there will be additional work to specify the pins and graphics for the new unit.
Nevertheless, it is possible to modify these properties at any time.

The graphic options "Show pin number" and "Show pin name" define the
visibility of the pin number and pin name text. The option "Place pin
names inside" defines the pin name position relative to the pin body.
The pin names will be displayed inside the symbol outline if the option
is checked. In this case the "Pin Name Position Offset" property defines
the shift of the text away from the body end of the pin. A value from
0.02 to 0.05 inches is usually reasonable.

The example below shows a symbol with the "Place pin name inside"
option unchecked. Notice the position of the names and pin numbers.

image::images/eeschema_uncheck_pin_name_inside.png[alt="Place pin name inside unchecked",scaledwidth="95%"]

[[symbol-name-description-and-keywords]]
===== Symbol Name, Description, and Keywords

The symbol's name is the same as the `Value` field. When the symbol name is
changed the value also changes, and vice versa. The symbol's name in the library
also changes accordingly.

The symbol description should contain a brief description of the component, such
as the component function, distinguishing features, and package options. The
keywords should contain additional terms related to the component. Keywords are
used primarily to assist in searching for the symbol.

image::images/eeschema_add_symbol_search_description.png[alt="Searching for a symbol in the add a symbol dialog",scaledwidth="65%"]

A symbol's name, description, and keywords are all used when searching for
symbols in the Symbol Editor and Add a Symbol dialog. The description and
keywords are displayed in the Symbol Library Browser and Add a Symbol dialog.

[[footprint-filters]]
===== Footprint Filters

The footprint filters tab is used to define which footprints are appropriate to
use with the symbol. The filters can be applied in the Footprint Assignment tool
so that only appropriate footprints are displayed for each symbol.

Multiple footprint filters can be defined. Footprints that match any of the
filters will be displayed; if no filters are defined, then all footprints will
be displayed.

Filters can use wildcards: `\*` matches any number of characters,
including zero, and `?` matches zero or one characters. For example, `SOIC-*`
would match the `SOIC-8_3.9x4.9mm_P1.27mm` footprint as well as any other
footprint beginning with `SOIC-`. The filter `SOT?23` matches `SOT23` as well as
`SOT-23`.

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

[[symbols-with-alternate-symbolic-representation]]
==== Symbols with Alternate Symbolic Representation

If the symbol has an alternate body style defined, one body style must be
selected for editing at a time. To edit the normal representation, click
the image:images/icons/morgan1_24.png[Normal representation icon] icon.

To edit the alternate representation, click on the
image:images/icons/morgan2_24.png[Alternate representation icon] icon.
Use the
image:images/toolbar_libedit_alias.png[images/toolbar_libedit_part.png]
dropdown shown below to select the unit you wish to edit.

image::images/eeschema_libedit_select_unit.png[alt="Selecting a symbol unit",scaledwidth="80%"]

[[graphical-elements]]
=== Graphical Elements

Graphical elements create the visual representation of a symbol and
contain no electrical connection information. Graphical elements are
created with the following tools:

* Lines and polygons defined by start and end points.
* Rectangles defined by two diagonal corners.
* Circles defined by the center and radius.
* Arcs defined by the starting and ending point of the arc and its
  center. An arc goes from 0° to 180°.

The vertical toolbar on the right hand side of the main window allows
you to place all of the graphical elements required to design
the representation of a symbol.

[[graphical-element-membership]]
==== Graphical Element Membership

Each graphic element (line, arc, circle, etc.) can be defined as common
to all units and/or body styles or specific to a given unit and/or body
style. Element options can be quickly accessed by right-clicking on
the element to display the context menu for the selected element. Below
is the context menu for a line element.

image::images/eeschema_libedit_context_menu.png[alt="Graphic line context menu",scaledwidth="80%"]

You can also double-left-click on an element to modify its properties.
Below is the properties dialog for a polygon element.

image::images/eeschema_libedit_polyline_properties.png[alt="Graphic line properties",scaledwidth="50%"]

The properties of a graphic element are:

* "Line width" defines the width of the element's line in the
  current drawing units.
* "Fill Style" determines if the shape defined by the
  graphical element is to be drawn unfilled, background filled, or
  foreground filled.
* "Common to all units in symbol" determines if the
  graphical element is drawn for each unit in symbol with more than one
  unit per package or if the graphical element is only drawn for the
  current unit.
* "Common to all body styles (De Morgan)" determines if the
  graphical element is drawn for each symbolic representation in
  symbols with an alternate body style or if the graphical element is
  only drawn for the current body style.

[[graphical-text-elements]]
==== Graphical Text Elements

The image:images/icons/text_24.png[Text icon] icon
allows for the creation of graphical text. Graphical text is automatically
oriented to be readable, even when the symbol is mirrored. Please note that
graphical text items are not the same as symbol fields.

[[multiple-units-per-symbol-and-alternate-body-styles]]
=== Multiple Units per Symbol and Alternate Body Styles

Symbols can have up to two body styles (a standard symbol and an alternate symbol
often referred to as a "De Morgan equivalent") and/or have more than one unit
per package (logic gates for example). Some symbols can have more than one unit
per package each with different symbols and pin configurations.

Consider for instance a relay with two switches, which can be designed as
a symbol with three different units: a coil, switch 1, and switch 2.
Designing a symbol with multiple units per package and/or alternate
body styles is very flexible. A pin or a body symbol item can be common
to all units or specific to a given unit or they can be common to both
symbolic representation so are specific to a given symbol representation.

By default, pins are specific to a unit and body style. When a pin is common to
all units or all body styles, it only needs to be created once. This is also the
case for the body style graphic shapes and text, which may be common to each
unit, but typically are specific to each body style).

[[example-of-a-symbol-with-multiple-noninterchangeable-units]]
==== Example of a Symbol With Multiple Noninterchangeable Units

For an example of a symbol with multiple units that are not interchangeable,
consider a relay with 3 units per package: a coil, switch 1, and switch 2.

The three units are not all the same, so "All units are interchangeable" should
be deselected in the Symbol Properties dialog. Alternatively, this option could
have been specified when the symbol was initially created.

image::images/eeschema_libedit_not_interchangeable.png[alt="Uncheck all units are interchangeable",scaledwidth="60%"]

===== Unit A

image::images/eeschema_libedit_unit1.png[alt="Relay unit A",scaledwidth="45%"]

===== Unit B

image::images/eeschema_libedit_unit2.png[alt="Relay unit B",scaledwidth="45%"]

===== Unit C

image::images/eeschema_libedit_unit3.png[alt="Relay unit C",scaledwidth="45%"]

Unit A does not have the same symbol and pin layout as Units B and C, so the
units are not interchangeable.

NOTE: "Synchronized Pins Edit Mode" can be enabled by clicking the
image:images/icons/pin2pin_24.png[Synchronized pins edit mode icon] icon. In
this mode, pin modifications are propagated between symbol units; changes
made in one unit will be reflected in the other units as well. When this mode is
disabled, pin changes made in one unit do not affect other units. This mode is
enabled automatically when "All units are interchangeable" is checked, but it
can be disabled. The mode cannot be enabled when "All units are interchangeable"
is unchecked or when the symbol only has one unit.

[[graphical-symbolic-elements]]
===== Graphical Symbolic Elements

Shown below are properties for a graphic body element. In the relay
example above, the three units have different symbolic representations.
Therefore, each unit was created separately and the graphical body
elements have the "Common to all units in symbol" setting disabled.

image::images/eeschema_libedit_disable_common.png[alt="Disable common to all units in symbol",scaledwidth="70%"]

[[pin-creation-and-editing]]
=== Pin Creation and Editing

You can click on the image:images/icons/pin_24.png[Pin icon] icon
to create and insert a pin. The editing of all pin properties is done by
double-clicking on the pin or right-clicking on the pin to open the pin
context menu. Pins must be created carefully, because any error will
have consequences on the PCB design. Any pin already placed can be
edited, deleted, and/or moved.

[[pin-overview]]
==== Pin Overview

A pin is defined by its graphical representation, its name and its number. The
pin's name and number can contain letters, numbers, and symbols, but not spaces.
For the Electrical Rules Check (ERC) tool to be useful, the pin's electrical
type (input, output, tri-state...) must also be defined correctly. If this type
is not defined properly, the schematic ERC check results may be invalid.

Important notes:

* Symbol pins are matched to footprint pads by number. The pin number
  in the symbol must match the corresponding pad number in the footprint.
* Do not use spaces in pin names and numbers. Spaces will be automatically
  replaced with underscores (`_`).
* To define a pin name with an inverted signal (overline) use the
  `~` (tilde) character followed by the text to invert in braces.
  For example `~{FO}O` would display [overline]#FO# O.
* If the pin name is empty, the pin is considered unnamed.
* Pin names can be repeated in a symbol.
* Pin numbers must be unique in a symbol.

[[pin-properties]]
==== Pin Properties

image::images/eeschema_libedit_pin_properties.png[alt="Pin properties",scaledwidth="95%"]

The pin properties dialog allows you to edit all of the characteristics
of a pin. This dialog pops up automatically when you create a pin or
when double-clicking on an existing pin. This dialog allows you to modify:

* The pin name and text size.
* The pin number and text size.
* The pin length.
* The pin electrical type and graphical style.
* Unit and alternate representation membership.
* Pin visibility.
* <<alternate-pin-definitions,Alternate pin definitions>>.

[[pin-graphic-styles]]
==== Pin Graphic Styles

Shown in the figure below are the different pin graphic styles. The
choice of graphic style does not have any influence on the pin's
electrical type.

image::images/eeschema_libedit_pin_properties_style.png[alt="Pin graphic styles",scaledwidth="95%"]

[[pin-electrical-types]]
==== Pin Electrical Types

Choosing the correct electrical type is important for the schematic ERC tool.
ERC will check that pins are connected appropriately, for example ensuring that
input pins are driven and power inputs receive power from an appropriate source.

[width="100%",cols="25%,75%",]
|=======================================================================
| Pin Type | Description
| Input | A pin which is exclusively an input.
| Output | A pin which is exclusively an output.
| Bidirectional | A pin that can be either an input or an output, such as a
microcontroller data bus pin.
| Tri-state | A three state output pin (high, low, or high impedance)
| Passive | A passive symbol pin: resistors, connectors, etc.
| Free | A pin that can be freely connected to any other pin without electrical
concerns.
| Unspecified | A pin for which the ERC check does not matter.
| Power input | A symbol's power pin. As a special case, power input pins that
are marked invisible are automatically connected to the net with the same name.
See the <<creating-power-ports, Power Ports section>> for more information.
| Power output | A pin that provides power to other pins, such as a regulator
output.
| Open collector | An open collector logic output.
| Open emitter | An open emitter logic output.
| Unconnected | A pin that should not be connected to anything.
|=======================================================================

[[pushing-pin-properties-to-other-pins]]
==== Pushing Pin Properties to Other Pins

You can apply the length, name size, or number size of a pin to the other
pins in the symbol by right clicking the pin and selecting **Push Pin Length**,
**Push Pin Name Size**, or **Push Pin Number Size**, respectively.

image::images/eeschema_libedit_pin_context_menu.png[alt="Pin context menu",scaledwidth="60%"]

[[defining-pins-for-multiple-units-and-alternate-symbolic-representations]]
==== Defining Pins for Multiple Units and Alternate Symbolic Representations

Symbols with multiple units and/or graphical representations are particularly
problematic when creating and editing pins. The majority of pins are specific to
each symbol unit (because each unit has a different set of pins) and to each
body style (because the form and position is different between the normal body
style and the alternate form).

The symbol library editor allows the simultaneous creation of pins. By default,
changes made to a pin are made for all units of a multiple unit symbol and to
both representations for symbols with an alternate symbolic representation.
The only exception to this is the pin's graphical type and name, which remain
unlinked between symbol units and body styles. This dependency was established
to allow for easier pin creation and editing in most cases. This dependency can
be disabled by toggling the image:images/icons/pin2pin_24.png[Synchronized pin
edit mode icon] icon on the main tool bar. This will allow you to create pins
for each unit and representation completely independently.

Pins can be common or specific to different units. Pins can also be common to
both symbolic representations or specific to each symbolic representation. When
a pin is common to all units, it only has to drawn once. Pins are set as common
or specific in the pin properties dialog.

An example is the output pin in the 7400 quad dual input NAND gate. Since there
are four units and two symbolic representations, there are eight
separate output pins defined in the symbol definition. When creating
a new 7400 symbol, unit A of the normal symbolic representation will
be shown in the library editor. To edit the pin style in the alternate
symbolic representation, it must first be enabled by clicking the
image:images/icons/morgan2_24.png[Alternate representation icon]
button on the tool bar. To edit the pin number for each unit,
select the appropriate unit using the 
image:images/toolbar_libedit_alias.png[images/toolbar_libedit_alias.png]
drop down control.

[[pin-table]]
==== Pin Table

Another way to edit pins is to use the Pin Table, which is accessible via the
image:images/icons/pin_table_24.png[Pin table icon] icon. The Pin Table
displays all of the pins in the symbol and their properties in a table view, so
it is useful for making bulk pin changes.

Any pin property can be edited by clicking on the appropriate cell. Pins can be
added and removed with the image:images/icons/small_plus_16.png[Plus icon] and
image:images/icons/small_trash_16.png[Trash icon] icons, respectively.

NOTE: Columns of the pin table can be shown or hidden by right-clicking on the
header row and checking or unchecking additional columns. Some columns are
hidden by default.

The screenshot below shows the pin table for a quad opamp.

image::images/eeschema_libedit_pin_table.png[alt="Pin table",scaledwidth="95%"]

[[alternate-pin-definitions]]
==== Alternate Pin Definitions

Pins can have alternate pin definitions added to them. Alternate pin definitions
allow a user to select a different name, electrical type, and graphical style
for a pin when the symbol has been placed in the schematic. This can be used for
pins that have multiple functions, such as microcontroller pins.

Alternate pin definitions are added in the Pin Properties dialog as shown below.
Each alternate definition contains a pin name, electrical type, and graphic style.
This microcontroller pin has all of its peripheral functions defined in the symbol
as alternate pin names.

image::images/eeschema_libedit_alternate_pin_definitions.png[alt="Alternate pin definitions", scaledwidth="60%"]

Alternate pin definitions are selected in the Schematic Editor once the symbol
has been placed in the schematic. The alternate pin is assigned in the Alternate
Pin Assignments tab of the Symbol Properties dialog. Alternate definitions are
selectable in the dropdown in the Alternate Assignment column.

image::images/eeschema_alternate_pin_assignment_selection.png[alt="Selecting an alternate pin definition", scaledwidth="60%"]

[[symbol-fields]]
=== Symbol Fields

All library symbols are defined with four default fields. The
reference designator, value, footprint assignment, and datasheet
link fields are created whenever a symbol is created or copied.
Only the reference designator and value fields are required.

Symbols defined in libraries are typically defined with only these four default
fields. Additional fields such as vendor, part number, unit cost, etc. can be
added to library symbols but generally this is done in the schematic editor so
the additional fields can be applied to all of the symbols in the schematic.

NOTE: A convenient way to create additional empty symbol fields is to use define
field name templates. Field name templates define empty fields that are added
to each symbol when it is inserted into the schematic. Field name templates can
be defined globally (for all schematics) in the Schematic Editor Preferences, or
they can be defined locally (specific to each project) in the Schematic Setup
dialog. 

[[editing-symbol-fields]]
==== Editing Symbol Fields

To edit an existing symbol field, right-click on the field text to
show the field context menu shown below.

image::images/eeschema_libedit_field_context_menu.png[alt="Symbol field context menu",scaledwidth="35%"]

To add new fields, delete optional fields, or edit existing fields, use the
image:images/icons/part_properties_24.png[Component properties icon]
icon on the main tool bar to open the <<symbol-properties,Symbol Properties dialog>>.

Fields are text information associated a the symbol. Do not confuse
them with text in the graphic representation of a symbol.

Important notes:

* Modifying the `Value` field changes the name of the symbol. The
  symbol's name in the library will change when the symbol is saved.
* The Symbol Properties dialog must be used to edit a field that is empty
  or has the invisible attribute enabled because such fields cannot be clicked on.
* The footprint is defined as an absolute footprint using the
  `LIBNAME:FOOTPRINTNAME` format where `LIBNAME` is the name of the footprint
  library defined in the footprint library table (see the "Footprint Library
  Table" section in the PCB Editor manual) and `FOOTPRINTNAME` is the name
  of the footprint in the library `LIBNAME`.

[[creating-power-ports]]
=== Creating Power Port Symbols

Power ports, or power symbols, are symbols that are used to label a wire as
part of a power net, like `VCC` or `GND`. The behavior of power ports is
described in the <<power-ports,electrical connections section>>. Power symbols
are handled and created the same way as normal symbols, but there are several
additional considerations described below.

It may be useful to place power symbols in a dedicated library. KiCad's symbol
library places power symbols in the `power` library, and users may create
libraries to store their own power symbols. If the "Define as power symbol" box
is checked in a symbol's properties, that symbol will appear in the Schematic
Editor's "Add Power Port" dialog for convenient access.


Below is an example of a `GND` power symbol.

image::images/eeschema_libedit_power_symbol.png[alt="Editing a power symbol",scaledwidth="95%"]

Power port symbols consist of a pin of type "Power input" that is marked
invisible. They must also have the "Define as power symbol" property checked.
<<hidden-power-pins,Invisible power input pins>> have a special property of
making implicit global connections based on the pin name.

NOTE: If the power symbol has the "Define as power symbol" property checked,
the power input pin does not need to be marked invisible. However, the convention
is to make these pins invisible anyway.

image::images/eeschema_libedit_power_symbol_pin.png[alt="Power symbol pin",scaledwidth="60%"]

To create a power symbol, use the following steps:

* Add a pin of type "Power input", with "Visible" unchecked, and the pin named
  according to the desired net. Make the pin number `1`, the length `0`, and set
  the graphic style to "Line". The pin name establishes the connection to the
  net; in this case the pin will automatically connect to the net `GND`. The pin
  number, length, and line style do not matter electrically.
* Place the pin on the symbol anchor.
* Use the shape tools to draw the symbol graphics.
* Set the symbol value. The symbol value does not matter electrically, but it is
  displayed in the schematic. To eliminate confusion, it should match the pin
  name (which determines the connected net name).
* Check the "Define as power symbol" box in Symbol Properties window. This
  makes the symbol appear in the "Add Power Port" dialog, makes the `Value` field
  read-only in the schematic, prevents the symbol from being assigned a footprint,
  and excludes the symbol from the board, BOM, and netlists.
* Set the symbol reference and uncheck the "Show" box. The reference text is not
  important except for the first character, which should be `\#`. For the power
  port shown above, the reference could be `#GND`. Symbols with references that
  begin with `#` are not added to the PCB, are not included in Bill of Materials
  exports or netlists, and they cannot be assigned a footprint in the footprint
  assignment tool. If a power port's reference does not begin with `#`, the
  character will be inserted automatically when the annotation or footprint
  assignment tools are run.

An easier method to create a new power port symbol is to use another symbol as a
starting point, <<creating-a-symbol-from-another-symbol,as described earlier>>.

NOTE: The connected net name is determined by the power port's *pin name*, not
      the name or value of the symbol. When modifying an existing power port
      symbol, make sure to rename the pin so that the new symbol connects to the
      appropriate power net. This means that power port net names can only be
      changed in the symbol editor, not in the schematic.
      
