KiVar − Multi-Scope PCB Assembly Variants for KiCad

Introduction

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

• Command Line Application (this package) and
• KiCad Action Plugin (available in KiCad PCM).

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.

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

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

KiVar requires the pcbnew Python module of at least KiCad release 8.

Project Page

For the usage manual and a demo project check out the KiVar Project Page.