Introspection

To use these functions, import the package jitx/commands and the package jitx where the enums are defined.

  import jitx
  import jitx/commmands

ref

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.

name

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

evaluate

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.

port-type

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

instantiable-type

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).

indices

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.

instances

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.

public-instances

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.

single-instances

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.

public-single-instances

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.

component-instances

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).

ports

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.

pins

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.

nets

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.

public-nets

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.

single-pin-nets

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.

public-single-pin-nets

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.

refs

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)

get-net

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.

length

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.

originating-instantiable

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.

containing-instance

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.

instance-definition

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.

instance-type

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

mpn?

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.

manufacturer?

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.

datasheet?

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.

reference-prefix?

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.

emodel?

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.

reference-designator

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.

connected?

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.

connected-pins

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.

all-connected-items

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>

layers

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.

layer

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.

pads

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.

pose

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.

side

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.

pad

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.

pad-shape

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.

pad-type

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)

landpattern

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.

package-poses

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

do-not-populate?

defn do-not-populate?  (obj:JITXObject) -> True|False

Check if a component instance is marked do-not-populate

component-status?

defn component-status?  (obj:JITXObject) -> [ComponentBOMStatus, ComponentBoardStatus]

Retrieve the component in-BOM and on-board status of a component instance

no-connect?

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.

get-min-width

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.

get-min-space

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.

get-board

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.

has-board?

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.

current-rules

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.

current-rules?

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.

clearances

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.

clearance

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.

get-export-backend

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.

get-shape-from-contour

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.