:experimental:

[[advanced]]
== Advanced Topics

[[color-settings]]
[[configuration-and-customization]]
[[preferences-field-name-templates]]
[[preferences-schematic-display-options]]
=== Configuration and Customization

NOTE: This section of the KiCad documentation has not yet been written.  We
      appreciate your patience as our small team of volunteer documentation
      writers work to update and expand the documentation.

[[text-variables]]
=== Text variables

KiCad supports text variables, which allow you to substitute the variable name
with a defined text string. This substitution happens anywhere the variable name
is used inside the variable replacement syntax of `${VARIABLENAME}`.

You can define your own text variables in the
<<schematic-setup-text-variables,schematic>> or
xref:../pcbnew/pcbnew.adoc#board-setup-text-variables[board setup]
dialogs, but there are also a number of built-in system text variables. System
text variables may be available in some contexts and not others.

The following variables can be used in schematic text, label names, label
fields, hierarchical sheet fields, symbol text, and symbol fields. There are
also a number of
xref:../pcbnew/pcbnew.adoc#text-variables[variables that can be used in the PCB Editor].

Variables used in hierarchical sheet fields refer to the properties of the
hierarchical sheet, not the parent, unless otherwise noted. For example, `${#}`
returns the subsheet's page number when used in a hierarchical sheet field, but
the parent sheet's page number when used in graphic text in the parent sheet.

[options="header",cols="20%,80%"]
|====
| Variable name | Description
| `#`
  | Sheet number.
| `##`
  | Total number of schematic sheets.
| `SHEETPATH`
  | Sheet path of the current sheet.
| `FILENAME`
  | Filename of the *root schematic sheet*, with a file extension.
| `PROJECTNAME`
  | Project name, without a file extension.
| `ISSUE_DATE`
  | Contents of drawing sheet's `Issue Date` field.
| `CURRENT_DATE`
  | Today's date, in ISO format.
| `REVISION`
  | Contents of drawing sheet's `Revision` field.
| `TITLE`
  | Contents of drawing sheet's `Title` field.
| `COMPANY`
  | Contents of drawing sheet's `Company` field.
| `COMMENT1` - `COMMENT9`
  | Contents of drawing sheet's `Comment<n>` field.
| `<variablename>`
  | Contents of <<schematic-setup-text-variables,project text variable>>
  `<variablename>`.
| `<fieldname>`
  | Contents of symbol field, hierarchical sheet field, or label field
    `<fieldname>`. Fields can only be accessed from within of their parent
    object, so symbol fields can be accessed from other text or fields within
    the symbol, and hierarchical sheet fields can be accessed within the sheet
    or in other sheet fields of the sheet.
    
    Both built-in and user-defined fields are available. Built-in fields use all
    uppercase letters: for example, to access the value of `U1`, use
    `${U1:VALUE}`.

    Built-in symbol fields are `DATASHEET`, `DNP`, `EXCLUDE_FROM_BOARD`,
    `EXCLUDE_FROM_BOM`, `FOOTPRINT`, `FOOTPRINT_LIBRARY`, `FOOTPRINT_NAME`,
    `REFERENCE`, `SYMBOL_DESCRIPTION`, `SYMBOL_KEYWORDS`, `SYMBOL_LIBRARY`,
    `SYMBOL_NAME`, `UNIT`, `VALUE`.

    Built-in sheet fields are `SHEETNAME` and `SHEETFILE`.

    Built-in label fields are `CONNECTION_TYPE`, `SHORT_NET_NAME`, `NET_NAME`,
    `NET_CLASS`, and `INTERSHEET_REFS` (global labels only).

| `<refdes>:<fieldname>`
  | Contents of field `<fieldname>` in symbol `<refdes>`.
    
    Both built-in and user-defined fields are available. Built-in fields use all
    uppercase letters: for example, to access the value of `U1`, use
    `${U1:VALUE}`.
    
    Built-in symbol fields are `DATASHEET`, `DNP`, `EXCLUDE_FROM_BOARD`,
    `EXCLUDE_FROM_BOM`, `FOOTPRINT`, `FOOTPRINT_LIBRARY`, `FOOTPRINT_NAME`,
    `REFERENCE`, `SYMBOL_DESCRIPTION`, `SYMBOL_KEYWORDS`, `SYMBOL_LIBRARY`,
    `SYMBOL_NAME`, `UNIT`, `VALUE`.

|====

////
[[preferences-common]]
===== Common Preferences
NOTE: This section of the KiCad documentation has not yet been written.  We
      appreciate your patience as our small team of volunteer documentation
      writers work to update and expand the documentation.

image::images/en/options_common.png[alt="Common settings",scaledwidth="70%"]

[[preferences-mouse]]
===== Mouse and Touchpad
[width="100%",cols="40%,60%",]
|============
|Center and warp cursor on zoom | If checked, the pointed location is warped
to the screen center when zooming in/out.

|Use touchpad to pan |When enabled, view is panned using scroll wheels (or
touchpad gestures) and to zoom one needs to hold kbd:[Ctrl]. Otherwise scroll
wheels zoom in/out and kbd:[Ctrl]/kbd:[Shift] are the panning modifiers.

|Pan while moving object |If checked, automatically pans the window
if the cursor leaves the window during drawing or moving.
|============

[[preferences-controls]]
===== Hotkeys

Redefine hotkeys.

image::images/en/options_hotkeys.png[alt="Hotkeys settings",scaledwidth="70%"]

Select a new hotkey by double clicking an
action or right click on an action to show a popup menu:

[width="100%",cols="40%,60%",]
|============
|Edit | Define a new hotkey for the action (same as double click).
|Undo Changes | Reverts the recent hotkey changes for the action.
|Clear Assigned Hotkey |
|Restore Default | Sets the action hotkey to its default value.
|============

[[preferences-display]]
===== Display Options

image::images/en/options_display.png[alt="Display options",scaledwidth="70%"]

[width="100%",cols="40%,60%",]
|=======================================================================
|Grid Size| Grid size selection.

It is *recommended* to work with normal grid (0.050 inches or 1,27 mm). Smaller
grids are used for component building.

|Bus thickness |Pen size used to draw buses.

|Line thickness |Pen size used to draw objects that do not have a
specified pen size.

|Part ID notation |Style of suffix that is used to denote symbol units (U1A,
U1.A, U1-1, etc.)

|Icon scale| Adjust toolbar icons size.

|Show Grid | Grid visibility setting.

|Restrict buses and wires to H and V orientation| If checked, buses and
wires are drawn only with vertical or horizontal lines.
Otherwise buses and wires can be placed at any orientation.

|Show hidden pins: |Display invisible (or __hidden__) pins, typically
power pins.

|Show page limits |If checked, shows the page boundaries on screen.

|Footprint previews in symbol chooser| Displays a footprint preview frame and
footprint selector when placing a new symbol.

*Note:* it may cause problems or delays, use at your own risk.
|=======================================================================

[[preferences-editing]]
===== Editing Options

image::images/en/options_editing.png[alt="Editing settings",scaledwidth="70%"]

[width="100%",cols="40%,60%",]
|=======================================================================
|Measurement units |Select the display and the cursor coordinate units
(inches or millimeters).

|Horizontal pitch of repeated items |
Increment on X axis during element duplication (default: 0)
(after placing an item like a symbol, label or wire,
a duplication is made by the kbd:[Insert] key)

|Vertical pitch of repeated items| Increment on Y axis during
element duplication (default: 0.100 inches or 2,54 mm).

|Increment of repeated labels |Increment of label value during duplication of texts ending
in a number, such as bus members (usual value 1 or -1).

|Default text size |Text size used when creating new text items or labels.

|Auto-save time interval |Time in minutes between saving backups.

|Automatically place symbol fields | If checked, symbol fields (e.g. value and
reference) in newly placed symbols might be moved to avoid collisions with
other items.

|Allow field autoplace to change justification | Extension of 'Automatically
place symbol fields' option. Enable text justification adjustment for symbol fields when placing
a new part.

|Always align autoplaced fields to the 50 mil grid |Extension of 'Automatically
place symbol fields' option. If checked, fields are autoplaced using 50 mils
grid, otherwise they are placed freely.
|=======================================================================

[[preferences-colors]]
===== Colors

Color scheme for various graphic elements. Click on any of the color swatches to
select a new color for a particular element.

image::images/en/options_color.png[alt="Color settings",scaledwidth="95%"]

[[preferences-default-fields]]
===== Default Fields

Define additional custom fields and corresponding values that will appear in
newly placed symbols.

image::images/en/options_default_fields.png[alt="Default Fields settings",scaledwidth="70%"]
////

[[database-libraries]]
=== Database Libraries

A database library is a type of KiCad symbol library that holds data about parts in an external
SQL database.  Database libraries do not contain any symbol or footprint definitions by themselves.
Instead, they **reference** symbols and footprints found in other KiCad libraries. Each database
library entry maps a KiCad symbol (from another library) to a set of properties (fields) and
usually a KiCad footprint (from a footprint library).

Using database libraries allows you to create fully-defined parts (sometimes called *atomic parts*)
out of KiCad symbols and footprints without needing to store all the part properties in a symbol
library.  The external database can be linked to third-party tools for managing part data and
lifecycles.  Database library workflows are generally more complex than the standard KiCad library
workflows, and so this type of library is typically only used in situations where it makes managing
a large library of fully-defined parts more efficient (such as in organization or team settings).

KiCad does not provide a GUI for editing a SQL database or defining a database library.  It is up
to the user to find the most appropriate workflow and toolchain for creating and updating the
database itself.  Some users may want to directly edit the database through a third-party database
client, and some may use other third-party software such as a part lifecycle management (PLM) tool
to create and edit data.

In a database library, there are one or more **tables** that generally represent a single type of
part (such as Resistors or Capacitors).  Each table can have an independent schema, meaning that
different types of parts can have different properties that are translated into symbol fields in
KiCad.  Each table must have a unique ID column which is used as the identifier for a symbol placed
from that table.  This unique ID will typically be a part number (either a manufacturer's part
number, or an internal organization part number).  Each table must also have a column that contains
a mapping to a KiCad symbol, in the form `LibraryNickname:SymbolName`.  The `LibraryNickname` must
match a symbol library that is present in the KiCad library tables.  Tables may also contain a
column containing a KiCad footprint, in the form `LibraryNickname:FootprintName`.  If this column
is present, symbols placed from the table will include a footprint mapping.

Tables may also contain arbitrary additional columns that may optionally be mapped to symbol fields
in KiCad.  The KiCad database library configuration file controls how these fields should be named,
whether or not to make the fields visible, and whether or not to include the fields in the data
displayed in the Symbol Chooser.

==== Database Library Configuration Files

To create a database library, you must create a configuration file that contains the necessary
information for KiCad to connect to your database and retrieve data from tables.  Copy the template
below into a new file and save it with a `kicad_dbl` extension.  You can then add this file to your
global symbol library table using the Configure Symbol Libraries dialog.

[code,json]
----
{
    "meta": {
        "version": 0
    },
    "name": "My Database Library",
    "description": "A database of components",
    "source": {
        "type": "odbc",
        "dsn": "",
        "username": "",
        "password": "",
        "timeout_seconds": 2,
        "connection_string": ""
    },
    "libraries": [
        {
            "name": "Resistors",
            "table": "Resistors",
            "key": "Part ID",
            "symbols": "Symbols",
            "footprints": "Footprints",
            "fields": [
                {
                    "column": "MPN",
                    "name": "MPN",
                    "visible_on_add": false,
                    "visible_in_chooser": true,
                    "show_name": true,
                    "inherit_properties": true
                },
                {
                    "column": "Value",
                    "name": "Value",
                    "visible_on_add": true,
                    "visible_in_chooser": true,
                    "show_name": false
                }
            ],
            "properties": {
                "description": "Description",
                "footprint_filters": "Footprint Filters",
                "keywords": "Keywords",
                "exclude_from_bom": "No BOM",
                "exclude_from_board": "Schematic Only"
            }
        }
    ]
}
----

===== Configuring the source

KiCad currently only supports ODBC connections to SQL databases.  You can either connect with a
DSN or a connection string.  If a DSN name is supplied, the optional `username` and `password`
fields will be used to connect to the DSN.  If a connection string is supplied, the `dsn`,
`username`, and `password` fields are ignored.  The connection string will be passed directly to
the ODBC driver, so you can include any parameters your ODBC driver supports.

KiCad does not recommend or endorse any particular ODBC driver or database server, but has been
tested to work with Sqlite, MySQL, MariaDB, and PostgreSQL.

NOTE: Flatpak users: Due to Flatpak sandboxing, the only way to connect to database servers
running on your local machine is via TCP/IP.  Using the default UNIX domain socket connections
for i.e. MySQL, MariaDB, or PostgreSQL is not possible.  First, make sure that your database
server allows TCP/IP connections, and then add the required `Port` parameter to your connection
string. For example, add `Port=3306;` for the default TCP port of MySQL/MariaDB, or
`Server=localhost;Port=5432;` to force PostgreSQL to use a TCP connection to the local server.

===== Configuring libraries

Each database library can contain "sub-libraries" mapped to a single database table.  The
`libraries` entry in the configuration file contains a list of objects that each define a single
library.  The following settings must exist for each library:

`name`: The name of the table that will be shown in the KiCad UI.

`table`: The name of the table in the database.

`key`: The column name containing a unique key that will be used to identify parts from the table.

`symbols`: The column name containing KiCad symbol references.

`footprints`: The column name containing KiCad footprint references.

`fields`:  A list of field definitions.  Each field defined here will be added to the symbol when
it is placed on the schematic.  If a field with a matching name is already defined in the source
symbol, the value from the database table will override whatever value was defined in the source
symbol. Each field definition may contain:

`column`: The name of the database table column that should be mapped to a field.

`name`: The name of the KiCad field to populate from the database.

`visible_on_add`: If `true`, this field will be visible in the schematic when a symbol is added. If
this setting is not specified, it will default to `false`.

`visible_in_chooser`: If `true`, this field will be shown in the Symbol Chooser as a column. If
this setting is not specified, it will default to `false`.

`show_name`: If `true`, the field's name will be shown in addition to its value in the schematic.
If this setting is not specified, it will default to `false`.

`inherit_properties`: If `true`, and a field with the given `name` already exists on the source
symbol, only the field contents will be updated from the database, and the other properties
(`visible_on_add`, `show_name`, etc) will be kept as they were set in the source symbol.  If the
given field name does not exist in the source symbol, this setting is ignored.  If this setting is
not specified, it will default to `false`.

`properties`: A map of symbol properties to database columns.  All properties are optional; any
that are not specified in the database library configuration will be inherited from the values set
for the source symbol.  The following properties are supported:

`description`: The symbol's Description property.

`footprint_filters`: Reserved for future expansion.

`keywords`: The symbol's Keywords property.

`exclude_from_bom`: The symbol's "Exclude from Bill of Materials" setting.  The column named here
must be a numeric type, and will be taken as a boolean (0 for false, 1 for true).

`exclude_from_board`: The symbol's "Exclude from PCB" setting. The column named here must be a
numeric type, and will be taken as a boolean (0 for false, 1 for true).

Database columns may be mapped to custom (user-defined) fields, or to certain built-in KiCad
fields, including `Value` and `Datasheet`.

==== Using database libraries

After creating your configuration file and adding it to your symbol library table, you can place
parts from the database tables using the Symbol Chooser.  Parts placed from a database library can
be updated using the Update Symbols from Library function, which will update any fields that were
changed in the database as well as updating the underlying symbol if it was changed in the source
library.

Note that any source library referenced by a database table must also be present in the symbol
library table for the database library to function.  If you want to use a library only as a source
of symbols for a database library, you can hide it from the Symbol Chooser by clearing the
"Visible" checkbox in the Manage Symbol Libraries dialog.


[[custom-netlist-and-bom-formats]]
=== Custom Netlist and BOM Formats

KiCad can output netlists and BOMs in various formats, and users can define new
formats if desired.

The process of exporting a netlist is described in the
<<netlist-export,netlist export section>>. BOM output is described in the
<<bom-export,BOM export section>>.

The following section describes how to create an exporter for a new output
format.

[[adding-new-netlist-generators]]
==== Adding new netlist generators

New netlist generators are added to the **Export Netlist** dialog by clicking
the **Add Generator...** button.

image::images/eeschema_netlist_dialog_add_plugin.png[alt="Custom Netlist Generator",scaledwidth="40%"]

New generators require a name and a command. The name is shown in the tab label,
and the command is run whenever the **Export Netlist** button is clicked.

When the netlist is generated, KiCad creates an intermediate XML file which
contains all of the netlist information from the schematic. The generator
command is then run in order to transform the intermediate netlist into the
desired netlist format.

The netlist command must be set up properly so that the netlist generator script
takes the intermediate netlist file as input and outputs the desired netlist
file. The exact netlist command will depend on the generator script used. The
<<generator-command-line-format,command format>> is described below.

Python and XSLT are commonly used tools to create custom netlist generators.

==== Adding a new BOM generator

KiCad also uses the intermediate netlist file to generate BOMs with the
<<bom-export,Generate BOM tool>>.

image::images/en/dialog_bom.png[alt="BOM dialog",scaledwidth="60%"]

Additional scripts can be added to the list of BOM generator scripts by clicking
the image:images/icons/small_plus_16.png[Plus icon] button. Scripts can be
removed by clicking the image:images/icons/small_trash_16.png[Delete icon]
button. The image:images/icons/small_edit_16.png[Edit icon] button opens the
selected script in a text editor.

Generator scripts written in Python and XSLT can contain a header comment that
describes the generator's functionality and usage. This header comment is
displayed in the BOM dialog as the description for each generator. The header
comment must contain the string `@package`. Everything following that string
until the end of the comment is used as the description for the generator.

KiCad automatically fills the command line field when a new generator script is
added, but the command line might need to be adjusted by hand depending on the
generator script. KiCad attempts to automatically determine the output file
extension from the example command line in the generator script's header.

[[generator-command-line-format]]
==== Generator command line format

The command line for a netlist or BOM exporter defines the command that KiCad
will run to generate the selected output file.

For a netlist exporter using `xsltproc`, an example is:

`xsltproc -o %O.net /usr/share/kicad/plugins/netlist_form_pads-pcb.asc.xsl %I`

For a BOM exporter using Python, an example is:

`/usr/bin/python3 /usr/share/kicad/plugins/bom_csv_grouped_by_value.py "%I" "%O.csv"`

NOTE: It is recommended to surround arguments in the command line with quotes
(`"`) in case they contain spaces or other special characters.

Some character sequences like `%I` and `%O` have a special meaning in the
command line, because KiCad replaces them with a filename or path before
executing the command.

[options="header",width="100%",cols="10%,30%,60%"]
|===
|Parameter |Replaced with... |Description
|`%I` 
    |`<project path>/<project name>.xml`
    |Absolute path and filename of the intermediate netlist file, which is the input
    to the BOM or netlist generator plugin
|`%O`
    |`<project path>/<project name>`
    |Absolute path and filename of the output BOM or netlist file (without file
    extension). An appropriate file extension may need to be specified after the
    `%O` sequence.
|`%B`
    |`<project name>`
    |Base filename of the output BOM or netlist file (without path or file
    extension). An appropriate file extension may need to be specified after the
    `%B` sequence.
|`%P`
    |`<project path>`
    |Absolute path of the project directory, without trailing slash.
|===

[[intermediate-netlist-file]]
==== Intermediate Netlist File

When exporting BOM files and netlists, KiCad creates an intermediate netlist
file and then runs a separate tool which post-processes the intermediate netlist
into the desired netlist or BOM format.

The intermediate netlist uses XML syntax. It contains a large amount of data
about the design. Depending on the output (BOM or netlist), different subsets of
the complete intermediate netlist file will be included in the final output
file.

The structure of the intermediate netlist file is described in detail
<<intermediate-netlist-structure,below>>.

Because the conversion from intermediate netlist file to output netlist or BOM
is a text-to-text transformation, the post-processing filter can be written
using Python, XSLT, or any other tool capable of taking XML as input.

NOTE: XSLT is not recommended for new netlist or BOM exporters; Python or
another tool should be used instead. Beginning with KiCad 7, `xsltproc` is no
longer installed with KiCad, although it can be installed separately.
Nevertheless, several examples of netlist exporters using XSLT are included
below.

[[intermediate-netlist-structure]]
==== Intermediate Netlist structure

This sample gives an idea of the netlist file format.

[source,xml]
----
<?xml version="1.0" encoding="utf-8"?>
<export version="D">
  <design>
    <source>F:\kicad_aux\netlist_test\netlist_test.sch</source>
    <date>29/08/2010 21:07:51</date>
    <tool>eeschema (2010-08-28 BZR 2458)-unstable</tool>
  </design>
  <components>
    <comp ref="P1">
      <value>CONN_4</value>
      <libsource lib="conn" part="CONN_4"/>
      <sheetpath names="/" tstamps="/"/>
      <tstamps>4C6E2141</tstamps>
    </comp>
    <comp ref="U2">
      <value>74LS74</value>
      <libsource lib="74xx" part="74LS74"/>
      <sheetpath names="/" tstamps="/"/>
      <tstamps>4C6E20BA</tstamps>
    </comp>
    <comp ref="U1">
      <value>74LS04</value>
      <libsource lib="74xx" part="74LS04"/>
      <sheetpath names="/" tstamps="/"/>
      <tstamps>4C6E20A6</tstamps>
    </comp>
    <comp ref="C1">
      <value>CP</value>
      <libsource lib="device" part="CP"/>
      <sheetpath names="/" tstamps="/"/>
      <tstamps>4C6E2094</tstamps>
    <comp ref="R1">
      <value>R</value>
      <libsource lib="device" part="R"/>
      <sheetpath names="/" tstamps="/"/>
      <tstamps>4C6E208A</tstamps>
    </comp>
  </components>
  <libparts/>
  <libraries/>
  <nets>
    <net code="1" name="GND">
      <node ref="U1" pin="7"/>
      <node ref="C1" pin="2"/>
      <node ref="U2" pin="7"/>
      <node ref="P1" pin="4"/>
    </net>
    <net code="2" name="VCC">
      <node ref="R1" pin="1"/>
      <node ref="U1" pin="14"/>
      <node ref="U2" pin="4"/>
      <node ref="U2" pin="1"/>
      <node ref="U2" pin="14"/>
      <node ref="P1" pin="1"/>
    </net>
    <net code="3" name="">
      <node ref="U2" pin="6"/>
    </net>
    <net code="4" name="">
      <node ref="U1" pin="2"/>
      <node ref="U2" pin="3"/>
    </net>
    <net code="5" name="/SIG_OUT">
      <node ref="P1" pin="2"/>
      <node ref="U2" pin="5"/>
      <node ref="U2" pin="2"/>
    </net>
    <net code="6" name="/CLOCK_IN">
      <node ref="R1" pin="2"/>
      <node ref="C1" pin="1"/>
      <node ref="U1" pin="1"/>
      <node ref="P1" pin="3"/>
    </net>
  </nets>
</export>
----

[[general-netlist-file-structure]]
===== General netlist file structure

The intermediate Netlist accounts for five sections.

* The header section.
* The components section.
* The lib parts section.
* The libraries section.
* The nets section.

The file content has the delimiter `<export>`

[source,xml]
----
<export version="D">
...
</export>
----

[[the-header-section]]
===== The header section

The header has the delimiter `<design>`

[source,xml]
----
<design>
<source>F:\kicad_aux\netlist_test\netlist_test.sch</source>
<date>21/08/2010 08:12:08</date>
<tool>eeschema (2010-08-09 BZR 2439)-unstable</tool>
</design>
----

This section can be considered a comment section.

[[the-components-section]]
===== The components section

The component section has the delimiter `<components>`

[source,xml]
----
<components>
<comp ref="P1">
<value>CONN_4</value>
<libsource lib="conn" part="CONN_4"/>
<sheetpath names="/" tstamps="/"/>
<tstamps>4C6E2141</tstamps>
</comp>
</components>
----

This section contains the list of components in your schematic. Each
component is described like this:

[source,xml]
----
<comp ref="P1">
<value>CONN_4</value>
<libsource lib="conn" part="CONN_4"/>
<sheetpath names="/" tstamps="/"/>
<tstamps>4C6E2141</tstamps>
</comp>
----

[width="100%",cols="37%,63%",]
|=======================================================================
|Element name |Element description

|`libsource` |name of the lib where this component was found.
|`part` |component name inside this library.
|`sheetpath` |path of the sheet inside the hierarchy: identify the sheet
within the full schematic hierarchy.
|`tstamps` |timestamp of the component.
|=======================================================================

[[note-about-time-stamps-for-components]]
====== Note about time stamps for components

To identify a component in a netlist and therefore on a board, the
timestamp reference is used as unique for each component. However KiCad
provides an auxiliary way to identify a component which is the
corresponding footprint on the board. This allows the re-annotation of
components in a schematic project and does not lose the link between
the component and its footprint.

A time stamp is an unique identifier for each component or sheet in a
schematic project. However, in complex hierarchies, the same sheet is
used more than once, so this sheet contains components having the same
time stamp.

A given sheet inside a complex hierarchy has an unique identifier: its
sheetpath. A given component (inside a complex hierarchy) has a unique
identifier: the sheetpath and its timestamp.

[[the-libparts-section]]
===== The libparts section

The libparts section has the delimiter `<libparts>`, and the content of
this section is defined in the schematic libraries.

[source,xml]
----
<libparts>
<libpart lib="device" part="CP">
  <description>Condensateur polarise</description>
  <footprints>
    <fp>CP*</fp>
    <fp>SM*</fp>
  </footprints>
  <fields>
    <field name="Reference">C</field>
    <field name="Valeur">CP</field>
  </fields>
  <pins>
    <pin num="1" name="1" type="passive"/>
    <pin num="2" name="2" type="passive"/>
  </pins>
</libpart>
</libparts>
----

|=======================================================================
|Element name |Element description

|`<footprints>` | The symbol's footprint filters. Each footprint filter is in a separate `<fp>` tag.
|`<fields>` |The symbol's fields. Each field's name and value is given in a separate `<field name="fieldname">...</field> tag.
|`<pins>` |The symbol's pins. Each pin is given in a separate `<pin num="pinnum" type="pintype"/>` tag. Possible pintypes are described below.
|=======================================================================

Possible electrical pin types are:

[width="94%",cols="25%,75%",]
|================================================================
|Pintype |Description

|Input |Usual input pin
|Output |Usual output
|Bidirectional |Input or Output
|Tri-state |Bus input/output
|Passive |Usual ends of passive components
|Unspecified |Unknown electrical type
|Power input |Power input of a component
|Power output |Power output like a regulator output
|Open collector |Open collector often found in analog comparators
|Open emitter |Open emitter sometimes found in logic
|Not connected |Must be left open in schematic
|================================================================

[[the-libraries-section]]
===== The libraries section

The libraries section has the delimiter `<libraries>`. This section
contains the list of schematic libraries used in the project.

[source,xml]
----
<libraries>
  <library logical="device">
    <uri>F:\kicad\share\library\device.lib</uri>
  </library>
  <library logical="conn">
    <uri>F:\kicad\share\library\conn.lib</uri>
  </library>
</libraries>
----

[[the-nets-section]]
===== The nets section

The nets section has the delimiter `<nets>`. This section describes the
connectivity of the schematic by listing all nets and the pins connected to
each net.

[source,xml]
----
<nets>
  <net code="1" name="GND">
    <node ref="U1" pin="7"/>
    <node ref="C1" pin="2"/>
    <node ref="U2" pin="7"/>
    <node ref="P1" pin="4"/>
  </net>
  <net code="2" name="VCC">
    <node ref="R1" pin="1"/>
    <node ref="U1" pin="14"/>
    <node ref="U2" pin="4"/>
    <node ref="U2" pin="1"/>
    <node ref="U2" pin="14"/>
    <node ref="P1" pin="1"/>
  </net>
</nets>
----

A possible net contains the following.


[source,xml]
----
<net code="1" name="GND">
  <node ref="U1" pin="7"/>
  <node ref="C1" pin="2"/>
  <node ref="U2" pin="7"/>
  <node ref="P1" pin="4"/>
</net>
----

[width="77%",cols="20%,80%",]
|================================================
|Element name | Element Description

|`net code` | an internal identifier for this net
|`name` | the net name
|`node` | the pin (identified by `pin`) of a symbol (identified by `ref`) which is connected to the net
|================================================

==== Example netlist exporters

Some example netlist exporters using XSLT are included below.

XSLT itself is an XML language very suitable for XML transformations.
http://xmlsoft.org/XSLT/xsltproc.html[The `xsltproc` program] can be used to
read the Intermediate XML netlist input file, apply a style-sheet to transform
the input, and save the results in an output file. Use of `xsltproc` requires a
style-sheet file using XSLT conventions. The full conversion process is handled
by KiCad, after it is configured once to run `xsltproc` in a specific way.

The document that describes XSL Transformations (XSLT) is available
here: http://www.w3.org/TR/xslt

NOTE: When writing a new netlist exporter, consider using Python or another tool rather than XSLT.

===== PADS netlist example using XSLT

The following example shows how to create an exporter for the PADS netlist
format using `xlstproc`.

The PADS netlist format is comprised of two sections:

    * A list of footprints
    * A list of nets, together with the pads connected to each net.

Below is an XSL style-sheet which converts the intermediate netlist file to the
PADS netlist format.

[source,xml]
----
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--XSL style sheet to Eeschema Generic Netlist Format to PADS netlist format
    Copyright (C) 2010, SoftPLC Corporation.
    GPL v2.

    How to use:
        https://lists.launchpad.net/kicad-developers/msg05157.html
-->

<!DOCTYPE xsl:stylesheet [
  <!ENTITY nl  "&#xd;&#xa;"> <!--new line CR, LF -->
]>

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="text" omit-xml-declaration="yes" indent="no"/>

<xsl:template match="/export">
    <xsl:text>*PADS-PCB*&nl;*PART*&nl;</xsl:text>
    <xsl:apply-templates select="components/comp"/>
    <xsl:text>&nl;*NET*&nl;</xsl:text>
    <xsl:apply-templates select="nets/net"/>
    <xsl:text>*END*&nl;</xsl:text>
</xsl:template>

<!-- for each component -->
<xsl:template match="comp">
    <xsl:text> </xsl:text>
    <xsl:value-of select="@ref"/>
    <xsl:text> </xsl:text>
    <xsl:choose>
        <xsl:when test = "footprint != '' ">
            <xsl:apply-templates select="footprint"/>
        </xsl:when>
        <xsl:otherwise>
            <xsl:text>unknown</xsl:text>
        </xsl:otherwise>
    </xsl:choose>
    <xsl:text>&nl;</xsl:text>
</xsl:template>

<!-- for each net -->
<xsl:template match="net">
    <!-- nets are output only if there is more than one pin in net -->
    <xsl:if test="count(node)>1">
        <xsl:text>*SIGNAL* </xsl:text>
        <xsl:choose>
            <xsl:when test = "@name != '' ">
                <xsl:value-of select="@name"/>
            </xsl:when>
            <xsl:otherwise>
                <xsl:text>N-</xsl:text>
                <xsl:value-of select="@code"/>
            </xsl:otherwise>
        </xsl:choose>
        <xsl:text>&nl;</xsl:text>
        <xsl:apply-templates select="node"/>
    </xsl:if>
</xsl:template>

<!-- for each node -->
<xsl:template match="node">
    <xsl:text> </xsl:text>
    <xsl:value-of select="@ref"/>
    <xsl:text>.</xsl:text>
    <xsl:value-of select="@pin"/>
    <xsl:text>&nl;</xsl:text>
</xsl:template>

</xsl:stylesheet>
----

And here is the PADS netlist output file after running `xsltproc`:

----
*PADS-PCB*
*PART*
P1 unknown
U2 unknown
U1 unknown
C1 unknown
R1 unknown
*NET*
*SIGNAL* GND
U1.7
C1.2
U2.7
P1.4
*SIGNAL* VCC
R1.1
U1.14
U2.4
U2.1
U2.14
P1.1
*SIGNAL* N-4
U1.2
U2.3
*SIGNAL* /SIG_OUT
P1.2
U2.5
U2.2
*SIGNAL* /CLOCK_IN
R1.2
C1.1
U1.1
P1.3

*END*
----

The command line to make this conversion is:

`kicad\\bin\\xsltproc.exe -o test.net kicad\\bin\\plugins\\netlist_form_pads-pcb.xsl test.tmp`

===== Cadstar netlist example using XSLT

The following example shows how to create an exporter for the Cadstar netlist
format using `xlstproc`.

The Cadstar format is comprised of two sections:

    * The footprint list
    * The Nets list: grouping pads references by nets

Below is an XSL style-sheet which converts the intermediate netlist file to the
Cadstar netlist format.

[source,xml]
----
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--XSL style sheet to Eeschema Generic Netlist Format to CADSTAR netlist format
    Copyright (C) 2010, Jean-Pierre Charras.
    Copyright (C) 2010, SoftPLC Corporation.
    GPL v2. -->

<!DOCTYPE xsl:stylesheet [
  <!ENTITY nl  "&#xd;&#xa;"> <!--new line CR, LF -->
]>

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="text" omit-xml-declaration="yes" indent="no"/>

<!-- Netlist header -->
<xsl:template match="/export">
    <xsl:text>.HEA&nl;</xsl:text>
    <xsl:apply-templates select="design/date"/>  <!-- Generate line .TIM <time> -->
    <xsl:apply-templates select="design/tool"/>  <!-- Generate line .APP <eeschema version> -->
    <xsl:apply-templates select="components/comp"/>  <!-- Generate list of components -->
    <xsl:text>&nl;&nl;</xsl:text>
    <xsl:apply-templates select="nets/net"/>          <!-- Generate list of nets and connections -->
    <xsl:text>&nl;.END&nl;</xsl:text>
</xsl:template>

 <!-- Generate line .TIM 20/08/2010 10:45:33 -->
<xsl:template match="tool">
    <xsl:text>.APP "</xsl:text>
    <xsl:apply-templates/>
    <xsl:text>"&nl;</xsl:text>
</xsl:template>

 <!-- Generate line .APP "eeschema (2010-08-17 BZR 2450)-unstable" -->
<xsl:template match="date">
    <xsl:text>.TIM </xsl:text>
    <xsl:apply-templates/>
    <xsl:text>&nl;</xsl:text>
</xsl:template>

<!-- for each component -->
<xsl:template match="comp">
    <xsl:text>.ADD_COM </xsl:text>
    <xsl:value-of select="@ref"/>
    <xsl:text> </xsl:text>
    <xsl:choose>
        <xsl:when test = "value != '' ">
            <xsl:text>"</xsl:text> <xsl:apply-templates select="value"/> <xsl:text>"</xsl:text>
        </xsl:when>
        <xsl:otherwise>
            <xsl:text>""</xsl:text>
        </xsl:otherwise>
    </xsl:choose>
    <xsl:text>&nl;</xsl:text>
</xsl:template>

<!-- for each net -->
<xsl:template match="net">
    <!-- nets are output only if there is more than one pin in net -->
    <xsl:if test="count(node)>1">
    <xsl:variable name="netname">
        <xsl:text>"</xsl:text>
        <xsl:choose>
            <xsl:when test = "@name != '' ">
                <xsl:value-of select="@name"/>
            </xsl:when>
            <xsl:otherwise>
                <xsl:text>N-</xsl:text>
                <xsl:value-of select="@code"/>
        </xsl:otherwise>
        </xsl:choose>
        <xsl:text>"&nl;</xsl:text>
        </xsl:variable>
        <xsl:apply-templates select="node" mode="first"/>
        <xsl:value-of select="$netname"/>
        <xsl:apply-templates select="node" mode="others"/>
    </xsl:if>
</xsl:template>

<!-- for each node -->
<xsl:template match="node" mode="first">
    <xsl:if test="position()=1">
       <xsl:text>.ADD_TER </xsl:text>
    <xsl:value-of select="@ref"/>
    <xsl:text>.</xsl:text>
    <xsl:value-of select="@pin"/>
    <xsl:text> </xsl:text>
    </xsl:if>
</xsl:template>

<xsl:template match="node" mode="others">
    <xsl:choose>
        <xsl:when test='position()=1'>
        </xsl:when>
        <xsl:when test='position()=2'>
           <xsl:text>.TER     </xsl:text>
        </xsl:when>
        <xsl:otherwise>
           <xsl:text>         </xsl:text>
        </xsl:otherwise>
    </xsl:choose>
    <xsl:if test="position()>1">
        <xsl:value-of select="@ref"/>
        <xsl:text>.</xsl:text>
        <xsl:value-of select="@pin"/>
        <xsl:text>&nl;</xsl:text>
    </xsl:if>
</xsl:template>

</xsl:stylesheet>
----

Here is the Cadstar output file.

----
.HEA
.TIM 21/08/2010 08:12:08
.APP "eeschema (2010-08-09 BZR 2439)-unstable"
.ADD_COM P1 "CONN_4"
.ADD_COM U2 "74LS74"
.ADD_COM U1 "74LS04"
.ADD_COM C1 "CP"
.ADD_COM R1 "R"


.ADD_TER U1.7 "GND"
.TER     C1.2
         U2.7
         P1.4
.ADD_TER R1.1 "VCC"
.TER     U1.14
         U2.4
         U2.1
         U2.14
         P1.1
.ADD_TER U1.2 "N-4"
.TER     U2.3
.ADD_TER P1.2 "/SIG_OUT"
.TER     U2.5
         U2.2
.ADD_TER R1.2 "/CLOCK_IN"
.TER     C1.1
         U1.1
         P1.3

.END
----

===== OrcadPCB2 netlist example using XSLT

This format has only one section which is the footprint list. Each footprint
includes a list of its pads with reference to a net.

Below is an XSL style-sheet which converts the intermediate netlist file to the
Orcad netlist format.

[source,xml]
----
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--XSL style sheet to Eeschema Generic Netlist Format to CADSTAR netlist format
    Copyright (C) 2010, SoftPLC Corporation.
    GPL v2.

    How to use:
        https://lists.launchpad.net/kicad-developers/msg05157.html
-->

<!DOCTYPE xsl:stylesheet [
  <!ENTITY nl  "&#xd;&#xa;"> <!--new line CR, LF -->
]>

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="text" omit-xml-declaration="yes" indent="no"/>

<!--
    Netlist header
    Creates the entire netlist
    (can be seen as equivalent to main function in C
-->
<xsl:template match="/export">
    <xsl:text>( { Eeschema Netlist Version 1.1  </xsl:text>
    <!-- Generate line .TIM <time> -->
<xsl:apply-templates select="design/date"/>
<!-- Generate line eeschema version ... -->
<xsl:apply-templates select="design/tool"/>
<xsl:text>}&nl;</xsl:text>

<!-- Generate the list of components -->
<xsl:apply-templates select="components/comp"/>  <!-- Generate list of components -->

<!-- end of file -->
<xsl:text>)&nl;*&nl;</xsl:text>
</xsl:template>

<!--
    Generate id in header like "eeschema (2010-08-17 BZR 2450)-unstable"
-->
<xsl:template match="tool">
    <xsl:apply-templates/>
</xsl:template>

<!--
    Generate date in header like "20/08/2010 10:45:33"
-->
<xsl:template match="date">
    <xsl:apply-templates/>
    <xsl:text>&nl;</xsl:text>
</xsl:template>

<!--
    This template read each component
    (path = /export/components/comp)
    creates lines:
     ( 3EBF7DBD $noname U1 74LS125
      ... pin list ...
      )
    and calls "create_pin_list" template to build the pin list
-->
<xsl:template match="comp">
    <xsl:text> ( </xsl:text>
    <xsl:choose>
        <xsl:when test = "tstamp != '' ">
            <xsl:apply-templates select="tstamp"/>
        </xsl:when>
        <xsl:otherwise>
            <xsl:text>00000000</xsl:text>
        </xsl:otherwise>
    </xsl:choose>
    <xsl:text> </xsl:text>
    <xsl:choose>
        <xsl:when test = "footprint != '' ">
            <xsl:apply-templates select="footprint"/>
        </xsl:when>
        <xsl:otherwise>
            <xsl:text>$noname</xsl:text>
        </xsl:otherwise>
    </xsl:choose>
    <xsl:text> </xsl:text>
    <xsl:value-of select="@ref"/>
    <xsl:text> </xsl:text>
    <xsl:choose>
        <xsl:when test = "value != '' ">
            <xsl:apply-templates select="value"/>
        </xsl:when>
        <xsl:otherwise>
            <xsl:text>"~"</xsl:text>
        </xsl:otherwise>
    </xsl:choose>
    <xsl:text>&nl;</xsl:text>
    <xsl:call-template name="Search_pin_list" >
        <xsl:with-param name="cmplib_id" select="libsource/@part"/>
        <xsl:with-param name="cmp_ref" select="@ref"/>
    </xsl:call-template>
    <xsl:text> )&nl;</xsl:text>
</xsl:template>

<!--
    This template search for a given lib component description in list
    lib component descriptions are in /export/libparts,
    and each description start at ./libpart
    We search here for the list of pins of the given component
    This template has 2 parameters:
        "cmplib_id" (reference in libparts)
        "cmp_ref"   (schematic reference of the given component)
-->
<xsl:template name="Search_pin_list" >
    <xsl:param name="cmplib_id" select="0" />
    <xsl:param name="cmp_ref" select="0" />
        <xsl:for-each select="/export/libparts/libpart">
            <xsl:if test = "@part = $cmplib_id ">
                <xsl:apply-templates name="build_pin_list" select="pins/pin">
                    <xsl:with-param name="cmp_ref" select="$cmp_ref"/>
                </xsl:apply-templates>
            </xsl:if>
        </xsl:for-each>
</xsl:template>


<!--
    This template writes the pin list of a component
    from the pin list of the library description
    The pin list from library description is something like
          <pins>
            <pin num="1" type="passive"/>
            <pin num="2" type="passive"/>
          </pins>
    Output pin list is ( <pin num> <net name> )
    something like
            ( 1 VCC )
            ( 2 GND )
-->
<xsl:template name="build_pin_list" match="pin">
    <xsl:param name="cmp_ref" select="0" />

    <!-- write pin numner and separator -->
    <xsl:text>  ( </xsl:text>
    <xsl:value-of select="@num"/>
    <xsl:text> </xsl:text>

    <!-- search net name in nets section and write it: -->
    <xsl:variable name="pinNum" select="@num" />
    <xsl:for-each select="/export/nets/net">
        <!-- net name is output only if there is more than one pin in net
             else use "?" as net name, so count items in this net
        -->
        <xsl:variable name="pinCnt" select="count(node)" />
        <xsl:apply-templates name="Search_pin_netname" select="node">
            <xsl:with-param name="cmp_ref" select="$cmp_ref"/>
            <xsl:with-param name="pin_cnt_in_net" select="$pinCnt"/>
            <xsl:with-param name="pin_num"> <xsl:value-of select="$pinNum"/>
            </xsl:with-param>
        </xsl:apply-templates>
    </xsl:for-each>

    <!-- close line -->
    <xsl:text> )&nl;</xsl:text>
</xsl:template>

<!--
    This template writes the pin netname of a given pin of a given component
    from the nets list
    The nets list description is something like
      <nets>
        <net code="1" name="GND">
          <node ref="J1" pin="20"/>
              <node ref="C2" pin="2"/>
        </net>
        <net code="2" name="">
          <node ref="U2" pin="11"/>
        </net>
    </nets>
    This template has 2 parameters:
        "cmp_ref"   (schematic reference of the given component)
        "pin_num"   (pin number)
-->

<xsl:template name="Search_pin_netname" match="node">
    <xsl:param name="cmp_ref" select="0" />
    <xsl:param name="pin_num" select="0" />
    <xsl:param name="pin_cnt_in_net" select="0" />

    <xsl:if test = "@ref = $cmp_ref ">
        <xsl:if test = "@pin = $pin_num">
        <!-- net name is output only if there is more than one pin in net
             else use "?" as net name
        -->
            <xsl:if test = "$pin_cnt_in_net>1">
                <xsl:choose>
                    <!-- if a net has a name, use it,
                        else build a name from its net code
                    -->
                    <xsl:when test = "../@name != '' ">
                        <xsl:value-of select="../@name"/>
                    </xsl:when>
                    <xsl:otherwise>
                        <xsl:text>$N-0</xsl:text><xsl:value-of select="../@code"/>
                    </xsl:otherwise>
                </xsl:choose>
            </xsl:if>
            <xsl:if test = "$pin_cnt_in_net &lt;2">
                <xsl:text>?</xsl:text>
            </xsl:if>
        </xsl:if>
    </xsl:if>

</xsl:template>

</xsl:stylesheet>
----

Here is the OrcadPCB2 output file.

----
( { Eeschema Netlist Version 1.1  29/08/2010 21:07:51
eeschema (2010-08-28 BZR 2458)-unstable}
 ( 4C6E2141 $noname P1 CONN_4
  (  1 VCC )
  (  2 /SIG_OUT )
  (  3 /CLOCK_IN )
  (  4 GND )
 )
 ( 4C6E20BA $noname U2 74LS74
  (  1 VCC )
  (  2 /SIG_OUT )
  (  3 N-04 )
  (  4 VCC )
  (  5 /SIG_OUT )
  (  6 ? )
  (  7 GND )
  (  14 VCC )
 )
 ( 4C6E20A6 $noname U1 74LS04
  (  1 /CLOCK_IN )
  (  2 N-04 )
  (  7 GND )
  (  14 VCC )
 )
 ( 4C6E2094 $noname C1 CP
  (  1 /CLOCK_IN )
  (  2 GND )
 )
 ( 4C6E208A $noname R1 R
  (  1 VCC )
  (  2 /CLOCK_IN )
 )
)
*
----
