
[[hierarchical-schematics]]
== Hierarchical schematics

[[introduction-2]]
=== Introduction

A hierarchical representation is generally a good solution for projects
bigger than a few sheets. If you want to manage this kind of project, it
will be necessary to:

* Use large sheets, which results in printing and handling problems.
* Use several sheets, which leads you to a hierarchy structure.

The complete schematic then consists in a main schematic sheet, called
root sheet, and sub-sheets constituting the hierarchy. Moreover, a
skillful subdividing of the design into separate sheets often improves
on its readability.

From the root sheet, you must be able to find all sub-sheets.
Hierarchical schematics management is very easy with Eeschema, thanks to
an integrated "hierarchy navigator" accessible via the icon
image:images/icons/hierarchy_nav.png[icons/hierarchy_nav_png]
of the top toolbar.

There are two types of hierarchy that can exist simultaneously: the
first one has just been evoked and is of general use. The second
consists in creating symbols in the library that appear like
traditional symbols in the schematic, but which actually correspond
to a schematic which describes their internal structure.

This second type is used to develop integrated circuits, because in this
case you have to use function libraries in the schematic you are
drawing.

Eeschema currently doesn't treat this second case.

A hierarchy can be:

* simple: a given sheet is used only once
* complex: a given sheet is used more than once (multiples instances)
* flat: which is a simple hierarchy, but connections between sheets are
  not drawn.

Eeschema can deal with all these hierarchies.

The creation of a hierarchical schematic is easy, the whole hierarchy is
handled starting from the root schematic, as if you had only one
schematic.

The two important steps to understand are:

* How to create a sub-sheet.
* How to build electrical connections between sub-sheets.

[[navigation-in-the-hierarchy]]
=== Navigation in the Hierarchy

Navigation among sub-sheets is acheived by using the navigator tool
accessible via the button
image:images/icons/hierarchy_nav.png[icons/hierarchy_nav_png]
on the top toolbar.

image::images/hierarchy_navigator_dialog.png[alt="hierarchy_navigator_dialog_png",scaledwidth="50%"]

Each sheet is reachable by clicking on its name. For quick access, right
click on a sheet name, and choose to Enter Sheet or double click within
the bounds of the sheet.

In order to exit the current sheet to the parent sheet, right click anywhere in the
schematic where there is no object and select "Leave Sheet" in the context menu
or press Alt+Backspace.

[[local-hierarchical-and-global-labels]]
=== Local, hierarchical and global labels

[[properties]]
==== Properties

Local labels, tool
image:images/icons/add_line_label.png[icons/add_line_label_png],
are connecting signals only within a sheet. Hierarchical labels (tool
image:images/icons/add_hierarchical_label.png[icons/add_hierarchical_label_png])
are connecting signals only within a sheet and to a hierarchical pin
placed in the parent sheet.

Global labels (tool
image:images/icons/add_glabel.png[Global label icon])
are connecting signals across all the hierarchy. Power pins (type _power
in_ and __power out__) invisible are like global labels because they are
seen as connected between them across all the hierarchy.

[NOTE]
Within a hierarchy (simple or complex) one can use both hierarchical
labels and/or global labels.

[[summary-of-hierarchy-creation]]
=== Summary of hierarchy creation

You have to:

* Place in the root sheet a hierarchy symbol called "sheet symbol".
* Enter into the new schematic (sub-sheet) with the navigator and draw
  it, like any other schematic.
* Draw the electric connections between the two schematics by placing
  Global Labels (HLabels) in the new schematic (sub-sheet), and labels
  having the same name in the root sheet, known as SheetLabels. These
  SheetLabels will be connected to the sheet symbol of the root sheet to
  the other elements of the schematic like standard symbol pins.

[[sheet-symbol]]
=== Sheet symbol

Draw a rectangle defined by two diagonal points symbolizing the
sub-sheet.

The size of this rectangle must allow you to place later particular
labels, hierarchy pins, corresponding to the global labels (HLabels) in
the sub-sheet.

These labels are similar to usual symbol pins. Select the tool
image:images/icons/add_hierarchical_subsheet.png[icons/add_hierarchical_subsheet_png].

Click to place the upper left corner of the rectangle. Click again to
place the lower right corner, having a large enough rectangle.

You will then be prompted to type a file name and a sheet name for this
sub-sheet (in order to reach the corresponding schematic, using the
hierarchy navigator).

image::images/hsheet_properties_1.png[alt="hsheet_properties_1_png",scaledwidth="70%"]

You must give at least a file name. If there is no sheet name, the file
name will be used as sheet name (usual way to do that).

[[connections-hierarchical-pins]]
=== Connections - hierarchical pins

You will create here points of connection (hierarchy pins) for the
symbol which has been just created.

These points of connection are similar to normal symbol pins, with
however the possibility to connect a complete bus with only one point of
connection.

There are two ways to do this:

* Place the different pins before drawing the sub-sheet (manual
  placement).
* Place the different pins after drawing the sub-sheet, and the global
  labels (semi-automatic placement).

The second solution is quite preferable.

*Manual placement:*

* Select the tool
  image:images/icons/add_hierar_pin.png[icons/add_hierar_pin_png].
* Click on the hierarchy symbol where you want to place the pin.

See below for an example of creating a hierarchical pin named
"CONNECTION":

image::images/eeschema_hierarchical_pin.png[alt="eeschema_hierarchical_pin_png",scaledwidth="70%"]

You can define the name, size and direction of the pin during creation
or later, by right clicking the pin and selecting Edit Sheet Pin in the popup menu.

Inside the sheet a Hierarchical Label must be preset with the same name
as the Hierarchical Pin. Taking care to correctly match these names must
be done manually, which is why the second method, below, is preferred.

*Automatic placement:*

* Select the tool
  image:images/icons/import_hierarchical_label.png[icons/import_hierarchical_label_png].
* Click on the hierarchy symbol from where you want to import the pins
  corresponding to global labels placed in the corresponding schematic. A
  hierarchical pin appears, if a new global label exists, i.e. not
  corresponding to an already placed pin.
* Click where you want to place this pin.

All necessary pins can thus be placed quickly and without error. Their
aspect is in accordance with corresponding global labels.

[[connections---hierarchical-labels]]
=== Connections - hierarchical labels

Each pin of the sheet symbol just created, must correspond to a label
called hierarchical Label in the sub-sheet. Hierarchical labels are
similar to labels, but they provide connections between sub-sheet and
root sheet. The graphical representation of the two complementary labels
(pin and HLabel) is similar. Hierarchical labels creation is made with
the tool
image:images/icons/add_hierarchical_label.png[icons/add_hierarchical_label_png].

See below a root sheet example:

image::images/hierarchical_label_root.png[alt="hierarchical_label_root_png",scaledwidth="70%"]

Notice pin VCC_PIC, connected to connector JP1.

Here are the corresponding connections in the sub-sheet :

image::images/hierarchical_label_sub.png[alt="hierarchical_label_sub_png",scaledwidth="85%"]

You find again, the two corresponding hierarchical labels, providing
connection between the two hierarchical sheets.

[NOTE]
You can use hierarchical labels and hierarchy pins to connect two buses,
according to the syntax (Bus [N. .m]) previously described.

[[labels-hierarchical-labels-global-labels-and-invisible-power-pins]]
==== Labels, hierarchical labels, global labels and invisible power pins

Here are some comments on various ways to provide connections, other
than wire connections.

[[simple-labels]]
===== Simple labels

Simple labels have a local capacity of connection, i.e. limited to the
schematic sheet where they are placed. This is due to the fact that :

* Each sheet has a sheet number.
* This sheet number is associated to a label.

Thus, if you place the label "TOTO" in sheet n° 3, in fact the true
label is "TOTO_3". If you also place a label "TOTO" in sheet n° 1 (root
sheet) you place in fact a label called "TOTO_1", different from
"TOTO_3". This is always true, even if there is only one sheet.

[[hierarchical-labels]]
===== Hierarchical labels

What is said for the simple labels is also true for hierarchical labels.

Thus in the same sheet, a hierarchical label "TOTO" is considered to be
connected to a local label "TOTO", but not connected to a hierarchical
label or label called "TOTO" in another sheet.

A hierarchical label is considered to be connected to the corresponding
sheet pin symbol in the hierarchical symbol placed in the parent sheet.

[[invisible-power-pins]]
===== Invisible power pins

It was seen that invisible power pins were connected together if they
have the same name. Thus all the power pins declared "Invisible Power
Pins" and named VCC are connected all symbol invisible power pins named
VCC only within the sheet they are placed.

This means that if you place a VCC label in a sub-sheet, it will not be
connected to VCC pins, because this label is actually VCC_n, where n is
the sheet number.

If you want this label VCC to be really connected to the VCC for the
entire schematic, it will have to be explicitly connected to an invisible
power pin via a VCC power symbol.

[[global-labels]]
==== Global labels

Global labels that have an identical name are connected across the whole
hierarchy.

(power labels like vcc ... are global labels)

[[complex-hierarchy]]
=== Complex Hierarchy

Here is an example. The same schematic is used twice (two instances).
The two sheets share the same schematic because the file name is the
same for the two sheets (``other_sheet.sch'').  The sheet names must be
unique.

image::images/eeschema_complex_hierarchy.png[alt="eeschema_complex_hierarchy_png",scaledwidth="80%"]

[[flat-hierarchy]]
=== Flat hierarchy

You can create a project using many sheets without creating connections
between these sheets (flat hierarchy) if the following rules are observed:

* Create a root sheet containing the other sheets which acts
  as a link between others sheets.
* No explicit connections are needed.
* Use global labels instead of hierarchical labels in all sheets.

Here is an example of a root sheet.

image::images/eeschema_flat_hierarchy.png[alt="eeschema_flat_hierarchy_png",scaledwidth="80%"]

Here is the two pages, connected by global labels.

Here is the pic_programmer.sch.

image::images/eeschema_flat_hierarchy_1.png[alt="eeschema_flat_hierarchy_1_png",scaledwidth="80%"]

Here is the pic_sockets.sch.

image::images/eeschema_flat_hierarchy_2.png[alt="eeschema_flat_hierarchy_2_png",scaledwidth="80%"]

Look at global labels.

image::images/eeschema_flat_hierarchy_3.png[alt="eeschema_flat_hierarchy_3_png",scaledwidth="30%"]
