Usage

You can use this plugin as installed Pcbnew Action Plugin or from command line as a standalone script.

For EasyEDA projects you can only use it as a standalone script.

Installed plugin

Open Pcbnew. Draw your board, make sure it has edges drawn on Edge.Cuts layer.

Save the file and press the button on the top toolbar.

If the button is not on the toolbar Tools -> External Plugins... -> Generate Interactive HTML BOM also works. Note that this menu is only present on builds that have KICAD_SCRIPTING_ACTION_MENU option turned on. In KiCad 5.1 and later you can choose to hide the plugin button in pcbnew preferences.

After launching the plugin a settings dialog will appear. Set your preferences and click Generate BOM. That will generate bom html page in the directory you chose.

If you don't want to configure the plugin every time you run it click Save settings after you've done it once and all the settings will be stored and will apply next time you use the plugin.

Standalone script

First determine which python version your KiCad installation supports. Go to Help->About KiCad->Show version info in main KiCad window and search for string KICAD_SCRIPTING_PYTHON3. If it says ON then you should use python3, otherwise python2. As of last update of this page only linux builds for recent distributions support python3, old linux builds, win and osx are still on python2. This plugin supports all platforms and python version combinations.

On Linux simply run this in terminal:

python2 path/to/InteractiveHtmlBom/generate_interactive_bom.py path/to/board.kicad_pcb

or

python3 path/to/InteractiveHtmlBom/generate_interactive_bom.py path/to/board.kicad_pcb

If you use python3 you can also add a symlink to generate_interactive_bom.py to a location on your $PATH, for example /usr/local/bin and then invoke the script from any location:

generate_interactive_bom.py path/to/board.kicad_pcb

On windows the trick is to use python that is bundled with KiCad so the command will look like this:

path/to/kicad/bin/python.exe .../generate_interactive_bom.py .../board.kicad_pcb

Note for EasyEDA users

For EasyEDA projects you first need to get the source file (go to board editor, Document -> EasyEDA File Source... and click download) then pass downloaded json file's location as a parameter to the script:

python .../generate_interactive_bom.py .../board.json

If you don't have KiCad installed you may need to install wxpython library.

pip install wxpython

EasyEDA Pro is not supported because it has different file format and no documentation.

Note for Eagle/Fusion360 users

Thanks to Funkenjaeger's contribution ibom now supports eagle/fusion360 board files natively.

Pass the board file directly to the script:

python .../generate_interactive_bom.py .../board.brd

Make sure you have the dependencies beforehand:

pip install wxpython jsonschema

Previous method with ulp script is now deprecated.

Note for Allegro PCB designer users

Use juulsA's skill script to generate json file and pass it to the script:

python .../generate_interactive_bom.py .../board.json

Make sure you have the dependencies beforehand:

pip install wxpython jsonschema

Command line options

All of the options that are configurable from the plugin settings dialog are also available from command line. You can also make the configuration dialog show up by running the script with --show-dialog flag. Run the script with --help flag to see all the options.

Note: all commands that have comma separated lists as arguments can escape the comma character with backslash ('\').

Example: --extra-fields "MFG\,MFG#,VEND1\,VEND1#" will yield fields with names MFG,MFG# and VEND1,VEND1#.

This is the output of --help flag as of editing this page:

usage: generate_interactive_bom.py [-h] [--show-dialog] [--version] [--dark-mode]
                                   [--hide-pads] [--show-fabrication]
                                   [--hide-silkscreen]
                                   [--highlight-pin1 [{none,all,selected}]]
                                   [--no-redraw-on-drag]
                                   [--board-rotation BOARD_ROTATION]
                                   [--offset-back-rotation] [--checkboxes CHECKBOXES]   
                                   [--bom-view {bom-only,left-right,top-bottom}]        
                                   [--layer-view {F,FB,B}] [--no-compression]
                                   [--no-browser] [--dest-dir DEST_DIR]
                                   [--name-format NAME_FORMAT] [--include-tracks]       
                                   [--include-nets] [--sort-order SORT_ORDER]
                                   [--blacklist BLACKLIST] [--no-blacklist-virtual]     
                                   [--blacklist-empty-val]
                                   [--netlist-file NETLIST_FILE]
                                   [--extra-data-file EXTRA_DATA_FILE]
                                   [--extra-fields EXTRA_FIELDS]
                                   [--show-fields SHOW_FIELDS]
                                   [--group-fields GROUP_FIELDS]
                                   [--normalize-field-case]
                                   [--variant-field VARIANT_FIELD]
                                   [--variants-whitelist VARIANTS_WHITELIST]
                                   [--variants-blacklist VARIANTS_BLACKLIST]
                                   [--dnp-field DNP_FIELD]
                                   file

KiCad InteractiveHtmlBom plugin CLI.

positional arguments:
  file                  KiCad PCB file

optional arguments:
  -h, --help            show this help message and exit
  --show-dialog         Shows config dialog. All other flags will be ignored.
                        (default: False)
  --version             show program's version number and exit
  --dark-mode           Default to dark mode. (default: False)
  --hide-pads           Hide footprint pads by default. (default: False)
  --show-fabrication    Show fabrication layer by default. (default: False)
  --hide-silkscreen     Hide silkscreen by default. (default: False)
  --highlight-pin1 [{none,all,selected}]
                        Highlight first pin. (default: none)
  --no-redraw-on-drag   Do not redraw pcb on drag by default. (default: False)
  --board-rotation BOARD_ROTATION
                        Board rotation in degrees (-180 to 180). Will be rounded to     
                        multiple of 5. (default: 0)
  --offset-back-rotation
                        Offset the back of the pcb by 180 degrees (default: False)      
  --checkboxes CHECKBOXES
                        Comma separated list of checkbox columns. (default:
                        Sourced,Placed)
  --bom-view {bom-only,left-right,top-bottom}
                        Default BOM view. (default: left-right)
  --layer-view {F,FB,B}
                        Default layer view. (default: FB)
  --no-compression      Disable compression of pcb data. (default: False)
  --no-browser          Do not launch browser. (default: False)
  --dest-dir DEST_DIR   Destination directory for bom file relative to pcb file
                        directory. (default: bom/)
  --name-format NAME_FORMAT
                        Output file name format supports substitutions: %f : original   
                        pcb file name without extension. %p : pcb/project title from    
                        pcb metadata. %c : company from pcb metadata. %r : revision     
                        from pcb metadata. %d : pcb date from metadata if available,    
                        file modification date otherwise. %D : bom generation date. %T  
                        : bom generation time. Extension .html will be added
                        automatically. (default: ibom)
  --include-tracks      Include track/zone information in output. F.Cu and B.Cu layers  
                        only. (default: False)
  --include-nets        Include netlist information in output. (default: False)
  --sort-order SORT_ORDER
                        Default sort order for components. Must contain "~" once.       
                        (default: C,R,L,D,U,Y,X,F,SW,A,~,HS,CNN,J,P,NT,MH)
  --blacklist BLACKLIST
                        List of comma separated blacklisted components or prefixes      
                        with *. E.g. "X1,MH*" (default: )
  --no-blacklist-virtual
                        Do not blacklist virtual components. (default: False)
  --blacklist-empty-val
                        Blacklist components with empty value. (default: False)
  --netlist-file NETLIST_FILE
                        (Deprecated) Path to netlist or xml file. (default: None)       
  --extra-data-file EXTRA_DATA_FILE
                        Path to netlist or xml file. (default: None)
  --extra-fields EXTRA_FIELDS
                        Passing --extra-fields "X,Y" is a shortcut for --show-fields    
                        and --group-fields with values "Value,Footprint,X,Y" (default:  
                        None)
  --show-fields SHOW_FIELDS
                        List of fields to show in the BOM. (default: Value,Footprint)   
  --group-fields GROUP_FIELDS
                        Fields that components will be grouped by. (default:
                        Value,Footprint)
  --normalize-field-case
                        Normalize extra field name case. E.g. "MPN" , "mpn" will be     
                        considered the same field. (default: False)
  --variant-field VARIANT_FIELD
                        Name of the extra field that stores board variant for
                        component. (default: None)
  --variants-whitelist VARIANTS_WHITELIST
                        List of board variants to include in the BOM. Use "<empty>" to  
                        denote not set or empty value. (default: )
  --variants-blacklist VARIANTS_BLACKLIST
                        List of board variants to exclude from the BOM. Use "<empty>"   
                        to denote not set or empty value. (default: )
  --dnp-field DNP_FIELD
                        Name of the extra field that indicates do not populate status.  
                        Components with this field not empty will be excluded.
                        (default: )

BOM page mouse actions

These are some less obvious things you can do with the generate BOM html page.

You can pan the pcb drawings by dragging with left mouse button, zoom using mouse wheel and reset view by right click.

Left click on a component drawing will highlight corresponding component group, unless it is currently filtered out by filter or reference lookup fields. If there are multiple components under mouse cursor, subsequent clicks will cycle through possible interpretations.

Clicking on Copy bom table to clipboard button (located to the right of filter field above the bom table) will copy tab separated values into clipboard. You can simply paste that data into Excel/Calc/Google sheets or any other spreadsheet software.

Clicking on bom column header cycles through sort modes of the table by that column. Note the small arrow indicator of the sorting order in the top right of the column header.

Double clicking checkbox column header sets/unsets all checkboxes in that column.

Drag column header to reorder columns.

Columns can be selectively hidden in the menu accessed from the top left corner of the bom table.

Touch support

Pinch zoom and drag panning is supported.

BOM keyboard shortcuts

Html page supports keyboard shortcuts to perform most tasks:

• ArrowUp / ArrowDown scroll through the bom table
• ArrowLeft / ArrowRight rotate the board
• Alt-R focuses reference lookup field
• Alt-F focuses filter field
• Alt-Z switches to bom only view
• Alt-X switches to bom left, drawings right view
• Alt-C switches to bom top, drawings bot view
• Alt-V switches to front only view
• Alt-B switches to front and back view
• Alt-N switches to back only view
• Alt-1 through Alt-9 toggle corresponding checkbox for highlighted bom row (if it exists)
• N ticks the Placed checkbox if it exists and moves the highlight to next row in the bom table