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
andleakage-current
are properties extracted from the datasheet.junction-temperature
is applied to the component via theself
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