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 symbols to the ground net and vout 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
  symbol(vout) = ocdb/utils/symbols/supply-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 BNC 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 and rotated a few components:

Joining Nets

We can join nets together by selecting their labels and pressing "q". Here, I joined vout and gnd from both circuits and moved components to make our 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 few vias made:

Note that you don't need to make vias for J2 and J5 as they are through-hole components. If you try to make a via on them, they don't connect.

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. We can also go through layers by pressing "s" or "w". In this case, we don't need to route on any other layer as our vias are connected to the ground plane in the inner layers.

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.