:experimental:

[[create-a-netlist]]
== Create a Netlist

=== Overview

A netlist is a file which describes electrical connections between symbol pins.
These connections are referred to as nets. Netlist files contain:

* A list of symbols and their pins.
* A list of connections (nets) between symbol pins.

Many different netlist formats exist. Sometimes the symbols list and the
list of nets are two separate files. This netlist is fundamental in the
use of schematic capture software, because the netlist is the link with
other electronic CAD software, such as:

* PCB layout software.
* Schematic and electrical signal simulators.
* Programmable logic (FPGA, CPLD, etc.) compilers.

KiCad supports several netlist formats:

* KiCad format, which can be imported by the KiCad PCB Editor. However,
  the <<eeschema_schematic_to_pcb.adoc#schematic-to-pcb,"Update PCB from Schematic">>
  tool should be used instead of importing a KiCad netlist into the PCB editor.
* OrCAD PCB2 format, for designing PCBs with OrCAD.
* CADSTAR format, for designing PCBs with CADSTAR.
* Spice format, for use with various external circuit simulators.

NOTE: In KiCad version 5.0 and later, it is not necessary to create a netlist
for transfering a design from the schematic editor to the PCB editor. Instead,
use the
<<eeschema_schematic_to_pcb.adoc#schematic-to-pcb,"Update PCB from Schematic">> tool.

[[netlist-formats]]
=== Netlist formats

Netlists are exported with the Export Netlist dialog (**File**->**Export**->**Netlist...**).

Several netlist formats are available, and are selectable with the tabs at the top of the window. Some netlist formats have options.

Clicking the **Export Netlist** button prompts for a netlist filename and saves the netlist.

[NOTE]
Netlist generation can take up to several minutes for large schematics.

Custom generators can be added by clicking the **Add Generator...** button.
Custom generators are external tools that are called by KiCad, for example
Python scripts or XSLT stylesheets. For more information on custom netlist
generators, see
<<adding-new-netlist-generators,the section on adding custom netlist generators>>.

==== KiCad Netlist Format

image::images/eeschema_netlist_dialog_kicad.png[alt="KiCad netlist export",scaledwidth="70%"]

The KiCad netlist exporter does not have any options.

NOTE: In KiCad version 5.0 and later, it is not necessary to create a netlist
for transfering a design from the schematic editor to the PCB editor. Instead,
use the
<<eeschema_schematic_to_pcb.adoc#schematic-to-pcb,"Update PCB from Schematic">> tool.

==== OrCAD PCB2 Netlist Format

image::images/eeschema_netlist_dialog_orcad.png[alt="OrCAD netlist export",scaledwidth="70%"]

The OrCAD netlist exporter does not have any options.

==== CADSTAR Netlist Format

image::images/eeschema_netlist_dialog_cadstar.png[alt="CADSTAR netlist export",scaledwidth="70%"]

The CADSTAR netlist exporter does not have any options.

==== Spice Netlist Format

image::images/eeschema_netlist_dialog_spice.png[alt="Spice netlist export",scaledwidth="70%"]

The Spice netlist format offers several options.

When the *Reformat passive symbol values* box is checked, passive symbol values
will be adjusted to be compatible with Spice. Specifically:

* `&mu;` and `M` as unit prefixes are replaced with `u` and `Meg`, respectively
* Units are removed (e.g. `4.7k&ohm;` is changed to `4.7k`)
* Values in RKM format are rewritten to be Spice-compatible (e.g. `4u7` is changed to `4.7u`) 

The Spice netlist exporter also provides an easy way to simulate the generated
netlist with an external simulator. This can be useful for running a simulation
without using <<eeschema_simulator.adoc#simulator,KiCad's internal ngspice simulator>>,
or for running an ngspice simulation with options that are not supported by
KiCad's simulator tool.

Enter the path to the external simulator in
the text box, with `%I` representing the generated netlist. Click the **Create
Netlist and Run Simulator Command** button to generate the netlist and
automatically run the simulator.

NOTE: The default simulator command (`spice "%I"`) must be adjusted to point to
a simulator installed on your system.

For more information on the contents of Spice netlists, see the
<<spice-netlists,Spice netlist section>>.

[[netlist-examples]]
=== Netlist examples

Below is the schematic from the `sallen_key` project included in KiCad's
simulation demos.

image::images/eeschema_netlist_schematic.png[alt="sallen_key demo schematic",scaledwidth="95%"]

The KiCad format netlist for this schematic is as follows:

----
(export (version "E")
  (design
    (source "/usr/share/kicad/demos/simulation/sallen_key/sallen_key.kicad_sch")
    (date "Sun 01 May 2022 03:14:05 PM EDT")
    (tool "Eeschema (6.0.4)")
    (sheet (number "1") (name "/") (tstamps "/")
      (title_block
        (title)
        (company)
        (rev)
        (date)
        (source "sallen_key.kicad_sch")
        (comment (number "1") (value ""))
        (comment (number "2") (value ""))
        (comment (number "3") (value ""))
        (comment (number "4") (value ""))
        (comment (number "5") (value ""))
        (comment (number "6") (value ""))
        (comment (number "7") (value ""))
        (comment (number "8") (value ""))
        (comment (number "9") (value "")))))
  (components
    (comp (ref "C1")
      (value "100n")
      (libsource (lib "sallen_key_schlib") (part "C") (description ""))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-00005789077d"))
    (comp (ref "C2")
      (value "100n")
      (fields
        (field (name "Fieldname") "Value")
        (field (name "SpiceMapping") "1 2")
        (field (name "Spice_Primitive") "C"))
      (libsource (lib "sallen_key_schlib") (part "C") (description ""))
      (property (name "Fieldname") (value "Value"))
      (property (name "Spice_Primitive") (value "C"))
      (property (name "SpiceMapping") (value "1 2"))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-00005789085b"))
    (comp (ref "R1")
      (value "1k")
      (fields
        (field (name "Fieldname") "Value")
        (field (name "SpiceMapping") "1 2")
        (field (name "Spice_Primitive") "R"))
      (libsource (lib "sallen_key_schlib") (part "R") (description ""))
      (property (name "Fieldname") (value "Value"))
      (property (name "SpiceMapping") (value "1 2"))
      (property (name "Spice_Primitive") (value "R"))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-0000578906ff"))
    (comp (ref "R2")
      (value "1k")
      (fields
        (field (name "Fieldname") "Value")
        (field (name "SpiceMapping") "1 2")
        (field (name "Spice_Primitive") "R"))
      (libsource (lib "sallen_key_schlib") (part "R") (description ""))
      (property (name "Fieldname") (value "Value"))
      (property (name "SpiceMapping") (value "1 2"))
      (property (name "Spice_Primitive") (value "R"))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-000057890691"))
    (comp (ref "U1")
      (value "AD8051")
      (fields
        (field (name "Spice_Lib_File") "ad8051.lib")
        (field (name "Spice_Model") "AD8051")
        (field (name "Spice_Netlist_Enabled") "Y")
        (field (name "Spice_Primitive") "X"))
      (libsource (lib "sallen_key_schlib") (part "Generic_Opamp") (description ""))
      (property (name "Spice_Primitive") (value "X"))
      (property (name "Spice_Model") (value "AD8051"))
      (property (name "Spice_Lib_File") (value "ad8051.lib"))
      (property (name "Spice_Netlist_Enabled") (value "Y"))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-00005788ff9f"))
    (comp (ref "V1")
      (value "AC 1")
      (libsource (lib "sallen_key_schlib") (part "VSOURCE") (description ""))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-000057336052"))
    (comp (ref "V2")
      (value "DC 10")
      (fields
        (field (name "Fieldname") "Value")
        (field (name "Spice_Node_Sequence") "1 2")
        (field (name "Spice_Primitive") "V"))
      (libsource (lib "sallen_key_schlib") (part "VSOURCE") (description ""))
      (property (name "Fieldname") (value "Value"))
      (property (name "Spice_Primitive") (value "V"))
      (property (name "Spice_Node_Sequence") (value "1 2"))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-0000578900ba"))
    (comp (ref "V3")
      (value "DC 10")
      (fields
        (field (name "Fieldname") "Value")
        (field (name "Spice_Node_Sequence") "1 2")
        (field (name "Spice_Primitive") "V"))
      (libsource (lib "sallen_key_schlib") (part "VSOURCE") (description ""))
      (property (name "Fieldname") (value "Value"))
      (property (name "Spice_Primitive") (value "V"))
      (property (name "Spice_Node_Sequence") (value "1 2"))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-000057890232")))
  (libparts
    (libpart (lib "sallen_key_schlib") (part "C")
      (footprints
        (fp "C?")
        (fp "C_????_*")
        (fp "C_????")
        (fp "SMD*_c")
        (fp "Capacitor*"))
      (fields
        (field (name "Reference") "C")
        (field (name "Value") "C"))
      (pins
        (pin (num "1") (name "") (type "passive"))
        (pin (num "2") (name "") (type "passive"))))
    (libpart (lib "sallen_key_schlib") (part "Generic_Opamp")
      (fields
        (field (name "Reference") "U")
        (field (name "Value") "Generic_Opamp"))
      (pins
        (pin (num "1") (name "+") (type "input"))
        (pin (num "2") (name "-") (type "input"))
        (pin (num "3") (name "V+") (type "power_in"))
        (pin (num "4") (name "V-") (type "power_in"))
        (pin (num "5") (name "") (type "output"))))
    (libpart (lib "sallen_key_schlib") (part "R")
      (footprints
        (fp "R_*")
        (fp "Resistor_*"))
      (fields
        (field (name "Reference") "R")
        (field (name "Value") "R"))
      (pins
        (pin (num "1") (name "") (type "passive"))
        (pin (num "2") (name "") (type "passive"))))
    (libpart (lib "sallen_key_schlib") (part "VSOURCE")
      (fields
        (field (name "Reference") "V")
        (field (name "Value") "VSOURCE")
        (field (name "Fieldname") "Value")
        (field (name "Spice_Primitive") "V")
        (field (name "Spice_Node_Sequence") "1 2"))
      (pins
        (pin (num "1") (name "") (type "input"))
        (pin (num "2") (name "") (type "input")))))
  (libraries
    (library (logical "sallen_key_schlib")
      (uri "/usr/share/kicad/demos/simulation/sallen_key/sallen_key_schlib.kicad_sym")))
  (nets
    (net (code "1") (name "/lowpass")
      (node (ref "C1") (pin "1") (pintype "passive"))
      (node (ref "U1") (pin "2") (pinfunction "-") (pintype "input"))
      (node (ref "U1") (pin "5") (pintype "output")))
    (net (code "2") (name "GND")
      (node (ref "C2") (pin "2") (pintype "passive"))
      (node (ref "V1") (pin "2") (pintype "input"))
      (node (ref "V2") (pin "2") (pintype "input"))
      (node (ref "V3") (pin "1") (pintype "input")))
    (net (code "3") (name "Net-(C1-Pad2)")
      (node (ref "C1") (pin "2") (pintype "passive"))
      (node (ref "R1") (pin "1") (pintype "passive"))
      (node (ref "R2") (pin "2") (pintype "passive")))
    (net (code "4") (name "Net-(C2-Pad1)")
      (node (ref "C2") (pin "1") (pintype "passive"))
      (node (ref "R2") (pin "1") (pintype "passive"))
      (node (ref "U1") (pin "1") (pinfunction "+") (pintype "input")))
    (net (code "5") (name "Net-(R1-Pad2)")
      (node (ref "R1") (pin "2") (pintype "passive"))
      (node (ref "V1") (pin "1") (pintype "input")))
    (net (code "6") (name "VDD")
      (node (ref "U1") (pin "3") (pinfunction "V+") (pintype "power_in"))
      (node (ref "V2") (pin "1") (pintype "input")))
    (net (code "7") (name "VSS")
      (node (ref "U1") (pin "4") (pinfunction "V-") (pintype "power_in"))
      (node (ref "V3") (pin "2") (pintype "input")))))
----

In Spice format, the netlist is as follows:

----
.title KiCad schematic
.include "ad8051.lib"
XU1 Net-_C2-Pad1_ /lowpass VDD VSS /lowpass AD8051
C2 Net-_C2-Pad1_ GND 100n
C1 /lowpass Net-_C1-Pad2_ 100n
R2 Net-_C2-Pad1_ Net-_C1-Pad2_ 1k
R1 Net-_C1-Pad2_ Net-_R1-Pad2_ 1k
V1 Net-_R1-Pad2_ GND AC 1
V2 VDD GND DC 10
V3 GND VSS DC 10
.ac dec 10 1 1Meg
.end
----


[[notes-on-netlists]]
=== Notes on Netlists

[[netlist-name-precautions]]
==== Netlist name precautions

Many software tools that use netlists do not accept spaces in component names,
pins, nets, or other fields. Avoid using spaces in pins, labels, names, and
value fields of components to ensure maximum compatibility.

In the same way, special characters other than letters and numbers can
cause problems. Note that this limitation is not related to KiCad,
but to the netlist formats that can then become untranslatable by
other software that reads those netlist files.

[[spice-netlists]]
==== Spice netlists

Spice simulators expect simulation commands (`.PROBE`, `.AC`, `.TRAN`, etc.) to be
included in the netlist.

Any text line included in the schematic diagram starting with a period (`.`)
will be included in the netlist. If a text object contains multiple lines,
only the lines beginning with a period will be included.

`.include` directives for including model library files are automatically
added to the netlist based on the Spice model settings for the symbols in
the schematic.

[[other-formats]]
=== Other formats

KiCad supports custom netlist generators for exporting netlists in other
formats. Some examples of netlist generators are given in the
<<eeschema_creating_customized_netlists_and_bom_files.adoc#creating-customized-netlists-and-bom-files,custom netlist generators section>>.

A netlist generator is a script or program that converts the intermediate
netlist file created by KiCad into the desired netlist format. The intermediate
netlist file contains all of the netlist information required to create an
arbitrary netlist for the schematic. Python and XSLT are commonly used tools to
create custom netlist generators.

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

New netlist generators are added 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 `%I` argument represents the input intermediate netlist filename and
the `%O` argument represents the output netlist filename. The exact netlist
command will depend on the generator script used.

[[command-line-format]]
==== Command line format

Consider the following example which uses `xsltproc` to generate a netlist in
PADS ASC format. `xsltproc` converts the intermediate netlist using the
`netlist_form_pads-pcb.asc.xsl` stylesheet to define the output format:

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

The purpose of each part of the command is as follows:

[width="100%",cols="58%,42%",]
|=======================================================================
|`xsltproc` |A tool to convert an XML file (the intermediate netlist) according
to an XSLT stylesheet.

|`-o %O.net` |Output filename. `%O` is replaced with the name of the
intermediate netlist file, which is `<schematic name>.xml`. Therefore in this
example the complete output filename is `<schematic name>.xml.net`. An arbitrary
output filename can be specified if desired with `-o <filename>`.

|`/usr/share/kicad/plugins/netlist_form_pads-pcb.asc.xsl` |XSLT stylesheet which
determines how the output is formatted. This particular stylesheet is included
with KiCad, but custom stylesheets can also be created.

|`%I` |Input (intermediate netlist) filename. `%I` is replaced with the name of
the intermediate netlist file, which is `<schematic name>.xml`.
|=======================================================================

For netlist generators that do not use `xsltproc`, the generator command will differ.

[[intermediate-netlist-file-format]]
==== Intermediate netlist file format

See the 
<<eeschema_creating_customized_netlists_and_bom_files.adoc#creating-customized-netlists-and-bom-files,custom netlist generators section>>
for more information about netlist generators, a description of the intermediate
netlist format, and some examples of netlist generators.