Special techniques for KiCad

2016-05-06  Robin Whittle rw@firstpr.com.au




KiCad - http://kicad-pcb.org - is a full-featured open-source schematic and PCB design program. 

I am active on the KiCad Users mailing list is https://groups.yahoo.com/neo/groups/kicad-users/info .

There is also a web-based KiCad Users Forum: https://forum.kicad.info .  This has a higher volume of messages than the mailing list, but I prefer mailing lists for in-depth discussions.

Contents:

#kpv
01 - Adding a field to schematic components so their value on the PCB can be different from their value on the schematic.
#bomw
02 - Creating a Bill of Materials from KiCad running under Windows.
#bomf
03 - Initial ideas for fancy BOMs with part numbers and stock numbers
#tfn
04 - Template Field Names in Eeschema 4.0.2-stable - later known as Default Fields
#kds
05 - Data Structures for KiCad - especially for generating BOMs
#conv
06 - Converting from old Protel files, including from Autotrax for DOS (1989).
#smtf
07 - Deciding exactly on SMT footprints using standards documents, software etc.
#links
08 - Links to other sites.



#kpv

01 - Adding a field to schematic components so their value on the PCB can be different from their value on the schematic

On 2016-04-22 I asked on the mailing list about how I could have a particular device in the schematic have one value displayed there, such as BZT52H-B5V6) but export via the Netlist some other value, including perhaps just a space which is invisible, to the PCB program, so that the value field for the matching device in the PCB is different, such as 5V6 or not visible at all, including as gray "invisible" text on the Pcbnew screen.

In the absence of an answer, I developed a way of doing it:

1 - Add a new field named PCBVal to the device in the schematic.  (This and the following step can also be done to a component/part in the Eeschema component library.)

2 - Set the value of this field to whatever I want, such as 5V6 or just a space " ", since it cannot be empty.

3 - Generate a netlist in the usual way from Eeschema.  The netlist contains the new field information.

4 - Process the netlist to make a modified netlist file in which the contents of the PCBVal field for each component is copied to its value field. 

5 - Read the modified netlist into Pcbnew.

This works fine for me.

Two usage scenarios are explained in the source code and in the page linked to below.  A third scenario follows below.  The program to do this is public domain C++, with 64 bit and 32 bit Windows executables. The source code is plain C++ and so can be compiled for Linux or any other OS. Please see this directory:

kicad-pcb-value/

A third usage scenario:

I have a 0.01 uF SMT capacitor in a 3216 (metric) 1206 (imperial) package.  It is no use having "0.01uf" in the BOM since there are a plethora of capacitor types.  I need a COG (AKA NPO) 5% one, not some X7R device whose capacitance varies enormously with temperature and/or voltage. 

(See Mark Fortunato's widely cited article from EDN in 2013 [ link http://pdfserv.maximintegrated.com/en/an/TUT5527.pdf "Temperature and Voltage Variation of Ceramic Capacitors, or Why Your 4.7µF Capacitor Becomes a 0.33µF Capacitor".)

The TDK part number is CGA5C2C0G1H103J060AA and Mouser's part number is C820-CGA5C2C0G1H103J.  I need one of these in the BOM, but I don't want these cluttering the schematic or the PCB, including in gray "invisible" text when designing the PCB.  (See also the fancy BOM section below: #bomf .)

Initially, I used the full TDK part number for the schematic component's value, make it invisible in the schematic, add a PCBValue field, set its value to 0.01uF and make this visible in the schematic with a type size I like.  The latter value now appears in both the schematic, the PCB design and PCB itself, where it is the "value" of the component in the PCB.

In light of what I found #bomf I could probably do this without the PCBValue field, but by setting the ordinary Value field to 0.01uf which would be fine in this case to appear in both the schematic and the PCB design, and add the manufacturer's part number, the Mouser stock number etc. into new fields created for these purposes.

A fourth usage scenario:

I want a value like 0.068uF for the schematic, but for space reasons, on the PCB: 683.

On 2016-04-25 I mentioned this and some of the sections below on the KiCad Users Forum: 

https://forum.kicad.info/t/enabling-the-pcb-value-to-differ-from-that-of-the-schematic-bom/2897

#bomw

02 - Creating a Bill of Materials from KiCad running under Windows

Here is a little cheatsheet on how to generate a BOM when running Eeschema 4.0.2-stable under Windows.  The Eeschema user manual (2016-04-25) instructs how to do it under Linux, but it is not immediately apparent how to do it under Windows. 
  1. Click the BOM icon on the top toolbar.

  2. Click the Add Plugin button.  This opens a file selection window for the directory:

    C:\Program Files\KiCad\bin

  3. Select the program there xsltproc.exe .and click "OK".

  4. Give this "plugin" (really a bunch of configuration data, specifying a plugin name and matching command line) a name, such as "XLSTPROC BOM".  The default command line:

    "C:\Program Files\KiCad\bin\xsltproc.exe" < "%I" > "%O"

    is not at all what we want.

  5. We need xsltproc.exe to use the supplied (and mentioned in the user manual) translation file which works from the intermediate netlist file to create a CSV format BOM file:

    C:\Program Files\KiCad\bin\scripting\plugins\bom2csv.xsl

    Edit the command line to be:

    "C:\Program Files\KiCad\bin\xsltproc.exe" -o "%O.csv" "C:\Program Files\KiCad\bin\scripting\plugins\bom2csv.xsl" "%I"

  6. With the relevant schematic project open in Eeschema, I can now generate a BOM by clicking the BOM icon in the top toolbar, selecting this plugin and clicking the "Generate" button.
The process seems to be, for a main schematic file D:\PCB\ABC\DEF.sch :
  1. An intermediate netlist file, in XML format, is generated in the above directory: D:\PCB\ABC\DEF.xml .

  2. xsltproc runs with its first two arguments specifying an output file D:\PCB\ABC\DEF.csv , the third argument being the above-mentioned bom2csv.xsl file, which contains the conversion instructions, and the fourth argument being the just-generated intermediate netlist file.  The command line, with this example, which appears in the window after I click the "Generate" button, is (2016-04-25, 4.0.2-stable):

    "C:/Program Files/KiCad/bin/xsltproc.exe" -o "D:/PCB/ABC/DEF.csv" "C:/Program Files/KiCad/bin/scripting/plugins/bom2csv.xsl" "D:/PCB/ABC/DEF.xml"

  3. The output CSV file is written in the project directory. 
This can be opened with LibreOffice Calc, MS Excel etc.  There is one line for each component.  The order seems to be that in which they were added to the schematic project.  For me, the columns were (before the changes documented in the next section #bomf):
I have some components in the design which have no pin numbers or footprints. They are just arrow symbols to show the direction of signal flow.  These do not appear in the BOM CSV file.  Likewise power symbols.

This means that some fancy techniques can easily be implemented with additional fields in some or all components, as mentioned in the next section.

#bomwlinks
This BOM CSV file does not collate similar components into a single line  See the third dot-point below for a way of achieving this.  There are various promising approaches to be found with a Google search for:

BOM collate KiCad

such as these Python scripts: https://github.com/hwstar/BOMtools .  Here are some other KiCad BOM generation links:



#bomf

03 - Initial ideas for fancy BOMs with part numbers and stock numbers

I had some initial ideas here but they are superseded by those in a section below #kds Data Structures for KiCad - especially for generating BOMs links to a page which has a more detailed account of a better approach.  Please see the links #bomwlinks above for some pages which concern attempts at data organization and BOM generation, written by people with much more experience than me.

#tfn

04 - Template Field Names in Eeschema 4.0.2-stable - later known as "Default Fields"

This feature is not explained properly in the Eeschema User Manual (2016-04-26).  Preferences > Schematic Editor Options > Template Field Names.  (For a recent nightly kicad-product-r6710.c1f0ab9-x86_64.exe there is a different kind of dialogue box, via Preferences > Schematic Editor Options > Default Fields.) 

Before discussing the high level functionality of this, there is a confusing user interface (it confused me and at least one other person) in 4.0.2-stable, as noted in bug 1389272:  The two text boxes and the tick box are for editing the currently selected line, with the result being visible if a second line is selected, a new line is added (which is what the "Add" button does) or if the "OK" button is pressed - but in the case of the OK button we have just a few milliseconds to see the changes before the dialogue box closes.  In the recent nightly build there is no such confusion, since there are no such text boxes or separate tick box - we simply edit the items in-situ in their line.

The only explanation of the functionality of what are now (in the latest nightly) called "Default Fields" is:

You can define custom fields that will exist by default in each component (even if left empty).

I found little discussion of this facility on the Web.  Here is my exploration trying to understand what this does.

The above explanation is misleading, since the fields do not in fact exist.  See below for a suggested revision to this text.

The configuration data for these additional field names, their default values and whether they are visible or not are stored as part of the Eeschema config data.  They are not part of the schematic or project files.

If I add such a default field named ABC, with visible default value def and if this is the only such default field then when I next edit a component in the schematic, I can see these, before the extra fields I added as described above: #bomf :



However, there is no such text ABC or def in the schematic file, if I do not actually change anything about this component, click the "Cancel" button and save the schematic project.

If I click the "OK" button then the component is changed, the def text appears in the centre of the component:



The saved schematic file is changed by the addition of a line, in this case field 4, with the previously existing fields 4 to 10 having their number incremented:

$Comp
L TR-NPN-SOT-23 DQ2
U 1 1 571C8647
P 10000 1950
F 0 "DQ2" H 10050 1600 50  0000 L BNN
F 1 "BC847" H 10050 1500 50  0000 L BNN
F 2 "0RWFP:SOT-23" H 10010 1810 10  0001 C CNN
F 3 "" H 10000 1950 50  0000 L CNN
F 4 "def" H 10000 1950 60  0000 C CNN "ABC"
F 5 "!!!" V 10000 1950 50  0001 C CNN "PCBVal-"
F 6 " " H 10000 1950 50  0001 L BNN "PN"
F 7 " " H 10000 1950 50  0001 L BNN "SN"
F 8 "1704823" H 10000 1950 50  0001 L BNN "SN-e14"
F 9 " " H 10000 1950 50  0001 L BNN "SN-MO"
F 10 " " H 10000 1950 50  0001 L BNN "SN-DK"
F 11 " " H 10000 1950 50  0001 L BNN "SN-OC"
    1    10000 1950
    1    0    0    -1 


So my understanding is that these Default Fields will be added to every component in the schematic which is edited, even just by opening the edit dialogue box and clicking OK.  Once this has happened, the edit dialogue box looks identical to how it did previously, see the image two before.

So the Default Fields add visible and editable lines to the component edit dialogue box, with this data added to the component if the "OK" button is clicked.

This functionality is repeated in the Eeschema component library editor, using the T icon on the top toolbar, once the changed library file has been saved, and with live update to the in-memory version of the library Eeschema uses even if the library file has not been changed yet, but if the "upwards green arrow" icon in the top toolbar is clicked.

In both cases, I think that subsequent edits will not cause a Default Field item to overwrite the field of the same name in the schematic or library component if the field of the same name has had its value or visibility changed.


Therefore, this Default Fields facility is a quick way of adding new fields to components in schematics and schematic libraries, by editing each such component and clicking "OK", with or without any changes to the visibility of value of the fields which are added by this process.

I suggested (bug report https://bugs.launchpad.net/kicad/+bug/1575100) a revision to the Eeschema user manual for the explanation of "Template Field Names", now known as "Default Fields" in the latest nightly:

Default Fields are a mechanism for easily introducing additional fields into components in schematics or component definitions in schematic libraries.

Each Default Field consists of a field name, a default value for this field - which can be empty - and a flag which controls whether the value of this field will be visible in the schematic editing screen and the printed schematic.

These configuration items are part of the Eeschema configuration and are not part of any schematic sheet or project.

The one or more Default Fields specified here do not exist in any components in schematics or in  schematic libraries until each such component is edited and the "OK" button is pressed in the edit dialogue box.  Then, the one or more Default Fields are added to the already existing fields for this component, starting at field 4, with any previously existing fields 4 and above being renumbered accordingly.  Changes can be made to the value and/or visibility flag during this initial edit session or at any subsequent time. 

Later changes to the default value of a Default Field will not affect the value of fields which have already been added to components.  Once one or more fields have been added to a component, each also has parameters for position, size and orientation of the text, when displayed in the schematic.



#kds

05 - Data Structures for KiCad - especially for generating BOMs

Please see the separate page kicad-data-structures/ for an account at my initial attempts at creating and populating fields in Eeschema schematic and library components for the purposes of helping with parts ordering etc. 

I was able to get a grouped BOM (all components which are the same accounted for on a single line) as a CSV file, very nicely, with Wolf Walter's .SLT file.  This worked fine with the new fields I added to schematic components.


#conv

06 - Converting from old Protel files, including from Autotrax for DOS (1989)

On 2016-02-13 I started a thread on converting from old DOS Autotrax PCB files, via Protel 99, through various other stages to generate KiCad PCB files.  This is also a way of transferring PCB components ("footprints" in KiCad parlance) from these old systems into PCB files from which they can be added to the KiCad footprint library.  The techniques discussed in this thread lead to a bug report https://bugs.launchpad.net/kicad/+bug/1547822 which resulted in Eldar Khayrullin improving the import facility for P-CAD ASCII files, which can be exported from Altium.

So the path of conversion is from DOS Autotrax to Protel 99, and from there to a free trial version of Altium, which exports P-CAD ASCII files which can be imported reliably into KiCad.  Initially I used Eagle in one of the later steps too, but the improved import facility makes this unnecessary.

Search engine bait:  Protel to KiCad; Autotrax to KiCad.

#smtf

07 - Deciding exactly on SMT footprints using standards documents, software etc.

It turns out that deciding on exact dimensions of SMT pads for resistors, capacitors, diodes, transistors - and probably everything else -  is a Black Art.  This is not the sort of problem I wanted to deal with while taking my first steps in designing SMT boards, but it can't be avoided.  I started a thread in the KiCad Users Mailing List on 2016-02-24 about what I found in terms of standards documents such as IPC-7351C, software and the like which helped with these decisions.  The discussion was very fruitful.

A note to anyone starting with KiCad: be sure to establish your own libraries for both schematic components and PCB footprints (previously known and "modules").  This is not clearly explained in the documentation.  This has been explained numerous times in the mailing list, most recently in discussions starting on 2016-04-19.  It takes a while to understand what these libraries are and how to edit them.  The GitHub libraries are a starting point - it may be a good idea to start with some of these items and modify them to suit your exact purposes.  Otherwise, with a bit more experience, it can be best to start from scratch - or for schematic components with lots of pins, see the links section below. 

#links

08 - Links

A web-based system for creating schematic components (such as to import into the Eeschema library editor) for large DIP devices.  This is particularly handy for creating schematic components with large numbers of pins, such as with 28 pin DIP PIC chips etc.  With a text file of pin numbers and names, a little work with the web page, I was able to make a perfectly satisfactory schematic component:

http://kicad.rohrbacher.net/quicklib.php

A link farm of numerous KiCad-related sites.  I will not try to duplicate it here - please check it out:

http://www.kicadlib.org/Kicad_related_links.html

This is part of a site devoted to sharing KiCad libraries:

http://www.kicadlib.org

A system for using a schematic's BOM output to find prices of parts at multiple distributors:

https://github.com/xesscorp/KiCost

Update history:


© Robin Whittle 2016 First Principles and Real World Interfaces