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.stanzaand 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
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
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
vin. You can only connect to ports of an instance like
source after you instantiate it with an
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, reg.vout) net (load.p, 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
; 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
; 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
;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
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.
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:
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:
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":
If you performed an action that you didn't want to retain, you can undo with
Ctrl+z, and you can redo with
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.
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.
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.
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:
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.
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.
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.