Quickstart 1: Your First JITX Design

NOTE: Before starting this tutorial, you should have installed and set up JITX.

Introduction

Welcome to JITX! This Quickstart tutorial is your gateway to faster hardware and PCB design.

In this tutorial, we will guide you to create your very first "smart" power regulator circuit to meet your design requirements automatically. This is a critical time saver for our JITX hardware engineers.

Using the code-based approach, we will:

  • generate circuits that can adapt to changes in your requirements
  • create schematics and PCB designs that are correct (due to intelligent code).
  • update circuit components using a single line of code.
  • accelerate your PCB design and layout speed by over 70%.

You typically can't find this kind of power embedded in any other ECAD tool!

So let's get started!

What is JITX?

JITX is a groundbreaking electronic computer aided design (ECAD) software that empowers electrical engineers to design electronics hardware and printed circuit boards (PCBs) faster using code.

This code-based approach to electronics and PCB design takes a lot of manual work out of schematic and PCB design, hence why JITX ends up giving a way faster workflow than normal for industry.

Before We Begin

First you need to install JITX. If you haven't done this yet, please refer to our JITX installation guide on the JITX website. Once JITX is up and running on your computer, you're ready to roll!

Overview

In this Quickstart Tutorial 1, we cover a lot of ground. You will

  1. Geting to Know JITX - Become familiar with the JITX workspace
  2. Create a simple design we will just call Design 1
  3. Learn the complete flow to design a printed circuit board (PCB)
  4. Generate a second design we just call Design 2 (our adaptive power regulator)

As we go through the tutorial, not only do you get a refresher on the PCB design process, but you see exactly how JITX introduces faster ways to do ECAD for printed circuit board design. Also, you will be given a number of exercises you can do to get you familiar with JITX and VS Code.

1. Getting to Know JITX

In this section you will learn where to find your project files, which windows are important in JITX and which mouse and button commands you need to work a design.

TIP: The Terminal window. In VS Code, there is a terminal that lets you execute commands - similar to Windows PowerShell or Mac OS Terminal. The terminal is useful not only for executing commands in JITX software, but for debugging your own design code.

To get comfortable with the terminal, let us do our first exercise.

Exercise 1

Your first exercise is to open the terminal window in VS Code.

To open the terminal, in VS Code, select the menu item View - Terminal (or type Ctrl + ` on your keyboard).

Once done, a terminal window should appear at the bottom of VS Code as seen below.

alt_text

Then the text in the terminal will tell you which user is logged into the machine and who is executing the commands.

Type the following command, such as dir if you are in Windows or pwd if you are on Mac OS or Linux.

Depending on your operating system, you will see the name of your current directory.

Mine shows:

kirschmackey@Kirschs-MacBook-Air ~ % pwd
/Users/kirschmackey

Once your terminal shows the directory you are working in and prints it to the terminal, you have successfully executed the command.

Close the terminal window by clicking on the 'X' icon at the upper right corner of the terminal window shown below.

alt_text

The Terminal disappears.

Exercise 1 - Done

Points Acquired = 2 points

Exercise 1 Takeaway

In JITX we are working with code now. In some cases, you will need to debug design behavior and compilation errors using the VS Code terminal window.

In upcoming tutorials when we say to 'run a command', we are referring to the VS Code terminal.

Next let's look at the different views of your design.

Window Views of Your Design

As you build your design, you have to look at the schematic, board layout, and files within your design to know if what you wrote in code is correct. To do this, click the JITX logo on your VS Code window (ours is on the far left).

That will make the JITX menu options and the Views section visible (see below).

alt_text

View Icons in jitX

These icons are important for verifying your design schematic and PCB layout at any time. We are ready for another exercise.

Exercise 2 - Design Views

In this next exercise, you will see which windows appear upon clicking the icons.

Step 1

First, click the Schematic icon. You should get an error message at the lower right of VS Code saying there is no schematic to show and to run a design containing view-schematic(). Later in our example design you will see the code that generates a schematic.

Step 2

Next click the Board icon. You will get an error message saying there is no board to show and to run a design containing view-board(). Later in our example design, you will see that there is a line of code that creates a board view.

Step 3

Still in the Views section from the previous photo, click the Checks icon. In this case, a window appears at the bottom, and multiple Panel tabs are open (see below).

alt_text

The highlighted panel is the 'JITX CHECK REPORT: CHECK REPORT' panel. Notice there are other panels as well, such as 'TERMINAL' (we were just in there in Exercise 1), 'PORTS', and so on. Click on each of those panels and observe what happens.

Step 4

Finally, click the Explorer button under our Views section.

You will see the 'JITX COMPONENTS' Panel appear at the bottom of the VS Code screen. This is our Open Components Database (OCDB) - a searchable, real-time components database that you can pull components from and use in your own designs.

Exercise 2 - Done

Exercise Points Acquired = 4 points

Exercise 2 Takeaway

Knowing how to navigate your design tool is critical for getting your designs finished faster.

Now that you have been introduced to the the JITX user interface, you are ready to create our first design.

2. Design 1 - Intro to JITX By Example

Let's get started with your first design.

Creating a New JITX Project (Example)

We are going to create a PCB design from scratch.

In the JITX VS Code panel, let's kick things off:

  1. Click the JITX app icon (if you already see Design Tools in the image below then no need, else it will close JITX. If you clicked anyway when it was open, just click the app icon again to make the Design Tools section in the picture below visible again) alt_text

  2. Create a new 'parent folder' to hold your designs in by going to menu File - Open (if you already created a folder) or File - New if you need to make a new folder.

  3. You can name the parent folder something like Quickstart1, similar to mine below: alt_text

  4. Once your new parent folder has been created or selected, click the Select Parent Folder button.

  5. This will populate the Parent Folder with the directory of the folder you just created.

  6. Create a new project by clicking under the Design Tools section and choosing New Project You will see a dropdown appear alt_text

  7. In the Project Name field, give your project a descriptive name, such as "regulator-tutorial."

  8. Then hit the Submit button.

JITX will open a new window in VS Code that points to a new folder created, named after whatever project name you chose. In this example, it created a folder named "Regulator-Tutorial".

New Files Created

Not only does a new VS Code window open to your new project folder, notice that new files were created.

alt_text

Let's get familiar with these files by doing some exercises.

Understanding What main.stanza Does

Each file in your design folder has important functions. We will explain each one briefly so that you are comfortable when modifying the main project file later on. Let's look at the most important file - the main project file, main.stanza

Main.Stanza

main.stanza is the main program file from which you run your entire design. The .stanza file is also where you define your electrical circuits and PCB. It even pulls functions from other coding files, like helpers.stanza.

We will break down main.stanza quickly so that you immediately understand what it is doing, then can make some modifications based on that knowledge. Here is an initial breakdown in the image below: alt_text

Main.Stanza - Functional Breakdown JITX made this example project and it is broken down into these sections:

  • Import major libraries, functions and commands (just like introducing header files in c programming) alt_text

  • Board dimensions and definition (shape, size, etc.) alt_text

  • Declaring the functional block diagrams (groups of circuits to execute those functions) - these are similar to declaring functions you want inside a main coding file.

alt_text

  • Adding components (electrical and/or mechanical) for those circuit groups (uses the JITX components database)

alt_text alt_text

  • Set PCB Fabricator and Board shape

alt_text

  • Set the schematic sheet parameters

alt_text

  • Set the main top level module for the design

alt_text

  • Finally view the schematic and PC board for layout alt_text

Now that we have a breakdown of the main.stanza file, we can move on to the next section. To solidify these concepts, you can perform the following exercises.

Exercise 3 - Creating Your Own main stanza file

Even though it may seem trivial, copying and pasting the code into a new file immediately after having the code structure explained will help you retain and understand the main.stanza details more effectively.

So in these exercise, we will make a clone of the main.stanza file by copying and pasting the example code into the new file and repeating the purpose of each code section.

  1. Step 1 - create a new file in VS Code by click the menu File - New File

  2. Then notice a top bar appear in VS Code awaiting the file name.

  3. Name your file main-exercise3.stanza and you will get a new window below alt_text

  4. Click Create File in the Finder window

Our new mock main project file has been created, it is visible in the VS Code interface and it is completely blank.

alt_text

Let's build it together:

  • Import major libraries and commands. Don't worry about where those come from yet as that is an advanced topic. To do this:
    • Copy the code below:
defpackage main :
  import jitx
  import core
  import jitx/commands
  import ocdb/utils/generic-components
  import helpers
  import ocdb/modules/passive-circuits
  • Paste it into your main-exercise3.stanza file. You have now imported high level functions and imported the open components database, plus access to some helper functions we will use later.

Let's repeat this process with the following code snippets.

  • Declare the board dimensions. Copy the code below and paste it into your own main-exercise3.stanza file.
; Define the shape/size of the board
val board-shape = RoundedRectangle(30.0, 18.5, 0.25)
  • Declare your functional block diagrams (which will eventually become circuit groups consisting of components, wired connections, etc.) - these are known as 'modules' in JITX.
pcb-module lm317a-regulator (output-voltage:Toleranced) :
  pin vin
  pin vout
  pin gnd
  pin adj
  • Add/create components (whether in modules or not)
    • 10 kΩ resistor
  ; Create a 10k resistor component
  res-strap(power-5v, signal, 10.0e3)
  • Mechanical component - label
  ; Write the board version on silkscreen
  inst version-label  : ocdb/artwork/board-text/version-silkscreen("Version 0.0")
  place(version-label) at loc(0.0, height(board-shape) / 2.0 - 1.0) on Bottom
  • Set the high-level design name
; Set the design name     - a directory with this name will be generated under the "designs" directory
;     the board           - a Board object
;     [optional] rules    - the PCB design rules (if not givn default rules will be used)
;     [optional] vendors  - Strings or AuthorizedVendors (if not give default vendors will be used)
;     [optional] quantity - Minimum stock quantity the vendor should carry (if not give default quantity will be used)
setup-design(
  "jitx-design",
  ocdb/utils/defaults/default-board(ocdb/manufacturers/stackups/jlcpcb-jlc2313, board-shape)
)
  • Set the schematic sheet size
; Set the schematic sheet size
set-paper(ANSI-A)
  • Package everything into a complete design and set that as the highest level module
; Set the top level module (the module to be compile into a schematic and PCB)
set-main-module(my-design)
  • Publish/view the finished schematic, and the PCB layout generated from code
; View the results
view-board()
view-schematic()
view-design-explorer()

Once you have copied and pasted those lines of code into your own main-exercise3.stanza file, you should end up with ~46 lines of code, because it will be missing the code to do design checks (shown below):

; Use any helper function from helpers.stanza here
; run-check-on-design(my-design)

Why did we skip this snippet of code? Because we will not be executing Checks on the designs in this guide.

Also notice that this code snippet was commented out (in JITX, code is commented out using the semicolon character at the beginning of the line).

Deleting a File

In VS Code, Right click your main-exercise3.stanza file, then choose Delete from the drop down menu. Your file you just made will be deleted. We no longer need it for this Guide.

Exercise 3 - Done

Points Acquired - 18 pts (2 pts per copied and pasted code)

What You Learned

JITX establishes its designs using code.

  • You understand the structure of a typical example code-defined schematic + PCB layout project in JITX
    • you can import functions
    • call components from a database of existing JITX components that we open to the community.
    • JITX turns all designs into modules that can be used later
    • you can declare the board size and the schematic sheet size
  • You know how to create files using the VS code interface directly
  • You know where to find your design files in VS Code

As an optional exercise, you are encouraged to click the other files in your folder, such as helpers.stanza, and stanza.proj and guess what they help your design to do.

alt_text

You can also click one of the files, and choose to Reveal in Finder (Mac OS) or Explorer (Windows OS). That will open the folder and show that new folders were created in your project folder as well, containing many .stanza files, components, folders for 3D models, etc.

Now that you know there is a lot more than meets the eye with simple project creation (multiple folders and files are generated to make a project), the next step is to generate the schematic and PCB layout views from the Design 1 code.

Design 1 - Generating the Schematic and PCB

With your code in place, it is time to bring your design to life.

In the previous exercise, by making a new project, you you created simple PCB code that contained a resistor and a label.

Now it’s the moment of truth - we will generate the schematic and PCB layout view for design 1!

With the main.stanza file active in VS Code, click anywhere inside the code, then press Ctrl + Enter to run the program (use the left keyboard Ctrl key instead of the right Ctrl key).

JITX compiles your design and generates a schematic and board in the PCB layout panel below.

alt_text

Note that just like above, you may see a blank design in the "JITX VISUALIZERS: BOARD". To correct this, click the the image of a double-headed diagonal arrow icon show in the image below (upper left side of VS Code terminal Panel amongst other icons).

alt_text

Once the icon is clicked, your PCB view will zoom in like below: alt_text

You generated a schematic and a printed circuit board using a frew lines of code instead of using manual graphically drawn methods (typical EDA flow).

Key Takeaway

Using code to generate a physical design and schematic is a game-changer. It's faster and more efficient than manually moving components around. Your time is precious, and JITX ensures you make the most of it.

About the Schematic - The schematic, is the upper left view in the image above. Once generated, the schematic cannot have its connections edited graphically. You can click in the schematic window, drag components around withe left mouse button, pan using the right mouse button, and zoom using the scroll wheel. However, it is impossible to modify the connections from the schematic view. In JITX, we prevent net adjustments via schematic view to prevent design mistakes and to maintain the correctness of the original design (which is defined using the code instead).

Tip: Initial Schematic View - Your schematic and PCB views may not show the components up close, so you may need to zoom in (Scroll Up while in the window) and pan (Hold and drag the canvas with the right mouse button) to see the part(s) more clearly.

About the PCB - You can also click around, zoom and pan in the PCB view. When you select the resistor 'R1' in the layout, it gets highlighted in the schematic view as well. This behavior is commonly known as 'cross-probing' in ECAD tools.

Alright, so congratulations on generating your first schematic and PCB layout using code!

In the next section we will show you how to make changes to your schematic and board (an Engineering Change Order) using code. Then that will complete Design 1 in this guide.

Engineering Change Order (ECO)

In practice, hardware designs often require changes or updates after the PCB has been created, even after PCB routing has started. This kind of change is called an Engineering Change Order (ECO) and while it may happen at any phase of the PCB design process, it is progressively more expensive to implement during later stages of the design.

Exercise 4 - Engineering Changes and Updating Code

In any case, let us say our design needs a couple tweaks based on customer feedback. That means we need to perform an ECO.

Removing Components via Comments

First let us remove components. To remove a part/component from a design, simply delete (or comment out) the code.

For instance comment out the res-strap(power-5v, signal, 10.0e3) line by placing a semicolon (;) at the start of the line.

Then while still in the code, hit Ctrl+Enter (and give JITX time to refresh), your resistor disappears from the schematic and the PCB.

alt_text

Changing a Component Value

Then let’s say we need to update the version of the design that has no resistor. We should change the label from 0.0 to 0.1. To do that, change the Version 0.0 text to Version 0.1 in the code below.

; Write the board version on silkscreen
  inst version-label  : ocdb/artwork/board-text/version-silkscreen("Version 0.0")
  place(version-label) at loc(0.0, height(board-shape) / 2.0 - 1.0) on Bottom

You should end up with this code:

  ; Write the board version on silkscreen
  inst version-label  : ocdb/artwork/board-text/version-silkscreen("Version 0.1")
  place(version-label) at loc(0.0, height(board-shape) / 2.0 - 1.0) on Bottom

After the change, perform that ECO again by making sure your cursor is anywhere inside the code window, and regenerating with Ctrl+Enter.

Then voila! Your design label has been updated in the schematic and the PCB layout!

alt_text

Excellent. You completed exercie 4!

Exercise 4 - Skills Attained

In this exercise you learned how to make changes to your code and regenerate your schematic and PCB design. Some things to rememeber are:

  • you can comment code using semicolons ;
  • you can also delete the code
  • to commit changes to your design graphically, type Ctrl+Enter (using the left Ctrl key)

Exercise 4 Points Acquired = 3

Exercise 4 - Done

Design 1 Finished

Now that you have finished your first design and gotten familiar with JITX, let's jump into the second design in this guide.

Part 2 - The PCB Design Process and Your Second Design

In the previous part of this guide, you became familiar with JITX, how to navigate the tool and how to generate and update a design.

In this Part 2, you will learn a lot more about the practical applications of using JITX for PCB design. We will cover:

  • The standard hardware design process
  • How to use JITX to implement a simple design

3. The Standard Hardware Design Workflow - Idea to Manufacturing

The following is the end-to-end workflow of going from a product idea to a PCB design. Then in the design 2 example, we show you how to implement this using JITX more quickly than it would take if done graphically like one would if using existing ECAD software.

Hardware Design Process + Powered by JITX

  1. Define requirements
  2. System level design, then a block diagram
  3. Create a new JITX project (in JITX, the project files are all modifiable code)
  4. Pull in major components to your JITX project (JITX components are taken from a live database so you don't have to spend as much time searching for the right solution).
    • Import your components from an existing design or component file (KiCad or Altium).
    • Search our online database to see if the part exists.
    • Create the component if it does not exist. (Using JITX component development, even the parts and their pins have intelligent data to inform your design and schematic to correctness.)
  5. Connectivity + Passive Components
    • Note your nets,
    • Wiring - Connect your component pins and nets together
  6. Perform PCB layout creation
    • Modify and update the PCB graphically and programmatically (make quick work of tedious tasks that normally take forever using traditional methods, like routing DDR)
  7. Perofrm robust design checks
    • write custom electrical checks for your components and design
    • run them to verify the validity of your design from JITX's deep understanding of your circuit and component behavior - not just general electrical checks in a typical ECAD flow.
  8. Perform final touch-ups in other ECAD tools
    • Export your PCB design to another software
    • do final touch-ups after doing the bulk of the work quickly in JITX (you can export to Altium or KiCad)
  9. Manufacture the PCB
    • Generate manufacturing files (Gerber, ODB++, IPC-2581, etc.)
    • Order the Board from your favorite manufactuer

That is the general flow, but when it comes to JITX, steps 3 through 7 are defined using code and certain tasks are automated. This code-based automation and optimization leads to more robust checks that don't rely on human review, reducing the likeihood of human error in a design.

The following section of this guide will be your soft introduction to the JITX workflow to design PCBs, so that you become even more familiar with the new environment. Future tutorials will focus on more advanced tasks.

It is highly recommended that you complete the previous design first and do not skip ahead, because we build on the knowledge from previous exercises. So if you skip ahead you will have to backtrack to these steps anyway.

Okay with that out the way, let's start the EE process for PCB design using JITX!

4. Design #2 - PCB Design Process using JITX

As mentioned in section 3, we will use JITX follow the 9-phase process that one typically follows to design PCBs from scratch.

Phase 1: Define Requirements

This is just like any hardware design flow. We work with new design requirements, like power consumption, voltage output, current consumption and so on. To keep things simple, we want the following:

  • a voltage regulator that generates an output voltage of 3.3 V at ±15%
  • a voltage divider on the output pin that can sink a maximum current of 1.6 A.

More precisely, we want a design like the LM317A power regulator shown below. alt_text

Phase 2: System Level Design (Block Diagram)

The first step to any hardware/PCB design is to draw a system block diagram. The benefit of doing this is to ensure we include all 'functions' within the product so that our reaquirements are met.

The electronics or electrical design engineer would fill in those details eventually.

For example, the voltage divider and its optimal resistors would be calculated manually or using some tools outside the schematic capture environment.

What is a 'Module' in JITX?

Still on the functions aspect, those can be drawn as block diagrams and can then be considered 'modules' that can be used specific to this design, or that can be reused in other designs.

Understanding Modules Better

Therefore, a 'module' in JITX refers to a functional block that consists of components that are connected to each other. You can have, say, the power regulator, some resistors and capacitors all in a single power module (or function block), because they connect together to perform a certain circuit design. The benefit of this approach is to have a library of these best known circuits for various applications, so engineers don't have to redesign them every time they want, say, a power regulator circuit for 3.3V output.

Design reuse is not a new concept, as other ECAD tools also have ways to reuse circuit designs. However, JITX's library of adaptable circuit modules really takes reuse to the next level, because our circuits are universal and adapt to the design at the time of use.

That means you are no longer locked into reusing circuits for a single ECAD tool, but can use the same circuit in many.

That also means, that with our circuit generators, you do far fewer design calculations to get, say, the right set of resistors for a simple voltage divider. What's even better is that the larger our circuit library becomes, the more engineering hours we will save engineers worldwide.

In fact, this is one of the our missions - to make life easier for hardware designers everywhere. We also have a community dedicated to this dream for all EEs and PCB designers. If you would like to support the mission and create Circuit Generators and modules that anyone can use, ask to join our community and we will show you how to get started.

On that note, let's start adding some modules to our design.

Phase 3: Creating a Design/JITX Project

Exercise 5 - Adding A Module

First we want to add a module to the design. Which is executed by the code:

pcb-module lm317a-regulator (output-voltage:Toleranced) :
  pin vin
  pin vout
  pin gnd
  pin adj

And generates the overall design, but without the ports/pins ‘vin’, ‘vout’, ‘gnd’ or ‘adj’ being visible, as seen below.

alt_text

Exercise 5 - Done

Exercise 5 Points Acquired = 2 points

You just added your first module!

Exercise 5 - Skill Acquired

Now that you know how to create modules, you will make additional modules (which would contain circuits) as you add components and flesh out the rest of each module in this design.

Phase 4: Components

Now we are in the Components design phase, where we start adding parts to our module(s).

Let’s say your engineering manager wants to add a power regulator, capacitors and a couple resistors to the board based on the LM317A, like the one below.

alt_text

Typically this requires hand calculations for say, the voltage divider circuit, parametric searches online for the perfect component that meets our requirements and is at a reasonable price.

That process can take a solid one to two hours. That would involve making an Excel spreadsheet comparing all the different viable options, not to mention compliance to safety or perofrmance standards.

It is all too common for engineers to have to work with multiple environments, tools, websites and various files just to bring their design data together all at once.

Add in looking through each datasheet for the components being analyzed, this expedition could easily become an afternoon's worth of work.

Fortunately with JITX, you will not have to do as much heavy lifting, because JITX and the code environment will pull the proper component(s) for your application based on intelligent design requirements. This adaptability saves you the hassle of doing all that parametric analysis manually.

To understand this concept, let us do an exercise.

Exercise 6: Instantiating Smart Parts from JITX Component Database (OCDB)

Instantiating a Part

The second step is to instantiate a part (the LM317A) from our existing database and put it into the module we created earlier for the LM317 circuit. So to get this device:

alt_text

We use the code below: alt_text

Here’s the code snippet for you to copy:

  inst lm317a : ocdb/components/unisonic/LM317A/component
  net (vin  lm317a.input)
  net (vout lm317a.output)

TIP: Be sure to indent this code at the same level as the pin statements above it. These components, pins and nets are all supposed to be within the pcb-module function.

The LM317A gets instantiated. Next we need to wire this component back to the main design ports.

End of Exercise 6

Exercise Points Acquired = 3 points

Skills Acquired

In this exxericse you learned how to:

  • Add a component to your design and
  • Connect the pins of the component to other nodes

Exercise 7 - Adding Components. Capacitors

To add capacitors to your regulator or any device, we just need two lines of code. Then JITX will choose our capacitors for us based on the values given to it and with awareness of the LM317A recommendations as well.

Here’s the code to copy if you want to try it:

  cap-strap(lm317a.input, gnd, 0.1e-6)
  cap-strap(lm317a.output, gnd, 1.0e-6)

Be sure to indent these lines of code so they are one level more indented than the pcb-module command (or on the same level as the net commands just before this section). As a guide of the complete module code, you can use this below:

pcb-module lm317a-regulator (output-voltage:Toleranced) :
  pin vin
  pin vout
  pin gnd
  pin adj

  inst lm317a : ocdb/components/unisonic/LM317A/component
  net (vin  lm317a.input)
  net (vout lm317a.output)

  cap-strap(lm317a.input, gnd, 0.1e-6)
  cap-strap(lm317a.output, gnd, 1.0e-6)

JITX is awesome because you don't have to do so much parametric searching for components, especially for things like passive devices (resistors, capacitors, etc.). The library does that for you. Just define the parameters and it will find what you need!

End of Exercise 7

Exercise 7 Points Acquired = 2

Even if component selection is taken care of by JITX, multi-component circuits that make a certain topology requires a special kind of code.

Next we will select a voltage divider and have JITX calculate our resistor values for us (based on components available in the Open Components Database (OCDB). We also discuss the typical approach to hardware design and why the new approach saves a lot of time.

Typical Approach to Circuit Design...

Normally, you would have your requirements defined, for your voltage divider, for example. To do this you would:

  • have to do component research,
  • pull up a spreadsheet,
  • do some analysis on the proper resistor value selection based on hand calculations for the ideal feedback voltage,
  • then select parts based on what’s available in component databases.
  • then back-calculate new values based on what resistors you could find on the market

All of this work is to find a few capacitors.

Luckily JITX has a solution for this, which we call Circuit Generators.

Modern Approach - Lessen Your Design Work by Using JITX Circuit Generators

You have encountered the next cool thing about JITX for automation in hardware design - Circuit Generators. Occasionally, we might refer to these generators as solvers for short.

Circuit generators are snippets of code that automatically select comopnents to meet your design requirements (e.g. a voltage divider) in terms of voltage, current and power consumption.

Circuit Generators are part of a special library of code (shown in next example). They reduce tedious tasks mentioned in the previous sedction and only require a couple lines of code. Circuit generators can turn what would take a couple hours of manual work into seconds.

To see this in action, let us select a generator and run it.

Exercise 8 - Use a Circuit Generator

First we want to implement the the kind of circuit seen below.

alt_text

To do this, copy and paste the following code into the design.

Voltage divider Circuit

  inst output-voltage-divider : voltage-divider(source-voltage   = output-voltage, 
                                                divider-output   = 1.25 +/- (15 %) 
                                                current          = 5.0e-3 )

Quick explainer of the code:

  • voltage-divider(source-voltage = output-voltage - this means we want the source of the voltage divider (going into the top resistor pin) is connected to the output-voltage coming from the LM317A device we instantiated earlier.
    • for more information on how this works, consult this guide
  • divider-output = 1.25 +/- (15 %) - this means we want the node connecting the two resistors to each other to have 1.25 ± 15% V (minimum of 1.0625 V, maximum of 1.4375 V) coming out of it.
  • current = 5.0e-3 ) - this is the maximum current (5 mA) we allow through the two resistors.

Eventually when we generate Ctrl+Enter the new design, the solver will do its thing and pick the resistor network (best resistors for the job within a certain tolerance of the desired output voltage) for us. It can do this, because it has enough information, like the output voltage coming from the LM317A's output pin, and our desired output from the divider.

We have our components, so now let us connect them.

Exercise 8 - Done

Exercise 8 Points Acquired = 2

Exercise 8 Skills Acquired

You learned how to instantiate (use) a circuit generator in a design. There are multiple kinds of circuit generators (or 'solvers') that help automate your design flow and will only grow as time progresses and engineers add more to our libraries.

The next step is to connect our circuits.

Phase 5: Connectivity

Remember that code at the top of the project that made a PCB module with the pins ‘vin’, ‘vout’, ‘gnd’ and ‘adj’ that we couldn’t see?

In this step, we’re using the net command to connect those unseen pins/ports to the input and output pins of the LM317A. The end result will have no visual change to the design.

In the next exercise, we will connect the voltage divider to the pins of the LM317 regulator.

Exercise 9 - Connecting nets

To connect component pins or nets, follow along by copying the code below:

  net (output-voltage-divider.in lm317a.output)
  net (output-voltage-divider.out lm317a.adj adj)
  net (output-voltage-divider.lo gnd)

and pasting it into the design window in VS Code underneath this code:

  inst output-voltage-divider : voltage-divider(source-voltage   = output-voltage, 
                                                divider-output   = 1.25 +/- (15 %) 
                                                current          = 5.0e-3 )

Making sure that the net commands are in line with the inst command. That means your code so far for the entire design from the top would look like this:

#use-added-syntax(jitx)
defpackage main :
  import jitx
  import core
  import jitx/commands
  import ocdb/utils/generic-components
  import helpers
  import ocdb/modules/passive-circuits

; Define the shape/size of the board
val board-shape = RoundedRectangle(30.0, 18.5, 0.25)

pcb-module lm317a-regulator (output-voltage:Toleranced) :
  pin vin
  pin vout
  pin gnd
  pin adj

  inst lm317a : ocdb/components/unisonic/LM317A/component
  net (vin  lm317a.input)
  net (vout lm317a.output)

  cap-strap(lm317a.input, gnd, 0.1e-6)
  cap-strap(lm317a.output, gnd, 1.0e-6)

  inst output-voltage-divider : voltage-divider(source-voltage   = output-voltage, 
                                                divider-output   = 1.25 +/- (15 %) 
                                                current          = 5.0e-3 )

  net (output-voltage-divider.in lm317a.output)
  net (output-voltage-divider.out lm317a.adj adj)
  net (output-voltage-divider.lo gnd)

Now let's explain what we just added:

Explanation of Net Command

The first net command says to connect some nets (or pins of components) together. The nets/pins in this case are:

  • the source/input of the voltage divider to the output pin of the LM317A
  • the output of the voltage divider to the adjustment feedback pin of the LM317A
  • the bottom pin of the voltage divider to the ground net

So instead of drawing wires like in a regular ECAD tool, we can explicitly state which nets, pins and nodes we want connected to each other, without room for graphical error.

Now that the voltage divider has been connected to the LM317 regulator, we have come to learn from the datasheet that this LM317A device needs capacitors on the input and output pins.

Alright, the voltage divider circuit is connected. Next step is setting our main design output voltage.

Exercise 9 - Done

Exercise 9 Points Acquired = 4 points

You now know how to connect nets and pins of circuit elements to each other.

(Optional) Updating the Board Version

To update your board version, give it any number you want. Considering ours was a demo, we will just keep it at 0.0 for now.

alt_text

Here is the code to make a label that has the version you want on it, and (just to be safe) a definition of our board design:

; Module to run as a design
public pcb-module my-design :
  val target-voltage = 3.30 +/- (10 %) 
  inst reg : lm317a-regulator(target-voltage)

  ; Write the board version on silkscreen
  inst version-label  : ocdb/artwork/board-text/version-silkscreen("Version 0.0")
  place(version-label) at loc(0.0, height(board-shape) / 2.0 - 1.0) on Bottom

Make sure that if you copy and paste this code, that the ; Module to run part is aligned with the pcb-module lm317a-regulator (output-voltage:Toleranced) :

code snippet this time. The reason being that our label, and other code being pasted is not part of the voltage regulator circuit module we made. The label and whatnot are part of the larger design that encloses everything.

To make sure we're on the same page, here is the code you should have so far:

#use-added-syntax(jitx)
defpackage main :
  import jitx
  import core
  import jitx/commands
  import ocdb/utils/generic-components
  import helpers
  import ocdb/modules/passive-circuits

; Define the shape/size of the board
val board-shape = RoundedRectangle(30.0, 18.5, 0.25)

pcb-module lm317a-regulator (output-voltage:Toleranced) :
  pin vin
  pin vout
  pin gnd
  pin adj

  inst lm317a : ocdb/components/unisonic/LM317A/component
  net (vin  lm317a.input)
  net (vout lm317a.output)

  cap-strap(lm317a.input, gnd, 0.1e-6)
  cap-strap(lm317a.output, gnd, 1.0e-6)

  inst output-voltage-divider : voltage-divider(source-voltage   = output-voltage, 
                                                divider-output   = 1.25 +/- (15 %) 
                                                current          = 5.0e-3 )

  net (output-voltage-divider.in lm317a.output)
  net (output-voltage-divider.out lm317a.adj adj)
  net (output-voltage-divider.lo gnd)

; Module to run as a design
public pcb-module my-design :
  val target-voltage = 3.30 +/- (10 %) 
  inst reg : lm317a-regulator(target-voltage)

  ; Write the board version on silkscreen
  inst version-label  : ocdb/artwork/board-text/version-silkscreen("Version 0.0")
  place(version-label) at loc(0.0, height(board-shape) / 2.0 - 1.0) on Bottom

Okay, and when that's up to date, you should be clear to continue to the PCB layout phase.

Phase 6: PCB Layout

PCB Generation

The final step in the creation phase is to generate the design.

Exercise 10 - Generating an Intelligent PCB Design

To do that, make sure you have the final correct code (copy and paste the code below just to make sure).

Final Power Regulator code:

; Generated by JITX 2.25.0
#use-added-syntax(jitx)
defpackage main :
  import jitx
  import core
  import jitx/commands
  import ocdb/utils/generic-components
  import helpers
  import ocdb/modules/passive-circuits

; Define the shape/size of the board
val board-shape = RoundedRectangle(30.0, 18.5, 0.25)

pcb-module lm317a-regulator (output-voltage:Toleranced) :
  pin vin
  pin vout
  pin gnd
  pin adj

  inst lm317a : ocdb/components/unisonic/LM317A/component
  net (vin  lm317a.input)
  net (vout lm317a.output)

  cap-strap(lm317a.input, gnd, 0.1e-6)
  cap-strap(lm317a.output, gnd, 1.0e-6)

  inst output-voltage-divider : voltage-divider(source-voltage   = output-voltage, 
                                                divider-output   = 1.25 +/- (15 %) 
                                                current          = 5.0e-3 )

  net (output-voltage-divider.in lm317a.output)
  net (output-voltage-divider.out lm317a.adj adj)
  net (output-voltage-divider.lo gnd)

; Module to run as a design
public pcb-module my-design :
  val target-voltage = 3.30 +/- (10 %) 
  inst reg : lm317a-regulator(target-voltage)

  ; Write the board version on silkscreen
  inst version-label  : ocdb/artwork/board-text/version-silkscreen("Version 0.0")
  place(version-label) at loc(0.0, height(board-shape) / 2.0 - 1.0) on Bottom

; Set the design name     - a directory with this name will be generated under the "designs" directory
;     the board           - a Board object
;     [optional] rules    - the PCB design rules (if not givn default rules will be used)
;     [optional] vendors  - Strings or AuthorizedVendors (if not give default vendors will be used)
;     [optional] quantity - Minimum stock quantity the vendor should carry (if not give default quantity will be used)
setup-design(
  "jitx-design",
  ocdb/utils/defaults/default-board(ocdb/manufacturers/stackups/jlcpcb-jlc2313, board-shape)
)

; Set the schematic sheet size
set-paper(ANSI-A)

; Set the top level module (the module to be compile into a schematic and PCB)
set-main-module(my-design)

; Use any helper function from helpers.stanza here
; run-check-on-design(my-design)

; View the results
view-board()
view-schematic()
view-design-explorer()

Then click anywhere inside the code in JITX, then hit Ctrl+Enter (generate) on your keyboard. Then voila, the design will take some time to load (even up to 30 seconds depending on how difficult it is for the Circuit Generating to find a solution for the voltage division circuit).

You will know you're on the right track if your output TERMINAL panel at the bottom of VS Code (you might have to click it) looks similar to below:

Current working directory: "/Users/kirschmackey/Documents/JITX/JITXProjects/Quickstart1/QS1_PowerRegDesign"
Loading JITX Shell...
-> Tolerance 2.0%
   No solution.
-> Tolerance 1.0%
    - Querying resistors for R1=442.0Ω R2=270.0Ω
      Checking solution for existing components with: tol1=MinMaxRange(min=-0.01, max=0.01), tol2=MinMaxRange(min=-0.01, max=0.01)
      Solved: mpn1=CRCW0402442RFKED, mpn2=RMCF0402FT270R, v-out=(min=1.0625V, nom=1.25V, max=1.4375V), current=0.00462962962962963A
Saving stable design and reference designator table
REPL environment is now inside package main.

Once finished, here are what the final schematic and PCB should look like:

alt_text

Exercise 10 - Done

Exercise 10 Points Acquired = 2 points

Exercise 10 Skills Acquired and lessons learned

You have succesfully executed the creation of a design that has intelligence in it, due to the circuit generator solving and finding resistors for your design.

In the Routing and layout phase, we show another time-saving feature - autorouting!

Key Benefits in Design Phase and Modern JITX Approach:

  • JITX has solvers that automatically select components for you for multiple applications
  • What would normally take 30 minutes to complete now only takes JITX 5 seconds
  • Design integrity is maintained by using a code-driven approach
  • Design flaws are inherently reduced as circuits are based on solvable electrical calculation solutions and not based on graphics-only designs that could introduce unsolvable circuits
  • Modular approach to the code libraries in JITX bodes well for design reuse and increasingly shorter design cycles (roughly 70% less time to manufacturing)

The next step is component placement.

Component Placement

Components have been placed onto the PCB and now it is time to connect them all using our router.

However, instead of manually routing traces by hand, we’ll use the routing tools inside JITX to do the routing for us.

Here is the unrouted board we generated:

alt_text

Next I will manually rearrange the components by clicking and dragging them into new positions (hitting ‘R’ on my keyboard to rotate them while dragging them).

Tip: To properly select components on the PCB, hover your cursor over the land pattern so that a white box appears around that part. Then click (and hold if you wish) once you see the white box. That part will turn green to let you know it has been selected. If you clicked and released the mouse button, the part will still be green. To move the part, simply click hold and drag the mouse, and the part will attach to your cursor and move wherever you like. The important thing is that you do not need to click, release, then click-hold-drag. Simply click and hold (the green highlight will appear if you selected the part properly by seeing the white enclosing box on mouse hover first), then drag.

alt_text

Excerise 11 - Component Placement

Rearrange the components in a way you would like them placed, taking note of the net names and rats nest lines (or 'airwires') that guide you on which pins should connect to which nets.

Exercise 11 - Done

Exercise 11 Points Acquired = 6 points

Exercise 11 Skills Acquired

In this exercise, you practiced moving components around on the PCB, so, component placement. Placement matters, so getting it right will make all the different in routing and the rest of layout.

Now that the components are positioned the way I want them to be, I can route them.

Note: JITX can auto place components as well, depending on your design preferences and goals, but we will save that cool feature for future guides.

Routing and Automation

Routing components on a PCB can be a daunting task, but not with JITX. Learn how to use JITX's routing tools to save time and create a professionally routed board without manual intervention.

Select any two or more pads at the same time (using Shift+Click) that you want to route.

alt_text

Then click the "Autoroute" button in the upper right corner, (or press "q" on your keyboard).

alt_text

The pads will be routed immediately. Here's what it looks like if you move a few components and autoroute a few of them.

alt_text

In this case, even though our full design got routed almost instantly. An engineer who designs power PCBs might not be happy with the routing!

But we will skip routing improvements for now for the sake of the guide.

What’s also great is that you can hover over a net and it will show the net name at the bottom of the PCB layout window.

Okay that’s a quick way to get a board done. The next step is to check to see if this board passes certain rules and constraints, both in the schematic design and the PCB layout.

We call these Design Checks in JITX.

Phase 7: Design Checks

This design is relatively simple/straightforward so we will skip this step for this design and do Design Checks in more advanced training eventually.

Phase 8: Final Edits in Other ECAD Tools

Once your design is complete and has passed checks, it is time to generate manufacturing files for your PCB. JITX streamlines this process, ensuring your design is ready for production.

1. Export Design to CAD

You can export your design files to Altium and/or to KiCAD, allowing you to work more efficiently in JITX, but still collaborate with engineers who are not using JITX.

Exporting to Altium

To export your design to Altium, just have the JITX plugin installed in Altium Designer and then have an Altium project opened.

There is a helper file that pulls in functions for extra tasks that help with our board design ecosystem. By default, the file exports to Altium. But we want to export to KiCAD, so we need to change its code.

In the helpers.stanza file, find altium in the export destination section shown below:

; ====================
; Actual Export design
; ====================
public defn export-to-cad () :
  set-paper(ANSI-A4)
  set-export-backend(`altium) ; set the CAD software for export to be altium (also supported: `kicad)
  export-cad()

Exercise 12 - Exporting CAD Files

Update the export destination to kicad if KiCAD is preferred, or keep it the same if using Altium. Now save that helpers.stanza file using Ctrl/Cmd+S or File - Save.

Click anywhere in the same file and use Crtl+Enter to export to KiCAD (Altium has to be open if you try to export to Altium, else you may get an error).

After all your changes are made, return to main.stanza and press Ctrl + Enter again.

Go into the file ‘helpers.stanza’, in your project folder and scroll down to the section of code that says:

Now, in the JITX Shell (This is the VS Code Terminal window), type export-design() and hit Enter to generate CAD files and our bill of materials.

You will then get an output similar to this one below in the VS Code Terminal:

stanza> reload
-> Tolerance 2.0%
   No solution.
-> Tolerance 1.0%
    - Querying resistors for R1=442.0Ω R2=270.0Ω
      Checking solution for existing components with: tol1=MinMaxRange(min=-0.01, max=0.01), tol2=MinMaxRange(min=-0.01, max=0.01)
      Solved: mpn1=CRCW0402442RFKED, mpn2=RMCF0402FT270R, v-out=(min=1.0625V, nom=1.25V, max=1.4375V), current=0.00462962962962963A
Saving stable design and reference designator table
stanza> export-design()
Export to CAD starts ...
Saving stable design and reference designator table
Unable to realize uninitialized layer 0
Unable to realize uninitialized layer 1
Unable to realize uninitialized layer 2
Unable to realize uninitialized layer 3
Changes detected:
- 3 groups added: reg.lm317a-regulator, reg.output-voltage-divider.voltage-divider, false
Schematic group tree:
false
├─ reg
│  ├─ reg.lm317a-regulator
│  └─ reg.output-voltage-divider.voltage-divider
└─ false

JITX: Packing schematic groups into sheets.
Export to CAD is done. The output is located at: designs/jitx-design/kicad

The files were generated in the following folder inside your project folder (only if you chose the kicad option): NameYouGaveYourProject/designs/jitx-design/kicad. If you want to get there quickly, you can right click on any of the design files (e.g. main.stanza`), then choose to show in Finder (Mac OS) or Explorer (Windows OS).

Exercise 12 - Done

Exercise 12 Points Acquired = 2 points

Exercise 12 Skills Acquired

You now know how to export KiCAD (or Altium) design files so that others (or yourself) can modify and clean up existing routes, schematics, and so on in your own ECAD software.

Phase 9: Manufacturing the PCB

At this point you have generated either an Alitum or KiCad project, depending on the setting you chose in the previous section. In our case, we used KiCAD since we are on a Mac and running KiCAD.

Ordering the board (PCB, PCBA, etc.)

This is the step where you order the board from your preferred manufacturer. You would need the following:

  • Design files
  • Bill of materials (BOM)
  • PCB Fabrication files (PCB, ODB++, IPC-2581)

The design files you would have generated from the previous section, Generating CAD Files. The PCB Fabrication files would come from the other ECAD tool you exported to after engineering creates them. You can generate a bill of materials (BOM) using JITX directly.

To do that, go back to the VS Code terminal window and run export-bom().

You will get an output similar to below:

stanza> export-cad
[Fn object]
stanza> export-bom()
Writing BOM to "designs/jitx-design/bom/jitx-design.xlsx" in XLSX format...
Writing BOM to "designs/jitx-design/bom/jitx-design.tsv" in TSV format...

It generated a .xlsx Excel BOM spreasheet and a tab-separated file (TSV). Open and examine those files and you can modify them as needed.

That ends the PCB design process and the different ways JITX can be used to execute the workflow.

5. Conclusion

Congratulations! You have successfully designed your first hardware project using JITX.

You now know how to:

  • create new projects
  • establish circuits as modules for modular design
  • add components from our open components database
  • use circuit generators to make adaptable designs (so you don't have to do so many calculations)
  • wire components in a schematic
  • generate PCBs using code and JITX
  • place components in the JITX PCB environment
  • route components using the autoroute feature
  • export designs in JITX to other software (Altium, KiCAD)
  • Generate a bill of materials (BOM)

Excellent work!

If you have been doing the exercises in this tutorial, you would have earned some points.

  • Exercise 1 - 2 pts
  • Exercise 2 - 4 pts
  • Exercise 3 - 18 pts
  • Exercise 4 - 3 pts
  • Exercise 5 - 2 pts
  • Exericse 6 - 3 pts
  • Exercise 7 - 2 pts
  • Exercise 8 - 2 pts
  • Exercise 9 - 4 pts
  • Exercise 10 - 2 pts
  • Exercise 11 - 6 pts
  • Exercise 12 - 2 pts
  • Total Points = 50 pts

You are well on your way becoming Activated as a JITX User.

Here is the breakdown of the levels you can attain if you do the exercises in the tutorials:

  • Learner Level (0 to 70 points)
    • Initiate (0-33 points)
    • Novice (33-50 points)
    • Apprentice (51-70 points)
    • Journeyman (71-90 points)
  • Advanced Level (91 to 150 points)
    • Expert (91-110 points)
    • Master (111-130 points)
    • Guru (131-150 points)
  • JITX Champion (151+ points)
  • JITX Jedi (200+)

In later guides, we will learn more about JITX, like how to organize our schematic, how to auto-place components based on design requirements or cost, assisted routing, signal integrity, and even pin swapping. Welcome to JITX.