Quickstart: Organize a Design
In this tutorial, we'll take the regulator design from Quickstart - Your First JITX Design and create a characterization fixture around it. We'll then add power and ground symbols and group together sections of the schematic using schematic-group
. We'll also use layout-group
so these same groupings happen in our layout.
NOTE: This Quickstart begins where the Quickstart - Your First JITX Design finishes. For your reference, the starting code for the file
main.stanza
and the finished code for this Quickstart tutorial are available.
Tutorial - Adding a Fixture and Organizing the Design
1. Building the Fixture
Let's add a pair of banana jacks to provide DC power. There is already a banana-plug-module()
defined in ocdb/utils/generic-components
(Ctrl+Click
on the name in VS Code to go to its definition). This module places a red and black banana jack at a standard connector pitch, labels each, and then provides a power
port as an electrical interface. The power
port is a JITX bundle, which contains pins gnd
and vdd
.
We'll then connect the power pins or the banana jack to the regulator circuit via the net
command, also naming the nets to be gnd
and vin
. You can only connect to ports of an instance like source
after you instantiate it with an inst
statement.
Add the following code inside the my-design
module, after the instantiation of the lm317a-regulator
(note the indentation):
inst source : banana-plug-module() ; shortcut to instantiate and place two `banana-plug`s plus the electrical support
net gnd (reg.gnd, source.power.gnd)
net vin (reg.vin, source.power.vdd)
Similarly, let's add an BNC connector to the regulator output after the code added from above.
inst measure : bnc-connector()
net vout (reg.vout, measure.sig)
net (gnd, measure.gnd)
We can then add test points to the adj
pin, and gnd
so we can inject some noise to this device and measure the change of the output. The function add-testpoint()
modifies the calling module to add a ocdb/components/keystone/500xx
component. Add the following code after the code added from above.
val test-points = add-testpoint([reg.adj, gnd])
Finally, we do some calculations to find a load resistor, and then pass the parameters to chip-resistor
to select a part from the database (add the following code after the val test-points = ...
).
val target-current = 450.0e-3
val target-load = closest-std-val(typ-value(target-voltage) / target-current, 5.0)
inst load : chip-resistor(["resistance" => target-load, "min-rated-power" => typ-value(target-voltage) * target-current * 2.0 ])
net (load.p[1], reg.vout)
net (load.p[2], gnd)
Adding all that in and running the design (with Ctrl + Enter
), we get this new schematic:
This schematic is technically correct, but not very legible. Let's add a couple lines of code to clean it up.
2. Handle Power Planes and Nets
We can add a ground plane to our design by adding this code to our main design:
; add a ground plane
geom(gnd) :
copper-pour(LayerIndex(1), isolate = 0.1, rank = 1, orphans = true) = Rectangle(width(board-shape) - 1.0, height(board-shape) - 1.0)
We can also specify trace width for various net classes. Let's do that for the power nets:
; add a net class for power nets
val power-net-class = NetClass(`Power, [`min-trace => 0.381])
property(gnd.net-class) = power-net-class
property(vout.net-class) = power-net-class
property(vin.net-class) = power-net-class
3. Net symbols
We can assign symbols to any net that we have named. Add a symbol to the ground net by adding this line of code to my-design
after the line net gnd (reg.gnd, source.power.gnd)
:
symbol(gnd) = ocdb/utils/symbols/ground-sym ; has to be placed after the definition of the net itself
We can see how this improves legibility by re-running the design:
We can assign symbols to any net in JITX. Symbols for power and ground nets go a long way towards schematic organization.
4. Schematic and Layout Grouping
The #1 ticket to schematic legibility is schematic-groups
. These are groups we apply as users to cluster symbols that should appear together in the schematic. JITX gives us a few ways to manage them automatically.
Schematic and Layout Groups - Inside Modules
One place where we can define a schematic group is inside of a module.
We want to always have the regulator grouped with its passives in the schematic. To do that, we can modify code inside the module definition of lm317a-regulator
. Let's add the following code after the last net
statement inside lm317a-regulator
:
; inside pcb-module lm317a-regulator
schematic-group(self) = lm317a
layout-group(self) = lm317a
Now, all the parts in the lm317a-regulator
module will be grouped together in any design we include it in. Once we add one group and recompile, every symbol belonging to an ungrouped component is automatically put into another group.
Schematic and Layout Groups - At the Top Level
Another place where we can define a schematic group is at the top level of the design.
In the top level of our design let's put our test points and the SMA connector into their own group. In the main module, put those components together in a group called test
by adding this line of code at the end of my-design
:
; inside pcb-module my-module
schematic-group([test-points, measure]) = test
layout-group([test-points, measure]) = test
Schematic and Layout Groups - With Other Groups
Another way to control schematic groups is by adding a component or module to an existing schematic-group.
For example, the load resistor is still grouping with the banana plug symbols. For this design, let's group it with the regulator group by adding this line of code at the end of my-design
:
;inside pcb-module my-module
schematic-group(load) = schematic-group(reg)
layout-group(load) = layout-group(reg)
Our schematic is looking more organized and production-ready - much better!
Whenever our schematic starts getting hard to read or slow to route, it's important to apply groups to keep things organized.
Using Layout Groups in Placement
As we can see above, the schematic-groups
are now part of our schematic. However, the layout-groups
did not apply. By default, JITX does not use layout groups, as it can slow down placement. Since we want our layout groups to be applied during placement, we should add the following command near the bottom of main.stanza
just before set-main-module
:
set-use-layout-groups()
Now, JITX uses our specified layout groups when doing automatic placement:
5. Using the Interactive Schematic to Organize our Design
JITX has an interactive schematic view which allows us to interact with our schematic similiarly to how you would in Altium or KiCad, but it can be done directly in VSCode. You can move components, create new sheets, and organize your design as you see fit. One major difference between JITX Schematics and classical CAD schematics is that you can't delete connections in JITX. If you want to change connectivity in a JITX design, you should do that in code. In the schematic, the focus is on legibility and organization.
Hierarchical View
If your schematic has schematic groups, then JITX automatically gives you a hierarchical view of your design. This is always on sheet 0 (the leftmost sheet in the sheet view. Here's the hierarchical group diagram for the LM317A design in this tutorial:
One can click on any group within this design to jump to that group. Let's click the reg.lm317a
to view that submodule (which will bring us to another sheet).
Now we've jumped to that submodule directly!
Moving and Rotating Components
I might want to tighten up the schematic look a bit better. To move components, I just hover my mouse over the component, click, hold, and drag, and then release the mouse button when I want to place the component. I can also press "r" at any time to rotate the component. Here, I moved a few components and rotated 1 resistor:
Joining Nets
Notice how, above the resistor has an adj
label where it could be directly joined to the wire to its left to form a node. Let's select that adj
label and press "q" to join our nets.
A bit more moving and rotating makes out submodule much cleaner and easier to parse:
Selecting Nets
If you want to select an entire net, select any trace of that net, then press "a":
Component Info Card
If you want more information about any specific component, hover your mouse over it and press "e":
Undo/Redo
If you performed an action that you didn't want to retain, you can undo with Ctrl+z
, and you can redo with Ctrl+Shift+z
.
Move a Schematic Group
Schematics groups can be moved as a unit. Just place your cursor on the bounding box outline of the schematic group, click, drag and release to move it. If you want to move the schematic group to a new sheet, then press the sheet number on your keyboard while hold the schematic group, and you will jump to that sheet while still holding the schematic group.
6. Using the Physical Design to Layout our Board
First off, looking at the layout from above, it looks like our board isn't big enough. Let's go into the code and make the board-shape
a bit bigger. Let's change it to:
; Define the shape/size of the board
val board-shape = RoundedRectangle(35.0, 25.0, 0.25)
Now let's recompile, and the shape of the board will change.
Placing Landpatterns
Let's place a landpattern. We can start with the banana plugs. First, hover your mouse over the banana plug and click to select it. Then click and drag your mouse to move it.
Creating Routes
Select any two or more pads at the same time (using Shift+Click
) that you want to route and click the "Autoroute" button in the right corner, or press "q", and you routes will appear. Here's what it looks like if you move a few components and use "q" to autoroute a few of them.
Creating Vias
If we want to create a via, we need to enter via mode by clicking the "Via" button in the top right, or by pressing "v". Then we need to click a pad, and drag out from that pad to place a via that is routed to that pad. Here's a via connected to a pad that we dragged out from:
Controlling Layers
So far, all of our routes have been on the top layer. To route on the bottom layer, we click the layers panel in the top left corner of the board view, and select the bottom layer. Then we create route like described above.
Layout Complete
You've now learned how to use the JITX schematic and board views to organize, layout, and route your PCB.
Before moving on, let's clear our work so it's fresh for the next quickstarts. To do so, just delete the contents inside the designs
directory in the VSCode File Explorer.
Next step
Continue with the Quickstart: Check a Design to learn how to add checks that make sure this design will actually work when we get the hardware back.