Proper file separations when creating a new component with associated ngspice model

Schematic Library Symbols
1

I am trying to make a new part via the tutorial for making new symbols. In addition to what is shown I am also trying to associate this part with a spice model via the docs.

My question is concerning how to properly separate the spice model from the schematic symbol. Are the symbol definition and spice model lib files supposed to be separate or is there a way to properly combine them? Both appear to be meant for a .lib file, but I’m getting some errors from ngspice that hint to me that I should not be combining them into a single file as it seems to imply in making new symbols tutorial:

In KiCad, a symbol is a piece of text that starts with ‘DEF’ and ends with ‘ENDDEF’. One or more symbols are normally placed in a library file with the extension .lib . If you want to add symbols to a library file you can just use the cut and paste commands of a text editor.

You can find the error that led to this question along with the NET list and lib file over at the ngspice support ticket. The error seems to indicate that ngspice is trying to parse the symbol definition as a subcircuit.

2

Following this.

I tried looking it up, but I couldn’t find a direct or clear answer.

3

I should add that the .lib format is stated to be for:

schematic symbols library file.

even though the SPICE model files used in assigning models also uses the .lib extension. The manufacturer SPICE models also use the .lib extension for specifying the SPICE model…maybe this is just a poor naming convention and they are indeed supposed to be separate files?

4

Prereq Knowledge:

  • KiCAD has a “legacy” and new .lib file format. Only the legacy format appears to have official documentation and some third party documentation.
  • The legacy .lib format file should only be used to define the KiCAD related info about the part (i.e. no SPICE library or model info should be present).
  • The typical SPICE .lib file is a completely different file format, with an unfortunate overlap in naming with the KiCAD .lib file extension.

Minimum File Requirements:

So for a given component you need at least:

  • One KiCAD .lib file which contains:
    • Graphic information to draw the symbol between the DRAW and ENDDRAW keywords
    • Definitions for the various text fields via the F<n> keywords. These can define required metadata like the component name, but also provide links to external files for SPICE libraries.
    • It is in the user fields F<n >= 4> that you can set global definitions for SPICE models. These should be a separate file.
  • One documentation .dcm file which contains meta data (not sure why most of this cannot be contained within the F<n> statements of the .lib file though.

Organization for Custom Global Components:

For global components, you can add the .dcm and .lib file of your new component to the global KiCAD library directory (e.g. on Ubuntu /usr/share/kicad/library), but as this requires sudo, I opt to put this in a dedicated global KiCAD components directory in my home folder (e.g. ~/kicad/libraries). I’m still not sure if it is appropriate to put the SPICE .lib files in this folder or not as this would likely be quite confusing. It might make more sense to add another directory (e.g. on Ubuntu /usr/share/kicad/library/spice or /home/[username]/kicad/spice). Note it does not seem KiCAD can traverse directories or interpret the ~/ directory so a full path is necessary. Either that, or using a suffix like _spice.lib but this is also likely to cause chaos later.

In the Assigning Models section of the KiCAD docs:

Spice model information is stored as text in symbol fields, therefore you may either define it in symbol editor or schematics editor.

It seems to me that if you define it in the schematics editor it is only saved to that particular instance of the component, whereas if you define it in the symbol editor it will be saved globally. This is a confusing point about the docs I think.

Making a Custom Global Component with Associated SPICE File:

So here are the steps I’d take to making a new global custom component with a SPICE file association:

  1. Open the Symbol Editor and find an existing part that is close to the one you want to make (i.e. should have the same symbol and same package type (e.g. TO-252-2).
  2. Export the above component with File -> Export Symbol (Note: this exports not just the symbol … it exports the KiCAD .lib file and the documentation .dcm file. I export this to my custom global kicad directory (e.g. /home/[username]/kicad/libraries) Note here that the FULL path is required. I tried ~/kicad/libraries and ../kicad/libraries when specifying the datasheet and spice model location and these resulted in errors.
  3. Either in a text editor, or by Preferences -> Manage Symbol Libraries and importing your copy, make the changes to the custom component. Note this makes a single .lib and .dcm file for each new custom component. After you get the hang of the file format, it likely makes more sense to compound all your custom components into a single .lib and .dcm file specific to the type of component (e.g. I have a custom_mosfets.lib and custom_mosfets.dcm file containing all my custom mosfet components).
  4. Still in the Symbol Editor, with your new custom library imported and your custom component open go to Edit -> Properties -> Edit Spice Model. Here you can assign the manufacturer spice .lib file, but again it must be a full path.
  5. Now you should be able to use your custom part with associated SPICE model in any new schematic file in Eeschema.

Summary of File Structure

So to summarize my file separations I have the following files:

  1. A custom KiCAD .lib file that contains graphic and meta data for several components of a given type in /home/[username]/kicad/libraries/custom_mosfets.lib
  2. A custom KiCAD .dcm file that contains even more meta data for all the components in the custom_mosfets.lib file in /home/[username]/kicad/libraries/custom_mosfets.dcm.
  3. An individual SPICE model (aka library or .lib file) for each component in /home/[username]/kicad/spice/mosfet1.lib
  4. [Not required] another folder for datasheets in /home/[username]/kicad/datasheets/mosfet1.pdf for keeping local datasheets, though you can likely provide a URL as well? (haven’t tested)

Example files:

custom_mosfets.lib:

EESchema-LIBRARY Version 2.4
#encoding utf-8
#
# SQP90P06-07L
#
DEF SQP90P06-07L Q 0 20 Y N 1 F N
F0 "Q" 200 100 50 H V L CNN
F1 "SQP90P06-07L" 195 0 50 H V L CNN
F2 "Package_TO_SOT_SMD:TO-252-2" 195 -75 50 H I L CIN
F3 "" 0 0 50 H I C CNN
F4 "X" 200 400 50 H I L CNN "Spice_Primitive"
F5 "SQP90P06-07L" 200 200 50 H I L CNN "Spice_Model"
F6 "Y" 200 500 50 H I L CNN "Spice_Netlist_Enabled"
F7 "2 1 3" 850 200 50 H I L CNN "Spice_Node_Sequence"
F8 "/home/[username]/kicad/spice/SQP90P06-07L_PS_spice.lib" 200 300 50 H I L CNN "Spice_Lib_File"
$FPLIST
 TO?252*
$ENDFPLIST
DRAW
C 65 0 110 0 1 10 N
C 100 -70 10 0 1 0 F
C 100 70 10 0 1 0 F
P 2 0 1 0 10 0 -100 0 N
P 2 0 1 10 10 75 10 -75 N
P 2 0 1 10 30 -50 30 -90 N
P 2 0 1 10 30 20 30 -20 N
P 2 0 1 10 30 90 30 50 N
P 2 0 1 0 100 100 100 70 N
P 3 0 1 0 100 -100 100 0 30 0 N
P 4 0 1 0 30 70 130 70 130 -70 30 -70 N
P 4 0 1 0 90 0 50 15 50 -15 90 0 F
P 4 0 1 0 110 -20 115 -15 145 -15 150 -10 N
P 4 0 1 0 130 -15 115 10 145 10 130 -15 N
X G 1 -200 0 100 R 50 50 1 1 I
X D 2 100 200 100 D 50 50 1 1 P
X S 3 100 -200 100 U 50 50 1 1 P
ENDDRAW
ENDDEF
#
# ...Add more components below this line...
#End Library

**Note lines starting with F4 through F8 which define the various SPICE model parameters.

custom_mosfets.dcm:

EESchema-DOCLIB  Version 2.0
#
$CMP SQP90P06-07L
D P-channel Power Enhancement MOSFET
K simulation mosfet, p-channel, enhancement
F /home/[username]/kicad/datasheets/65687SQP90P06-07L_PS_REVA.pdf
$ENDCMP
# ...Add more components below this line...
#End Doc Library

mosfet1.lib:

********************************
* Copyright:                   *
* Vishay Intertechnology, Inc. *
********************************
*Apr 27, 2015
*ECN S15-0949, Rev. A
*File Name: SQP90P06-07L_PS.txt and SQP90P06-07L_PS.lib
*This document is intended as a SPICE modeling guideline and does not
*constitute a commercial product datasheet. Designers should refer to the
*appropriate datasheet of the same number for guaranteed specification
*limits.
.SUBCKT SQP90P06-07L D G S  
M1 3 GX S S PMOS W= 19911044u L= 0.3u 
M2 S GX S D NMOS W= 19911044u L= 0.42u 
R1 D 3 5.040e-03 TC=5.458e-03,7.805e-06
CGS GX S 6.574e-09 
CGD GX D 1.885e-10 
RG G GY 1m 
RTCV 100 S 1e6 TC=3.411e-04,-2.704e-06
ETCV GY GX 100 200 1 
ITCV S 100 1u 
VTCV 200 S 1 
DBD D S DBD 19911044u 
************************************************** 
.MODEL PMOS PMOS ( LEVEL = 3 TOX = 5e-8 
+ RS = 0 
+ KAPPA = 1.001e-02 NFS = 3.30e+11 
+ LD = 0 IS = 0 TPG = -1    )
**************************************************  
.MODEL NMOS NMOS ( LEVEL = 3 TOX = 5e-8 
+NSUB = 1.290e+16 IS = 0 TPG = -1    )
************************************************** 
.MODEL DBD D ( 
+FC = 0.1 TT = 2.389e-08 TNOM = 25 BV = 61
+RS = 3.848e-02 N = 1.084e+00 IS = 1.408e-12 
+EG = 1.498e+00 XTI = -8.875e+00 TRS1 = 2.706e-03
+CJO = 9.387e-11 VJ = 3.212e+00 M = 9.990e-01 ) 
.ENDS 
*************************
5

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.