KiVar − Multi-Scope PCB Assembly Variants for KiCad

<img align='right' style='width:6em;' src='doc/kivar-icon.inkscape.svg'>

KiVar is a tool for KiCad PCB Assembly Variant and Micro-Variant selection, provided as platform-independent

• KiCad Plugin and
• Command Line Application.

PCB component variation rules for multiple independent design scopes are defined in component (i.e. symbol or footprint) fields. This allows for the complete low-level variation configuration to be contained in the schematic and board files without requiring external data outside the native KiCad design.

In addition, Variant Definition Tables (KiCad-independent CSV format) can optionally be used to summarize the configuration of these low-level scopes in classic flat variants, which can then be switched between.

[!NOTE] While KiCad 10 introduces native assembly variant support, KiVar's concept of multiple independent Aspects (or Micro-Variants) goes beyond a single flat variant switch. Each Aspect represents its own variation scope – such as LED current, boot source, I²C address, or output voltage – and each can be set independently or grouped into named Variants. This multi-scope approach continues to offer unique flexibility that complements or exceeds what common EDA variants provide.

Featured at KiCon Europe 2024

<a href='https://youtu.be/SpXH380KWUA' target='_blank'><img align='right' style='width:14em;' src='https://i.ytimg.com/vi/SpXH380KWUA/mqdefault.jpg'></a>

For a presentation of the concepts and features of KiVar, including a short tutorial, you can watch the talk "Managing PCB Assembly Variants with KiVar", which was recorded at KiCon Europe 2024 in Bochum, Germany.

The presentation slides including the embedded screencast videos can be downloaded from the pretalx page.

[!NOTE] The presentation covered KiVar 0.4.0, which did not yet support flat variants (added in 0.5.0).

Many thanks to Seth for the invitation.

Features

KiVar assigns PCB component values, field content, attributes (such as Do not populate, Not in position files or Not in BoM) and features (such as individual 3D model visibility or solder paste application) according to variation rules specified in footprint fields. When applying those rules, components are modified in place, allowing for immediate update of the PCB design as well as the 3D view and enabling compatibility with any exporter.

Back-propagation of modified component data from the PCB to the schematic can be done in an extra step.

What to Expect

KiCad Plugin

Example selection dialog of the KiVar Plugin for KiCad:

Command Line Interface Application

Example usage of the KiVar Command Line Interface app:

$ kivar list --selection kivar-demo.kicad_pcb 
~: 'Series 1000' 'Series 3000 Basic' ['Series 3000 Pro'] 'Series 5000 Basic' 'Series 5000 Pro'
BOOT_SRC~: EMMC JP NAND [SD]
IOEXP_TYPE/ADDR~: 9535/0x20 [9535/0x24] 9539/0x74
EEPROM_ADDR~: [0x54] 0x55
I_LED_MA~: 10 20 30 40 50 60 70 80 90 [100] 110 120 130 140 150 JP
ISL91127~: [IRAZ] IRNZ
UVLO_LO/HI: 2.41V/3.40V [3.15V/3.57V]
VOUT: 1.2V [1.8V] 2.5V 3.3V

$ kivar set --variant 'Series 5000 Pro' --verbose kivar-demo.kicad_pcb 
Changes (19):
    Change R1 'Do not populate' from 'true' to 'false' (EEPROM_ADDR=0x55).
    Change R1 'Exclude from bill of materials' from 'true' to 'false' (EEPROM_ADDR=0x55).
    Change R1 'Exclude from position files' from 'true' to 'false' (EEPROM_ADDR=0x55).
    Change R2 'Do not populate' from 'false' to 'true' (EEPROM_ADDR=0x55).
    Change R2 'Exclude from bill of materials' from 'false' to 'true' (EEPROM_ADDR=0x55).
    Change R2 'Exclude from position files' from 'false' to 'true' (EEPROM_ADDR=0x55).
    Change R21 field 'VarID' from 'A' to 'B' (I_LED_MA=110).
    Change R30 'Do not populate' from 'true' to 'false' (I_LED_MA=110).
    Change R30 'Exclude from bill of materials' from 'true' to 'false' (I_LED_MA=110).
    Change R30 'Exclude from position files' from 'true' to 'false' (I_LED_MA=110).
    Change U1 field 'I2C Address' from '0x54' to '0x55' (EEPROM_ADDR=0x55).
    Change U1 field 'VarID' from '54' to '55' (EEPROM_ADDR=0x55).
    Change U4 value from 'TCA9535PWR' to 'TCA9539PWR' (IOEXP_TYPE/ADDR=9539/0x74).
    Change U4 visibility of 3D model #1 from 'true' to 'false' (IOEXP_TYPE/ADDR=9539/0x74).
    Change U4 visibility of 3D model #2 from 'false' to 'true' (IOEXP_TYPE/ADDR=9539/0x74).
    Change U4 field 'I2C Address' from '0x24' to '0x74' (IOEXP_TYPE/ADDR=9539/0x74).
    Change U4 field 'VarID' from '24' to '74' (IOEXP_TYPE/ADDR=9539/0x74).
    Change U4 field 'Datasheet' from 'http://www.ti.com/lit/ds/symlink/tca9535.pdf' to 'http://www.ti.com/lit/ds/symlink/tca9539.pdf' (IOEXP_TYPE/ADDR=9539/0x74).
    Change U4 field 'MPN' from 'TCA9535PWR' to 'TCA9539PWR' (IOEXP_TYPE/ADDR=9539/0x74).
Board saved to file "kivar-demo.kicad_pcb".

$ kivar list --selection kivar-demo.kicad_pcb 
~: 'Series 1000' 'Series 3000 Basic' 'Series 3000 Pro' 'Series 5000 Basic' ['Series 5000 Pro']
BOOT_SRC~: EMMC JP NAND [SD]
IOEXP_TYPE/ADDR~: 9535/0x20 9535/0x24 [9539/0x74]
EEPROM_ADDR~: 0x54 [0x55]
I_LED_MA~: 10 20 30 40 50 60 70 80 90 100 [110] 120 130 140 150 JP
ISL91127~: [IRAZ] IRNZ
UVLO_LO/HI: 2.41V/3.40V [3.15V/3.57V]
VOUT: 1.2V [1.8V] 2.5V 3.3V

$ kivar check kivar-demo.kicad_pcb 
Check passed.  Matching variant and choices found for complete set of 7 aspect(s).

$ kivar state --query EEPROM_ADDR --query BOOT_SRC kivar-demo.kicad_pcb 
0x55
SD

The KiVar CLI application provides support for

• setting,
• querying,
• listing and
• analyzing

low-level and high-level variant data and current settings of a PCB. It can also be used in Continuous Integration services.

Concepts

Key concepts of KiVar are:

• Designs may contain multiple independent aspect scopes (micro-variants).
• Variation rules are fully contained in component fields of native design files (no external configuration files involved) and portable (i.e. copying components to another design keeps their variation specification intact).
• Component values, fields, attributes and features are modified in place with immediate effect, enabling compatibility with all exporters that work on the actual component data.
• No external state information is stored; currently matching variation choices are detected automatically.
• Optional external variant definition table in independent file format (CSV) enables switching of aspect groups based on a single variant name.

Supported KiCad Versions

KiCad Release Series | Compatible KiVar Releases -------------------- | ------------------------- 7.x | 0.0.1 – 0.1.2 8.x | 0.2.0 – latest 9.x | 0.4.2 – latest 10.x | 0.5.4 – latest

[!NOTE] KiCad 10 introduces native assembly variant support. However, KiVar's multi-scope Aspect model provides flexibility beyond KiCad's built-in single design-scope variant selection.

KiVar currently (still) uses the SWIG-based Python bindings of pcbnew (KiCad PCB Editor).

Installation

[!NOTE] The KiCad Plugin and the CLI app can be installed independently of each other. As the KiCad Plugin does not have external module dependencies, it does not require the CLI package to be installed.

KiVar Plugin

The recommended plugin installation method is to use KiCad's integrated Plugin and Content Manager. KiVar is included in the official PCM repository, allowing a smooth and safe installation and update experience.

Required steps:

1. Start the Plugin and Content Manager from the KiCad main window.
2. Find KiVar in the Plugins section.
3. Mark it for installation and apply the pending changes.
4. The KiVar plugin icon should now appear in the PCB Editor (pcbnew) toolbar.

KiVar Command Line Application

To install the latest KiVar CLI app directly from the official KiVar PyPI repository, follow the instructions below depending on your operating system.

Installation on Linux

For conveniently installing the KiVar CLI app inside a dedicated Virtual Environment, it is recommended to use pipx. Install it, if required, depending on your type of Linux distribution. With pipx in place, open a shell and run:

pipx install --system-site-packages kivar

This will install the KiVar CLI app in a location available in your search path. The name of the executable is kivar.

To check that the installation was successful and that the correct pcbnew module version is used, run:

kivar --version

Installation on Windows

On Windows systems, KiCad ships with its own Python distribution included. It is important to use the KiCad-provided Python interpreter for installing the KiVar CLI app.

To install the kivar.exe executable, open a cmd.exe shell and run:

"%ProgramFiles%\KiCad\9.0\bin\python.exe" -m pip install --user kivar

[!NOTE] The above command assumes that KiCad version 9.0 is used. Please adapt the version part (9.0) of the command, if required.

If you don't happen to have the app installation directory already listed in your PATH variable, then pip will print a warning including the actual installation directory:

WARNING: The script kivar.exe is installed in '...' which is not on PATH.

This message includes the location of the directory in which the kivar.exe executable is installed.

You will need to run kivar from this exact location. If desired, you can add the installation directory to your PATH variable (as suggested by pip), or use any other preferred method of making the executable callable from any working directory.

To check that the installa