Properties¶

Properties are a flexible way to add data to ports, instances, and nets. We can create and query properties inside components and modules.

The property statement is valid within the following contexts:

Signature¶

; Get Form
val v1:JITXValue = property(dot-path)
val v2:Maybe<JITXValue> = property?(dot-path)
val v3:JITXValue = property?(dot-path, def-value)

val v4:True|False = has-property?(dot-path)

; Set Form
property(dot-path) = 3.0

The "Get" form of the property statement allows the user to inspect a particular property of an object. If the requested property doesn't exist, then a NoPropertyWithName exception will be thrown.

The property? statement is a "Get" form that will return a Maybe element or allow for a default value def-value. This get statement form will not throw an exception if the property doesn't exist. It will either return None() or it will return the passed def-value.

The has-property? statement checks for the existence of a particular property on a particular object. This statement is often used with the eval-when statement.

The "Set" form of the property statement allows the user to create a new property or override an existing property on an object. The value assigned to a property must be of type JITXValue.

The argument to the property statement is a dot notation path or dot-path. A dot-path will typically start with the name of an instance, net, or port, and the final element of the dot path will be the identifier for the property.

For example:

pcb-component props-test:

  port gnd : pin

  property(self.gnd.voltage) = 0.0

In this example, we use the special instance self to refer to this component instance (ie, an instance of props-test). The next element on the dot-path is referring to the gnd port of the props-test instance. Finally, the element voltage is the name of the property that is being set on the gnd port.

Assigned Types¶

The value assigned to a property must be of type JITXValue. The JITXValue type includes most of the built-in JITX types like Double, Int, Pose, Toleranced, String, etc. It will not necessarily include custom, user-defined types (ie, any type created with deftype or defstruct). If you try to set a property with a defstruct - you will see an exception thrown that looks something like:

Cannot call function 'set-property' with given arguments: Argument 4: Passing type 'CustomUserType' to expected type 'JITXValue'.

To assign more custom data types, you will need to define a pcb-struct type. This is similar to the defstruct style type definitions but adds additional features that fulfill the JITXValue interface.

Common Component Properties¶

Below is an example component with common property statement patterns:

pcb-component TPS62081:
  manufacturer = "Texas Instruments"
  mpn = "TPS62081DSG"
  datasheet = "https://www.ti.com/lit/ds/symlink/tps62082.pdf"
  pin-properties:
    [pin:Ref | pads:Int ...]
    [EN      | 1]
    [GND     | 2]
    [MODE    | 3]
    [FB      | 4]
    [VOS     | 5]
    [PG      | 6]
    [SW      | 7]
    [VIN     | 8]

  property(self.EN.threshold) = 1.0
  property(self.PG.leakage-current) = typ-max(0.01e-6, 0.1e-6)

  property(self.junction-temperature) = min-max(-40.0, 125.0)

This definition defines 3 properties, 2 on ports and 1 on the instance itself.

threshold and leakage-current are properties extracted from the datasheet.
junction-temperature is applied to the component via the self keyword.

Common Module Properties¶

In the below example, we show a pcb-module definition using property statements:

pcb-module switcher : 

  property(self.buck) = true

  port VIN : pin
  port VOUT : pin 
  port GND : pin

  property(VIN.max-voltage) = 6.0

  inst IC : TPS62081

  property(IC.no-clean) = true
  property(IC.FB.max-voltage) = 3.6

  net local-gnd (GND, IC.GND)

  property(local-gnd.voltage) = 0.0

In the module context, we have the opportunity to apply properties to:

The module instance itself via the self identifier
The ports of the module instance - eg VIN, VOUT
The component instances defined in the module - eg IC in this example.
Ports of the component instances in the module - eg IC.FB.
The nets of the module instance - eg local-gnd