:experimental:

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

=== Introduction

A schematic can be represented by a single sheet, but, if big enough, it
will require several sheets.

A schematic represented by several sheets is hierarchical,
and all its sheets (each one represented by its own file) constitute a
complete KiCad schematic. The manipulation of hierarchical schematics will be
described in the <<hierarchical-schematics,Hierarchical Schematics>>
chapter.

[[general-considerations]]
=== General considerations

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 bill of materials (<<creating-customized-netlists-and-bom-files,BOM>>).
* <<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.

[[component-placement-and-editing]]
=== Symbol placement and editing

[[find-and-place-a-component]]
==== Find and place a symbol

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. Advanced
filters can be used just by typing them:

* *Wildcards:* use the characters `?` and `*` respectively to mean "any
  character" and "any number of characters".
* *Relational:* 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 expression:* 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.

[[component-editing-and-modification-already-placed-component]]
==== Symbol Editing and Modification (already placed component)

There are two ways to edit a symbol:

* Modification of the symbol itself: position, orientation, unit selection on a multi-unit symbol.
* Modification of one of the fields of the symbol: reference, value, footprint, etc.

When a symbol has just been placed, you may have to modify its value
(particularly for resistors, capacitors, etc.), but it is useless to
assign to it a reference number right away, or to select the unit
(except for components with locked units, which you have to assign
manually). This can be done automatically by the annotation function.

[[component-modification]]
===== Symbol modification

To modify some feature of a symbol, position the cursor on the
symbol, and then either:

* Double-click on the symbol to open the full editing dialog.
* Right-click to open the context menu and use one of the
  commands: Move, Orientation, Edit, Delete, etc.
* Use a hotkey to perform an action on the symbol (kbd:[E]
  to open the properties dialog, kbd:[R] to rotate, etc.). Note that
  hotkeys act on the selected symbol; if no symbol is selected
  hotkeys act on the symbol under the cursor.

Symbols can also be selected by clicking on them or drag-selecting them.
Selected symbols can be modified by clicking relevant buttons in the top toolbar
or using a hotkey.

[[text-fields-modification]]
===== Text fields modification

You can modify the reference, value, position, orientation, text size and
visibility of the fields:

* Double-click on the text field to modify it.
* Right-click to open the context menu and use one of the
  commands: Move, Rotate, Edit, Delete, etc.
* Position the cursor over the field (if nothing is selected)
  or select the field and press kbd:[E] to edit the field.
* Position the cursor over the symbol (if nothing is selected)
  or select the symbol and press kbd:[V], kbd:[U], or kbd:[F]
  hotkeys to directly edit the symbol's value, reference designator,
  or footprint fields, respectively.

For more options, or in order to create fields,
double-click on the symbol to open the Symbol Properties
dialog.

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

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.

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

NOTE: TODO: Write this section.

[[wires-buses-labels-power-ports]]
=== Electrical Connections

[[introduction-1]]
==== Introduction

There are a number of elements that can be added to a schematic to electrically
connect components. All of these elements can be placed with the buttons on the
vertical right toolbar or using hotkeys.

These elements are:

* *Wires:* direct connection between pins.
* *Buses:* connections for a group of signals.
* *Bus entries:* connections between wires and buses.
* *No-connection flags:* terminations for pins or wires that are intentionally
  unconnected. These flags prevent ERC violations for unconnected pins.
* *Junctions:* connections between crossing wires or buses.
* *Net labels:* local name for a signal. Signals within a sheet that have the
  same net label are connected.
* *Global labels:* global name for a signal. Signals with the same global label
  are connected even if they are not in the same sheet.
* *Hierarchical labels:* a label for a signal in a subsheet that enables the
  signal to be accessed in a parent sheet. See the
  <<hierarchical-schematics,Hierarchical Schematics>> section for more
  information about hierarchical labels, sheets, and pins.
* *Hierarchical sheets:* an instantiation of a subsheet within a parent
  sheet. The parent sheet can connect to the subsheet through the subsheet's hierarchical pins.
* *Hierarchical pins:* connection points between a parent sheet and a subsheet.
  Hierarchical pins appear at the parent sheet's level and correspond to hierarchical
  labels in the subsheet.

Several other types of items can be placed on the schematic but do not affect connectivity:

* *Graphical lines:* graphical lines for presentation.
* *Text:* textual comments and annotations.
* *Bitmap images:* raster graphics from an external file.

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).

[[connections-wires-and-labels]]
==== Connections (Wires and Labels)

There are two ways to establish connection:

* Pin to pin wires.
* Labels.

The following figure shows the two methods:

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

===== Label Connections

The point of "contact" of a label is the small square in the corner of
the label. The square disappears when the label is connected.
The position of the connection point relative to the label text can be
changed by choosing a different label orientation in the label properties, or
by mirroring/rotating the label.

The label's connection point must be in contact with a wire or the end of
a pin for the label to be connected.

===== Wire Connections

To establish a connection, a segment of wire must be connected by its
ends to an another segment or to a pin.

If there is overlapping (if a wire passes over a pin, but without being
connected to the pin end) there is no connection.

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**.

===== Wire Junctions

Wires that cross are not implicitly connected. It is necessary to
join them with a junction dot if a connection is desired. Junction dots will be
automatically added to wires that start or end on top of an existing wire.

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

===== Nets with Multiple Names

A signal 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.

[[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 automatically be connected to the global
`VCC` net.

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, the use of invisible power pins in
symbols is not recommended outside of power port symbols, and is only supported
for compatibility with legacy designs and symbols.

[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 (options)
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.

It is not recommended to use labels for power connection. These only have
a "local" connection scope, and will not connect to invisible power pins.

[[wiring]]
==== Wiring

To begin connecting elements, you may either use the 'Wire' or 'Bus' tools
from the right-hand toolbar, or you can auto-start a new wire from any existing
pin or unconnected wire.

The wire drag action will drag the entire wire if you start
dragging from the middle of the wire.  Alternatively, it will drag just one corner
if you start the drag action over a corner where two wires connect

[[connections-buses]]
==== Connections (Buses)

In the following schematic, many pins are connected to buses.

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

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

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, and are named using labels the same way signal wires are.
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]]
==== Power Ports

Power port symbols are conventionally used to connect pins to power nets. Power
port symbols have a single pin which is invisible and marked as a power input.
As described in the <<hidden-power-pins,hidden power pins section>>, any wire
connected to the pin of a power port is therefore automatically connected to the
power net with the same name as the port's pin.

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 hidden pin marked as a power input. Name the pin
according to the desired power net.

The figure below shows an example of power port connections.

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

In this example, power ports symbols are used to connect the positive and
negative terminals of the capacitors to the `VCC` and `GND` nets, respectively.

Power port symbols are found in the `power` symbol library. They can also be
created by drawing a symbol with a hidden "power input" pin that has the name of
the desired power net.

[[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.

[[drawing-complements]]
=== Drawing Complements

[[text-comments]]
[[graphic-lines]]
==== Text comments 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%"]

[[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.

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...**.

[[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.
