To use these functions, import the package jitx/commands and the package jitx where the enums are defined.
import jitx
import jitx/commmands
defn ref (a:JITXObject) -> Ref
Get the associated Ref of an object instance.
Syntax
pcb-module my-module :
inst U1 : my-component
; Print out the Refs of the pins of a component
for p in pins(U1) do :
println(ref(p))
Description
Instances, ports, pins, and pads in the design hierarchy have
an associated "reference" name, for example, my-module.U1.p[3].
The ref(...) introspection will look up the associated Ref value
with any object, if it is assigned.
defn name (def:JITXDef) -> String
Get the name of an object
Syntax
pcb-component my-component :
name = "My Awesome Component"
println(name(my-component))
; prints, "My Awesome Component"
Description
Every definition in JITX has an associated name. It may
be overridden explicitly using the name = ... syntax,
else it is inferred from the identifier given in the definition.
The name (...) introspection function will lookup the associatd
name from a given definition
defn evaluate (def:JITXDef) -> Null
Evaluates a definiton, expanding its statements.
Syntax
pcb-pad simple-pad :
shape = Circle(1.0)
apply-soldermask()
evaluate(simple-pad)
Description
The evaluate (...) introspection forces the expansion
of a pcb-*** definition, including all of its generators. This
is useful when writing unit test, or working on generators outside
of an existing design.
defn port-type (obj:JITXObject) -> PortType
Get the type of a port from a component or module definition/instance
Syntax
pcb-module my-module :
port p : i2c
println(port-type(p))
Description
Ports of components or modules may be one of a given [PortType], valid port types are SinglePin, Bundle, PortArray
defn instantiable-type (obj:JITXObject) -> InstantiableType
Return the type of instantiable an object is.
Syntax
pcb-module my-module :
...
; prints `Instantiable`.
println(instantiable-type(obj))
Description
The instantiable-type is either a single instantiable (Instantiable) or
an array of instantiables (InstantiableArray).
defn indices (obj:JITXObject) -> Seqable<Int>
Get the indices of an array of JITX objects.
Syntax
inside pcb-module :
port p: pin[[1 2 3 5 7]]
val indices = indices(p)
for idx in indices do :
val p* = p[idx]
println(port-type(p*))
Description
Arrays of JITX objects can have custom indices. The indices (...) introspection
is useful for extracting port/pin or instances indices for generators that may
need to reference them.
defn instances (obj:JITXObject)
defn instances (def:Instantiable)
Get the instances of a module.
Syntax
inside pcb-module :
for r in [1.0e3, 2.0e3, 3.0e3] do :
inst R : gen-res-cmp(r)
for i in instances(self) do :
if has-property?(i.resistance) :
println("There is a resistor: %_ ohms." % [property(i.resistance)])
Description
The instances introspection returns a sequence of all the instances within
a module. This is useful for checks and generators that need to loop over
the instances of a module to find their properties, generate additional
instances, and so on.
defn public-instances (obj:JITXObject)
defn public-instances (def:Instantiable)
Get the public instances of a module.
Syntax
pcb-module my-module :
inst R1 : gen-res-cmp(1.0e3)
public inst R2 : gen-res-cmp(2.0e3)
; This loop will only print "2000.0", since
; R1 is a private instance.
for cmp in public-instances(my-module) do :
println(property(cmp.resistance))
Description
By default, all instances in a module are considered to have "private" visibility, which disables instantiators from referencing the instances' refs, ports, and properties.
The public-instances introspection returns a sequence of instances of a module that
are explicitly marked public.
defn single-instances (obj:JITXObject)
defn single-instances (def:Instantiable)
Get the single (non array) instances of a module.
Syntax
pcb-module my-module :
inst R : gen-res-cmp(1.0e3)[10]
inst R11 : gen-res-cmp(2.0e3)
; This loop will only print "2000.0", as there
; is only one "single' instance in `my-module`.
for cmp in single-instances(my-module) do :
println(property(cmp.resistance))
Description
The single-instances introspection returns a sequence of instances
of a module that are not defined within instance arrays.
defn public-single-instances (obj:JITXObject)
defn public-single-instances (def:Instantiable)
Get the public single (non array) instances of a module.
Syntax
pcb-module my-module :
inst R : gen-res-cmp(1.0e3)[10]
inst R11 : gen-res-cmp(2.0e3)
public inst R12 : gen-res-cmp(3.0e3)
; This loop will only print "3000.0", as there
; is only one "single' instance in `my-module`.
; that is explicitly marked `public`
for cmp in single-instances(my-module) do :
println(property(cmp.resistance))
Description
The public-single-instances introspection returns a sequence
of explicitly public instances that are not defined within instance
arrays.
defn component-instances (obj:JITXObject)
defn component-instances (def:Instantiable)
Get the instances of a module that are components (not modules).
Syntax
pcb-module sub-module :
..
pcb-module my-module :
inst sub : sub-module
inst cmp : gen-res-cmp(1.0e3)
; This will only print "my-module.cmp" as it is the only
; instance of the module that is **not** another module.
for cmp in component-instances(my-module) do :
println(ref(cmp))
Description
The component-instances introspection returns a sequence of
instances of a module that are components, that is to say that
they are instances at the bottom of the design hierarchy (not
contained within submodules of the module).
defn ports (obj:JITXObject)
defn ports (def:Instantiable|Bundle)
Get the ports of a component, bundle, or module
Syntax
val ports = ports(my-component)
for p in ports do :
println(ref(port))
Description
ports are defined using the port statement. The ports introspection
retrieves all port statements associated with the bundle, component, or module.
defn pins (obj:JITXObject)
defn pins (def:Instantiable|Bundle|SchematicSymbol)
Get the pins associated with an object.
Syntax
val cmp = gen-res-cmp(1.0e3)
for p in pins(cmp) do :
println(ref(p))
Description
The pins introspection is useful for extracting the pins of a component,
bundle, or schematic symbol.
defn nets (obj:JITXObject)
defn nets (def:Instantiable)
Get the nets of a module.
Syntax
pcb-module my-module :
inst R1 : gen-res-cmp(1.0e3)
inst R2 : gen-res-cmp(1.0e3)
net my-net (R1.p[1], R2.p[1])
for n in nets(self) do :
println(name(n))
Description
The nets introspection is useful for extracting all the net statements of
a module. It's important to note that this corresponds to the individual net
statements, and not the electrical concept of a "net." For example, if there are
two nets in a module that are electrically identical, calling nets(self) will
return both of them.
defn public-nets (obj:JITXObject)
defn public-nets (def:Instantiable)
Get the nets of a module.
Syntax
pcb-module my-module :
inst R1 : gen-res-cmp(1.0e3)
inst R2 : gen-res-cmp(1.0e3)
net my-net (R1.p[1], R2.p[1])
public net my-public-net (R1.p[2], R2.p[2])
for n in public-nets(self) do :
println(name(n))
Description
The public-nets introspection is useful for extracting all the net statements of
a module that are explicitly marked public. It's important to note that this corresponds
to the individual net statements, and not the electrical concept of a "net." For example,
if there are two public nets in a module that are electrically identical, calling nets(self)
will return both of them.
defn single-pin-nets (obj:JITXObject)
defn single-pin-nets (def:Instantiable)
Get the nets of a module.
Syntax
pcb-module my-module :
inst R1 : gen-res-cmp(1.0e3)
inst R2 : gen-res-cmp(1.0e3)
net my-net (R1.p[1], R2.p[1])
net my-single-net (R1.p[2])
for n in public-nets(self) do :
println(name(n))
Description
The single-pin-nets introspection is useful for extracting all the net statements of
a module that contain only a single pin.
defn public-single-pin-nets (obj:JITXObject)
defn public-single-pin-nets (def:Instantiable)
Get the nets of a module.
Syntax
pcb-module my-module :
inst R1 : gen-res-cmp(1.0e3)
inst R2 : gen-res-cmp(1.0e3)
net my-net (R1.p[1], R2.p[1])
public net my-public-net (R1.p[2], R2.p[2])
for n in public-nets(self) do :
println(name(n))
Description
The public-single-pin-nets introspection is useful for extracting all the net statements of
a module with a single pin that are explicitly marked public.
defn topology-ends (obj:JITXObject) -> KeyValue<JITXObject, JITXObject>
Get the ends of a named topology.
Syntax
pcb-module my-module :
inst R1 : gen-res-cmp(1.0e3)
inst R2 : gen-res-cmp(1.0e3)
topology my-topo (R1.p[1] => R2.p[1])
val ends:KeyValue<JITXObject,JITXObject> = topology-ends(my-topo)
println("Topology goes from %_ to %_" % [key(ends) value(ends)])
Description
The topology-ends introspection is useful for extracting the start and end
of a named topology object.
defn refs (obj:JITXObject)
Return all the refs inside of an object
Syntax
pcb-module main-module :
for r in refs(self) do :
println(r)
defn get-net (name:String) -> JITXObject
Find a net with a given name in a module.
Syntax
pcb-module my-module :
inst R1 : gen-res-cmp(1.0e3)
inst R2 : gen-res-cmp(1.0e3)
net my-net (R1.p[1], R2.p[1])
; ...
val my-net = get-net(my-module, "my-net")
Description
Sometimes nets are generated programatically and it may not be possible
to use the local identifier to lookup a net. For this purpose, the
get-net introspection will search the net statements of the current
module.
This function must be called inside pcb-module.
defn length (obj:JITXObject) -> Int
Get the length of an instance or bundle array.
Syntax
inst R : gen-res-cmp(1.0e3)[5]
println(length(R))
Description
Bundles and instances may be created in arrays, the length introspection
will return the length of those arrays.
defn originating-instantiable (obj:JITXObject) -> Instantiable
Get the inst definition that created an instance.
Syntax
inst i: gen-res-cmp(3.0)
print-def(originating-instantiable(i))
Description
The originating-instantiable retrieves the Instantiable that was used to create
an instance in a module.
defn containing-instance (obj:JITXObject) -> Instance|False
Get the instance that an object is contained within, if it exists.
Syntax
pcb-module sub-module :
public inst R : gen-res-cmp(1.0e3)
pcb-module parent-module :
inst i: sub-module
println(ref(containing-instance(i.R)))
Description
The containing-instance introspection retreives the instance that
owns another instance. This is useful for generators and checks that
might not have access to the original identifier of a given instance.
defn instance-definition (obj:JITXObject) -> Instantiable
Get the pcb-* definition of an instance.
Syntax
pcb-module my-module :
inst X : my-component
print-def(instance-definition(X))
Description
The instance-definition introspection retrieves the pcb-* definition
that corresponds to a given component or module.
defn instance-type (obj:JITXObject) -> InstanceType
Determine if an instance is a component, module, or array.
Syntax
pcb-module my-module :
inst X : my-component[10]
print-def(instance-type(X))
Description
The instance-type introspection retrieves the type of an instance, represented
as the enum InstanceType:
public defenum InstanceType :
SingleComponent
SingleModule
InstanceArray
defn mpn? (c:Instantiable) -> String|False
defn mpn? (obj:JITXObject) -> String|False
Get the MPN of a component, if it exists.
Syntax
pcb-module my-module :
inst U : ocdb/components/abracon/AMB7/component(10.0e6)
println(mpn?(U))
Description
Looks up the value associated with an mpn = ... statement in a
pcb-component.
defn manufacturer? (c:Instantiable) -> String|False
defn manufacturer? (obj:JITXObject) -> String|False
Get the manufacturer name of a component, if it exists.
Syntax
pcb-module my-module :
inst U : ocdb/components/abracon/AMB7/component(10.0e6)
println(manufacturer?(U))
Description
Looks up the value associated with an manufacturer = ... statement in a
pcb-component.
defn datasheet? (c:Instantiable) -> String|False
defn datasheet? (obj:JITXObject) -> String|False
Get the datasheet name of a component, if it exists.
Syntax
pcb-module my-module :
inst U : ocdb/components/abracon/AMB7/component(10.0e6)
println(datasheet?(U))
Description
Looks up the value associated with an datasheet = ... statement in a
pcb-component.
defn reference-prefix? (c:Instantiable) -> String|False
defn reference-prefix? (obj:JITXObject) -> String|False
Get the reference prefix of a component, if it exists.
Syntax
pcb-module my-module :
inst U : ocdb/components/abracon/AMB7/component(10.0e6)
println(reference-prefix?(U))
Description
Looks up the value associated with an reference-prefix = ... statement in a
pcb-component.
defn emodel? (c:Instantiable) -> EModel|False
defn emodel? (obj:JITXObject) -> EModel|False
Get the emodel of a component or the component of an inst, if it exists.
Syntax
pcb-module my-module :
inst U : chip-resistor(1000.0)
println(emodel?(U))
Description
Looks up the value associated with an emodel = ... statement in a
pcb-component.
defn reference-designator (obj:JITXObject) -> String
Get the reference designator of a component.
Syntax
pcb-module my-module :
inst R : gen-res-cmp(1.0e3)
println(reference-designator(R))
Description
The reference-designator retrieves the the reference designator of
a component in the design, which is either generated automatically or
defined explicitly using the reference-designator(object) = ... syntax.
defn connected? (obj:JITXObject) -> True|False
defn connected? (objs:Seqable<JITXObject>) -> True|False
Check if a pin or a net is connected
Syntax
pcb-module my-module :
inst R : gen-res-cmp(1.0e3)
println(connected?(R.p[1]))
Description
The connected? introspection checks if a pin or net is connected
to any other pins or nets in a design. This is useful when writing checks
for connected or unconnected components.
defn connected-pins (obj:JITXObject) -> Tuple<Pin>
Return the pins connected to an existing pin.
Syntax
pcb-module my-module :
pin gnd
public inst R: gen-res-cmp(1.0e3)[4]
for n in 0 to 4 do :
net (gnd, R[n].p[1])
val connected = connected-pins(gnd)
for p in connected do :
println(ref(p))
Description
The connected-pins introspection returns a Tuple of all the pins
connected to the argument, excluding the argument pin itself. This is
useful for writing connectivity checks.
defn all-connected-items (m:Self|Instantiable) -> Tuple<ConnectedItems>
Returns a list of all the connected items to a pin or net.
Syntax
pcb-module my-module :
val N = 100
inst R: gen-res-cmp(1.0e3)[N]
net gnd ()
for n in 0 to 100 do :
net (R.p[1], gnd)
val connected-items = all-connected-items(self)
for item in connected-items :
for n in nets(item) do :
println(ref(n))
Description
The all-connected-items introspection returns a tuple of ConnectedItems
which represent all the connected items in a module. This is primarily
used when writing checks that need to observe the full design, for example
checking if specific component pins are net'd together or pins on nets have
the appropriate properties.
The ConnectedItems structure contains the following fields :
public defstruct ConnectedItems :
nets: Tuple<Net>
module-pins: Tuple<Pin>
component-pins: Tuple<Pin>
abstract-pins: Tuple<Pin>
defn layers (obj:LandPattern|Pad|Self) -> Tuple<LayerShape>
Get the layer statements of a pcb-landpattern or pcb-pad.
Syntax
val landpattern = ocdb/components/st-microelectronics/landpatterns/TSSOP20
for layer in layers(landpattern) do :
println("There is a %_ on %_." % [shape(layer), specifier(layer)])
Description
The layers introspection finds all the geometry specified in layer statements
in landpattern or pad definitions. It is useful for writing landpattern checks.
defn layer (obj:LandPattern|Pad|Self, l:LayerSpecifier) -> Tuple<Shape>
Get all the shapes on a specific layer of a landpattern
Syntax
val landpattern = ocdb/components/st-microelectronics/landpatterns/TSSOP20
val solder-mask = layer(landpattern, SolderMask(Top))
Description
The layer introspection retrieves all the geometry on a single layer defined in a landpattern or pad.
defn model3ds (obj:LandPattern|Self) -> Tuple<Model3D>
Get the model3ds of a pcb-landpattern.
Syntax
val landpattern = ocdb/components/st-microelectronics/landpatterns/TSSOP20
for model3d in model3ds(landpattern) do :
println(model3d)
Description
The model3ds introspection returns all the Model3Ds in the landpattern.
defn pads (obj:LandPattern|Self) -> Tuple<LandPatternPad>
Get the pads of a pcb-landpattern.
Syntax
val landpattern = ocdb/components/st-microelectronics/landpatterns/TSSOP20
for pad in pads(landpattern) do :
println(pad)
Description
The pads introspection returns all the LandPatternPads that have
been created using the pad ... statement.
defn pose (l:JITXObject)
Get the pose of a pad inside a pcb-landpattern
Syntax
val landpattern = ocdb/components/st-microelectronics/landpatterns/TSSOP20
for pad in pads(landpattern) do :
println("There is a pad at: %_" % [pose(pad)])
Description
The pose introspection retrieves the Pose of a pad in a landpattern.
defn side (l:JITXObject)
Get the side of a pad in a landpattern
Syntax
val landpattern = ocdb/components/st-microelectronics/landpatterns/TSSOP20
val pads-on-top =
for pad in pads(landpattern) filter :
side(pad) is Top
Description
The side introspection is used to find which side of the board a
landpattern pad is upon.
defn pad (l:JITXObject)
Get the pcb-pad definition of a pad in a landpattern.
Syntax
val landpattern = ocdb/components/st-microelectronics/landpatterns/TSSOP20
for p in pads(landpattern) do :
val def = pad(p)
print-def(def)
Description
The pad introspection returns the pcb-pad definition of a
landpattern pad. This is useful for writing landpattern checks that
need to inspect the pad data, for example their layers.
defn pad-shape (p:Pad|Self)
Get the shape of a pcb-pad definition.
Syntax
pcb-pad my-pad :
shape = Circle(1.0)
type = SMD
println(pad-shape(my-pad))
Description
The pad-shape introspection returns the shape of a
pad that has been defined using the shape = ... statement.
defn pad-type (p:Pad|Self)
Get the type of a pcb-pad definition.
Syntax
pcb-pad my-pad :
shape = Circle(1.0)
type = SMD
println(pad-type(my-pad))
Description
The pad-type introspection returns the PadType associated with a pcb-pad definition, which
can either be TH (through hole) or SMD (surface mount)
defn landpattern (obj:Self|JITXDef) -> LandPattern
Get the landpattern associated with a pcb-component definition.
Syntax
val component = ocdb/components/abracon/AMB7/component(10.0e6)
val landpattern = landpattern(component)
print-def(landpattern)
Description
The landpattern introspection function returns the pcb-landpattern definition associated with
a pcb-component definition. This is useful for writing checks that look at the landpatterns
of components placed in the design.
defn package-poses (obj:JITXDef) -> Tuple<PackagePose>
Get the package poses associated with a pcb-component definition.
Syntax
val package-poses = package-poses(my-module)
do(println, package-poses)
print-def(inst(package-poses[0]))
Description
The package-poses introspection function returns the pose information given explicitly to instances in a pcb-module definition.
The returned object is
public defstruct PackagePose :
inst:Instance
pose:Pose|False
side:Side
anchor:Instance|False
defn do-not-populate? (obj:JITXObject) -> True|False
Check if a component instance is marked do-not-populate
defn component-status? (obj:JITXObject) -> [ComponentBOMStatus, ComponentBoardStatus]
Retrieve the component in-BOM and on-board status of a component instance (deprecated)
defn instance-status? (obj:JITXObject) -> [ComponentBOMStatus, ComponentBoardStatus]
Retrieve the component in-BOM and on-board status of a component instance (deprecated)
defn no-connect? (pin:JITXObject) -> True|False
Check if a pin is no-connect.
Syntax
pcb-component component :
pin GND
pin VDD
pin NC
no-connect(NC)
pcb-module my-module :
inst U1 : component
; prints false.
println(no-connect?(U1.GND)
; prints false.
println(no-connect?(U1.VDD)
; prints true.
println(no-connect?(U1.NC)
Description
The no-connect? introspection checks if a no-connect(...) statement has been applied
to the given pin. This is useful when writing checks.
defn get-min-width (l:LayerSpecifier|LayerIndex) -> Double
Get the minimum width rule for a given LayerSpecifier.
Syntax
val min-cu-width = get-min-width(LayerIndex(0))
Description
get-min-width is a convenience function around clearance and current-rules introspections
for quickly retrieving the DRC parameters for minimum width on a given layer. Currently, only
copper, silkscreen, and solder mask opening widths are supported.
defn get-min-space (l:LayerSpecifier|LayerIndex) -> Double
Get the minimum space rule for a given LayerSpecifier.
Syntax
val min-cu-space = get-min-space(LayerIndex(0))
Description
get-min-space is a convenience function around clearance and current-rules introsepctions
for quickly retrieving the DRC parameters for the minimum space on a given layer. Currently only
copper and solder mask bridge spacings are supported.
defn get-board () -> Board|False
Get the current pcb-board, if it exists
Syntax
val current-board? = get-board()
Description
The get-board introspection returns a board that has been set by set-board, if it exists.
defn has-board? () -> True|False
Check if the board has been set.
Syntax
println(has-board?())
set-board(ocdb/utils/defaults/default-board(4))
println(has-board?())
Description
The has-board? introspection is a convenience function to check if the board has been set by
a call to set-board.
defn current-rules () -> Rules
Get the current design rules of the project
Syntax
val rules = current-rules()
Description
The current-rules introspection returns the design rules that
have been set with set-rules, or set-default-rules if set-rules
has never been called. It fails if there are no design rules for the design.
defn current-rules? () -> Rules|False
Get the current design rules, if they exist.
Syntax
val no-rules = current-rules?()
println(no-rules) ; false
set-rules(ocdb/utils/defaults/default-rules)
val rules = current-rules?()
println(rules) ; Rules
Description
Like current-rules, current-rules? returns the design rules of the
project if they have been set, but does not crash if they are not available
and returns false otherwise.
defn clearances (r:Rules) -> Tuple<RuleClearance>
Get the clearances specified by a Rules object
Syntax
for clearance in clearances(current-rules()) :
println(clearance)
Description
The clearances introspection returns the design rules as a list
of RuleClearance objects, containing their name and value.
defn clearance (r:Rules, c:ClearanceType) -> Double
defn clearance (c:ClearanceType) -> Double
Get a specific clearance rule.
Syntax
val min-cu-width = clearance(current-rules(), MinCopperWidth)
println(min-cu-width)
; convenience variation to lookup a
; val min-cu-width = clearance(MinCopperWidth)
Description
The clearance introspection takes a Rules and ClearanceType and
lookups up the associated value with that ClearanceType. When called
without an explicit Rules argument, the current-rules() are used.
defn get-export-backend ()
Get the currently set CAD exporter backend.
Syntax
set-current-design("jitx-design")
get-export-backend()
Description
The get-export-backend command returns which CAD backend export-cad is currently set to use.
defn get-shape-from-contour (lines:Tuple<Line|Polyline>) -> Polygon|PolygonWithArcs
Get a shape from a tuple of lines/polylines.
Syntax
val line1 = Line(1.0, [Point(0.0, 1.0), Point(0.0, 0.0)])
val line2 = Polyline(1.0, [Point(0.0, 0.0), Point(1.0, 0.0), Point(0.0, 1.0)])
val shape = get-shape-from-contour([line1, line2])
println(shape)
Description
The get-shape-from-contour command computes a polygon from
a list of lines and/or polylines. The lines/polylines must
be in the same order as they are along the boundary of the
polygon.