.. _kicad-pyopus-library:

Using the pyopus symbol library
===============================
For drawing schematics that will be used for generating netlists you can use 
arbitrary KiCad schematic components. But the most straightforward way is to 
use the pyopus symbol library of schematic components. Predefined rules exist for 
netlisting these components. For other KiCad schematic components you will 
have to write your own netlisting rules. In some cases even the default 
netlisting rule will be good enough. 


Getting started with your first schematic
=========================================
First, note that in KiCad 6 schematic files have the .kicad_sch extension. 
This tutorial was written for KiCad 5. So if you are using KiCad 6, 
whenever you encounter .sch in this tutorial, note that the correct extension 
should be .kicad_sch. 

One KiCad schematic can be subdivied in several .sch files, but in the end 
this hierarchy will be flattened to produce one netlist file which is 
either a top-level netlist or defines one subcircuit. 

To introduce the PyOPUS netlister for KiCad we are going to draw two schematics. 
The first one (``miller.sch``) defines a Miller operational transconductance 
amplifier (OTA) as a subcircuit. The second one (``topdc.sch``) uses this 
subcircuit and simulates its DC and AC behavior. 

In the folder where the schematic files will be stored start eeschema by typing
	
.. code-block:: none

	eeschema

Before you proceed, save the file by choosing File/Save Current Sheet As...
Specify ``miller.sch`` as the file name. If you want to open the schematic 
later you must type

.. code-block:: none

	eeschema `pwd`/miller.sch
	
The ``pwd`` prefix must be added because eeschema requires a full path to be 
specified. If you open the schematic file by doubleclicking it in the file
manager (e.g. Dolphin) a full path to the file will be passed to eeschema 
automatically. Under Windows use the File Explorer for opening schematic files 
to avoid typing the full path when invoking eeschema. This behavior seems to 
be gone in KiCad 6, where you can again specify only the schematic file without 
the fuill path. 

The Miller OTA schematic is constructed using the following components from 
the pyopus symbol library

* NMOS and PMOS for the MOS transistors
* RES and CAP for the resistor and capacitor
* ISRC for the independent current source
* OUTPUT_FILE for defining the output netlist file name
* SUBCKT for defining the subciruit name and pin order

.. figure:: kicad-miller.png
	:scale: 60%
	
	Miller OpAmp schematic.

Note that at netlisting KiCad will insist that all your component names end 
with a number. So don't waste your time trying to force Ma as the MOS 
transistor name. Name it Ma1 instead. 

MOS transistors have 3 numbers associated with every symbol. The bold one is 
the channel width (W). Right above/below it (depending on symbol's rotation) 
is the channel length (L). Somewhat further away is the multiplier factor (M).
The model name is specified as the Model filed. 

By default the netlister will recognize components GND, GNDA, GNDD, GNDPWR, and 
GNDREF as ground nodes. You can change this in the netlister configuration. See 
the documentation of :mod:`pyopus.netlister` on how to do this. The customized 
configuration must be stored in a ``netlister.json`` file in the folder where 
the intermediate XML netlists will be generated by KiCad. 

The pins of the subcircuit must be named with global labels. If you place a 
SUBCKT component from pyopus library the whole schematic will be treated as 
a subcircuit definition. The name of the subcircuit and the net names of its 
pins are defined as Fields of the SUBCKT component. 

To define subcircuit parameters use the SUBCKT_PARAM components (one for 
every parameter). Arbitrary parameters can be defined using the PARAM 
component (one per parameter). Every PARAM component translated to one 
``.param`` statement inside the subcircuit definition (or in the top-level 
netlist of the schematic defines a top-level netlist). 

Before generating the netlist save the schematic by choosing File/Save from 
the mneu. Select Tools/Generate Netlist File in the eeschema menu. A window 
will pup up. Select the Spice Opus tab and click on the Generate button. 
A file dialog will pup up asking you for the netlist file name, After entering 
it and clicking the Save button the intermediate XML netlist will be generated 
and the PyOPUS KiCad netlister plugin will be invoked. This plugin reads 
the XML file and the netlister configuration files (.json files) that 
customize its behavior. After that it outputs the nelist. If you place an 
OUTPUT_FILE component in your schematic this component will define the name 
of the netlist file regardless of what you specify in the file dialog (the 
file name will only be used for the intermediate netlist). After the netlist 
file is generated a window will pop up showing the contents of the netlist 
file ``miller.inc``. 

.. literalinclude:: ../demo/kicad/01-schem/miller.inc
   :language: none
   
You can close it by pressing ``Enter`` or ``Esc`` or clicking on the Close 
button. 

To define the top-level netlist start another instance of eeschema by typing

.. code-block:: none

	eeschema

Note that eeschema will complain it is already running. Simply ignore 
the message and click Yes to continue. Save the empty schematic as 
``topdc.sch``. The top level schematic uses the following pyopus symbol 
library components

* VSRC for the independent voltage sources
* VCVS for the voltage-controlled voltage source
* RES and CAP for resistors and capacitors
* OPAMP for the opamp
* OUTPUT_FILE for specifying the output netlist file name
* INCLUDE for including an external file (``miller.inc``)
* LIB for including section ``tm`` of the library file (``cmos180n.lib``)

.. figure:: kicad-topdc.png
	:scale: 60%

	Testbench circuit schematic.
	
All nodes that will be accessed by the Spice Opus commands are named 
explicitly with global labels. The Value filed of the OPAMP is set to the 
name of the subcircuit that defines the Miller OTA (included from file 
``miller.inc``). By default all components that do not have a netlisting 
rule defined are netlisted as subcircuits. The Value field specifies the 
subcircuit name. The nodes of the subcircuit instance are dumped in the 
increasing pin number order of the component. 

Any text block will be added to the netlist above/below netlisted components 
if it starts with the line

.. code-block:: none

	Text<number> position=top|bottom

If there are multiple text blocks they are dumped in in the increasing 
number order. Note that the schematic file must be saved before netlisting 
so that the netlister can extract the text blocks from the schematic file. 
We use this text block feature to add a ``.control`` block to the netlist 
with the commands thet will run a DC and an AC analysis and plot the results. 

Save the finished schematic by choosing File/Save from the menu. 
After netlisting the ``topdc.sch`` file the following netlist will be written 
to the ``topdc.cir`` file (due to the OUTPUT_FILE component). 

.. literalinclude:: ../demo/kicad/01-schem/topdc.cir
   :language: none

You can run the simulation by typing

.. code-block:: none

	spiceopus topdc.cir

Demo files for this section can be found `here <../../../demo/kicad/01-schem>`_.
