Components¶

A pcb-component statement defines a model for a single part that can be placed on a board. There are many examples of component definitions to be found in the open-components-database. Components have ports, schematic symbols, a landpattern, and associated metadata.

The primary functions of the pcb-component statement are:

Provide the sourcing information to include this component in the BOM
Provide the mapping between schematic symbol pins and land pattern pads.
Provide the electrical interface to a component and make abstractions where necessary.
Provide engineering data for signal integrity and other analysis.

Signature¶

pcb-component comp-name (arg1:Type1, ...) :
  name = <String>
  description = <String|False>
  manufacturer = <String|False>
  mpn = <String|False>
  datasheet = <String|False>
  reference-prefix = <String>

  <PORT-1>
  ...

  <PIN-PROP-TABLE-1>
  ...

  <SYMBOL>
  <LANDPATTERN>

  ; Simulation Support
  emodel = <MODEL>

  ; SI Pin Model Definitions
  pin-model(<PORT-1>) = PinModel(...)
  pin-model(<PORT-1>, <PORT-2>) = PinModel(...)

  ; Property Definitions
  property(self.<PROP-NAME-1>) = <JITXValue>
  ...
  property(self.<PORT-1>.<PROP-NAME>) = <JITXValue>
  ...

  <SUPPORTS-1>
  ...

  no-connect(<PORT-1>)

  <EVAL-WHEN-1>
  ...

The expression name comp-name uniquely identifies this component definition in the current context.

The argument list (arg1:Type1, ...) is optional and provides a means of constructing parameterized component definitions.

Required Parameters¶

<SYMBOL> - The symbol statement defines the schematic symbol representation for this component. There are two primary forms:
- Symbol Mapping Form - Explicit Mapping of component ports to symbol pins
- Symbol Unit Form - Allows mapping multiple symbol units to the ports of a component.
- The assign-symbol utility is a tool for automating this mapping with the help of the pin property table.
- Only one symbol statement is allowed per component.
<LANDPATTERN> - The landpattern statement defines the land pattern (or footprint) for this component and the mapping from component ports to land pattern pads.
- The assign-landpattern utility is a tool for automating this mapping with the help of the pin property table.
- Only one landpattern statement is allowed per component.

Optional Parameters¶

name - This name is used in the Board UI as a more user friendly name. If this string is not provided then the comp-name expression is used as the component's name.
description - This string is defining more meta-data for the component.
manufacturer - This string defines the manufacturer for this component.
mpn - This string defines the manufacturer's part number for this component.
datasheet - This string defines the URL to the datasheet for this component.
reference-prefix - This string defines the reference designator prefix, for example C for capacitors, R for resistors, Q for transistors, etc. It not provided, this defaults to U.
<PORT-1> - A component typically has zero or more port statements.
<PIN-PROP-TABLE-1> - A component may have 1 or more pin property tables that provide a convenient way to specify the symbol to landpattern mapping.
emodel - The emodel statement allows the user to associate a simulation model with this component. Only one statement of this type is allowed per component definition.
pin-model - The pin-model statement is a means of associating a Signal Integrity model with a particular component's ports.
property - The property statement allows the user the opportunity to associate data with the component itself or with individual ports of the component.
<SUPPORTS-1> - The supports statement allows the user to define pin assignment problems.
no-connect - The no-connect statement allows the user to mark a port on a component as not connected to any net and reserving that state as not an error.
<EVAL-WHEN-1> - The eval-when statement provides a convenient method to generate checks on a component later in the design run after the circuit's structure has been built.

Usage¶

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"
  reference-prefix = "Y"

  ; Port Declarations
  port p : pin[[1 2]]

  ; Symbol to Land Pattern Mapping
  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])

  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

It is common to place the manufacturer, mpn, datasheet, and similar labels near the top of a pcb-component definition.

The port declarations define the electrical interface to this component.

The symbol and landpattern statements define the mapping between the symbol, the landpattern, and the electrical interface of this component.

The property statements provide meta-data and characteristics for this device or for any of its ports.

Port Declaration¶

There are three main ways to declare the ports of a pcb-component.

Explicit Port Declarations
Pin Property Table
Combination of Explicit and Pin Property Table

The epson-fc-135 definition above is an example of "Explicit Port Declarations". With explicit port declarations, we must use the explicit mapping forms of the symbol and landpattern statements.

The Pin Properties Table is a convenience mechanism for mapping the component ports to schematic symbol pins and land-pattern pads. It also simplifies the process of constructing ports.

pcb-component NPN :

  pin-properties:
    [pin:Ref | pads:Int ...]
    [b       | 1 ]
    [c       | 2 ]
    [e       | 3 ]

  assign-symbol(bjt-sym())
  assign-landpattern(SOT95P280X100-3N)

Notice that in this example - there are no port statements to explicitly declare the ports b, c, or e. The pin-properties table constructs these ports as SinglePin ports if they are not found at run time.

Combining Explicit & Pin Properties Table¶

Sometimes is very useful to combine these two approaches. This is especially true when we want the interface to a component to be bundle defined. For example:

pcb-component accelerometer:

  port bus : i2c

  pin-properties:
    [pin:Ref       | pads:Int ... | side:Dir ]
    [bus.sda       | 1            | Left  ]
    [bus.scl       | 2            | Left  ]
    [VDD           | 3            | Right ]
    [GND           | 4            | Left  ]
    [ADDR          | 5            | Right ]

  make-box-symbol()
  assign-landpattern(SOT95P280X145-5N)

This example is a bit contrived - but the idea here is that we can forward declare ports that are not of type SinglePin. In this example, bus is a Bundle type port. The properties table can then refer to individual SinglePin ports of the bus port. In this case the i2c bundle only has the sda and scl ports.

Supports & Requires¶

The pcb-component statement can contain supports statements. These statements provide a means of constructing pin assignment problems.

pcb-component MCU:

  pin-properties:
    [pin:Ref | pads:Int ... ]
    for i in 1 through 16 do:
      [ PA[i] | i ]  

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

While supports statements can be used at will in a pcb-component context, the require statement is more restricted. Placing a restrict statement in the body of a pcb-component statement will result in an error:

pcb-component MCU:
  pin-properties:
    [pin:Ref | pads:Int ... ]
    for i in 1 through 16 do:
      [ PA[i] | i ]  

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

  require bus:i2c from self

The last line of this example will elicit the following error:

Errors occurred during parsing:

... Syntax Error: Expression expected here.

The require statement can be used from within a supports statement:

pcb-component MCU:
  pin-properties:
    [pin:Ref | pads:Int ... ]
    for i in 1 through 16 do:
      [ PA[i] | i ]

  for i in i through 16 do:
    supports gpio:
      gpio.gpio => PA[i]

  supports i2c:
    require p1:gpio
    require p2:gpio
    i2c.sda => p1
    i2c.scl => p2

Notice that this creates a cascade of supports and require statements. We call this a Nested supports or require statement. We first create a supports statement for each of the GPIO pins in port PA. Then in the supports i2c: statement, we require two of these GPIO pins and assign them to the pending ports for this supports statement (ie i2c.sda and i2c.scl).

This syntax will not result in a parsing error.

Mapping to the `>VALUE` template¶

In a pcb-component definition, there are two ways to set the >VALUE template parameter:

Use the mpn statement - Directly copies the string value of MPN to the >VALUE template locations.
Use the emodel statement - Formats the value (resistors, capacitance, etc) with proper unit prefix (ie, 4.7e3 maps to 4.7k) and generates a string representation.

The emodel statement takes higher precedence than the mpn. So if you add both statements, then the emodel value will override the mpn.

There is also a value-label statement within the pcb-module context that can override the value from outside the pcb-component definition on a per instance basis.

Statements¶

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

Statement	Description
`datasheet`	URL reference to Datasheet for component
`description`	Description for the component
`emodel`	EModel for the component
`eval-when`	Conditional evaluation of code.
`landpattern`	Physical land-pattern/footprint for the component. Also mapped to component ports.
`manufacturer`	Manufacturer of the component
`mpn`	Manufacturer part number of the component
`name`	Name of the component
`no-connect`	Set a port as "Not Connected"
`pin-properties`	An easy way to map component ports to pins on a landpattern.
`ports`	Ports usable when this component is instantiated in a module
`property`	Properties of the component or its ports.
`reference-prefix`	Start of the reference designator (default is "U").
`require`	Construct Abstract Ports inside `supports` statements
`supports`	Supported peripherals for automated pin solving.
`symbol`	Schematic symbol for the component. Mapped to the defined ports.