GSCHEM-FINALIZER

EDA Tool To Finalize gEDA gschem Schematic Drawing Project

OVERVIEW

Gschem-finalizer is EDA tool to finalize your project in drawing circuit schematics with use gEDA gschem. This program consist as executable shell script written in PHP scripting language. This program integrates gEDA Suites (gschem, gnetlister, PCB, and NGSPICE) to compile, annotate, and produce netlist of gEDA circuit schematic. This program also enables circuit level simulation using NGSPICE from gEDA circuit schematics files, by producing SPICE 3F5 netlist format for analog, digital, and mixed circuit simulation mode.

FEATURES

  • Finalizing circuit schematics into multiple-page PDF documents complete with voltage operating point.
  • Produce SPICE 3F5 netlist for analog, digital, & mixed circuit simulation.
  • Produce PCB layout generation for gEDA PCB & Kicad PCB (Kicad pcbnew).
  • PCB layout design annotation from circuit schematic.
  • Additional DRC (checking for: duplicate REFDES, unnamed net, & unknown ports of digital symbol).
  • Supports circuit schematic annotations to control the output form, to configure SPICE netlist generation, and for configuring PCB layout netlisting.

SPECIAL FEATURE

Gschem-finalizer includes special feature to produce SPICE netlist for digital simulation by working together gnetlist with vams backend (VHDL-AMS). This special feature allows you easily designing and simulating circuit schematics with primitive models of TTL (Transistor-Transistor Logic).

DOWNLOAD

Repository:
http://sourceforge.net/projects/gschemfinalizer/files/

Current stable version is V. 0.4-20130902, available here:
http://sourceforge.net/projects/gschemfinalizer/files/gschem-finalizer_0.4-20130902.tar.gz

LICENSE

Gschem-finalizer free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Gschem-finalizer is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

------------------------------------------------------

This project is started & maintained by HERU HIMAWAN T.

INSTALLATION

Gschem-finalizer as of version 0.3-16102012 released complete with install script named install.sh. Installation can be executed from terminal console under root user privileges.

Installation Requirements

The mainly requirement is GNU/LINUX or UNIX like OS'es installed on your machine.

Notice
The install.sh installation script will assume standard environment system of any variant of GNU/LINUX or UNIX operating system that consist of env that pointed by environment variable known as "_", i.e _=/usr/bin/env.

Yet, Gschem-finalizer requires the following programs installed on your system:

  • PHP: version >= 5.4.7 compiled with posix, sysvmsg, and pcntl module.
  • gEDA Suites: gschem, gnetlist (with spice-sdb & vams backend), PCB (PCB GTK or PCB LESSTIF), and NGSPICE >= 22
  • GNU a2ps
  • ps2pdf (from Ghostscript package)
  • find (GNU Findutils)
  • echo, rm, & cat (GNU Coreutils)
  • tar
  • gzip

HOWTO Install

Installation can be done by with the following instructions:

  1. Download the latest version of installation package from Gschem-finalizer repository. Extract the installation package into a specific folder, i.e named gschem-finalizer[version].

  2. Open the terminal console program (xterm, gnome-terminal, etc.) and change directory into the extracted package.

  3. Run terminal command to load install script (install.sh) under root privileges:

        $ sudo ./install.sh
  4. Answer Y/yes if install.sh ask to continue the installation and if you really want to install. Otherwise answer N/no.

Installation will be done if all required programs already installed. Halt otherwise.

The executable shell will be installed with absolute path /usr/bin/gschem-finalizer. The source code and all package file will be installed into directory /usr/share/gschem-finalizer.

EXTENDED USAGE

For more convenience, please follow the tutorial here: gschem-finalizer-tutorial.html

Running As A Terminal Command

Gschem-finalizer can be running via terminal console as a command, after it is installed on your system:

    $ gschem-finalizer [OPTIONS]

Cautions!

  1. Do not running gschem-finalizer under root account to avoid it damages your system.

  2. Gschem-finalizer as for current version is not be able to run as standalone program from local directory i.e. from your home directory. Running gschem-finalizer from local directory or out of system bin will cause it fail to generate sub-circuit SPICE directive (.subckt) from a sub-circuit schematic diagram.

Running From Shell Script

We advise you use gschem-finalizer from within a shell script. Calling gschem-finalizer from a shell script much easies to include number of command options and arguments rather than directly writing a long command line on terminal.

Here is an example script named "finalize.sh", which you may reference on it:

#!/bin/bash

gschem-finalizer                                                                \
--basic-technology="MATRIX 1. 4 Free Audio Power Amplifier Technology (K 2012)" \
--project-code-name="1500w-2-ohms-audio-power-amp"                              \
--common-nets="vccmp, vccmn, SYSGND, 0"                                         \
--create-tarball                                                                \
--designer="Heru Himawan T"                                                     \
--email="heru. htl@gmail. com"                                                  \
--include-files="gpl3.txt, README, schematic-license-notice, spice-credits.txt, \
  finalize.sh, schematics, PENGANTAR-BERBAHASA-INDONESIA"                       \
--inventor="Heru Himawan T"                                                     \
--license-file="schematic-license-notice"                                       \
--project-name="1500 Watt Peak Class AB Audio Power Amplifier For 2-Ohms        \
  Loudspeaker (Core)"                                                           \
--project-version="k-1500-2-2012"                                               \
--special-nets="SYSGND, 0"                                                      \
--spice-credit-text-file="spice-credits.txt"                                    \
--url="http://matrix14freeamp.sourceforge.net/"                                 \
--large-paper-type=a2 --normal-paper-type=a3 $@

COMMAND LINE OPTIONS

Common Options:

--help

Show this help and exit.

--version

Print version, view about gschem-finalizer, and exit.

Conditional Command Line Options:

--project-code-name=<"project code name">

Set the code name of project. The code name must contain only the following characters: [a-to-z], [0-to-9], and [-] (minus). The capital characters will be lowered.

--project-version=<"version">

Set version of schematic project. The project version must contain only the following characters: [a-to-z], [0-to-9], [. ] (dot), and [-] (minus). The capital characters will be lowered.

Running Mode Option:

--fork

Fork the program to be running on background. When this option is set, you may close current terminal without interrupting current running process.

--enable-gaf

Enabling the use of gaf executable. This option will be usable if gaf executable available within your gEDA installation.

Schematic Annotations Options:

--basic-technology=<"basic technology">

Set the basic technology property. This will be included on PDF output as the value of 'Keyword' Document Properties.

--designer=<"designer name">

Set the designer name. This will be included on PDF output as the value of 'Author' Document Properties.

--email=<"e-mail address">

Set the designers e-mail address.

--inventor=<"inventor name">

Set the inventor name.

--license-file=<"path to license file">

Set path to the license text file to be loaded and inserted to the final (copy of) schematics.

--project-name=<"project name">

Set the schematic project name.

--reset-rev-count

Reset the revision count into 1. You likely do not need to use this option if you are maintaining a schematic project for a team project. Before using this option, you are recommended to backup a hidden file named .revision (if any) in the project directory.

--set-rev-count=<number>

Set the revision count specifically. You likely do not need to use this option if you are maintaining a schematic project for a team project. Before using this option, you are recommended to backup a hidden file named .revision (if any) in the project directory.

--url=<"URL address">

Add the designer URL address.

--use-current-rev

Use current revision count. This option overrides --reset-rev-count and --set-rev-count. If your schematic is newly configured, the revision count will be set to 1.

Packaging Options:

--create-tarball

Pack the current project as gzipped GNU TARBALL.

--include-files=<"file1[, file2][, file3]. . . ">

List of additional files or directories to be included in the final distribution package (TARBALL). Each pair is comma delimited.

Print Output Options:

--enable-color

Enable output color for Postscript output and PDF output. This option works only with option --enable-gaf or if gaf installed on your computer.

--image-out-size=<"width x height">

Set the output image size of your schematics for Web/HTML presentation. The width and height defined as string expression i.e. "1024 x 768", "1152 x 864", etc. Default image output size is set as 1280 x 1024.

--large-paper-type=<"paper type">

Set the large paper type for Postscript and PDF print-out schematic. The value is one of the supported paper types. Default large paper type is A3. Please read the documentation for further information.

--normal-paper-type=<"paper type">

Set the normal paper type for Postscript and PDF print-out schematic. The value is one of the supported paper types. Default normal paper type is A4. Please read the documentation for further information.

SPICE Netlisting Option:

--column-pair=<pair>

Column pair number of circuit table in the generated SPICE3 netlist. Value in integer. Used only with option --create-subckt. You likely do not need to use this option, let gschem-finalizer automatically determine the circuit table column pair while configuring SPICE3 netlist.

--create-netlist-only

Create SPICE3 netlist only. The print-out generated only as SPICE3 netlist report-view.

--common-nets=<"list of common nets">

Set the list of common nets. The listed nets will not be renamed, although present within the twin schematics. Each pair is comma delimited.

--remove-unused-spice-models

Remove all unused SPICE models (and/or sub-circuit models) from the SPICE netlist, as they were defined but never used in the circuit.

--special-nets=<"list of special nets">

Set the list of special nets. The listed nets will not be detected as unnamed active nets. Each pair is comma delimited

--create-subckt

Enable sub-circuit model generation. Option --subckt-sch-file must also be specified. Optionally, you may include option --column-pair and --list-column-length.

--list-column-length=<length1[, length2][, length3]. . . >

List of length to be set for each circuit table column in the generated SPICE3 netlist. Length defined as integer, delimited by comma. Use only this option with option --create-subckt. You likely do not need to use this option, let gschem-finalizer automatically determine the circuit table column length while configuring SPICE3 netlist.

--spice-credit-text-file=<"path to SPICE credit text file">

Path to SPICE credit text file to be loaded.

--subckt-sch-file=<"base filename">

Set reference of base filename to be detected as a sub-circuit schematic. The specified filename is basename, not absolute path neither relative path.

--unhide-netname

Force netnames to be displayed if option --no-spice-test is set. Note that the netname that you set as hidden attribute will be kept hidden.

--use-vams-for-spice

Use vams backend (VHDL-AMS) instead of spice-sdb backend to pre-configure SPICE netlist. This option enables gschem-finalizer to generate SPICE netlist for digital circuit either mixed analog-digital circuit simulations using ngspice with XSPICE extension. You will like to use this option in case the limitations of spice-sdb or native spice backend in recognizing digital devices within gEDA gschem schematic. The following native TTL gates were supported, i.e: BUFFER, INVERTER, AND, NAND, OR, NOR, XOR, XNOR, TRISTATE, PULLDOWN, PULLUP, D FLIP-FLOP, JK FLIP-FLOP, TOGGLED FLIP-FLOP, SET-RESET FLIP-FLOP, D LATCH, SET-RESET LATCH, STATE MACHINE, FREQUENCY DIVIDER, RAM, DIGITAL SOURCE, OPEN-COLLECTOR BUFFER (since ngspice 22), and OPEN-EMITTER BUFFER (since ngspice 22). Some hybrid models were also supported: ANALOG-TO-DIGITAL NODE BRIDGE, DIGITAL-TO-ANALOG NODE BRIDGE, and CONTROLLED DIGITAL OSCILLATOR. The complex digital models were not supported (i.e. an instant BCD/BINARY COUNTER), so you must consider to create complex digital model as a sub-circuit from any supported primitive digital models if you want gschem-finalizer to deal with your complex digital circuit schematics.

--auto-invert-digital-ports

This option used with option --use-vams-for-spice to fix the SPICE netlist nets those connected to any inverted digital ports, so that you no need to add any digital inverter to your schematics to handle the inverted digital ports. This option deals ngspice behavior in handle the digital models (ngspice does not know whether any digital port marked as inverted (except the output ports of FLIP-FLOP models), while your schematic defines the inverted digital ports i.e. _RESET_ as usually RESET, _CLK_ as usually CLK, or etc. ). gschem-finalizer will add additional .model directives to define appropriate additional digital inverter models (actually a generic digital inverter). Additional new lines will be added in circuit to define circuit element contains REFDES, bypassed nets, and appropriate digital inverter model-name as value. Note that gschem-finalizer by with this option will add prefixes as: AIX_ for additional REFDES, invi_ as additional nets for inverted digital input ports, invo_ as additional nets for inverted digital output ports, and aix_inv_ as additional digital inverter model, and therefore you may not apply such prefixes into your schematics. This option will not touch the output port of FLIP-FLOP either STATE MACHINE models marked as _Q_. This option will not effect to the native TTL gate models i.e DIGITAL SOURCE, BUFFER, INVERTER, AND, NAND, OR, NOR, XOR, XNOR, PULLDOWN, and PULLUP. The NULL digital ports will be ignored.

--ground-to-zero

Rename all nets marked as GND into 0 nets. This option usable with option --use-vams-for-spice.

Testing Options:

--force-test-all

Force the twin schematics passed through ngspice simulation, i.e. if you are designing dual-channel hi-fi stereo system, which then both channel will be tested. Using this option precedes heavy SPICE simulation although guarantee more accurate operating point results.

--hide-all-op

Hide all operating points from being displayed on the final schematics. The feature within this option actually will turn all netname attribute into hidden.

--no-op

Set the gschem-finalizer to be not updating operating point results on the final schematics. The netnames will be preserved as in the source schematic.

--test-wait=>timeout>

Set timeout to wait schematic test in N seconds. Default timeout is set in 30 seconds.

--transient-init-step=<value>

Specify transient initial step value (TSTEP) to test your schematics. Value in micro-second. Note that very short initial step may cause the test reaching up time out. You must set the timeout value appropriately within option --test-wait to not conflict with this option. Default set value by gschem-finalizer is 100 (in uS).

--transient-init-stop=<value>

Specify transient initial stop value (TSTOP) to test your schematics. Value in millisecond, must be smaller then maximum transient time (--transient-init-max). Note that very long stop time may cause the test reaching up timeout. You must set the timeout value appropriately within option --test-wait to not conflict with this option. Default value set by gschem-finalizer is 200 (in mS).

--transient-init-start=<value>

Specify transient initial start value (TSTART) to test your schematics. Value in millisecond, must be smaller than initial stop (--transient-init-stop) and maximum transient time (--transient-init-max). Default value set by gschem-finalizer is 100 (in mS).

--transient-init-max=<value>

Specify transient initial stop value (TMAX) to test your schematics. Value in millisecond. Note that very long maximum transient time may cause the test reaching up timeout. You must set the timeout value appropriately within option --test-wait to not conflict with this option. Default value set by gschem-finalizer is 250 (in mS).

--print-test-result

Display the test result on terminal console. This option will be executed if --no-spice-test is not set. Note that this option will not provides interactive media. The test result only redirected to STDOUT without reading STDIN in case ngspice process has been actually shutdown while the test result is being displayed.

--no-spice-test

Disable ngspice testing the schematics. The SPICE netlist will still be generated, but: (1) all visible netnames in the final (copy of) schematics will be hidden and (2) the print-out schematics generated without operating points.

PCB Layouting Options:

--with-pcb

Enable feature schematics to PCB annotations. Optionally, you may use --pcb-only (with different effects).

--pcb-only

Use gschem-finalizer to update PCB layout only. Testing the schematics by ngspice not available. However, the test will still be executed over duplicate REFDES and unnamed active nets.

--pcb-new-lib=<"new lib. path">

Additional PCB footprints library directory path. It maybe relative to current working directory.

--pcb-autoplace-new-parts

Option to auto-place new added parts rather then disperse (default is disperse). Auto-placing parts let you easy pick each new added part. Using this option may cause PCB loaded with prompt.

--pcb-refresh-parts

Refresh all parts as the parts in library has renewed or changed. All parts will be replaced with footprints those have identical name currently available in library. This option probably cause undesired result, therefore you will be prompted to make sure you are seriously using this option.

--pcb-loop-replace-parts=<max. loop>

Maximum loop count to repeat parts/footprints replacements. Allowed value is greater than 5. This option will be used on replacing parts/footprints either on executing option --pcb-refresh-parts. Default maximum loop count is set to 10.

--pcb-kicad-export

Generate Kicad PCB netlist from the schematics marked for PCB layouting. The generated netlist is compatible Kicad EESchema Version 1. 1. Note that netlist not include Kicad EESchema library references. This option will be ignored if option --with-pcb is not set or if specific option to enable PCB layouting is not set.

--pcb-kicad-export-only

Similar to option --pcb-kicad-export, unless without dealing GEDA PCB layouting. This option will be ignored if option --with-pcb is not set or if specific option to enable PCB layouting is not set.

SCHEMATIC ANNOTATIONS

Annotation useful to figure up your schematic to be portable with Gschem-finalizer extensions. You can place annotations as text on your schematic begin with "@", i.e: @date_created, @license, @page, @pages, and etc. Gschem-finalizer will interpret the annotations to reference in executing appropriate extension functions. Some annotations compatible only with specific option, i.e @pcb only compatible with option --with-pcb and/or --with-pcb.

Schematic Properties

@basic_technology

Place basic technology description text on schematic, as its value specified with option --basic-technology.

@current_version

Place the project version on schematic page as text, as its value specified with option --project-version.

@date_created

Place the date of project creation/revision on schematic page as text. Date is generated automatically.

@designer

Place the designer name on schematic page as text, as its value specified with option --designer.

@email

Place the email address on schematic page as text, as its value specified with option --email.

@inventor

Place the inventor name as text on schematic, as its value specified with option --inventor.

@license

Place the license text on schematic, as its value loaded from a text file as specified with option --license-file.

@package_name

Same as @project_name.

@page

Place current page number as text on schematic. The value is generated automatically by the program.

@pages

Place total page count as text on schematic. The value is generated automatically by the program.

@project_name

Place the project name on schematic page as text, as its value specified with option --project-name.

@rev_count

Place the revision count as text on schematic, as its value specified with option --set-rev-count.

@revision_date

Place the revision date on schematic page as text. Revision date is generated automatically in format d/m/Y.

@url

Place the URL address on schematic page as text, as its value specified with option --url.

Printout Control

@noprint

Set a schematic page/file to exclude from compiled as multipages printout.

SPICE Netlisting Control

@net_alias=[orig|alias]

List the net alias to display in printout schematic, to replace original natname, as NGSPICE testing is disabled by with option --no-spice-test.

@notest

Set a schematic page/file to exclude from NGSPICE test.

@subckt_name=[sub_circuit_name]

Set name of sub-circuit schematic.

@swap=[current pin number|swapper pin number]

Swap or barter the pin number. This useful to swap transistor symbol pins from any order to be CBE in SPICE netlist output.

@twin

Set a schematic page/file to as twin schematic of another one.

@twinparts

List the twin parts to exclude from test.

PCB Netlisting Control

@common_pcb_nets

Guide the PCB layouting extension to recognize common PCB nets. This annotation effects with option --with-pcb or --pcb-only.

@pcb=[pcb file name]

Guide the PCB layouting extension to create PCB with filename as specified. The file name is specified as basename, not a path to a file.

@rename=[orig|alias]

Rename a part in schematic to follow the standard part name in PCB.

@rename=[from|to]

Rename parts from it's original name. This annotation will effect with option --with-pcb or --pcb-only.

PAPER TYPE FOR PRINTOUT

Paper type to be specified with option --normal-paper-type and --large-paper-type, to figure the page size of output in format Postscript and PDF.

Paper TypeDimension
Letter8.5 in x 11 in
Legal8.5 in x 14 in
Statement5.5 in x 8.5 in
Tabloid11 in x 17 in
Ledger17 in x 11 in
Folio8.5 in x 13 in
Quarto8.472 in x 10.833 in
10x1410 in x 14 in
Executive7.5 x 10 in
A8.5 in x 11 in
B11 in x 17 in
C17 in x 22 in
D22 in x 34 in
E34 in x 44 in
A084.10 cm x 118.90 cm
A159.40 cm x 84.10 cm
A242.00 cm x 59.40 cm
A329.70 cm x 42.00 cm
A421.00 cm x 29.70 cm
A514.80 cm x 21.00 cm
A610.50 cm x 14.80 cm
A77.40 cm x 10.50 cm
A85.20 cm x 7.40 cm
A93.70 cm x 5.20 cm
A102.60 cm x 3.70 cm
A111.80 cm x 2.60 cm
A121.30 cm x 1.80 cm

SUPPORTED DIGITAL MODELS

Gschem-finalizer supports the digital models recently available with ngspice package as they were standard in SPICE 3.

Basic Digital Models

  • BUFFER (d_buffer)
  • INVERTER (d_inverter)
  • AND (d_and)
  • NAND (d_nand)
  • OR (d_or)
  • NOR (d_nor)
  • XOR (d_xor)
  • XNOR (d_xnor)
  • TRISTATE (d_tristate)
  • PULLDOWN (d_pulldown)
  • PULLUP (d_pullup)
  • D FLIP-FLOP (d_dff)
  • JK FLIP-FLOP (d_jkff)
  • TOGGLED FLIP-FLOP (d_tff)
  • SET-RESET FLIP-FLOP (d_srff)
  • D LATCH (d_dlatch)
  • SET-RESET LATCH (d_srlatch)
  • STATE MACHINE (d_state)
  • FREQUENCY DIVIDER (d_fdiv)
  • RAM (d_ram)
  • DIGITAL SOURCE (d_source)
  • OPEN-COLLECTOR BUFFER (d_open_c, since ngspice V. 22)
  • OPEN-EMITTER BUFFER (d_open_e, since ngspice V. 22)

Hybrid Models

  • ANALOG-TO-DIGITAL NODE BRIDGE (adc_bridge)
  • DIGITAL-TO-ANALOG NODE BRIDGE (dac_bridge)
  • CONTROLLED DIGITAL OSCILLATOR (d_osc)