JITX Official Documentation

Welcome to the official documentation of JITX. Here you'll find function references, tutorials, how-to guides, FAQs, and all of the information you need to learn and use JITX.

What Is JITX?

JITX is a tool that helps you design PCBs with automation of circuit design, component selection, component modeling, pin assignment, geometric constraints, schematic drafting, schematic verification, and more. You can design at the system level and automate the rest.

New Users / Getting Started / How To Start

If you're new to using JITX, welcome! A background in electrical engineering is all you need to get up and running designing boards in JITX.

For new users, we recommend reading through this page, then starting with the Tutorials, which will give you a quickstart to setting up and using JITX for your designs. Specifically, checkout the workflows below for a path to get started:

Suggested Onboarding Workflows

First Time User - End to End Design

1. Setup and install JITX with JITX Installation Instructions.
2. Design a basic board in JITX and export to CAD - do Quickstart 1
3. Organize your schematic and layout with Quickstart II: Organize a schematic
4. Export to CAD (KiCad or Altium) by following Exporting to CAD
5. Layout the PCB in CAD the same way that you normally would.

Working with Existing Projects

1. Import your design from CAD
   • How to import from KiCad into JITX
   • How to import from Altium into JITX
2. Revise your design in JITX
   • Revising a KiCad Design in JITX
   • Revising an Altium design in JITX
3. Export your design back into CAD
   • How to export from JITX into Altium Designer
     • How to Install the JITX Extension for Altium Designer
   • How to export from JITX into KiCad

Checking Designs

1. Follow Write a check
2. Follow Analyze a design

Creating Components

1. Follow Creating Components - Model a power regulator
2. Follow Parametric Land Patterns

In Depth

1. Follow First Time User, Checking Designs, and Creating Components Workflow.
2. Follow Learn JITX
3. Follow Quickstart III: Check a design

How To Use These Docs

Use the left side bar to move around the documentation (you can open the left side bar by clicking the ☰ in the top left of this page), and use the search bar above to search for functions, questions, tutorials, etc.

Install

Follow this tutorial to get JITX setup on your own system: Installing JITX

How Do I Get Help?

If you haven't been able to answer your questions by looking through the tutorials and using the search bar above, you can get help from JITX Inc. directly using one of the methods below.

VSCode Extension Method

This method assumes you have JITX installed in VSCode.

1. Open VSCode.
2. Click the "JITX" extension icon in the left side bar.
3. Click the hamburger menu in the top left that looks like this: ☰
4. Click "Request help"
5. Fill out the form. We'll get back to you right away.

Web Method

If the VSCode extension method doesn't work for you, you can fill out this form to request help, we'll get back to you right away: https://support.jitx.com/hc/en-us/requests/new

Resources

• JITX Official Website
• JITX Github
• Learning Stanza (the programming language that JITX uses): http://lbstanza.org/stanzabyexample.html
• JITX Demo Videos
  • https://www.youtube.com/watch?v=PkfMr6CSR60 - Software defined electronics.
  • https://www.youtube.com/watch?v=ebKaLhxQn8Y - Create a new design.

Documentation Overview/Sections

The organization of the docuementation is as follows (see the side bar for a full index of the documentation).

1. JITX Documentation Introduction - intro to the docs.
2. Reference
   • Reference materials are the low-level documentation of JITX. The Reference materials refer to technical descriptions of JITX's machinery and its operation. Things like descriptions of key classes, functions, and APIs
3. Tutorials
   • Tutorials are small, rewarding projects that help you learn JITX.
4. How-To Guides
   • How-to guides take you through a series of steps to help you solve a specific real world problem. They are tools for practitioners who are trying to get something done using JITX.
5. Open Component Database (OCDB)
   • The Open Components Database (OCDB) is an open database of components and circuit generators for automated circuit board design. This section provides users with quick access to information on how to use everything in OCDB with examples.
6. BOM Import Data Format
   • Describes how to import a BOM.
7. Example Designs
   • The example designs consists of projects exemplifying common use cases.
8. Frequently Asked Questions
   • This section contains questions that users frequently encounter.

Documentation Index

You can access the index of the entire docs in the left hand side panel.

JITX Docs Index

• JITX Documentation - Intro - PCB Design Software Defined Hardware
• Documentation Index
• JITX Reference
  • JITX Statements
    • Boards
      • name
      • description
      • layer
      • stackup
        • layer
    • Bundles
      • name
      • description
      • ports
    • Checks
      • #CHECK
    • Components
      • description
      • emodel
      • landpattern
      • manufacturer
      • datasheet
      • mpn
      • name
      • pin-properties
      • ports
      • property
      • reference-prefix
      • require
      • supports
      • symbol
      • value-label
    • Enums
    • Geometry
      • Shape
        • Circle
        • Line
        • Point
        • Polygon
        • Rectangle
        • Text
        • Union
      • copper
      • copper-pour
      • loc
      • via
    • Land Patterns
      • copper
      • description
      • external-names
      • layers
      • name
      • pad
      • via
      • ref-label
      • model3d
    • Materials
      • name
      • description
    • Modules
      • description
      • geom
      • inst
      • layer
      • component-status
      • do-not-populate
      • layout-group
      • name
      • net
      • node
      • place
      • ports
      • property
      • reference-designator
      • require
      • restrict
      • schematic-group
      • short-trace
      • supports
      • symbol
      • variants
    • Pads
      • name
      • description
      • layer
    • Rules
      • name
      • description
    • Stackups
    • Symbols
      • backend-substitution
      • description
      • layer
      • name
      • ports
      • preferred-orientation
    • Structs
  • JITX Types
  • JITX Patterns Cheat Sheet
  • Stanza Cheat Sheet
  • Commands
    • Main Design
    • Top Level Commands
    • Lookup
    • Part Query API
  • Utilities
    • Stateful
    • Toleranced
    • Design Variables
    • Land Patterns
    • Land Protrusions
    • Properties
    • Closest Standard Value
    • Mounting Holes
    • Testpoints
    • Make-Net
    • Set Symbols
  • Components
    • Resistors
    • Capacitors
    • Inductors
    • Microcontrollers
  • Open Components Database
  • BOM Import Data Format
  • Converting Number Types
  • Using Schematic and Physical Design
  • Known Issues
• Tutorials
  • Quickstarts (Start Here)
    • Quickstart I: Your First JITX Design
      • Completed Code
    • Quickstart II: Organize and Layout a Design
      • Completed Code
    • Quickstart III: Circuit Generators
      • Completed Code
    • Quickstart IV: Check a Design
      • Completed Code
  • Learn JITX
    • Components and Nets
      • Tutorial Code
    • Landpatterns and Symbols
      • Tutorial Code
    • Parametric CAD
      • Tutorial Code
    • Modules
      • Tutorial Code
    • Properties and Parametric Circuits
      • Tutorial Code
    • Bundles
      • Tutorial Code
    • Pin Assignment
      • Tutorial Code
  • Create a Component
    • Tutorial Code
  • Write a Check
    • Completed Code
  • Analyze a Design
  • Revise a Design
    • Revising a KiCad Design in JITX
    • Revising an Altium Design in JITX
  • Create a Land Pattern
    • Requirements and Errata
  • Import from CAD
    • How to Import from KiCad into JITX
    • How to Import from Altium into JITX
  • Export to CAD
    • How to Export from JITX into Altium Designer
      • How to Install the JITX Extension for Altium Designer
    • How to Export from JITX into KiCad
  • Tips For When You're Stuck
• Example Designs
• FAQs
  • Installation Instructions
  • Troubleshooting Your Installation
  • Keyboard Shortcuts / Hotkeys

JITX Reference

Reference materials refer to technical descriptions of JITX’s machinery and its operation. Things like descriptions of key classes, functions, and APIs would fall under this umbrella. This includes types, statements, and commands among other things.

• Types are classifications of circuit board concepts and define their possible values and operations.
• Statements are pieces of code, often one line each, that together define a design. Statements are what constructs ESIR (Electronic Systems Intermediate Representation) to create designs.
• Commands are function calls that retrieve information from or modify a design.

Examples

• Commands
  • pins (obj:JITXObject) retrieves all pins in the given JITXObject.
  • set-rules (rules:Rules) assigns a Rules to your design.
• Statements
  • mpn = "TRS3122ERGER" assigns a component's mpn.
  • port p : pin[2] creates a port with two pins.
• Types
  • Top-level definitions have types including LandPattern, SchematicSymbol, and Board. They all subtype JITXDef, meaning that objects with these types can perform the same operations as a JITXDef.
  • Local definitions have types including LandPatternPad and SymbolPin. They all subtype JITXObject.

JITX Statements

Boards

A pcb-board definition represents a physical circuit board. A board contains a stackup, boundary, signal boundary, and optional layer statements.

Syntax :

val board-shape = Recatangle(10.0, 10.0)

pcb-board my-circuit-board : 
  stackup: my-stackup
  boundary: board-shape
  signal-boundary: board-shape
  
  layer(Silkscreen("F-silk", Top)) = 
    Text("Board v1.2.3", 2.54, C, loc(0.0, 0.0))

Description

Here is the list of all of the statements you can use in a pcb-board :

Name

name is the optional name field of an JITX object. Use it to store a descriptive name as a String for human designers reading JITX.

Syntax

pcb-component component :
  name = "ADM7150"

pcb-pad smd-pad (anchor:Anchor, w:Double, h:Double) :
  name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor])

pcb-module band-pass-filter :
  name = "Band-pass filter"

Description

name = "ADM7150" Name this component "ADM7150"

name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor]) Name this pad by constructing a name passed to a paramteric pad function

name = "Band-pass filter" Name this module "Band-pass filter"

Description

description is the optional description field of a JITX object. Use it to store a description of the object for human designers reading JITX, and to make the object easier to find via text search.

Syntax

pcb-component analog-devices-ADM7150 :
  description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator"

pcb-module band-pass-filter :
  description = "Passive band-pass filter with cascaded highpass and low-pass stages."

Description

description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator" Add a description to call out special functions of the device.

name = "Band-pass filter" Add a description to signify the intent of a circuit.

Layer

layer is used to create geometry on the manufacturing layers of a circuit board. Layers can be used inside pcb-landpattern, and pcb-module.

Syntax

layer(Courtyard(Top)) = Rectangle(3.0, 2.0)
layer(SolderMask(Top)) = Rectangle(anchor, w, h)
layer(Silkscreen("values", Top)) = Text(">REF", 1.0, a, loc(x,y))
layer(Silkscreen("f-silk", Top)) = LineRectangle(1.5, 3.0)
layer(Silkscreen("pol", Top)) = Circle(x0, y0, 0.254)

layer(ForbidCopper(LayerIndex(n)))
layer(ForbidCopper(LayerIndex(2,Bottom)))
layer(ForbidCopper(LayerIndex(0), LayerIndex(2)))
layer(ForbidCopper(LayerIndex(0), LayerIndex(0, Bottom)))

Description

• layer(Courtyard(Top)) = Rectangle(3.0, 2.0) Define a 3mmx2mm Rectangle on the top courtyard layer. This would define the bounds of an SMD land pattern.
• layer(SolderMask(Top)) = Rectangle(w, h) Define a w x h Rectangle on the top soldermask layer, as used to define soldermask for a pad.
• layer(Silkscreen("values", Top)) = Text(">REF", 1.0, a, loc(x,y)) Add 1mm high text saying ">REF" to the top silkscreen layer, anchored at a and located at (x,y). "values" is used to specify the intent of the text; all silkscreen on the top layer will get flattened to a single silkscreen layer in CAD export.
• layer(Silkscreen("f-silk", Top)) = LineRectangle(1.5, 3.0) Add a 1.5mmx3mm rectangular outline to the top silkscreen.
• layer(Silkscreen("pol", Top)) = Circle(x0, y0, 0.254) Add a circular polarity marker to the top silkscreen.

We can create geometry on the copper layers in our board using the LayerIndex function. For example, here's how to create a keepout:

• layer(ForbidCopper(LayerIndex(2))) Forbid Copper on third layer from top
• layer(ForbidCopper(LayerIndex(2,Bottom))) Forbid Copper on third layer from bottom
• layer(ForbidCopper(LayerIndex(0), LayerIndex(2))) Forbid Copper on top three layers
• layer(ForbidCopper(LayerIndex(0), LayerIndex(0, Bottom))) Forbid Copper on all layers

All layer specifiers

pcb-stackup

Outline

pcb-stackup :
  name:        String 
  description: String

  *layer(thickness:Double, material:pcb-material) 

Description

A set of manufacturing rules that defines the materials and thicknesses of each layer (including insulators) of a PCB. Probably defined by your fab.

Usage

pcb-stackup Oshpark4Layer : 
  name        = "Oshpark Four Layer Stackup"
  description = "The standard 4 layer stackup at OshPark"
  
  layer(1.0, dlp)
  layer(1.0, ENIG)
  layer(1.4, copper-1_0)
  layer(6.7, FR408_prepreg)
  layer(0.7, copper-0_5)
  layer(47.0 FR408_core)
  layer(0.6, copper-0_5)
  layer(6.7, FR408_prepreg)
  layer(1.4, copper-1_0)
  layer(1.0, ENIG)
  layer(1.0, dlp)

Statements

Stackup Layers

The layer statement inside a pcb-stackup declares a layer within the stackup.

Syntax

layer(size, material)
layer (size, material)
layer name (size, material)

The optional name argument define the name of the layer for later reference. The size argument defines the vertical height of the layer of the stackup, in millimeters. The material parameter associates a pcb-material definition with the layer.

Bundle Statements

A pcb-bundle definition groups a set of pins. Bundles can include ports and other bundles. You can connect bundles using a net statement, or use supports and require statements with bundles for automated pin assignment.

For example we can create a bundle for an i2c bus with the following statement:

pcb-bundle i2c:
  pin sda
  pin scl

Bundles can be parametric and include other bundles. Here is a definition for a bank of lvds pins of variable size:

pcb-bundle diff-pair :
  pin N
  pin P

pcb-bundle lvds-bank (width:Int) :
  port clk : diff-pair
  port data : diff-pair[width]

You can make bundles parametric to represent optional pins. Here's an example of a parametric SWD bundle, that can optionally include the SWO pin:

pcb-bundle swd (swo:True|False) :
  pin swdio
  pin swclk
  pin reset
  if swo :
    pin swo

Statements

Here is the list of all of the statements you can use in a pcb-bundle :

Name

name is the optional name field of an JITX object. Use it to store a descriptive name as a String for human designers reading JITX.

Syntax

pcb-component component :
  name = "ADM7150"

pcb-pad smd-pad (anchor:Anchor, w:Double, h:Double) :
  name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor])

pcb-module band-pass-filter :
  name = "Band-pass filter"

Description

name = "ADM7150" Name this component "ADM7150"

name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor]) Name this pad by constructing a name passed to a paramteric pad function

name = "Band-pass filter" Name this module "Band-pass filter"

Description

description is the optional description field of a JITX object. Use it to store a description of the object for human designers reading JITX, and to make the object easier to find via text search.

Syntax

pcb-component analog-devices-ADM7150 :
  description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator"

pcb-module band-pass-filter :
  description = "Passive band-pass filter with cascaded highpass and low-pass stages."

Description

description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator" Add a description to call out special functions of the device.

name = "Band-pass filter" Add a description to signify the intent of a circuit.

Ports

port is a JITX statement that defines pins on components and modules that you can net to.

Syntax

port a : pin
pin a

port b : pin[6]
port c : pin[[1, 2, 4 through 6]]

port data : i2c
port lots-of-data : i2c[30]

Description

port a : pin Create a port with a single pin named a

pin a Create a port with a single pin named a (same as above, but more convenient syntax.)

port b : pin[4] Create a port named b with 4 pins named b[0] through b[3]. You can loop over these pins programmatically:

for i in indices(b) do:
  net (b[i])
  println(i)

Prints out:

0
1
2
3

port c : pin[[1, 2, 4 through 6]] Create a port named c with a non-standard range. c has 4 pins named c[1] c[2] c[4] c[5] and c[6]. You can loop over these pins programmatically:

for i in indices(c) do:
  net (c[i])
  println(i)

Prints out:

1
2
4
5
6

port data : i2c Create a port named data of the pcb-bundle named i2c.

port lots-of-data : i2c[30] Create a port array with 30 I2C ports. lots-of-data[0].sda is the sda pin of the first I2C bundle.

Check Statements

Checks are how we check our designs for correctness. We can write arbitrary code to scan through our designs, inspect the data and make sure the circuit will work as designed. The checking functions contain code that generates a well formatted report, that prompts us to enter more data or points out errors in our design.

ocdb/utils/checks has a large set of common checks, and code to apply those automatically checks to a design.

We can also define checks that are specific to a circuit or component. The goal is to create circuit generators that check themselves for correctness, making our design work more reusable.

Example check for AEC ratings

pcb-check aec-q200 (component:JITXObject):

    #CHECK(
    name =                 "Automotive rating"
    description =          "Check that a passive component is AEC Q200 rated"
    condition =            has-property?(component.aec-rating),
    category =             "Component Data"
    subcheck-description = "Check that %_ has a defined aec-rating" % [ref(component)],
    pass-message =         "%_ has a property for aec-rating of %_" % [ref(component) property(component.aec-rating)],
    info-message =         "%_ does not have an aec-rating property attached" % [ref(component)],
    locators =             [instance-definition(component)]
    )

    #CHECK(
    name =                 "Automotive rating"
    description =          "Check that a passive component is AEC Q200 rated"
    condition =            property(component.aec-rating) == "Q200",
    category =             "Component Checks"
    subcheck-description = "Check that %_ is AEC Q200 rated." % [ref(component)],
    pass-message =         "%_ is AEC Q200 rated" % [ref(component)],
    fail-message =         "%_ is not AEC Q200 rated. Instead has rating %_." % [ref(component) property(component.aec-rating)],
    locators =             [instance-definition(component)]
    )

    pcb-module checked-design :
      inst r : chip-resistor(1.0)
      check aec-q200(r)

Statements

Here is the list of all of the statements you can use in a pcb-check :

#CHECK

We use #CHECK statements to evaluate conditions in our designs, and then show a Pass Add Info or Fail state.

Syntax

pcb-check aec-q200 (component:JITXObject):

    #CHECK(
    name =                 "Automotive rating"
    description =          "Check that a passive component is AEC Q200 rated"
    condition =            has-property?(component.aec-rating),
    category =             "Component Data"
    subcheck-description = "Check that %_ has a defined aec-rating" % [ref(component)],
    pass-message =         "%_ has a property for aec-rating of %_" % [ref(component) property(component.aec-rating)],
    info-message =         "%_ does not have an aec-rating property attached" % [ref(component)],
    locators =             [instance-definition(component)]
    )

    #CHECK(
    name =                 "Automotive rating"
    description =          "Check that a passive component is AEC Q200 rated"
    condition =            property(component.aec-rating) == "Q200",
    category =             "Component Checks"
    subcheck-description = "Check that %_ is AEC Q200 rated." % [ref(component)],
    pass-message =         "%_ is AEC Q200 rated" % [ref(component)],
    fail-message =         "%_ is not AEC Q200 rated. Instead has rating %_." % [ref(component) property(component.aec-rating)],
    locators =             [instance-definition(component)]
    )

Description

The above #CHECK statements generate this report, when run on a component with instance nae r[0].

name The name of the check

description The top-level description of the check in the report

condition A boolean expression that evaluates to true or false. This condition defines if the check passes, or fails.

category The top-level category to organize this check in the report.

subcheck-description A detailed description of the result of this specific #CHECK

pass-message What should be printed in the report if condition resolves to true

fail-message What should be printed in the report if condition resolves to false and the #CHECK describes a design error. A #CHECK can have a fail-message or a pass-message but not both.

info-message What should be printed in the report if condition resolves to false and the #CHECK describes missing data. A #CHECK can have a fail-message or a pass-message but not both.

locators A list of code locators that help the reader of the report what specific aspect of the design needs attention when the #CHECK fails.

Components

A pcb-component definition models a single part that can be placed on a board. Components have ports, schematic symbols, a landpattern, and associated metadata.

Here is an example definition for an Epson FC-135 crystal oscillator:

pcb-component epson-fc-135 :
  name = "32.768kHz Crystal"
  description = "CRYSTAL 32.7680KHZ 7PF SMD"
  manufacturer = "Epson"
  mpn = "FC-135 32.768KA-AG0"

  port p : pin[[1 2]]

  val sym = crystal-sym(0)
  symbol = sym(p[1] => sym.p[1], p[2] => sym.p[2])
  landpattern = xtal-2-3215(p[1] => xtal-2-3215.p[1], p[2] => xtal-2-3215.p[2])
  reference-prefix = "Y"

  property(self.load-capacitance) = 7.0e-12
  property(self.shunt-capacitance) = 1.0e-12
  property(self.motional-capacitance) = 3.4e-15
  property(self.ESR) = 70.0e3
  property(self.frequency) = 32.768e3
  property(self.frequency-tolerance) = 20.0e-6
  property(self.max-drive-level) = 0.5e-6 

Statements

Here is the list of all of the statements you can use in a pcb-component :

Description

description is the optional description field of a JITX object. Use it to store a description of the object for human designers reading JITX, and to make the object easier to find via text search.

Syntax

pcb-component analog-devices-ADM7150 :
  description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator"

pcb-module band-pass-filter :
  description = "Passive band-pass filter with cascaded highpass and low-pass stages."

Description

description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator" Add a description to call out special functions of the device.

name = "Band-pass filter" Add a description to signify the intent of a circuit.

EModel

The emodel statement inside a pcb-component associates the component with an electrical model.

Syntax

; define a resistor EModel
inside pcb-component :
  emodel = Resistor(resistance-ohms, tolerance-%, max-power-watts)

; define a capacitor EModel
inside pcb-component :
  emodel = Capacitor(capacitance-farads,
                     tolerance-%,
                     max-voltage-volts,
                     polarized?, ; optional boolean
                     low-esr?,   ; optional boolean
                     temperature-coefficient?, ; optional string, eg "X7R" or "X5R"
                     dielectric? ; optional)   ; optional string, eg "Ceramic, "Tantalum", "Electrolytic"

; define an inductor EModel
inside pcb-component :
  emodel = Inductor(inductance-microhenries, tolerance-%, max-current-amps)

; define a diode EModel
inside pcb-component :
  emodel Diode(forward-current-amps, 
               forward-voltage-volts, 
               max-current-amps, 
               max-reverse-voltage-volts,
               color?, ; optional, for LEDs
               luminous-intensity-millicandelas) ; optional, for LEDs

Description

An emodel is a simplified model of electrical properties. More complete simulation models can be defined with spice statements (coming soon).

Land Pattern

landpattern is an ESIR statement that associates a physical footprint/land-pattern with a component, and maps the ports of the component to the pads of the land-pattern.

Syntax

pcb-component inverted-f-antenna-cmp :
  description = "2.4 GHz Inverted F trace antenna"
  pin launch
  pin gnd
  val lp = ant-2GHz4-inverted-f-geom
  landpattern = lp(launch => lp.p[1], gnd => lp.p[2], gnd => lp.p[3], gnd => lp.p[4])

pcb-component amphenol-minitek127 (n-pins:Int) :
  description = "SMD Female 1.27mm pitch header"
  port p : pin[1 through n-pins]
  val lp = amphenol-minitek127-pkg(n-pins)
  landpattern = lp(for i in 1 through n-pins do: p[i] => lp.p[i])

Description

The land pattern statement specifies a land pattern to use, as well as a pad mapping. The general pattern is:

pcb-component my-component:
  pin component-pin-a
  pin component-pin-b
  landpattern = my-landpattern(component-pin-a => landpattern-pad-a, component-pin-b => landpattern-pad-b)

Where my-landpattern is the name of the pcb-landpattern, which has pads landpattern-pad-a and landpattern-pad-b.

The following snippet matches component port launch to the p[1] pad of the antenna-landpattern, and the component port gnd to three pads on the land pattern p[2], p[3], and p[4]. When we net to inverted-f-antenna-cmp.gnd, all associated land pattern pads will be added to the netlist.

pcb-component inverted-f-antenna-cmp :
  description = "2.4 GHz Inverted F trace antenna"
  pin launch
  pin gnd
  val lp = ant-2GHz4-inverted-f-geom
  landpattern = lp(launch => lp.p[1], gnd => lp.p[2], gnd => lp.p[3], gnd => lp.p[4])

Note that when you instantiate this component in a design, you can only net to the ports of the component, not the pads of the landpattern. e.g.:

inst ant : inverted-f-antenna-cmp
net (ant.gnd) ; Allowed
net (ant.p[2]) ; NOT Allowed, and will cause a compile error.

To save some typing, you can use for loops in the land pattern pad-mapping. The following snippet matches (p[1] => p[1], p[2] => p[2], ... p[n-pins] => p[n-pins]) for a parametric land pattern that has the same pad names as the component.

pcb-component amphenol-minitek127 (n-pins:Int) :
  description = "SMD Female 1.27mm pitch header"
  port p : pin[1 through n-pins]
  val lp = amphenol-minitek127-pkg(n-pins)
  landpattern = lp(for i in 1 through n-pins do: p[i] => lp.p[i])

Manufacturer

manufacturer defines the manufacturer of a component. It is used to create our bill of materials, and to check the sourceability of the pcb-component.

Syntax

manufacturer = "Texas Instruments"

Description

manufacturer = "Texas Instruments" The manufacturer of this component is "Texas Instruments"

Manufacturer

datasheet defines the link to the datasheet of a component.

Syntax

datasheet = "https://www.jitx.com/components/one/datasheet.pdf"

Description

datasheet = "https://www.jitx.com/components/one/datasheet.pdf" The link to the datasheet of this component is "https://www.jitx.com/components/one/datasheet.pdf"

MPN

mpn defines the manufacturer part number of a component. It is used to create our bill of materials, and to check the sourceability of the pcb-component.

Syntax

mpn = "TPD3S014DBVR"

val n-sw = 8
mpn = to-string("219-%_MSTR"%[n-sw])

Description

mpn = "TPD3S014DBVR" The MPN of this component is "TPD3S014DBVR"

Sometimes we model a family of parts with a single pcb-component, so the mpn is constructed parametrically.

val n-sw = 8
mpn = to-string("219-%_MSTR"%[n-sw])

Results in mpn = "219-8MSTR".

Name

name is the optional name field of an JITX object. Use it to store a descriptive name as a String for human designers reading JITX.

Syntax

pcb-component component :
  name = "ADM7150"

pcb-pad smd-pad (anchor:Anchor, w:Double, h:Double) :
  name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor])

pcb-module band-pass-filter :
  name = "Band-pass filter"

Description

name = "ADM7150" Name this component "ADM7150"

name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor]) Name this pad by constructing a name passed to a paramteric pad function

name = "Band-pass filter" Name this module "Band-pass filter"

Pin Properties

We created pin-properties to make it easy to quickly model a component from a datasheet, capture the pin assignment, and create a box symbol. pin-properties generates the usual low-level JITX statements for symbols, pin creation, and pin assignment.

Example of Modeling a Component

#use-added-syntax(jitx)
defpackage mygenerator :
  import core
  import collections
  import box-symbol

pcb-component mycomponent :
  ;Each row has format:
  pin-properties :
    [pin:Ref | pads:Int ...   ]
    [a       | 1         ]
    [b       | 2         ]
    [c       | 3         ]        
    [gnd     | 4 5 6 7 8 ]
    [d+      | 9         ]
    [d-      | 10        ]

  ;Make a generic box symbol for the pins
  make-box-symbol()

  ;Assign the given land pattern the pad associations
  ;in the table.
  assign-landpattern(mylandpattern)

Note that when the pad name is given as a raw integer, i, then it is assumed that the full pad name is p[i] in the land pattern definition.

Assigning a Direction in the Box Symbol

pcb-component mycomponent :
  ;Each row has format:
  pin-properties :
    [pin:Ref | pads:Int ...   | side:Dir   ]
    [a       | 1              | Left  ]
    [b       | 2              | Left  ]
    [c       | 3              | Left  ]
    [gnd     | 4 5 6 7 8      | Down  ]
    [d+      | 9              | Right ]
    [d-      | 10             | Right ]

  ;Make a generic box symbol for the pins
  make-box-symbol()

  ;Assign the given land pattern the pad associations
  ;in the table.
  assign-landpattern(mylandpattern)

Programmatic Tables

The tables can be generated programmatically:

pcb-component mycomponent :
  ;Each row has format:
  ;  [pin name | pad numbers ... | side]
  pin-properties :
    [pin:Ref | pads:Int ... | side:Dir ]
    for i in 0 to 10 do :
      [A[i] | i, i + 20 | Left]

  ;Make a generic box symbol for the pins
  make-box-symbol()

  ;Assign the given land pattern the pad associations
  ;in the table.
  assign-landpattern(mylandpattern)

Working with Land Patterns with Named Pads

pcb-component mycomponent :
  ;Each row has format:
  ;  [pin name | pad name ... | side]
  pin-properties :
    [pin:Ref | pads:Ref ...   | side:Dir ]
    [a       | A[1]           | Left  ]
    [b       | A[2]           | Left  ]
    [c       | A[3]           | Left  ]
    [gnd     | C[0] C[1] C[2] | Down  ]
    [d+      | B[1]           | Right ]
    [d-      | B[10]          | Right ]

  ;Make a generic box symbol for the pins
  make-box-symbol()

  ;Assign the given land pattern the pad associations
  ;in the table.
  assign-landpattern(mylandpattern)

Multi-bank Box Symbols

Use a fourth column to indicate the bank. The bank can either be given as an integer:

pcb-component mycomponent :
  pin-properties :
    [pin:Ref | pads:Ref ...   | side:Dir | bank:Int]
    [a       | A[1]           | Left     | 0  ]
    [b       | A[2]           | Left     | 0  ]
    [c       | A[3]           | Left     | 0  ]
    [gnd     | C[0] C[1] C[2] | Down     | 1  ]
    [d+      | B[1]           | Right    | 1  ]
    [d-      | B[10]          | Right    | 1  ]

Or the bank can also be given as a Ref, which saves you the hassle of generating unique integers yourself.

pcb-component memory :
  pin-properties :
    [pin:Ref  | pads:Ref ... | side:Dir | bank:Ref ]
    [pwr      | A[1]         | Left     | base         ]
    [gnd      | B[1]         | Down     | base         ]
    [clk      | C[1]         | Left     | base         ]
    [sig      | A[2]         | Right    | base         ]
    [en       | C[2]         | Up       | base         ]
    [data[0]  | A[3]         | Left     | data-bank[0] ]
    [data[1]  | A[4]         | Left     | data-bank[0] ]
    [data[2]  | A[5]         | Left     | data-bank[0] ]
    [data[3]  | B[3]         | Left     | data-bank[0] ]
    [data[4]  | B[4]         | Left     | data-bank[0] ]
    [data[5]  | B[5]         | Left     | data-bank[0] ]
    [data[6]  | C[3]         | Left     | data-bank[1] ]
    [data[7]  | C[4]         | Left     | data-bank[1] ]
    [data[8]  | C[5]         | Left     | data-bank[1] ]
    [data[9]  | D[0]         | Left     | data-bank[1] ]
    [data[10] | D[1]         | Left     | data-bank[1] ]
    [data[11] | D[2]         | Left     | data-bank[1] ]

Ports

port is a JITX statement that defines pins on components and modules that you can net to.

Syntax

port a : pin
pin a

port b : pin[6]
port c : pin[[1, 2, 4 through 6]]

port data : i2c
port lots-of-data : i2c[30]

Description

port a : pin Create a port with a single pin named a

pin a Create a port with a single pin named a (same as above, but more convenient syntax.)

port b : pin[4] Create a port named b with 4 pins named b[0] through b[3]. You can loop over these pins programmatically:

for i in indices(b) do:
  net (b[i])
  println(i)

Prints out:

0
1
2
3

port c : pin[[1, 2, 4 through 6]] Create a port named c with a non-standard range. c has 4 pins named c[1] c[2] c[4] c[5] and c[6]. You can loop over these pins programmatically:

for i in indices(c) do:
  net (c[i])
  println(i)

Prints out:

1
2
4
5
6

port data : i2c Create a port named data of the pcb-bundle named i2c.

port lots-of-data : i2c[30] Create a port array with 30 I2C ports. lots-of-data[0].sda is the sda pin of the first I2C bundle.

Properties

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

Syntax

  import jitx
  import ocdb/utils/property-structs

pcb-component mycomponent :
  pin a
  pin b

  property(a.leakage-current) = 50.0e-6
  has-property?(a.leakage-current) ; returns true
  property(a.leakage-current) ; returns 50.0e-6

  property(b.power-pin) = PowerPin(min-typ-max(4.5, 5.5, 5.0))

  property(self.rated-temperature) = min-max(-55.0 125.0)

pcb-module my-module :
  port i2c : i2c
  inst comp : my-component

  net SDA (i2c.sda comp.a)
  net VDD (i2c.sda comp.b)

  property(comp.rated-temperature) ; returns min-max(-55.0 125.0)
  property(comp.a.leakage-current) ; returns 50.0e-6

  property(comp.no-clean) = false
  has-property?(comp.no-clean) ; returns true
  property(comp.no-clean) ; returns false

  property(VDD.voltage) = min-max(3.0, 3.5)

Description

Component property statements

property(a.leakage-current) = 50.0e-6 Create a property on pin a with name leakage-current and value 50.0e-6.

has-property?(a.leakage-current) Check if pin a has a property named leakage-current.

property(a.leakage-current) Get the value of the property on pin a named leakage-current.

property(b.power-pin) = PowerPin(min-typ-max(4.5, 5.5, 5.0)) Create a property on pin b with name power-pin and value of a pcb-struct from ocdb/utils/property-structs.

property(self.rated-temperature) = min-max(-55.0 125.0) Create a property on the component with name rated-temperature and value of a pcb-struct from ocdb/utils/property-structs.

Module property statements

property(comp.rated-temperature) Get the value of the property named rated-temperature on the instance of comp : my-component.

property(comp.a.leakage-current) Get the value of the property named leakage-current on pin a of the instance of comp : my-component.

property(comp.no-clean) = false Create a property named no-clean on the instance of comp : my-component, and give it the value false.

has-property?(comp.no-clean) Check if a property named no-clean on the instance of comp : my-component exists.

property(comp.no-clean) Get the value of a property named no-clean on the instance of comp : my-component.

property(VDD.voltage) = min-max(3.0, 3.5) Create a property named voltage on the net VDD, and give it the value min-max(3.0, 3.5).

Reference Prefix

The reference prefix sets the prefix of reference designators of component instances in JITX. If no reference-prefix is set, the default prefix is "U". Any string is valid as a reference prefix.

Syntax

pcb-component my-component:
  reference-prefix = "X"

pcb-component my-component:
  reference-prefix = "ESD"

Description

reference-prefix = "X" Set the reference prefix of this component to be "X". The first component would get reference designator X1.

reference-prefix = "ESD" Set the reference prefix of this component to be "ESD". The first component would get reference designator ESD1.

Require

require can be used in coordination with supports statements to automate pin assignment. When we use a require statement it creates a bundle which we can use like it already exists and the concrete pins it maps to are determined later.

Syntax

The general form of a require statement is:

require name-of-bundle:bundle-type from supporting-inst

pcb-module my-module :
  
  inst stm32 : stm32f405G7
  require data:i2c from stm32
  require lots-of-data:i2c[10] from stm32

  port p : pin[10]

  pcb-bundle io-pin :
    pin p

  for i in pins(p) do :
    supports io-pin:
      io-pin.p => i

  require dummy:io-pin[4] from self


pcb-component my-component :
  port p : pin[10]

  pcb-bundle io-pin :
    pin p

  for i in pins(p) do :
    supports io-pin:
      io-pin.p => i

  require dummy:io-pin[4]

  supports i2c :
    require sda-pin:io-pin
    require scl-pin:io-pin
    i2c.sda => sda-pin.p
    i2c.scl => scl-pin.p

Description

pcb-module my-module :
  
  inst stm32 : stm32f405G7
  require data:i2c from stm32
  require lots-of-data:i2c[10] from stm32

require data:i2c from stm32 Create a bundle named data of type i2c and specify that it needs to come from the stm32 instance. We can now use data in other code like net statements.

require lots-of-data:i2c[10] from stm32 Create a bundle array named lots-of-data of type i2c[10] and specify that it needs to come from the stm32 instance.

We can use require amd supports inside a module to use pin assignment more flexible (e.g. allow pin swaps for routability for any set of bundles or pins). Here we define a dummy bundle io-pin, add supports for it in the context of the current module, and can then use require dummy:io-pin[4] from self to access those supports.

  port p : pin[10]

  pcb-bundle io-pin :
    pin p

  for i in pins(p) do :
    supports io-pin:
      io-pin.p => i

  require dummy:io-pin[4] from self

Similarly we can use require inside a component definition, and we leave off the from because it can only be from the component itself:

pcb-component my-component :
  port p : pin[10]

  pcb-bundle io-pin :
    pin p

  for i in pins(p) do :
    supports io-pin:
      io-pin.p => i

  require dummy:io-pin[4]

And this can be used to simplify supports for bundles that can be supported on many possible pins. e.g. when a processor or FPGA has a full cross bar for all of its digital interfaces, and i2c could appear on any of the pins, we can capture that full flexibility with a require inside a supports statement:

  supports i2c :
    require sda-pin:io-pin
    require scl-pin:io-pin
    i2c.sda => sda-pin.p
    i2c.scl => scl-pin.p

We require two io-pin dummy pins (which can map to any component pin), and then map the i2c pins sda and scl to those pins. Now i2c can be mapped to any pin on the component.

Supports

Support statements are used as part of the pin assignment solver. We use supports to describe valid ways pins could be assigned.

Often supports are used to describe pin mappings on a processor (e.g. this i2c IP can have pins here or here). The support mechanism is very flexible and can be used more generally.

Syntax

The general syntax supports a pcb-bundle on a set of pins:

supports my-bundle:
  bundle.pin-1 => supporting-pin-1
  bundle.pin-2 => supporting-pin-2
  bundle.pin-3 => supporting-pin-3
  ...

We can later tap this support using a require statement like require something:my-bundle from supporting-inst.

More examples:

import ocdb/utils/bundles

pcb-component my-component :
  port sys : i2c
  port PA : pin[10]

  supports i2c :
    i2c.sda => sys.sda
    i2c.scl => sys.scl

  supports gpio :
    gpio.gpio => PA[0]

  supports gpio :
    option :
      gpio.gpio => PA[1]
    option :
      gpio.gpio => PA[4]

  pcb-bundle io-pin : (pin p)
  for i in 5 to 10 do:
    supports io-pin :
      io-pin.p => PA[i]

  supports uart([UART-DTR UART-RX UART-TX]) :
    require pins:io-pin[3]
    uart([UART-DTR UART-RX UART-TX]).tx => pins[0].p
    uart([UART-DTR UART-RX UART-TX]).rx => pins[1].p
    uart([UART-DTR UART-RX UART-TX]).dtr => pins[2].p

pcb-module my-module :
  inst c : my-component

  supports i2c : 
    i2c.sda => c.PA[2]
    i2c.scl => c.PA[3]

Description

  supports i2c :
    i2c.sda => sys.sda
    i2c.scl => sys.scl

This component supports i2c on the port named sys that is also of type i2c.

  supports gpio :
    gpio.gpio => PA[0]
    property(PA[0].is-gpio?) = true

Pin PA[0] of this component supports a gpio bundle. A property is-gpio? is set on this pin only if this support statement is trigged. i.e. if PA[0] is used as a gpio by the pin solver, then the property is-gpio? is set, but not otherwise.

  supports gpio :
    option :
      gpio.gpio => PA[1]
    option :
      gpio.gpio => PA[4]

Another gpio bundle is supported on pin PA[1] or PA[4], but not both.

  pcb-bundle io-pin : (pin p)
  for i in 5 to 10 do:
    supports io-pin :
      io-pin.p => PA[i]

  supports uart([UART-DTR UART-RX UART-TX]) :
    require pins:io-pin[3]
    uart([UART-DTR UART-RX UART-TX]).tx => pins[0].p
    uart([UART-DTR UART-RX UART-TX]).rx => pins[1].p
    uart([UART-DTR UART-RX UART-TX]).dtr => pins[2].p

Pins are often arbitrarily mappable, i.e. here any pin in PA[5 to 10] can support any pin of a uart interface with pins tx rx and dtr. We create a dummy bundle io-pin to support the flexibility of the mapping. Inside the supports statement for uart, we can require the three io-pin pins we need for the interface and then map them to our uart pins. The full space of possible pin assignments is captured and a valid solution will be found by the solver if any solution is possible.

pcb-module my-module :
  inst c : my-component

  supports i2c : 
    i2c.sda => c.PA[2]
    i2c.scl => c.PA[3]

Support statements can be associated with an instance's ports outside of that instance. Here we map an i2c bus to the pins of c at the module level.

Symbol

symbol is an ESIR statement that associates a schematic symbol with a component, and maps the ports of the component to the pins on the symbol.

Syntax

pcb-component inverted-f-antenna-cmp :
  description = "2.4 GHz Inverted F trace antenna"
  pin launch
  pin gnd
  symbol = antenna-symbol(1,1)(launch => antenna-symbol(1,1).p[1], gnd => antenna-symbol(1,1).p[2])

pcb-component amphenol-minitek127 (n-pins:Int) :
  description = "SMD Female 1.27mm pitch header"
  port p : pin[[1 through n-pins]]
  symbol  = header-symbol(n-pins,2)(for i in 1 through n-pins do: p[i] => header-symbol(n-pins,2).p[i])

Description

The symbol statement specifies a symbol to use, as well as a pin mapping. The general pattern is:

pcb-component my-component:
  pin component-pin-a
  pin component-pin-b
  symbol = my-symbol(component-pin-a => my-symbol.pin-a, component-pin-b => my-symbol.pin-b)

Where my-symbol is the name of the pcb-symbol, which has pins pin-a and pin-b.

The following snippet matches component ports launch and gnd to the pins of the parametric antenna-symbol p[1] and p[2].

pcb-component inverted-f-antenna-cmp :
  description = "2.4 GHz Inverted F trace antenna"
  pin launch
  pin gnd
  symbol = antenna-symbol(1,1)(launch => antenna-symbol(1,1).p[1], gnd => antenna-symbol(1,1).p[2])

Note that when you instantiate this component in a design, you can only net to the ports of the component, not the pins of the symbol. e.g.:

inst ant : inverted-f-antenna-cmp
net (ant.gnd) ; Allowed
net (ant.p[2]) ; NOT Allowed, and will cause a compile error.

To save some typing, you can use for loops in the symbol pin-mapping. The following snippet matches (p[1] => p[1], p[2] => p[2], ... p[n-pins] => p[n-pins]) for a parametric header symbol that has the same pin names as the component.

pcb-component amphenol-minitek127 (n-pins:Int) :
  description = "SMD Female 1.27mm pitch header"
  port p : pin[[1 through n-pins]]
  symbol = my-symbol(component-pin-a => my-symbol.pin-a, component-pin-b => my-symbol.pin-b)

Value Label

value-label can be used to change the value label of a component. value-label can also specify the location, size, orientation, etc. of the value label of a component.

You can set the value-label of a component by setting value-label(my-component) equal to a Text object. This Text object takes a string, text size, anchor location (N, E,S, or W), and the pose (loc) that specifies where to place the value label of the component.

Example usage

    ; name the test point, 
    value-label(my-component) = Text("my-component-value", 1.0, W, loc(1.2, 0.0))

Enum Statements

pcb-enum is a way to store categorical variables.

Example

Right now we need to use a fully qualified name to define a new pcb-enum. So if we wanted an enum named:

Antenna

And we're defining it in a package named

defpackage ocdb/components/espressif/esp32-wroom-32

Then the enum needs to be defined as follows:

public pcb-enum ocdb/components/espressif/esp32-wroom-32/Antenna :

All together this is what it looks like to define and use a pcb-enum:

defpackage ocdb/components/espressif/esp32-wroom-32:
...

public pcb-enum ocdb/components/espressif/esp32-wroom-32/Antenna :
  Integrated
  UMCX


  ; Using the pcb-enum as a type to define land pattern geometry
  pcb-landpattern esp32-wroom (antenna-type:Antenna) :
    switch(antenna-type):
      Integrated :
        package-y = 25.5
        offset = (25.5 - 19.2) / 2.0
      UMCX :
        package-y = 19.2
        offset = 0.0

Length of Enum

Get the length of an enum

When you create a new enum, called my-enum, Stanza (the language JITX uses) creates a new integer which represents the length of that enum, called my-enum-length.

Just add a -length to the end of any enum name to get its length.

Geometry Statements

Geometry statements are used to draw objects in JITX.

Shape

public deftype Shape <: Equalable & Hashable

Circle

public defstruct Circle <: Shape :
  center: Point
  radius: Double with: (ensure => non-negative!)

public defn Circle (x:Double, y:Double, radius:Double) :
  Circle(Point(x,y), radius)
  
public defn Circle (anchor:Anchor, x:Double, y:Double, radius:Double) :
  val [vt, hr] = components(anchor)
  val x* = match(hr) :
    (hr:W) : x + radius
    (hr:C) : x
    (hr:E) : x - radius
  val y* = match(vt) :
    (vt:S) : y + radius
    (vt:C) : y
    (vt:N) : y - radius
  Circle(Point(x*,y*), radius)
  
public defn Circle (anchor:Anchor, radius:Double) :
  Circle(anchor, 0.0, 0.0, radius)

public defn Circle (radius:Double) :
  Circle(C, 0.0, 0.0, radius)

Circle(Point(1.0, 3.0), 1.5)
Circle(1.0, 3.0, 1.5)
Circle(C, 1.0, 3.0, 1.5)
Circle(C, 5.0)
Circle(5.0)

Line

public defstruct Line <: Shape  :
  width: Double with: (ensure => non-negative!)
  points: Tuple<Point> with: (ensure => min-length!(2))
with:
  constructor => #Line

public defn Line (width:Double, pts:Seqable<Shape|Seqable>) :
  val pts* = to-tuple(flatten-shapes(pts))
  ensure-points(pts*, "line")
  #Line(width, pts* as Tuple<Point>)

Line(0.15, [
  Point(2.0, 2.0),
  Point(-2.0, 2.0),
  Point(-2.0, -2.0),
  Point(2.0, -2.0)])

Point

public defstruct Point <: Shape :
  x: Double with: (updater => sub-x)
  y: Double with: (updater => sub-y)

Point(5.0, 1.0)

Polygon

public defstruct Polygon <: Shape :
  points: Tuple<Point> with: (ensure => min-length!(3))
with:
  constructor => #Polygon

public defn Polygon (pts:Seqable<Point|Seqable>) :
  val pts* = to-tuple(flatten-shapes(pts))
  ensure-points(pts*, "polygon")
  #Polygon(pts* as Tuple<Point>)

Polygon([
  Point(2.0, 2.0),
  Point(-2.0, 2.0),
  Point(-2.0, -2.0),
  Point(2.0, -2.0)])

Rectangle

public defstruct Rectangle <: Shape :
  width: Double with: (ensure => non-negative!)
  height: Double with: (ensure => non-negative!)
  pose: Pose

public defn Rectangle (w:Double, h:Double) :
  Rectangle(w, h, loc(0.0, 0.0))
  
public defn Rectangle (anchor:Anchor, w:Double, h:Double) :
  val [vt, hr] = components(anchor)
  val dx = match(hr) :
    (hr:W) : w / 2.0
    (hr:C) : 0.0
    (hr:E) : w / -2.0
  val dy = match(vt) :
    (vt:S) : h / 2.0
    (vt:C) : 0.0
    (vt:N) : h / -2.0
  Rectangle(w, h, loc(dx, dy))

Rectangle(2.0, 3.0, loc(0.0, 0.0))
Rectangle(2.0, 3.0)
Rectangle(C, 2.0, 3.0)

Text

How to create text on the silkscreen of your board and place that text anywhere you want.

The Text function supports placing an arbitrary string on the silkscreen of your board. You can speficy the font size, the anchoring location, and position of the text.

public defstruct Text <: Shape  :
  string: String with: (updater => sub-string)
  size: Double with: (ensure => non-negative!, updater => sub-size)
  anchor: Anchor with: (updater => sub-anchor)
  pose: Pose with: (updater => sub-pose)

anchor sets the anchor for the text object. i.e. is the origin centered (C), south (S), west (W), east (E), or north (N)? NE, NW, SE, SW are also options.

Text("Sample", 2.0, C, loc(1.0, 1.0))

Union

public defstruct Union <: Shape  :
  shapes: Tuple<Shape>
with:
  constructor => #Union

public defn Union (ss:Seqable<Shape|Seqable>) :
  val ss* = generate<Shape> :
    let loop (s:Shape|Seqable = ss) :
      match(s) :
        (s:Union) : do(yield, shapes(s))
        (s:Shape) : yield(s)
        (s:Seqable) : do(loop, s)
  if empty?(ss*) :
    fatal("Cannot form union from no shapes.")
  else :
    val s0 = next(ss*)
    if empty?(ss*) : s0
    else : #Union(to-tuple(cat([s0], ss*)))

Union([Circle(1.0), Rectangle(4.0, 0.5)])

Copper

copper is a JITX statement for creating a shape on a copper layer of our board.

Syntax

geom(my-net):
  copper(LayerIndex(0)) = Circle(0.0, 15.0, 1.0)
  copper(LayerIndex(1)) = Line(1.0, [Point(0.0, -5.0) Point(5.0, -5.0)]) 

Description

• copper(LayerIndex(0)) = Circle(0.0, 15.0, 1.0) Create a copper circle at (x,y) = (0,15mm) of radius 1mm. You can use any Shape with the copper statement.
• copper(LayerIndex(1)) = Line(1.0, [Point(0.0, -5.0) Point(5.0, -5.0)]) Create a 1mm wide copper line (results in a trace) on the 2nd copper layer from the top.

Copper Pour

copper-pour is an ESIR statement for creating a filled outline on a copper-layer of our board. It gets exported to a plane in our CAD file.

Syntax

geom(my-net) :
  copper-pour(LayerIndex(0), isolate = 0.1) = Circle(0.0, 15.0, 1.0)
  copper-pour(LayerIndex(1), isolate = 0.1, rank = 1) = Rectangle(5.0, 5.0)
  copper-pour(LayerIndex(1), isolate = 0.1, rank = 1, orphans = true) = Rectangle(5.0, 5.0)

Description

• copper-pour(LayerIndex(0), isolate = 0.1) = Circle(0.0, 15.0, 1.0) Create a circular copper-pour on the top layer with 0.1mm geometric clearance/isolation. isolate is a required parameter for copper-pours. You can use any Shape with the copper-pour statement.
• copper-pour(LayerIndex(1), isolate = 0.1, rank = 1) = Rectangle(5.0, 5.0) Create a rectangular copper-pour on the second layer form the top, with 0.1mm clearance, and rank 1. Rank is an optional parameter that increases the priority of the pour - a higher-ranked pour fills before a lower ranked one.
• copper-pour(LayerIndex(1), isolate = 0.1, rank = 1, orphans = true) = ``Rectangle(5.0, 5.0) Similar to the previous command, but enable orphaned islands of copper to exist in the pour.

Place - how to place a component or module in JITX

In JITX, we can programmatically place components or modules on our board with a single line of code.

First, we specific place and the component that we want to place. Then we specify the location. Finally, we specifiy if we want to place it on the top or bottom.

Example placement

inst c : my-component
place(c) at loc(2.0, 3.0) on Top

loc

The loc statement is for placement in JITX. It creates an object describing translation and rotations that can be used to create goemetric constraints.

loc statements can be multiplied together (i.e. the transforms can be composed) and used to create trees of kinematic constraints.

pcb-landpatterns and pcb-modules have a right-handed coordinate system with origin at loc(0.0, 0.0, 0.0). Items you place in that coordinate frame will move together. e.g. you can move a land-pattern and all the pads stay in the same relative positions. You can place components in a module, and the relative positions of those components will remain fixed when you place the module.

Syntax

loc(1.0, 5.0)
loc(2.0, 3.0, 90.0)
loc(0.0, (- 3.0), (- 90.0)) on Bottom
loc(2.0, 3.0) on Top (relative-to proc)

pad p[0] : smd-pad(2.0, 1.0) at loc(0.0, 0.0, 90.0) * loc(2.0, 3.0)
pad p[1] : smd-pad(5.0, 1.0) at loc(2.0, 3.0) * loc(0.0, 0.0, 90.0)

inst c : my-component
place(c) at loc(2.0, 3.0) on Top

Description

• loc(1.0, 5.0) Create a pose of (x,y) = (1.0mm, 5.0mm)
• loc(2.0, 3.0, 90.0) Create a pose of (x,y, theta) = (1.0mm, 5.0mm, 90 degrees)
• loc(2.0, 3.0, (- 90.0)) on Top Create a pose of (x,y, theta) = (1.0mm, 5.0mm, -90 degrees), specifying that the component is on Top of the board.
• loc(0.0, (- 3.0), (- 90.0)) on Bottom Create a pose of (x,y, theta) = (0.0mm, -3.0mm, -90 degrees), specifying that the component is on the Bottom of the board.
• loc(2.0, 3.0) on Top (relative-to proc) Create a pose of (x,y) = (2.0mm, 3.0), defined from the origin of an instance named 'proc'. This is a relative constraint.

pad p[0] : smd-pad(2.0, 1.0) at loc(0.0, 0.0, 90.0) * loc(2.0, 3.0)
pad p[1] : smd-pad(5.0, 1.0) at loc(2.0, 3.0) * loc(0.0, 0.0, 90.0)

These statements create and place two pads at locations found by composing several poses together. The ordering of poses matters when you are composing them.

The pose loc(0.0, 0.0, 90.0) * loc(2.0, 3.0) first rotates the coordinate system by 90 degrees, and then translates it by (x,y) = (2.0mm, 3.0mm) in the new frame, so that the final pose is (x,y,theta) = (-3.0, 2.0, 90.0)

The pose loc(2.0, 3.0) * loc(0.0, 0.0, 90.0) first translates by (x,y) = (2.0mm, 3.0mm), then rotates the coordinate system by 90 degrees, so that the final pose is (x,y,theta) = (2.0, 3.0, 90.0). Here is the resulting pad geometry (origin of the land pattern is the blue cross):

  inst c : my-component
  place(c) at loc(2.0, 3.0) on Top

Via

via is a JITX statement for creating a via between layers of a circuit board.

Syntax

geom(my-net): 
    via(LayerIndex(0), LayerIndex(0, Bottom), 
        radius = 0.3, hole-radius = 0.125) 
        at Point(0.0, 0.0)

    via(LayerIndex(1), LayerIndex(2),
        radius = 0.3, hole-radius = 0.125,
        type = BlindVia) 
        at Point(1.0, 0.0) 

    via(LayerIndex(0), LayerIndex(1),
        radius = 0.1, hole-radius = 0.05,
        type = MicroVia) 
        at Point(2.0, 0.0) 

Description

    via(LayerIndex(0), LayerIndex(0, Bottom), 
        radius = 0.3, hole-radius = 0.125) 
        at Point(0.0, 0.0)

Create a through-via from the top to the bottom copper layer at (x,y) = (0,0), with an 0.3mm radius capture pad, and a 0.125mm drill radius. Through via is the default via type.

    via(LayerIndex(1), LayerIndex(2),
        radius = 0.3, hole-radius = 0.125,
        type = BlindVia) 
        at Point(1.0, 0.0) 

Create a blind/buried via from the 2nd to 3rd copper layer from the top at (x,y) = (1mm,0), with an 0.3mm radius capture pad, and a 0.125mm drill radius.

    via(LayerIndex(0), LayerIndex(1),
        radius = 0.1, hole-radius = 0.05,
        type = MicroVia) 
        at Point(2.0, 0.0) 

Create a micro via from the 1st to 2nd copper layer at (x,y) = (2.0mm, 0.0mm), with an 0.1mm radius capture pad, and a 0.05mm drill radius.

Land Patterns

A pcb-landpattern definition represents the geometry that attaches a component to a board. This is known alternately as a footprint, package, or land-pattern.

Here is an example definition for a 3-pin SOT23 pcb-landpattern:

pcb-landpattern SOT95P280X100-3N :
  
  val x0 = -0.95
  val y0 = -1.0
  pad p[1] : smd-pad(0.6, 0.7) at loc(x0,y0)
  pad p[2] : smd-pad(0.6, 0.7) at loc((- x0), y0)
  pad p[3] : smd-pad(0.6, 0.7) at loc(0.0, (- y0))

  layer(Courtyard(Top)) = Rectangle(3.3, 3.0)
  layer(Silkscreen("f-silk", Top)) = LineRectangle(3.3, 3.0)  
  ref-label()

Statements

Here is the list of all of the statements you can use in a pcb-landpattern :

Copper

copper is a JITX statement for creating a shape on a copper layer of our board.

Syntax

geom(my-net):
  copper(LayerIndex(0)) = Circle(0.0, 15.0, 1.0)
  copper(LayerIndex(1)) = Line(1.0, [Point(0.0, -5.0) Point(5.0, -5.0)]) 

Description

• copper(LayerIndex(0)) = Circle(0.0, 15.0, 1.0) Create a copper circle at (x,y) = (0,15mm) of radius 1mm. You can use any Shape with the copper statement.
• copper(LayerIndex(1)) = Line(1.0, [Point(0.0, -5.0) Point(5.0, -5.0)]) Create a 1mm wide copper line (results in a trace) on the 2nd copper layer from the top.

Description

description is the optional description field of a JITX object. Use it to store a description of the object for human designers reading JITX, and to make the object easier to find via text search.

Syntax

pcb-component analog-devices-ADM7150 :
  description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator"

pcb-module band-pass-filter :
  description = "Passive band-pass filter with cascaded highpass and low-pass stages."

Description

description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator" Add a description to call out special functions of the device.

name = "Band-pass filter" Add a description to signify the intent of a circuit.

External Names

external-names is an optional field in a pcb-landpattern to allow us to match the land pattern with parts found at component vendors.

Syntax

external-names = (["0402"])
external-names = (["0402" "0402-01005"])

Description

• external-names = (["0402"]) Indicate this land pattern matches "0402"-sized SMD components
• external-names = (["0402" "0402-01005"]) Indicate this land pattern matches "0402" and "0402-01005"-sized SMD components. Each additional string is another alias.

Layer

layer is used to create geometry on the manufacturing layers of a circuit board. Layers can be used inside pcb-landpattern, and pcb-module.

Syntax

layer(Courtyard(Top)) = Rectangle(3.0, 2.0)
layer(SolderMask(Top)) = Rectangle(anchor, w, h)
layer(Silkscreen("values", Top)) = Text(">REF", 1.0, a, loc(x,y))
layer(Silkscreen("f-silk", Top)) = LineRectangle(1.5, 3.0)
layer(Silkscreen("pol", Top)) = Circle(x0, y0, 0.254)

layer(ForbidCopper(LayerIndex(n)))
layer(ForbidCopper(LayerIndex(2,Bottom)))
layer(ForbidCopper(LayerIndex(0), LayerIndex(2)))
layer(ForbidCopper(LayerIndex(0), LayerIndex(0, Bottom)))

Description

• layer(Courtyard(Top)) = Rectangle(3.0, 2.0) Define a 3mmx2mm Rectangle on the top courtyard layer. This would define the bounds of an SMD land pattern.
• layer(SolderMask(Top)) = Rectangle(w, h) Define a w x h Rectangle on the top soldermask layer, as used to define soldermask for a pad.
• layer(Silkscreen("values", Top)) = Text(">REF", 1.0, a, loc(x,y)) Add 1mm high text saying ">REF" to the top silkscreen layer, anchored at a and located at (x,y). "values" is used to specify the intent of the text; all silkscreen on the top layer will get flattened to a single silkscreen layer in CAD export.
• layer(Silkscreen("f-silk", Top)) = LineRectangle(1.5, 3.0) Add a 1.5mmx3mm rectangular outline to the top silkscreen.
• layer(Silkscreen("pol", Top)) = Circle(x0, y0, 0.254) Add a circular polarity marker to the top silkscreen.

We can create geometry on the copper layers in our board using the LayerIndex function. For example, here's how to create a keepout:

• layer(ForbidCopper(LayerIndex(2))) Forbid Copper on third layer from top
• layer(ForbidCopper(LayerIndex(2,Bottom))) Forbid Copper on third layer from bottom
• layer(ForbidCopper(LayerIndex(0), LayerIndex(2))) Forbid Copper on top three layers
• layer(ForbidCopper(LayerIndex(0), LayerIndex(0, Bottom))) Forbid Copper on all layers

All layer specifiers

Name

name is the optional name field of an JITX object. Use it to store a descriptive name as a String for human designers reading JITX.

Syntax

pcb-component component :
  name = "ADM7150"

pcb-pad smd-pad (anchor:Anchor, w:Double, h:Double) :
  name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor])

pcb-module band-pass-filter :
  name = "Band-pass filter"

Description

name = "ADM7150" Name this component "ADM7150"

name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor]) Name this pad by constructing a name passed to a paramteric pad function

name = "Band-pass filter" Name this module "Band-pass filter"

Pad

pad is a JITX statement that defines a pad in a pcb-landpattern. A pad is a thing you can associate with a component pin.

Syntax

pad a : square-pad at loc(0.0, 0.0)
pad p[0] : smd-pad(0.5, 0.5) at loc(5.0, 0.0)

val prefix = Ref("RP")
pad (prefix)[4] : bga-pad(1.0) at loc(1.0, 0.0)

Description

pad a : square-pad at loc(0.0, 0.0) Create a pad named a of type square-pad and place it at (x,y) = (0.0, 0.0). loc is a pose object for defining pad locations.

pad p[0] : {smd-pad(0.5, 0.5)} at loc(5.0, 0.0) Create a pad named p[0] using the parameteric smd-pad function, and place it at (x,y) = (5.0, 0.0)

val prefix = Ref("RP")
pad (prefix)[4] : bga-pad(1.0) at loc(1.0, 0.0)

Define a custom prefix for your pad name, then use it to create a pad named RP[4] using the parameteric bga-pad function, and place it at (x,y) = (1.0, 0.0). The Ref function casts the String to a Ref object that can be used as a name in JITX. This strategy is used to generate names for BGA land pattern pads.

Via

via is a JITX statement for creating a via between layers of a circuit board.

Syntax

geom(my-net): 
    via(LayerIndex(0), LayerIndex(0, Bottom), 
        radius = 0.3, hole-radius = 0.125) 
        at Point(0.0, 0.0)

    via(LayerIndex(1), LayerIndex(2),
        radius = 0.3, hole-radius = 0.125,
        type = BlindVia) 
        at Point(1.0, 0.0) 

    via(LayerIndex(0), LayerIndex(1),
        radius = 0.1, hole-radius = 0.05,
        type = MicroVia) 
        at Point(2.0, 0.0) 

Description

    via(LayerIndex(0), LayerIndex(0, Bottom), 
        radius = 0.3, hole-radius = 0.125) 
        at Point(0.0, 0.0)

Create a through-via from the top to the bottom copper layer at (x,y) = (0,0), with an 0.3mm radius capture pad, and a 0.125mm drill radius. Through via is the default via type.

    via(LayerIndex(1), LayerIndex(2),
        radius = 0.3, hole-radius = 0.125,
        type = BlindVia) 
        at Point(1.0, 0.0) 

Create a blind/buried via from the 2nd to 3rd copper layer from the top at (x,y) = (1mm,0), with an 0.3mm radius capture pad, and a 0.125mm drill radius.

    via(LayerIndex(0), LayerIndex(1),
        radius = 0.1, hole-radius = 0.05,
        type = MicroVia) 
        at Point(2.0, 0.0) 

Create a micro via from the 1st to 2nd copper layer at (x,y) = (2.0mm, 0.0mm), with an 0.1mm radius capture pad, and a 0.05mm drill radius.

Reference Label

If you want to specify the location, size, orientation, etc. of the reference label of a component that appears on the silk screen, you can do that with ref-label.

The following are the available ref-label helper functions:

; Creates a reference label from pose and anchor
public defn ref-label (pose:Pose, anchor:Anchor)

; Creates a reference label at a fixed pose
public defn ref-label (pose:Pose)

; Create a default reference label
public defn ref-label ()

This allows you to control or change the reference indicator of a landpattern.

Example usage

Create a reference label at a default location:

pcb-landpattern SOT95P280X100-3N :
  
  val x0 = -0.95
  val y0 = -1.0
  pad p[1] : smd-pad(0.6, 0.7) at loc(x0,y0)
  pad p[2] : smd-pad(0.6, 0.7) at loc((- x0), y0)
  pad p[3] : smd-pad(0.6, 0.7) at loc(0.0, (- y0))

  layer(Courtyard(Top)) = Rectangle(3.3, 3.0)
  layer(Silkscreen("f-silk", Top)) = LineRectangle(3.3, 3.0)  
  ref-label() ; create a reference label

or create a reference label at a specific fixed pose (in this case 90 degrees rotated):

pcb-landpattern SOT95P280X100-3N :
  
  val x0 = -0.95
  val y0 = -1.0
  pad p[1] : smd-pad(0.6, 0.7) at loc(x0,y0)
  pad p[2] : smd-pad(0.6, 0.7) at loc((- x0), y0)
  pad p[3] : smd-pad(0.6, 0.7) at loc(0.0, (- y0))

  layer(Courtyard(Top)) = Rectangle(3.3, 3.0)
  layer(Silkscreen("f-silk", Top)) = LineRectangle(3.3, 3.0)  
  ref-label(loc(0.0, 0.0, 90.0))

model3d

model3d is a JITX statement that defines a 3D model associated with a pcb-landpattern definition.

Syntax

; inside pcb-landpattern :
model3d = Model3D(filename, position, scale, rotation) where :
  val filename = "my-3d-model.wrl"
  val position = Vec3D(0.0, 0.0, 0.0)
  val scale    = Vec3D(0.0, 0.0, 0.0)
  val rotation = Vec3D(0.0, 0.0, 0.0)

Description

The model3d statement associates a 3D model with a pcb-landpattern. Models may be .stp, .step, or .wrl files. The arguments to Model3D are the name of the 3D model file, and 3D vectors for position/translation, scale, and rotation.

The filename argument may be a relative or absolute path. If it is relative, the resolved path will be relative to the directory of the source file that contains the statement.

For example :

  ;in project/landpatterns/landpattern.stanza 
  ;...
  model3d = Model3D("../3DModels/model.step")

The resolved path will be project/3DModels/model.step.

During import, imported model files are placed in the imported design directory under <imported-design>/3d-models and model3d statements are generated automatically.

Materials

A pcb-material definition represents a material in a pcb-stackup layer.

Syntax

pcb-material material-identifier : 
  name:        String 
  description: String 
  type:        Conductor|Dielectric
  dielectric-constant : Double

Description

The name field is an optional name associated with the material that is different from its identifier.

The description field is an optional string describing the material.

The type is either Conductor or Dielectric, representing what kind of material this represents.

The dielectric-coefficient is an optional double value representing the permittivity of the material.

Name

name is the optional name field of an JITX object. Use it to store a descriptive name as a String for human designers reading JITX.

Syntax

pcb-component component :
  name = "ADM7150"

pcb-pad smd-pad (anchor:Anchor, w:Double, h:Double) :
  name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor])

pcb-module band-pass-filter :
  name = "Band-pass filter"

Description

name = "ADM7150" Name this component "ADM7150"

name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor]) Name this pad by constructing a name passed to a paramteric pad function

name = "Band-pass filter" Name this module "Band-pass filter"

Description

description is the optional description field of a JITX object. Use it to store a description of the object for human designers reading JITX, and to make the object easier to find via text search.

Syntax

pcb-component analog-devices-ADM7150 :
  description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator"

pcb-module band-pass-filter :
  description = "Passive band-pass filter with cascaded highpass and low-pass stages."

Description

description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator" Add a description to call out special functions of the device.

name = "Band-pass filter" Add a description to signify the intent of a circuit.

Module Level Statements

A pcb-module definition represents a group of instances, their statuses, their nets, and layers or geoms in a design. Modules form the hierarchy of your design and can be instantiated, placed, and connected via nets.

Syntax

pcb-module my-module :
  port power : ocdb/bundles/power

  inst mcu        : components/manu/CoolCPU-123
  inst peripheral : components/manu/Awesome-Peripheral-456
  inst fuse       : components/manu/broken-fuse
  inst jumper     : components/manu/normal-jumper
  inst dnp-me     : components/manu/normal-jumper 

  component-status(fuse) :
    bom-status = NotInBOM
  component-status(jumper) :
    board-status = NoOnBoard
  do-not-populate(dnp-me)

  require spi-control  : spi-controller() from mcu
  require spi-periph   : spy-peripheral() from peripheral
  require mcu-power    : power from mcu
  require periph-power : power from peripheral 

  net (spi-control.copi, spi-periph.sdi)
  net (spi-control.cipo, spi-periph.sdo)
  
  net (power, mcu-power, periph-power)

  schematic-group(self) = CoolModule

Statements

Here is the list of all of the statements you can use in a pcb-module :

Description

description is the optional description field of a JITX object. Use it to store a description of the object for human designers reading JITX, and to make the object easier to find via text search.

Syntax

pcb-component analog-devices-ADM7150 :
  description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator"

pcb-module band-pass-filter :
  description = "Passive band-pass filter with cascaded highpass and low-pass stages."

Description

description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator" Add a description to call out special functions of the device.

name = "Band-pass filter" Add a description to signify the intent of a circuit.

Geom

geom is used to create custom copper geometry (copper shapes, pours, and vias) and associate it with a net.

Syntax

  geom(mynet) :
    via(LayerIndex(0), LayerIndex(1),
        radius = 0.1, hole-radius = 0.05) at Point(0.0, 0.0)
    copper(LayerIndex(1)) = Rectangle(5.0, 5.0)    

Description

geom(mynet) : Creates a geom environment inside of which you can add copper, copper-pour, and via statements and associate the geometry with mynet.

Instance

inst is how we add modules and components to modules.

Syntax

pcb-module my-module:
  inst my-inst : my-component
  inst my-inst-array : my-component[10]

  for i in 0 to 10 do :
    inst r : chip-resistor(1.0e3)

  inst my-module-inst : my-module

Description

inst my-inst : my-component Add an instance named my-inst of type my-component to this module.

inst my-inst-array : my-component[10] Add an instance array named my-inst-array of type my-component to this module. This creates ten instances of my-component with names my-inst-array[0] through my-inst-array[9]

  for i in 0 to 10 do :
    inst r : chip-resistor(1.0e3)

Add a instance named r of type chip-resistor(1.0e3) inside a for loop. If we needed to refer to r to connect to its ports, we could only do so inside this loop.

inst my-module-inst : my-module Modules can be instantiated just like components. We can nest modules as deeply as we like.

Layer

layer is used to create geometry on the manufacturing layers of a circuit board. Layers can be used inside pcb-landpattern, and pcb-module.

Syntax

layer(Courtyard(Top)) = Rectangle(3.0, 2.0)
layer(SolderMask(Top)) = Rectangle(anchor, w, h)
layer(Silkscreen("values", Top)) = Text(">REF", 1.0, a, loc(x,y))
layer(Silkscreen("f-silk", Top)) = LineRectangle(1.5, 3.0)
layer(Silkscreen("pol", Top)) = Circle(x0, y0, 0.254)

layer(ForbidCopper(LayerIndex(n)))
layer(ForbidCopper(LayerIndex(2,Bottom)))
layer(ForbidCopper(LayerIndex(0), LayerIndex(2)))
layer(ForbidCopper(LayerIndex(0), LayerIndex(0, Bottom)))

Description

• layer(Courtyard(Top)) = Rectangle(3.0, 2.0) Define a 3mmx2mm Rectangle on the top courtyard layer. This would define the bounds of an SMD land pattern.
• layer(SolderMask(Top)) = Rectangle(w, h) Define a w x h Rectangle on the top soldermask layer, as used to define soldermask for a pad.
• layer(Silkscreen("values", Top)) = Text(">REF", 1.0, a, loc(x,y)) Add 1mm high text saying ">REF" to the top silkscreen layer, anchored at a and located at (x,y). "values" is used to specify the intent of the text; all silkscreen on the top layer will get flattened to a single silkscreen layer in CAD export.
• layer(Silkscreen("f-silk", Top)) = LineRectangle(1.5, 3.0) Add a 1.5mmx3mm rectangular outline to the top silkscreen.
• layer(Silkscreen("pol", Top)) = Circle(x0, y0, 0.254) Add a circular polarity marker to the top silkscreen.

We can create geometry on the copper layers in our board using the LayerIndex function. For example, here's how to create a keepout:

• layer(ForbidCopper(LayerIndex(2))) Forbid Copper on third layer from top
• layer(ForbidCopper(LayerIndex(2,Bottom))) Forbid Copper on third layer from bottom
• layer(ForbidCopper(LayerIndex(0), LayerIndex(2))) Forbid Copper on top three layers
• layer(ForbidCopper(LayerIndex(0), LayerIndex(0, Bottom))) Forbid Copper on all layers

All layer specifiers

Component Status

component-status and do-not-populate are optional statements to modify the on-board and BOM statuses of components.

Syntax

pcb-module my-module:
  inst fuse       : components/manu/broken-fuse
  inst jumper-a   : components/manu/normal-jumper
  inst jumper-b   : components/manu/normal-jumper
  inst jumper-c   : components/manu/normal-jumper
  inst dnp-me     : components/manu/normal-jumper 

  component-status(fuse) :
    bom-status = NotInBOM
  component-status(jumper-a) :
    board-status = NoOnBoard
  component-status(jumper-b) :
    bom-status = MarkedDNP
    board-status = OnBoard
  do-not-populate(dnp-me)

Description

component-status(instance-name) : Tells which component inst is affected by the sub-statement(s) below.

Possible sub-statements:

• bom-status = InBOM|NotInBOM|MarkedDNP|InBOMVariant. InBOM is the default when bom-status is missing.
• board-status = OnBoard|NotOnBoard|InBoardVariant. OnBoardBOM is the default when board-status is missing.

do-not-populate(instance-name) Mark a component instance as a DNP component. This is equivalent to bom-status = MarkedDNP using component-status(instance-name). do-not-populate always supersedes component-status no matter where they are in the code.

In this example, fuse is [NoInBOM, OnBoard] jumper-a is [InBOM NoOnBoard], jumper-b is [MarkedDNP OnBoard], and jumper-c is [InBOM OnBoard]. dnp-me is [MarkedDNP OnBoard]

There are 2 commands to query the component status of a component instance. do-not-populate?(instance-name) and component-status?(instance-name)

do-not-populate?(instance-name) will return True|False. component-status?(instance-name) will return a Tuple of ComponentBOMStatus and ComponentBoardStatus. for example, [InBOM NotOnBoard]

Component Status

component-status and do-not-populate are optional statements to modify the on-board and BOM statuses of components.

Syntax

pcb-module my-module:
  inst fuse       : components/manu/broken-fuse
  inst jumper-a   : components/manu/normal-jumper
  inst jumper-b   : components/manu/normal-jumper
  inst jumper-c   : components/manu/normal-jumper
  inst dnp-me     : components/manu/normal-jumper 

  component-status(fuse) :
    bom-status = NotInBOM
  component-status(jumper-a) :
    board-status = NoOnBoard
  component-status(jumper-b) :
    bom-status = MarkedDNP
    board-status = OnBoard
  do-not-populate(dnp-me)

Description

component-status(instance-name) : Tells which component inst is affected by the sub-statement(s) below.

Possible sub-statements:

• bom-status = InBOM|NotInBOM|MarkedDNP|InBOMVariant. InBOM is the default when bom-status is missing.
• board-status = OnBoard|NotOnBoard|InBoardVariant. OnBoardBOM is the default when board-status is missing.

do-not-populate(instance-name) Mark a component instance as a DNP component. This is equivalent to bom-status = MarkedDNP using component-status(instance-name). do-not-populate always supersedes component-status no matter where they are in the code.

In this example, fuse is [NoInBOM, OnBoard] jumper-a is [InBOM NoOnBoard], jumper-b is [MarkedDNP OnBoard], and jumper-c is [InBOM OnBoard]. dnp-me is [MarkedDNP OnBoard]

There are 2 commands to query the component status of a component instance. do-not-populate?(instance-name) and component-status?(instance-name)

do-not-populate?(instance-name) will return True|False. component-status?(instance-name) will return a Tuple of ComponentBOMStatus and ComponentBoardStatus. for example, [InBOM NotOnBoard]

Layout Group

layout-group is used to control the placer in JITX, which arranges our components automatically on our board. The placer will try to place components in a layout group close to each other (with a controllable weighting), and optionally will arrange the layout groups off to the side of the board to make manual placement easier.

Syntax

pcb-module reg
  layout-group(self) = reg

pcb-module my-module
  layout-group(my-inst) = power
  layout-group(my-other-inst) = test
  layout-group([test-points measure]) = test
  layout-group(load) = layout-group(my-inst)

Description

pcb-module reg :
  layout-group(self) = reg

This statement will apply a layout group to all of the components that are instantiated inside the module reg. Multiple instances of reg will be grouped individually.

layout-group(my-inst) = power Set the layout-group of my-inst to be power.

layout-group(my-other-inst) = test Set the layout-group of my-other-inst to be test.

layout-group([test-points measure]) = test Set the layout-group of test-points and measure to also be test.

layout-group(load) = layout-group(my-inst) Set the layout-group of load to be the same as the layout-group of my-inst.

Name

name is the optional name field of an JITX object. Use it to store a descriptive name as a String for human designers reading JITX.

Syntax

pcb-component component :
  name = "ADM7150"

pcb-pad smd-pad (anchor:Anchor, w:Double, h:Double) :
  name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor])

pcb-module band-pass-filter :
  name = "Band-pass filter"

Description

name = "ADM7150" Name this component "ADM7150"

name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor]) Name this pad by constructing a name passed to a paramteric pad function

name = "Band-pass filter" Name this module "Band-pass filter"

Net

We use net statements to make electrical connections inside modules. Nets can connect both individual pins and entire bundles. Optionally, nets can be assigned names.

Syntax

pcb-module my-module :

  net (a-inst.p b-inst.p)

  net GND (my-inst.gnd)
  net (GND power-inst.gnd)

  net (a-inst.i2c b-inst.i2c)

  net SYS-BUS:can[10]
  for i in 0 to 10 do :
    net (my-inst[i].can SYS-BUS[i])

Description

net (a-inst.p b-inst.p) Electrically connect the p pin of a-inst to the p pin of b-inst.

net GND (my-inst.gnd)
net (GND power-inst.gnd)

Create a net named GND that has the pin my-inst.gnd.

net (a-inst.i2c b-inst.i2c) Connect an i2c bundle from a-inst to an i2c bundle from b-inst. Only identical bundles can be connected with a net statement. When they are connected, each pin of one bundle will be wired to the identically named pin on the other bundle.

net SYS-BUS:can[10]
for i in 0 to 10 do :
  net (my-inst[i].can SYS-BUS[i])

If we want to name a collection of nets, create the named nets first and then connect to them later in the design.

Node

node creates an artificial electrical attachment point.

Syntax

pcb-module my-module :
  node a:pin
  node b:pin[10]

Description

node a:pin Create a node named a that is one pin.

node b:pin[10] Create a node named b that is of type pin[10]. You can create nodes of any bundle/bundle array type, similar to a port.

Place - how to place a component or module in JITX

In JITX, we can programmatically place components or modules on our board with a single line of code.

First, we specific place and the component that we want to place. Then we specify the location. Finally, we specifiy if we want to place it on the top or bottom.

Example placement

inst c : my-component
place(c) at loc(2.0, 3.0) on Top

loc

The loc statement is for placement in JITX. It creates an object describing translation and rotations that can be used to create goemetric constraints.

loc statements can be multiplied together (i.e. the transforms can be composed) and used to create trees of kinematic constraints.

pcb-landpatterns and pcb-modules have a right-handed coordinate system with origin at loc(0.0, 0.0, 0.0). Items you place in that coordinate frame will move together. e.g. you can move a land-pattern and all the pads stay in the same relative positions. You can place components in a module, and the relative positions of those components will remain fixed when you place the module.

Syntax

loc(1.0, 5.0)
loc(2.0, 3.0, 90.0)
loc(0.0, (- 3.0), (- 90.0)) on Bottom
loc(2.0, 3.0) on Top (relative-to proc)

pad p[0] : smd-pad(2.0, 1.0) at loc(0.0, 0.0, 90.0) * loc(2.0, 3.0)
pad p[1] : smd-pad(5.0, 1.0) at loc(2.0, 3.0) * loc(0.0, 0.0, 90.0)

inst c : my-component
place(c) at loc(2.0, 3.0) on Top

Description

• loc(1.0, 5.0) Create a pose of (x,y) = (1.0mm, 5.0mm)
• loc(2.0, 3.0, 90.0) Create a pose of (x,y, theta) = (1.0mm, 5.0mm, 90 degrees)
• loc(2.0, 3.0, (- 90.0)) on Top Create a pose of (x,y, theta) = (1.0mm, 5.0mm, -90 degrees), specifying that the component is on Top of the board.
• loc(0.0, (- 3.0), (- 90.0)) on Bottom Create a pose of (x,y, theta) = (0.0mm, -3.0mm, -90 degrees), specifying that the component is on the Bottom of the board.
• loc(2.0, 3.0) on Top (relative-to proc) Create a pose of (x,y) = (2.0mm, 3.0), defined from the origin of an instance named 'proc'. This is a relative constraint.

pad p[0] : smd-pad(2.0, 1.0) at loc(0.0, 0.0, 90.0) * loc(2.0, 3.0)
pad p[1] : smd-pad(5.0, 1.0) at loc(2.0, 3.0) * loc(0.0, 0.0, 90.0)

These statements create and place two pads at locations found by composing several poses together. The ordering of poses matters when you are composing them.

The pose loc(0.0, 0.0, 90.0) * loc(2.0, 3.0) first rotates the coordinate system by 90 degrees, and then translates it by (x,y) = (2.0mm, 3.0mm) in the new frame, so that the final pose is (x,y,theta) = (-3.0, 2.0, 90.0)

The pose loc(2.0, 3.0) * loc(0.0, 0.0, 90.0) first translates by (x,y) = (2.0mm, 3.0mm), then rotates the coordinate system by 90 degrees, so that the final pose is (x,y,theta) = (2.0, 3.0, 90.0). Here is the resulting pad geometry (origin of the land pattern is the blue cross):

  inst c : my-component
  place(c) at loc(2.0, 3.0) on Top

Ports

port is a JITX statement that defines pins on components and modules that you can net to.

Syntax

port a : pin
pin a

port b : pin[6]
port c : pin[[1, 2, 4 through 6]]

port data : i2c
port lots-of-data : i2c[30]

Description

port a : pin Create a port with a single pin named a

pin a Create a port with a single pin named a (same as above, but more convenient syntax.)

port b : pin[4] Create a port named b with 4 pins named b[0] through b[3]. You can loop over these pins programmatically:

for i in indices(b) do:
  net (b[i])
  println(i)

Prints out:

0
1
2
3

port c : pin[[1, 2, 4 through 6]] Create a port named c with a non-standard range. c has 4 pins named c[1] c[2] c[4] c[5] and c[6]. You can loop over these pins programmatically:

for i in indices(c) do:
  net (c[i])
  println(i)

Prints out:

1
2
4
5
6

port data : i2c Create a port named data of the pcb-bundle named i2c.

port lots-of-data : i2c[30] Create a port array with 30 I2C ports. lots-of-data[0].sda is the sda pin of the first I2C bundle.

Properties

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

Syntax

  import jitx
  import ocdb/utils/property-structs

pcb-component mycomponent :
  pin a
  pin b

  property(a.leakage-current) = 50.0e-6
  has-property?(a.leakage-current) ; returns true
  property(a.leakage-current) ; returns 50.0e-6

  property(b.power-pin) = PowerPin(min-typ-max(4.5, 5.5, 5.0))

  property(self.rated-temperature) = min-max(-55.0 125.0)

pcb-module my-module :
  port i2c : i2c
  inst comp : my-component

  net SDA (i2c.sda comp.a)
  net VDD (i2c.sda comp.b)

  property(comp.rated-temperature) ; returns min-max(-55.0 125.0)
  property(comp.a.leakage-current) ; returns 50.0e-6

  property(comp.no-clean) = false
  has-property?(comp.no-clean) ; returns true
  property(comp.no-clean) ; returns false

  property(VDD.voltage) = min-max(3.0, 3.5)

Description

Component property statements

property(a.leakage-current) = 50.0e-6 Create a property on pin a with name leakage-current and value 50.0e-6.

has-property?(a.leakage-current) Check if pin a has a property named leakage-current.

property(a.leakage-current) Get the value of the property on pin a named leakage-current.

property(b.power-pin) = PowerPin(min-typ-max(4.5, 5.5, 5.0)) Create a property on pin b with name power-pin and value of a pcb-struct from ocdb/utils/property-structs.

property(self.rated-temperature) = min-max(-55.0 125.0) Create a property on the component with name rated-temperature and value of a pcb-struct from ocdb/utils/property-structs.

Module property statements

property(comp.rated-temperature) Get the value of the property named rated-temperature on the instance of comp : my-component.

property(comp.a.leakage-current) Get the value of the property named leakage-current on pin a of the instance of comp : my-component.

property(comp.no-clean) = false Create a property named no-clean on the instance of comp : my-component, and give it the value false.

has-property?(comp.no-clean) Check if a property named no-clean on the instance of comp : my-component exists.

property(comp.no-clean) Get the value of a property named no-clean on the instance of comp : my-component.

property(VDD.voltage) = min-max(3.0, 3.5) Create a property named voltage on the net VDD, and give it the value min-max(3.0, 3.5).

Reference designator

reference-designator can be used to hardcode the reference designator of a component in a module

Syntax

pcb-module my-module :
  
  reference-designator(my-inst) = "R4"

Description

reference-designator(my-inst) = "R4" Set the reference designator of my-inst to by "R4"

Require

require can be used in coordination with supports statements to automate pin assignment. When we use a require statement it creates a bundle which we can use like it already exists and the concrete pins it maps to are determined later.

Syntax

The general form of a require statement is:

require name-of-bundle:bundle-type from supporting-inst

pcb-module my-module :
  
  inst stm32 : stm32f405G7
  require data:i2c from stm32
  require lots-of-data:i2c[10] from stm32

  port p : pin[10]

  pcb-bundle io-pin :
    pin p

  for i in pins(p) do :
    supports io-pin:
      io-pin.p => i

  require dummy:io-pin[4] from self


pcb-component my-component :
  port p : pin[10]

  pcb-bundle io-pin :
    pin p

  for i in pins(p) do :
    supports io-pin:
      io-pin.p => i

  require dummy:io-pin[4]

  supports i2c :
    require sda-pin:io-pin
    require scl-pin:io-pin
    i2c.sda => sda-pin.p
    i2c.scl => scl-pin.p

Description

pcb-module my-module :
  
  inst stm32 : stm32f405G7
  require data:i2c from stm32
  require lots-of-data:i2c[10] from stm32

require data:i2c from stm32 Create a bundle named data of type i2c and specify that it needs to come from the stm32 instance. We can now use data in other code like net statements.

require lots-of-data:i2c[10] from stm32 Create a bundle array named lots-of-data of type i2c[10] and specify that it needs to come from the stm32 instance.

We can use require amd supports inside a module to use pin assignment more flexible (e.g. allow pin swaps for routability for any set of bundles or pins). Here we define a dummy bundle io-pin, add supports for it in the context of the current module, and can then use require dummy:io-pin[4] from self to access those supports.

  port p : pin[10]

  pcb-bundle io-pin :
    pin p

  for i in pins(p) do :
    supports io-pin:
      io-pin.p => i

  require dummy:io-pin[4] from self

Similarly we can use require inside a component definition, and we leave off the from because it can only be from the component itself:

pcb-component my-component :
  port p : pin[10]

  pcb-bundle io-pin :
    pin p

  for i in pins(p) do :
    supports io-pin:
      io-pin.p => i

  require dummy:io-pin[4]

And this can be used to simplify supports for bundles that can be supported on many possible pins. e.g. when a processor or FPGA has a full cross bar for all of its digital interfaces, and i2c could appear on any of the pins, we can capture that full flexibility with a require inside a supports statement:

  supports i2c :
    require sda-pin:io-pin
    require scl-pin:io-pin
    i2c.sda => sda-pin.p
    i2c.scl => scl-pin.p

We require two io-pin dummy pins (which can map to any component pin), and then map the i2c pins sda and scl to those pins. Now i2c can be mapped to any pin on the component.

Restrict

restrict can be used in coordination with require to add specific constraints on which pins are valid. We can specify all pins in a bundle to come from a specific IO bank, or that a timer has some advanced feature, or has a specific electrical property.

Notes:

• The restrict syntax is purposefully verbose.
• All pins that could be mapped to the restricted bundle pin must have the pin property.

Syntax

The general form of a restrict statement is:

  require <pin>:<bundle>
  restrict(<pin of required bundle>,
    ;Inlining a function.
    ;mypin is the name of the function parameter. It can be named anything.
    fn (mypin) :
      ;A restriction based on a pin property.
      ;This restrict statement ensures that the assigned pin will pin-property > 10.0.
      property(mypin.<pin-property>) > 10.0)

pcb-module restrict-one-pin :
  pin p
  property(p.active) = true

  supports gpio :
    gpio.gpio => p
  
  require g:gpio from self
  restrict(g.gpio,
    fn (mypin) :
      property(mypin.active))

pcb-module restrict-in-option :
  pin p
  pin q

  property(p.active) = true
  property(q.active) = false

  pcb-bundle bund1 :
    pin p

  pcb-bundle bund2 :
    pin x
    pin y

  supports bund2 :
    bund2.x => p
    bund2.y => q

  supports bund1 :
    require my2:bund2 from self
    restrict(my2.x,
      fn (mypin) :
        property(mypin.active))
    bund1.p => my2.x
  
  ;If p and q are swapped above, the pin solver cannot find a solution.
  require my1:bund1 from self

Description

This module supports a gpio, and requires a gpio with a restriction that the pin is active based on the property active.

pcb-module restrict-one-pin :
  pin p
  property(p.active) = true

  supports gpio :
    gpio.gpio => p
  
  require g:gpio from self
  restrict(g.gpio,
    fn (mypin) :
      property(mypin.active))

Restrictions can also be applied on required pins in a support statement. This module supports bund1 and bund2 bundles. bund1 requires a bund2 with the restriction that x pin is active. When bund1 is required, the solver can find a solution. If q was active instead of p, no solution would be found.

pcb-module restrict-in-option :
  pin p
  pin q

  property(p.active) = true
  property(q.active) = false

  pcb-bundle bund1 :
    pin p

  pcb-bundle bund2 :
    pin x
    pin y

  supports bund2 :
    bund2.x => p
    bund2.y => q

  supports bund1 :
    require my2:bund2 from self
    restrict(my2.x,
      fn (mypin) :
        property(mypin.active))
    bund1.p => my2.x
  
  ;If p and q are swapped above, the pin solver cannot find a solution.
  require my1:bund1 from self

Schematic Group

schematic-group is used to control the organization of our schematic in JITX. The schematic layout engine is allowed to route wires between all of the symbols in a single schematic-group. Wires going between schematic-groups will be broken and have net labels added. The top-level schematic group gets a dotted box drawn around it.

Syntax

pcb-module reg
  schematic-group(self) = reg

pcb-module my-module
  schematic-group(my-inst) = power
  schematic-group(my-other-inst) = test
  schematic-group([test-points measure]) = test
  schematic-group(load) = schematic-group(my-inst)

Description

pcb-module reg :
  schematic-group(self) = reg

This statement will apply a schematic group to all of the components that are instantiated inside the module reg. Multiple instances of reg will be grouped individually.

schematic-group(my-inst) = power Set the schematic-group of my-inst to be power.

schematic-group(my-other-inst) = test Set the schematic-group of my-other-inst to be test.

schematic-group([test-points measure]) = test Set the schematic-group of test-points and measure to also be test.

schematic-group(load) = schematic-group(my-inst) Set the schematic-group of load to be the same as the schematic-group of my-inst.

Short Trace

short-trace gives hints to the placer to keep two pads on different components close together (like a bypass capacitor close to its associated pin). The pads must be on the same net.

Syntax

pcb-module my-module:
  net (inst-a.p inst-b.p)
  short-trace(inst-a.p inst-b.p)

Description

short-trace(inst-a.p inst-b.p) Keep the p pin of inst-a close to the p pin of 'inst-b' in the layout.

Supports

Support statements are used as part of the pin assignment solver. We use supports to describe valid ways pins could be assigned.

Often supports are used to describe pin mappings on a processor (e.g. this i2c IP can have pins here or here). The support mechanism is very flexible and can be used more generally.

Syntax

The general syntax supports a pcb-bundle on a set of pins:

supports my-bundle:
  bundle.pin-1 => supporting-pin-1
  bundle.pin-2 => supporting-pin-2
  bundle.pin-3 => supporting-pin-3
  ...

We can later tap this support using a require statement like require something:my-bundle from supporting-inst.

More examples:

import ocdb/utils/bundles

pcb-component my-component :
  port sys : i2c
  port PA : pin[10]

  supports i2c :
    i2c.sda => sys.sda
    i2c.scl => sys.scl

  supports gpio :
    gpio.gpio => PA[0]

  supports gpio :
    option :
      gpio.gpio => PA[1]
    option :
      gpio.gpio => PA[4]

  pcb-bundle io-pin : (pin p)
  for i in 5 to 10 do:
    supports io-pin :
      io-pin.p => PA[i]

  supports uart([UART-DTR UART-RX UART-TX]) :
    require pins:io-pin[3]
    uart([UART-DTR UART-RX UART-TX]).tx => pins[0].p
    uart([UART-DTR UART-RX UART-TX]).rx => pins[1].p
    uart([UART-DTR UART-RX UART-TX]).dtr => pins[2].p

pcb-module my-module :
  inst c : my-component

  supports i2c : 
    i2c.sda => c.PA[2]
    i2c.scl => c.PA[3]

Description

  supports i2c :
    i2c.sda => sys.sda
    i2c.scl => sys.scl

This component supports i2c on the port named sys that is also of type i2c.

  supports gpio :
    gpio.gpio => PA[0]
    property(PA[0].is-gpio?) = true

Pin PA[0] of this component supports a gpio bundle. A property is-gpio? is set on this pin only if this support statement is trigged. i.e. if PA[0] is used as a gpio by the pin solver, then the property is-gpio? is set, but not otherwise.

  supports gpio :
    option :
      gpio.gpio => PA[1]
    option :
      gpio.gpio => PA[4]

Another gpio bundle is supported on pin PA[1] or PA[4], but not both.

  pcb-bundle io-pin : (pin p)
  for i in 5 to 10 do:
    supports io-pin :
      io-pin.p => PA[i]

  supports uart([UART-DTR UART-RX UART-TX]) :
    require pins:io-pin[3]
    uart([UART-DTR UART-RX UART-TX]).tx => pins[0].p
    uart([UART-DTR UART-RX UART-TX]).rx => pins[1].p
    uart([UART-DTR UART-RX UART-TX]).dtr => pins[2].p

Pins are often arbitrarily mappable, i.e. here any pin in PA[5 to 10] can support any pin of a uart interface with pins tx rx and dtr. We create a dummy bundle io-pin to support the flexibility of the mapping. Inside the supports statement for uart, we can require the three io-pin pins we need for the interface and then map them to our uart pins. The full space of possible pin assignments is captured and a valid solution will be found by the solver if any solution is possible.

pcb-module my-module :
  inst c : my-component

  supports i2c : 
    i2c.sda => c.PA[2]
    i2c.scl => c.PA[3]

Support statements can be associated with an instance's ports outside of that instance. Here we map an i2c bus to the pins of c at the module level.

Symbol

symbol(my-net) = my-symbol allows to specify a single-pin symbol my-symbol to attach to a net my-net. This symbol will act as a global label, that is to say that all nets bearing this symbol will be electrically connected. The main use-case is power symbols.

Syntax

pcb-module my-design :
  pin gnd
  pin vcc
  inst C1 : gen-cap-cmp(0.1e-6)
  inst C2 : gen-cap-cmp(0.1e-6)
  net gnd (C1.p[1], C2.p[1])
  net vcc (C1.p[2], C2.p[2])
  symbol(gnd) = ground-sym
  symbol(vcc) = supply-sym

Description

Importing the ocdb/utils/symbols package from the open-components-database repository, the ground earth symbol ground-sym and supply symbol supply-sym can be attached to nets gnd and vcc in this example.

Component Status

component-status and do-not-populate are optional statements to modify the on-board and BOM statuses of components.

Syntax

pcb-module my-module:
  pin gnd
  pin power
  pin signal

  inst fuse       : components/manu/broken-fuse
  inst jumper-a   : components/manu/normal-jumper
  inst jumper-b   : components/manu/normal-jumper
  inst jumper-c   : components/manu/normal-jumper
  inst dnp-me     : components/manu/normal-jumper
  val r = res-strap(signal, gnd, 10.0e3)

  property(power.voltage) = Stateful(["low" => 1.8, "medium" => 3.3, "high" => 5.0])
  state(power.voltage) = "low"

  variant "DNP" :
    do-not-populate(dnp-me)
    do-not-populate(r)

  variant "High Resistance" :
    property(r.rid.resistance) = 10.0e6

  variant "High Power" :
    state(power.voltage) = "high"

  variant "Medium Power" :
    state(power.voltage) = "medium" 
  
  variant "TOUGH Fuse" :
    property(fuse.rated-temperature) = min-typ-max(-50, 120, 150)

Description

variant "variant name" : Specifies a Variant that may alter the inst in this module. Its application is determined by a command apply-variants later in top level.

Possible sub-statements:

• do-not-populate, property, component-status, value-label.

For example, if later on, a top level command val new-module = apply-variants(["DNP" "High Power"] my-module) is executed, the inst dnp-me will become do-not-populate and power pin will have 5V in new-module.

Pads

A pcb-pad definition represents a single lead found on a pcb-landpattern.

Syntax

pcb-pad my-pad :
  type  = SMD ; or TH
  shape = Rectangle(1.0, 0.5)
  layer(SolderMask(Top)) = Rectangle(1.25, 0.75)

Statements

Name

name is the optional name field of an JITX object. Use it to store a descriptive name as a String for human designers reading JITX.

Syntax

pcb-component component :
  name = "ADM7150"

pcb-pad smd-pad (anchor:Anchor, w:Double, h:Double) :
  name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor])

pcb-module band-pass-filter :
  name = "Band-pass filter"

Description

name = "ADM7150" Name this component "ADM7150"

name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor]) Name this pad by constructing a name passed to a paramteric pad function

name = "Band-pass filter" Name this module "Band-pass filter"

Description

description is the optional description field of a JITX object. Use it to store a description of the object for human designers reading JITX, and to make the object easier to find via text search.

Syntax

pcb-component analog-devices-ADM7150 :
  description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator"

pcb-module band-pass-filter :
  description = "Passive band-pass filter with cascaded highpass and low-pass stages."

Description

description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator" Add a description to call out special functions of the device.

name = "Band-pass filter" Add a description to signify the intent of a circuit.

Layer

layer is used to create geometry on the manufacturing layers of a circuit board. Layers can be used inside pcb-landpattern, and pcb-module.

Syntax

layer(Courtyard(Top)) = Rectangle(3.0, 2.0)
layer(SolderMask(Top)) = Rectangle(anchor, w, h)
layer(Silkscreen("values", Top)) = Text(">REF", 1.0, a, loc(x,y))
layer(Silkscreen("f-silk", Top)) = LineRectangle(1.5, 3.0)
layer(Silkscreen("pol", Top)) = Circle(x0, y0, 0.254)

layer(ForbidCopper(LayerIndex(n)))
layer(ForbidCopper(LayerIndex(2,Bottom)))
layer(ForbidCopper(LayerIndex(0), LayerIndex(2)))
layer(ForbidCopper(LayerIndex(0), LayerIndex(0, Bottom)))

Description

• layer(Courtyard(Top)) = Rectangle(3.0, 2.0) Define a 3mmx2mm Rectangle on the top courtyard layer. This would define the bounds of an SMD land pattern.
• layer(SolderMask(Top)) = Rectangle(w, h) Define a w x h Rectangle on the top soldermask layer, as used to define soldermask for a pad.
• layer(Silkscreen("values", Top)) = Text(">REF", 1.0, a, loc(x,y)) Add 1mm high text saying ">REF" to the top silkscreen layer, anchored at a and located at (x,y). "values" is used to specify the intent of the text; all silkscreen on the top layer will get flattened to a single silkscreen layer in CAD export.
• layer(Silkscreen("f-silk", Top)) = LineRectangle(1.5, 3.0) Add a 1.5mmx3mm rectangular outline to the top silkscreen.
• layer(Silkscreen("pol", Top)) = Circle(x0, y0, 0.254) Add a circular polarity marker to the top silkscreen.

We can create geometry on the copper layers in our board using the LayerIndex function. For example, here's how to create a keepout:

• layer(ForbidCopper(LayerIndex(2))) Forbid Copper on third layer from top
• layer(ForbidCopper(LayerIndex(2,Bottom))) Forbid Copper on third layer from bottom
• layer(ForbidCopper(LayerIndex(0), LayerIndex(2))) Forbid Copper on top three layers
• layer(ForbidCopper(LayerIndex(0), LayerIndex(0, Bottom))) Forbid Copper on all layers

All layer specifiers

Rules

A pcb-rules definition represents the set of design rules associated with a specific circuit board manufacturer.

Syntax

pcb-rules bay-area-circuits-std-rules :
  min-copper-width = 0.127
  min-copper-copper-space = 0.127 
  min-copper-hole-space = 0.2032
  min-copper-edge-space = 0.381
  min-annular-ring = 0.1524
  min-drill-diameter = 0.254
  min-silkscreen-width = 0.0762
  min-pitch-leaded = 0.35
  min-pitch-bga = 0.35
  max-board-width = 457.2
  max-board-height = 609.6
  min-silk-solder-mask-space = 0.127
  min-silkscreen-text-height = 0.75
  solder-mask-registration = 0.106
  min-th-pad-expand-outer = 0.2032
  min-soldermask-opening = 0.152
  min-soldermask-bridge = 0.102
  min-hole-to-hole = 0.254
  min-pth-pin-solder-clearance = 3.0

Description

All design rules are required to have a value. The supported design rules are :

Statements

In addition to the set of supported design rules, pcb-rules may have some additional, optional statements.

Name

name is the optional name field of an JITX object. Use it to store a descriptive name as a String for human designers reading JITX.

Syntax

pcb-component component :
  name = "ADM7150"

pcb-pad smd-pad (anchor:Anchor, w:Double, h:Double) :
  name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor])

pcb-module band-pass-filter :
  name = "Band-pass filter"

Description

name = "ADM7150" Name this component "ADM7150"

name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor]) Name this pad by constructing a name passed to a paramteric pad function

name = "Band-pass filter" Name this module "Band-pass filter"

Description

description is the optional description field of a JITX object. Use it to store a description of the object for human designers reading JITX, and to make the object easier to find via text search.

Syntax

pcb-component analog-devices-ADM7150 :
  description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator"

pcb-module band-pass-filter :
  description = "Passive band-pass filter with cascaded highpass and low-pass stages."

Description

description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator" Add a description to call out special functions of the device.

name = "Band-pass filter" Add a description to signify the intent of a circuit.

pcb-stackup

Outline

pcb-stackup :
  name:        String 
  description: String

  *layer(thickness:Double, material:pcb-material) 

Description

A set of manufacturing rules that defines the materials and thicknesses of each layer (including insulators) of a PCB. Probably defined by your fab.

Usage

pcb-stackup Oshpark4Layer : 
  name        = "Oshpark Four Layer Stackup"
  description = "The standard 4 layer stackup at OshPark"
  
  layer(1.0, dlp)
  layer(1.0, ENIG)
  layer(1.4, copper-1_0)
  layer(6.7, FR408_prepreg)
  layer(0.7, copper-0_5)
  layer(47.0 FR408_core)
  layer(0.6, copper-0_5)
  layer(6.7, FR408_prepreg)
  layer(1.4, copper-1_0)
  layer(1.0, ENIG)
  layer(1.0, dlp)

Statements

Symbol Statements

Symbols are definitions of the schematic representation of a part. The JITX OCDB has a large collection of predefined symbols you can use. The make-box-symbol() is a powerful tool to quickly create a consistent looking part library. For more information, see the symbol reference.

For more unusual components where box symbols may not apply, you can draw symbols the same way you can draw any collections of shapes in JITX. On imported components, the symbols may appear as collections of lines, shapes, and text.

Example, Wurth 760390012

pcb-symbol c-760390012-symbol :
  pin p[1] at Point(-5.08, 7.62) with :
    direction = Left
    length = 2.54
    number-size = 0.609
    name-size = 0.609
  pin p[2] at Point(-5.08, 0.0) with :
    direction = Left
    length = 2.54
    number-size = 0.609
    name-size = 0.609
  pin p[3] at Point(-5.08, -7.62) with :
    direction = Left
    length = 2.54
    number-size = 0.609
    name-size = 0.609
  pin p[6] at Point(5.08, 7.62) with :
    direction = Right
    length = 2.54
    number-size = 0.609
    name-size = 0.609
  pin p[5] at Point(5.08, 0.0) with :
    direction = Right
    length = 2.54
    number-size = 0.609
    name-size = 0.609
  pin p[4] at Point(5.08, -7.62) with :
    direction = Right
    length = 2.54
    number-size = 0.609
    name-size = 0.609
  layer("foreground") = Text(">VALUE", 0.762, SW, loc(-5.08, 7.62 + 0.3))
  layer("foreground") = Text(">REF", 0.762, SW, loc(-5.08, 7.62 + 0.3 + 0.762 + 0.3))
  layer("foreground") = Circle(Point(-3.175, 6.604), 0.254)
  layer("foreground") = Circle(Point(-3.175, -1.016), 0.254)
  layer("foreground") = Circle(Point(2.667, -1.016), 0.254)
  layer("foreground") = Circle(Point(2.667, 6.604), 0.254)
  layer("foreground") = Line(0.254, [Point(-0.635, 8.0), Point(-0.635, -0.508)])
  layer("foreground") = Line(0.254, [Point(0.635, 8.0), Point(0.635, -0.508)])
  layer("foreground") = Line(0.254, [Point(-0.635, 0.381), Point(-0.635, -8.128)])
  layer("foreground") = Line(0.254, [Point(0.635, 0.381), Point(0.635, -8.128)])
  layer("foreground") = Line(0.254, [Point(-2.54, 7.62), Point(-5.08, 7.62)])
  layer("foreground") = Line(0.254, [Point(-2.54, 0.0), Point(-5.08, 0.0)])
  layer("foreground") = Line(0.254, [Point(-2.54, -7.62), Point(-5.08, -7.62)])
  layer("foreground") = Line(0.254, [Point(2.54, -7.62), Point(5.08, -7.62)])
  layer("foreground") = Line(0.254, [Point(2.54, 0.0), Point(5.08, 0.0)])
  layer("foreground") = Line(0.254, [Point(2.54, 7.62), Point(5.08, 7.62)])

Statements

Here is the list of all of the statements you can use in a pcb-symbol :

backend-substitution

backend-substitution(backend) = my-symbol with backend in {"Kicad, "Altium"} allows symbols to be substituted by other symbols when exported to a particular CAD tool, namely Kicad or Altium that has a restricted set of power symbols. Altium ground and supply symbols are in the ocdb/utils/symbols package of the open-components-database repository.

Syntax

public pcb-symbol ground-sym :
  pin p[0] at unit-point(0.0, 0.0)
  
  unit-line([[0.0, 0.0], [0.0, -0.5]])
  unit-line(0.1, [[-0.5, -0.5], [0.5, -0.5]])
  unit-line(0.1, [[-0.3, -0.7], [0.3, -0.7]])
  unit-line(0.1, [[-0.1, -0.9], [0.1, -0.9]])

  unit-val([-1.0, -1.5])
  preferred-orientation = PreferRotation([0])
  backend-substitution("Altium") = altium-ground-sym

Description

The standard ground symbol ground-sym defined in the ocdb/utils/symbols package of the open-components-database is automatically replaced by the altium-ground-sym symbol everywhere it is used when exporting the schematics to Altium using set-export-backend("Altium") before export-cad() command.

Description

description is the optional description field of a JITX object. Use it to store a description of the object for human designers reading JITX, and to make the object easier to find via text search.

Syntax

pcb-component analog-devices-ADM7150 :
  description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator"

pcb-module band-pass-filter :
  description = "Passive band-pass filter with cascaded highpass and low-pass stages."

Description

description = "800 mA Ultralow Noise, High PSRR, RF Linear Regulator" Add a description to call out special functions of the device.

name = "Band-pass filter" Add a description to signify the intent of a circuit.

Symbol Layers

The layer statement inside a pcb-symbol adds symbol artwork on a named schematic layer.

Syntax

; layer(layer-name:String) = Shape 

layer("foreground") = Rectangle(10.0, 10.0)
layer("background") = Rectangle(10.0, 10.0)

Description

layer places geometry on a named layer in the schematic. The most commonly used layers in JITX schematics are "foreground" and "background".

Name

name is the optional name field of an JITX object. Use it to store a descriptive name as a String for human designers reading JITX.

Syntax

pcb-component component :
  name = "ADM7150"

pcb-pad smd-pad (anchor:Anchor, w:Double, h:Double) :
  name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor])

pcb-module band-pass-filter :
  name = "Band-pass filter"

Description

name = "ADM7150" Name this component "ADM7150"

name = to-string("%_x%_ %_ SMD Pad" % [w,h,anchor]) Name this pad by constructing a name passed to a paramteric pad function

name = "Band-pass filter" Name this module "Band-pass filter"

Ports

port is a JITX statement that defines pins on components and modules that you can net to.

Syntax

port a : pin
pin a

port b : pin[6]
port c : pin[[1, 2, 4 through 6]]

port data : i2c
port lots-of-data : i2c[30]

Description

port a : pin Create a port with a single pin named a

pin a Create a port with a single pin named a (same as above, but more convenient syntax.)

port b : pin[4] Create a port named b with 4 pins named b[0] through b[3]. You can loop over these pins programmatically:

for i in indices(b) do:
  net (b[i])
  println(i)

Prints out:

0
1
2
3

port c : pin[[1, 2, 4 through 6]] Create a port named c with a non-standard range. c has 4 pins named c[1] c[2] c[4] c[5] and c[6]. You can loop over these pins programmatically:

for i in indices(c) do:
  net (c[i])
  println(i)

Prints out:

1
2
4
5
6

port data : i2c Create a port named data of the pcb-bundle named i2c.

port lots-of-data : i2c[30] Create a port array with 30 I2C ports. lots-of-data[0].sda is the sda pin of the first I2C bundle.

preferred-orientation

preferred-orientation = AnyRotation() | PreferRotation(rotation-list) allows to specify a preferred-orientation as a SymbolOrientationobject.AnyRotation()means no specified preferred orientation.PreferRotation(rotation-list)allows to give a list of preferred rotation options to apply that are integers between 0 and 3. the applied rotation fori will be of90° * i` (direct trigonometric sense ie ccw).

SymbolOrientation is defined in the jitx package :

public deftype SymbolOrientation
public defstruct AnyRotation <: SymbolOrientation
public defstruct PreferRotation <: SymbolOrientation :
  rotations: Tuple<Int> with: (ensure => ensure-rotations!)

Syntax

public pcb-symbol altium-ground-sym :
  name = "POWER-GROUND"
  pin p[0] at unit-point(0.0, 0.0)

  unit-line([[0.0, 0.0], [2.54, 0.0]])
  unit-line(0.1, [[2.54, -1.4], [2.54, 1.4]])
  unit-line(0.1, [[3.81 -0.93], [3.81, 0.93]])
  unit-line(0.1, [[5.08, -0.46], [5.08, 0.46]])
  unit-val([7.5, -2.5])

  preferred-orientation = PreferRotation([3])

Description

This ground Altium symbol is defined with the pin to the left but needs to be rotated by 270° to have it point upwards in the schematics.

Struct Statements

pcb-struct is a way to store a collection of related variables.

Example

Right now we need to use a fully qualified name to define a new pcb-struct. So if we wanted an struct named:

GenericPin

And we're defining it in a package named

defpackage ocdb/utils/property-structs

Then the struct needs to be defined as follows:

public pcb-struct ocdb/utils/property-structs/GenericPin :
  max-voltage:Toleranced|RelativeVoltage    ; Maximum voltage that can be applied to pin (V)
  rated-esd:Double   

All together this is what it looks like to define and use a pcb-struct:

defpackage ocdb/utils/property-structs:
...

public pcb-struct ocdb/utils/property-structs/GenericPin :
  max-voltage:Toleranced|RelativeVoltage    ; Maximum voltage that can be applied to pin (V)
  rated-esd:Double   

val generic-props  = GenericPin(min-max(-0.3 5.0), 1500.0)

println(max-voltage(generic-props))

When we create a value that uses a struct, the variables are given in the order defined in the pcb-struct. In the above example:

• min-max(-0.3 5.0) gets assigned to max-voltage
• 1500.0 gets assigned to rated-esd

We can then access the information by the name defined in the pcb-struct. max-voltage(generic-props) fetches the value stored in the field max-voltage of a GenericPin.

JITX Types Reference

This is the reference page for JITX types.

Top Level Definitions

Top-level definitions are subtypes of JITXDef.

public deftype JITXDef <: Hashable & Equalable

;pcb-landpattern
public defstruct LandPattern <: JITXDef

;pcb-pad
public defstruct Pad <: JITXDef

;pcb-symbol
public defstruct SchematicSymbol <: JITXDef

;pcb-rules
public defstruct Rules <: JITXDef

;pcb-material
public defstruct Material <: JITXDef

;pcb-board
public defstruct Board <: JITXDef

;pcb-stackup
public defstruct Stackup <: JITXDef

While most top-level definitions follow this format, components, modules, and bundles have additional types. Instantiables include modules and components, and since they support individual and array representations, they are subtypes of JITXDef and InstantiableType. Bundles are one of three forms that can be declared as a port in a pcb-module or pcb-component. They are subtypes of JITXDef and PortType.

public deftype InstantiableType

;pcb-module and pcb-component
public defstruct Instantiable <: JITXDef & InstantiableType

public defstruct InstantiableArray <: InstantiableType

public deftype PortType

public defstruct SinglePin <: PortType

;pcb-bundle
public defstruct Bundle <: JITXDef & PortType

public defstruct PortArray <: PortType

Local Definitions

Local definitions are subtypes of JITXObject.

public deftype JITXObject <: Hashable & Equalable

;Pins of modules, components, or bundles
public defstruct Pin <: JITXObject

;Land pattern pads
public defstruct LandPatternPad <: JITXObject

;Symbol pins
public defstruct SymbolPin <: JITXObject

;Instances of modules or components
public defstruct Instance <: JITXObject

;Nets of modules
public defstruct Net <: JITXObject

self is an Instance than can be referenced within a pcb-module or pcb-component to access or modify fields of that definition.

JITX Patterns Cheat Sheet

The JITX language is embedded into the LB Stanza Programming Language. A comprehensive guide to learning stanza can be found in the reference, Stanza by Example. A short guide on stanza expressions and syntax can also be read here.

Common Code Patterns

for loops

A for loop takes the form

for <thing> in <sequence> <op> :
  <body> 

Where thing is an identifier, sequence is an expression of type Seqable, and op is an "operating" function that applies body to thing. Here are some common examples :

val values = [1, 2, 3]
for value in values do :
  println(value)

; prints :
; 1
; 2
; 3

do is the most common operating expression and just applies the body of the loop to the value in the sequence.

Another common operator is filter, which is used to loop over the sequence and remove items.

val values = [1, 2, 3]
val odds =
  for value in values filter :
    value % 2 != 0
for odd in odds do :
  println(odd)

; prints : 
; 1
; 3

More examples of for loops can be found in Stanza by Example, and a list of operating functions is available in the reference.

match expressions

The match expression is a conditional expression that evaluates one of multiple branches depending on the types of its arguments. The most common form is a single argument match.

defn my-function (arg:Int|Double|True|False) :
  match(arg) :
    (i:Int) : 
      println("arg is an Int:%_" % [i])
    (d:Double) :
      println("arg is a Double:%_" % [d])
    (b:True|False) :
      println("arg is a boolean:%_" % [b])

match can take multiple arguments.

defn my-function (x:Int|Double, y:Int|Double) :
  match(x, y) :
    (x:Int, y:Int) :
      println("x and y are Ints.")
    (x:Double, y:Double) :
      println("x and y are Doubles.)
    (x, y) :
      println("x and y are of different types!)

A common pattern is something like this :

defn my-function (arg:Int|False) :
  match(arg) :
    (arg:Int) :
      do-something(arg)
    (f:False) :
      ; do nothing
      false

A shorthand for this syntax is

defn my-function (arg:Int|False) :
  match(arg:Int) :
    do-something(arg)

switch expressions

The switch expression is another conditional expression that evaluates multiple branches, it's syntactic sugar for chains of if/else if expressions.

defn arrive-or-leave (arg:String) :
  switch(arg) :
    "hello" : 
      hello()
    "goodbye" : 
      goodbye()
    else : 
      fatal("The caller has bad manners.")

supports statements

Supports statements declare what bundle(s) a component or module supports and how the bundle pins are mapped to the ports of the component or module.

  ; Bundles may be used inside pcb-components or
  ; pcb modules

  ; The mapping goes 
  ; bundle.pin-ref => self.pin-ref    
  supports bundle :
    bundle.p[1] => self.p[2]
    ; ... rest of mappings to the bundle ...

requires statements

Requires statements are used in pcb-module definitions to define what supports they need.

  ; inside pcb-module
  require <ref> : <bundle> from <instance>

The pin solver will automatically map pins that supports the bundle that the module requires to an alias, ref.

In addition to using require inside of a pcb-module, require statements can be "chained" inside of supports statements.

pcb-component mcu :
  port p: pin[128]

  for n in 10 to 30 do :
    supports gpio :
      gpio.p => self.p[n]

  supports spi-controller():
    require io : gpio[4]
    spi-controller().copi => io[0].p  
    spi-controller().cipo => io[1].p  
    spi-controller().cs   => io[2].p
    spi-controller().sck  => io[3].p  

pin-properties tables

pin-properties tables are a mechanism for declaring metadata about the pins in a pcb-component. It is used for commands like assign-landpattern, assign-symbol, and make-box-symbol.

; Declare pin properties: the names of pins and pads they are mapped
; to on the associated landpattern
pcb-component component :
  ;Each row has format:
  pin-properties :
    [pin:Ref | pads:Int ...   ]
    [a       | 1              ]
    [b       | 2              ]
    [c       | 3              ]        
    [gnd     | 4 5 6 7 8      ]
    [d+      | 9              ]
    [d-      | 10             ]

  make-box-symbol()
  assign-landpattern(mylandpattern)

pcb-component definitions

See the reference for more.

pcb-component component :
  name         = "My awesome component"
  mpn          = "MPN"
  manufacturer = "Manufacturer"
  description  = "This is an example component."

  ; ... component statements ... 

pcb-module definitions

See the reference for more.

pcb-module module :
  ; Define some metadata of the module
  name        = "My Module"
  description = "This is an example module"

  ; Declare some ports 
  port io: bundle

  ; Declare some instances
  inst U: component

  ; Net ports and instances together
  net (io.p[1], U.p[1])

  ; Perhaps add some layer geometry
  layer(Silkscreen("F-Silk", Top)) = Text("REV 1.0", 2.54, C, loc(0.0, 0.0))

  ; Add instances to schematic groups
  schematic-group(U) = grouped-insts

  ; Add the instances to schematic groups 

pcb-landpattern definitions

See the reference for more.

pcb-landpattern my-landpattern :
  ; define a pad
  pcb-pad p[1] : smd-pad(Circle(1.0)) at loc(0.0, 0.0) on Top

  ; Add custom soldermask layers
  layer(SolderMask(Top)) = Rectangle(1.25, 1.25)

pcb-component to pcb-symbol mappings

Symbol pins are mapped to component pins using the following syntax :

pcb-component my-resistor :
  port p: pin[[1, 2]]

  ; sym is an expression corresponding to a generated
  ; pcb-symbol
  val sym = resistor-sym()

  ; The mapping is:
  ;    <component-pin> => <symbol>.<symbol-pin>
  symbol = 
    sym(p[1] => sym.p[1], 
        p[2] => sym.p[2])

pcb-component to pcb-landpattern mappings

Landpattern pins are mapped to component pins using the following syntax :

pcb-component my-resistor :
  port p: pin[[1, 2]]

  ; lp is an expression corresponding to a generated
  ; pcb-landpattern
  val lp = ipc-two-pin-landpattern("0201")

  ; The mapping is:
  ;    <component-pin> => <landpattern>.<landpattern-pad>
  landpattern = 
    lp(p[1] => lp.p[1], 
       p[2] => lp.p[2])

Getting and setting properties

  ; set a property
  property(self.property-name) = expression

  ; get a property
  val property = property(self.property-name)

  ; check if a property is set
  has-property?(self.property-name)

  ; optionally check if a property is set and 
  ; perform some logic with the value
  match(property?(self.property-name)) :
    (one:One) :
      val property = value(one)
    (none:None) :
      ; property is not set

Adding passive components

ocdb/utils/generic-components has a few generators for querying jellybean components from the JITX parts database. See the design variables reference for configuration with global design parameters.

defpackage my-design :
  import jitx
  import jitx/commands
  import ocdb/utils/design-vars
  import ocdb/utils/generic-components

; define the minimum package size for the design
MIN-PKG = "0601"

pcb-module module :
  ; Drop some passives in a module

  ; Query a generic 1k ohm chip resistor
  inst R1 : chip-resistor(1.0e3)

  ; Query a generic 1k ohm chip resistor with 5% tolerance
  inst R2 : chip-resistor(1.0e3, 0.05)

  ; Query a generic 4.7nF ceramic cap
  inst C1 : ceramic-cap(4.7e-9)

  ; Query a generic 4.7nF ceramic cap with 5% tolerance
  inst C1 : ceramic-cap(4.7e-9)

Named nets

Nets can be given a name, but it must have one character of whitespace between the name and arguments!

pcb-module module :
  net name (a, b, c)
  ; net name(a, b,c) <--- invalid!

Learning Stanza: quick reference

JITX is implemented in the LB Stanza (Stanza) programming language. We like stanza because it supports types to help write correct code, and also allows higher-level programming. We can write Stanza programs inline with JITX code, to generate designs, components, and modules programmatically.

We do not need all of Stanza to develop with JITX; this document provides a short walkthrough of commonly-used Stanza features.

; this is a comment 
;<A>
This is a block comment 
    ;<B> 
        block comments can be nested with optional tags. 
    ;<B>
;<A>

defpackage learn-stanza-in-y: 
  import core 
  import collections 

;=========================================================================
; The basics, things you'd find in most programming languages
;=========================================================================

; Variables can be mutable (var) or immutable (val)
var mutable = "this one can be" 
val immutable = "this string can't be changed"

; The basic data types (annotations are optional) 
val an-int: Int = 12345
val a-long: Long = 12345L
val a-float: Float = 1.2345f
val a-double: Double = 3.14159
val a-string: String = "this is a string"
val a-multiline-string = \<tag>
    this is a multi-line string literal. 
<tag>


; print formatted strings with println() and "..." % [...]
println("this is a formatted string %_ %_" % [mutable, immutable])

; Stanza is optionally typed, and has a ? (any) type. 
var anything:? = 0
anything = 3.14159
anything = "a string"

; Stanza has basic collections such as Tuples, Arrays, Vectors, HashTables, etc. 
val tuple: Tuple<?> = [mutable, immutable]

val array = Array<?>(3)
array[0] = "string"
array[1] = 1
array[2] = 1.23455
; array[3] = "out-of-bounds" ; arrays are bounds-checked 

val vector = Vector<?>()
vector[0] = "string"
vector[1] = 1
vector[2] = 3.14159

val hash-table = HashTable<String, ?>()
hash-table["0"] = 0
hash-table["1"] = 1 
hash-table["2"] = 1 


;========================================================================
; Functions
;========================================================================
; Functions are declared with the `defn` keyword 
defn my-function (arg:?) : ; note the space between identifier and arg list
  println("called my-function with %_" % [arg])

my-function("arg")  ; note the lack of a space to call the function

; functions can be declared inside another function and capture their environemtn
defn outer (arg): 
  defn inner (): 
    println("outer had arg: %_" % [arg])
  inner()

outer("something")

; functions are "first-class" in stanza, meaning you can assign variables 
; to functions and pass functions as arguments to other functions. 
val a-function = outer 
defn do-n-times (arg, func, n:Int): 
  for i in 0 to n do : 
    func(arg)
do-n-times("argument", a-function, 3)

; sometimes you want to define a function inline, or use an anonymous function. 
; for this you can use the syntax: 
;   fn (args): 
;       ... 
do-n-times("hello", fn (arg): println(arg), 2)

; there is a shorthand for writing anonymous functions, the above can be written
do-n-times("hello", { println(_) }, 2)

; the short hand works for multiple arguments as well. 
val multi-lambda = { println(_ + 2 * _) }
multi-lambda(1, 2)

;========================================================================
; User defined types
;========================================================================
; Structs are declared with the `defstruct` keyword
defstruct MyStruct: 
  field

; constructors are derived automatically
val my-struct = MyStruct("field:value")

; fields are accessed using function-call syntax
println(field(my-struct))

; Stanza supports subtyping with a "multimethod" system based on method 
; overloading.
deftype MyType
defmulti a-method (m:MyType)

defstruct Foo <: MyType
defstruct Bar <: MyType
defmethod a-method (a-foo: Foo):
  println("called a-method on a Foo")

defmethod a-method (a-foo: Bar):
  println("called a-method on a Bar")

;=========================================================================
; The Type System
;=========================================================================
; True and Falseare types with a single value. 
val a-true: True = true 
val a-false: False = false 

; You can declare a union type, or a value that is one of a set of types 
val a-boolean: True|False = true 
val another-boolean: True|False = false 

; You can pattern match on types 
match(a-boolean):
  (t:True): println("is true")
  (f:False): println("is false")

; You can match against a single possible type
match(a-boolean:True):
  println("is still true")
else: 
  println("is not true")

; You can compose program logic around the type of a variable
if anything is Float :
  println("anything is a float")
else if anything is-not String : 
  println("anything is not an int")
else : 
  println("I don't know what anything is")

; stanza 
;=========================================================================
; Control Flow 
;=========================================================================
; stanza has the standard basic control flow 
val condition = [false, false]
if condition[0] : 
  ; do something 
  false 
else if condition[1] : 
  ; do another thing
  false 
else :
  ; whatever else
  false

; there is also a switch statement, which can be used to pattern match
; on values (as opposed to types)
switch(anything):
  "this": false 
  "that": false 
  "the-other-thing": false 
  else: false 

; for and while loops are supported
while condition[0]: 
  println("do stuff")

for i in 0 to 10 do:  
  vector[i] = i

; stanza also supports named labels which can functin as break or return 
; statements
defn another-fn (): 
  label<False> return:
    label<False> break:
      while true: 
        if condition[0] is False: 
            break(false) 
    return(false)

; For a comprehensive guide on Stanza's advanced control flow, check out 
; this page: http://lbstanza.org/chapter9.html from Stanza-by-Example

;=========================================================================
; Sequences 
;=========================================================================
; for "loops" are sugar for a more powerful syntax. 
val xs = [1, 2, 3] 
val ys = ['a', 'b', 'c']
val zs = ["foo", "bar", "baz"]

for (x in xs, y in ys, z in zs) do : 
  println("x:%_, y:%_, z:%_" % [x, y, z])


;xs, ys, and zs are all "Seqable" meaing they are Seq types (sequences). 
; the `do` identifier is a special function that just applies the body of
; the for loop to each element of the sequence. Sequences are called "iterators"
; in other languages and provide similar abstractions. 
; 
; A common sequence task is concatenating sequences. This is accomplished 
; using the `seq-cat` function. This is analogous to "flattening" iterateors
val concat = to-tuple $ 
  for sequence in [xs, ys, zs] seq-cat: 
    sequence

; we can also use a variation to interleave the elements of multiple sequences
val interleaved = to-tuple $ 
  for (x in xs, y in ys, z in zs) seq-cat : 
    [x, y, z]

println("[%,] [%,]" % [concat, interleaved])

; Another common task is mapping a sequence to another, for example multiplying
; all the elements of a list of numbers by a constant. To do this we use `seq`. 
var numbers = [1.0, 2.0, 3.0, 4.0] 
numbers = to-tuple $ 
  for n in numbers seq : 
    2.0 * n 
println("%," % [numbers])

if find({_ == 2.0}, numbers) is-not False : 
  println("found it!")

; or maybe we just want to know if there's something in a sequence 
var is-there = 
  for n in numbers any? :
    n == 2.0 

; since this is "syntactic sugar" we can write it explicitly using an 
; anonymous function
is-there = any?({_ == 2.0}, numbers)

; a detailed reference of the sequence library and various adaptors can 
; be found here: http://lbstanza.org/reference.html#anchor439
;=========================================================================
; Documentation 
;=========================================================================
;
; Top level statements can be prefixed with the "doc" field which takes 
; a string value and is used to autogenerate documentation for the package. 
doc: \<doc>
    # Document Strings 

    ```stanza
    val you-can = "include code snippets, too" 
    ```

    To render documentation as markdown (compatible with mdbook)

    ```bash 
    stanza doc source.stanza -o docs 
    ```
<doc>
defn docfn () : false 

API Reference for jitx/commands

• Main Design
• Top Level Commands
• Lookup

Main Design

set-main-module

defn set-main-module (module:Instantiable)

Define the "main" module of the current design.

Syntax

pcb-module main-module :
  ...

set-main-module(main-module)

Description

The main module is the root of the entire JITX design, and is analogous to a "root" schematic sheet.

set-board

defn set-board (board:Board)

Sets the pcb-board object used by the current design.

Syntax

pcb-board my-board :
  ...

set-board(my-board)

Description

This specifies the pcb-board which defines the stackup, board outline, and signal boundary of the physical board used in the design.

Multi-board designs require separate calls to set-design, set-board, etc.

set-rules

defn set-rules (rules:Rules)

Set the design rules for the current design.

Syntax

pcb-rules jlc-pcb-rules :
  ...

set-rules(jlc-pcb-rules)

Description

The design rules takes the name of a pcb-rules as an argument and configures the design rules used for generators and checks in the current design. This will be cleared on calls to set-design.

set-default-rules

defn set-default-rules (rules:Rules)

Sets the default rules for all designs in the current program.

Syntax

pcb-rules jlc-pcb-rules :
  ...

set-default-rules(jlc-pcb-rules)

Description

Default rules differ from design rules set in set-rules in that they are not cleared between designs, and serves as temporary or default values for design rules so generators can make progress even if you have not set the rules for your design.

Default rules can also be used to share design rules in multi-design programs.

clear-default-rules

defn clear-default-rules ()

Syntax

  clear-default-rules()

Description

Removes default rules if they are set. This is primarily used for testing.

Top Level Commands

print-def

defn print-def (def:JITXDef)

Print the ESIR defintion as ASCII. Not very human readable. Use Design Explorer to see this data structured for human consumption.

Syntax

pcb-module my-module : 
  ...

print-def(my-module)

print-def will print out the fully expanded definition. JITX definitions include pcb-board, pcb-module, pcb-rules, pcb-stackup, pcb-component, pcb-pad, pcb-landpattern, etc.

assign-landpattern

defn assign-landpattern (package:LandPattern) -> False

Map a landpattern to a component using pin properties.

Syntax

public pcb-component component :
  manufacturer = "Texas Instruments"
  mpn          = "FDC2214QRGH"

  pin-properties :
    [pin:Ref | pads:Int ... | side:Dir ]
    [i2c.scl | 1            | Left     ]
    [i2c.sda | 2            | Left     ]
    [CLKIN   | 3            | Left     ]
    [ADDR    | 4            | Left     ]
    [INTB    | 5            | Left     ]
    [SD      | 6            | Left     ]
    [VDD     | 7            | Left     ]
    [GND     | 8            | Left     ]
    [IN0A    | 9            | Right    ]
    [IN0B    | 10           | Right    ]
    [IN1A    | 11           | Right    ]
    [IN1B    | 12           | Right    ]
    [IN2A    | 13           | Right    ]
    [IN2B    | 14           | Right    ]
    [IN3A    | 15           | Right    ]
    [IN3B    | 16           | Right    ]

val lp = qfn-landpattern(0.5, 3.8, 16, 0.25, 0.4, [2.6 2.6])
assign-landpattern(lp)

Description

The assign-landpattern convenience function is a helper for mapping a landpattern to a pcb-component using the pin-properties table. The table must contain a pads column whose type is | pads: Int ...|, | pads: Ref ...| or |pads: Int|Ref ...|. Multiple entries in the pads column can be used to assign a component pin to multiple pads.

assign-symbol

defn assign-symbol (symbol:SchematicSymbol) -> False

Assign a symbol to a pcb-component

Syntax

public pcb-component component :
  name = "142-0761-881"
  manufacturer = "Johnson / Cinch Connectivity Solutions"
  mpn = "142-0761-881"
  reference-prefix = "J"

  pin-properties :
    [pin:Ref  |pads:Int ...   | side:Dir]
    [sig      | 1             | Left    ]
    [gnd      | 2 3           | Down    ]

  assign-symbol(coax-sym)
  assign-landpattern(johnson-142-0761-881-pkg)

Description

The assign-symbol function uses the pin column in a pin-properties table to map the pins of a component to the pins of a schematic symbol. The symbol pin names must match the component pin names

transform-module

defn transform-module (body:() -> ?, module:Instantiable) -> Instantiable

Applies body on module to return a newly transformed Instantiable. This is how to run custom passes on your design module.

Syntax

pcb-module main-module :
  ; ...

defn generate-power () :
  inside pcb-module :
    ; ...

val module-with-power = transform-module(generate-power, main-module)

Description

The transform-module function takes two arguments, a function body and pcb-module module. The compiler will apply body to the module

run-evals

defn run-evals (module:Instantiable) -> Instantiable

Runs all eval-when blocks nested within module to return a newly evaluated Instantiable.

Syntax

pcb-module main-module :
  eval-when has-property?(self.voltage) :
    println("Voltage assigned!")

defn assign-voltage () :
  inside pcb-module :
    property(self.voltage) = 3.3

val transformed-module = transform-module(assign-voltage, main-module)
val evaluated-module = run-evals(transformed-module)

Description

eval-when statements need to be driven by the design generator code. The run-evals command is used to control this.

run-checks

defn run-checks (filename:String) -> CheckSummary

Runs all checks statements, saves results in a file named filename, and returns a CheckSummary.

Syntax

pcb-check check-5V (a:JITXObject) :
  #CHECK(has-property?(a.voltage))
  #CHECK(property(a.voltage) is Double)
  #CHECK(property(a.voltage) == 5.0)

pcb-module mymodule :
  pin x
  property(x.voltage) = 5.0
  check check-5V(self)

set-main-module(mymodule)
run-checks("5V-check.txt")

Description

The run-checks command is used to run pcb-checks on a design. Checks are arbitrary DRC, ERC, or other static analsyses defined in code to validate a design programmatically.

freeze-reference-designators

defn freeze-reference-designators () -> Instantiable

Freeze all the reference designators, so they will not be recomputed.

Syntax

val lowered-module = run-final-passes(module)
set-main-module(lowered-module)
set-main-module(freeze-reference-designators())

Description

The freeze-reference-designators command stops the JITX compiler from generating new reference designators for existing components in a design.

assign-pins

defn assign-pins () -> Instantiable

Explicitly run pin assignment before automatic placement, visualization, or export.

Syntax

pcb-module my-module :
  pin x
  supports gpio :
    gpio.gpio => x
  require mygpio: gpio from self

set-main-module(my-module)
val my-module-assigned = assign-pins()

Description

JITX will automatically run pin assignment prior to board placement, export, and visualization. Pin assignment can be run manually using the assign-pins function, which can be useful when running checks or debugging.

Running assign-pins?() instead of assign-pins will return False if there is no valid pin assignment.

view-board

defn view-board (view-mode:ViewMode) -> False

Visualize the generated board.

Syntax

; Default: update the view
view-board()
; Visualize, panning to the center of the view and zooming to fit
view-board(NewView)
; Visualize, but maintain the same pan/zoom state.
view-board(UpdateView)

Description

The view-board command is used to visualize the generated circuit board.

view-schematic

defn view-schematic (view-mode:ViewMode) -> False

Visualize the generated schematic.

Syntax

; Default: update the view
view-schematic()
; Visualize, panning to the center of the view and zooming to fit
view-schematic(NewView)
; Visualize, but maintain the same pan/zoom state.
view-schematic(UpdateView)

Description

The view-schematic command is used to visualize the generated circuit board.

view-sub-schematic

defn view-sub-schematic (objects: Tuple<JITXObject>, schematic-group?: True|False) -> False
defn view-sub-schematic (objects: Tuple<JITXObject>) -> False
defn view-sub-schematic (object: JITXObject, schematic-group?: True|False) -> False
defn view-sub-schematic (object: JITXObject) -> False

Visualize the generated sub-schematic for a list of nets and instances.

Nets can be single nets, net arrays or bundle nets.

Instances can be component or module instances. They can be single instances or instance arrays.

Syntax

; Objects given to view-sub-schematic need to reference the design main module.
set-main-module(main-module)

; Visualize a list of nets and instances. Default: no schematic groups.
view-sub-schematic([main-module.gnd, main-module.P3V3])
; Visualize a list of nets and instances with schematic groups.
view-sub-schematic([main-module.gnd, main-module.P3V3], true)
; Visualize a single net or instance. Default: no schematic groups.
view-sub-schematic(main-module.sensors)
; Visualize a single net or instance with schematic groups.
view-sub-schematic(main-module.sensors, true)

Description

The view-sub-schematic command is used to visualize a subset of the schematic of the generated board.

view

defn view (def:LandPattern, view-mode:ViewMode) -> False

View a landpattern, schematic symbol, or pcb-component.

Syntax

; Default: update the view
view(ocdb/utils/symbols/resistor-sym)
; Visualize, panning to the center of the view and zooming to fit
view(ocdb/utils/symbols/resistor-sym, NewView)
; Visualize, but maintain the same pan/zoom state.
view(ocdb/utils/symbols/resistor-sym, UpdateView)

Description

The view command is used to visualize generated landpatterns, schematic symbols, or components. It will fail if passed a pcb-module or array of instantiables.

view-design-explorer

defn view-design-explorer () -> False

Visualize the design as a hierarchical tree.

Syntax

; Visualize the design as a tree
view-design-explorer()

Description

The view-design-explorer command is used to visualize the design in the VSCode UI.

set-current-design

defn set-current-design (name:String) -> False

Set the directory "./designs/" that JITX will use to store design data.

Syntax

set-current-design("jitx-design")

Description

The set-current-design command will clear design state and create a new design directory to store data JITX uses. This directory will contain export data, 3D model files, and cached data used by the design.

export-cad

defn export-cad () -> False
defn export-cad (field-mappings:Tuple<KeyValue<String String>>) -> False

Export the JITX design to CAD.

Syntax

set-current-design("jitx-design")
set-export-backend(`altium)

; ... run design ...

export-cad()
; Cad files written to <project-root>/designs/jitx-design/altium

OR

val mappings = [
  "rated-temperature" => "Rated-temperature"
  "datasheet" => "Datasheet"
]
export-cad(mappings)
; Cad files written to CAD with the field/property names converted.

Description

The export-cad command will take the generated board and schematic and convert it to a set of files in the design directory that can be used in CAD software.

The output directory will be <design-directory-name>/<export-backend>.

An optional field-mappings can be supplied as an argument. Name, Description, Manufacturer, MPN, Reference-prefix will always be exported, even if there is no field-mappings. Their exported names can be changed by using the field-mapping.

Component properties can also be exported if an entry exists in field-mappings. For example, if there is a property(U1.datasheet) = "http://www.somewhere.com/my-datasheet.pdf", using "datasheet" => "Datasheet" in the field-mappings (as above), a field "Datasheet" with value "https://www.somewhere.com/my-datasheet.pdf" will appear as a property of the component in CAD software.

A property will not be exported if...

• there is no corresponding entry in field-mappings; OR
• it does not exist; OR
• its value cannot be converted to a string.

To export a property without name change, put the same name in both ends of the mapping. For example, "rated-voltage" => "rated-voltage".

set-export-backend

defn set-export-backend (backend:Symbol)

Set the CAD exporter backend to use.

Syntax

set-current-design("jitx-design")
set-export-backend(`altium)

; ... run design ...

export-cad()
; Cad files written to <project-root>/designs/jitx-design/altium

Description

The set-export command will control which CAD backend that export-cad will use. The backend will also define some contraints on internals like placement and visualization.

set-value-format-options

defn set-value-format-options (format-options:Tuple<String>)

Set the formats of the value strings during export operation.

Syntax

set-current-design("jitx-design")
set-export-backend(`kicad)
val format-options = ["keep-decimal" "LC-units-always-present"]
set-value-format-options(format-options)

; ... run design ...

export-cad()
; Cad files written to <project-root>/designs/jitx-design/altium

Description

The set-value-format-options command will set the preferences to generate component values. It is optional. export-cad will work even if this command is not present. By default, without this command the output will look like these: By way of examples: | |Value |Output| |----------|------------------|------| |Resistor |3300 Ohm |3K3 | | |100 Ohm |100R | |----------|------------------|------| |Capacitor |0.0000047 Farad |4.7u | | |0.000000010 Farad |10n | |----------|------------------|------| |Inductor |0.010 Henry |10m |

If a string is present in the format-options, the value will be different: "use-small-k" => 3300-ohm Resistor Value will be: 3k3 "use-greek-mu" => 0.0000047-farad Capacitor Value will be: 4.7μ "use-greek-ohm" => 100-ohm Resistor Value will be: 100Ω "R-unit-always-present" => 3300-ohm Resistor Value will be: 3K3R or 3K3Ω "LC-units-always-present" => 0.0000047-farad Capacitor Value will be: 4.7uF "R-not-replace-decimal-by-quantifier" => 3300-ohm Resistor Value will be: 3.3K "LC-replace-decimal-by-quantifier" => 0.0000047-farad Capacitor Value will be: 4u7 "keep-decimal" => 100-ohm Resistor Value will be: 100.0R "C-replace-n-by-K" => 0.000000010-farad Capacitor Value will be: 10K or 10k (if "use-small-k" is also present) "add-tolerance" => 0.010-henry Inductor Value will be: 10m ± 20% (depends on actual tolerance value)

set-export-board?

defn set-export-board? (b:True|False)

Set whether export-cad should generate board files.

Syntax

set-export-board?(true) ; or false

Description

By default, the export command will generate a board. Use set-export-board? to control whether it is generated or not.

set-export-schematic?

defn set-export-schematic? (b:True|False)

Set whether export-cad should generate schematic files.

Syntax

set-export-schematic?(true) ; or false

Description

By default, the export command will generate a schematic. Use set-export-schematic? to control whether it is generated or not.

export-bom

defn export-bom () -> False

Export the bill of materials (BOM) to the design directory.

Syntax

set-bom-vendors([
  "Allied Electronics & Automation",
  "Arrow Electronics",
  "Avnet",
  "Digi-Key",
  "Future Electronics",
  "Mouser",
  "Newark"
])

set-bom-design-quantity(100)

;write the BOM files to disk
export-bom()

Description

The export-bom command will create the following files in the design directory :

<design-directory>/bom/<design>.tsv
<design-directory>/bom/<design>.select

The .tsv file is a tab separated value that can be imported by spreadsheet software to order parts. The formatting is not defined and subject to change. Parts are autoselected, unless overridden by the .select file.

set-bom-vendors

defn set-bom-vendors (vendors:Tuple<String>|False) -> False

Define the approved vendors used by the design.

Syntax

set-bom-vendors([
  "Allied Electronics & Automation",
  "Arrow Electronics",
  "Avnet",
  "Digi-Key",
  "Future Electronics",
  "Mouser",
  "Newark"
])

set-bom-design-quantity(100)

;write the BOM files to disk
export-bom()

Description

The set-bom-vendors command will define the list of approved parts vendors. Parts are queried from these vendors to be placed in the design.

set-bom-design-quantity

defn set-bom-design-quantity (quantity:Int) -> False

Set the quantity of boards to manufacturer when generating a BOM.

Syntax

set-bom-vendors([
  "Allied Electronics & Automation",
  "Arrow Electronics",
  "Avnet",
  "Digi-Key",
  "Future Electronics",
  "Mouser",
  "Newark"
])

set-bom-design-quantity(100)

;write the BOM files to disk
export-bom()

Description

The set-bom-design-quantity is used to define the number of boards to manufacturer. It is combined with the vendors list to automatically find parts from the vendors lists in the appropriate quantity to assemble the generated board design.

set-paper

defn set-paper (paper:Paper) -> False

Set the paper size used in schematic export

Syntax

set-paper(ANSI-A4)

Description

The set-paper command is used to define the paper size in the exported schematic files.

Valid values are :

public defenum Paper :
  ANSI-A0
  ANSI-A1
  ANSI-A2
  ANSI-A3
  ANSI-A4
  ANSI-A5
  ANSI-A
  ANSI-B
  ANSI-C
  ANSI-D
  ANSI-E

set-use-layout-sketch

defn set-use-layout-sketch () -> False

Configure the placer to run in sketch mode.

Syntax

set-use-layout-sketch()

Description

When running in sketch mode, the placer will not take Layout Groups into account (faster).

set-use-layout-groups

defn set-use-layout-groups () -> False

Configure the placer to run in groups mode.

Syntax

set-use-layout-groups()

Description

When running in groups mode, the placer will take Layout Groups into account (slower).

enable-spy

defn enable-spy () -> False

Dump the generated internal representation during compilation

Syntax

enable-spy()
evaluate(my-design)

Description

The enable-spy command is a debugging tool to dump the compiler's internal representation(s) into a human readable text form. It is generally only useful for analyzing internal compiler errors.

import-cad

defn import-cad (input-dir:String, output-dir:String, cad:CadSoftware) -> ImportCadResult
defn import-cad (input-dir:String, output-dir:String, cad:CadSoftware, field-mapping:Tuple<KeyValue<String String>>) -> ImportCadResult

Import CAD from KiCAD or Altium. Optional field-mapping can be used to change property field names, used only in KiCad. Possible target Fields are "Name", "Manufacturer", "MPN", "Description", case-sensitive. For example, you can map "Field1" to "Manfacturer" and "Part Desc" to "Description" by

val mapping = [ "Field1" => "Manufacturer" "Part Desc" => "Description" ]
import-cad("input-folder", "out-folder", Kicad, mapping)

Syntax

defpackage import-script :
  import core
  import jitx
  import jitx/commands

import-cad("input-directory", "output-directory", Altium)

Description

The import-cad command is used to read KiCAD or Altium files from input-directory and generate JITX code in output-directory. The currently supported CadSoftware values are :

public defenum CadSoftware :
  Kicad ; Experimental v6 support
  Altium 

Requirements

• The input directory must exist.
• input may not be a symbolic link.
• The output directory must not exist or be an empty directory
• When importing a board, schematic, and netlist:
  • Reference designators in the project files must be consistent.
  • Nets on the board, in the schematic, and netlist must be consistent.
  • "Consisent" means components may not be present on the board or schematic that aren't in the other, nets on the board/schematic/netlist must be the same, etc.
• Altium constraints :
  • Only files generated with the JITX Altium Extension will be imported. These are files with the following extensions :
    • (SCHLIB).JSON
    • (SCHDOC).JSON
    • (PRJPCB).JSON
    • (PCBLIB).JSON
    • (PCBDOC).JSON
• Kicad constraints :
  • Only files of the following file extension will be imported :
    • kicad_mod
    • kicad_sym
    • kicad_pcb
    • kicad_sch
    • net
    • kicad_pro
    • fp-lib-table
  • Only Kicad 6 is supported.
  • A netlist (.net) file must be provided.
  • Only one .kicad_pcb, .kicad_pro, and .net file may exist in the input directory.
• 3D Model Files:
  • only .step, .stp, and .wrl files will be copied to imported code.
• BOM Files:
  • BOM files must be named jitx-import-bom.tsv and be of the correct schema

min-space

defn min-space (s:Seqable<Shape>) -> Double

Compute the minimum space in a sequence of shapes.

Syntax

val shapes = [
  loc(1.0, 1.0) * Circle(0.001)
  loc(2.0, -1.0) * Circle(0.01)
]

println(min-space(shapes))

Description

The minimum space in a set of shapes is defined as the smallest distance between non overlapping sides of the shapes. This command is useful when writing DRC checks.

min-width

defn min-width (s:Seqable<Shape>) -> Double

Compute the minimum width in a sequence of shapes.

Syntax

val r1 = loc(-0.5, 0.0) * Rectangle(2.0, 1.0)
val r2 = loc( 0.5, 0.0) * Rectangle(2.0, 1.0)
val mw = min-width([r1, r2])
println(mw)

Description

The minimum width is defined as the minimum length of a line you can draw inside the shape between two segments (on the boundary) with opposite directions and overlapping.

offset

defn offset (s:Shape, amount:Double) -> Shape

Compute a shape that is "offset" from another by a fixed distance.

Syntax

val rect = Rectangle(10.0, 10.0)
val offset-rect = offset(rect, 1.0)
println(offset-rect) ; Rectangle(11.0, 11.0)

Description

The offset command derives a new shape from an existing one using a factor to expand the dimensions in x/y directions. This is useful when creating new shapes that are a fixed size larger than some root shape.

dims

defn dims (s:Shape) -> Dims

Compute the x/y dimensions of a shape.

Syntax

val shape = Union([
  Rectangle(10.0, 10.0)
  loc(2.0, 0.0 * Circle(10.0, 10.0)
])

println(dims(shape))

Description

The dims command takes a shape as an argument and computes the x/y dimensions (bounding box) of the complete shape. This is useful for simple collision detection and size computation.

expand

defn expand (s:Shape, amount:Double) -> Shape

Expand a shape by a fixed distance.

Syntax

val shape = Rectangle(10.0, 10.0)
val expanded = expand(shape, 1.0)
println(expanded)

Description

The expand command computes an "expanded" shape, which is a shape that is exactly amount distance away from the perimeter of s.

Lookup

ref

defn ref (a:JITXObject) -> Ref

Get the associated Ref of an object instance.

Syntax

pcb-module my-module :
  inst U1 : ocdb/manufacturers/MANU/MPN

  ; 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) -> False

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)

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)

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)

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)

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)

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)

Get the ports of a component, bundle, or module

Syntax

val ports = ports(ocdb/utils/bundles/jtag())
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)

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)

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)

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)

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)

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 : ocdb/components/abracon/AMB7/component(10.0e6)
  print-def(instance-definition(X))

Description

The instance-definition introspection retrieves the pcb-* definition that corresponds to a given component or module.

instance-type

public defn instance-type (obj:JITXObject) -> InstanceType :
  instance-type(JITX-CLIENT, obj)

public defenum InstanceType :
  SingleComponent
  SingleModule
  InstanceArray

Determine if an instance is a component, module, or array.

Syntax

pcb-module my-module :
  inst X : ocdb/components/abracon/AMB7/component(10.0e6)
  print-def(instance-type(X))

Description

The instance-type introspection retrieves the type of an instance.

mpn?

defn mpn? (c:Instantiable) -> 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

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.

reference-prefix?

defn reference-prefix? (c:Instantiable) -> 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

Get the emodel of a component, if it exists.

Syntax

pcb-module my-module :
  inst U : ocdb/components/abracon/AMB7/component(10.0e6)
  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

Check if a pin 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.

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 () -> False|Board

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

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.

Part Query API

The part query API is a low level API that returns actual components that meet the specified criteria.

We recommend using the Higher level Part Query accessors to query for parts.

The JITX database currently supports 4 categories. Detailed information on how to query each category can be found at:

• Resistors
• Capacitors
• Inductors
• Microcontrollers

The API queries the JITX database containing millions of parts and supports:

• filtering on attributes by equality, inequality or set of values,
• optimizing on an attribute (for example smallest area or price),
• querying for a specific number of parts
• requiring some attributes to exist in the resulting parts (for example tolerance)
• listing the available values for an attribute after filtering on other query parameters
• integrate real-time sourcing data to the query

Part query results are cached in memory for future use. This can be particularly useful when using the jitx repl. The cache is lost when a jitx program exits.

Caching

Internet is required to perform the part queries the first time. All results are then cached to disk to be reused across sessions. To query fresh parts, clear the cache with:

stanza> import jitx/commands
stanza> clear-dbquery-cache()

Accessors

The part query API is imported from the package jitx/commands. Here are the accessors:

public defn dbquery (params: Tuple<KeyValue<String, Tuple<String>|Tuple<Double>|String|Double|Int>>, limit: Int) -> Tuple<JSON>

The maximum number of components that can be queried at a time by dbquery is 1000. Any value of limit in dbquery above 1000 will throw an error.

public defn dbquery-all (params: Tuple<KeyValue<String, Tuple<String>|Tuple<Double>|String|Double|Int>>) -> Tuple<JSON>

dbquery-all calls dbquery with a limit of 25. As our part database contains millions of resistors and hundreds of thousands of inductors and capacitors, dbquery-all cannot return all components that meet the query.

public defn dbquery-first (args: Tuple<KeyValue<String, Tuple<String>|Tuple<Double>|String|Double|Int>>) -> JSON

dbquery-first calls dbquery with a limit of 1, if no component is found, it throws a NoComponentMeetingRequirements

Examples

Querying the smallest 1Ω resistor:

stanza> import jitx/commands
stanza> val resistor-json = dbquery-first(["category" => "resistor", "resistance" => 1.0, "_sort" => ["area"]])
stanza> println(resistor-json)
JObject(entries = ["_id" => "0f3e3eeb6393f83d591a03c3" "trust" => "low" "category" => "resistor" "mpn" => "CRCW01001R00FYEL" "mounting" => "smd" "manufacturer" => "Vishay Dale" "type" => "chip" "dimensions" => JObject(entries = ["x" => 0.4 "y" => 0.2 "z" => 0.15 "area" => 0.08]) "stock" => 9355.0 "minimum_quantity" => 1.0 "metadata" => JObject(entries = ["datasheets" => "https://www.vishay.com/docs/20056/crcw01005e3.pdf" "image" => "//media.digikey.com/Renders/Vishay%20Dale%20Renders/CRCW-01005-(0402metric).jpg" "digi-key-part-number" => "541-4281-6-ND" "description" => "RES SMD 1 OHM 1% 1/32W 01005" "factory-stock" => 0.0 "unit-price" => "Digi-Reel" "qty" => 0.0 "packaging" => "Digi-Reel®" "series" => "CRCW" "supplier-device-package" => 1005.0 "number-of-terminations" => 2.0]) "tolerance" => JObject(entries = ["min" => -0.01 "max" => 0.01]) "resistance" => 1.0 "rated-power" => 0.03 "composition" => "thick-film" "tcr" => JObject(entries = ["pos" => -0.0002 "neg" => 0.0006]) "rated-temperature" => JObject(entries = ["min" => -55.0 "max" => 125.0]) "case" => "01005" "update_date" => "2021-09-04T01:35:34.335000"])
stanza> import ocdb/utils/db-parts
stanza> import json
stanza> println $ Resistor(resistor-json as JObject)
Resistor(
  mpn = CRCW01001R00FYEL
  trust = low
  (x, y, z) = (0.4, 0.2, 0.15)
  mounting = smd
  rated-temperature = MinMaxRange(min=-55.0, max=125.0)
  case = 01005
  type = chip
  tolerance = MinMaxRange(min=-0.01, max=0.01)
  resistance = 1.0
  composition = thick-film
  rated-power = 0.03
  TCR = TCR(positive=-0.0002, negative=0.0006)
  sourcing = ESR(price=false, minimum-quantity=1, stock=9355)
  metadata =
    "datasheets" => "https://www.vishay.com/docs/20056/crcw01005e3.pdf"
    "image" => "//media.digikey.com/Renders/Vishay%20Dale%20Renders/CRCW-01005-(0402metric).jpg"
    "digi-key-part-number" => "541-4281-6-ND"
    "description" => "RES SMD 1 OHM 1% 1/32W 01005"
    "factory-stock" => 0.0
    "unit-price" => "Digi-Reel"
    "qty" => 0.0
    "packaging" => "Digi-Reel®"
    "series" => "CRCW"
    "supplier-device-package" => 1005.0
    "number-of-terminations" => 2.0)

Querying some capacitors (at most 25 by default):

$ jitx repl
stanza> import jitx/commands
stanza> val capacitor-jsons = dbquery-all(["category" => "capacitor"])

Querying 200 inductors with 1µH inductance:

$ jitx repl
stanza> import jitx/commands
stanza> val inductor-jsons = dbquery(["category" => "inductor", "inductance" => 1.0e-6], 200)

Querying the list of available mcu cores in the JITX database:

$ jitx repl
stanza> import jitx/commands
stanza> val cores = dbquery-all(["category" => "microcontroller", "_distinct" => "core"])
stanza> println(cores)
["ARM Cortex-M0" "ARM Cortex-M0+" "ARM Cortex-M3" "ARM Cortex-M4" "ARM Cortex-M7"]

Querying the list of available packages for smd resistors:

$ jitx repl
stanza> import jitx/commands
stanza> println $ dbquery-all(["category" => "resistor" "mounting" => "smd", "_distinct" => "case"])
[JNull() "009005" "01005" "0201" "02016" "0202" "0302" "0303" "0402" "0404" "0503" "0505" "0603" "0612" "0805" "1206" "1210" "1218" "1812" "2-SMD, J-Lead" "2010" "2010 J-Lead" "2012 J-Lead" "2015" "2512"]

Creating a module with the cheapest smd resistor with a resistance of 1Ω±5%:

#use-added-syntax(jitx)
defpackage my-design :
  import jitx/commands

pcb-module my-module :
  inst resistor : dbquery-first(["resistance" => 10.0 "tolerance" => 0.05 "mounting" => "smd" "_sort" => ["cost"]])

Querying the list of packages available for mcus:

$ jitx repl
stanza> import jitx/commands
stanza> val packages = dbquery-all(["category" => "microcontroller" "_distinct" => "mfg-package"])
stanza> println(length(packages))
28
stanza> println(packages)
["LFBGA100" "LQFP100" "LQFP144" "LQFP176" "LQFP208" "LQFP48" "TFBGA216" "TFBGA225" "TFBGA64" "UFBGA100" "UFBGA132" "UFBGA169" "UFBGA64" "UFQFPN28" "UFQFPN32" "UFQFPN48" "WLCSP100" "WLCSP104" "WLCSP156" "WLCSP168" "WLCSP180" "WLCSP25" "WLCSP36" "WLCSP49" "WLCSP63" "WLCSP64" "WLCSP81" "WLCSP90"]

Querying the list of mcu mpns for package "WLCSP49":

$ jitx repl
stanza> import jitx/commands
stanza> val mpns = dbquery(["category" => "microcontroller" "mfg-package" => "WLCSP49" "_distinct" => "mpn"], 500)
stanza> println(length(mpns))
21
stanza> println(mpns)
["STM32F071CBY6" "STM32F071CBY7" "STM32F072CBY6" "STM32F072CBY7" "STM32F078CBY6" "STM32F303C8Y6" "STM32F318C8Y6" "STM32F334C8Y6" "STM32F334C8Y7" "STM32F411CCY6" "STM32F411CCY7" "STM32F411CEY6" "STM32F411CEY7" "STM32L071CBY6" "STM32L071CBY7" "STM32L071CZY6" "STM32L071CZY7" "STM32L073CZY6" "STM32L073CZY7" "STM32L082CZY6" "STM32L082CZY7"]

Querying the list for all bundles for all mcus with the package "WLCSP49":

$ jitx repl
stanza> import jitx/commands
stanza> val mcus = dbquery(["category" => "microcontroller" "mfg-package" => "WLCSP49"], 500)
stanza> println(length(mcus))
21
stanza> import json
stanza> println $ to-tuple $ to-hashset<String> $ for mcu in (mcus as Tuple<JObject>) seq-cat : mcu["bundles"] as Tuple<String>
["RCC_OSC32_OUT" "USART3_RTS" "I2S1_CK" "SPI1_SCK" "RCC_OSC_OUT" "USART4_RTS" "LPUART1_DE" "LPUART1_CTS" "SPI2_SCK" "USART5_RTS" "SPI3_SCK" "SPI4_SCK" "LPUART1_TX" "SPI5_SCK" "SYS_JTDO-SWO" "I2S5_SD" "LPUART1_RX" "I2S4_SD" "I2S3_SD" "I2C1_SDA" "I2S2_SD" "I2C2_SDA" "I2S1_SD" "I2C3_SDA" "SYS_SWCLK" "SYS_JTDO-TRACESWO" "SPI5_MISO" "SPI5_MOSI" "SPI4_MISO" "SPI4_MOSI" "USART1_CTS" "USART5_DE" "SPI3_MISO" "SPI3_MOSI" "USART2_CTS" "I2S5_WS" "LPUART1_RTS" "USART4_DE" "SPI2_MISO" "SPI2_MOSI" "USART3_CTS" "I2S4_WS" "USART3_DE" "USART6_TX" "SPI1_MISO" "SPI1_MOSI" "USART4_CTS" "RCC_OSC_IN" "I2S3_WS" "USART2_DE" "USART5_TX" "RCC_OSC32_IN" "I2S2_WS" "CAN_TX" "SPI1_NSS" "USART1_DE" "USART4_TX" "USART6_RX" "SYS_SWDIO" "I2C1_SCL" "I2S1_WS" "SPI2_NSS" "USART3_TX" "USART5_RX" "SYS_JTCK-SWCLK" "I2C2_SCL" "CAN_RX" "SPI3_NSS" "USART2_TX" "USART4_RX" "I2C3_SCL" "SPI4_NSS" "USART1_TX" "USART3_RX" "USART5_CK" "SPI5_NSS" "USART2_RX" "USART1_RX" "USART3_CK" "USART2_CK" "SYS_JTMS-SWDIO" "USART1_CK" "I2S5_CK" "I2S1_MCK" "I2S4_CK" "I2S2_MCK" "USART1_RTS" "I2S3_CK" "I2S3_MCK" "USART2_RTS" "I2S2_CK"]

Supported parameters

The supported special query parameters are:

• _exist : List of attributes that the returned documents must contain.
• _sort : The returned documents will be sort according to the list of attributes specified by this parameter, applied in the order they appear. Sorting in descending fashion can be obtained by starting a sorting attribute by a minus sign "−". This can take 2 additional value besides the list of existing properties: area is an alias for dimensions.area and cost is an alias for price.
• _distinct : If this parameter exist, it must be an attribute string, the query will return the set of available values for the specified attribute in the list of documents that meet all the query constraints.

Regular filter properties:

• We can filter on a part attribute : {"category": "resistor"}.
• We can filter on a capacitance, resistance and inductance, those constraints are replaced by interval allowing for queries with a precision of 0.0005Ω, 0.01A and 0.01F respectively.
• We can filter on a tolerance : {"tolerance": 0.05} will constrain the tolerance to be an exact match {"tolerance": {"min": -0.05, "max": 0.05}}. Returns 500 Bad Request if this is not a positive double
• We can filter on a nested parameter using . : {"dimensions.x": 11}
• We can filter on a list of values giving a list : {"case": ["Axial", "0402"]}
• We can filter with an inequality prepending min- or max- : {"max−rated-power": 0.05}.
• max-x, max-y and max-z are shorthands for max-dimensions.x, max-dimensions.y, max-dimensions.z
• We interpret minimum_quantity as a floor on bulk purchase size; we automatically convert minimum_quantity to max-minimum_quantity.

Typo checker

The typo checker is triggered when an unsupported parameter is used in a query where the "category" parameter is present and amongst ["resistor", "capacitor", "inductor", "microcontroller"]. When the typo checker detects an unsupported parameter, it will throw an error printing the list of supported parameters of the category. Example:

$ jitx repl
stanza> import jitx/commands
stanza> println $ dbquery-all(["category" => "capacitor" "typo" => 1.0e-06])
The invalid attributes ("typo") are used in the query ["category" => "capacitor" "typo" => 1.0e-06].
Valid attributes for category capacitor must be amongst:
  - anode
  - capacitance
  - case
  - category
  - dimensions.area
  - dimensions.x
  - dimensions.y
  - dimensions.z
  - electrolyte
  - esr
  - esr_frequency
  - manufacturer
  - minimum_quantity
  - mounting
  - mpn
  - price
  - rated-current-pk
  - rated-current-rms
  - rated-temperature.max
  - rated-temperature.min
  - rated-voltage
  - rated-voltage-ac
  - stock
  - temperature-coefficient.change
  - temperature-coefficient.code
  - temperature-coefficient.lower-temperature
  - temperature-coefficient.raw_data
  - temperature-coefficient.tolerance
  - temperature-coefficient.upper-temperature
  - temperature-coefficient.value
  - tolerance
  - tolerance.max
  - tolerance.min
  - trust
  - type
  - update_date

Sourcing data

If the request contains the attributes _stock or/and _sellers: more advanced part sourcing data will be independently queried and integrated to the results, disregarding sellers that:

• are not in the list
• do not have an inventory level above the queried stock
• do not have a pricing offering with a minimum quantity lower that the queried stock In this case, any part that does not have sourcing data that meets the criteria above will be ignored.

If _stock is 0 or _sellers is [], then no filtering out is done using those properties. In particular querying with both [_"stock" => 0, "_sellers" => []] will append the whole part sourcing data to the result for any sellers at any inventory stock and with any price offerings.

We recommend to always provide a list of allowed sellers as the part sourcing data contains unverified sellers that may be intermediaries.

A sellers key will be added to the returned json with the sourcing data meeting the request. The best price from each seller is aggregated in the resolved_price key in each seller data. The best price from all qualifying offerings is returned in the resolved_price key at the root of the json.

"sellers": [
    {
        "company_name": ...,
        "resolved_price": ...,
        "offers": [{
                "inventory_level": ...,
                "prices": [{"quantity": ..., "converted_price": ...}]
        },...]
    }
]
"resolved_price": ...

Sorting by price

cost and price can be used used interchangeably. We are using cost in what follows. If _sort is ["cost"] (respectively ["-cost"]), results will be sorted by increasing (respectively decreasing) price.

If neither _stock nor _sellers are parameters of the query, then the price used to sort on for resistors, capacitors and resistors is the price for 1 unit from Digikey (updated every week). For the microcontroller category, no sorting on price will occur, please see the next section.

If _stock or _sellers are parameters of the query, then real-time sourcing data is integrating in the query (see section "Sourcing data" above). At most 1000 parts meeting the query are retrieved from the JITX database, then sourcing data for each part is retrieved, the price used to sort on is the resolved_price attribute.

Utilities

This section contains info on JITX utility functions.

Stateful

Stateful is a useful tool for managing property states.

Data Types

public defstruct Stateful<K,V> :
  current: K|False
  states: Tuple<KeyValue<K,V>>

public defn Stateful<?K,?V> (states:Seqable<KeyValue<?K, ?V>>) -> Stateful
public defn Stateful<?K,?V> (current:JITXValue, states:Seqable<KeyValue<?K, ?V>>) -> Stateful

Stateful is a collection of states with a possibly current state.

• current: the current state, or false if there is no current state.
• states: mappings from a state's name to a value.

Function

public defn get<?K,?V> (s:Stateful<?K,?V>, state:?K) -> V :

Returns the value for the given state.

public defn state-names<?K,?V> (s:Stateful<?K,?V>) -> Tuple<K> :

Returns the names of all states.

Additional Syntaxes

state(<object>.<property>) = <state>

Set the property's state to state. It is required that object.property is a Stateful. This statement must be declared inside a pcb-module, pcb-component, or support option.

state(<object>.<property>)

Get the property's current state. It is required that both object.property is a Stateful and there is a current state.

state?(<object>.<property>)

Get the property's current state. It is required that object.property is a Stateful. Returns false if there is no current state.

has-state?(<object>.<property>, <state>)

Returns whether state is one of object.property's states. It is required that object.property is a Stateful.

pcb-module :
  port p : pin[5]

  ;Assign a Stateful property to pin p[3] in a USB-powered system.
  ;The low state load-current is 100mA and the high state load-current is 1.5A.
  ;No initial state is assigned.
  property(p[3].load-current) = Stateful(["low" => 100.0e-3,
                                          "high" => 1.5])
  
  ;Try getting the current state. Returns false.
  state?(p[3].load-current)

  ;Set the state to "low".
  ;Much like properties, states can be set inside a module, component, or support option.
  state(p[3].load-current) = "low"

  ;Get the current state. Returns "low".
  state(p[3].load-current)

  ;Does the property have a "high" state? Returns true.
  has-state?(p[3].load-current, "high")

The above pcb-module demonstrates how all syntaxes can be used.

Toleranced

Toleranced is a useful tool for managing values with some tolerance.

Data Types

public defstruct Toleranced :
  typ:  Double
  tol+: Double
  tol-: Double

Toleranced is a generic value with upper and lower bound tolerances that may be off-center (upper tolerance != lower tolerance). It represents the inequality (typ - tol-) <= T <= (typ + tol+).

• typ: the typical value
• tol+: the upper tolerance
• tol-: the lower tolerance

Functions

public defn min-typ-max (min:Double, typ:Double, max:Double) -> Toleranced

Creates a Toleranced value from minimum/typical/maximum values.

public defn min-max (min:Double, max:Double) -> Toleranced

Creates a Toleranced value from minimum/maximum values with typ as the midpoint.

public defn tol% (typ:Double, tol+:Double, tol-:Double) -> Toleranced

Creates a Toleranced value using percentages (0.0 <= tol+/tol- <= 100.0) for +/- tolerance.

public defn tol% (typ:Double, tol:Double) -> Toleranced

Creates a symmetric Toleranced value using percentages (0.0 <= tol <= 100.0) for +/- tolerance.

public defn tol (typ:Double, tol+:Double, tol-:Double) -> Toleranced

Creates a Toleranced value using relative values for +/- tolerance.

public defn tol (typ:Double, tol:Double) -> Toleranced

Creates a Toleranced value using the symmetric range for +/- tolerance.

public defn tol+% (t:Toleranced) -> Double

Returns the upper tolerance, as a percentage.

public defn tol-% (t:Toleranced) -> Double

Returns the lower tolerance, as a percentage.

public defn max-value (t:Toleranced) -> Double

Returns the maximum value of the tolerance.

public defn typ-value (t:Toleranced) -> Double

Returns the typ value of the tolerance (not necessarily the center value).

public defn min-value (t:Toleranced) -> Double

Returns the minimum value of the tolerance.

public defn center-value (t:Toleranced) -> Double

Returns the center value of the tolerance, which may not be the typical value.

public defn in-range? (t:Toleranced, value:Double) -> True|False

Checks if a value is within the tolerance's range.

public defn in-range? (t:Toleranced, value:Toleranced) -> True|False

Checks if a value Toleranced min/max is within the first argument tolerance's min/max.

public defn tolerance-range (t:Toleranced) -> Double

Returns the difference between maximum and minimum values of the tolerance.

public defn minus (a:Toleranced, b:Toleranced) -> Toleranced
public defn minus (a:Double, b:Toleranced) -> Toleranced

Subtraction of Toleranced values. Arithmetic with Toleranced values are useful for the worst case analysis, but be aware the bounds can grow quickly so it's important to use realistic ranges.

public defn plus (a:Toleranced, b:Toleranced) -> Toleranced
public defn plus (a:Double, b:Toleranced) -> Toleranced

Addition of Toleranced values. See note under toleranced subtraction.

public defn divide (a:Toleranced, b:Toleranced) -> Toleranced
public defn divide (a:Double, b:Toleranced) -> Toleranced

Division of Toleranced values. See note under toleranced subtraction.

public defn times (a:Toleranced, b:Toleranced) -> Toleranced
public defn times (a:Double, b:Toleranced) -> Toleranced

Multiplication of Toleranced values. See note under toleranced subtraction.

Example usage

; Create a range between -0.3 and 5.0
val range-1 = min-max(-0.3, 5.0)

; Create a range within 20% of 500.0
val range-2 = tol%(500.0, 20.0)

; Check if range-2 includes range-1
in-range?(range-2, range-1)

; Get the minimum value of range-1
min-value(range-1)

ocdb/utils/design-vars

Design variables are configuration settings for OCDB applied to the current design (or sets of designs, in multi-board projects). These variables control generator mechanisms across OCDB.

Data Types

public pcb-enum ocdb/utils/design-vars/DensityLevel:
  DensityLevelA
  DensityLevelB
  DensityLevelC

DensityLevel is a helper enum that represents the desired density level of the current design (A, B, or C, with "A" being the least dense and "C" being the most dense). It is used to generate IPC compliant land patterns.

Global Variables

public var OPERATING-TEMPERATURE = min-max(0.0, 25.0)

The operating temperature range of the design (C).

public var OPTIMIZE-FOR = ["area"]

The desired optimization approach by JITX internal generators. Supported values are "area" and "cost".

public var MAX-Z = 500.0

The maximum height of a component (mm).

public var MIN-PKG = "0201"

The minimum package size of a passive component. Used to find components that can be placed by the fabricator when pulling components from the JITX database.

public var APPROVED-DISTRIBUTOR-LIST = ["Allied Electronics & Automation"
                                        "Arrow Electronics"
                                        "Avnet"
                                        "Digi-Key"
                                        "Future Electronics"
                                        "Mouser"
                                        "Newark"]

The list of approved distributors. Set it to false to allow any distributor.

public var DESIGN-QUANTITY = 100

The number of boards you intend to fabricate. Used to find components in stock when pulling components from the JITX database.

public var ALLOW-NON-STOCK = true

Whether to allow components to be out of stock. JITX gives warning messages when components are out of stock and ALLOW-NON-STOCK is true (the default bevavior). If ALLOW-NON-STOCK is false, JITX throws an exception when any component is out of stock.

public var PREFERRED-MOUNTING = "smd" 

The preferred mounting style of a component pulled from the JITX database. Supported values are ["smd", "through-hole"].

public var MIN-CAP-VOLTAGE = 10.0

Minimum voltage to allow for capacitors

public var DEFAULT-ALLOW-ALL-VENDOR-PART-NUMBERS = false

Use all parts from the Parts Database for existing parametric queries (e.g. chip-resistor). If false, restrict these queries to a set of parts with a higher confidence in quality.

public var DENSITY-LEVEL: DensityLevel = DensityLevelC

The preferred density level of the design. Used when generating land patterns.

public var MIN-SOLDER-MASK-SLIVER: Double = 0.15

The minimum space allowed between non overlapping regions of solder mask opening. Used when checking land patterns.

public var MIN-OUTER-LAYER-PAD-SIZE: Double = 0.2032 

The minimum size of a circular pad on the outer layers. Used when computing through hole land patterns.

public var MAX-HOLE-SIZE-TOLERANCE:  Double = 0.0508

The board fabricator's tolerance on the diameter of the largest hole (mm). Used when computing through hole land patterns.

public var MIN-HOLE-SIZE-TOLERANCE:  Double = 0.0508

The board fabricator's tolerance on the diameter of the smallest hole (mm). Used when computing through hole land patterns.

public var HOLE-POSITION-TOLERANCE:  Double = 0.0508

The board fabricator's tolerance on placing the center of any hole (mm). Used when computing through hole land patterns.

ocdb/utils/landpatterns

Land patterns (sometimes called footprints) are the geometry associated with a single package that is to be placed on a design. In JITX, they are represented using the pcb-landpattern statement. The package ocdb/utils/landpatterns contains utilities for generating optimized land-patterns from parameters.

Table of Contents

• Helpful References
• Definitions
• Two Pin Land Patterns
  • Chip Land Patterns
  • Through Hole Land Patterns
    • Radial Through Hole Land Patterns
    • Axial Through Hole Land Patterns
• Small Outline (SO) Land Patterns
  • Small Outline Transistor (SOT) Land Patterns
• QFP Land Patterns
• QFN Land Patterns
• BGA Land Patterns
  • Depopulation Modifiers
    • Full Matrix
    • Staggered Matrix
    • Perimeter Matrix
    • Thermally Enhanced Matrix
    • Equilateral Triangle Matrix
    • Custom Depopulation

Helpful References

• JEDEC JESD30E, "Descriptive Designation System for Semiconductor-device packages"
• IPC 7351B, Generic Requirements for Surface Mount Design and Land Pattern Standard

Definitions

• Package: the physical device that will be placed (including the exterior plastic packaging and metal leads or terminations of a component). A package has one or more leads or terminations..
• Lead or Termination: The conductors on the package that interface with the electrical device.
• Land Pattern: the geometry on the layers of the board that sits underneath the package. A landpattern has one or more pads or and zero or more layers.
• Pad: the geometry on the layers associated with a single lead or termination of the component.

Two Pin Land Patterns

Chip Land Patterns

Two pin chip land patterns are commonly used for passive devices. The following generators are used to generate land patterns for these components that are compliant with IPC specifications.

public defn make-two-pin-chip-landpattern (length:Toleranced,
                                           width:Toleranced,
                                           lead-length:Toleranced)

Create a two pin surface mount (chip) non-polarized land pattern.

• length: the length of the component.
• width: the width of the component.
• lead-length: the length of the leads of the component.

public defn make-two-pin-chip-landpattern (length:Toleranced,
                                           width:Toleranced,
                                           lead-length:Toleranced,
                                           polarized?:True|False)

Create a two pin surface mount (chip) land pattern with optional polarization

• length: the length of the component.
• width: the width of the component.
• lead-length: the length of the leads of the component.
• polarized?: true if the land pattern is polarized, false otherwise.

public defn make-two-pin-chip-landpattern (length:Toleranced,
                                           width:Toleranced,
                                           lead-length:Toleranced,
                                           lead-width:Toleranced)

Create a two pin surface mount (chip) land pattern with a lead width that is different from the component width.

• length: the length of the component.
• width: the width of the component.
• lead-length: the length of the leads of the component.
• lead-width: the width of the leads of the component, which may be different than the width of the component.

public defn make-two-pin-chip-landpattern (length:Toleranced,
                                           width:Toleranced,
                                           lead-length:Toleranced,
                                           lead-width:Toleranced,
                                           polarized?:True|False)

Create a two pin surface mount (chip) land pattern with a lead width that is different from the component width and optional polarization.

• length: the length of the component.
• width: the width of the component.
• lead-length: the length of the leads of the component.
• lead-width: the width of the leads of the component, which may be different than the width of the component.
• polarized?: true if the land pattern is polarized, false otherwise.

Example : A Surface Mount Capacitor

The associated datasheet can be found here

pcb-landpattern TH3Axxx : 
  make-two-pin-chip-landpattern(tol(3.2, 0.2), ; package-length, L
                                tol(1.6, 0.2), ; package-width, W
                                tol(0.8, 0.3), ; lead-length, P
                                tol(1.2, 0.1), ; lead-width, Tw
                                true)          ; polarized ?

Through Hole Land Patterns

Radial Through Hole Land Patterns

Supported two-pin through hole land patterns are either axial or radial.

public defn make-two-pin-radial-landpattern (component-diameter:Toleranced,
                                             lead-spacing:Double,
                                             lead-diameter:Toleranced)

Create a two-pin radial landpattern.

• component-diameter: the diameter of the component package
• lead-spacing: the distance between leads.
• lead-diameter: the diameter of the leads.

public defn make-two-pin-radial-landpattern (component-diameter:Toleranced,
                                             lead-spacing:Double,
                                             lead-diameter:Toleranced
                                             polarized?:True|False)

Create a two-pin radial landpattern with optional polarity.

• component-diameter: the diameter of the component package
• lead-spacing: the distance between leads.
• lead-diameter: the diameter of the leads.
• polarized?: true if the land pattern is polarized, false otherwise.

Axial Through Hole Land Patterns

public defn make-two-pin-axial-landpattern (component-diameter:Toleranced,
                                             lead-spacing:Double,
                                             lead-diameter:Toleranced)

Create a two-pin radial landpattern.

• component-diameter: the diameter of the component package
• lead-spacing: the distance between leads.
• lead-diameter: the diameter of the leads.

public defn make-two-pin-axial-landpattern (component-diameter:Toleranced,
                                            lead-spacing:Double,
                                            lead-diameter:Toleranced
                                            polarized?:True|False)

Create a two-pin radial landpattern with optional polarity.

• component-diameter: the diameter of the component package
• lead-spacing: the distance between leads.
• lead-diameter: the diameter of the leads.
• polarized?: true if the land pattern is polarized, false otherwise.

Small Outline Land Patterns

A small outline (SO) package is a package with pins along two sides of the component.

JEDEC symbol to JITX Generator Arguments

The following table may help in converting JEDEC-style dimensions into arguments for the JITX small outline landpattern generator.

public defn make-n-pin-soic-landpattern (num-pins:Int,
                                         pitch:Double,               ; e
                                         lead-span:Toleranced,       ; E
                                         package-length:Toleranced,  ; E1
                                         package-width:Toleranced,   ; D
                                         terminal-length:Toleranced, ; L
                                         terminal-width:Toleranced)  ; b

Create an SO land pattern.

• num-pins: the number of pins of the package (must be even).
• pitch: the pitch of the leads or terminals (mm), e in the table above.
• lead-span: the distance from lead-edge to lead-edge (mm), E in the table above.
• package-length: the size of the package in the same dimension as the lead-span (mm), E1 in the table above.
• package-width: the size of the package in the orthogonal dimension as lead-span (mm), D in the table above.
• terminal-length: the length of terminals or leads in contact with the land pattern (mm), L in the table above.
• terminal-width: the size of the terminals or leads in contact with the land pattern, in the orthogonal dimension to terminal-length (mm), b in the table above.

Example Usage

pcb-landpattern SO8N : 
  make-n-pin-soic-landpattern(8,    ; number of pins
                              1.27 ; pitch
                              min-typ-max(5.8, 6.0, 6.2) ; lead-span
                              min-typ-max(4.8, 4.9, 5.0) ; package-length
                              min-typ-max(3.8, 3.9, 4.0) ; package-width
                              min-typ-max(0.4, 0.8, 1.27) ; lead-length, using average as typical
                              min-typ-max(0.28, 0.38, 0.48)) ; lead-width, using average as typical

See The Model a Land Pattern tutorial for more details on parametric land pattern generation.

SOT Land Patterns

SOT landpatterns can be defined using the more general purpose API call, make-dual-row-smd-landpattern which creates a two-row SMD land pattern with different numbers of pins on either side.

public defn make-dual-row-smd-landpattern (primary-num-pins:   Int,
                                          secondary-num-pins:  Int,
                                          primary-pin-pitch:   Double,
                                          secondary-pin-pitch: Double,
                                          lead-span:           Toleranced,
                                          package-length:      Toleranced,
                                          package-width:       Toleranced,
                                          terminal-length:     Toleranced,
                                          terminal-width:      Toleranced,
                                          polarity-marker?:    True|False)

• primary-num-pins: the number of pins on one side of the land pattern
• secondary-num-pins: the number of pins on the other side of the land pattern
• primary-pin-pitch: the pitch of pins on the primary side of the land pattern
• secondary-pin-pitch: the pitch of the pins on the other side of the land pattern
• lead-span: the lead span across the land pattern
• package-length: the length of the package
• package-width: the width of the package
• terminal-length: the length of the terminals
• terminal-width: the width of the terminals
• polarity-marker?: whether to add a polarity marker to the landpattern or not

Example Usage

pcb-landpattern SOT-23 :
  make-dual-row-smd-landpattern(
      n1, n2, p1, p2, 
      lead-span, package-length, package-width, 
      terminal-length, terminal-width, 
      polarity-marker?: True|False) where :
  val n1 = 2
  val n2 = 1
  val p1 = 1.9
  val p2 = 0.0 ; unneeded for one pin
  val lead-span       = min-typ-max(2.1, 2.37, 2.634) ; E
  val package-length  = tol(1.3, 0.1)                 ; E1
  val package-width   = min-typ-max(2.8, 2.9, 3.04),  ; D
  val terminal-length = tol(0.4, 0.1)
  val terminal-width  = tol(0.5, 0.1)
  val polarity-marker? = false

QFP Land Patterns

A quad flat package (QFP) is a package with pins along all four sides of the component.

JEDEC symbol to JITX Generator Arguments

public defn make-qfp-landpattern (num-pins:Int,
                                  pitch:Double,               ; e
                                  lead-span:Toleranced,       ; E, D
                                  package-size:Toleranced,    ; E1, D1
                                  terminal-length:Toleranced, ; L
                                  terminal-width:Toleranced   ; b
                                  exposed-metal-heat-feature?:Shape ; optional thermal pad

• num-pins: the number of pins of the package (must be even).
• pitch: the pitch of the leads or terminals (mm), e in the table above.
• lead-span: the distance from lead-edge to lead-edge (mm), E in the table above.
• package-size: the size of the package, E1, D1 in the table above. The package is assumed to be square.
• terminal-length: the length of terminals or leads in contact with the land pattern (mm), L in the table above.
• terminal-width: the size of the terminals or leads in contact with the land pattern, in the orthogonal dimension to terminal-length (mm), b in the table above.
• exposed-metal-heat-feature?: an optional parameter for a thermal pad shape.

Example Usage

pcb-landpattern QFP-100 :
  make-qfp-landpattern(
      num-pins, pitch, 
      lead-span, package-size,
      terminal-length, terminal-width,
      thermal-pad) where :
    val num-pins     = 100 ; the total number of pins
    val pitch        = 0.5 ; the distance between pin centers
    val lead-span    = min-typ-max(15.8, 16.0, 16.2) ; the distance between the outer edges of the leads
    val package-size = min-typ-max(13.8, 14.0, 14.2) ; the size of the package, assumed to be square
    val terminal-width   = min-typ-max(0.17, 0.22, 0.27) ; the width of the leads
    val terminal-length  = min-typ-max(0.45, 0.60, 0.70) ; the length of the leads
    val thermal-pad = false

QFN Land Patterns

A quad flat package no-lead (QFN) is a quad landpattern where the terminals are pads on the underside of the component, as opposed to leads that extend outside the component (see QFP Land Patterns).

JEDEC symbol to JITX Generator Arguments

public defn make-qfn-landpattern (num-pins:Int, 
                                  pitch:Double, ; e
                                  package-size:Toleranced, ; E, D
                                  terminal-length:Toleranced, ; L
                                  terminal-width:Toleranced, ; b
                                  corner-pads?:False|[Pad, Pad], ; L1 x b
                                  exposed-metal-heat-feature?:Shape|False) : ; optional thermal pad

• num-pins: the number of pins of the package (must be even).
• pitch: the pitch of the leads or terminals (mm), e in the table above.
• package-size: the size of the package, E, D in the table above. The package is assumed to be square.
• terminal-length: the length of terminals or leads in contact with the land pattern (mm), L in the table above.
• terminal-width: the size of the terminals or leads in contact with the land pattern, in the orthogonal dimension to terminal-length (mm), b in the table above.
• corner-pads?: optional pair of pcb-pad definitions to use to replace the corner pads on the landpattern.
• exposed-metal-heat-feature?, an optional

Example Usage

pcb-landpattern QFN-28 :
  make-qfn-landpattern(
      num-pins, pitch, 
      package-size, lead-length, lead-width
      corner-pads, 
      thermal-pad,) where :
    val num-pins     = 28  ; the total number of pins, must be divisible by 4
    val pitch        = 0.5 ; the pitch of the pins
    val package-size = min-typ-max(3.90, 4.00, 4.10) ; the size of the package, assumed to be square
    val lead-length  = min-typ-max(0.30, 0.40, 0.50) ; the length of the lead terminals
    val lead-width   = min-typ-max(0.20, 0.25, 0.30) ; the width of the lead terminals
    
    ; Optional Corner Pad Modifiers
    val corner-pads  = [
      smd-pad(loc(-0.1, 0.0) * Rectangle(0.45, 0.21))
      smd-pad(loc(-0.1, 0.0) * Rectangle(0.45, 0.21))
    ]

    ; Optional thermal pad
    val thermal-pad = false

Note: some trial and error might be required to find dimensions for corner pad overrides. In this case, the length was found using the max value of L1 in the table, and the width was found empirically by measuring the width of the other pads.

BGA Land Patterns

A ball grid array (BGA) package uses a matrix of solder balls on the bottom of the package, as opposed to exposed metal terminals.

JEDEC symbol to JITX Generator Arguments

                                     num-cols:Int,
                                     pitch:Double,
                                     ball-diameter:Double,
                                     package-length:Toleranced,
                                     package-width:Toleranced,
                                     modifier:BGAModifier) :

• num-rows : the number of rows of package
• num-cols : the number of columns of the package
• pitch : the pitch of the solder bumps
• ball-diameter : the nominal/typical diameter of the solder balls
• package-length : the length of the package
• package-width : the width of the package
• modifier : the depopulation and/or pitch modifier

Example Usage

pcb-landpattern BGA-64 :
  make-bga-landpattern(
      num-rows, num-cols
      pitch, ball-diameter
      package-length, package-width
      modifier
  ) where :
    val num-rows = 8 ; Number of rows in the matrix
    val num-cols = 8 ; Number of columns in the matrix
    val pitch    = 0.50 ; the spacing between ball centers
    val ball-diameter = 0.28 ; the diameter of the solder balls
    val package-length = min-typ-max(4.85, 5.0, 5.15) ; the length of the package
    val package-width  = min-typ-max(4.85, 5.0, 5.15) ; the width of the package

    ; The BGA Modifier. See ocdb/utils/landpatterns for more
    ; modifiers, supported are StaggeredMatrix, EquilateralTriangleMatrix,
    ; PerimeterMatrix, ThermallyEnhancedMatrix.
    val modifier = FullMatrix()

Depopulation Modifiers

The make-bga-package argument uses a special argument named modifier which allows for a variety of depopulation and ball spacing strategies. The currently supported depopulation modifiers are:

FullMatrix

In a FullMatrix (the default) no pads will be depopulated.

defn FullMatrix () -> BGAModifier

StaggeredMatrix

In a StaggeredMatrix, every other pad is depopulated.

defn StaggeredMatrix () -> BGAModifer

PerimeterMatrix

In a PerimeterMatrix, a range of rows and columns in the center will be depopulated

defn PerimeterMatrix (rows:Range, cols:Range) -> BGAModifer

• rows: the range of rows to depopulate
• cols: the range of cols to depopulate

Usage :

  ; rows 3,4,6 and columns 4,5 will be depopulated.
  val modifier = PerimeterMatrix(3 through 6, 4 through 5)

ThermallyEnhancedMatrix

A ThermallyEnhancedMatrix is like a PerimeterMatrix, except with some region in the center remaining populated.

defn ThermallyEnhancedMatrix (perimeter-rows:Range, perimeter-cols:Range
                              interior-rows:Range, interior-cols:Range ) -> BGAModifer

• perimeter-rows : the range of rows to depopulate
• perimeter-cols : the range of columns to depopulate
• interior-rows : the range of rows in the center to remain populated
• interior-cols : the range of columns in the center to remain populated

Usage :

; Pins (5,5) through (6,6) will be populated, while the other
; pins within the range (4,4) through (7,7) will be depopulated.
val modifier = ThermallyEnhancedMatrix(
  4 through 7, 4 through 7,
  5 through 6, 5 through 6,
))

EquilateralTriangleMatrix

An "EquilaterTriangleMatrix" is like a staggered matrix, but where the pads are all equistance from eachother. This means for any three adjacent pads with two in the same row or column, the centers of the pads form an equilateral triangle.

defn EquilateralTriangleMatrix () -> BGAModifier

CustomDepop

The CustomDepop modifier allows the caller to specify which pins are depopulated using a callback.

defn CustomDepop (callback: (Int, Int) -> True|False)

Usage :

  defn depop? (row:Int, col:Int) :
    ; Specify a list of custom depopulated pins
    val depopulated = [
      [0, 2]
      [0, 5]
      [2, 8]
      [3, 0]
      [5, 8]
      [6, 0]
      [8, 3]
      [8, 6]
    ]
    contains?(depopulated, [row, col])

  val modifier = CustomDepop(depop?)

ocdb/utils/land-protrusions

ocdb/utils/land-protrusions is a set of lookup tables used to satisfy IPC compliance during the generation of land patterns. It defines a set of LandProtrusionTypes that represent metadata about package leads or terminations that is used alongside DensityLevel in order to compute offsets to the pads and courtyards of land patterns.

Data Types

public pcb-enum ocdb/utils/land-protrusions/LandProtrusionType :
  SmallFlatRibbonLLeads,  ; Flat ribbon L leads for pitch less than 0.0625mm
  SmallGullWingLeads,     ; Gull wwing leads with pitch less than 0.0625mm
  BigFlatRibbonLLeads,    ; Flat ribbon L leads for pitch greater than 0.0625mm
  BigGullWingLeads,       ; GullWing leads for pitch greater than 0.0625mm
  JLeads,                 ; J Leads
  SmallRectangularLeads,  ; Leads for rectangular components (chip capacitors, resistors, inductors) smaller than 0601
  BigRectangularLeads,    ; Leads for rectangular components (chip capacitors, resistors, inductors) 0601 or larger
  CylindricalLeads,       ; Cylindrical end cap leads
  LeadlessChipCarrierLeads, ; Lead less chip carrier leads
  ConcaveChipArrayLeads,    ; Concave chip array leads
  ConvexChipArrayLeads,     ; Convex chip array leads
  FlatChipArrayLeads,       ; Flat chip array leads
  ButtJointLeads,           ; Butt joint leads
  InwardFlatRibbonLLeads,   ; Inward flat ribbons L leads
  FlatLugLeads,             ; flat lug leads
  QuadFlatNoLeads,          ; quad flat components without leads
  SmallOutlineNoLeads,      ; small outline packages without leads
  SmallOutlineFlatLeads,    ; small outline flat leads
  ShortTwoPinCrystalLeads,  ; two pin crystal components shorter than 10mm
  ShortAluminumElectrolyticLeads, ; electrolytic capacitor shorter than 10mm
  TallTwoPinCrystalLeads,         ; two pin crystal components 10mm or taller
  TallAluminumElectrolyticLeads,  ; electrolytic capacitor 10mm or taller 

LandProtrusionType is a helper enum for various kinds of leads and terminations on components. It is used to configure their generated land patterns.

public pcb-struct ocdb/utils/land-protrusions/LeadFillets:
  toe:Double  ; space away from the component towards the board
  heel:Double ; space towards the component
  side:Double ; space on the edges of the lead
  courtyard-excess:Double ; additional area to add to the courtyard 

LeadFillets is a helper struct that represents the space added to pads and courtyard area when generating land patterns.

Functions

public defn lead-fillets (lead-type:LandProtrusionType) -> LeadFillets
public defn lead-fillets (lead-type:LandProtrusionType, density-level:DensityLevel) -> LeadFfillets

A helper function to lookup the LeadFillets corresponding to a LandProtrusionType given a DensityLevel. If not supplied, the DensityLevel used is the default defined in Design Variables

public defn bga-courtyard-excess (density-level:DensityLevel) -> Double

A helper function to lookup the courtyard excess when computing BGA land patterns.

Properties

JITX allows us to associate arbitrary properties with pins, components, and modules. These properties are used throughout OCDB for design calculations and design review checks. Everyone is free to define and use their own parameters, but when we collaborate on a shared set it is easier to write better automation. What follows is documentation of the properties defined in OCDB.

Component properties

These are properties associated with components, including passive components like resistors, capacitors, and inductors.

Generic properties

These properties apply to all components.

Resistor properties

These are properties associated with resistors, as used by gen-res-cmp in ocdb/utils/generic-components.

Capacitor properties

These are properties associated with capacitors, as used by gen-cap-cmp in ocdb/utils/generic-components.

Inductor properties

These are properties associated with inductors, as used by gen-ind-cmp in ocdb/utils/generic-components.

Crystal properties

These are properties associated with crystals, as used by gen-xtal-cmp in ocdb/utils/generic-components.

public pcb-struct ocdb/utils/property-structs/CrystalResonator :
  load-capacitance:Double     ; Load capacitance in Farads                
  shunt-capacitance:Double    ; Shunt capacitance in Farads                
  motional-capacitance:Double ; Motional capacitance in Farads                    
  ESR:Double                  ; Series resistance of crystal in Ohms  
  frequency:Double            ; Fundamental frequency in Hz        
  frequency-tolerance:Double  ; Frequency tolerance in Hz                
  max-drive-level:Double      ; Max drive level in W      

; Example call
  property(self.crystal-resonator) = ocdb/utils/property-structs/CrystalResonator(cl, cs, cm, esr, f, df * f, dl)

Pin properties

These properties are associated with component pins like power, reset, and logic pins.

Power pins

Logic pins

Digital pins

These are properties to check the generic rated voltage and ESD protection of pins, used by the checks in ocdb/utils/checks. | Name | Type | Values | Unit | Description | |:-----|:-----|:-------|:-----|:------------| | generic-pin | GenericPin() | see below | | Properties for rated voltage and ESD protection. |

; Library property name: generic-pin
public pcb-struct ocdb/utils/property-structs/GenericPin :
  max-voltage:Toleranced|RelativeVoltage    ; Maximum voltage that can be applied to pin (V)
  rated-esd:Double                          ; Rated ESD voltage (V)

; Example call
property(self.SDA.generic-pin) = GenericPin(min-max(-0.3, 3.6), 1500.0)

; Library property name: digital-input
public pcb-struct ocdb/utils/property-structs/DigitalInput :
  vil:Toleranced|RelativeVoltage    ; Range of voltages that will read as logic low (V)
  vih:Toleranced|RelativeVoltage    ; Range of voltages that will read as logic high (V)
  vdd-pin:JITXObject                ; Pin that powers the high reference 
  gnd-pin:JITXObject                ; Pin that powers the low reference
  leakage-current:Double            ; Leakage current in Amps

; Example call
property(UART-RX.digital-input) = DigitalInput(0.4, 0.7 * vcc, VCCIO, GND, 1.0e-6)

; Library property name: digital-output
public pcb-struct ocdb/utils/property-structs/DigitalOutput :
  driver:LogicFamily          ; Driver model of the output
  tristateable:True|False     ; Can this pin be put in a high-impedance mode?
  vdd-pin:JITXObject          ; Pin that powers the high reference 
  gnd-pin:JITXObject          ; Pin that powers the low reference

; Example Call
property(UART-TX.digital-output) = DigitalOutput(CMOSOutput(min-max(0.3, 0.5), min-max(2.6, 3.3)), false, VCCIO, GND)

; Library property name: digital-io
public pcb-struct ocdb/utils/property-structs/DigitalIO :
  driver:LogicFamily                ; Driver model of the output
  vil:Toleranced|RelativeVoltage    ; Range of voltages that will read as logic low (V)
  vih:Toleranced|RelativeVoltage    ; Range of voltages that will read as logic high (V)  gnd-pin:JITXObject          ; Pin that powers the driver low reference
  vdd-pin:JITXObject                ; Pin that powers the high reference 
  gnd-pin:JITXObject                ; Pin that powers the low reference
  leakage-current:Double            ; Leakage current in Amps

; Example call
property(PA[3].digital-io) = DigitalIO(CMOSOutput(min-max(0.0, 0.4), min-max(3.3 - 0.4, 3.3)), typ(0.3 * 3.3), typ(0.7 * 3.3), self.VDD, self.VSS, 50.0e-9)

Closest Standard Value

How to find the closest standard value for a resistor, capacitor, or inductor.

If you've computed the value you need for a resistor, capacitor, or inductor, and now you need to compute the closest normal value to that computed value, you can use closest-std-val.

closest-std-val

closest-std-val take a value and a tolerance as input, and return a standard/normal/nominal EIA value you can use to create or query your basic components (resistor, capacitor, or inductor):

; Returns the closest value to v in the tolerance range specified by tol
public defn closest-std-val (v:Double, tol:Double)

Example usage:

  ; get the required resistance, given the input voltage and the desired current
  val computed-resistance = (voltage - typ(vf)) / typ(computed-current)
  ; turn the resistor into the closest standard value resistor by passing in a the resistance that we computed
  val standard-computed-resistance = closest-std-val(typ-value(computed-resistance), 5.0)

Adding Mounting Holes

JITX contains utilities to add mounting holes to a board automatically. A single call to add-mounting-holes can add a mounting hole to each corner of your board.

In order to add mounting holes to your board, call add-mounting-holes with your board shape, the size of screw that you want, and optionally a Tuple which specifies the corners that you don't want holes added:

; Add mounting holes to the board given its shape, a screw size, and hole indices to exclude.
public defn add-mounting-holes (board-shape:Shape, screw-size:String|Double, no-hole:Tuple<Int>)

If you want holes added to every corner of the board:

; Add mounting holes to the board given its shape and a screw size.
public defn add-mounting-holes (board:Shape, screw-size:String|Double):
  add-mounting-holes(board, screw-size, [])

Other mounting hole utilities also exist:

;  Add mounting holes to the board given its shape. Defaults to M3 size holes.
public defn add-mounting-holes (board:Shape)

; Add mounting holes to the board given its shape, excluding holes given
; by the indices in no-holes. Defaults to M3 size mounting holes.
public defn add-mounting-holes (board:Shape, no-hole:Tuple<Int>)

Screw Sizes

The screw size is specified by a string, and can be any one of the following:

• "M2"
• "M2p5"
• "M3"
• "M3p5"

Testpoint - how to place a testpoint

We can place a testpoint for any net with a call to testpoint-strap.

Here is the built-in definition of testpoint-strap:

; place a testpoint
defn testpoint-strap (tp:JITXObject, tp-name:String, diameter:Double) -> JITXObject:

It accepts a net to place the testpoint for, a name to apply to the testpoint, and the diameter you want the circular SMD test pad to be.

Example Usage

  ; add a testpoint for this pin
  val test-pad = my-testpoint-strap(IN, net-name, 2.0) ; in current versions of OCDB, we can directly call `testpoint-strap` function

Make-Net

make-net is another way to create connection between components, and it creates the exact same type of net that the net statement makes.

However, make-net allows us to name nets with strings, among some other benefits.

Use make net when you want to create a net using a string for the name.

Example usage

make-net("my-net-name", [component-1, component-2, component-3)

Symbols - set symbols of a net

We can set any net to use a specified symbol. This is especially useful for power and gnd nets.

You can design your own symbol, or you can use any of the many built-in symbols.

Example

To assign power symbols to the GND and POWER nets, we could specify the following in our top level pcb-module:

  ; set symbols of some nets
  symbol(GND) = ocdb/utils/symbols/ground-sym
  symbol(POWER) = ocdb/utils/symbols/supply-sym

Components

Sections

• Resistors
• Inductors
• Capacitors
• Microcontrollers

High Level Part Query

We can query actual parts from the JITX database that can be bought. Our database contains resistors, inductors, capacitors and STM micro-controllers.

Check the properties reference for a description of supported attributes.

Read about the Low Level Part Query API to learn about the syntax of the query requirements. The high level functions in ocdb/utils/generic-components such as chip-resistor make calls to less specialized functions in ocdb/utils/parts such as Resistor that make calls to the low level API such as dbquery-first.

Supported parameters

The supported special query parameters are:

• _exist : List of attributes that the returned documents must contain.
• _sort : The returned documents will be sort according to the list of attributes specified by this parameter, applied in the order they appear. Sorting in descending fashion can be obtained by starting a sorting attribute by a minus sign "−". This can take 2 additional value besides the list of existing properties: area is an alias for dimensions.area and cost is an alias for price.

Regular filter properties:

• We can filter on a part attribute : {"category": "resistor"}.
• For filtering over capacitance, resistance and inductance, those constraints are replaced by interval allowing for queries with a precision of 0.0005Ω, 0.01A and 0.01F respectively.
• For filtering over the tolerance : {"tolerance": 0.05} will constrain the actual tolerance range to be included in the interval [-5%, 5%]. Returns 500 Bas Request if this is not a positive double
• We can filter on a nested parameter using . : {"dimensions.x": 11}
• We can filter on a list of values giving a list : {"case": ["Axial", "0402"]}
• We can filter with an inequality prepending min- or max- : {"max−rated-power": 0.05}. max-x, max-y and max-z are shorthands for max-dimensions.x, max-dimensions.y, max-dimensions.z
• We interpret minimum_quantity as a floor on bulk purchase size; we automatically convert minimum_quantity to max-minimum_quantity.

Example:

#use-added-syntax(jitx)
defpackage my-design :
  import ocdb/utils/generic-components

pcb-module my-module :
  inst res : chip-resistor(["max-z" => 0.5, "_sort" => ["-rated-power"], "_exist" => ["tolerance"]])

Resistors

This sections details how to search and specify resistors in a design. There are over 1,000,000 resistors in the JITX database and the same part can be referenced in different packaging (cut tape, reels...).

chip-resistor finds a specific resistor based on specified properties and stock.

look-up-chip-resistors is a function that returns lists of resistors based on properties and stock.

res-strap does everything chip-resistor does and connects it to two nets.

gen-res-cmp allows us to place generic resistor components for offline use.

The db-parts section describes lower level functions, and the properties section describes every available attribute we can search with.

Contents:

• ocdb/utils/generic-components
  • chip-resistor
    • Example
  • look-up-chip-resistors
    • Example
  • res-strap
    • Example
  • gen-res-cmp
    • Example
• ocdb/utils/db-parts
  • Resistor Struct
    • Example
  • Resistor Accessors
    • Example
  • Resistor from JSON
    • Example
  • query-available-resistance-values
    • Example
  • look-up-resistors
    • Example
• Properties
  • Attribute: resistance
  • Attribute: tolerance (min, max)
  • Attribute: manufacturer
  • Attribute: mounting
  • Attribute: case
  • Attribute: type
  • Attribute: composition
  • Attribute: rated-power
  • Attribute: tcr (neg, pos)
  • Attribute: rated-temperature (min, max)
  • Attribute: mpn
  • Attribute: dimensions (x, y, z, area)
  • Attribute: stock
  • Attribute: price
  • Attribute: minimum_quantity
  • Attribute: metadata.datasheets
  • Attribute: metadata.image
  • Attribute: metadata.digi-key-part-number
  • Attribute: metadata.description
  • Attribute: metadata.series
  • Attribute: metadata.packaging
  • Attribute: metadata.features
  • Attribute: metadata.supplier-device-package
  • Attribute: metadata.number-of-terminations

ocdb/utils/generic-components

The resistor functions are located in ocdb/utils/generic-components, which imports ocdb/utils/db-parts.

chip-resistor

We can query an actual SMD resistor from the JITX database that can be bought. This call requires internet access. chip-resistor calls the lower level Part Query API adding the list of attributes provided by the user on top of design settings.

public defn chip-resistor (params:Tuple<KeyValue>)

Here are the quick accessors:

public defn chip-resistor (resistance:Double)
public defn chip-resistor (resistance:Double, tolerance:Double)

The resistance is in Ohms and the tolerance is unit-less (0.01 is ±1%).

Example:

• res1 = 10 kΩ
• res2 = 0.01 Ω, 0.5% tolerance
• res3 = 0.01 Ω, 0.5% tolerance, 0.5 Watt or more
• res4 = 1 Ω, 0.5% tolerance, 1206 size
• res5 = 100 mΩ, 0.5% tolerance, 1210 size or larger
• res6 = 100 mΩ, 0.5% tolerance, 1210 size or larger, rated to 60° C or above
• res7 = First, the value is calculated ( (5-3)/0.005 = 400 Ω), then it's rounded to the closest 5% resistor value (402 Ω), then a 402 Ω resistor of 1% tolerance is returned.

#use-added-syntax(jitx)
defpackage my-design :
  import ocdb/utils/generic-components
  import ocdb/utils/design-vars

; Overrides default value set in ocdb/utils/design-vars
MIN-PKG = "0402"

pcb-module my-module :
  inst res1 : chip-resistor(10.0e3)
  inst res2 : chip-resistor(0.01, 0.005)
  inst res3 : chip-resistor(["resistance" => 0.01 "tolerance" => 0.005 "min-rated-power" => 0.5])
  inst res4 : chip-resistor(["resistance" => 1.0 "tolerance" => 0.005 "case" => "1206"])
  inst res5 : chip-resistor(["resistance" => 100.0e-3 "tolerance" => 0.005 "case" => get-valid-pkg-list("1210")])
  inst res6 : chip-resistor(["resistance" => 0.1 "tolerance" => 0.005 "case" => get-valid-pkg-list("1210") "min-rated-temperature.max" => 60.0])
  var some-voltage = 3.0
  val some-current = 5.0e-3
  inst res7 : chip-resistor(closest-std-val( (5.0 - some-voltage) / some-current,0.5), 0.01)

Fixed Requirements :

• category: "resistor"
• mounting: "smd"
• minimum_quantity: 1

Default design Requirements (set by global variables defined in ocdb/utils/design-vars) :

• min-stock: 500
• _sort: ["area"]
• max-rated-temperature.min: 0.0
• min-rated-temperature.max: 25.0
• case: ["0201" "02016" "0202" "0302" "0303" "0402" "0404" "0503" "0505" "0603" "0612" "0805" "1206" "1210" "1218" "1812" "2010" "2512" "2525" "2615" "2616" "3920" "4122" "4823" "5329" "6030"]

Those design requirements can be changed, either by changing ocdb/utils/design-vars or by importing ocdb/utils/design-vars and setting new values for the global variables:

• min-stock: this is 5 times DESIGN-QUANTITY. Which mean that DESIGN-QUANTITY default is 100.
• _sort: set by OPTIMIZE-FOR. Default is ["area"].
• [max-rated-temperature.min min-rated-temperature.max] : rated-temperature range in degC set by OPERATING-TEMPERATURE.
• case: computed from MIN-PKG. MIN-PKG default is "0201".

look-up-chip-resistors

public defn look-up-chip-resistors (attribute: String) -> Tuple
public defn look-up-chip-resistors (attribute: String, filter-properties:Tuple<KeyValue>) -> Tuple

Looks up the list of available values (at most 1000 returned) for attribute amongst chip resistors in the JITX database. This call filters on the same properties as chip-resistor. Additional properties filter-properties can be given in argument to restrict further criteria on the considered chip resistors.

Example:

$ jitx repl
stanza> import ocdb/utils/generic-components
stanza> println $ look-up-chip-resistors("type", ["resistance" => 1.0, "min-rated-power" => 1.0])
["chip"]
stanza> println $ look-up-chip-resistors("composition", ["resistance" => 1.0, "min-rated-power" => 1.0])
["thick-film" "thin-film" "wirewound"]

res-strap

res-strap is a wrapper around chip-resistor that also connects the resistor to two nets specified. This call requires internet access. It needs to be called inside a pcb module.

public defn res-strap (first-pin:JITXObject, second-pin:JITXObject, resistance:Double)
public defn res-strap (first-pin:JITXObject, second-pin:JITXObject, resistance:Double, tol:Double)
public defn res-strap (first-pin:JITXObject, second-pin:JITXObject, params:Tuple<KeyValue>)

Example:

#use-added-syntax(jitx)
defpackage my-design :
  import ocdb/utils/generic-components

pcb-module my-module :
  pin gnd
  pin power-5v
  pin signal
  res-strap(power-5v, signal, 10.0e3) ; 10 kΩ between power-5v and signal
  res-strap(gnd, signal, 120.0, 0.01) ; 120 Ω, 1% tolerance between gnd and signal
  res-strap(power-5v, signal, ["resistance" => 0.01 "tolerance" => 0.005 "min-rated-power" => 0.5]) ; 0.01 Ω, 1% tolerance, 0.5 Watt or more between power-5v and signal

gen-res-cmp

This is a generic resistor component, this is not an actual part that can be bought. This call does not require internet access. Pins are p[1] and p[2]. Arguments:

• r-type := ResistorStd | ResistorVariable | ResistorPot | ResistorPhoto | ResistorTherm from ocdb/utils/ResistorSymbolType (decides the schematic symbol)
• res : resistance in Ohms
• tol: tolerance (1.0 means ±1%)
• pwr : maximum power in watts
• pkg-name: Package name (example: "0204")

public defn gen-res-cmp (res:Double)
public defn gen-res-cmp (res:Double, pkg:String)
public defn gen-res-cmp (res:Double, tol:Double)
public defn gen-res-cmp (res:Double, tol:Double, pkg:String)
public defn gen-res-cmp (res:Double, tol:Double, pwr:Double)
public pcb-component gen-res-cmp (r-type:ResistorSymbolType, res:Double, tol:Double, pwr:Double, pkg-name:String)

Here are the quick accessors: Defaults used are:

• r-type : ResistorStd
• tol : 2%
• pwr : 0.0625 W
• pkg-name : "0402"

Valid entries for ResistorSymbolType:

• ResistorStd
• ResistorVariable
• ResistorPot
• ResistorPhoto
• ResistorTherm

Specifying ResistorSymbolType requires importing ocdb/utils/symbols

Example:

• r = instantiating a 5Ω generic resistor
• r1 = instantiating a 5Ω generic resistor with a 1206 package
• r2 = instantiating a 120Ω photo resistor, 10% tolerance, 0.5W, with a 0805 package

pcb-module my-design :
  inst r : gen-res-cmp(5.0)
  inst r1 : gen-res-cmp(5.0, "1206")
  inst r2 : gen-res-cmp (ResistorPhoto, 120.0, 0.10, 0.5, "0805")

ocdb/utils/db-parts

Resistor Struct

Here is the Resistor struct. When resistors are queried from the JITX database, the resistor data gets populated into this struct. It can be used to write pure stanza solvers like a voltage divider (see open-components-database/modules/voltage-divider.stanza) without having to deal with jitx macros.

public defstruct Resistor <: Component :
  ; Generic properties
  manufacturer: String
  mpn: String
  trust: String
  x: Double with: (as-method => true)
  y: Double with: (as-method => true)
  z: Double|False
  mounting: String
  rated-temperature: MinMaxRange|False
  case: String|False
  sourcing: Sourcing
  metadata: Tuple<KeyValue>
  ; Resistor specific properties
  type: String ; Type of resistor
  tolerance: MinMaxRange|False ; Guaranteed tolerance from manufacture (Ohm/Ohm)
  resistance: Double ; Nominal resistance (Ohm)
  composition: String|False ; Composition of resistor
  rated-power: Double|False ; Power dissipation limit as rated by manufacturer. One value, or PWL function (W | [degC, W])
  TCR: TCR|False ; Temperature coefficient of resistance (ohms/ohm*degC)
  sellers: Tuple<Seller>|False with: (as-method => true)
  resolved-price: Double|False with: (as-method => true)

public defstruct MinMaxRange :
  min: Double
  max: Double

defstruct Sourcing :
  price: Double|False
  minimum-quantity: Int
  stock: Int

public defstruct TCR :
  reference-temperature: Double
  positive: Double
  negative: Double

defmethod to-jitx (resistor: Resistor) -> Instantiable

Takes a Resistor struct and returns an instance.

Example:

#use-added-syntax(jitx)
defpackage my-design :
  import ocdb/utils/db-parts

val resistor = Resistor(["tolerance" => 0.05 "composition" => "thick-film"])

pcb-module my-module :
  inst res : to-jitx(resistor)

Resistor Accessors

We can query an actual resistor from the JITX database that can be bought. This call requires internet access. Resistor calls the lower level Part Query API adding the list of attributes provided by the user on top of design settings.

public defn Resistor (properties:Tuple<KeyValue>) -> Resistor

Fixed Requirements :

• category: "resistor"

Default design Requirements (set by global variables defined in ocdb/utils/design-vars) :

• _sort: ["area"]
• max-rated-temperature.min: 0.0
• min-rated-temperature.max: 25.0

Those design requirements can be changed, either by changing ocdb/utils/design-vars or by importing ocdb/utils/design-vars and setting new values for the global variables:

• _sort: set by OPTIMIZE-FOR.
• [max-rated-temperature.min min-rated-temperature.max] : rated-temperature range in degC set by OPERATING-TEMPERATURE.

Here are accessors to override design requirements:

public defn Resistor (properties:Tuple<KeyValue>,
                      exist:Tuple<String>) -> Resistor
public defn Resistor (properties:Tuple<KeyValue>,
                      exist:Tuple<String>,
                      sort:Tuple<String>,
                      operating-temperature:Toleranced|False) -> Resistor

Arguments:

• exist: we can require the resulting resistor to have an attribute that is otherwise optional (for example "tolerance").
• sort: overrides the sorting arguments that would otherwise be OPTIMIZE-FOR.
• operating-temperature: overrides the rated temperature range that would otherwise be OPERATING-TEMPERATURE.

Example:

Query a resistor with real-time sourcing data

$ jitx repl
stanza> import ocdb/utils/db-parts
stanza> import jitx/commands
stanza> val resistor = Resistor(["resistance" => 1.0, "_sellers" => bom-vendors(), "_stock" => 1000])
stanza> println $ resistor
Resistor(
  mpn = ERJ-XGNJ1R0Y
  trust = low
  (x, y, z) = (0.4, 0.2, 0.15)
  mounting = smd
  rated-temperature = MinMaxRange(min=-55.0, max=125.0)
  case = 01005
  type = chip
  tolerance = MinMaxRange(min=-0.05, max=0.05)
  resistance = 1.0
  composition = thick-film
  rated-power = 0.03
  TCR = TCR(positive=-0.0001, negative=0.0006)
  sourcing = ESR(price=0.01932, minimum-quantity=20000, stock=0)
  metadata =
    "datasheets" => "https://b2b-api.panasonic.eu/file_stream/pids/fileversion/1242"
    "image" => "//media.digikey.com/Photos/Panasonic Photos/MFG_ERJ-XGNJ1R0Y.jpg"
    "digi-key-part-number" => "10-ERJ-XGNJ1R0YTR-ND"
    "description" => "RES SMD 1.0 OHM 5% 1/32W 01005"
    "factory-stock" => 0.0
    "qty" => 0.0
    "packaging" => "Tape & Reel (TR)"
    "series" => "ERJ-XGN"
    "supplier-device-package" => 1005.0
    "number-of-terminations" => 2.0
  sellers =
    Seller(
      company-name = Digi-Key
      resolved-price = 0.02484
      offers = (
        SellerOffer(
          inventory-level = 17314
          prices = (
            SellerOfferPrice(quantity = 1, converted-price = 0.18)
            SellerOfferPrice(quantity = 10, converted-price = 0.152)
            SellerOfferPrice(quantity = 100, converted-price = 0.0593)
            SellerOfferPrice(quantity = 1000, converted-price = 0.02484)
            SellerOfferPrice(quantity = 2500, converted-price = 0.02277)
            SellerOfferPrice(quantity = 5000, converted-price = 0.0207)))
        SellerOffer(
          inventory-level = 17314
          prices = (
            SellerOfferPrice(quantity = 1, converted-price = 0.18)
            SellerOfferPrice(quantity = 10, converted-price = 0.152)
            SellerOfferPrice(quantity = 100, converted-price = 0.0593)
            SellerOfferPrice(quantity = 1000, converted-price = 0.02484)
            SellerOfferPrice(quantity = 2500, converted-price = 0.02277)
            SellerOfferPrice(quantity = 5000, converted-price = 0.0207)))
        SellerOffer(
          inventory-level = 0
          prices = (
            SellerOfferPrice(quantity = 20000, converted-price = 0.01932)))))
    Seller(
      company-name = Newark
      resolved-price = 0.074
      offers = (
        SellerOffer(
          inventory-level = 19850
          prices = (
            SellerOfferPrice(quantity = 1, converted-price = 0.55)
            SellerOfferPrice(quantity = 25, converted-price = 0.461)
            SellerOfferPrice(quantity = 100, converted-price = 0.179)
            SellerOfferPrice(quantity = 250, converted-price = 0.144)
            SellerOfferPrice(quantity = 500, converted-price = 0.109)
            SellerOfferPrice(quantity = 1000, converted-price = 0.074)))
        SellerOffer(
          inventory-level = 0
          prices = (
            SellerOfferPrice(quantity = 20000, converted-price = 0.041)))))
    Seller(
      company-name = Avnet
      resolved-price = 0.074
      offers = (
        SellerOffer(
          inventory-level = 19850
          prices = (
            SellerOfferPrice(quantity = 1, converted-price = 0.55)
            SellerOfferPrice(quantity = 25, converted-price = 0.461)
            SellerOfferPrice(quantity = 100, converted-price = 0.179)
            SellerOfferPrice(quantity = 250, converted-price = 0.144)
            SellerOfferPrice(quantity = 500, converted-price = 0.109)
            SellerOfferPrice(quantity = 1000, converted-price = 0.074)))
        SellerOffer(
          inventory-level = 0
          prices = (
            SellerOfferPrice(quantity = 20000, converted-price = 0.04914)
            SellerOfferPrice(quantity = 40000, converted-price = 0.04662)
            SellerOfferPrice(quantity = 80000, converted-price = 0.0441)
            SellerOfferPrice(quantity = 120000, converted-price = 0.04158)
            SellerOfferPrice(quantity = 160000, converted-price = 0.03906)
            SellerOfferPrice(quantity = 200000, converted-price = 0.03654)
            SellerOfferPrice(quantity = 2000000, converted-price = 0.03402)))))
    Seller(
      company-name = Arrow Electronics
      resolved-price = 0.0463
      offers = (
        SellerOffer(
          inventory-level = 20000
          prices = (
            SellerOfferPrice(quantity = 1, converted-price = 0.3073)
            SellerOfferPrice(quantity = 10, converted-price = 0.2577)
            SellerOfferPrice(quantity = 25, converted-price = 0.2551)
            SellerOfferPrice(quantity = 50, converted-price = 0.2526)
            SellerOfferPrice(quantity = 100, converted-price = 0.1516)
            SellerOfferPrice(quantity = 250, converted-price = 0.0993)
            SellerOfferPrice(quantity = 500, converted-price = 0.0924)
            SellerOfferPrice(quantity = 1000, converted-price = 0.0463)
            SellerOfferPrice(quantity = 3000, converted-price = 0.0423)
            SellerOfferPrice(quantity = 6000, converted-price = 0.0419)
            SellerOfferPrice(quantity = 15000, converted-price = 0.0324)))))
  resolved-price = 0.02484)

public defn Resistors (user-properties:Tuple<KeyValue>, limit: Int) -> Tuple<Resistor>

Similar to Resistor but querying up to 25 resistors.

Resistor from JSON

public defn Resistor (raw-json: JObject) -> Resistor

Creates a Resistor from a JObject.

Example:

$ jitx repl
stanza> import jitx/commands
stanza> import ocdb/utils/db-parts
stanza> import json
stanza> val jobject = dbquery-first(["category" => "resistor" "resistance" => 2.0]) as JObject
stanza> println(jobject)
JObject(entries = ["_id" => "0f8e320e1bc955ff59439bfc" "trust" => "low" "category" => "resistor" "mpn" => "OK20G5E-R52" "mounting" => "through-hole" "manufacturer" => "Ohmite" "type" => "through-hole" "dimensions" => JObject(entries = ["x" => 6.8 "y" => 2.5 "area" => 17.0]) "stock" => 0.0 "minimum_quantity" => 50000.0 "metadata" => JObject(entries = ["datasheets" => "http://www.ohmite.com/assets/docs/res_little_rebel.pdf?r=false" "digi-key-part-number" => "OK20G5E-R52-ND" "description" => "RES 2 OHM 5% 1/4W AXIAL" "factory-stock" => 0.0 "qty" => 0.0 "packaging" => "Tape & Reel (TR)" "series" => "Little Rebel® OK" "supplier-device-package" => "Axial" "number-of-terminations" => 2.0]) "price" => 0.01197 "tolerance" => JObject(entries = ["min" => -0.05 "max" => 0.05]) "resistance" => 2.0 "rated-power" => 0.25 "composition" => "carbon-film" "tcr" => JObject(entries = ["pos" => -0.00035 "neg" => 0.00035]) "case" => "Axial" "update_date" => "2021-09-04T01:26:50.670000"])
stanza> val resistor = Resistor(jobject)
stanza> println(resistor)
Resistor(
  mpn = OK20G5E-R52
  trust = low
  (x, y, z) = (6.8, 2.5, false)
  mounting = through-hole
  rated-temperature = false
  case = Axial
  type = through-hole
  tolerance = MinMaxRange(min=-0.05, max=0.05)
  resistance = 2.0
  composition = carbon-film
  rated-power = 0.25
  TCR = TCR(positive=-0.00035, negative=0.00035)
  sourcing = ESR(price=0.01197, minimum-quantity=50000, stock=0)
  metadata =
    "datasheets" => "http://www.ohmite.com/assets/docs/res_little_rebel.pdf?r=false"
    "digi-key-part-number" => "OK20G5E-R52-ND"
    "description" => "RES 2 OHM 5% 1/4W AXIAL"
    "factory-stock" => 0.0
    "qty" => 0.0
    "packaging" => "Tape & Reel (TR)"
    "series" => "Little Rebel® OK"
    "supplier-device-package" => "Axial"
    "number-of-terminations" => 2.0)

query-available-resistance-values

public defn query-available-resistance-values (properties:Tuple<KeyValue>, exist:Tuple<String>) -> Tuple<Double> :

We can query the list of available resistance values available using the same design requirements as Resistor, filtering on a list of query parameters properties and requiring the attributes in exist to exist on the resistors.

Example:

$ jitx repl
stanza> import ocdb/utils/db-parts
stanza> println $ query-available-resistance-values(["composition" => "thick-film" "case" => "Axial"], ["tolerance"])
[100.0 150.0 270.0 470.0 511.0 560.0 680.0 750.0 1000.0 1010.0 1500.0 2000.0 2700.0 3300.0 4300.0 4700.0 4990.0 5100.0 6800.0 7500.0 10000.0 15000.0 18000.0 20000.0 24000.0 27000.0 33000.0 40000.0 47000.0 49900.0 50000.0 51000.0 60000.0 66000.0 75000.0 95300.0 100000.0 120000.0 150000.0 196000.0 200000.0 220000.0 250000.0 270000.0 300000.0 330000.0 350000.0 390000.0 400000.0 500000.0 680000.0 820000.0 1000000.0 1050000.0 1100000.0 1240000.0 1470000.0 1800000.0 2000000.0 2200000.0 2400000.0 2700000.0 3000000.0 3300000.0 4000000.0 4700000.0 5000000.0 5100000.0 6000000.0 6650000.0 7000000.0 7500000.0 8000000.0 8450000.0 9000000.0 10000000.0 11000000.0 12000000.0 12500000.0 14700000.0 15000000.0 16000000.0 20000000.0 22000000.0 22100000.0 25000000.0 27000000.0 30000000.0 30100000.0 33000000.0 39000000.0 40000000.0 47000000.0 50000000.0 60000000.0 68000000.0 70000000.0 75000000.0 80000000.0 82000000.0 100000000.0 120000000.0 130000000.0 140000000.0 150000000.0 180000000.0 195000000.0 200000000.0 222000000.0 250000000.0 300000000.0 330000000.0 400000000.0 430000000.0 470000000.0 500000000.0 750000000.0 900000000.0 1000000000.0 1200000000.0 1240000000.0 1320000000.0 2000000000.0 3000000000.0 4700000000.0 5000000000.0 9000000000.0 10000000000.0 15000000000.0 20000000000.0 50000000000.0 60000000000.0 100000000000.0 120000000000.0 200000000000.0 300000000000.0 500000000000.0]

look-up-resistors

public defn look-up-resistors (attribute: String) -> Tuple
public defn look-up-resistors (attribute: String, filter-properties:Tuple<KeyValue>) -> Tuple

Looks up the list of available values (at most 1000 returned) for attribute amongst resistors in the JITX database. This call filters on the same properties as Resistor. Additional properties filter-properties can be given in argument to restrict further criteria on the considered resistors.

Example:

$ jitx repl
stanza> import ocdb/utils/db-parts
stanza> println $ look-up-resistors("mounting", ["resistance" => 1.0, "min-rated-power" => 1.0])
["smd" "through-hole"]

Properties

Each resistor has a different Digi-Key Part Number but an mpn has typically 3 Digi-Key Part Numbers for 3 different packagings.

For example the resistor of mpn "ERJ-XGNJ1R0Y" appears with the following Digi-Key Part Numbers and packagings:

• 10-ERJ-XGNJ1R0YCT-ND: Cut Tape (CT)
• 10-ERJ-XGNJ1R0YDKR-ND: Digi-Reel®
• 10-ERJ-XGNJ1R0YTR-ND: Tape & Reel (TR)

This information can be found in the attributes metadata.digi-key-part-number and metadata.packaging but cannot be queried on. We can check by ourselves doing:

$ jitx repl
stanza> import ocdb/utils/db-parts
stanza> do(println, Resistors(["mpn" => "ERJ-XGNJ1R0Y"], 25))

Check the properties reference for a description of supported attributes.

Here are available attribute values with default design requirements as of 10/14/2021. They can be queried anytime with:

$ jitx repl
stanza> import ocdb/utils/db-parts
stanza> for attribute in ["manufacturer", "mpn", "resistance", "trust", "dimensions", "mounting", "case", "stock", "price", "minimum_quantity", "type", "composition", "rated-power", "tcr", "metadata.datasheets", "metadata.image", "metadata.digi-key-part-number", "metadata.description", "metadata.packaging", "metadata.series", "metadata.features", "metadata.supplier-device-package", "metadata.number-of-terminations"] do :
      >   val values = look-up-resistors(attribute)
      >   if length(values) <= 150 :
      >     println("| %_ | %@ |" % [attribute, values])
      >   else :
      >     println("| %_ | %_ values |" % [attribute, length(values)])
stnaza> import json
stanza> for attribute in ["rated-temperature", "tolerance"] do :
      >   val values =  to-tuple $ filter({_ is JObject}, look-up-resistors(attribute))
      >   if length(values) <= 150 :
      >     println("| %_ (min, max) | %@ |" % [attribute, map({"(%_, %_)" % [_0["min"], _0["max"]]}, values)])
      >   else :
      >     println("| %_ | %_ values |" % [attribute, length(values)])
stanza> for attribute in ["tcr"] do :
      >   val values =  to-tuple $ filter({_ is JObject}, look-up-resistors(attribute))
      >   if length(values) <= 150 :
      >     println("| %_ (neg, pos) | %@ |" % [attribute, map({"(%_, %_)" % [_0["neg"], _0["pos"]]}, values)])
      >   else :
      >     println("| %_ | %_ values |" % [attribute, length(values)])

Metadata values are not sanitized.

Attribute: resistance

Values:

0.0 0.0001 0.0002 0.00025 0.0003 0.0004 0.0005 0.0007 0.00075 0.0008 0.001 0.0013 0.0015 0.002 0.0022 0.00225 0.0025 0.0028 0.003 0.0032 0.0033 0.0035 0.0036 0.00375 0.004 0.0045 0.0047 0.0048 0.005 0.006 0.0068 0.007 0.0075 0.008 0.009 0.0093 0.01 0.011 0.012 0.0125 0.013 0.0133 0.014 0.015 0.016 0.0162 0.0165 0.0169 0.017 0.0174 0.0178 0.018 0.0182 0.0187 0.019 0.0191 0.0196 0.02 0.0205 0.021 0.0215 0.022 0.0221 0.0226 0.023 0.0232 0.0237 0.024 0.0243 0.0249 0.025 0.0255 0.026 0.0261 0.0267 0.027 0.0274 0.028 0.0287 0.029 0.0294 0.03 0.0301 0.0309 0.0316 0.032 0.0324 0.033 0.0332 0.034 0.0348 0.035 0.0357 0.036 0.0365 0.0374 0.038 0.0383 0.039 0.0392 0.04 0.0402 0.0412 0.042 0.0422 0.043 0.0432 0.0442 0.045 0.0453 0.046 0.0464 0.047 0.0475 0.0487 0.049 0.0499 0.05 0.0502 0.051 0.0511 0.0523 0.0536 0.054 0.0549 0.055 0.056 0.0562 0.0576 0.059 0.06 0.0604 0.0619 0.062 0.0634 0.064 0.0649 0.065 0.066 0.0665 0.067 0.068 0.0681 0.0698 0.07 0.0715 0.0732 0.075 0.076 0.0768 0.077 0.078 0.0787 0.079 0.08 0.0806 0.081 0.082 0.0825 0.083 0.0845 0.085 0.0866 0.087 0.0887 0.089 0.09 0.0909 0.091 0.0931 0.095 0.0953 0.0976 0.1 0.101 0.102 0.105 0.107 0.11 0.113 0.115 0.118 0.12 0.121 0.124 0.125 0.127 0.13 0.132 0.133 0.135 0.137 0.14 0.142 0.143 0.145 0.147 0.149 0.15 0.151 0.152 0.154 0.156 0.158 0.16 0.162 0.165 0.166 0.167 0.169 0.17 0.174 0.176 0.178 0.18 0.182 0.187 0.191 0.196 0.2 0.205 0.21 0.215 0.22 0.221 0.226 0.229 0.23 0.232 0.234 0.237 0.24 0.243 0.249 0.25 0.252 0.255 0.258 0.26 0.261 0.264 0.267 0.27 0.271 0.274 0.28 0.287 0.294 0.3 0.301 0.309 0.31 0.316 0.32 0.322 0.324 0.33 0.332 0.333 0.34 0.348 0.35 0.357 0.36 0.365 0.37 0.374 0.375 0.38 0.383 0.39 0.391 0.392 0.397 0.4 0.402 0.407 0.41 0.412 0.42 0.422 0.427 0.43 0.432 0.44 0.442 0.449 0.45 0.453 0.46 0.464 0.466 0.47 0.475 0.481 0.487 0.49 0.499 0.5 0.5003 0.505 0.51 0.511 0.512 0.52 0.523 0.53 0.536 0.54 0.549 0.55 0.556 0.557 0.56 0.562 0.57 0.576 0.58 0.59 0.597 0.598 0.6 0.604 0.61 0.619 0.62 0.625 0.626 0.63 0.634 0.635 0.64 0.645 0.649 0.65 0.66 0.665 0.67 0.673 0.68 0.681 0.689 0.69 0.698 0.7 0.71 0.715 0.723 0.732 0.74 0.741 0.75 0.751 0.752 0.759 0.768 0.78 0.781 0.787 0.796 0.8 0.806 0.82 0.825 0.83 0.833 0.84 0.845 0.85 0.853 0.865 0.866 0.87 0.88 0.887 0.898 0.9 0.909 0.91 0.931 0.942 0.95 0.953 0.96 0.965 0.976 0.99 1.0 1.0009 1.001 1.0015 1.005 1.0055 1.01 1.02 1.024 1.03 1.04 1.05 1.07 1.09 1.1 1.125 1.13 1.1364 1.15 1.152 1.16 1.18 1.2 1.21 1.212 1.222 1.23 1.24 1.25 1.26 1.2626 1.27 1.29 1.3 1.32 1.33 1.35 1.37 1.4 1.42 1.43 1.44 1.47 1.5 1.505 1.52 1.53 1.54 1.56 1.58 1.592 1.6 1.62 1.64 1.65 1.6667 1.6696 1.67 1.68 1.69 1.7 1.74 1.78 1.79 1.8 1.82 1.85 1.87 1.9 1.91 1.93 1.954 1.96 1.98 2.0 2.0015 2.002 2.01 2.015 2.02 2.04 2.05 2.07 2.08 2.085 2.088 2.1 2.138 2.15 2.151 2.195 2.2 2.21 2.23 2.25 2.26 2.29 2.3 2.304 2.3047 2.32 2.341 2.35 2.37 2.4 2.43 2.46 2.47 2.49 2.5 2.5065 2.507 2.51 2.52 2.55 2.58 2.6 2.61 2.639 2.64 2.6435 2.656 2.66 2.67 2.7 2.71 2.74 2.75 2.77 2.8 2.82 2.87 2.88 2.92 2.94 2.98 3.0 3.01 3.03 3.05 3.06 3.09 3.1 3.11 3.135 3.15 3.16 3.18 3.2 3.24 3.28 3.3 3.32 3.329 3.3333 3.34 3.343 3.36 3.38 3.4 3.47 3.48 3.5 3.52 3.54 3.57 3.5728 3.6 3.61 3.65 3.7 3.72 3.74 3.75 3.79 3.8 3.83 3.84 3.88 3.9 3.907 3.92 3.97 3.999 4.0 4.008 4.01 4.02 4.022 4.07 4.1 4.12 4.16 4.17 4.18 4.185 4.19 4.2 4.22 4.3 4.32 4.42 4.444 4.48 4.49 4.5 4.53 4.54 4.57 4.64 4.651 4.6512 4.7 4.71 4.74 4.75 4.761 4.78 4.8 4.81 4.87 4.9 4.93 4.95 4.99 5.0 5.005 5.01 5.012 5.025 5.05 5.08 5.1 5.11 5.15 5.17 5.19 5.2 5.21 5.23 5.263 5.3 5.36 5.4 5.487 5.49 5.5 5.56 5.6 5.62 5.69 5.7 5.71 5.714 5.7143 5.75 5.76 5.8 5.83 5.85 5.9 5.92 5.97 6.0 6.02 6.04 6.06 6.12 6.19 6.2 6.23 6.25 6.3 6.34 6.3407 6.35 6.4 6.42 6.43 6.453 6.49 6.5 6.54 6.57 6.6 6.64 6.65 6.666 6.6666 6.6667 6.67 6.7 6.73 6.78 6.8 6.81 6.85 6.9 6.91 6.926 6.98 7.0 7.029 7.06 7.15 7.2 7.23 7.3 7.32 7.37 7.3785 7.41 7.43 7.5 7.51 7.59 7.6 7.68 7.77 7.8 7.87 7.96 8.0 8.045 8.06 8.09 8.1 8.16 8.2 8.21 8.22 8.25 8.3 8.333 8.3333 8.4 8.45 8.5 8.6 8.66 8.7 8.76 8.8 8.85 8.87 8.98 9.0 9.09 9.1 9.2 9.31 9.4 9.42 9.45 9.47 9.5 9.53 9.6 9.65 9.7 9.74 9.76 9.88 9.95 9.995 9.999 10.0 10.001 10.01 10.015 10.03 10.1 10.12 10.2 10.21 10.3 10.4 10.417 10.5 10.6 10.7 10.8 10.85 10.86 10.9 10.973 11.0 11.1 11.11 11.111 11.16 11.2 11.25 11.3 11.4 11.5 11.52 11.6534 11.66 11.7 11.8 11.9 12.0 12.1 12.106 12.2 12.3 12.4 12.5 12.584 12.6 12.7 12.8 12.9 12.944 13.0 13.2 13.28 13.3 13.333 13.4 13.5 13.6 13.7 13.8 13.851 13.889 14.0 14.1 14.142 14.16 14.2 14.204 14.285 14.3 14.4 14.42 14.5 14.53 14.55 14.59 14.7 14.9 15.0 15.05 15.1 15.17 15.2 15.3 15.4 15.446 15.491 15.6 15.7 15.8 15.92 16.0 16.032 16.09 16.18 16.2 16.32 16.4 16.48 16.5 16.65 16.667 16.7 16.8 16.83 16.9 16.95 17.0 17.2 17.238 17.4 17.48 17.5 17.6 17.8 17.857 17.9 18.0 18.1 18.2 18.3 18.4 18.5 18.7 18.75 18.8 18.9 19.0 19.1 19.17 19.2 19.3 19.42 19.5 19.53125 19.57 19.6 19.8 19.9 20.0 20.002 20.02 20.1 20.2 20.27 20.3 20.5 20.552 20.6 20.8 20.833 21.0 21.1 21.17 21.2 21.27 21.298 21.3 21.42 21.5 21.574 21.6 21.7 21.8 21.946 22.0 22.1 22.2 22.239 22.3 22.5 22.6 22.81 22.9 23.0 23.2 23.331 23.4 23.7 23.8 23.81 24.0 24.001 24.2 24.224 24.3 24.5 24.6 24.72 24.9 24.92 25.0 25.1 25.1252 25.2 25.3 25.4 25.5 25.7 25.8 26.0 26.1 26.2 26.4 26.5 26.5258 26.56 26.64 26.7 26.9 27.0 27.1 27.23 27.3 27.4 27.5 27.6 27.7 27.702 27.9 28.0 28.095 28.1 28.2 28.242 28.3 28.4 28.5 28.7 28.7708 28.771 28.8 28.904 28.948 29.0 29.1 29.2 29.247 29.4 29.7 29.8 30.0 30.001 30.1 30.2 30.3 30.303 30.5

Attribute: tolerance (min, max)

Values:

(-0.3, 0.0) (-0.3, 0.3) (-0.2, 0.2) (-0.15, 0.15) (-0.1, 0.0) (-0.1, 0.1) (-0.05, 0.05) (-0.03, 0.03) (-0.02, 0.02) (-0.01, 0.01) (-0.005, 0.005) (-0.0025, 0.0025) (-0.002, 0.002) (-0.001, 0.001) (-0.0005, 0.0005) (-0.0002, 0.0002) (-0.0001, 0.0001) (-5.0e-05, 5.0e-05) (-2.5e-05, 2.5e-05) (-2.0e-05, 2.0e-05) (-1.0e-05, 1.0e-05)

Attribute: manufacturer

Values:

"AVX Corporation" "Aillen" "American Technical Ceramics" "Anaren" "Bourns Inc." "CAL-CHIP ELECTRONICS, INC." "CTS Resistor Products" "Caddock Electronics Inc." "Delta Electronics/Cyntec" "KOA Speer Electronics, Inc." "Kamaya Inc." "Meritek" "Murata Power Solutions Inc." "NTE Electronics, Inc" "Ohmite" "Panasonic Electronic Components" "Riedon" "Rohm Semiconductor" "Samsung Electro-Mechanics" "Stackpole Electronics Inc" "Susumu" "TE Connectivity" "TE Connectivity AMP Connectors" "TE Connectivity Passive Product" "TT Electronics/IRC" "TT Electronics/Welwyn" "TubeDepot" "Venkel" "Viking Tech" "Vishay Beyschlag/Draloric/BC Components" "Vishay Dale" "Vishay Dale Thin Film" "Vishay Electro-Films" "Vishay Foil Resistors (Division of Vishay Precision Group)" "Vishay Huntington Electric Inc." "Vishay Sfernice" "Vishay Thin Film" "Walsin Technology Corporation" "Würth Elektronik" "Xicon" "YAGEO" "Yageo"

Attribute: mounting

Values:

"smd" "through-hole"

Attribute: case

Values:

"009005" "01005" "0201" "02016" "0202" "0302" "0402" "0404" "0505" "0603" "0612" "0805" "1206" "1210" "1218" "1812" "2-SMD, J-Lead" "2010" "2010 J-Lead" "2012 J-Lead" "2015" "2512" "2512 J-Lead" "2515 J-Lead" "2520" "2615" "2615 J-Lead" "2616" "2817" "3014 J-Lead" "3017 J-Lead" "3916 J-Lead" "3920" "4-ESIP" "4-SIP" "4122" "4122 J-Lead" "4124 J-Lead" "4318 J-Lead" "4324 J-Lead" "4524 J-Lead" "4525 J-Lead" "4527 J-Lead" "5025 J-Lead" "5322 J-Lead" "5329" "6030" "6227 J-Lead" "6327 J-Lead" "6927 J-Lead" "8035 J-Lead" "8127 J-Lead" "8230 J-Lead" "Axial" "Axial - 4 Leads" "Axial, Radial" "Axial, Radial Bend" "Axial, Radial Formed" "MELF, 0102" "MELF, 0204" "MELF, 0207" "MELF, 0309" "Non-Standard D-PAK" "Nonstandard" "PFC10" "Radial" "Radial - 2 Leads" "Radial - 4 Leads" "Radial, Tubular" "SMD, J-Bend" "SMD, L-Bend" "SR10" "SR20" "Strip, C Bend" "Strip, L Bend" "TO-126-2" "TO-204AA" "TO-220-2" "TO-220-2 Full Pack" "TO-220-4" "TO-220-4, SMD" "TO-247-2" "TO-247-2 Variant" "TO-252-3, DPak" "TO-263-3, D²Pak" "Wide 0402" "Wide 0603" "Wide 0604" "Wide 0805" "Wide 1206" "Wide 1508" "Wide 1612" "Wide 1812" "Wide 2010" "Wide 2412" "Wide 2512" "Wide 2516" "Wide 2827" "Wide 3008" "Wide 3015" "Wide 3518" "Wide 4320" "Wide 5929"

Attribute: type

Values:

"chip" "through-hole"

Attribute: composition

Values:

"carbon-composition" "carbon-film" "ceramic" "metal-element" "metal-film" "metal-foil" "metal-oxide-film" "thick-film" "thin-film" "wirewound"

Attribute: rated-power

Values:

0.0125 0.0189 0.02 0.025 0.03 0.0375 0.05 0.06 0.063 0.075 0.1 0.12 0.125 0.135 0.15 0.16 0.167 0.175 0.2 0.225 0.245 0.25 0.3 0.32 0.333 0.35 0.375 0.4 0.5 0.6 0.63 0.667 0.7 0.75 0.8 0.9 1.0 1.1 1.2 1.25 1.3 1.33 1.4 1.5 1.6 1.75 1.8 2.0 2.16 2.2 2.3 2.4 2.5 2.7 2.75 2.8 2.88 3.0 3.12 3.2 3.25 3.47 3.5 3.6 3.75 3.8 4.0 4.2 4.25 4.32 4.4 4.5 4.8 5.0 5.2 5.5 5.6 6.0 6.25 6.3 6.5 7.0 7.5 7.8 8.0 8.4 8.8 9.0 10.0 11.0 12.0 12.5 13.0 13.5 14.0 15.0 16.0 16.8 17.0 18.0 20.0 22.0 22.4 25.0 28.0 30.0 35.0 36.0 40.0 45.0 50.0 60.0 75.0 95.0 100.0 140.0 150.0

Attribute: tcr (neg, pos)

Values:

(0.0039, -0.0039) (0.002, -0.002) (0.0018, -0.0018) (-0.0015, -0.0015) (-0.0009, -0.0015) (0.0015, -0.0015) (-0.0013, -0.0013) (0.0013, -0.0013) (-0.0006, -0.0012) (0.0012, -0.0012) (0.0011, -0.0011) (-0.0016, -0.001) (0.001, -0.001) (0.00095, -0.00095) (0.0009, -0.0009) (0.00085, -0.00085) (0.0008, -0.0008) (0.00075, -0.00075) (-0.0007, -0.0007) (0.0004, -0.0007) (0.0007, -0.0007) (0.00065, -0.00065) (0.0002, -0.0006) (0.0006, -0.0006) (0.0003, -0.0005) (0.00035, -0.0005) (0.0005, -0.0005) (0.00035, -0.00045) (0.00045, -0.00045) (0.00015, -0.0004) (0.0004, -0.0004) (0.00035, -0.00035) (0.0005, -0.00035) (0.000325, -0.000325) (5.0e-05, -0.0003) (0.0003, -0.0003) (0.0005, -0.0003) (0.00028, -0.00028) (0.000275, -0.000275) (0.00027, -0.00027) (0.00026, -0.00026) (0.00025, -0.00025) (0.0005, -0.00025) (0.000245, -0.000245) (0.00024, -0.00024) (0.00023, -0.00023) (0.000225, -0.000225) (0.0002, -0.0002) (0.00035, -0.0002) (0.0004, -0.0002) (0.0006, -0.0002) (0.00018, -0.00018) (0.000175, -0.000175) (0.00017, -0.00017) (-0.0004, -0.00015) (0.00015, -0.00015) (0.0004, -0.00015) (0.00014, -0.00014) (0.000125, -0.000125) (0.00012, -0.00012) (0.000115, -0.000115) (0.00011, -0.00011) (0.0001, -0.0001) (0.00035, -0.0001) (0.0004, -0.0001) (0.0005, -0.0001) (0.0006, -0.0001) (9.0e-05, -9.0e-05) (4.0e-05, -8.0e-05) (8.0e-05, -8.0e-05) (0.0005, -8.0e-05) (0.0009, -8.0e-05) (7.5e-05, -7.5e-05) (7.0e-05, -7.0e-05) (0.00017, -7.0e-05) (6.0e-05, -6.0e-05) (-0.00015, -5.0e-05) (5.0e-05, -5.0e-05) (0.0001, -5.0e-05) (4.0e-05, -4.0e-05) (3.5e-05, -3.5e-05) (3.0e-05, -3.0e-05) (2.5e-05, -2.5e-05) (2.0e-05, -2.0e-05) (5.0e-05, -2.0e-05) (8.0e-05, -2.0e-05) (1.5e-05, -1.5e-05) (1.2e-05, -1.2e-05) (-8.0e-05, -1.0e-05) (1.0e-05, -1.0e-05) (8.0e-06, -8.0e-06) (5.0e-06, -5.0e-06) (4.0e-06, -4.0e-06) (3.0e-06, -3.0e-06) (2.5e-06, -2.5e-06) (2.0e-06, -2.0e-06) (1.0e-06, -1.0e-06) (2.0e-07, -2.0e-07) (-0.0018, 0.0) (-0.0015, 0.0) (-0.0013, 0.0) (-0.001, 0.0) (-0.00085, 0.0) (-0.0008, 0.0) (-0.0007, 0.0) (-0.0006, 0.0) (-0.0005, 0.0) (-0.00045, 0.0) (-0.0004, 0.0) (-0.00035, 0.0) (-0.00015, 0.0) (0.0, 0.0) (2.5e-05, 0.0) (6.0e-05, 0.0) (0.0001, 0.0) (0.00015, 0.0) (0.0002, 0.0) (0.00025, 0.0) (0.0003, 0.0) (0.00035, 0.0) (0.0004, 0.0) (0.00042, 0.0) (0.0005, 0.0) (0.0007, 0.0) (0.0008, 0.0) (5.0e-06, 5.0e-06) (1.0e-05, 1.0e-05) (2.5e-05, 2.5e-05) (5.0e-05, 5.0e-05) (0.0001, 0.0001) (0.00018, 0.0001) (0.00015, 0.00015) (0.00018, 0.00018) (0.0002, 0.0002) (0.00025, 0.00025) (0.0003, 0.0003) (0.00035, 0.00035) (450.0, 450.0)

Attribute: rated-temperature (min, max)

Values:

(-80.0, 280.0) (-65.0, 125.0) (-65.0, 150.0) (-65.0, 155.0) (-65.0, 165.0) (-65.0, 170.0) (-65.0, 175.0) (-65.0, 200.0) (-65.0, 225.0) (-65.0, 230.0) (-65.0, 250.0) (-65.0, 275.0) (-65.0, 350.0) (-60.0, 150.0) (-55.0, 105.0) (-55.0, 110.0) (-55.0, 125.0) (-55.0, 145.0) (-55.0, 150.0) (-55.0, 155.0) (-55.0, 170.0) (-55.0, 175.0) (-55.0, 180.0) (-55.0, 195.0) (-55.0, 200.0) (-55.0, 210.0) (-55.0, 215.0) (-55.0, 220.0) (-55.0, 225.0) (-55.0, 230.0) (-55.0, 235.0) (-55.0, 250.0) (-55.0, 270.0) (-55.0, 275.0) (-55.0, 300.0) (-55.0, 350.0) (-55.0, 355.0) (-50.0, 125.0) (-50.0, 150.0) (-40.0, 85.0) (-40.0, 110.0) (-40.0, 125.0) (-40.0, 130.0) (-40.0, 150.0) (-40.0, 155.0) (-40.0, 175.0) (-40.0, 200.0) (-40.0, 220.0) (-40.0, 275.0) (-25.0, 100.0) (-25.0, 125.0) (-25.0, 150.0) (-25.0, 155.0) (-20.0, 125.0) (-15.0, 105.0)

Attribute: mpn

Values:

More than 1000 values...

Attribute: dimensions (x, y, z, area)

Values:

More than 1000 values...

Attribute: stock

Values:

More than 1000 values...

Attribute: price

Values:

More than 1000 values...

Attribute: minimum_quantity

Values:

312 values

Attribute: metadata.datasheets

Values:

More than 1000 values...

Attribute: metadata.image

Values:

More than 1000 values...

Attribute: metadata.digi-key-part-number

Values:

More than 1000 values...

Attribute: metadata.description

Values:

More than 1000 values...

Attribute: metadata.series

Values:

More than 1000 values... |

Attribute: metadata.packaging

Values:

"Bag" "Box" "Bulk" "Cut Tape (CT)" "Digi-Reel®" "Strip" "Tape & Box (TB)" "Tape & Reel (TR)" "Tray" "Tube"

Attribute: metadata.features

Values:

"Anti-Arc, Current Sense, Flame Proof, Non-Inductive, Pulse Withstanding, Safety" "Anti-Arc, Flame Proof, Moisture Resistant, Non-Inductive, Safety" "Anti-Arc, Flame Proof, Moisture Resistant, Safety" "Anti-Corrosive, Automotive AEC-Q200, Moisture Resistant" "Anti-Corrosive, Current Sense, Moisture Resistant" "Anti-Corrosive, Flame Proof, Moisture Resistant, Safety" "Anti-Sulfur" "Anti-Sulfur, Automotive" "Anti-Sulfur, Automotive AEC-Q200" "Anti-Sulfur, Automotive AEC-Q200, Current Sense" "Anti-Sulfur, Automotive AEC-Q200, Current Sense, Moisture Resistant" "Anti-Sulfur, Automotive AEC-Q200, Current Sense, Moisture Resistant, Pulse Withstanding" "Anti-Sulfur, Automotive AEC-Q200, High Voltage" "Anti-Sulfur, Automotive AEC-Q200, High Voltage, Moisture Resistant" "Anti-Sulfur, Automotive AEC-Q200, Moisture Resistant" "Anti-Sulfur, Automotive AEC-Q200, Moisture Resistant, Pulse Withstanding" "Anti-Sulfur, Automotive AEC-Q200, Pulse Withstanding" "Anti-Sulfur, Current Sense" "Anti-Sulfur, Current Sense, Moisture Resistant, Pulse Withstanding" "Anti-Sulfur, Flame Proof, High Voltage, Pulse Withstanding, Safety" "Anti-Sulfur, Moisture Resistant" "Anti-Sulfur, Moisture Resistant, Non-Inductive" "Anti-Sulfur, Moisture Resistant, Non-Inductive, Non-Magnetic" "Automotive AEC-Q200" "Automotive AEC-Q200, Current Sense" "Automotive AEC-Q200, Current Sense, Moisture Resistant" "Automotive AEC-Q200, Current Sense, Moisture Resistant, Pulse Withstanding" "Automotive AEC-Q200, Current Sense, Pulse Withstanding" "Automotive AEC-Q200, Flame Retardant Coating, Safety" "Automotive AEC-Q200, High Voltage" "Automotive AEC-Q200, High Voltage, Moisture Resistant" "Automotive AEC-Q200, High Voltage, Pulse Withstanding" "Automotive AEC-Q200, Moisture Resistant" "Automotive AEC-Q200, Moisture Resistant, Non-Inductive" "Automotive AEC-Q200, Moisture Resistant, Pulse Withstanding" "Automotive AEC-Q200, Non-Inductive" "Automotive AEC-Q200, Pulse Withstanding" "Bonding Mountable, Moisture Resistant" "Bonding Mountable, Moisture Resistant, RF, High Frequency" "Current Sense" "Current Sense, Flame Proof, Moisture Resistant, Pulse Withstanding, Safety" "Current Sense, Flame Proof, Moisture Resistant, Safety" "Current Sense, Flame Proof, Non-Inductive, Pulse Withstanding, Safety" "Current Sense, Flame Proof, Pulse Withstanding, Safety" "Current Sense, Flame Proof, Safety" "Current Sense, Flame Retardant Coating, Safety" "Current Sense, Moisture Resistant" "Current Sense, Moisture Resistant, Non-Inductive" "Current Sense, Moisture Resistant, Non-Inductive, Non-Magnetic" "Current Sense, Moisture Resistant, Non-Inductive, Pulse Withstanding" "Current Sense, Moisture Resistant, Pulse Withstanding" "Current Sense, Non-Inductive" "Current Sense, Pulse Withstanding" "Flame Proof, Fusible, Moisture Resistant, Safety" "Flame Proof, Fusible, Pulse Withstanding, Safety" "Flame Proof, Fusible, Safety" "Flame Proof, High Voltage, Moisture Resistant, Non-Inductive, Safety" "Flame Proof, High Voltage, Non-Inductive, Safety" "Flame Proof, High Voltage, Pulse Withstanding, Safety" "Flame Proof, High Voltage, Safety" "Flame Proof, Moisture Resistant, Non-Inductive, Safety" "Flame Proof, Moisture Resistant, Non-Magnetic, Safety" "Flame Proof, Moisture Resistant, Pulse Withstanding, Safety" "Flame Proof, Moisture Resistant, Safety" "Flame Proof, Non-Inductive, Pulse Withstanding, Safety" "Flame Proof, Non-Inductive, Safety" "Flame Proof, Pulse Withstanding, Safety" "Flame Proof, Safety" "Flame Retardant Coating, Fusible, Pulse Withstanding, Safety" "Flame Retardant Coating, High Voltage, Moisture Resistant, Pulse Withstanding, Safety" "Flame Retardant Coating, High Voltage, Moisture Resistant, Safety" "Flame Retardant Coating, High Voltage, Pulse Withstanding, Safety" "Flame Retardant Coating, High Voltage, Safety" "Flame Retardant Coating, Military, Moisture Resistant, Safety" "Flame Retardant Coating, Moisture Resistant, Non-Inductive, Pulse Withstanding, Safety" "Flame Retardant Coating, Moisture Resistant, Safety" "Flame Retardant Coating, Non-Inductive, Safety" "Flame Retardant Coating, Pulse Withstanding, Safety" "Flame Retardant Coating, RF, High Frequency, Safety" "Flame Retardant Coating, Safety" "Fusible, Moisture Resistant, Safety" "Fusible, Pulse Withstanding, Safety" "Fusible, Safety" "High Voltage" "High Voltage, Moisture Resistant" "High Voltage, Moisture Resistant, Non-Inductive" "High Voltage, Moisture Resistant, Non-Magnetic" "High Voltage, Moisture Resistant, Pulse Withstanding" "High Voltage, Non-Inductive" "High Voltage, Non-Magnetic" "High Voltage, Pulse Withstanding" "Military" "Military, Moisture Resistant" "Military, Moisture Resistant, Non-Inductive" "Military, Moisture Resistant, Weldable" "Military, Non-Inductive" "Moisture Resistant" "Moisture Resistant, Non-Inductive" "Moisture Resistant, Non-Inductive, Non-Magnetic" "Moisture Resistant, Non-Inductive, Pulse Withstanding" "Moisture Resistant, Pulse Withstanding" "Non-Inductive" "Non-Inductive, Pulse Withstanding" "Non-Magnetic" "Pulse Withstanding" "RF, High Frequency" |

Attribute: metadata.supplier-device-package

Values:

102.0 201.0 204.0 207.0 306.0 402.0 404.0 406.0 505.0 508.0 510.0 603.0 606.0 612.0 705.0 805.0 808.0 815.0 816.0 830.0 1005.0 1010.0 1020.0 1050.0 1206.0 1210.0 1216.0 1218.0 1220.0 1224.0 1225.0 1313.0 1506.0 1575.0 1608.0 1632.0 1812.0 2010.0 2012.0 2015.0 2016.0 2208.0 2412.0 2512.0 2515.0 2520.0 2615.0 2725.0 2726.0 2728.0 2816.0 2817.0 2818.0 3014.0 3216.0 3264.0 3512.0 3637.0 3920.0 3921.0 4020.0 4026.0 4124.0 4318.0 4527.0 5020.0 5322.0 5931.0 6227.0 6432.0 6927.0 7638.0 8035.0 9045.0 11050.0 15075.0 "2-SMD" "Axial" "D-Pak in TO-263 Housing" "D2PAK" "DPAK" "D²PAK" "Flex-2" "MELF" "Mini MELF" "PFC10" "Panasert" "Powerchip®" "Radial" "Radial Lead" "SM-5" "SM2" "SMD" "SMD J-Lead, Pedestal" "SMD J-Lead, Recessed" "SR10" "SR20" "TO-126" "TO-126 (D-Pak Style)" "TO-218 (TO-247)" "TO-220" "TO-220-2" "TO-220-4" "TO-247" "TO-247-2" "TO-252" "TO-252, (D-Pak)" "TO-263" "TO-263 (D²Pak)"

Attribute: metadata.number-of-terminations

Values:

2.0 3.0 4.0

Capacitors

There are almost 1,000,000 capacitors in the JITX database but the same part can be referenced in different packaging (cut tape, reels...).

ceramic-cap finds a specific capacitor based on specified properties and stock.

look-up-ceramic-caps is a function that returns lists of capacitors based on properties and stock.

cap-strap does everything ceramic-cap does and connects it to two nets.

gen-cap-cmp allows us to place generic capacitor components for offline use.

The db-parts section describes lower level functions, and the properties section describes every available attribute we can search with.

Contents:

• ocdb/utils/generic-components
  • ceramic-cap
    • Example
  • look-up-ceramic-caps
    • Example
  • cap-strap
    • Example
  • gen-cap-cmp
    • Example
• ocdb/utils/db-parts
  • Capacitor Struct
    • Example
  • Capacitor Accessors
    • Example
  • query-available-capacitance-values
    • Example
  • look-up-capacitors
    • Example
• Properties
  • Attribute: manufacturer
  • Attribute: case
  • Attribute: rated-voltage
  • Attribute: rated-temperature (min, max)
  • Attribute :mpn
  • Attribute :capacitance
  • Attribute :dimensions
  • Attribute :mounting
  • Attribute :stock
  • Attribute :price
  • Attribute :minimum_quantity
  • Attribute :type
  • Attribute :anode
  • Attribute :electrolyte
  • Attribute :esr
  • Attribute :esr_frequency
  • Attribute :rated-voltage-ac
  • Attribute :rated-current-pk
  • Attribute :rated-current-rms
  • Attribute :temperature-coefficient.code
  • Attribute :temperature-coefficient.lower-temperature
  • Attribute :temperature-coefficient.raw_data
  • Attribute :temperature-coefficient.tolerance
  • Attribute :temperature-coefficient.upper-temperature
  • Attribute :temperature-coefficient.value
  • Attribute :tolerance
  • Attribute :temperature-coefficient.change (min, max)
  • Attribute :metadata.datasheets
  • Attribute :metadata.image
  • Attribute :metadata.digi-key-part-number
  • Attribute :metadata.description
  • Attribute :metadata.packaging
  • Attribute :metadata.ripple-current-low-frequency
  • Attribute :metadata.ripple-current-high-frequency
  • Attribute: metadata.lifetime-temp
  • Attribute: metadata.applications
  • Attribute: metadata.lead-spacing