Usage

KiABOM detects the use of an ‘MPN’ field in the schematic symbols. The field name is very specific and case sensitive. It also ignores searching for part numbers with the values ‘Generic’, ‘TBD’, and ‘Manufacturer’s Stock’ in the MPN field. Therefore, to use KiABOM, create an MPN field in each symbol and add the MPN in that field description.

You can use the generator either through the terminal or through KiCad itself. See the relevant sections below for more information and the Example Uses section for some example command options. Supports all modern KiCad versions using Python v3.9+.

Using Through a Terminal

KiABOM can be treated (depending on your installation) as an executable application or a Python script. In both cases options would be passed to it the same way. See the Options section for the list of options and example commands you can use with the tool.

Using Through KiCad

There are three ways of using KiABOM through KiCad. One is via the Legacy BOM generator menu, the second one is the netlist exporter, and the third one is with a jobset file. All methods use the Generator command line format as specified in the KiCad documentation. The options used with each method also get saved by KiCad, so you only need to set your configuration once.

Depending on how KiABOM was installed, you may want to use different commands. If using the executable you would use,

kiabom "%I" "%B".csv [options]

If using a Python installation you would use,

python path/to/kiabom.py "%I" "%B".csv [options]

And if using a Python virtual environment you would use,

path/to/python/venv/bin/python /path/to/kiabom.py "%I" "%B".csv [options]

These commands use the current schematic as input to KiABOM and the project name as the CSV name. The .csv extension can be changed to .html or .txt and the output format will be detected and changed by the generator.

Via Legacy BOM Generator

  1. In any schematic go to Tools -> Generate Legacy Bill of Materials… and click the + sign under the ‘BOM generator scripts’.

  2. Find either the KiABOM executable or Python file, select it, and add an appropriate generator name.

  3. Depending on your installation the command in the text box will change. See the commands listed above for which commands to use.

  4. Clicking Generate should then output the auto-generated BOM in the project root directory.

This method is the recommended method as you can see the output of KiABOM in the dialogue box if anything fails.

Via Netlist Exporter

  1. First open the schematic editor in any project and go to File -> Export -> Netlist….

  2. Click Add Exporter, add the title KiABOM and depending on your installation the command in the text box will change. See the commands listed above for which commands to use.

  3. Clicking Export Netlist should then output the auto-generated BOM in the project root directory.

This method is only listed to show that it is possible and it is definitely viable even if it’s not the recommended way. The only quirks with this method is that there is no feedback to the user of what happened, and it is done through the Netlist generator.

Via a Jobsets File

  1. To use KiABOM with a jobsets file, the schematic XML must also be generated. To accomplish this, in a jobsets file create a Special: Execute Command job type and in the Command: text box, enter the following to generate the schematic XML file,

kicad-cli sch export netlist --format kicadxml "${PROJECTNAME}.kicad_sch"

  1. Then create another job of the same type and input your KiABOM command with your options, as given in the previous two sections. Depending on your installation the command in the text box will change. See the commands listed above for which commands to use.

Note: Due to jobsets not using format specifiers, instead of %I and %B you would use ${PROJECTNAME} as used in step 1 above.

  1. Make sure to save this jobsets file.

Using With Supplier BOM Tools

Some suppliers offer BOM tools that assist with ordering parts if you already have the MPNs or the Supplier Order Codes. Using KiABOM’s CSV output format, the BOM can be uploaded to these tools, and by specifying the correct column types, the parts can be automatically detected and then ordered. See below for example instructions for how to do that with Mouser’s BOM Tool. DigiKey myLists is their version of a BOM tool and has a very similar process.

Go to the Mouser BOM tool and upload your BOM CSV file. In the next page you will set the column types. Assuming you are using the default column preset, set the Quantity column as Quantity 1, Description as Description, Manufacturer as Mfr Name, MPN as Mfr Part Number, and the Order Code as the Mouser Part Number. In the next page set the appropriate settings and once done proceed to the next page. From here you can add the parts listed to your basket and submit an order. Multiples of the same BOM can be added to basket for multiple boards using the same BOM for a single board.

Some tips for this process is that the --no-headers column might need to be used to get rid of the column headers before inputting to a BOM tool. Also using --remove-ignore-mpn-parts will remove parts with the ignore MPN values from the BOM, thus saving you time removing these from the result list.

Advanced Customisations

KiABOM is written such that it is as portable and as easy to understand as possible. For this reason, advanced users are encouraged to edit the source code for having their custom column and group presets. After modifying the source pyinstaller can then be used to generate an executable if desired by doing,

pyinstaller .\kiabom.py -F --add-data ../LICENSE:. --icon ..\images\kiabom-icon.ico

Adding User Custom Presets

To add custom column presets add a dictionary entry to the column_preset_dict defined after the import statements. Any of the listed supported column values (shown by using the --list-supported-columns option) can be entered and then your preset can then be used by using the --column-preset PRESET option.

For custom grouping presets it is the same process but by using the group_preset_dict and by specifying yourcustom preset with --group-preset PRESET. A limitation placed for the group presets is that they should contain at least the Value and Footprint group values. This is in place to promote a good standard of BOM generation.

Both of these preset groups can be used together by specifying --preset PRESET which uses preset_dict to specify both the group and column presets. The presets in this variable are in a COLUMNS PRESET, GROUP PRESET format. See below for an example on how to use these variables for customisation (dots imply ommission of the other entries),

column_preset_dict = {
    .
    .
    .
    "custom-columns": [
        "Value",
        "Footprint",
        "MPN",
        "Custom Field",
    ],
}

group_preset_dict = {
    .
    .
    .
    "custom-group": [
        "Value",
        "Footprint",
        "Custom Field",
    ],
}

preset_dict = {
    .
    .
    .
    "custom": [
        "custom-columns",
        "custom-groups",
    ],
}

Then your custom preset can be used with,

kiabom input_xml output.csv --preset custom

Options

The --help page for KiABOM is shown below along with some examples,

usage: kiabom.py input_xml output_file [options]

Automatic BOM tool for KiCAD.

positional arguments:
  input_xml             input the path to the XML file generated from the KiCAD schematic.
  output_file           name of the output CSV or HTML file. It will be outputed in the same directory where the script is run from.
options:
  -h, --help            show this help message and exit
  --version             output the KiABOM version.
  --info                append to the output some general info about the generated BOM like, board quantity, schematic name, component count, date, and generator used.
  --no-headers          don't output BOM column headers.
  -k, --no-kicost       disable the KiCost integration.
  --preset PRESET       specify both the columns and group presets at the same time with this option. Both '--columns-preset' and '--group-preset' overwrite this option.
  --columns-preset COLUMNS_PRESET
                        set a BOM preset for what part data should be outputed. Overwrites '--columns' if it comes after. Use '--append-columns' to append columns to a preset. Choose between 'Default', 'Minimal', 'No-KiCost', and 'Mage'.
  --group-preset GROUP_PRESET
                        choose a group preset. Available ones are 'Default', 'Minimal', and 'Mage'. Append to a preset with '--append-groups'.
  -g, --group-by GROUP_BY
                        choose what symbol fields to group by, Grouping by 'Value' and 'Footprint' is mandatory. Choose up to 5 additional fields to group by. Use values separated by commas and place values in quotes in they contain spaces
  -c, --columns COLUMNS
                        set the columns to be outputed. Use values separated by commas and place values in quotes in they contain spaces. Overwrites '--preset' if it comes after. Use '--    append-columns' to append columns to a preset and `--list-supported-columns' to list valid column values.
  -a, --append-columns APPEND_COLUMNS
                        append columns to the selected preset. Use values separated by commas and place values in quotes in they contain spaces.
  --append-groups APPEND_GROUPS
                        append to a group preset.
  --ignore-mpns IGNORE_MPNS
                        add more MPN field values to ignore. This option appends the default option of 'Generic','TBD','Manufacturer's Stock', and '' (blank). Use values separated by commas and place values in quotes in they contain spaces.
  -p, --primary-supplier PRIMARY_SUPPLIER
                        select primary supplier from supplier list. View by executing KiABOM with '--list-suppliers' option.
  -s, --secondary-supplier SECONDARY_SUPPLIER
                        select secondary supplier. View by executing KiABOM with '--list-suppliers' option.
  -d, --download-datasheets
                        optionally donwload the datasheets for the parts with valid URLs in a 'Datasheet' field. Files get downloaded to a 'datasheets' folder in the current working directory.
  -u, --primary-only    only use the primary supplier.
  -q, --quiet           silence warnings
  --kefbom, --keep-exclude-from-bom
                        include the components with the 'Exclude from BOM' property set.
  --kefboard, --keep-exclude-from-board
                        include the components with the 'Exclude from Board' property set.
  -b, --board-quantity BOARD_QUANTITY
                        select board quantity, default is 1.
  --sum                 add a summation of the total price to the end of the table.
  --currency CURRENCY   select the currency, currently supports 'GBP', 'EUR', and 'USD' options.
  --remove-ignore-mpn-parts
                        remove parts from the BOM that contain the ignore MPN values. This options was implemented specifically for supplier BOM tools.
  --list-suppliers      list supported suppliers.
  --list-presets        list built-in presets.
  --list-column-presets
                        list built-in column presets.
  --list-group-presets  list built-in group presets.
  --list-supported-columns
                        list supported column values. Any symbol field can also be a column value.

Example Uses

The examples listed here will assume the executable is installed on your system but they could easily be replaced with python kiabom.py input_xml output_file [options].

Default behaviour for the tool is to generate a CSV in the default column and grouping presets. The auto-generated name of the output is ‘kiabom-output-HHMMSSddmmyy.csv’ which also contains the date and time of generation. The output will contain headers, will be for 1 board of your schematic, use GBP as the currency, and will retrieve the parts data from the suppliers.

kiabom input_xml

You can fully customise the outputted columns based on the list shown from the --list-supported-columns option. For example you can create a BOM with no headers, in HTML format, without parts data, that only has the Designator, DNP, Unit/Reel Price, Footprint, and Value,

kiabom input_xml output.html --no-headers --columns "Designator,DNP,Unit/Reel Price,Footprint,Value" --no-kicost

Adding a symbol field to the BOM can be done by using the appropriate preset and appending columns to that. Grouping can also be done on that field. You can even only output one supplier instead of two,

kiabom input_xml output.csv --append-columns Rating --append-groups Rating --primary-only

More information can be outputted than just the parts data like generator info and board quantity by specifying --info and to get a total price sum by using --sum.

kiabom input_xml output.csv --sum --info

Datasheets can be downloaded by specifying --download-datasheets, which downloads the files located at the links in the ‘Datasheet’ symbol field in a ‘datasheets’ folder in the current directory. The symbols with the ‘Exclude From BOM’ and ‘Exclude From Board’ properties can also be used in the BOM with --kefbom and --kefboard.

kiabom input_xml output.csv --download-datasheets --kefbom --kefboard

Currently only two suppliers are supported (Mouser and DigiKey), but in the future the suppliers will be specified with the appropriate options.

Presets can be used to simplify the columns and groupings used in the BOM. For example to output a BOM for JLCPCB, you would execute,

kiabom input_xml output.csv --preset jlcpcb

which is the same as,

kiabom input_xml output.csv --columns-preset jlcpcb --group-preset jlcpcb

Using the command above you can mix and match columns and group presets,

kiabom input_xml output.csv --columns-preset default --group-preset minimal

Contributions are welcome for any presets or columns you would like the generator to support!

Lastly, editing the generator file is encouraged to create your own presets. See the Advanced Customisations section for how to customise KiABOM’s source code to get more out of the generator.