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 outside the native KiCad design files.

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.

Example selection dialog of the KiVar Action Plugin for KiCad:

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]
VOUT: 1.2V [1.8V] 2.5V 3.3V

$ kivar set --assign 'IOEXP_TYPE/ADDR=9539/0x74' --assign 'VOUT=3.3V' --verbose kivar-demo.kicad_pcb 
Changes (14):
    Change R34 value from '100kΩ' to '175kΩ' (VOUT=3.3V).
    Change R34 field 'VarID' from '18' to '33' (VOUT=3.3V).
    Change R34 value from '100kΩ' to 'DNP' (VOUT=3.3V).
    Change R35 'Do not populate' from 'false' to 'true' (VOUT=3.3V).
    Change R35 'Exclude from bill of materials' from 'false' to 'true' (VOUT=3.3V).
    Change R35 'Exclude from position files' from 'false' to 'true' (VOUT=3.3V).
    Change R35 solder paste relative clearance from 0.0% to -4200000.0% (VOUT=3.3V).
    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 
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]
VOUT: 1.2V 1.8V 2.5V [3.3V]

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

$ kivar state --query VOUT --query EEPROM_ADDR kivar-demo.kicad_pcb 
3.3V
0x55

The KiVar CLI provides support for

• setting,
• querying,
• listing and
• analyzing

variation data, either manually or - for example - integrated in a Continuous Integration service.

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 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.

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

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

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.

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.

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.

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

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

pip install kivar

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

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, attributes and features.

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. Examples are given where appropriate.

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.

Basic terms used in this document:

• Aspect:
  A scope (or dimension) of variation changes, which are defined by Choices (see below). One PCB design can refer to multiple Aspects. Each component that makes use of KiVar variations must refer to exactly one Aspect Identifier.
  For example, an Aspect can be the I²C address of an EEPROM IC, using an identifier such as EEPROM_I2C_ADDR.

• Choice:
  A set of Content (component values or component field values) and/or Properties to be assigned to specific components. A Choice is always related to a specific Aspect.
  For example, possible Choices for the I²C address Aspect could be 0x50, 0x51, 0x52, 0x53.

• Configuration:
  A fully defined selection of specific Choices for all available Aspects. In other words, one specific board assembly variant state.
  An example is shown in the following section.

• Record:
  An entry in a KiVar-specific custom field of a component (symbol or footprint) to be interpreted by the KiVar rule processor.

• Assignment:
  A group of one or more Records containing Choice Expressions to assign a set of data to the same Assignment target (e.g. the component itself, or an existing custom field of the component).

In the following sections, these and other specific KiVar terms are capitalized.

Each component that uses KiVar variation rules must bind to exactly one variation Aspect to which all specified variation Choices for that component will then relate to.

Example:

• Design

  • Aspect EEPROM_I2C_ADDR

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

  • Aspect BOOT_SRC

    • Choice EMMC
    • Choice SDCARD
    • Choice NAND

  • Aspect VIO_LEVEL

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

One possible resulting example Configuration for this design:

EEPROM_I2C_ADDR=0x52 BOOT_SRC=NAND VIO_LEVEL=1.8V

KiVar computes possible sets of Aspect and Choice definitions internally by checking each component's field data for KiVar Records and the Assignments resulting from them. The structure and syntax of the expressions used in such Records are described in the following sections.

The text expressions that describe the variation rules are noted as Records, i.e. as custom field entries with each field's name containing the keyword Var in one of several forms.

Records must appear in the component they relate to.

A usual Record contains the following elements:

• Assignment Target information: implicit, depending on the Assignment Scope
• Choice Expression(s): one or more, depending on the Record Format
  • Choice Identifier List: list of affected Choice names
  • Choice Argument(s): data to be assigned to the affected Choices
    • Content Specifier(s): provide data to be used as component value or custom field value
    • Property Specifier(s): provide settings to switch component attributes or footprint features

There is a special Aspect Specifier Record type, discussed in the corresponding section.

Records can use various notations, depending on their Format. Details are described in the following sections.

Each Record addresses a specific target that the contained rule expressions refer to. A group of one or more Records with the same target form an Assignment.

Possibe Assignment targets are:

• the component's value,
• one of the component's (custom) fields,
• a component attribute and/or
• a component feature (e.g. solder paste application, 3D representation).

Depending on the used Format, each Record can carry either a single or multiple Choice Expressions.

Each Choice Expression specifies

• for which Choice Identifiers to assign
• which data to the Record's Assignment target.

For each Choice Expression, this data is passed via the

• Choice Identifier List and
• Choice Arguments.

The actual data to be assigned to the Choices passed as Choice Identifier List is expressed in the Choice Arguments.

These Choice Arguments are a list of space-separated specifiers used to declare the data to be assigned to the Assignment Target.

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

• a Content Specifier to assign a component value or a specific custom field value, or
• a Property Specifier, e.g. to mark a component (un)fitted, (not) in BoM, (not) in position files or change a dedicated footprint feature.

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

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

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

There may exist multiple Content Specifiers in each Choice Argument List. Their values will be concatenated with one (space) character as separator to form the resulting Content string. However, each Assignment may have a maximum of one resulting Content specified. 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 Identifier, such as Choice1("hello world") Choice1(foo bar), are invalid. This restriction is due to the fact that Records can be provided in different Formats and there is no guaranteed processing (concatenation) order.

All Content Specifiers inside the Choice Arguments 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.

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

KiVar provides a set of boolean component Properties that allow controlling the component attributes

• Do not Populate,
• Not in Position Files, and
• Not in BoM

as well as component features, such as

• Individual 3D Model Visibility and
• Solder Paste Application.

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.

All Property Specifiers inside a Choice Argument List 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.

The following Properties allow modification of component attributes:

• Fit (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.
• Pos (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.
• Bom (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.

Additionally, the following Properties allow controlling footprint features:

• Model (Property identifier mN, with N being an integer number).
  This Property controls the visibility of each individual 3D model of the corresponding component footprint to either visible (Property state true) or invisible (Property state false). An integer number must be provided directly following the first character of the Property identifier, representing the index of the model to be shown or hidden. The index starts at 1.
• Solder (Property identifier s).
  This Property controls the application of solder paste to the pads of a component's footprint. Solder paste can be enabled (Property state true) or disabled (Property state false). For both cases, user-defined footprint-specific solder paste clearances are maintained (see note below).
  Important: As usual for KiCad solder paste clearance settings, this Property has only effect for pads on copper layers, but not for SMD Aperture pads!

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

• Assemble (Property identifier !).
  This Group Property represents all three attribute properties Fit, Pos and Bom (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 when a component is switched between assembled or unassembled. However, if finer control is desired, the state of individual attribute properties can still be overridden. Examples can be found in the next section.

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

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.

The reserved Choice identifiers ? and * can be used to assign template data to Choices not defined or not fully defined, respectively, for the corresponding assignment. For details, refer to the Stand-In Choice and Default Choices sections below.

KiVar uses implicit declaration of Choice Identifiers.

That is, adding a new Choice to an Aspect is simply done by using (i.e. mentioning) the Choice Identifier in any Assignment's Choice Expression. This will cause the Choice to be created (if it's new) or extended (if it matches an existing one).

It is therefore important to pay attention to correct spelling of Choice Identifiers, so that they can be correctly allocated.

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

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 would require each Choice Identifier to be explicitly listed along with its corresponding Content or Property specifications. Also, any modification of available Choice Identifiers (i.e. adding, removing, renaming Choices) in one component would (that is, will) require the Choice Expressions of all components in the same Aspect scope to be adapted as well.

To avoid having to explicitly list all possible Choice Identifiers for each assignment, Default Choices and Stand-In Choices are available. The Content and Properties specified for Default and Stand-In Choices apply as described in the following sections.

Data assigned to a Stand-In Choice is used for all specific Choices that remain undefined (i.e. not mentioned) in the corresponding Assignment.

Stand-In Choice data is not used for specific Choices that have empty definitions.

Stand-In Choices are particularly useful to assign data to "all other" Choices without explicitly mentioning them, or to make use of Implicit Property Defaults, which would be overridden by specifying a Default Choice.

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

Data assigned to a Stand-In Choice is used for specific Choices that are declared in other Assignments, but are undefined in the Assignment for which the Stand-In Choice is defined.

Data (Content or Properties) assigned to a Default Choice is used as a baseline for the data assigned to all specific Choices (defined or undefined) for the Assignment in which the Default Choice is defined.

Default Choice Content (if any) is used for all specific Choices that do not provide their own Content or that are undefined.

Default Choice Properties (if any) are used as base data before applying Property data from specific Choices definitions. Undefined Choices inherit the Default Choice's Properties.

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

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.

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).

While Stand-In and Default Choices act similarly, users should be aware of the following differences between them.

• Stand-In data is only used for Choices that are declared elsewhere, but are not defined (not even with an empty definition) for the Assignment.
• Default data is used as a basis for all Choices of the Assignment and only overridden by specific Choice data. Empty definitions inherit the unaltered Default Choice data, as they do not override any data.

• Stand-In data is used as a whole (all Content and Properties), depending on the presence of the definition for a corresponding specific Choice, while
• Default data is used as a baseline and can be overridden on a per-element basis (Content or Properties) by the corresponding specific Choice.

First, Stand-In data is assigned to all undefined Choices. After that, Default Choice data is used for all resulting Choice data as usual.

That is, Stand-In and Default Choices can be used at the same time and Default Data applies to all (resulting) Choice definitions in any case.

As Stand-In Choice data is only used for undefined Choices, it can be used for the calculation of Implicit Property Default data.

For Property states Implicit Property Defaults may apply.

For each Assignment target, whenever only one state (i.e. either + or -) is assigned to a given Property by any number of Choices, then the opposite state is used for this Property as the Implicit Default State for that Assignment.

The following table explains Implicit Property Default state inheritance rules using the example Choice Identifiers C1, C2, C3. C3 is not defined, but declared by another Assignment. Hence C3's Property states ("PS") will be assigned the values found in the Assignment's Implicit Default PS (as computed by analysis of all defined Choices, i.e. C1 and C2) and the user-provided (explicit) Default (*) PS (overriding Implicit Default values, per Property). Resulting Property states ("RPS") for all Choices C1, C2, C3 are listed with Property Specifier syntax.

The data defined for an Assignment can be applied to either

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

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

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

Also, the Component Scope is used to modify component attributes, for example the DNP (Do Not Populate), Exclude from Position Files and/or Exclude from BoM states (attributes) of a component, or dedicated component/footprint features, for example controlling 3D model visibility or solder paste application. Component attributes and features are modified using Property Specifiers.

Examples using the Component Scope are discussed later in the SCAR and CCAR sections.

Assignments in Field Scope are used to assign Content to custom fields, such as the manufacturer name or the manufacturer product number (MPN), for example, to be used in the bill of materials. Other usual component fields to be modified are tolerance ranges, voltage rating, or the datasheet URL.

For documentation purposes, essential components may be assigned information about the currently selected Aspect Choice, such as a component's selected bus address or some bootstrap configuration settings. This data can then be made visible anywhere in the schematic and even in the PCB. This enables automatically updated documentation.

Examples using the Field Scope are discussed later in the SFAR and CFAR sections.

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

Both available Record Formats are described in the following sub-sections.

The Simple Format is particularly well suited to

• specify a part of an Assignment containing
• a single Choice Expression using
• one dedicated Record.

Records 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 in 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, which "pollutes" the fields list, e.g. in the Symbol Fields Editor.

Examples using the Simple Format are provided in the SCAR and SFAR sections.

The Combined Format is particularly well suited to

• specify one or more parts of an Assignment containing
• one or more Choice Expression,
• optionally including the Aspect Identifier (only in Component Scope), using
• one dedicated Record.

Assignments 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 a lot of Records (and field adding/typing work) when many Choices need to be declared or defined.

Examples using the Combined Format are provided in the CCAR and CFAR sections.

The four available Assignment Record Types are the result of using both Assignment Scopes in combination with both Record Formats as discussed in the following sub-sections.

Using the Component Scope, Simple Component Assignment Records define the component's Value content and/or component attributes and features with Content and Property specifiers noted in the Simple Format.

Field name: Var(<CIL>)

Field content: <CAL>

Used placeholders:

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

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

* 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.

Using the Component Scope, Combined Component Assignment Records define the component's Value content, component attributes and features and/or the Aspect Identifier with Content and Property specifiers noted in the Combined Format.

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.

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

The same explanation applies as for the above SCAR example.

Using the Field Scope, Simple Field Assignment Records define the Content of a specified existing component field with Content Specifiers noted in the Simple Format.

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.

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.

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

Using the Field Scope, Combined Field Assignment Recordss define the Content of a specified existing component field with Content Specifiers noted in the Combined Format.

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.

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

The same explanation applies as for the above CFAR example.

To define to which Aspect (i.e. group/dimension/degree of freedom) all of the component's Choice Identifiers relate to, an Aspect Identifier must be specified for each component that makes use of KiVar Assignments.

Similarly to Choice Identifiers, KiVar uses implicit declaration of Aspect Identifiers.

That is, adding a new Aspect to a design is simply done by using (i.e. mentioning) the Aspect Identifier in an Aspect Specifier (see below for possible methods). This will cause the Aspect to be created or extended (if it matches an already existing one).

It is therefore important to pay attention to correct spelling of Aspect Identifiers, so that they can be correctly allocated.

There are two methods of specifying the Aspect Identifier:

1. Using a dedicated Record in the component field Var.Aspect, or
2. as part of a Combined Component Assignment Record.

Details and examples can be found in the following sections.

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

For each Assignment it is therefore required that for the Content and for each specific Property, respectively, there is

• either no definition for any Choice (i.e. Content or the specific Property's state, respectively, is kept in its original state)
• or a dedicated definition for every Choice (i.e. Content or the specific Property's state is assigned defined data).

It is not allowed to provide only a sparse set of definitions for each Assignment element (Content or Property), unless Stand-In or Default Choice definitions are provided to fill the undefined parts. Sparse definitions are forbidden as they would lead to inconsistent states when switching Choices.

In short, assignments must be done for either none or all Choices.

Special characters inside an Assignment, 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 expression, 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, in which case the inner quotation marks will become part of the verbatim string.

To include any character as-is without being interpreted as special character (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.

Examples:

• To assign the fictional value don't care (a string containing a single quotation mark and a space) as a single argument, the appropriate Content Argument in the Choice Expression would be either 'don\'t care', "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.

The following figure illustrates the processing of some example Assignments using Combined Component Assignment Records.

The following examples are mostly taken from real commercial projects. They show a few configurable variation Aspects, their possible Choices along with a short explanation of the used Assignments.

To further explore these examples and learn the recommended ways of implementing KiVar rule expressions, 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.

In this very simple example, KiVar is used to conveniently select the address of an I²C device. Address input signal 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 for the sake of simplicity.

How to read the rules:

• Variation Aspect Identifier 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 Stand-In or Default Choice required, as Implicit Property 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 Combined Format Records.

This schematic snippet 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 Identifier 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 Property 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.

This example uses only Combined Format Records.

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 Identifier 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 (i.e. for all Choices not explicitly mentioned in this Assignment) set to 1MΩ. It is not really required to apply a value or to use a variation rule for this symbol at all. 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.

This snippet is used for selecting peripheral parts on a boost-buck-converter IC that is available as fixed (IRNZ suffix) and adjustable (IRAZ suffix) voltage IC 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 Identifier is ISL91127 (with Choice IRAZ currently applied in the figure).
• C5, C6: For Choice IRAZ this part is fitted, else (IRAZ, handled by Implicit Property 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, the component value is set to ISL91127IRAZ, for Choice IRNZ it is set to ISL91127IRNZ. Also, the MPN field is set accordingly (Record not shown in the schematic, check out the demo project for details).
  Furthermore, for choice IRAZ, the (visible) Info field content is set to Adjustable, for choice IRNZ it is set to Fixed for documentation purposes.

This schematic snippet is used for selecting an I/O expander's specific 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 box 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 therefore 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 Identifier 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 Identifier 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 Property 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. The MPN and Datasheet fields are set accordingly. Also, for the 9539 IC type (Choice 9539/0x74) only the second 3D model will be visible (+m2), while for other choices (i.e. 9535 IC type, default choice), only the first 3D model will be visible instead (+m1). Implicit Property Defaults take care of hiding 3D models that are mentioned in other Choices, but not in the current one.
  The MPN, Datasheet and 3D model visibility rules are not shown on the symbol to keep the schematic clear. To see all rules, check out the demo project.

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 allow selecting 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 Identifier 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 Property 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.

In this example a simple resistor network determines the output voltage of an LDO voltage regulator.

The available resistor combinations allow selecting between four different voltages: 1.2V, 1.8V, 2.5V and 3.3V. If a resistor is to be unpopulated, the solder paste will be suppressed for that component, too.

How to read the rules:

• Variation Aspect Identifier is VOUT (with Choice 1.8V currently applied in the figure).
• R34: This is the first of two parallel resistors connected in parallel, forming the top resistance of the feedback network. For Choice 1.2V this will be fitted with a 0Ω resistor to directly feed the output voltage back to the FB input (1.2V is the LDO's internal reference voltage). For Choices 1.8V, 2.5V and 3.3V the resistor value will be set to 100kΩ, 150kΩ and 175kΩ, respectively, connected in parallel with R35 to form the required top resistance.
• R35: This is the second of the two parallel resistors in the top part of the feedback network. For Choices 1.8V and 2.5V the value is set to 100kΩ and 390kΩ, respectively, forming the required top resistance with R34. For all other Choices (i.e. 1.2V and 3.3V), a Stand-In is provided to set the resistor's value to DNP, to unfitted state and to suppress solder paste (-s) for the corresponding footprint.
• R36: This resistor forms the bottom part of the feedback network. For the Choice 1.2V (the LDO's internal reference voltage) the resistor component's value is set to DNP and the component is unfitted to make the bottom path high-impedance. Also, as for R35, solder paste is suppressed in this case. All other Choices (i.e. 1.8V, 2.5V and 3.3V) are covered by the Stand-In Choice definition that sets the resistor value to 100kΩ.

For each above example, one essential component was chosen to carry an Aspect Choice variation identifier code (in field VarID). These codes than then be used to form a PCB assembly variant code that is unique for each Configuration (i.e. combination of Aspect Choices).

Even though PCB variants are not really supposed to change any property of the bare PCB (i.e. copper, solder mask, ...), such variant configuration codes can be added to any documentation (or any other) layer. Refer to the PCB 3D views below and to the demo project for a usage example.

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

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

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.

Upon start, during the rule processing stage, KiVar analyzes the board data and automatically detects the current variation Configuration, i.e. it tries to find one definite Choice for each configured Aspect, based on the currently assigned values, field contents, attributes and features for each related footprint.

If KiVar fails to find a matching definite Choice for a 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 Assignments, because not all of the initial footprint data may perfectly match exactly one of the defined variation Choices (per Aspect).

In case the user-provided Records cannot be parsed and/or processed without problems, an error message window with a list of problems will be presented. Each of the listed problems must then be fixed in order to successfully start the plugin.

If all Records can be processed without problems, the plugin dialog window appears.

For the above usage 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, attributes and features 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.

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

When clicking the Update PCB button, KiVar sets the configured data for all relevant footprints as previewed in the information text box and then closes the selection dialog window.

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):

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 KiVar Records inside the PCB Editor, i.e. edited the footprint fields* instead of the symbol fields, then also select the checkbox Other fields* to propagate your modified KiVar Records to the schematic.

The KiVar CLI application uses the same KiVar backend as the plugin, but a different user interface. Also, the CLI app manipulates existing .kicad_pcb files (which must not be opened in another application).

For usage information and available commands and options, run:

kivar --help

KiVar 0.2.0 introduced 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.

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.

Further reading: Choice Expressions.

While the legacy format of the KiVar.Rule field is very similar to the current "Combined Component Assignment Record" (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.

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:

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

There is also a Group Property Assemble (identifier !), which resolves to "Fit", "Pos" and "Bom", 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:

New behavior:

Further reading: Default Choices.

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 processor 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.

Further reading: Implicit Property Defaults.

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.

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.

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.

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.

Severity: Not critical (backwards-compatible).

KiVar 0.3.0 added Feature Properties, which allow you to

• enable or disable the visibility of individual 3D models of a footprint and
• suppress the application of solder paste for SMD pads of a footprint.

Severity: Not critical (backwards-compatible).

Base and Auxiliary scope were renamed to Component and Field scope, respectively, to better reflect their usage due to the following change:

It is no longer necessary to declare Choices in Component (ex "Base") scope before they can be used in Field (ex "Auxiliary") scope. Expressions in Field scope now implicitly declare Choice Identifiers, just as in Component scope.

Severity: Not critical (backwards-compatible).

Version 0.4.0 introduces Stand-In Choices, which act similarly to Default Choices, but do not inherit Content or Properties for declared specific Choices. Stand-In Choices may therefore be preferred over Default Choices in many cases, for example when making use of Implicit Property Defaults.