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
Contents:
Create a new JITX project and set up 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 lineimport ocdb/utils/defaults
- Near the top of the file, insert the line
- Update the design rules for the board.
- Edit
run-design.stanza
and replace the line that saysset-rules(design-rules)
withset-rules(jlcpcb-rules
- Edit
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.
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 (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.