Copper Shapes, Net Ties and Virtual Connections#

Pads, routes and pours put most of the copper on a board, but sometimes we want to draw a shape ourselves from Python: a wide strap on a power rail, or a net tie that joins two grounds at one point. JITX has two kinds of drawn copper, and what separates them is whether the copper belongs to a net. Copper does, so the router and the overlap checks treat it as part of that net. OverlappableCopper belongs to no net. The router and the overlap checks ignore it. Two pads can also be joined by something with no copper in the design, such as a wire soldered between them after fabrication. A VirtualConnection tells JITX that two pads joined this way are connected.

Copper on a net#

A Copper is a shape on one layer of the board. By itself it isn’t part of anything, so we give it two relationships. Assigning it to a field of the circuit makes it part of the design. Adding it to a Net says what it carries. A short strap on a power net might look like this:

class PowerStrap(Circuit):
    VOUT = Net(name="VOUT")

    def __init__(self):
        ...
        # A 6 mm by 1.5 mm strap on the top layer, centered at (3, 0)
        self.strap = Copper(rectangle(6.0, 1.5).at(3.0, 0.0), layer=0)
        self.VOUT += self.strap

Some things to note:

  • If we assign the copper but never add it to a net, the build stops with an error saying it “has not been attached to a net or port attachment”.

  • If we add it to a net without assigning it, as in self.VOUT += Copper(...), the design still builds. JITX warns that attaching geometry through a net without also assigning it to a circuit is deprecated.

  • A Pour is a kind of Copper, so the same two steps apply when you place pours in code.

Because the strap is on VOUT, wherever it overlaps a VOUT pad the router merges the two shapes into one and marks them connected, so it doesn’t route a trace between them.

Overlappable copper#

Copper on a net is checked like any other copper on that net. To join an analog ground to the main ground at one point, we want a single piece of copper that overlaps a pad on AGND and a pad on GND. As Copper, that shape would have to belong to one of the two nets. The overlap checks would then flag the place where it covers the other net’s pad as an error.

Drawn as OverlappableCopper instead, the same shape belongs to neither net. Once the board is fabricated it is ordinary copper, so it connects whatever copper it touches. Besides net ties, you can use it for an antenna, or for any other overlap you need on the board that the overlap checks would flag.

Overlappable copper is a member of a circuit and is drawn in that circuit’s coordinates. This means the parts whose pads it has to cover should be placed in code in the same circuit. A net tie might look like this:

class GroundTie(Circuit):
    AGND = Net(name="AGND")
    GND = Net(name="GND")

    def __init__(self):
        ...
        where = (20.0, 10.0)

        # A two-pad part, one pad per net, placed in code
        self.tie = TiePads()
        self.place(self.tie, where)
        self.AGND += self.tie.a
        self.GND += self.tie.b

        # One strip across both pads, at the same point in this circuit
        self.tie_copper = OverlappableCopper(rectangle(1.6, 0.4).at(where), layer=0)

Here TiePads stands for a small part of your own, declared as a NonPopulatedComponent, which keeps its landpattern on the board but leaves it out of the bill of materials and unsoldered. It has ports a and b on two pads that sit left and right of its origin, along x. The strip is 1.6 mm along x and 0.4 mm along y, so the pads have to be close enough together that it covers part of each.

Some things to note:

  • Copper of another net that crosses the strip, such as a trace the router runs across it, joins that net to AGND and GND on the fabricated board. Neither the router nor the overlap checks report it. If this is a concern, we can surround the gap the strip bridges between the two pads with a KeepOut that sets route=True, which disallows autorouter traces in that area. Overlappable copper isn’t affected by keep-outs.

  • A strip that doesn’t reach both pads leaves the tie open, and JITX doesn’t report that either. The two pads are on different nets, so there is no ratsnest line between them. Check the tie in the board view: the strip should cover both pads, and no other net’s copper should cross it.

  • Assigning to self.tie_copper is what puts the strip in the design. If we create the OverlappableCopper without assigning it to a field, the design still builds without the strip. JITX gives no error or warning.

  • The strip isn’t added to either net. Adding it to one, as in self.GND += self.tie_copper, stops the build with an error that includes “Incompatible ports on Net”. AGND and GND stay two nets in the design, joined only on the fabricated board. The net tie needs no virtual connection.

  • The part and the strip are both positioned with where, so changing it moves them together. A part left free to move in the board view could be dragged out from under the copper, which is why we place it in code.

  • The strip doesn’t follow the part if the part is placed on the bottom side or rotated: it stays at where on layer 0, in the circuit’s coordinates. Place the part as here, on top with no rotation, or move the strip with it. For a part on the bottom side, that means putting the strip on the bottom layer, layer=-1, as well as at the part’s position.

  • Put on a component or a landpattern, overlappable copper stops the build with an error that includes “Unhandled feature type”, so it can’t be drawn as part of a footprint.

Virtual connections#

The virtual connection API is currently experimental and may change.

Suppose two pads on SENSE sit on opposite sides of a trace with no room to route around it, so we’ll join them with a jumper wire soldered on after fabrication. With no trace between them, JITX shows a ratsnest line and an unrouted warning. A VirtualConnection between the two ends of the wire tells JITX that the wire joins them. Each end can be a single-pin port, a pad or a via. JITX then suppresses both the ratsnest line and the warning, and leaves the connection unrouted: the autorouter counts the two pads as already connected and adds no trace between them.

Like copper, a virtual connection is a member of a circuit. It isn’t exported from the top-level jitx package, so we import it from jitx.virtual:

from jitx.virtual import VirtualConnection

class SenseWire(Circuit):
    SENSE = Net(name="SENSE")

    def __init__(self):
        ...
        self.SENSE += self.end_a.p
        self.SENSE += self.end_b.p

        # A jumper wire soldered between the pads after fabrication, on the top layer
        self.sense_wire = VirtualConnection(
            self.end_a.p,
            self.end_b.p,
            source_layer=0,
            destination_layer=0,
        )

Here end_a and end_b are one-pad parts of your own, declared as NonPopulatedComponent like TiePads so they stay out of the bill of materials. Each has a port p and sits at one end of the wire.

Assigning to self.sense_wire is what puts the connection in the design. Created without being assigned, the VirtualConnection is left out, the design still builds, and the two pads keep their ratsnest line and unrouted warning. JITX also logs a warning that names the object and the line where we created it, beginning “Reference to structural object VirtualConnection at : lost during instantiation”.

We declare a virtual connection the same way for each join with no copper in the design: a connection made after fabrication, such as a wire, or another structure that is electrically real but has no shape in the design. Two pads on the same net already joined by overlappable copper need one too, since the router ignores that copper. Because JITX stops showing the ratsnest line and the unrouted warning for those pads, a virtual connection belongs only where something on the finished board really joins them.

Virtual connection limitations#

Virtual connections have these limits:

  • Virtual connections aren’t meant to bridge nets: one declared between pads on two nets doesn’t join the two nets.

  • More than one virtual connection between the same pair of endpoints isn’t supported. If they carry different pin models, which one JITX uses may be arbitrary.

  • JITX drops a virtual connection it doesn’t allow.

  • A virtual connection inside a constrained topology needs a PinModel passed as its pin_model. Without one, a length-matching, skew or insertion-loss constraint routed through it may be reported as a missing route.