Introducing KiVar: PCB Assembly Variants for KiCad

Hi KiCad community,

I’d like to take the release of series 0.2.x as an opportunity to introduce KiVar to this forum today.

As you know, one of the features still missing in KiCad is PCB assembly variant management.

If you want to switch variations and have the changes reflected directly in your PCB and schematic files, then using text callouts to describe which components have to be changed in which way for switching the behavior of the circuit is tedious, hard to maintain, inconvenient and error-prone.

So I came up with a method to (more or less formally) describe component variations, assign them to groups (called aspects) and a convenient and safe way to switch between these defined variation options (called choices) with a KiCad plugin or command-line application.

The plugin has been around for a while now, but I think with release series 0.2.x the expression syntax and features have matured to a point, where it could definitely be helpful for many KiCad users. The feedback I have received from users so far makes me optimistic.

In my experience, there is rarely a static PCB design that would not benefit from one or more - even small - variation options. Be it switching an I²C address, a maximum current, a voltage threshold, a few bootstrap pins, the MPNs of equivalent ICs - or of similar ICs and their respective peripheral ICs - or switching between already designed-in options to reduce costs.

For the complete feature set it’s best to consult the documentation. But as a short impression what KiVar can do for you:

Depending on the selected component variation choices, KiVar can assign component values, custom field content and attributes (i.e. DNP, Not in Pos. Files, Not in BoM).

Future versions may also support switching of component-specific solder paste application and of the visibility of individual 3D models of a component.

Setup is easy. You simply write your rule expressions into custom fields of the relevant components and you’re done. If you make the changes in the Schematic Editor, you will have to sync them to your PCB first. If you choose to add the expressions directly in the PCB (and sync them back to the schematic later), you’re already good to go. Simply click on the plugin icon and select a variation choice per aspect.

Following are two very simple examples to give you an impression how to use KiVar:

To switch a resistor between fitted and unfitted, add a custom field to this resistor, with the following content:

Var = Resistor_Fitted Yes(+!) No(-!)

This will create an aspect “Resistor_Fitted” (this is a random name and can be whatever you like to use as identifier), which can be used for this resistor only, or for other components as well. Also, these other components can add further variation choices, which will then be added to the possible choices for that aspect.

Syntax hint: Property ! stands for: fitted + in position files + in BoM.

Another example: To switch a resistor value between , 47kΩ and 100kΩ, use:

Var = Resistance Zero(0Ω) Medium(47kΩ) High(100kΩ)

Syntax hint: Any choice argument not starting with - or + is interpreted as part of the value (in the scope used here).

These as just two very basic examples. KiVar can also assign custom field content (such as MPN, datasheet URL, order info), use different expression notations (useful for making parts of your rules visible in your schematic for documentation purposes) and allows fine control over attributes.

For more examples take a look at the real-world examples in the documentation or check out the demo project.

KiVar is available as a KiCad Action Plugin, for seamless use directly inside the PCB Editor with immediate effect on your open PCB file, as well as a command line application to be used on *.kicad_pcb files, for analyzing and switching variations in command line and script environments.

KiVar 0.2.x requires KiCad version 8 or later.

The KiVar plugin can be installed from the official KiCad PCM repository.

The KiVar command-line app can be installed with pip install kivar.

More information can be found in the documentation.

I hope it’s useful for you.

Mark

4 Likes

Nice. This missing feature has indeed been badly needed. I am still on v7 until I wrap up a production project but hope to jump to v8 soon and will definitely check it out. Thanks Mark.

The previous release, version 0.1.2, is also still available for KiCad 7. You can install it via PCM.

That release still uses the older rule syntax dialect and does not yet provide custom field manipulation. But it’s useful nonetheless, and you’ll get a feeling of the general workflow.

If you want to use it, make sure to check out the matching documentation for the 0.1.2 release.

Also, when using KiCad 7, restrictions regarding back-annotation to your schematic apply (as listed in the documentation). These restrictions were resolved in KiCad 8.

I hope so too but I’m finding your documentation very hard work.

Using the examples only, I’m making progress and yes, it looks to be very helpful so far :slight_smile:

Thank you for developing this plugin. I really needed it.
Any hints to do this? → Switch symbol kivar plugin

@RaptorUK: Looking at your other posting, I think you did a very good job in understanding the expression documentation. Sorry if it’s overwhelming at the beginning. I tried to be as correct, complete and precise as I could, and I’m fully aware that this can be boring or hard to read and understand. That’s why I included the examples.
However, I didn’t want to start with the examples because I feared that users might stop reading to early, before really understanding why and how exactly the examples work, and what else is possible.
Any tips how I could improve the documentation lecture experience or rearrange the sections are greatly appreciated.

Thank you for your reply and your willingness to take constructive criticism :+1: it’s not always the case.

The first thing that kept throwing me off was the repeated references to the previous version . . . I’ve only started using the latest version so it had a big impact on readability for me.

Then I just experienced a mass of terminology, I didn’t know which applied to my application or not so I had no way of filtering the information I needed to understand and that which I didn’t need to.

Perhaps a simple example early on in the Documentation would help illustrate some of the terminology ?

Having worked through some of the examples and setup my 5 variants I can now better understand some of the terminology.

The last thing I have to do now is my BOMs . . .

1 Like

Are you referring to the section “Migrating from KiVar 0.1.x”? Well, if you didn’t want to migrate, then you could have skipped that one.
I’ll consider moving it to a different place within the documentation, or at least add an info that new users may skip it (which may not be obvious right now).

A decision chart, including examples, might help. And a TOC that guides users of different experience levels (incl. users of legacy versions) through the most important parts. I’ll consider that.

I understand how the terminology may seem strange at first. But a different user told me (about the 0.1.x doc, admitted) that having a strict terminology and sticking to it throughout the documentation is a good thing (I share that opinion).

Documenting has consumed much more time than the actual implementation. And I have very few spare time, which makes it even less fun.

That’s why I’ve already cursed myself for not “simply” implementing a complete variant setup GUI, which would require so much less explanation. But otoh, I would not want to use undocumented expressions in the “Var” fields of users’ schematics (and I wouldn’t want to force users to use the GUI), so they would have to be documented anyway, additionally to the GUI.

Also, I’m counting on the KiCad developers (core team and community) to implement native variants support at some point in time, making KiVar obsolete sooner or later. So an additional GUI would only increase the obsoleted effort.

tl;dr
I’ll see what I can do to make reading the docs more fun.

Thanks for your feedback.

No not really . . . it was these . . .

" Prior to version 0.2.0, KiVar supported “Option” arguments. An Option always started with a - (dash) character, followed by the Option identifier."

“With version 0.2.0, this behavior has changed.”

“Starting with version 0.2.0, users can choose to only specify . . .”

"Prior to version 0.2.0 multiple Value arguments were forbidden inside . . . "

"Starting with version 0.2.0, Choice Expressions can now . . "

“Before version 0.2.0 the aspect identifier (name) . . .”

etc.

I’ve never seen a previous version so all these statements just make things unclear for me.

Yes, I understand that and I do applaud your efforts.

Me too, but how long have we been waiting . . . your software, for my current needs, make that a non-issue for me, so thank you.

If I can figure out how to get my variant number and PCBA revision number I’ll be done and have an easy process going forward.

:+1:

Yes, those quotes are part of the migration guide section. You can check that in the Outline view.
I will try to mark them more clearly as optional reading.
Sorry for any confusion caused.

Can you elaborate on this? What exactly are you trying to accomplish?
Do you want to modify some text on your PCB silkscreen/mask, depending on the selected variation choices?

What I was trying to do was get my variant number, my PCBA number (which is essentially my BOM) and revision into my BOM. I’ve done this now by adding a symbol and footprint just containing the Variant number and having it included in the BOM. I’ll probably end up making the PCBA/BOM revision number a manually added item to the BOM and include this step as a manual step in my documented process.

My PCB and PCBA (BOM) can have different revisions, for example if a component goes obsolete and I have to change it for a device with the same footprint this would be a BOM revision not a PCB revision. I need to allow and capture this difference.

Your software has enabled me to get 99% of the way to where I need to be, so, again, thank you. :slight_smile:

I modified KiBoM to do something very similar to that.

[edit]
More specifically:

  • I added a Text Variable to my schematic that holds our project reference.
  • Added
    def getText(self, name):
        return self.design.get("textvar", "name", name)
 

to “netlist_reader.py”

  • After the line output_name, output_ext = os.path.splitext(output_name) in __main__.py I added output_name = net.getText("PROJREF")

  • In bom.ini set output_file_name = %O-%V-%v and variant_file_name_format = %V

This gives me a BOM named like IPD-B-102-103-06.csv , where 103 is the variant and 06 the revision number.

1 Like

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.