How to Import Kicad Designs into JITX

This tutorial walks through importing an open source project usb-sniffer into JITX. This project is available under a BSD 3-Clause New license which allows us to use the data with acknowledgement to Alex Taradov (https://github.com/ataradov). At the end of this tutorial, we will have experience using the KiCAD importer.

Tip: More information is in the command reference

Create a New JITX Project and Setup for Importing

Create a new directory in your filesystem named kicad-tutorial. This directory will be the root directory for the imported design. Now use the New project command in the JITX sidebar of the VSCode extension to select the newly created (and empty) directory as the folder in which to create the project.

Let's add the Kicad project we want to import as a subdirectory of our new project directory. For this tutorial, we are going to use the usb-sniffer project as the starting Kicad project. Navigate to the git repository, download and unzip the repo using the Download ZIP option if you don't have git installed or git clone the repo into the project directory. For the git clone method, do the following:

cd kicad-tutorial
git clone https://github.com/ataradov/usb-sniffer.git

Delete the created files kicad-tutorial/main.stanza and kicad-tutorial/helpers.stanza as they are not needed for the imported project.

Our project folder now contains the following:

kicad-tutorial
 \ usb-sniffer/
 \ open-components-database/
 | stanza.proj

Import Project

Using the VSCode JITX extension, let's use the command to import a Kicad project Import from Kicad.

The file browser that appears is to choose the input Kicad project. Navigate to the usb-sniffer/hardware directory and press Choose as input directory.

The terminal window output alerts us to any issues and how the importer attempted to correct them. The log also describes those design elements that do not have a corresponding JITX construct. The log file is kicad-tutorial/kicad-imports/usb-sniffer/log.txt

A new directory, kicad-imports/usb-sniffer is created containing the imported design along with component and board data. usb-sniffer.stanza is the top level file of the new imported project. In order to run the design, the run-design.stanza file should be used.

Our project folder now contains the following:

kicad-tutorial
 \ usb-sniffer/
 \ open-components-database/
 \ kicad-imports/usb-sniffer
 | stanza.proj

To compile the imported usb-sniffer project, we now open the run-design.stanza file. We need to edit this file in order to successfully run the project. The changes are: - Add a new package for default board design rules. - Near the top of the file, insert the line import ocdb/manufacturers/rules after the line import ocdb/utils/defaults - Update the design rules for the board. - Edit run-design.stanza and replace the line that says set-rules(design-rules) with set-rules(jlcpcb-rules

Then, press "Ctrl+Enter" - and JITX will compile and run the imported project. You can open the schematic, board and design explorer views by using the buttons in the JITX extension.

Notes

The imported components will have their (X,Y) locations imported in the tool in the form of:

    place(self.BAT54S) at loc(-15.2019, 14.1859, 270.0) on Bottom

Once the component is placed in code like this, the component is considered locked and will not be moveable in the board view. If you want to move the component in the board UI, you will need to delete the place() statement in the code.

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.

Errata

See the Kicad Importer Errata for current known issues with projects imported from Kicad.