footprinter

@tscircuit/footprinter

Footprinter is tscircuit's DSL and micro-builder for creating footprints.

You can create very custom footprints using the <footprint> element, but the compressability is poor. footprinter produces very short, low parameter mini-programs for generating footprints, this makes it suitable for standardized footprints. You can use it with any component that accepts a footprint prop, e.g. <bug footprint="qfp12_p0.5" />

Here are some example programs:

import { fp } from "@tscircuit/footprinter"

fp.cap().w(0.4).h(0.2)
fp.cap().p(0.1).pw(0.1).ph(0.1) // pitch, pad width and pad height
fp.cap().metric("0402")
fp.res().imperial("01005")
fp.dip(4).w(7.62)
fp.dip(4).w(7.62).socket()

[!NOTE] Footprinter is the DSL that text-to-footprint uses. If you're unable to generate a particular footprint, try to see if you can produce it in footprinter. If you can't, you'll need to add some kind of representation in the DSL before it can be generated.

[!NOTE] Compressability of the DSL is important because it allows an LLM to fit more examples into context, and not waste output tokens on verbose elements

Footprinter Strings

A footprinter string is a string that maps to a set of builder calls.

import { fp } from "@tscircuit/footprinter"

fp.string("dip4_w7.62") // same as fp.dip(4).w(7.62)
fp.string("dip4_w7.62mm") // same as fp.dip(4).w(7.62)
fp.string("dip4_w0.3in") // same as fp.dip(4).w("0.3in")

Getting JSON output from the builder

Use the .soup() function to output tscircuit soup JSON

fp.string("res0402").soup()
/*
[
  {
    type: 'pcb_smtpad',
    x: -0.5,
    y: 0,
    width: 0.6000000000000001,
    height: 0.6000000000000001,
    layer: 'top',
    shape: 'rect',
    pcb_smtpad_id: '',
    port_hints: [ '1' ]
  },
  {
    type: 'pcb_smtpad',
    x: 0.5,
    y: 0,
    width: 0.6000000000000001,
    height: 0.6000000000000001,
    layer: 'top',
    shape: 'rect',
    pcb_smtpad_id: '',
    port_hints: [ '2' ]
  }
]
*/

Generation Defaults

• Pins are CCW starting at the top left
• Y is upward-positive, X is rightward-positive

Slop

Slop is a "sloppy" definition, it really doesn't have enough information to draw a footprint, i.e. it's missing critical dimensions.

footprinter is extremely tolerant to Slop, because it's useful when you're iterating incrementally towards a fully constrained design, or when you're using footprinter strings as an output format for an AI.

Generally when footprinter is interpreting a sloppy definition, it will use industry best practices or otherwise "reasonable" defaults. In theory, upgrading footprinter could cause the defaults to change, which is why sloppy definitions are generally not desirable.

An example of a sloppy definition is bga64. It's very underconstrained and unlikely to be correct (what's the pitch? pad size?). tscircuit strict mode or a linter will eventually error if it sees these.

Adding a new footprint function

You can add new footprint functions by introducing a new function in the src/fn directory. You'll also need to export it from the footprint function index file

After you've written the function, you can introduce a quick test, e.g. soic.test.ts Currently it's not possible to see if a given definition is sloppy.

To run tests, just run npx ava ./tests/soic.test.ts or whatever your test file is.

You'll sometimes see this logSoup function- this makes some debug output appear at https://debug.tscircuit.com. Make sure to hit "pcb" and "pcb_renderer" after the design.