Interactive HTML BOM

To install and use the Interactive HTML BOM plugin in KiCad, refer to the official project wiki for detailed step-by-step instructions.

Wiki Link: https://github.com/openscopeproject/InteractiveHtmlBom/wiki/Installation

The generate_interactive_bom.py script is the CLI entrypoint for the KiCad InteractiveHtmlBom plugin. It allows you to generate an interactive HTML Bill of Materials from a KiCad PCB file.

Basic Usage:

python3 generate_interactive_bom.py <path_to_kicad_pcb_file>

Key Features:

• INI Configuration: Use the --use-ini flag to load settings from an .ini file. Command-line arguments will override values found in the INI file.
• Dialog Mode: Use the --show-dialog flag to trigger a GUI dialog for configuration (requires wxpython and that the INTERACTIVE_HTML_BOM_NO_DISPLAY environment variable is NOT set).
• Headless Mode: To run without a display (e.g., in CI/CD), set the INTERACTIVE_HTML_BOM_NO_DISPLAY environment variable.

The CLI supports configuration through three layers of precedence:

1. Command-line arguments (highest priority)
2. INI file settings (loaded via --use-ini)
3. Default settings (lowest priority)

When using --use-ini, the script performs a two-pass parse: it first identifies the PCB file and the presence of the --use-ini flag, loads the INI defaults into the parser, and then performs a final parse to allow command-line overrides.

Footprints are collections of pads, drawings, and metadata.

Key Fields:

• ref: Component reference.
• center: [x, y] coordinates.
• bbox: Bounding box containing pos, angle, relpos, and size.
• pads: Array of pad objects.
  • layers: F, B, or both.
  • shape: rect, oval, circle, roundrect, chamfrect, or custom.
  • type: th (through-hole) or smd (surface mount).
  • pin1: Boolean, indicates if this is the first pin (based on name or lexicographical order).
  • drillsize: For th pads, [x, y] (where x is diameter).
  • chamfpos: Bitmask for chamfered corners (left=1, right=2, bottom left=4, bottom right=8).
• drawings: Array of copper drawings (F or B) associated with the footprint.
• layer: The primary layer (F or B).

BOM Row Structure

A BOM row is a list of reference sets. A reference set is an array of tuples containing [reference_name, footprint_id] to handle duplicate references.

Configuration Structure

The config object controls the plugin's UI and rendering behavior:

config = {
  "dark_mode": bool,
  "show_pads": bool,
  "show_fabrication": bool,
  "show_silkscreen": bool,
  "highlight_pin1": "none" | "all" | "selected",
  "redraw_on_drag": bool,
  "board_rotation": int,
  "checkboxes": "checkbox1,checkbox2,...",
  "bom_view": "bom-only" | "left-right" | "top-bottom",
  "layer_view": "F" | "FB" | "B",
  "extra_fields": ["field1_name", "field2_name", ...],
}

Common issues and their causes:

• Missing wxpython: If wxpython is not installed and INTERACTIVE_HTML_BOM_NO_DISPLAY is not set, the script will exit with an error stating wxpython is required.
• Dialog Error: If you attempt to use --show-dialog while the INTERACTIVE_HTML_BOM_NO_DISPLAY environment variable is set, the script will exit with ExitCodes.ERROR_NO_DISPLAY.
• File Not Found: If the provided PCB file does not exist, the script exits with ExitCodes.ERROR_FILE_NOT_FOUND.
• INI Not Found: If --use-ini is used but no valid .ini file is found, the script exits with ExitCodes.ERROR_FILE_NOT_FOUND.
• Parsing Failure: If the PCB file cannot be parsed, the script exits with ExitCodes.ERROR_PARSE.

The exit_error function is a utility to log an error message and immediately terminate the application with a specific exit code.

Parameters:

• logger: A logger instance capable of calling .error(msg).
• code: An integer from the ExitCodes class.
• err: The error message or exception object to be logged.

def exit_error(logger, code, err):
    logger.error(err)
    sys.exit(code)

To use the Interactive HTML BOM functionality within KiCad, you must register the InteractiveHtmlBomPlugin. This is typically handled automatically by the plugin's entrypoint, but the core logic relies on the register() method of the InteractiveHtmlBomPlugin class.

from .ecad.kicad import InteractiveHtmlBomPlugin

plugin = InteractiveHtmlBomPlugin()
plugin.register()

On platforms other than Linux where standard KiCad plugin button support might be limited, the plugin uses a background thread to manually inject an "iBOM" button into the ID_H_TOOLBAR. This is triggered if plugin.pcbnew_icon_support is false and the platform is not Linux.

# Internal logic used when pcbnew_icon_support is False and platform is not Linux
if not plugin.pcbnew_icon_support and not sys.platform.startswith('linux'):
    t = threading.Thread(target=check_for_bom_button)
    t.daemon = True
    t.start()