markh-de/kivar

PCB Assembly Variants for KiCad

kivar's Issues

clarify quoting and escaping

Quoting and escaping part of the documentation looks a little bit misleading. Special characters are really not considered to be special in pair of parentheses, but this not apply to parentheses of the choice definition. Rule asp ch1(-12V) ch2(-5V) will cause an error. Rule asp ch1((-12V)) ch2((-5V)) is correct, but does not help with assigning -12V value, since it assign (-12V). Correct way how to do it is to use asp ch1('-12V') ch2('-5V') or asp ch1(-12V) ch2(-5V).

I know it is just low priority detail, it just looks interesting to me. :-) Is there any practical use of fact that spacial characters are not considered to be special in ( )? Or it is just implication of the fact, how KiVar internally works?

kivar-cli: syntax error of KiVar.Rule does not report an error

Originally, I had following KiVar rule: VOLT_RANGE 1208(BSC026N08NS5) 1210(BSC035N10NS5) 1308(ISC014N08NM6) 1310(ISC022N10NM6). In order to test KiVar, I deleted first closing parenthesis, so the rule was: VOLT_RANGE 1208(BSC026N08NS5 1210(BSC035N10NS5) 1308(ISC014N08NM6) 1310(ISC022N10NM6). When I tried to run KiVar plugin from gui, it reported error, as expected: Q3: rule splitter error: Unmatched opening parenthesis. When I tried kivar-cli with pcb containing this syntax error, no error was reported, kivar-cli worked "normally". According to output of kivar-cli list -d board.kicad_pcb it was just ignoring the part Q3, which had syntax error in the KiVar.Rule field. I would expect the kivar-cli to print same error, as the gui.

KiVar testing

I have prepared a little testing pcb file for KiVar: errors.zip. This one should test, if KiVar discovers and correctly reports an error. Righ now, I manually open the KiVar gui and read through all the errors. In the future, this could be done by kivar-cli and script which will parse and check the output.

My next idea is to prepare similar board with more tests - changing values of components, changing DNP, case sensitivity for aspects and choices naming ... In this case, KiVar should not report and error, instead it shoul run and perform variant switching. After that, Pick-and-Place file would be generated and compared to the correct one, which was manually checked. This could be also automated by kivar-cli and some scripts.

More ideas and feedback are welcomed, especially:

• it this even right way, how to test KiVar?
• what else should be tested? Where could be bugs?
• way of collaboration on this - Should I fork KiVar repository and create pull request or create another repo? Sending pcb file zipped as attachment to issue is not comfortable ...

kivar_cli: instalation and usage on windows

I am using KiCad on regular windows machine, so I tested kivar_cli there. Here are my observations:

• just mention for the beginning: kicad installation on windows has its own command prompt, it is not possible to use kicad from regular command line or powershell
• ./kivar-cli --help does not work for windows, it probably does not uderstand the ./ and the fact, that it is python script. I was able to run it by command python kivar-cli --help
• it is possible to run the script only from the folder, where it is located. It should be probably added to $PATH or something like this during plugin installation
• author of KiKit plugin was probably solving similar issue. According to its documentation, KiKit has multiple parts - action plugin for pcbnew (installed by PCM) and backend installed from kicad command prompt using pip.

How to install KiVar from actual repository state

How should I install KiVar, if I want to try the newest development version (actual state of the main branch)? There are only instructions for PCM and for manual instalation from the release zip archive in the readme.md.

Add deep rule ambiguity check

Instead of a verification step for dedicated configurations (=sets of aspect choices), check for choice ambiguity during database building and return a list of errors in case some choices are not unique.

plugin icon does not work

Describe the bug
Windows version of KiCad does not show correct icon for KiVar plugin. It shows general puzzle icon instead

To Reproduce

1. install plugin as described in documentation
2. in pcbnew, do: tools -> external plugins -> refresh plugins
3. in pcbnew preferences -> PCB editor -> action plugins select "show button" for KiVar and hit OK
4. KiVar shows in pcbnew top panel, but icon is just general puzzle picture, not picture contained in the plugon repository

Expected behavior
Plugin icon will be shown instead of general puzzle icon

Screenshots

Desktop (please complete the following information):

• OS: Windown 11, tested with KiCad 7.0.10 and 8.0.0-rc2

Enable/disable solder paste per footprint

KiVar shall be able to switch solder paste application per footprint.

For this, the FOOTPRINT.Get/SetLocalSolderPasteMarginRatio() shall be used.

As this shall be mapped to a bool property, the original value must be saved. Therefore, a negative offset value shall be used.

As the resulting clearance is the sum of the PasteMarginRatio and the PasteMargin (which can be a fairly high positive value), there shall be a safety margin to make sure the effective solder paste amount (per pad) is really reduced to zero. Also, there can be an additional boundary check for reasonable PasteMargin values.

Using the Offset Value:
KiVar shall classify a footprint as with paste if the ratio value is in the (usual) range of -10.0 to 10.0 (i.e. -1000% to 1000%) or without paste if the ratio values is in the range -10010.0 to -9990.0 (i.e. -1001000% to -999000%). If the ratio value cannot be classified, an error shall be thrown.

Enabling/disabling paste is then done by adding/subtracting the 10000.0 (i.e. 1000000%) offset.

Idea: Maybe the offset can use some "signature", such as 7573866582 or just 866582, representing the concatenation of the decimal ASCII codes for KIVAR or VAR, respectively.

The bool property identifier to be used shall be s (for "solder paste enabled", as p is already claimed by "in position file").

There shall be a note in the docs that this property will not be applied to "SMD Aperture" type pads.

This issue is related to #52, which was about "completely" removing footprints, although it seems that the real use-case was just enabling/disabling solder paste per footprint.

kivar-cli: Script does not read KiVar.Rule

Describe the bug
kivar-cli list Board.kicad_pcb
returns
Error: No rule definitions found.
when field KiVar.Rule is used.
e.g. KiVar.Rule = ETH *,NO(-!) YES(+!)

When naming the field Var (like done in the Demo-Project) the script returns correct data:
ETH: NO YES

BUT... the action script inside KicadPCB doesn't find any data with variabl "Var"...

Expected behavior
KiVar.Rule is used from CLI and GUI (not Var)

Desktop (please complete the following information):

• OS: Linux
• Version: f5b5434

KiVar 0.1.2: No rule definitions found - kivar-demo

Describe the bug
The KiVar plugin cannot be started in the example kivar-demo project.

To Reproduce

1. install the KiVar from Plugin and Content Manager
2. open kivar-demo.kicad_pro in KiCad 8.0.1 release build
3. in PCB editor open KiVar plugin
   Expected behavior
   Variant selection gui should be appeared.

Screenshots

Additional context
Application: KiCad PCB Editor x64 on x64

Version: 8.0.1, release build

Libraries:
wxWidgets 3.2.4
FreeType 2.12.1
HarfBuzz 8.3.0
FontConfig 2.14.2
libcurl/8.5.0-DEV Schannel zlib/1.3

Platform: Windows 10 (build 19045), 64-bit edition, 64 bit, Little endian, wxMSW

Build Info:
Date: Mar 15 2024 01:52:47
wxWidgets: 3.2.4 (wchar_t,wx containers)
Boost: 1.83.0
OCC: 7.7.1
Curl: 8.5.0-DEV
ngspice: 42
Compiler: Visual C++ 1936 without C++ ABI

Build settings:

link to migrate does not work + migrate part of the docs not present

Describe the bug
I installed KiVar 0.2.0-dev32 and run it with the board file, which already contains some KiVar rules. KiVar reported, that it does not find any valid rules, but it found 140 legacy rules and offers me a link https://help.kivar.markh.de#migrate. Links directed me to the readme.md from the kivar repo, but there is no part about the migration written yet.

I want to convert KiVar rules from the legacy to the new format on that board, so the migration part of the documentation will be handy. If it will be ready soon, I can use it (=test it for you). Otherwise, I will do the conversion on my own and I will write here some notes about it, so you can use the notes when creating the migration section of the documentation.

Do you have some guess, when the migration part of the documentation will be ready, so I could decide whether I will wait for it or not?

Switch visibility of individual 3D models of a footprint

Add an indexed property type that allows switching visibility of 3D models of a footprint.

The new property identifier could be m (for model), followed by an index, which addresses the 3D model file entry of the footprint.

Example:
Choice expression -m1 +m2 disables visibility of the first 3D model file entry (not yet sure about the index base, should it be 1 or 0?) and enables visibility of the second 3D model file entry. Implicit defaults will take care of assigning the opposite to other choices.

kivar-cli: state arguments -a -Q should not be used simultaneously

Command kivar-cli state -a -Q aspect board.kicad_pcb will outputs only choice selected by aspect, not all of them, as instructed by -a. Options -a and -Q aspect are exclusive and kivar-cli should report an error, when these options are used simultaneously.

kivar_cli: primitive test

There is relation between kivar-clioutputs: kivar-cli state "+" kivar-cli check "=" kivar-cli state --all. Primitive test of kivar-cli can be preformed by running these 3 commands and checking their outputs, if they match the rule listed above.

kivar-cli: omit board filename if only one is in the current working directory

To save some typing, it could be beneficial allowing to ommit pcb filename, if only one pcb file is found in current working directory. This would be usually the case, since each kicad projects resides in its own directory and usually have only one pcb file. If multiple files with pcb are found, kivar should print an error message.

Incorrect RefDes when reporting rule error

Kivar should report error Rule mixes choices with defined (2) and undefined(1) values (either all or none) for components R13 and R15 in attached pcb. Instead of that, it reports the error multiple times for R18 (last component checked). When the last line of report is clicked, R15 is correctly highlighted, if previous line is clicked, the R13 is correctly highlighted. It looks like error was identified correctly, but refdes was accidentally overwritten by the refdes of component, that was checked at the very end.

Tested with KiCad 8.0 and KiVar 0.2.0-dev6 on machine with win11

example PCB: errors.zip

R13 selected:

R15 selected

footprint visibility when populating/unpopulating

Is it possible to completely remove a not populated footprint from the board layout when switching aspects?

This would be handy for creating different stencils when the choise is between LQFP and QFN package for the same component

Add rules migration hint to plugin

If the v0.2.0+ plugin does not find any rules in the new format, but finds at least one legacy KiVar.Rules field, the "no rules found" dialog shall be swapped by a dialog telling the user that rules need to be revised and that the old field name is not used anymore.

There shall be a web-link to the migration guide on the release series branch.

Create own PCM repo for pre-releases

Do not pollute the official KiCad PCM repo with pre-releases that lack proper documentation.

Try to add our own pre-release (and release) repo for brave testers.

Is it just a matter of copying the build artifacts of the KiCad PCM repo CI to an own file-storage and HTTP server, such as https://pcm.kivar.markh.de?

KiVar warn about legacy rules only if there are no rules in new format

Right now, KiVar prints warning about presence of the rules in legacy format (nice feature). It does it only if there are no rules in new format. If both formats are present, no warning is displayed. Maybe it will be goot idea to show this warning always, when legacy format rules are found.

New plugin icon

The original icon does not emphasize the aspect of switching between variations. Use a modified version of the icon to fix that.

Also, the border takes up precious space and does not match the icon style of KiCad. Remove the border.

Can I have multiple attribute change by a selected variant?

I have MPN attribute that has a value for a specific resistor, capacitor. If I change a value, I would like to change the MPN attribute as well.

Some component has MPN1, MPN2, MPN3 ..etc. I would like to have control on these too.

There is an attribute SPECS, which contains specification for a component. E.g 10k/0402/1% or 100nF/0603/10%/50V/X7R ..etc. And if the variant use a different value, the specs should be updated too.

How can I do this in KiVar?
Can I add multiple attributes into the Choices?
E.g.:
Variant1 Test1(Value=3k,MPN=xxcvcx,SPECS=3k/0402/1%) Test2(Value=1k,MPN=yyyxy,SPECS=1k/0402/5%)

Thanks!

control KiVar from command line

Is it possible to control KiVar from command line? I am using KiBot to generate gerber data and position files. If I could call kivar from command line and tell it somehow, which variant I need to set, I can automatically create position files for all assembly variants by running single script which would do following:

• call kibot to generate gerbers
• call kivar to set variant 1
• call kibot to generate position files for variant 1
• call kivar to set variant 2
• call kibot to generate position files for variant
• ...

separate options for dnp, not-in-bom and not-in-pos

Why is there only option-!, which controls fit/unfit status of the component? If I understand it correctly, this option control "not in bom", "not in pos files" and "dnp" kicad attributes together. Did you think about adding separate options for controlling the attributes individually (somethink like -dnp, -nbom, -npos + keeping the -! as shorthand to manipulate all of them at once)?

There is one marginal example, of usage separate options:

• lets suppose, I have one PCB design, but there is more variant of bare pcb, which can be produced from the design (different copper thicknesses in pcb stackup, different layer count)
• it is good idea to add PCB itself to the BOM file (just as reminder for assembly house, that they needs to order pcb alng with other components)
• so I would create "virtual" componnet to appear in BOM
• since there is multiple variants of the board, I would use KiVar to take care of the variants
• there is no need to have entry for PCB in position files

I know the example above is really unlikely to happen, so take it as interesting thing to think about. The truth is, that I met with all listed conditions in real life. Having PCB as one item of the BOM was requirement of one assembly house and I already designed several boards, which use same gerber data, but different fabrication specs.

Update documentation for 0.2.0 release

There were so many changes to the internals and the syntax and fields, which are not yet covered by the documentation.

This needs to be done before the 0.2.0 release.

kivar-cli ends with error `TypeError: argument of type 'NoneType' is not iterable`

kivar-cli ends with TypeError: argument of type 'NoneType' is not iterable when run with this PCB file.
exact command: python kivar-cli check errors.kicad_pcb (run on win 11 from kicad command promt in ...\Documents\KiCad\8.0\scripting\plugins)
kivar version: 0.2.0-dev10
full error message:

C:\Users\JanHladík\Documents\KiCad\8.0\scripting\plugins>python kivar-cli check errors.kicad_pcb
Traceback (most recent call last):
  File "C:\Users\JanHladík\Documents\KiCad\8.0\scripting\plugins\kivar-cli", line 258, in <module>
    sys.exit(main())
             ^^^^^^
  File "C:\Users\JanHladík\Documents\KiCad\8.0\scripting\plugins\kivar-cli", line 246, in main
    if not check_command(args.board): # , args.verbose
           ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\JanHladík\Documents\KiCad\8.0\scripting\plugins\kivar-cli", line 135, in check_command
    vardict = get_vardict(b)
              ^^^^^^^^^^^^^^
  File "C:\Users\JanHladík\Documents\KiCad\8.0\scripting\plugins\kivar-cli", line 35, in get_vardict
    vardict, errors = kivar.get_vardict(board)
                      ^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\JanHladík\Documents\KiCad\8.0\scripting\plugins\kivar.py", line 356, in get_vardict
    return build_vardict(load_fpdict(board))
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\JanHladík\Documents\KiCad\8.0\scripting\plugins\kivar.py", line 482, in build_vardict
    error_str = add_choice(vardict, uuid, aspect, name, content, field, all_choices[aspect])
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\JanHladík\Documents\KiCad\8.0\scripting\plugins\kivar.py", line 308, in add_choice
    return f"Undeclared choice '{choice}' (in aspect {quote_str(aspect)})."
                                                      ^^^^^^^^^^^^^^^^^
  File "C:\Users\JanHladík\Documents\KiCad\8.0\scripting\plugins\kivar.py", line 115, in quote_str
    if any(c in str for c in ', -\\()='):
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\JanHladík\Documents\KiCad\8.0\scripting\plugins\kivar.py", line 115, in <genexpr>
    if any(c in str for c in ', -\\()='):
           ^^^^^^^^
TypeError: argument of type 'NoneType' is not iterable

With my poor knowledge of Python and a help of ChatGPT, I was able to fix it by adding following into the function quote_str(str):

    if str is None:
        return "''"

Whole function after fix looks like this:

def quote_str(str):
    if str is None:
        return "''"
    if str == '': result = "''"
    else:
        if any(c in str for c in ', -\\()='):
            result = "'"
            for c in str:
                if c == '\\' or c == "'": result += '\\'
                result += c
            result += "'"
        else: result = str
    return result

I am not sure, if this is real fix or just workaround, please do a real fix :-)

Distribute the CLI app as a PyPI package

It does not make much sense to distribute the CLI app as part of the PCM plugin.

Also, downloading and extracting the release package is not very convenient for users.

So, distribute kivar or kivar-cli (whatever it'll be called) as a PyPI package, installable via pip.

Allow rules without any component value definition

The current rule concept requires that each flattened (i.e. after applying default values, if available) choice defines a component value.

However, it would be useful to allow rules that do not define any value for a given component. That is, the currently applied component value stays untouched. It must be checked that each rule defines either

• a value for each flattened choice, x-or
• no value for any flattened choice

to avoid a mixture of choices that modify the value and choices that leave the value untouched.

Use-case: Parts which should only be switched between fitted and unfitted (DNP), but which always keep the same (currently assigned) value.

Add a release series maintenance branch for v0.2.x

Add a v0.2.x release series maintenance branch that keeps v0.2.x-specific documentation and demo project. Link to it from the corresponding releases (plugin, CLI).

This should avoid confusion with the stuff on the main branch.

assembly variants for other fields than value

According to the plugin documentation, there is way how to vary multiple component fields by having multiple instances of the component and switching -! options to fit the component with desired set of fields. Downside of this approach is more complex schematic and overlapping footprints, which require some drc tweaking. Here is idea of another possible approach:

• instead of KiVar.Rule field for variatlion of the Value field, lets use KiVar.Value field
• for variation of other fields, lets use KiVar.<fieldname> field
• all KiVar.<fieldname> fields for one components needs to be compatible. Easiest way (and the least user friendly) to achieve this is to require them to have same aspect name and same choice names

Here is example for variation of power transistor (value, datasheet, description):¨

• KiVar.Value = VOLTAGE 80V(BSC026N08) 100V(BSC035N10)
• KiVar.Description = VOLTAGE 80V('80V Power transistor in TDSON8 package') 100V('100V Power transistor in TDSON8 package')
• KiVar.Datasheet = VOLTAGE 80V('http://...link-to-bsc026.pdf') 100V('http://...link-to-bsc035.pdf')

Another example is variation of value and LCSC partnumber for pull-down resistor:

• KiVar.Value = pulldown weak(100k) strong(1k)
• KiVar.LCSC = pulldown weak(C25803) strong(C21190)

Allthough identical rules are formulated, one Component does not react as the others

Describe the bug
I have a board where several components are populated or not according to several rules.
One of those components does not get unpopulated allthough the rules are identical for all components (copy-paste)

To Reproduce
I could not reproduce it with a new KiCad-project.
I use KiVar on several existing projects, but this is the only one with a problem

Desktop (please complete the following information):

• OS: Windows
• KiCad Version: 8.0.1
• KiVar Version: 0.1.2

Additional context
I can confidentially share the project in question

gui: show all components affected by the aspect

There is nice feature in kivar-cli: kivar-cli list --detailed board.kicad_pcb. Maybe it would be worth to add something like this also into the GUI. For example:

• add button "details" or "show components" next to dropdown for each listed aspect
• to the bottom part of the gui, add second tab with name "aspect details"
• when "details" / "show components" button is clicked, all associated components are listed in the bottom part of the GUI
• listed components are clickable - same as they are, when listed for chages when selecting variation choices
• instead of adding button "details" for each aspect, it could be activated by opening the dropdown. Or, aspect name itself could be the button

kivar-cli: --verbose does something only for `set`

Option --verbose is listed in help of all positional arguments (list, state, check, set) but it does something only for set. When used with list, state or check, output printed to the terminal is the same. I would expect to have --verbose listed in help only if it does something :-)

Finalize rule syntax and field names

While the basic rule syntax is getting settled, the field names will still get an overhaul.

I'll add my list of ideas and plans soon.

control text variables from KiVar

Is there any way, how to affect text variables by KiVar? It would be handy, if KiVar could somehow tell, which assembly variant is actually selected. Right now, I am using KiBot to automatically generate gerbers and assembly data from project. It could read text variables stored in project and use them as filenames for the outputs. I am used to name bom and pick-and-place data according to selected assembly variant. If KiVar could do this automatically, I would not need to set them manually, thus less work and less chance for my error.