KiCad Workspace / Panelizer / Build Variants / Differ

Kikakuka (企画課, きかくか, Planning Section) (formerly Kikit-UI) is mainly built on top of KiKit, Shapely, modified pcb-tools, OpenCV, pypdfium2 and PUI.

It creates a few more dimensions for KiCad:

• Workspace and project management
• Revision management
• Build variants
• Panelization
• FreeCAD integration for flexible PCB bending and multi-board assembly

Features

• Workspace Manager
  • Easily navigate between projects
    • Automatically open multiple KiCad instances on macOS
  • Recall windows of previously opened files (macOS and Windows only)
• Differ
  • Highlight changed areas
  • Schematic diff viewer
  • PCB diff viewer
  • Git support
• Fabrication Planner
  • Panelizer
    • Interactive arrangement with real-time preview
    • Freeform placement not limited to M×N grid configurations
    • Support for multiple different PCBs in a single panel
    • Automatic or manual tab creation
    • Automatic V-cut/mousebites selection
    • Enable hole creation in panel substrate for extruded parts
    • Load KiKit multiboard files as multiple separate boards
    • No coding skills required
  • Build Variants
    • Single PCB without panelization can be done with frameless setting
    • Each PCB can have its own flag settings
• Gerber handling
  • Available in the panelizer
  • Or direct conversion to .kicad_pcb
  • Compared with KiCad output
    • Better restoration of oval drill holes
    • Allow attaching BOM/CPL (converted to reference-only footprints)
• CLI
  • Convert saved .kkkk_pnl to kicad files in one command
  • Same usage for panelizer & build variants
• FreeCAD Integration (only tested on macOS/Windows)
  • Requires FreeCAD 1.0 or later
  • FreekiCAD supports loading multiple .kicad_pcb files into a FreeCAD document
  • Designed to work with the Manipulator workbench and FreeCAD's new built-in transform tool; alternatively, use the automatic coupler-based PCB alignment described below.
  • A sketch is provided for real-time board outline editing in FreeCAD
  • Components moved in FreeCAD are synced to KiCad in real time
  • Auto or manual in-place PCB reloading
  • Optional copper and solder-mask import, with outer copper, inner copper, and mask controlled independently
  • Flex PCB bending driven by bend lines and parameters defined in KiCad
  • Automatic coupler-based PCB alignment using matching CouplerFixed and CouplerMoving footprints, with coupler plane markers for inspection
  • kicad-python is used and the workspace manager handles multiple KiCad instances & API sockets

Workspace Manager

The .kkkk file saves workspace information in JSON format.

Differ

Schematics Differ

PCB Differ

• A diff sample of cynthion-hardware

Build Variants

Example: samples/build_variant.kikit_pnl and samples/build_variant.kicad_pcb.

Set BUILDEXPR in footprints' properties. This can be done quickly with Symbol Fields Table using the current sheet only scope. Remember to sync them to PCB afterward.

• Kikakuka extracts build flags from BUILDEXPR. Selected flags are interpreted as true, and vice versa.
• Footprints with the BUILDEXPR evaluated as false will be marked as DNP.
• Footprints with unset or empty BUILDEXPR will be kept as is.

BUILDEXPR

A boolean expression with operators:

• ~ Not
• & And
• | Or

It can be as simple as a build name as shown in the image above or an expression like (A | ~B) & C.

Panelization with different build variants

Single PCB without panelization can be done with frameless setting

Field Values Variants

Field#Flag or multiple flags like Field#FlagA#FlagB will set Field to the value where build flags contain all the flags. Field#Opt=A, Field#Opt=B will be displayed as dropdown options.

Panelizer

The .kikit_pnl file saves panelization settings in JSON format, with PCB paths stored relative to the file's location.

Global Alignment

Per-PCB Alignment

Substrate Hole

Tight Frame + Auto Tab + V-Cuts or Mousebites

Output

3D Output

Tight Frame + Auto Tab + V-Cuts and Mousebites

Loose Frame + Auto Tab + Mousebites

3D Output

Auto Tab

Tab position candidates are determined by the PCB edge and max_tab_spacing, prioritized by divided edge length (smaller first), and skipped if there is a nearby candidate (distance < max_tab_spacing/3) with higher priority.

In the image below with debug mode on, small red dots are tab position candidates, larger red circles are selected candidates, and the two rectangles represent the two half-bridge tabs.

Manual Tab

Auto tab is off for PCB with manual tabs. Drag inside the PCB for moving selected tab, drag outside the PCB for changing the direction for the selected tab.

FreeCAD Integration

Requires FreeCAD 1.0 or later and KiCad 9.0 or later.

• Manually install FreekiCAD to FreeCAD

  • Open FreeCAD's python console: Menubar -> View -> Panels -> Python Console
  • Get the installation path by executing print(os.path.join(App.getUserAppDataDir(), "Mod")) in the Python console
  • Create the Mod folder if it does not exist
  • Copy the FreekiCAD folder into the Mod folder
  • Install kicad-python into FreeCAD by executing the following command in the Python console

  import subprocess, os, sys; subprocess.check_call([os.path.join(os.path.dirname(sys.executable), "python"), "-m", "pip", "install", "kicad-python>=0.8,<0.9"])
  

  • Restart FreeCAD

• Activate Preferences -> Plugins -> Enable KiCad API, then close KiCad (let Kikakuka manage instances).

• Make sure the Kikakuka Workspace Manager is running.

• FreeCAD

  • Add PCB
    • Switch to the FreekiCAD workbench.
    • Menubar -> FreekiCAD -> Add KiCad PCB
  • Reload PCB
    • Right-click on the board object -> Reload KiCad PCB
  • Edit Board Shape
    • Expand the object's children.
    • Open the sketch with the _Outline suffix.
  • Inspect Copper Layers
    • FreekiCAD imports tracks, filled zones, pads, vias, and copper-layer graphics as separate F.Cu, In*.Cu, and B.Cu child objects.
    • ImportOuterCopper independently controls F.Cu and B.Cu; ImportInnerCopper controls In*.Cu. Both default to off.
    • Inner layers use their physical stackup Z and are normally hidden by the board body; hide the board or make it transparent to inspect them.
    • Copper is display geometry and does not add to component Z. The board thickness already includes the complete KiCad stackup.
  • Inspect Solder Mask
    • ImportSolderMask imports translucent F.Mask and B.Mask child objects, with pad/via openings computed by KiCad plus explicit mask-layer graphics. It defaults to off.
    • With mask import enabled, the board body uses the configured dielectric stackup colors and KiCad opacity, or white with KiCad's default board-body opacity when no color is available. Mask opacity likewise follows its KiCad stackup color. Both display opacities are scaled to 70% in FreeCAD. With mask import disabled, the original opaque board color is preserved.
    • Mask and copper are zero-thickness display geometry. Copper is placed 20 um outside the board and mask another 20 um outside copper; their physical thicknesses remain metadata only.
  • Coupler-Based PCB Alignment
    • Place a CouplerFixed footprint on the reference PCB and a CouplerMoving footprint on the PCB to be aligned. Couplers are matched by their KiCad reference.
    • On reload, a linked PCB with SnapToCoupler enabled (the default) is moved as a whole so that its moving coupler plane meets the matching fixed coupler plane face-to-face. Alignment uses each plane's position after flex-PCB bending. Each coupler is also available as a child object in FreeCAD; its plane marker is hidden by default and can be shown for inspection.
    • The bundled footprints are CouplerFixed and CouplerMoving in resources/kikakuka.pretty.
    • Alignment example boards: assembly-power.kicad_pcb, assembly-mcu.kicad_pcb, assembly-led.kicad_pcb, and assembly-mezzanine.kicad_pcb.
    • The coupler plane is defined by the footprint position, side, rotation, and these custom footprint properties:
      • Z moves the plane origin along the footprint's local Z axis. It defaults to 0 mm; values without a unit are millimetres, and mm and in are supported. The origin starts at the PCB surface, including the board thickness on F.Cu. The local Z direction is reversed on B.Cu.
      • Tilt tilts the plane around the footprint's local X axis. It is specified in degrees and defaults to 0.
    • Z and Tilt are independent: Tilt rotates the plane around its Z-offset origin and does not change that origin's position. The footprint's normal KiCad rotation supplies the rotation around its local Z axis.
  • Flex PCB Bending
    • Draw bend lines as line segments on KiCad's User.4 layer.
    • Add bend parameters as User.4 text near a bend line endpoint, for example a=-70 r=0.5 or a=-70 s=0.61.
      • The text anchor must be within 0.1 mm of a bend line endpoint.
      • a is bend angle in degrees.
      • r is bend radius in mm.
      • s is bend spanning in mm and is used to derive r when r is omitted, using the board thickness from stackup.
    • After loading the board in FreeCAD, each bend line appears as a child object with Angle, Radius, and Active properties.
    • The linked PCB object also has an EnableBending property to toggle the deformation on or off.
    • Imported copper and solder mask are cut with the same board pieces. Rigid display faces follow each piece, while faces in a bend band are rebuilt with the wedge's curved point mapping.
    • If no User.4 text is provided, the bend line still loads and can be configured directly in FreeCAD.

Coupler-Based PCB Alignment

Coupler Pair

Changing Z and Tilt

Coupler plane markers are available as child objects in FreeCAD and are hidden by default.

Flexible PCB Bending

Manual bending checks are currently done with these sample boards:

• samples/fpc.kicad_pcb
• samples/maze.kicad_pcb
• samples/maze_radius.kicad_pcb

For the implementation details of the bending pipeline, see FreekiCAD/ARCHITECTURE.md.

Bending + Assembly

Kikakuka Footprints

Kikakuka includes a KiCad footprint library in resources/kikakuka.pretty. Add that directory to KiCad's footprint library table (for example, as kikakuka) before placing these footprints:

• Variable displays its Value on the board. Use build-variant fields such as Value#Flag or Value#Option=Choice to show a value selected by the active build flags or options.
• StringTemplate formats its Value during export. Braced placeholders such as {Revision} are replaced with matching footprint properties or build options after build-variant fields have been applied.
• CouplerFixed and CouplerMoving define matching planes for coupler-based PCB alignment. Give a pair the same reference; use the Z and Tilt properties when the mating plane is offset or tilted from the PCB surface.
• Footprint is an internal, graphics-free placeholder used when Kikakuka converts an attached BOM/CPL into reference-only footprints. It normally does not need to be placed manually.

Run from source (Linux/macOS)

Make sure your python can import pcbnew

> python3 -c "import pcbnew; print(pcbnew._pcbnew)"
<module '_pcbnew' from '/usr/lib/python3/dist-packages/_pcbnew.so'>

On macOS, I have to use the python interpreter bundled with KiCAD

PYTHON=/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3

On Linux, you should be able to just use the your default python3

PYTHON=python3

Create a virtual environment and install dependencies

${PYTHON} -m venv --system-site-packages env
./env/bin/pip3 install -r requirements.txt

Update submodule

git submodule update --init --recursive

Run

./env/bin/python3 kikakuka.py

Run from source (Windows)

On Windows the Python interpreter is at C:\Program Files\KiCad\10.0\bin\python.exe. But however in my Windows environment venv is not working properly, here is how I run it with everything installed in the KiCad's environment.

# Powershell
# Initialize bundled submodules after cloning
git submodule update --init --recursive

&"C:\Program Files\KiCad\10.0\bin\python.exe" -m pip install -r requirements.txt
&"C:\Program Files\KiCad\10.0\bin\python.exe" kikakuka.py

CLI Usage

# Just open it
./env/bin/python3 kikakuka.py

# Start with PCB files
./env/bin/python3 kikakuka.py a.kicad_pcb b.kicad_pcb...

# Load file (.kkkk or .kikit_pnl)
./env/bin/python3 kikakuka.py a.kikit_pnl

# Headless export for panelization or build variants
./env/bin/python3 kikakuka.py a.kikit_pnl out.kicad_pcb

# Differ
./env/bin/python3 kikakuka.py --differ a.kicad_sch b.kicad_sch

# Gerber to KiCAD Conversion
./env/bin/python3 kikakuka.py gerber.gbr out.kicad_pcb
./env/bin/python3 kikakuka.py gerber_folder out.kicad_pcb # BOM/CPL will be detected if they are in the folder
./env/bin/python3 kikakuka.py gerber.zip out.kicad_pcb
./env/bin/python3 kikakuka.py gerber.zip out.kicad_pcb bom_or_cpl_1.csv bom_or_cpl_2.csv # BOM/CPL files are determined by filename regardless of argument order

Reverse-Engineering Notes for KiCAD Gerber

• Convert Gerber to .kicad_pcb with BOM/CPL using Kikakuka
• Footprint names are also exported, so Tools -> Update Footprints from Library can bring back the footprint if the name matches
• Lock the footprint, clean up with quick selection and deletion, unlock the footprint (you will need to set the Selection Filter)
• If footprint update fails, focus on the User.Drawings layer and set Selection Filter to Footprints-only can help you select individual footprints and then Change Footprint