:experimental:

[[schematic-creation-and-editing]]
== Schematic Creation and Editing

=== Introduction

A schematic designed with KiCad is more than a simple graphic
representation of an electronic device. It is normally the entry point
of a development chain that allows for:

* Validating against a set of rules (<<erc,Electrical Rules Check>>) to detect
  errors and omissions.
* Automatically generating a
  <<creating-customized-netlists-and-bom-files,bill of materials>>.
* <<creating-customized-netlists-and-bom-files,Generating a netlist>> for
  simulation software such as SPICE.
* <<creating-customized-netlists-and-bom-files,Defining a circuit>> for
  transferring to PCB layout.

A schematic mainly consists of symbols, wires, labels, junctions,
buses and power ports. For clarity in the schematic, you can place
purely graphical elements like bus entries, comments, and polylines.

Symbols are added to the schematic from symbol libraries. After
the schematic is made, the set of connections and footprints is imported into
the PCB editor for designing a board.

Schematics can be contained in a single sheet or split among multiple sheets. In
KiCad, multi-sheet schematics are organized hierarchically, with a root sheet
and sub-sheet(s). Each sheet is its own `.kicad_sch` file and is itself a
complete KiCad schematic. Working with hierarchical schematics is described in
the <<hierarchical-schematics,Hierarchical Schematics>> chapter.

[[schematic-editing-operations]]
=== Schematic editing operations

Schematic editing tools are located in the right toolbar.  When a tool is
activated, it stays active until a different tool is selected or the tool is
canceled with the kbd:[Esc] key. The selection tool is always activated when any
other tool is canceled.

[width="100%",cols="10%,90%",]
|=======================================================================
|image:images/icons/cursor_24.png[Selection tool icon]
|Selection tool (the default tool)

|image:images/icons/net_highlight_schematic_24.png[Highlight net icon]
|Highlight a net by marking its wires and net labels with a different color.
If the PCB Editor is also open then copper corresponding to the selected net
will be highlighted as well. Net highlighting can be cleared by clicking with
the highlight tool in an empty space, or by using the Clear Net Highlighting
hotkey (kbd:[~]).

|image:images/icons/add_component_24.png[New Symbol icon]
|Display the symbol selector dialog to place a new symbol.

|image:images/icons/add_power_24.png[Add Power icon]
|Display the power symbol selector dialog to place a new power symbol.

|image:images/icons/add_line_24.png[Draw Wire icon]
|Draw a wire.

|image:images/icons/add_bus_24.png[Draw Bus icon]
|Draw a bus.

|image:images/icons/add_line2bus_24.png[Draw wire to bus icon]
|Draw wire-to-bus entry points. These elements are only graphical and do not create
a connection, thus they should not be used to connect wires together.

|image:images/icons/noconn_24.png[draw no connect flag icon]
|Place a "No Connect" flag. These flags should be placed on symbol pins which
are meant to be left unconnected. "No connect" flags indicate to the Electrical
Rule Checker that the pin is intentionally unconnected and not an error.

|image:images/icons/add_junction_24.png[place junction icon]
|Place a junction. This connects two crossing wires or a wire and a pin, which
can sometimes be ambiguous without a junction (i.e. if a wire end or a pin is
not directly connected to another wire end).

|image:images/icons/add_label_24.png[Local label icon]
|Place a local label. Local labels connect items located **in the same sheet**.
For connections between two different sheets, use global or hierarchical labels.

|image:images/icons/add_glabel_24.png[Global label icon]
|Place a global label. All global labels with the same name are connected, even
when located on different sheets.

|image:images/icons/add_hierarchical_label_24.png[Hierarchical label icon]
|Place a hierarchical label. Hierarchical labels are used to create a connection
between a subsheet and the sheet's parent sheet. See the
<<hierarchical-schematics,Hierarchical Schematics>> section for more information
about hierarchical labels, sheets, and pins.


|image:images/icons/add_hierarchical_subsheet_24.png[Hierarchical subsheet icon]
|Place a hierarchical subsheet. You must specify the file name for this subsheet.

|image:images/icons/import_hierarchical_label_24.png[Import hierarchical label icon]
|Import a hierarchical pin from a subsheet. This command can be executed only on
hierarchical subsheets. It will create hierarchical pins corresponding to hierarchical
labels placed in the target subsheet.

|image:images/icons/add_dashed_line_24.png[draw dashed line icon]
|Draw lines.

*Note:* Lines are graphical objects and are not the same as wires
placed with the Wire tool. They do not connect anything.

|image:images/icons/text_24.png[place text icon]
|Place a text comment.

|image:images/icons/image_24.png[place bitmap icon]
|Place a bitmap image.

|image:images/icons/delete_cursor_24.png[interactive delete tool icon]
|Delete clicked items.

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

[[grids]]
=== Grids

In the Schematic Editor the cursor always moves over a grid. The grid can be
customized:

* Size can be changed using the right click menu or using **View** -> **Grid Properties...**.
* Color can be changed in the **Colors** page of the **Preferences** dialog
  (menu **Preferences** -> **General Options**).
* Visibility can be switched using the left-hand toolbar button.

The default grid size is 50 mil (0.050") or 1.27 millimeters.

This is the recommended grid for placing symbols and wires in a schematic,
and for placing pins when designing a symbol in the Symbol Editor.

NOTE: Wires connect with other wires or pins only if their ends coincide
      *exactly*. Therefore it is very important to keep symbol pins and wires
      aligned to the grid. It is recommended to always use a 50 mil grid when
      placing symbols and drawing wires because the KiCad standard symbol
      library and all libraries that follow its style also use a 50 mil grid.
      *Using a grid size other than 50 mil will result in schematics without
      proper connectivity!*

Smaller grids can also be used, but this is intended only for text and symbol
graphics, and not recommended for placing pins and wires.

NOTE: Symbols, wires, and other elements that are not aligned to the grid can be
      snapped back to the grid by selecting them, right clicking, and clicking
      **Align Elements to Grid**.

[[snapping]]
=== Snapping

Schematic elements such as symbols, wires, text, and graphic lines are snapped
to the grid when moving, dragging, and drawing them. Additionally, the wire tool
snaps to pins even when grid snapping is disabled. Both grid and pin snapping
can be disabled while moving the mouse by using the modifier keys in the table
below.

NOTE: On Apple keyboards, use the kbd:[Cmd] key instead of kbd:[Ctrl].

[options="header",cols="40%,60%"]
|====
| Modifier Key | Effect
| kbd:[Ctrl] | Disable grid snapping.
| kbd:[Shift] | Disable snapping wires to pins.
|====

[[working-with-symbols]]
=== Working with symbols

[[placing-symbols]]
==== Placing symbols

To load a symbol into your schematic you can use the icon
image:images/icons/add_component_24.png[New Symbol icon].
A dialog box allows you to type the name of the symbol to load.

image::images/en/dialog_choose_component.png[alt="Choose Component dialog",scaledwidth="60%"]

The Choose Symbols dialog will filter symbols by name, keywords,
and description according to what you type into the search field.

Some advanced filters are available:

* *Wildcards:* use the characters `?` and `*` respectively to mean "any
  single character or no characters" and "any number of any characters,
  including none".
* *Key-value pairs:* if a library part's description or keywords contain a tag
  of the format "Key:123", you can match relative to that by typing
  "Key>123" (greater than), "Key<123" (less than), etc. Numbers may include
  one of the following case-insensitive suffixes:
+
[width="100%"]
|===
| p | n | u | m | k | meg | g | t
| 10^-12^ | 10^-9^ | 10^-6^ | 10^-3^ | 10^3^ | 10^6^ | 10^9^ | 10^12^
|===
+
[width="50%"]
|===
| ki | mi | gi | ti
| 2^10^ | 2^20^ | 2^30^ | 2^40^
|===

* *Regular expressions:* if you're familiar with regular expressions, these
  can be used too. The regular expression flavor used is the
  http://docs.wxwidgets.org/3.0/overview_resyntax.html[wxWidgets
  Advanced Regular Expression style], which is similar to Perl regular
  expressions.


If the symbol specifies a default footprint, this footprint will be previewed in
the lower right. If the symbol includes footprint filters, alternate footprints
that satisfy the footprint filters can be selected in the footprint dropdown
menu at right.

After selecting a symbol to place, the symbol will be attached to the cursor.
Left clicking the desired location in the schematic places the symbol into the
schematic. Before placing the symbol in the schematic, you can rotate it, mirror
it, and edit its fields, by either using the hotkeys or the right-click
context menu. These actions can also be performed after placement.

Here is a symbol during placement:

image::images/en/component_during_placement.png[alt="component during placement",scaledwidth="95%"]

If the *Place repeated copies* option is checked, after placing a symbol KiCad
will start placing another copy of the symbol. This process continues until
the user presses kbd:[Esc].

For symbols with multiple units, if the *Place all units* option is checked,
after placing the symbol KiCad will start placing the next unit in the symbol.
This continues until the last unit has been placed or the user presses
kbd:[Esc].

[[placing-power-ports]]
==== Placing power ports

A <<power-ports,power port symbol>> is a symbol representing a connection to a
power net.  The symbols are grouped in the `power` library, so they can be
placed using the symbol chooser.  However, as power placements are frequent, the
image:images/icons/add_power_24.png[Add Power icon] tool is available. This tool
is similar, except that the search is done directly in the `power` library and
any other library that contains power symbols.

[[moving-symbols]]
==== Moving symbols

Symbols can be moved using the Move (kbd:[M]) or Drag (kbd:[G]) tools. These
tools act on the selected symbol, or if no symbol is selected they act on the
symbol under the cursor.

The *Move* tool moves the symbol itself without maintaining wired connections to
the symbol pins.

The *Drag* tool moves the symbol without breaking wired connections to its pins,
and therefore moves the connected wires as well.

You can also Drag symbols by clicking and dragging them with the mouse,
depending on the *Left button drag gesture* setting in the *Mouse and Touchpad*
section of Preferences.

Symbols can also be rotated (kbd:[R]) or mirrored in the X (kbd:[X]) or Y
(kbd:[Y]) directions.

[[editing-symbol-properties]]
==== Editing symbol properties

A symbol's fields can be edited in the symbol's Properties window. Open the
Symbol Properties window for a symbol with the kbd:[E] hotkey or by
double-clicking on the symbol.

image::images/en/dialog_component_properties.png[alt="Component Properties dialog",scaledwidth="70%"]

The Symbol Properties window displays all the fields of a symbol in a table. New
fields can be added, and existing fields can be deleted, edited, reordered,
moved, or resized.

Each field can be visible or hidden, and displayed horizontally or
vertically. The displayed position is always indicated
for a normally displayed symbol (no rotation or mirroring) and is relative
to the anchor point of the symbol.

The position and orientation properties of each field may be hidden in this
dialog. They can be shown by right-clicking on the column header of the fields
table and enabling the "Orientation", "X Position", and/or "Y Position" columns.
Other columns can be shown or hidden as desired.

The "Update Symbol from Library..." button is used to update the schematic's
copy of the symbol to match the copy in the library. The "Change Symbol..."
button is used to swap the current symbol to a different
symbol in the library.

"Edit Symbol..." opens the Symbol Editor to edit the copy of the symbol in
the schematic. Note that the original symbol in the library will not be
modified. The "Edit Library Symbol..." button opens the Symbol Editor to
edit the original symbol in the library. In this case, the symbol in the
schematic will not be modified until the user clicks the "Update Symbol from
Library..." button.

===== Editing symbol fields individually

An individual symbol text field can be edited directly with the kbd:[E] hotkey (with a field
selected instead of a symbol) or by double-clicking on the field.

Some symbol fields have their own hotkey to edit them directly. With the symbol
selected, the Reference, Value, and Footprint fields can be edited with the kbd:[U],
kbd:[V], or kbd:[F] hotkeys, respectively.

image::images/en/dialog_edit_value_field.png[alt="Edit Value Field dialog",scaledwidth="70%"]

The options in this dialog are the same as those in the full Symbol Properties
dialog, but are specific to a single field.

Symbol fields can be automatically moved to an appropriate location with the
Autoplace Fields action (select a symbol and press kbd:[O]). Field autoplacement
is configurable in the Schematic Editor's Editing Options, including a setting
to always autoplace fields.

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

The Symbol Fields Table allows you to view and modify field values for all
symbols in a spreadsheet interface. You can open the Symbol Fields Table with
the image:images/icons/spreadsheet_24.png[Symbol Fields Table icon] button.

image:images/en/dialog_symbol_fields_table.png[alt="Symbol Fields Table",scaledwidth="79%"]

Cells are navigated with the arrow keys, or with kbd:[Tab] / kbd:[Shift+Tab] to
move right / left and kbd:[Enter] / kbd:[Shift+Enter] to move down / up,
respectively.

A range of cells can be selected by clicking and dragging. The whole range of
selected cells will be copied (kbd:[Ctrl+C]) or pasted into (kbd:[Ctrl+V]) on a
copy or paste action. Copying a range of cells from the table can be useful for
creating a BOM. More details of copying and pasting cells are described below.

Any symbol field can be shown or hidden using the *Show* checkboxes on the left,
or by right-clicking on the header of the table. New symbol fields can be added
using the *Add Field...* button.

Similar symbols can optionally be grouped by any symbol field using the *Group
By* checkboxes. Grouped symbols are shown in a single row in the table. The
grouped row can be expanded to show the individual symbols by clicking the arrow
at the left of the row.

===== Tricks to simplify filling fields

There are several special copy/paste methods in the spreadsheet for pasting
values into larger regions, including auto-incrementing pasted cells. These
features may be useful when pasting values that are shared in several symbols.

These methods are illustrated below.

[options="header"]
|==========================================
|1. Copy (kbd:[Ctrl+C]) |2. Select target cells |3. Paste (kbd:[Ctrl+V])

|image:images/copypaste11.png["1copy"]
|image:images/copypaste12.png["1selection"]
|image:images/copypaste13.png["1paste"]

|image:images/copypaste21.png["2copy"]
|image:images/copypaste22.png["2selection"]
|image:images/copypaste23.png["2paste"]

|image:images/copypaste31.png["3copy"]
|image:images/copypaste32.png["3selection"]
|image:images/copypaste33.png["3paste"]

|image:images/copypaste41.png["4copy"]
|image:images/copypaste42.png["4selection"]
|image:images/copypaste43.png["4paste"]

|image:images/copypaste51.png["5copy"]
|image:images/copypaste52.png["5selection"]
|image:images/copypaste53.png["5paste"]
|==========================================

NOTE: These techniques are also available in other dialogs with a grid control
element.

[[reference-designators-and-symbol-annotation]]
=== Reference Designators and Symbol Annotation

Reference designators are unique identifiers for components in a design. They
are often printed on a PCB and in assembly diagrams, and allow you to match
symbols in a schematic to the corresponding components on a board.

In KiCad, reference designators consist of a letter indicating the type of
component (`R` for resistor, `C` for capacitor, `U` for IC, etc.) followed by a
number. If the symbol has multiple units then the reference designator will also
have a trailing letter indicating the unit. Symbols that don't have a reference
designator set have a `?` character instead of the number. Reference designators
must be unique.

Reference designators can set manually by editing a symbol's reference
designator field, or automatically using the Annotation tool.

NOTE: The process of setting a symbol's reference designator is called
*annotation*.

==== Annotation tool

The Annotation tool automatically assigns reference designators to symbols in
the schematic. To launch the Annotation tool, click the 
image:images/icons/annotate_24.png[Annotate icon] button in the top toolbar.

image::images/en/annotate-dialog.png[alt="annotate dialog",scaledwidth="50%"]

The tool provides several options to control how symbols are annotated.

*Scope:* Selects whether annotation is applied to the entire schematic, to only
the current sheet, or to only the selected symbols.

*Options:* Selects whether annotation should apply to all symbols and reset
*existing reference designators, or apply only to unannotated symbols. 

*Order:*  Chooses the direction of numbering. If symbols are sorted by X
position, all symbols on the left side of a schematic sheet will be lower
numbered than symbols on the right side of the sheet. If symbols are sorted by Y
position, all symbols on the top of a sheet will be lower numbered than symbols
at the bottom of the sheet.

*Numbering:* Selects the starting point for numbering reference designators. The
lowest unused number above the starting point is picked for each reference
designator. The starting point can be an arbitrary number (typically zero), or
it can be the sheet number multiplied by 100 or 1000 so that each part's
reference designator corresponds to the schematic page it is on.

The **Clear Annotation** button clears all reference designators in the selected
scope.

Annotation messages can be filtered with the checkboxes at the bottom or saved
to a report using the **Save...** button.

[[electrical-connections]]
=== Electrical Connections

There are two primary ways to establish connections: wires and labels. Both are
shown in the schematic below.

image::images/wires_labels.png[alt="Wires labels",scaledwidth="90%"]

Connections can also be made with buses and with implicit connections via
hidden power pins.

This section will also discuss two special types of symbols
that can be added with the "Power port" button on the right toolbar:

* *Power ports*: symbols for connecting wires to a power or ground net.
* *PWR_FLAG*: a specific symbol for indicating that a net is powered when it is
  not connected to a power output pin (for example, a power net that is supplied
  by an off-board connector).

[[label-connections]]
==== Label Connections

Labels are used to assign net names to wires and pins. Wires with the same net
name are considered to be connected. A net can only have one name. If two
different labels are placed on the same net, an ERC violation will be generated.
Only one of the net names will be used in the netlist. The final net name is
determined according to the <<net-name-assignment,rules described below>>.

There are three types of labels, each with a different connection scope.

* *Local labels*, also referred to simply as labels, only make connections
  within a sheet. Add a local label with the
  image:images/icons/add_label_24.png[Local Label icon] button in the right
  toolbar.

* *Global labels* make connections anywhere in a schematic, regardless of sheet.
  Add a global label with the
  image:images/icons/add_glabel_24.png[Global Label icon] button in the right
  toolbar.

* *Hierarchical labels* connect to hierarchical sheet pins and are used in
  <<hierarchical-schematics,hierarchical schematics>> for connecting child
  sheets to their parent sheet. Add a hierarchical label with the
  image:images/icons/add_hierarchical_label_24.png[Hierarchical Label icon]
  button in the right toolbar.

NOTE: Labels that have the same name will connect, regardless of the label type,
      if they are in the same sheet.

After using the appropriate button or hotkey to create a label, the Label
Properties dialog appears.

image::images/global_label_properties.png[Global Label Properties dialog]

The *Label* field sets the label's text, which determines the net that the label
assigns to its attached wire. Label text supports <<text-markup,markup>> for
overbars, subscripts, etc., as well as <<text-variables,variable substitution>>.
Use the *Syntax help* link in the dialog for a summary.

*Justification* sets the position of the label's connection point relative to
the label's text. For example, when *Align right* is selected the connection
point will be to the right of the text.

*Text size* and *Style* control the appearance of the label's text. *Shape*
controls the shape of the outline around the label; this is purely visual and
has no electrical consequence. Local labels do not have an outline, and
therefore do not have *Shape* options.

NOTE: Global labels have additional settings to control margins around the label
text in the <<schematic-setup,Schematic Setup dialog>>.

After accepting the label properties, the label is attached to the cursor for
placement. The connection point for a label is the small square in the corner of
the label. The square disappears when the label is connected to a wire or the
end of a pin.

image::images/unconnected_label.png[Unconnected label]

The connection point's position relative to the label text can be changed by
choosing a different label orientation in the label's properties, or by
mirroring/rotating the label.

The Label Properties dialog can be accessed at any time by selecting a label and
using the kbd:[E] hotkey, double-clicking on the label, or with
**Properties...** in the right-click context menu.

==== Wire Connections

To establish a connection, a segment of wire must be connected by its end to
another segment or to a pin. Only wire ends create connections; if a wire
crosses the middle of another wire, a connection will not be made.

Unconnected wire ends have a small square that indicates the connection point.
The square disappears when a connection is made to the wire end. Unconnected
pins have a circle, which also disappears when a connection is made.

NOTE: Wires connect with other wires or pins only if their ends coincide
      exactly. Therefore it is important to keep symbol pins and wires aligned
      to the grid. It is recommended to always use a 50 mil grid when placing
      symbols and drawing wires because the KiCad standard symbol library and
      all libraries that follow its style also use a 50 mil grid.

NOTE: Symbols, wires, and other elements that are not aligned to the grid can be
      snapped back to the grid by selecting them, right clicking, and selecting
      **Align Elements to Grid**.

[[drawing-and-editing-wires]]
===== Drawing and editing wires

To begin connecting elements with wire, use the Wire tool
image:images/icons/add_line_24.png[line tool icon] in the right toolbar
(kbd:[w]). Wires can also be automatically started by clicking on an unconnected
symbol pin or wire end.

Wires can be moved using the Move (kbd:[M]) or Drag (kbd:[G]) tools. As with
symbols, the *Move* tool moves only the selected segment, without maintaining
existing connections to other segments. The *Drag* tool maintains existing
connections.

If a segment is selected or the cursor is over the middle of a wire, the
move/drag action will move the entire segment. If the cursor is over a corner or
wire end, the move/drag action will act on one end of the segment.

===== Wire Junctions

Wires that cross are not implicitly connected. It is necessary to
join them by explicitly adding a junction dot if a connection is desired
(image:images/icons/add_junction_24.png[Add Junction icon] button in the right
toolbar). Junction dots will be automatically added to wires that start or end
on top of an existing wire.

Junction dots are used in the schematic figure above on the wires connected to
`P1` pins 18, 19, 20, 21, 22, and 23.


[[bus-connections]]
==== Bus Connections

Buses are a way to group related signals in the schematic in order to
simplify complicated designs.  Buses can be drawn like wires using the
bus tool image:images/icons/add_bus_24.png[bus tool icon], and are named using
labels the same way signal wires are.

In the following schematic, many pins are connected to buses, which are the
thick blue lines in the center.

image::images/sch_with_buses.png[alt="Example schematic with buses",scaledwidth="90%"]

[[bus-members]]
===== Bus members

There are two types of bus in KiCad 6.0 and later: vector buses and
group buses.

A *vector bus* is a collection of signals that start with a common prefix
and end with a number.  Vector buses are named `<PREFIX>[M..N]` where
`PREFIX` is any valid signal name, `M` is the first suffix number, and `N`
is the last suffix number.  For example, the bus `DATA[0..7]` contains the
signals `DATA0`, `DATA1`, and so on up to `DATA7`.  It doesn't matter which
order `M` and `N` are specified in, but both must be non-negative.

A *group bus* is a collection of one or more signals and/or vector buses.
Group buses can be used to bundle together related signals even when they
have different names.  Group buses use a special label syntax:

`<OPTIONAL_NAME>{SIGNAL1 SIGNAL2 SIGNAL3}`

The members of the group are listed inside curly braces (`{}`) separated
by space characters.  An optional name for the group goes before the opening
curly brace.  If the group bus is unnamed, the resulting nets on the PCB
will just be the signal names inside the group.  If the group bus has a
name, the resulting nets will have the name as a prefix, with a period (`.`)
separating the prefix from the signal name.

For example, the bus `{SCL SDA}` has two signal members, and in the netlist
these signals will be `SCL` and `SDA`.  The bus `USB1{DP DM}` will generate
nets called `USB1.DP` and `USB1.DM`.  For designs with larger buses that are
repeated across several similar circuits, using this technique can save time.

Group buses can also contain vector buses.  For example, the bus
`MEMORY{A[7..0] D[7..0] OE WE}` contains both vector buses and plain signals,
and will result in nets such as `MEMORY.A7` and `MEMORY.OE` on the PCB.

Bus wires can be drawn and connected in the same manner as signal wires,
including using junctions to create connections between crossing wires.
Like signals, buses cannot have more than one name -- if two conflicting
labels are attached to the same bus, an ERC violation will be generated.

[[connections-between-bus-members]]
===== Connections between bus members

Pins connected between the same members of a bus must be connected by
labels. It is not possible to connect a pin directly to a bus; this
type of connection will be ignored by KiCad.

In the example above, connections are made by the labels placed on wires
connected to the pins. Bus entries (wire segments at 45
degrees) to buses are graphical only, and are not necessary to form
logical connections.

In fact, using the repetition command (kbd:[Insert]), connections can
be very quickly made in the following way, if component pins are aligned
in increasing order (a common case in practice on components such as
memories, microprocessors...):

* Place the first label (for example `PCA0`)
* Use the repetition command as much as needed to place members.
  KiCad will automatically create the next labels (`PCA1`, `PCA2`...)
  vertically aligned, theoretically on the position of the other pins.
* Draw the wire under the first label. Then use the repetition command
  to place the other wires under the labels.
* If needed, place the bus entries by the same way (Place the first
  entry, then use the repetition command).

[NOTE]
====

In the **Schematic Editor** -> **Editing Options** section of the Preferences
menu, you can set the repetition parameters:

* Horizontal pitch
* Vertical pitch
* Label increment (labels can be incremented or decremented by 1, 2, 3, etc.)
====

[[bus-unfolding]]
===== Bus unfolding

The unfold tool allows you to quickly break out signals from a bus.  To unfold a
signal, right-click on a bus object (a bus wire, etc) and choose
**Unfold from Bus**.  Alternatively, use the *Unfold Bus* hotkey (default: kbd:[C])
when the cursor is over a bus object.  The menu allows you to select which bus
member to unfold.

After selecting the bus member, the next click will place the bus member
label at the desired location.  The tool automatically generates a bus entry
and wire leading up to the label location.  After placing the label, you
can continue placing additional wire segments (for example, to connect to a
component pin) and complete the wire in any of the normal ways.

[[bus-aliases]]
===== Bus aliases

Bus aliases are shortcuts that allow you to work with large group buses
more efficiently.  They allow you to define a group bus and give it a short
name that can then be used instead of the full group name across the schematic.

To create bus aliases, open the **Bus Definitions** dialog in the **Tools** menu.

image::images/en/dialog_bus_definitions.png[alt="Bus Definitions Dialog",scaledwidth="90%"]

An alias may be named any valid signal name.  Using the dialog, you can add
signals or vector buses to the alias.  As a shortcut, you can type or paste
in a list of signals and/or buses separated by spaces, and they will all be
added to the alias definition.  In this example, we define an alias called
`USB` with members `DP`, `DM`, and `VBUS`.

After defining an alias, it can be used in a group bus label by putting the
alias name inside the curly braces of the group bus: `{USB}`.  This has the
same effect as labeling the bus `{DP DM VBUS}`.  You can also add a prefix
name to the group, such as `USB1{USB}`, which results in nets such as
`USB1.DP` as described above.  For complicated buses, using aliases can
make the labels on your schematic much shorter.  Keep in mind that the aliases
are just a shortcut, and the name of the alias is not included in the netlist.

Bus aliases are saved in the schematic file.  Any aliases created in a given
schematic sheet are available to use in any other schematic sheet that is in
the same hierarchical design.

[[bus-migration]]
===== Buses with more than one label

KiCad 5.0 and earlier allowed the connection of bus wires with different labels
together, and would join the members of these buses during netlisting. This
behavior has been removed in KiCad 6.0 because it is incompatible with group
buses, and also leads to confusing netlists because the name that a given signal
will receive is not easily predicted.

If you open a design that made use of this feature in a modern version of KiCad,
you will see the Migrate Buses dialog which guides you through updating the
schematic so that only one label exists on any given set of bus wires.

image::images/en/dialog_migrate_buses.png[alt="Bus Migration Dialog",scaledwidth="90%"]

For each set of bus wires that has more than one label, you must choose the
label to keep.  The drop-down name box lets you choose between the labels that
exist in the design, or you can choose a different name by manually entering it
into the new name field.

[[power-ports-connection]]
[[hidden-power-pins]]
==== Hidden Power Pins

When the power pins of a symbol are visible, they must be connected, as with any
other signal. However, symbols such as gates and flip-flops are sometimes drawn
with hidden power input pins which are connected implicitly.

KiCad automatically connects invisible pins with type "power input" to a global
net with the same name as the pin. For example, if a symbol has a hidden power
input pin named `VCC`, this pin will be globally connected to the `VCC` net on
all sheets.

NOTE: Hidden pins can be shown in the schematic by checking the **Show hidden
      pins** option in the **Schematic Editor** -> **Display Options** section
      of the preferences, or by selecting **View** -> **Show hidden pins**.
      There is also a toggle icon image:images/icons/hidden_pin_24.png[] on the
      left toolbar.

It may be necessary to join power nets of different names (for example, `GND` in
TTL components and `VSS` in MOS components). To accomplish this, add a
<<power-ports,power port symbol>> for each net and connect them with a wire.

If hidden power pins are used, it is not recommended to use local labels for
power connection, as they will not connect to hidden power pins on other sheets.

NOTE: Care must be taken with hidden power input pins because they can create
      unintentional connections. By nature, hidden pins are invisible and do not
      display their pin name. This makes it easy to accidentally connect two
      power pins to the same net. For this reason, *using invisible power pins
      in symbols is not recommended* outside of power port symbols, and is only
      supported for compatibility with legacy designs and symbols.

[[power-ports]]
==== Power Ports

Power ports are symbols that are conventionally used to represent a connection
to a power net, such as `VCC` or `GND`. In addition to being a visual indicator
that the attached net is a power rail, power ports make global connections: two
power ports with the same pin name connect to each other anywhere in the
schematic, regardless of sheet.

In the figure below, power port symbols are used to connect the positive and
negative terminals of the capacitors to the `VCC` and `GND` nets, respectively. 

image::images/en/power_ports_example.png[alt="Power ports example",scaledwidth="90%"]

In the KiCad standard library, power ports are found in the `power` library, but
power port symbols can be created in any library. To create a custom power port,
make a new symbol with a power input pin that is set to be invisible. Name the
pin according to the desired power net. In addition, set the "Define as power
symbol" symbol property. As described in the
<<hidden-power-pins,hidden power pins section>>, invisible power input pins make
global connections based on the hidden power pin's name. The process of creating
a power port is described in more detail in the <<creating-power-ports,Symbol
Editor section>>.

NOTE: The connected net name is determined by the power port's *pin name*, not
      the name or value of the symbol. This means that power port net names
      can only be changed in the symbol editor, not in the schematic.

[[net-name-assignment-rules]]
==== Net name assignment rules

Every net in the schematic is assigned a name, whether that name is specified by
the user or automatically generated by KiCad.

When multiple labels are attached to the same net, the final net name is
determined in the following order, from highest priority to lowest:

1. Global labels
2. <<power-ports,Power ports>>
3. Local labels
4. Hierarchical labels
5. Hierarchical sheet pins

If there are multiple labels of one type attached to a net, the names are sorted
alphabetically and the first is used. 

If a net travels through multiple sheets in a
<<hierarchical-schematics,hierarchy>>, and has no global label or power port, it
will take its name from the highest level of the hierarchy where it has a
hierarchical label or local label. As described above, local labels take
priority over hierarchical labels.

If none of the labels above are attached to a net, the net's name is
automatically generated based on the connected symbol pins.

[[pwr-flag]]
==== PWR_FLAG

Two `PWR_FLAG` symbols are visible in the screenshot above. They indicate to ERC
that the two power nets `VCC` and `GND` are actually connected to a power
source, as there is no explicit power source such as a voltage regulator output
attached to either net.

Without these two flags, the ERC tool would diagnose: __Error: Input Power pin
not driven by any Output Power pins.__

The `PWR_FLAG` symbol is found in the `power` symbol library. The same effect
can be achieved by connecting any power output pin to the net.

[[no-connection-symbols]]
==== No-connection flag

No-connection flags (image:images/icons/noconn_24.png[No-connection icon]) are
used to indicate that a pin is intentionally unconnected.  These flags do not
have any effect on the schematic's connectivity, but they prevent "unconnected
pin" ERC warnings for pins that are intentionally unconnected.

=== Graphical items

[[text-comments]]
[[graphic-lines]]
==== Text and graphic lines

It can be useful to place annotations such as text fields and frames to aid in
understanding the schematic. Text fields (image:images/icons/text_24.png[]) and
graphic lines (image:images/icons/add_dashed_line_24.png[]) are intended for
this use, as opposed to labels and wires, which are connection elements.

The image below shows graphic lines and text in addition to wires, local labels,
and hierarchical labels.

image::images/en/frame_example.png[alt="Frame with comment example",scaledwidth="65%"]

[[text-markup]]
// TODO describe text markup

[[sheet-title-block]]
==== Sheet title block

The title block is edited with the Page Settings tool
(image:images/icons/sheetset_24.png[Page Settings tool]).

image::images/en/page_settings.png[alt="Page settings dialog",scaledwidth="80%"]

Each field in the title block can be edited, as well as the paper size and
orientation. If the "Export to other sheets" option is checked for a field, that
field will be updated in the title block of all sheets, rather than only the
current sheet.

You can set the date to today's or any other date by pressing the left arrow
button by "Issue Date", but the date in the schematic will not be automatically
updated.

A drawing sheet template file can also be selected.

image::images/en/title_block.png[alt="Title block",scaledwidth="80%"]

The sheet number (Sheet X/Y) is automatically updated, but sheet page numbers
can also be manually set using **Edit** -> **Edit Sheet Page Number...**.

[[schematic-setup]]
=== Schematic Setup

The Schematic Setup window is used to set schematic options that are specific to
the currently active schematic. For example, the Schematic Setup window contains
formatting options, electrical rule configuration, netclass setup, and schematic
text variable setup.

// TODO: expand
// Formatting: describe here
// Field name templates: describe here
// ERC: mention, link to ERC section
// Net classes: mention, link to pcbnew, mention about unstable net naming & net classes
// text variables: describe here, and in a note link to advanced documentation on builtins

[[rescuing-cached-components]]
=== Rescuing cached symbols

By default, KiCad loads symbols from the project libraries according to the set paths and
library order. This can cause a problem when loading a very old project: if the symbols in the
library have changed or have been removed or the library no longer exists since they were used
in the project, the ones in the project would be automatically replaced with the new versions.
The new versions might not line up correctly or might be oriented differently leading to a
 broken schematic.

When a project is saved, a cache library with the contents of the current library symbols is
saved along with the schematic. This allows the project to be distributed without the full
libraries. If you load a project where symbols are present both in its cache and in the system
libraries, KiCad will scan the libraries for conflicts. Any conflicts found will be listed
in the following dialog:

image::images/en/rescue-conflicts.png[alt="Rescue conflicts dialog",scaledwidth="60%"]

You can see in this example that the project originally used a diode with the cathode facing up,
but the library now contains one with the cathode facing down. This change would break the
schematic! Pressing OK here will cause the symbol cache library to be saved into a special
`rescue` library and all the symbols are renamed to avoid naming conflicts.

If you press Cancel, no rescues will be made, so KiCad will load all the new components by
default. If you save the schematic at this point, your cache will be overwritten and the old
symbols will not be recoverable.  If you have saved the schematic, you can still go back and
run the rescue function again by selecting "Rescue Cached Components" in the "Tools" menu to
call up the rescue dialog again.

If you would prefer not to see this dialog, you can press "Never Show Again". The default will
be to do nothing and allow the new components to be loaded. This option can be changed back in
the  Libraries preferences.
