How to import from KiCad into JITX

This tutorial walks through importing the open source Goldfish design into JITX. At the end of this tutorial, we will have experience using the KiCAD importer.

Tip: More information is in the command reference

Contents:

Create a new JITX project and set up for importing
Create and Run import.stanza
Next Steps
Notes

Create a new JITX project and set up for importing

Create a new project using the JITX VS Code extension, just like in previous tutorials.

Let's put the KiCad project we want to import as a subdirectory of our new project directory. Navigate to the Goldfish git repo and download and unzip or git clone the repo into the project directory.

Delete main.stanza.

Our project folder now contains the following:

kicad-tutorial
 \ Goldfish
 \ open-components-database
 | stanza.proj

Create and Run import.stanza

In visual Studio Code, let's create a new file import.stanza and save it in our main jitx project directory.

The contents of import.stanza:

#use-added-syntax(jitx)
defpackage my-design :
  import core
  import jitx/commands

import-cad("goldfish/cad", "imported-Goldfish", Kicad)

Our project folder now contains the following:

kicad-tutorial
 \ Goldfish
 \ open-components-database
 | stanza.proj
 | import.stanza

The first directory lists the location of the KiCad project file (.pro), in this case, in Goldfish/cad. The second directory is the output directory imported-Goldfish.

We can set overwrite => true if we want to overwrite the directory each time we run the import.

The terminal window output alerts us to any issues the import tool runs into and how the importer attempted to correct them. Some issues may need to be manually corrected after the tool finishes.

Common issues are schematic symbols with off grid pins and schematic symbols with hidden pins placed outside the main component area. These get turned into box symbols. We can check these schematic symbols manually.

Tip: If we are importing multiple projects, we can have separate import and output directories and use multiple import statements in a single stanza file.

Let's navigate to our project directory, open import.stanza, and press Ctrl+Enter to run this file.

The new directory, imported-Goldfish is created with component and project information. goldfish.stanza will contain the JITX project.

This project folder will not compile as is - it will fail due to "not found" errors. In order to run the imported-Goldfish project, we need to open it as its own project by going to "File" -> "Open Folder" and selecting the folder containing the run-design.stanza file. Then, open run-design.stanza and press "Ctrl+Enter" - and you will build the imported project.

Next Steps

The KiCad design is now in JITX. Next, let's edit the imported JITX project to use the more advanced features of JITX in the Revising an Existing KiCad Design in JITX tutorial.

Notes

The imported components will have their XY locations imported in the tool in the form of:

  place(J4) at loc(22.38, -55.24, 180.0) on Top

If we are designing a mating PCB, we can use this same notation with the same locations to place mating components in JITX.

Keeping the reference designators the same is an important method to be able to keep our layout when we make revisions. It is accomplished by:

  for inst in [<xxx>] do :
    reference-designator(inst) = to-string(ref(inst))

If we wish to name your instances something more descriptive, we can set reference designators manually with:

reference-designator(instname) = "U1"

Any instance without an assigned reference designator will get one assigned automatically.

Optional: Attach BOM data

JITX supports importing BOM data for manufacturer names and manufacturer part numbers (MPN) in imported pcb-components. This feature requires generating a jitx-import-bom.tsv in the import data directory.

See the BOM Data Format Reference to see how the data should be structured.

JITX Documentation