Add a short tutorial on how to convert simple netlists

.gitignore

@@ -0,0 +1,30 @@
+# For PCBs designed using KiCad: https://www.kicad.org/
+# Format documentation: https://kicad.org/help/file-formats/
+
+# Temporary files
+*.000
+*.bak
+*.bck
+*.kicad_pcb-bak
+*.kicad_sch-bak
+*-backups
+*.kicad_prl
+*.sch-bak
+*~
+_autosave-*
+*.tmp
+*-save.pro
+*-save.kicad_pcb
+fp-info-cache
+
+# Netlist files (exported from Eeschema)
+*.net
+*.cir
+
+# Autorouter files (exported from Pcbnew)
+*.dsn
+*.ses
+
+# Exported BOM files
+*.xml
+*.csv

Example.md

@@ -0,0 +1,119 @@
+## Simple Example
+
+These are the steps I took to convert a very simple schematic into a working MAME netlist.
+
+As an example I used
+
+https://github.com/mamedev/discrete/tree/master/kicad/wildfire
+
+Load the project in KiCAD and open the schematic editor.
+
+Some of these files have been created in older version of KiCAD, in this case it will ask you to rescue the symbols, just click OK.
+
+Once you can see the schematic, click on `File -> Export -> Netlist...`
+
+In the Export Netlist window click on the `Spice` tab and then on `Export Netlist`.
+Save the file next to the other project files.
+
+If you had errors in the annotation, it will pop up a window at this point, in the case of this example it's fine to click on `Annotate` and continue.
+
+Your wildfire.cir file will look somewhat like this:
+
+```
+.title KiCad schematic
+C1 Net-_I_A12-P1_ VDD 4.7u
+I_A12 __I_A12
+O_AUDIO1 __O_AUDIO1
+R2 Net-_I_A12-P1_ Net-_Q2-B_ 10k
+I_F1 __I_F1
+Q3 __Q3
+Q2 __Q2
+R1 Net-_Q2-B_ VDD 10k
+.end
+```
+
+Next we'll need a build of nltool.
+Open a terminal and navigate to your mame source folder and then into src/lib/netlist/build
+If you don't have nltool yet, run `make` (It doesn't build automatically with MAME).
+
+If the build succeeded run `./nltool --help` to get a short overview of the features.
+Next we want to convert the Spice netlist into a MAME one.
+
+For this the command is `./nltool -c convert /path/to/discrete/kicad/wildfire/wildfire.cir`
+
+Here we hit our first roadblock, the converter thinks the part labeled I_A12 is a power source.
+Go back into the schematic editor, click the in- and output terminals and add a 'J' at the start of the reference.
+You can find a list of which reference letters will convert to which parts in nl_convert.cpp
+
+After changing them export the netlist to retry converting it.
+
+This time, nltool will throw a segmentation fault.
+The problem is that it expects the transistors to have more than 1 parameter each.
+
+Click the transistor in the schematic, press E (or right click and choose Edit) and in the window that pops up
+at the bottom there's a button `Simulation Model...`
+In the Simulation Model Editor change the radio box to `Built-in SPICE model` and for Device pick "PNP BJT", because
+the transistor in this schematic is a PNP one.
+Exit out with OK and pay attention to the Sim.Pins field in the Symbol Properties.
+Most likely the Pin assignment is wrong here, this transistor uses ECB as the pin order but the default spice symbol assigned CBE.
+Change it to `1=E 2=C 3=B` and exit with OK.
+
+Export the netlist again and run nltool with the convert command again and it will work!
+
+To save this netlist run the command again but add ` > nl_wildfire.cpp` to pipe the output into that file.
+
+You can now try to run this file with `./nltool -c run nl_wildfire.cpp`
+It will fail and complain that the Base of Q3 isn't connected to anything else.
+
+The base of Q3 is actually one of the inputs of this circuit so we'll do that next.
+Open nl_wildfire.cpp in a text editor.
+
+Remove the line it complained about `NET_C(Q3.B)`
+
+Between the last NET_C line and the } bracket add a few newlines.
+
+Here we'll add some lines for our in- and outputs
+```
+ALIAS(I_F, Q3.B)
+ALIAS(I_A12, R2.1)
+ALIAS(O_AUDIO, Q3.E)
+```
+
+If we run the netlist now it complains about CAP_U missing.
+This is an easy fix, add `#include "netlist/devices/net_lib.h"` as the first line before `NETLIST_START(dummy)` and on that occasion rename dummy to wildfire.
+
+Next error is that xxPNP is missing. MAMEs PNP transistor has a different name from KiCADs
+Remove the 2 NET_MODEL lines and at the 2 lines for `QBJT_EB(Qx, "__Qx")`, replace the `__Qx` with `PNP`.
+
+If you run it again it will not complain about our netlist anymore but that the solver is missing.
+Create a newline after `// .END` and add this line.
+```
+SOLVER(Solver, 48000)
+```
+
+48000 is the default value for audio circuits.
+If you're recreating a different circuit you'll want to change this later.
+
+After this change the netlist will finally run in nltool
+We can check on the output pin with the following command:
+`./nltool -c run -t 3 -l O_AUDIO ./nl_wildfire.cpp`
+
+If you open `log_O_AUDIO.log` you'll see the time on the left side and the voltage on the right side.
+The voltage is slowly rising and the circuit isn't working quite right.
+This probably has to do with the fact we're missing input power.
+
+After the SOLVER line add
+```
+ANALOG_INPUT(V5, 5)
+ALIAS(VDD, V5)
+```
+
+Go to line `NET_C(C1.2, R1.2, Q2.E)` and add `VDD, ` before C1 to connect our new power source up.
+If we run the log again it's now at a steady 5V.
+This is expected as the circuit isn't getting any input right now.
+
+## Notes
+This will not work for multi-part ICs (such as almost all 74 series parts)
+The reason for this is that KiCAD ignores all parts after the first one.
+The bug is being tracked here:
+https://gitlab.com/kicad/code/kicad/-/issues/1779

README.md

@@ -13,14 +13,13 @@ This repository is meant to house files in formats that can be imported and work
 Going forward you will need at least KiCad 5.1. On Ubuntu you can install KiCad using 
 
 ```sh
-sudo add-apt-repository ppa:js-reynaud/kicad-5.1
-sudo apt-get update
+sudo apt update
 sudo apt install kicad kicad-templates kicad-doc-en kicad-symbols kicad-footprints kicad-demos kicad-packages3d libngspice-kicad kicad-libraries
 ```
 
 #### Libraries
 
-Add `MAME.kib` and `netlist.lib` to your library list:
+Add `MAME.lib` and `netlist.lib` to your library list:
 
 Preferences-> Manage Symbol Libraries -> Add existing library
 
@@ -45,7 +44,7 @@ obxVoice  | TBD
 tb303 | TBD 
 carPolo | TBD 
 StarCruiser | TBD 
-wildfire | TBD 
+wildfire | migrated to 8
 
 ### Specific components
 
@@ -110,8 +109,11 @@ Convert an exported spice file (suffix cir) to netlist format using:
 ```sh 
 nltool -c convert -f congoBongo.cir > nl_congo_bongo.cpp
 ```
+### Development aids
+As a replacement for the retired aatool, you may want to look at
+https://github.com/aovestdipaperino/aa-tool
 
+For schematics involving multi-part devices, you may want to use nlconvert from
+https://github.com/stonedDiscord/netlist-tools
 
-
-
-
+For a very short example guide you may want to look at Example.md in this folder.

kicad/wildfire/sym-lib-table

@@ -0,0 +1,5 @@
+(sym_lib_table
+  (version 0)
+  (lib (name "wildfire-rescue")(type "Legacy")(uri "${KIPRJMOD}/wildfire-rescue.lib")(options "")(descr ""))
+  (lib (name "MAME")(type "Legacy")(uri "../MAME.lib")(options "")(descr ""))
+)

kicad/wildfire/wildfire-rescue.lib

@@ -0,0 +1,99 @@
+EESchema-LIBRARY Version 2.4
+#encoding utf-8
+#
+# 2SB631
+#
+DEF 2SB631 Q 0 0 Y Y 1 F N
+F0 "Q" 0 -150 40 H V R CNN
+F1 "2SB631" 0 150 40 H V R CNN
+F2 "TO126" -120 100 29 H I C CNN
+F3 "" 0 0 60 H V C CNN
+F4 "" 0 0 50 H I C CNN
+$FPLIST
+ TO126*
+$ENDFPLIST
+DRAW
+P 2 0 1 0 100 -100 25 -25 N
+P 2 0 1 0 100 100 25 25 N
+P 3 0 1 20 25 75 25 -75 25 -75 F
+P 5 0 1 0 55 -75 75 -55 35 -35 55 -75 55 -75 F
+C 50 0 111 0 1 12 N
+X E 1 100 -200 100 U 40 40 1 1 P
+X C 2 100 200 100 D 40 40 1 1 P
+X B 3 -200 0 225 R 40 40 1 1 I
+ENDDRAW
+ENDDEF
+#
+# C
+#
+DEF C C 0 10 N Y 1 F N
+F0 "C" 0 100 40 H V L CNN
+F1 "C" 6 -85 40 H V L CNN
+F2 "" 38 -150 30 H V C CNN
+F3 "" 0 0 60 H V C CNN
+F4 "" 0 0 50 H I C CNN
+$FPLIST
+ SM*
+ C?
+ C1-1
+$ENDFPLIST
+DRAW
+P 2 0 1 20 -80 -30 80 -30 N
+P 2 0 1 20 -80 30 80 30 N
+X ~ 1 0 200 170 D 40 40 1 1 P
+X ~ 2 0 -200 170 U 40 40 1 1 P
+ENDDRAW
+ENDDEF
+#
+# GND
+#
+DEF GND #PWR 0 0 Y Y 1 F P
+F0 "#PWR" 0 0 30 H I C CNN
+F1 "GND" 0 -70 30 H I C CNN
+F2 "" 0 0 60 H V C CNN
+F3 "" 0 0 60 H V C CNN
+F4 "" 0 0 50 H I C CNN
+DRAW
+P 4 0 1 0 -50 0 0 -50 50 0 -50 0 N
+X GND 1 0 0 0 U 30 30 1 1 W N
+ENDDRAW
+ENDDEF
+#
+# R
+#
+DEF R R 0 0 N Y 1 F N
+F0 "R" 80 0 40 V V C CNN
+F1 "R" 7 1 40 V V C CNN
+F2 "" -70 0 30 V V C CNN
+F3 "" 0 0 30 H V C CNN
+F4 "" 0 0 50 H I C CNN
+$FPLIST
+ R?
+ SM0603
+ SM0805
+ R?-*
+ SM1206
+$ENDFPLIST
+DRAW
+S -40 150 40 -150 0 1 12 N
+X ~ 1 0 250 100 D 60 60 1 1 P
+X ~ 2 0 -250 100 U 60 60 1 1 P
+ENDDRAW
+ENDDEF
+#
+# VDD
+#
+DEF VDD #PWR 0 0 Y Y 1 F P
+F0 "#PWR" 0 100 30 H I C CNN
+F1 "VDD" 0 110 30 H V C CNN
+F2 "" 0 0 60 H V C CNN
+F3 "" 0 0 60 H V C CNN
+F4 "" 0 0 50 H I C CNN
+DRAW
+P 3 0 1 0 0 0 0 40 0 40 N
+C 0 60 20 0 1 0 N
+X VDD 1 0 0 0 U 40 40 0 0 W N
+ENDDRAW
+ENDDEF
+#
+#End Library