KiVar − PCB Assembly Variants for KiCad

Introduction

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

• KiCad Action Plugin and
• Command Line Application.

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

The name KiVar (for KiCad Variants, obviously) can also be read as an acronym for KiCad Variation assignment rules.

Features

KiVar assigns PCB component values, field content and attributes (such as Do not populate, Not in position files, Not in BoM) 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 Action Plugin

Example selection dialog of the KiVar Action Plugin for KiCad:

Command Line Interface Application

Example usage of the KiVar Command Line Interface app:

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

$ kivar set --assign 'I_LED_MA=60' --assign 'BOOT_SRC=NAND' --verbose kivar-demo.kicad_pcb 
Changes (16):
    Change R9 'Do not populate' from 'false' to 'true' (BOOT_SRC=NAND).
    Change R9 'Exclude from bill of materials' from 'false' to 'true' (BOOT_SRC=NAND).
    Change R9 'Exclude from position files' from 'false' to 'true' (BOOT_SRC=NAND).
    Change R9 field 'ChoiceText' from 'SoM eMMC' to 'SoM NAND' (BOOT_SRC=NAND).
    Change R10 'Do not populate' from 'true' to 'false' (BOOT_SRC=NAND).
    Change R10 'Exclude from bill of materials' from 'true' to 'false' (BOOT_SRC=NAND).
    Change R10 'Exclude from position files' from 'true' to 'false' (BOOT_SRC=NAND).
    Change R11 'Do not populate' from 'false' to 'true' (BOOT_SRC=NAND).
    Change R11 'Exclude from bill of materials' from 'false' to 'true' (BOOT_SRC=NAND).
    Change R11 'Exclude from position files' from 'false' to 'true' (BOOT_SRC=NAND).
    Change R21 'Do not populate' from 'false' to 'true' (I_LED_MA=60).
    Change R21 'Exclude from bill of materials' from 'false' to 'true' (I_LED_MA=60).
    Change R21 'Exclude from position files' from 'false' to 'true' (I_LED_MA=60).
    Change R22 'Do not populate' from 'true' to 'false' (I_LED_MA=60).
    Change R22 'Exclude from bill of materials' from 'true' to 'false' (I_LED_MA=60).
    Change R22 'Exclude from position files' from 'true' to 'false' (I_LED_MA=60).
Board saved to file "kivar-demo.kicad_pcb".

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

Concepts

Key concepts of KiVar are:

• Designs may contain multiple independent variation aspects (i.e. dimensions or degrees of freedom).
• Variation rules are fully contained in component fields of native design files (no external configuration files) and portable (i.e. copying components to another design keeps their variation specification intact).
• Component values, fields and attributes are modified in place, 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.

Supported KiCad Versions

KiVar releases 0.2.0 and later require at least KiCad release 8.

Earlier versions of KiVar also supported KiCad 7, but in a very restricted way. Hence, after the release of KiCad 8, KiVar support for KiCad 7 has been dropped.

KiVar uses the Python API wrapper for pcbnew, the KiCad PCB Editor.

Installation

KiVar Action 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. For manual installation users can also choose to download the plugin archive package.

Using the Plugin and Content Manager

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.

Using Manual Archive Extraction

Required steps:

1. Open the KiCad PCB Editor (pcbnew).
2. In the PCB Editor, choose the menu option Tools → External Plugins → Open Plugin Directory. This will open a file browser at the location of your KiCad plugin directory.
3. Unzip the contents of an official KiVar release archive (the ZIP file without the -pcm suffix) to that KiCad plugin directory you opened in the previous step. Important: Do not create another directory inside the target plugin directory, but only place the files from the release archive directly in the plugin directory.
4. Switch back to the PCB Editor and choose the menu option Tools → External Plugins → Refresh Plugins. The KiVar plugin icon should now appear in the toolbar and in the plugin list under Tools → External Plugins.

If the installation does not work for you this way, consider reporting your problem as an issue in the KiVar bug tracker.

KiVar Command Line Application

Using pip

The KiVar CLI (command line interface) Python package can be installed using the following methods.

From the PyPI Repository

To install the latest KiVar CLI app from the official KiVar PyPI repository, open a shell and run:

pip install kivar

From a Release Archive

The KiVar CLI app can also be installed using a downloaded (or locally created) Python Package (replace ${VERSION} by the actual package version):

pip install kivar-${VERSION}.tar.gz

Usage

Important

This manual refers to the 0.2.x series of KiVar, which uses different component fields for specifying rules, a slightly modified (but significantly extended) rule syntax, and an enhanced range of functions compared to earlier versions.
If you are still using an older version, please consider updating KiVar and migrating your variation rules to the new format.
You can also switch to the latest version of this user guide.

The process of writing and assigning rules to components (i.e. symbols and footprints) is done manually using simple text expressions.

Once all relevant components are equipped with their variation rules, KiVar allows the selection of variation choices using either an easy-to-use dialog interface (when using the Action Plugin) or a command-line interface (when using the CLI app) and takes care of the automatic analysis and assignment of the corresponding component values, fields and attributes.

The following sections describe the process of configuring your schematic or board and - after that - selecting a variation configuration from the previously configured variation choices.

Component Variation Setup

The following sub-sections describe the variation rules setup procedure.

While it is recommended to define variation rules in the schematic (i.e. in symbol fields) and propagate them to the board, it is also possible to define those rules directly in the board (i.e. in footprint fields) and propagate them back to the schematic. Either way, in order for KiVar to utilize the variation rules, they must be present in the footprint fields, as KiVar uses the pcbnew API wrapper and can therefore only operate on the board (not schematic) data, which must then be propagated back to the schematic.

Migrating from KiVar 0.1.x

KiVar 0.2.0 introduces changes and enhancements to the rule syntax. The following sub-sections will support experienced users of KiVar 0.1.x with updating their legacy variation rules for current and upcoming KiVar versions.

New Field Names

Severity: Critical.

While KiVar 0.1.x and earlier used a single field named KiVar.Rule, current releases use the field Var for quite the same purpose.

So as a first step users should move all legacy rules from KiVar.Rule to Var. This can be achieved by copying and pasting the values of the KiVar.Rule column over to the Var column in the KiCad Schematic Editor's Symbol Fields Table.

Tip

To do this, open the Symbol Fields Table, sort by the legacy KiVar.Rule field, then copy & paste all relevant cells to the Var field (which may need to be created first). Afterwards, remove all KiVar.Rule fields (can be done in the Symbol Fields Table dialog).

Further reading: Choice Expressions.

Basic Rule Format

While the legacy format of the KiVar.Rule field is very similar to the current "Combined Base Expression Type" (using the Var field), there have been some changes that may (or may not) break existing legacy rules. Users will need to revise their legacy rules to be sure that they are parsed as expected with current (and upcoming) versions of KiVar.

The following sections will cover the details.

Property (Formerly Options) Inheritance

Severity: Critical.

Prior to version 0.2.0, KiVar supported "Option" arguments. An Option always started with a - (dash) character, followed by the Option identifier. The only supported Option identifier was !, which resulted in the Do not populate, Exclude from Position Files and Exclude from BoM component attributes to be set (or cleared if the option was not provided!).

If an Option was specified in a Default Choice (specified by the Choice Identifier *), that Option was not inherited by specific Choice Expressions, but would have to be specified again in all specific expression in order to be effective for those choices.

This (questionable) design decision had been made because there was no way to reset an Option specified in a Default Choice when overriding that Default Choice with a specific Choice. Hence, every Choice declaration/definition caused all Options to be reset for that specific Choice, to allow for providing a fresh set of Options for specific Choices.

Values, however, were handled differently: They were inherited from the Default choice definition and used as long as no Value was passed in a specific rule.

With version 0.2.0, this behavior has changed. Default Choice inheritance has been streamlined and now applies to both Values (now called Content) and Options (now called Properties), thanks to the introduction of enhanced Property Specifiers. Property Modifiers now allow overriding property states with either set (modifier +) or clear (modifier -) operations. That is, after the Default Property states are applied (inherited), specific choices can (partially) override those states.

There are now three supported effective Properties:

• Fitted (identifier f): Component is fitted. Clears the "Do not populate" component attribute.
• inPos (identifier p): Component is listed in Position files. Clears the "Exclude from Position Files" component attribute.
• inBom (identifier b): Component is listed in Bill of Materials. Clears the "Exclude from BoM" component attribute.

There is also a Placeholder Property !, which resolves to "Fitted", "InPos" and "InBom", being nearly backwards-compatible to the old -! Option. However, special care must be taken when -! appears in Default choices, as those Properties are now inherited by specific choices.

The following examples try to illustrate the different handling:

Old behavior:

Rule String	Resulting Choice1 Value	Resulting Choice1 Options	Resulting Choice2 Value	Resulting Choice2 Options
*(10k -!) Choice2()	10k	-!	10k (inheritance)	(none) (no inheritance)

New behavior:

Rule String	Resulting Choice1 Content	Resulting Choice1 Properties	Resulting Choice2 Content	Resulting Choice2 Properties
*(10k -!) Choice2()	10k	-! (effectively -f -b -p)	10k	-! (effectively -f -b -p)
*(10k -!) Choice2(+b)	10k	-! (effectively -f -b -p)	10k	-! +b (effectively -f +b -p)

Important

Component attributes (DNP, Not in Pos, Not in BoM) are now kept at their current state (and ignored in the Choice match) if their corresponding properties are not defined (to true or false).
In versions prior to 0.2.0 all three component attributes were either set or cleared, depending on the presence of the -! option. They could not be set to different states, and none of them could be kept untouched for component with variation rules. Version 0.2.0 introduces much more flexibility regarding attribute management.

Further reading: Default Choices.

Implicit Property Default States

Severity: Not critical (backwards-compatible).

Starting with version 0.2.0, users can choose to only specify the Property State that makes a Choice unique and let the the KiVar rule compiler assume the opposite state to be the Implicit Default state (if no default Property State is provided otherwise) for other choices of the same assignment.

For example, if a component is only fitted (Property Identifier f) in one Choice (of many), it is now sufficient to specify +f in that Choice Expression and leave the rest of the assignment choices and the Default Choice (*) without a definition for the f Property. The implicit default state for the f (fitted) Property will then automatically assumed to be the opposite (-f) for any other Choices.

Important

Implicit Property States can only be used if there is only one type of State/Polarity (either + or -) assigned in any of the assignment's choices.

Important

Implicit default States only work for Property States, as they use boolean states (actually tri-state, but as soon as a Property is provided, it's either true or false) and therefore have an (implicit) "opposite" value.

Further reading: Implicit Defaults.

Values As Multiple Words

Severity: Not critical (backwards-compatible).

Prior to version 0.2.0 multiple Value arguments were forbidden inside a Choice Expression. Only a single Value argument was allowed to be assigned to a Choice definition. In case of multiple "words", the argument had to be quoted (with ' (single-quote) characters) in order to be accepted as a single argument.

Starting with version 0.2.0, Choice Expressions can now contain multiple Value (now called Content) arguments, which are joined with a single (space) character inbetween.

This change is fully backwards-compatible. There is no need to adapt legacy rule strings.

Further reading: Content Specifiers.

Aspect Identifier Position

Severity: Not critical (backwards-compatible).

Before version 0.2.0 the aspect identifier (name) had to be the first argument in every rule string. From version 0.2.0 on, the aspect identifier can be specified at any position, or even left away and instead be specified in a different component field (Var.Aspect).

This change is fully backwards-compatible. There is no need to adapt legacy rule strings.

Further reading: Aspect Identifier.

New Choice Expression Types and Formats

Severity: Not critical (backwards-compatible).

Versions before 0.2.0 supported only a single rule format in the KiVar.Rule component field. From version 0.2.0 on, multiple rule (now called Choice Expression) formats are supported, which can be specified in different component fields.

This change is fully backwards-compatible. Apart from the changes discussed above, there is no need to change the format of legacy rule strings.

Further reading: Choice Expressions.

Double-Quote Characters Support

Severity: Not critical (backwards-compatible).

Prior to version 0.2.0 only ' (single-quote) characters could be used for the purpose of quoting verbatim strings.

Starting with version 0.2.0, " (double-quote) characters are also supported for quoting. Single- and double-quote strings can be nested, e.g. the string "hello 'world'" would result in hello 'world'.

This change is mostly backwards-compatible. If your legacy string do not use double-quote characters that are supposed to be used in a verbatim fashion themselves, there is no need to adapt legacy rule strings.

Further reading: Quoting and Escaping.

Definition of Terms

Basic terms used in this document:

• Aspect:
  A dimension of variation changes, which are defined by Choices (see below). One PCB design can refer to multiple aspects. Each component, which makes use of KiVar variations, must refer to exactly one aspect identifier.

• Choice:
  A set of values (component values or field contents) and/or properties to be assigned to specific components. A Choice is always related to a specific Aspect.

• Configuration:
  A fully defined selection of specific Choices for all available Aspects. In other words, one specific board assembly variant state.

Fundamentals

Each component (which uses KiVar variation rules) must refer to exactly one Aspect, to which all Choices defined or referred to in that component always relate to.

There can exist multiple Aspects per design, and for each Aspect there can exist multiple Choices.

Example:

• Aspect DEV_ADDR

  • Choice 0x50
  • Choice 0x51
  • Choice 0x52

• Aspect BOOT_SRC

  • Choice EMMC
  • Choice SDCARD
  • Choice NAND

• Aspect VIO_LEVEL

  • Choice 1.8V
  • Choice 2.5V
  • Choice 3.3V

One possible example Configuration for these Aspects and Choices:

DEV_ADDR=0x52 BOOT_SRC=NAND VIO_LEVEL=1.8V

KiVar computes such sets of Aspect and Choice definitions internally by checking each component's field data for KiVar Choice Expressions, which are explained in the following sections.

Choice Expressions

Component variation rules are specified in Choice Expressions, which are defined in the fields of each component (i.e. symbol and/or footprint) they relate to. Multiple components may (and usually will) refer to the same aspects and choices.

One component must relate to a single aspect, but can relate to an unlimited number of choices for that aspect.

Typically, multiple components are involved when defining specific Choices. But not each component is forced to refer to all Choices (of a certain Aspect). Instead, the KiVar Expression compiler accumulates all mentioned Choices and computes the data to be assigned for each of them.

Choice Expressions can use various notations, depending on their Scope and Format. Choice Expression syntax is described in the following sections from their innermost to outermost elements.

Choice Arguments

In its simplest form, a Choice Expression consists only of a Choice Argument List, which is just a list of space-separated Choice Arguments to be assigned to a component for a specific choice.

Each Choice Argument of the Choice Argument List can be of one of two possible types:

• a part of the Content to be assigned as the component value or a specific target field, or
• a Property state assignment specifier (e.g. to mark a component (un)fitted, (not) in BoM, (not) in position files).

Argument types are distinguished by their first (unescaped) character and will be explained in more detail in the following sub-sections.

Content Specifiers

Purpose

One or more Content Specifiers can be used to form a string to be assigned to the component value or to any (custom) component field (such as Manufacturer, MPN, ...).

Syntax

Each argument beginning with a character other than - and + is interpreted as a Content Specifier.

There can be multiple Content Specifiers in each Choice Expression. Their values will be concatenated with one (space) character as separator to form the resulting Content string. However, each choice may have only a maximum of one resulting Content assigned. For example: Choice1("hello world" foo bar) will result in Choice1 to be assigned the content hello world foo bar, but multiple content assignments to the same Choice, such as Choice1("hello world") Choice1(foo bar), are invalid. This restriction is due to the fact that Choice Expressions can be provided in different (Simple, Combined) formats and there is no guaranteed processing (concatenation) order.

Evaluation

All Content Specifiers of a Choice Expression are evaluated from left to right and concatenated with one space character between each argument to form the final content string to be assigned when the corresponding choice is selected.

Note

As arguments can be separated by any number of space characters, each separation will result in a single space character in the final content, no matter how many spaces were used for the argument separation originally (similar to HTML). For strings that shall be assigned in a verbatim way (such as a URL), it is highly recommended to use quoting techniques (discussed later).

Examples

The Content Specifiers in the following input Choice Argument Lists will result in the following Content strings:

Choice Argument List input	Resulting Content string	Explanation
100nF	100nF	Simple single arguments can be noted without escaping or quoting as long as they don't contain certain special characters (discussed later).
470µF 10%	470µF 10%	Uncritical text, no verbatim adoption of the arguments required.
470µF 10%	470µF 10%	Multiple separator characters will be converted to a single separator. As the text is uncritical, this conversion may even be desired.
'https://kivar.markh.de/ds/abc123.pdf'	https://kivar.markh.de/ds/abc123.pdf	Strings to be used verbatim should always be enclosed in quote characters.
'abc def ' 123 456	abc def 123 456	Mixed type of quoted and unquoted representation. Note how the trailing space after def remains contained in the result.
abc "def 'ghi' jkl" mno	abc def 'ghi' jkl mno	Outer double quotes encapsulate inner single quotes, which are part of the verbatim string.
abc 'def "ghi" jkl' mno	abc def "ghi" jkl mno	Outer single quotes encapsulate inner double quotes, which are part of the verbatim string.
abc \d\e\f\ \ ghi\'jkl\\mno	abc def ghi'jkl\mno	Escaping (prepending a backslash) ensures that the following character is interpreted verbatim, not as a special character. To create a backslash (the escape character) string, use a double backslash (i.e. escape the backslash).
\+10% \-5% \-12V \+5V	+10% -5% -12V +5V	If the first character of a Content Specifier is a - or +, the corresponding Choice Argument must be prepended with a backslash (\) character or be part of a verbatim string (see next example).
"+10%" '-5%' "-"12V '+'5V	+10% -5% -12V +5V	If the first character of a Content Specifier is a - or +, the corresponding Choice Argument must be part of a verbatim string or be prepended with a backslash (\) character (see previous example).

Property Specifiers

Purpose

KiVar provides a set of boolean component Properties that allow controlling certain component attributes, such as Do not populate, Not in Position Files or Not in BoM.

Syntax

Each argument beginning with a - or + is interpreted as a Property Specifier, which is a combination of Property Modifiers and Property Identifiers.

Each Property Specifier must start with a Property Modifier, defining the boolean state (true or false, represented by + or -, respectively) to be assigned to the Properties subsequently specified by their corresponding Property Identifiers.

Evaluation

All Property Specifiers inside a Choice Expression are evaluated from left to right, resulting in a set of defined boolean Property states for the corresponding component and Choice. Properties not defined in any of the component's Choices are kept in their original state.

Attribute Properties

The following Properties allow modification of component attributes:

• Fitted (property identifier f).
  This property specifies whether a component shall be fitted (property state true) or unfitted (property state false). This property is linked to the pcbnew footprint attribute Do not populate with inverted polarity.
• inPos (property identifier p).
  This property specifies whether a component shall be included in the component placement/position files (property state true) or excluded (property state false). This property is linked to the pcbnew footprint attribute Not in Position Files with inverted polarity.
• inBom (property identifier b).
  This property specifies whether a component shall be included in the Bill of Materials (property state true) or excluded (property state false). This property is linked to the pcbnew footprint attribute Not in BoM with inverted polarity.

Placeholder Properties

The following Property allows grouping frequently used attribute properties for user convenience:

• All (property identifier !).
  This placeholder property represents all three attribute properties Fitted, inPos and inBom (f, p, b). It can be used as a shortcut, as most of the times all three attributes are controlled together and set to the same state. However, if finer control is desired, the state of individual attribute properties can still be overridden. Examples can be found in the next section.

Examples

The Property Specifiers in the following input Choice Argument Lists will result in the following Property states:

Choice Argument List input	Resulting Property states	Explanation
-f	not Fitted	The - causes false to be assigned to the subsequent properties, i.e. Fitted. The footprint's attribute Do not populate will be set to true.
-fbp	not Fitted, not inBom, not inPos	One modifier (-) can be used for any number of subsequent identifiers.
-!	not Fitted, not inBom, not inPos	Equivalent to prior example.
+!	Fitted, inBom, inPos	Place this component to the board, include it in the BoM and in position files.
-! +b	not Fitted, inBom, not inPos	After setting f, b, p to false, b is set to true again. Useful if you want your BoM to include unfitted parts, that are otherwise marked "DNP".
-!+b	not Fitted, inBom, not inPos	Equivalent to prior example. Multiple modifiers may appear inside a single specifier argument.

Choice Identifiers

Purpose

Each Choice must have a unique name within its Aspect scope. This name can be any string.

For referring to a Choice name, Choice Identifiers are used. They are basically the same as the name itself, but rules for quoting and escaping of special characters apply. Choice Identifiers are case-sensitive.

Whether the mention of a Choice Identifier implicitly declares the Choice in its Aspect context depends on the scope in which the identifier is used:
In Base Scope, expressions can declare (new) choice identifiers, while in Auxiliary Scope, expressions can only refer to Choice Identifiers declared in Base Scope (in the same or another component).

The special Choice Identifier * is used for specifying default Content and Properties to be applied to Choices not explicitly listed in the corresponding assignment. Refer to the Default Choices section below for details.

Declaration and Definition

Choice Identifier Lists

When using Choice Identifiers in Choice Expressions, those identifiers are always specified inside Choice Identifier Lists. A Choice Identifier List consists of one or more Choice Identifiers that are separated by , (comma) characters (e.g. ChoiceId_1,ChoiceId_2,ChoiceId_3). No space is allowed around the separating comma.

Default Choices

Purpose

To follow the "All-or-None" rule, Content and Property assignments must be defined for all choices involved if at least one assignment is defined.

Defining all Choices for each assignment theoretically requires each Choice Identifier to be listed along with its corresponding Content or Property assignments. Also, any modification of available Choice Identifiers (i.e. adding, removing, renaming Choices) in one component theoretically requires the Choice Expressions of all components in the same Aspect scope to be adapted as well.

To avoid listing each possible Choice Identifier for each assignment, Default Choices can be used. The Content and Property assignments specified for a Default Choice apply as described below.

Syntax

The reserved Choice Identifier used for Default Choices is "*".

Default Content Inheritance

For each assignment target, the Content (component value or field content, respectively) specified in the Default Choice applies to all Choices that do not provide their own Content definition for the same assignment.

The following table explains Content inheritance rules using an example Choice Identifier A and some example Content.

Default Choice (*) Content	Specific Choice (A) Content	Resulting Specific Choice (A) Content
(none)	(none)	(none)
(none)	123	def
abc	(none)	abc
abc	123	123

Default Property Inheritance

For each assignment target, the state of each Property specified in the Default Choice is used as the initial value for all Choices with the same assignment target.

The following table explains Property state inheritance rules using an example Choice Identifier B and some example Property states (with resulting Property states listed with Property Specifier syntax).

Default Choice (*) Property Specifiers	Specific Choice (B) Property Specifiers	Resulting Specific Choice (B) Property states
(none)	(none)	(none)
(none)	+f	+f
+f	(none)	+f
+!	(none)	+fbp (→ placeholder)
+!	-p	+fb -p
+f	-b	+f -b
+f +b	-b	+f -b

Implicit Defaults

For Property assignments, it may not be required to explicitly specify a Default Choice, as for Properties, Implicit Defaults may apply.

For each assignment target, whenever only one state (i.e. either + or -) is assigned to a specific Property, then the opposite state is used for this Property as the Implicit Default for that assignment.

Note

The Implicit Default can be imagined as a "Default Default", i.e. the Implicit Default state of a Property will be overridden by a state specified in an explicit (usual) Default Choice.

Note

Implicit Defaults are only used for Properties, not for Content, as Properties are boolean values and therefore have an "opposite" value that can be assumed as the desired Default state.

The following table explains Implicit Default state inheritance rules using the example Choice Identifiers C1, C2, C3. C3 is not defined, but declared, hence its Property states (PS) will be assigned a value if Default states (implicit or explicit) exist. Resulting Property states ("RPS") are listed with Property Specifier syntax).

Choice C1 PS	Choice C2 PS	Implicit Default PS	Default (*) PS	C1 RPS	C2 RPS	C3 RPS
(none)	(none)	(none)	(none)	(none)	(none)	(none)
+f	(none)	-f (opposite of C1)	(none)	+f	-f	-f
+f	+f	-f (opposite of C1/C2)	(none)	+f	+f	-f
+f	-f	(none) (C1/C2 contradicting)	(none)	+f	-f	(none) (Invalid! f missing!)
+f	-f	(none)	-f	+f	-f	-f
+f	-p	-f +p	(none)	+f +p	-f -p	-f +p
-!	(none)	+fbp (→ placeholder)	(none)	-fbp	+fbp	+fbp
-!	-p	+fbp	(none)	-fbp	+fb -p	+fbp
+f	(none)	-f	+b	+f +b	-f +b	-f +b
-!	+p	+fb (p contradicting)	(none)	`-fbp	+fb +p	+fb (Invalid! p missing!)
-!	+p	+fb	-p	`-fbp	+fb +p	+fb -p

Choice Expression Scopes

The data defined in Choice Expressions can be applied to either

• the component's basic properties (i.e. component value and attributes), or to
• custom component fields (such as Manufacturer, MPN, ...).

For each of them there exists a dedicated Choice Expression Scope. Both scopes are explained in the following sub-sections.

Base Scope

Purpose

Expressions in Base Scope are used to

• assign component values (using Content Specifiers) and attributes (using Property Specifiers), and to
• declare and define Choice Identifiers in the context of a corresponding Aspect Identifier.

Typical Use

The Base Scope is used to assign basic component values, such as 10kΩ, 0.1µF 50V or 74HC595, to the mandatory "Value" field of a component (i.e. symbol or footprint), passed via Content Specifiers.

Also, the Base Scope is used to modify component attributes, for example to modify the DNP (Do Not Populate), Exclude from Position Files and/or Exclude from BoM states (attributes) of a component. Component attributes are modified using Property Specifiers.

Important

Expressions in the Base Scope can not modify custom (i.e. other than "Value") fields. For this, the Auxiliary Scope must be used (see next section).

Examples using the Base Scope are discussed later in the SBE and CBE sections.

Auxiliary Scope

Purpose

Expressions in Auxiliary Scope (or short: Aux Scope) are used for assigning values to specific component custom target fields with the use of Content Specifiers.

Important

Expressions in the Auxiliary Scopy can not declare additional Choice Identifiers, but only refer to existing ones that are declared in the Base Scope of the same or any other component using the same Aspect.

Important

Expressions in the Auxiliary Scope refer to dedicated target fields of components, not to the components themselves. As target fields do not have mutable attributes, Auxiliary Scope expressions do not support specifying Properties.

Important

Target fields referenced by Expressions in the Auxiliary Scope must already exist.

Note

The target field names "Footprint", "Reference" and "Value" are not permitted (to change the component value, the Base Scope must be used).

Typical Use

The Auxiliary Scope is used to assign custom field values, such as a manufacturer name or a manufacturer product number (MPN), for example, to be used in the bill of materials.

Auxiliary Scope expressions can also be used to specify other information, such as user-defined choice-dependent text information to be visible anywhere in the schematic for documentation purposes (using text-variables).

Examples using the Auxiliary Scope are discussed later in the SAE and CAE sections.

Choice Expression Formats

Furthermore, Choice Expressions can use different notations, depending on the user's preferences and requirements.

The two different Choice Expression Formats are described in the following sub-sections.

Simple Format

Purpose

The Simple Format is particularly well suited to

• specify a single Choice Expression using
• one specific component field per expression.

Typical Use

Expressions noted in Simple Format

• are recommended for longer, more complex (or verbatim) Content, such as a datasheet or purchase URL or a complex "Value" field content,
• can be useful when referencing a dedicated set of Choice Arguments using text variables that are embedded at another location of the schematic (see examples),
• have the drawback that, due to the diversity of the symbol field names they occupy, each unique used field name adds to the list of field names available in total, for example when using the Symbol Fields Editor.

Examples using the Simple Format are provided in the SBE and SAE sections.

Combined Format

The Combined Format is particularly well suited to

• allow combining multiple Choice Expressions in
• a single component field (also, in Base Scope, optionally accepting the Aspect Identifier).

Typical Use

Expressions noted in Combined Format

• are recommended for shorter, simpler Content, such as a simple component Value, a short MPN or manufacturer name,
• allow specifying multiple Choice Expressions in a compact way,
• therefore save space when many Choices need to be declared or defined.

Examples using the Combined Format are provided in the CBE and CAE sections.

Choice Expression Types

The four available Choice Expression Types are formed by using both Expression Scopes with both Expression Formats as discussed in the following sub-sections.

Simple Base Expressions (SBE)

Typical Use

Using the Base Scope, Simple Base Expressions define the component's Value content and/or component attributes and features.

Content and Property specifiers are noted in the Simple Format.

Syntax

Field name: Var(<CIL>)

Field content: <CAL>

Used placeholders:

• <CIL> specifies the Choice Identifiers List.
• <CAL> specifies the corresponding Choice Arguments List.

Examples

The following entries could be used for a capacitor. Note how the Aspect Identifier must be passed with a dedicated entry, as SBEs cannot include the Aspect Identifier, as is possible for CBEs.

Field name	Field content
Var.Aspect *	Capacitance
Var(Low)	10µF
Var(Medium)	100µF
Var(High)	470µF
Var(None,*)	-! DNP

* This defines an Aspect Identifier "Capacitance" including (at least, depending on the definitions used in other components) the Choice Identifiers "Low", "Medium", "High", which define capacitance values, as well as "None", which assigns the (capacitance) value DNP and also makes the component unfitted and excluded from position files and BoM.

Note

In the above example, the Default Choice Identifier "*" is added to the "None" Choice, so that the corresponding expression also applies to any Choices declared outside this component in the same Aspect context. Applying default data to Choices that the current component or assignment is "unaware" of may or may not be a good idea, depending on the chosen convenience vs. safety ratio.

Combined Base Expressions (CBE)

Typical Use

Using the Base Scope, Combined Base Expressions define the component's Value content, component attributes and features and/or the Aspect Identifier.

Content and Property specifiers are noted in the Combined Format.

Note

This Choice Expression type probably seems familiar, as it is very similar to the classic notation used in versions prior to 0.2.0 of KiVar.

Syntax

Field name: Var

Field content: [<ASPECT_ID> ]<CIL_1>(<CAL_1>)[ <CIL_2>(<CAL_2>)[ ...[ <CIL_N>(<CAL_N>)]]]

Used placeholders:

• <ASPECT_ID> (optional) specifies the Aspect Identifier.
• <CIL_1> .. <CIL_N> specify the Choice Identifiers Lists.
• <CAL_1> .. <CAL_N> specify the corresponding Choice Arguments Lists.

Note

The Aspect Identifier can be passed at any element position within the Combined Expression (first or last position recommended for readability).

Examples

The following single entry serves the same purpose as the above SBE example. Note how even the Aspect Identifier is included in the same single expression.

Field name	Field content
Var	Capacitance Low(10µF) Medium(100µF) High(470µF) None,*(-! DNP)

The same explanation applies as for the above SBE example.

Simple Auxiliary Expressions (SAE)

Typical Use

Using the Auxiliary Scope, Simple Auxiliary Expressions define the content of a specified existing component field.

Content and Property specifiers are noted in the Simple Format.

Syntax

Field name: <TARGET_FIELD_NAME>.Var(<CIL>)

Field content: <CAL>

Used placeholders:

• <TARGET_FIELD_NAME> specifies the name of the component's field to assign specified content to.
• <CIL> specifies the Choice Identifiers List.
• <CAL> specifies the corresponding Choice Arguments List.

Examples

The following entries could be used to define the MPN, description and datasheet URL for an imaginary LDO component. Note that the target field names "Description", "MPN" and "Datasheet" must exist.

Field name	Field content
Description.Var(1.8V)	Fixed voltage 1.8V 200mA LDO
Description.Var(3.3V)	Fixed voltage 3.3V 200mA LDO
Description.Var(adjustable)	Adjustable voltage 200mA LDO
MPN.Var(1.8V)	ALDO200V18
MPN.Var(3.3V)	ALDO200V33
MPN.Var(adjustable)	ALDO200ADJ
Datasheet.Var(1.8V,3.3V)	"https://example.kivar.markh.de/products/aldo200v.pdf"
Datasheet.Var(adjustable)	"https://example.kivar.markh.de/products/aldo200a.pdf"

This defines the Choice Identifiers "1.8V", "3.3V" and "adjustable", which define different field content for the target fields "Description", "MPN" and "Datasheet". Note how this example does not make use of the Default Choice Identifier "*", as there are no sensible defaults that could be assigned for yet unknown Choices that may be declared by other components.

As it is not possible to declare Choice Identifiers in the Auxiliary Scope (they rely on declarations in the Base Scope), there must exist at least the following Choice declarations in the same or another component that uses the same Aspect Identifier ("Voltage" assumed here). These Choice declarations are noted as SBEs, but Choices can be declared in any Expression Format (i.e. SBE or CBE types), even intermixed.

Field name	Field content
Var.Aspect	Voltage
Var(1.8V,3.3V,adjustable)	(empty)

Combined Auxiliary Expressions (CAE)

Typical Use

Using the Auxiliary Scope, Combined Auxiliary Expressions define the content of a specified existing component field.

Content and Property specifiers are noted in the Combined Format.

Syntax

Field name: <TARGET_FIELD_NAME>.Var

Field content: <CIL_1>(<CAL_1>)[ <CIL_2>(<CAL_2>)[ ...[ <CIL_N>(<CAL_N>)]]]

Used placeholders:

• <TARGET_FIELD_NAME> specifies the name of the component's field to assign specified content to.
• <CIL_1> .. <CIL_N> specify the Choice Identifiers Lists.
• <CAL_1> .. <CAL_N> specify the corresponding Choice Arguments Lists.

Examples

The following few entries serve the same purpose as the above SAE example.

Field name	Field content
Description.Var	1.8V(Fixed voltage 1.8V 200mA LDO) 3.3V(Fixed voltage 3.3V 200mA LDO) adjustable(Adjustable voltage 200mA LDO)
MPN.Var	1.8V(ALDO200V18) 3.3V(ALDO200V33) adjustable(ALDO200ADJ)
Datasheet.Var	1.8V,3.3V("https://example.kivar.markh.de/products/aldo200v.pdf") adjustable("https://example.kivar.markh.de/products/aldo200a.pdf")

The same explanation applies as for the above CAE example.

As explained above, declaring Choice Identifiers is not allowed from the Auxiliary Scope. Hence, there must exist at least the following Choice declarations in the same or another component that uses the same Aspect Identifier. These Choice declarations are noted as CBCs.

Field name	Field content
Var	Voltage 1.8V,3.3V,adjustable()

Aspect Identifier

Purpose

To define to which aspect (i.e. group/dimension/degree of freedom) a component's Choice Identifiers relate to, an Aspect Identifier must be specified for every component that uses one or more Choice Expressions.

Specification

There are two methods of passing the Aspect Identifier:

1. Using the dedicated component field Var.Aspect, or
2. as part of a Combined Base Expression.

Details and examples can be found in the following sections.

Fully Defined Assignments (The "All-or-None" Rule)

Purpose

One of the key concepts of KiVar requires all Configurations (sets of Choice selections) to be unambiguous with regard to their outcome. This is required in order to be able to detect, i.e. map the assigned outcome back to an unambiguous set of Choices.

It is therefore required for each Content or Property assignment that there is

• either no definition for any Choice involved (i.e. keep all Content or Property states in their original state)
• or a dedicated definition for every Choice involved (i.e. set all Content or Property states to a defined state).

In short, assignments must be done for either none or all Choices. There must be no sparsely defined assignments, because they would lead to inconsistent states when switching Choices.

Tip

To avoid undefined assignments, Default Choices can be used. For example, the Default Choice Identifier (*) can be added to the Choice Identifier List of an appropriate Choice Expression for that expression to also apply to otherwise undefined Choices.

Note

The KiVar Choice Expression compiler will stop with an error if a sparse definitions are detected.

Quoting and Escaping

Special characters inside a Choice Expression, such as , - + ( ) (comma, space, dash/minus, plus, parentheses) are not considered special (i.e. do not act as separators or Property Modifiers) if

• they appear inside a quoted part of the definition, i.e. inside a matching pair of two unescaped ' (single quotation mark) or " (double quotation mark) characters, or when
• they are escaped, i.e. directly prepended with a \ (backslash).

Single and double quotation mark characters (' and ") can be nested. The inner quotation marks will be part of the verbatim string in this case.

To include any character as-is without being interpreted (e.g. - or + to be used as first character of a Content string, or a quotation mark or backslash), that character must be escaped, i.e. preceded, with a backslash character.

Tip

For many cases, quoting and escaping in KiVar works just like in a regular POSIX shell interpreter.

Tip

As long as they come in pairs and in the correct nesting order, parentheses (( and )) are not required to be escaped or quoted, as the expression parser can handle multiple levels of properly nested parentheses. For example, Choice_1(100nF (10%)) is fine, even without quoting or escaping. Unusual arrangements, however, may require quoting or escaping in order to avoid misinterpretation by the parser.

Examples:

• To assign the fictional value don't care (a string containing a single quotation mark and a space), the appropriate Content Argument in the Choice Expression would be either 'don\'t care' or don\'t\ care.
• To use +5V (a string starting with a plus) as a value, the choice definition arguments '+5V' or \+5V would be appropriate. If the plus were not escaped, +5V would be interpreted as an (invalid) Property Specifier.
• To assign an empty Content string (e.g. component value or target field content), use an empty quoted string ('' or "") as Content Specifier.
• To assign a list of simple words or values as Content (e.g. value specifications such as 47µF 35V 10% X7R), the Content Specifiers can be naturally listed without quoting or escaping.
• To keep consecutive space characters, they must be escaped or quoted, e.g. to assign the Content string three spaces the Content Specifier three\ \ \ spaces, "three spaces" or three' 'spaces could be used.

Note

The same quoting and escaping rules apply for Aspect and Choice Identifiers.

Expression Processing Example

The following figure illustrates the processing of some example Choice Expressions using Combined Base Expressions (the classic Expression Type).

Real-World Examples

The following examples are taken from real commercial projects. They show a few configurable variation aspects, their possible choices along with a short explanation of the implementation.

To further explore these examples and learn the recommended ways of implementing KiVar rules, check out the demo project.

In the following sections, each example is illustrated with a schematic snippet including the values of the relevant fields for each related symbol.

Example 1: I²C Device Address Selection

In this very simple example, KiVar is used for address selection of an I²C device. Address input A0 switches between device addresses 0x54 (A0=GND) and 0x55 (A0=+3V3).

The device address is selected by tying the IC input A0 to either GND or +3V3, depending on the selected choice. Inputs A1 and A2 are tied to fixed levels.

How to read the rules:

• Variation aspect is EEPROM_ADDR (with choice 0x55 currently applied in the figure).
• R1: For choice 0x55 this part will be fitted (+!, resolving to +fpb). There is no default choice required, as implicit defaults (opposite property states, i.e. -fpb) are assumed automatically.
• R2: Likewise, for choice 0x54 this part will be fitted, else unfitted (same explanation as for R1).
• U1: A purely informational field called I2C Address is assigned the value 0x54 or 0x55, depending on the choice. This field can then either be made visible directly, or referenced by other symbols or text boxes within the schematic (using text variable ${U1:I2C Address}).

This example uses only classic Combined Format Expressions.

Example 2: Boot Source Selection

This is used for the boot source device selection for an NXP i.MX6ULL SoC.

The variation choices provide selection between the boot sources EMMC, SD and NAND, as well as an extra choice JP (which leaves all configuration resistors unfitted, so that the user can configure the board by manually shorting the solder bridges JP1, JP2, JP3).

How to read the rules:

• Variation aspect is BOOT_SRC (with choice EMMC currently applied in the figure).
• R9: For choices NAND and JP this part is unfitted, else (SD and EMMC, handled by Implicit Defaults) fitted.
• R10: For choices SD, EMMC and JP this part is unfitted, else (NAND) fitted.
• R11: For choices SD, NAND and JP this part is unfitted, else (EMMC) fitted.

Note

The Aspect Identifier is specified in a dedicated field for each involved component, so that the (visible) Expressions can be kept short.
The Aspect Identifier field (Var.Aspect) is kept invisible, except for component R9, from where it is moved to the top of the figure for documentation purposes.
Hint: In the Schematic Editor, uncheck the "Allow automatic placement" option for such moved fields.

This example uses only classic Combined Format Expressions.

Example 3: Undervoltage Trip Points

Typical use-cases for variations are resistor divider networks, such as voltage regulator feedback dividers or — in this case — a voltage divider with two taps for a programmable hysteresis on an undervoltage lock-out (UVLO) circuit.

The used variation aspect defines all four resistors (only two of them with varying values), allowing to select the lower (cut-off) and higher (recovery) voltage limits for the supply voltage monitor IC.

How to read the rules:

• Variation aspect is UVLO_HYST (with choice 3.15V/3.57V currently applied in the figure).
• R12: For choice 2.41V/3.40V the value is 0Ω, for choice 3.15V/3.57V, the value is 309kΩ.
• R13: The value is always set to 1MΩ. It is not really required to apply a value, or to use a variation rule at all for this symbol. However, in case more choices are added in the future, it is very likely that the value of this resistor will change. Hence the resistor symbol has the rule entry already prepared for easy introduction of new choices.
• R14: For choice 2.41V/3.40V the value is 309kΩ, for choice 3.15V/3.57V, the value is 100kΩ.
• R15: The value is always set to 750kΩ. Same explanation applies as for R13.

Note

The Aspect Identifier is handled similarly to example 2 above.

Example 4: IC Variant Selection

This is used for selection of peripheral parts on a boost-buck-converter IC, which is available as fixed (IRNZ suffix) and adjustable (IRAZ suffix) voltage variants (just like many LDOs are, too). Depending on the market availability of those IC variants, this variation aspect helps to quickly select between assembly options.

The fixed voltage IC variant requires direct feedback of the output voltage to the FB pin, while the adjustable voltage IC variant requires a typical feedback resistor network, including a capacitance of 66pF for stabilization.

How to read the rules:

• Variation aspect is ISL91127 (with choice IRAZ currently applied in the figure).
• C5, C6: For choice IRAZ this part is fitted, else (IRAZ, handled by Implicit Defaults) unfitted.
• R16: For choice IRAZ the value is 1MΩ (adjustable version using a voltage divider for feedback), for choice IRNZ the value is 0Ω (fixed version using direct output voltage feedback).
• R17: For choice IRAZ this part is fitted, else (IRNZ) it is unfitted.
• U3: For choice IRAZ, set the component value to ISL91127IRAZ, for choice IRNZ set it to ISL91127IRNZ. Also, set the MPN field accordingly (expression not shown in the schematic, check out the demo project).
  Furthermore, for choice IRAZ, set the (visible) Info field content to Adjustable, for choice IRNZ set it to Fixed for documentation purposes.

Note

The Aspect Identifier is referenced by a text field from component U3 using the text variable ${U3:Var.Aspect}. Using this technique, the pure Aspect Identifier can be placed inside any text for documentation purposes.

Example 5: IC Type and Address Selection

This is used for selection of an I/O expander IC type (9535 vs. 9539) along with its I²C address. Different (footprint-compatible!) IC types interpret the input on pin 3 differently ("A2" vs. "/RESET"). See the text callout in the figure for details.

This example really implements two simple sub-aspects in a single variation aspect:

• the type of the IC and
• the device address.

As both sub-aspects depend on each other and can only be defined in a combined way, all sensible combinations (there are only three) must be defined for the combined aspect. It is recommended to use the same dedicated sub-aspect separation character (/ used in this example) in the Aspect Identifier as well as the Choice Identifiers to make it obvious to the user which sub-choice applies to which sub-aspect.

How to read the sub-aspects:

This example uses variation aspect IOEXP_TYPE/ADDR (read as: sub-aspects IOEXP_TYPE and IOEXP_ADDR) with choice 9539/0x74 (read as: 9539 selected for IOEXP_TYPE, 0x74 selected for IOEXP_ADDR) currently applied in the figure.

How to read the rules:

• Variation aspect is IOEXP_TYPE/ADDR (see above).
• R18: For choices 9535/0x24 and 9539/0x74 this part will be fitted, else (9535/0x20, handled by Implicit Defaults) unfitted.
• R19: For choice 9535/0x20 this part will be fitted, else (9535/0x24, 9539/0x74) unfitted.
• U4: The I²C address information field I2C Address is set according to the resulting address, depending on the selected choice. Also, the MPN and Datasheet fields are set accordingly (expression not shown in the schematic, check out the demo project).

Note

Depending on the available space in the schematic, the Aspect Identifier can be moved into the dedicated Var.Aspect field (and shown or hidden), as for U4, or be part of the Choice Expression, as for R18 and R19.

Example 6: Backlight LED Maximum Constant Current Selection

In this example a combination of resistor networks determines the maximum constant current for an LED backlight (maximum because the used current regulator also has a PWM input, which can be controlled via software).

The resistor network combination allows to select an LED current from 10mA to 150mA in steps of 10mA. Also, like in example 2, there is an additional choice JP, which leaves all four configuration resistors unfitted, so that the user can manually select the current using the solder bridges.

How to read the rules:

• Variation aspect is I_LED_MA (with choice 100 currently applied in the figure).
• R21: This is the most significant path for 80mA current. For the upper half of the current choices, i.e. 80 up to 150, the resistor is fitted. For other choices (incl. JP) the part is unfitted (handled by Implicit Defaults).
• R22: This is the path for 40mA current. For choices 40 through 70 and 120 through 150 the resistor is fitted. For other choices (incl. JP) it is unfitted.
• R29: This is the path for 20mA current. For choices 20, 30, 60, 70, 100, 110, 140, 150 the resistor is fitted. For other choices (incl. JP) it is unfitted.
• R30: This is the least significant path for 10mA current. For choices 10, 30, 50, 70, 90, 110, 130, 150 the resistor is fitted. For other choices (incl. JP) it is unfitted.

Note

Again, to save horizontal space, the Aspect Identifier is moved to the dedicated Var.Aspect field (shown), for all involved components.

Rules Application

After setting up the rules for each relevant symbol (or footprint), variations can finally be switched using the KiVar plugin or CLI app.

Using the KiVar Action Plugin

Update the PCB

If the expressions were set up in the Schematic Editor (eeschema), they need to be updated to the PCB Editor first (menu item Tools → Update PCB from Schematic...).

Run the Plugin

To open the plugin dialog, simply click the KiVar plugin icon in the main toolbar, or choose the KiVar menu item under Tools → External Plugins.

Configuration Identification

Upon start, during the compilation stage, KiVar automatically detects the current variation configuration, i.e., it tries to find a definite choice for each configured aspect, based on the currently assigned values, field contents and attributes for each related footprint.

If they do not exactly match one definite choice (per variation aspect), then the corresponding variation choice selector is preset to the entry '<unset>'. This will probably happen before applying a specific choice for the first time or after editing expressions, because not all of the currently assigned footprint properties may perfectly match one of the defined variation choices.

Possible Error Messages

In case the defined choice expressions cannot be parsed and/or compiled without problems, an error message window with a list of problems is presented. Each of the listed problems must then be fixed in order to successfully start the plugin.

Tip

Error messages can be clicked to focus the corresponding footprint on the pcbnew canvas in the background.

Variation Choices Selection

If all expressions can be compiled without problems, the plugin dialog window appears.

For the above real-world examples, the selection dialog window may look similar to the following:

For each of the listed Aspect Identifiers a variation Choice Identifier can now be selected.

If the values, field contents and attributes of the footprint(s) related to a variation aspect shall not be modified, the entry '<unset>' can be selected for that variation aspect. In this case, the corresponding variation will be excluded from the assignment stage and related footprints remain unmodified.

The change list section below the selection area summarizes all component changes to be performed for each related footprint if the current variation configuration is applied.

Tip

Entries in the change list can be clicked to focus the corresponding footprint on the pcbnew canvas in the background.

After selecting a few different variation choices, the dialog window may look like the following:

When clicking the Update PCB button, KiVar sets the values and attributes for all relevant footprints as previewed in the information text box.

Visible Changes

The performed changes will immediately be visible in the PCB Editor (e.g. for shown footprint values) and the 3D Viewer window (immediately or after refresh, depending on the preferences setting).

The following images show the 3D board view for the original settings:

... and after applying the new variation configuration (according to the dialog window above):

Updating the Schematic

All changes by the plugin are only performed in the board, as KiVar is a plugin for pcbnew (eeschema does not yet have a plugin interface). That is, the performed changes must be propagated back from the board to the schematic in order to be visible there (e.g. for changed values and DNP markings).

To propagate the changes back to the schematic, use the PCB Editor menu item Tools → Update Schematic from PCB... and make sure to select the checkboxes Values and Attributes*. If you have modified the KiVar rules inside the PCB Editor, i.e. edited the footprint fields* instead of the symbol fields, then also select the checkbox Other fields*, in order to propagate your KiVar rules to the schematic.

Using the KiVar Action Plugin

The KiVar CLI application works similar to the plugin, except that it manipulates an existing .kicad_pcb file (which must not be opened in another application).

For usage information and available commands and options, run:

kivar --help