MSEkicadBOM Tutorial

This tutorial shows how to work with MSEkicadBOM using the KiCad "complex_hierarchy" example.

1 Installation

Download the MSEkicadBOM package for your system from:
https://sourceforge.net/projects/mseuniverse/files/msekicadbom/
Extract it to a directory of your choice (yourdidectory).
MSEkicadBOM uses Firebird 3: https://firebirdsql.org/
Please download it from https://www.firebirdsql.org/en/firebird-3-0/ and install the package.
If you use 32 bit MSEkicadBOM select 32 bit Firebird, if you use 64 bit MSEkicadBOM select 64 bit Firebird.
In order to view and print documents a Postscript viewer is needed. On Linux there normally at least one is installed by default (Okular, Evince, Ghostview...).
For Windows there is for example GSView:
http://pages.cs.wisc.edu/~ghost/gsview/get50.htm
In order to produce PDF-files Ghostscript is needed. On Linux it is normally installed by default. On Windows use:
https://ghostscript.com/download/gsdnld.html The "GNU Affero General Public License" versions are free.

Windows:
Start yourdirectory\msekicadbom.exe, click Global Settings. Enter the paths to the tools in Postscript viewer, ps2pdf-script (ps2pdf.cmd), the Firebird directory and the Python interpreter (pythonw.exe).

Linux:
Start yourdirectory/msekicadbom, click Global Settings. Change the settings if necessary. Firebird directory normally can be empty.

2 Database setup

MSEkicadBOM uses a Firebird 3 database in order to store the data. Firebird can run in different server modes or as an embedded database without the need to run a database server. In the tutorial we use the embedded mode of Firebird. Start MSEkicadBOM, click Global Settings. In order to work without a Firebird server leave Hostname empty (embedded mode). In Databasename enter the path to the wanted database file.

Click Create Database, the database file will be created.
WARNING: Do not use the same database file concurrently for embedded and server access or concurrent embedded access off different users or there will be data corruption.

3 Create project

Do File-New Project, navigate to the wanted project directory, enter the project name in Name, click OK or press Enter.

The project settings dialog opens, add the schematics of the project to the list in Schematic Files.

Click OK or press Enter. The components were loaded.

MSEkicadBOM looks-up the VALUE, VALUE1 and VALUE2 fields in the database and marks not found components in magenta. Because the database is empty all rows are magenta colored.

4 Create components

Click in the right ED column or press F3 or DoubleClick in the row 1. An entry form with the according VALUE fields opens

Because there are several capacitors with different values in the design we make a component kind entry from where we can inherit from. Click on the ellipse button in Comp.-Kind. In the component-kind entry form press the + button in order to get a new record, enter the Name and the Description values. ${VALUE} is a macro and will be replaced by the actual VALUE field of the schematic. For a list of predefined macros see Macros.

In order to assign a footprint click on the ellipse button in the Footprint column in the grid at the bottom of the form.

Clicking on the + button creates an empty row. Name is the name used to select the entry in MSEkicadBOM, Ident is the value used in KiCad.
Click the ellipse button in Library column in order to create a footprint library entry.

It works like creating a footprint entry. Name is the name used to select the entry in MSEkicadBOM, Ident is the value used in KiCad. Press F10 in order to store the footprint-library record and to close the window. Select the new footprint library.

Press F10 in order to store the footprint record and to close the window.
Select the new footprint.

It is possible to assign multiple footprints to a component. MSEkicadBOM matches the FOOTPRINTINFO field of the schematic with the Footprintinfo column in order to select the appropriate footprint.
Press F10 in order to store the component-kind record and to close the window. Select the component-kind in Comp.-Kind, press F2 in order to store the record. Pressing F2 again makes it editable. Clicking the empty triangle button in DB-navigator switches to automatic editing mode.

Inherited values are displayed in gray and cursive, they can be overriden here. Hoovering over a value shows it with expanded macros. Close the window; the first row has been resolved and becomes white.

Click in the right ED column or press F3 or DoubleClick in the row of C2. C2 is also an electrolytic capacitor with the same footprint as C1 so we can use the same component type. Select "cp6" in Comp.-Kind, press F10.

The database items can also be edited by the Database main menu items. Do Database-Componentkinds.

The list dialog can be used to make simple edits. The drop-down-widgets above Name and Description can be used in order to search an entry. In order to have access on all fields select the wanted entry and press F3 or click on the ellipse button in DB-navigator or DoubleClick in the row of the wanted record.
We make an entry for film capacitors with "Discret:C2" footprint and one for ceramic capcitors also with "Discret:C2" footprint.
Press F3 in the row of "cp6", the component dialog with the "cp6" item opens. Press the + button in DB-navigator in order to get an empty record, enter the field values, press F2 in order to store the record.

The entry for ceramic capacitors is almost the same. Click the button with the two empty squares in order to get a copy.

Modify the necessary fields and press F2.

Close the DB-edit-windows, go back to the main window and resolve the rest of the capacitors. C9 needs a new component-kind which can be made by copying "cp6".

The procedure continues until all rows are resolved.

5 Create component-footprint file

Normally one would not set the FOOTPRINT field in schematic manually. MSEkicadBOM marks rows where the footprints of schematic and the database do not match in yellow color.
Make-Component-Footrintlist creates a *.cmp list with the database values which can be used in KiCad to update the FOOTRINT fields in the schematics. The filename can be defined in Project Settings-Make-Component-Footprint. The project name will be used as filename by default.
It is possible to replace footprint-libraries project specific. Add library-alias pairs in Project Settings-Footprint Library-Alias.

6 Create documentation

The definition of documentation stacks is stored in the database. Do Database-Docusets, click on the ellipse button in DB-navigator in order to activate the edit dialog, click on the + button in DB-navigator in order to create a new record. Set Name to "2la_nosmd_schem3" which means 2-layer conventional board with 3 schematics.

The printed pages are listed in Pages. Kind can be Title,Schematic,PCB-Layer-Plot, Drill-Map,Partlist or BOM. The Title column sets the additional text in headers or footers. Because we want to use the docustack for different projects we use macros. Add a Title and three Schematic rows.

Click on the ellipse button in the Schematic rows in order to set the file name of the Postscript plot of the schematic, we use macros too. Reduce the scale slightly so that it fits in given page size and padding.

In order to use this docustack in a project it is necessary to define the used macros in Project Settings-Macros.

Plot the schematics in KiCad Eeschema program in Postscript format, enter the macro names and the produced filenames without extension and enter the title macros.
In Project Settings-Make enter the board file name in Boardfile and select the docuset in Documentation sets.

The new docustack will be listed in main menu Make-Docustack and can be used to print the documentation. MSEkicadBOM loads the produced Postscript file in the program defined in Global settings-Postscript Viewer.

We'll add more pages. Do Database-Docusets, select "2la_nosmd_schem3" and press F3 in order to open the edit dialog. Add a PCB Layer-Plot,

Press F3, enter the ploted layers.

R means show reference, V means show value.
Hint: Color settings do not work because of problems with KiCad Python bindings.
Add an entry for the top layer

Drillmarks can be None, Small or Full.
Add an entry for the bottom layer

the drillmap

the partlist

and the BOM.

Enter the file name of the produced PDF.

Make-Docuset-2la_nosmd_schem3 produces this PDF.

7. Create production files

The definition of production file stacks is stored in the database. Do Database-Production File-Stacks, click on the ellipse button in DB-navigator in order to activate the edit dialog, click on the + button in DB-navigator in order to create a new record. Set Name to "2layer_nosmd". Enter the Output directory and the needed layerplots.
R='Show reference text', V='Show value text', I='Show invisible text'. Enter the needed drill files either individual files in the list or by activating All PT (all plated) and All NPT (all non plated) and setting the file Prefix and Suffix.

Creating of module position files is currently not possible because of problems with the KiCad Python bindings.

CSV part- or BOM-lists can be defined in Partlists.

Click on the ED button in order to define the listed fields.

Fieldname are the header values.
In Project Settings-Make select the definition in Production file stacks.

The new production file stack will be listed in main menu Make-Production-Files.