Soup Specification - tscircuit docs

Overview

“tscircuit soup” is the name of the built low-level JSON circuit representation. It contains all the information needed to visually represent a schematic, PCB, produce Gerber files, produce bill of materials, run SPICE simulations, view warnings and more. It is designed to easily interoperate with a SQL database.

tscircuit soup is an array of objects, a tscircuit soup object looks like this:

{
  "type": "source_component",
  "ftype": "simple_resistor",
  "source_component_id": "source_component_1",
  "name": "R1"
}

Typically a component like a resistor will be made up of many soup objects. All tscircuit components (from the API reference section) have methods that convert themselves into soup. Sometimes a component will analyze the soup produce by it’s children to produce it’s own soup. For example, a <group /> will build soup for it’s children, then route traces.

Units

You can use any standard unit e.g. 0.1in or 2.54mm, these are automatically translated to the numeric value for the “default unit” after parsing.

Source

`source_simple_capacitor`

{
  "type": "source_component",
  "ftype": "simple_capacitor",
  "source_component_id": "source_component_1",
  "name": "C1",
  "capacitance": "1uF"
}

Property	Type	Required
type	string	Yes
ftype	string	Yes
source_component_id	string	Yes
name	string	Yes
capacitance	string, number	Yes

`source_simple_resistor`

{
  "type": "source_component",
  "ftype": "simple_resistor",
  "source_component_id": "source_component_1",
  "name": "R1",
  "resistance": "1k"
}

Property	Type	Required
type	string	Yes
ftype	string	Yes
source_component_id	string	Yes
name	string	Yes
resistance	string, number	Yes

Schematic

`schematic_box`

Draws a box on the schematic

{
  "type": "schematic_box",
  "schematic_component_id": "schematic_component_1",
  "width": "5mm",
  "height": "5mm",
  "x": "3mm",
  "y": "1mm"
}

Property	Type	Required
type	string	Yes
schematic_component_id	string	Yes
width	string, number	Yes
height	string, number	Yes
x	string, number	Yes
y	string, number	Yes

`schematic_component`

{
  "type": "schematic_component",
  "rotation": "90deg",
  "size": {
    "width": "5mm",
    "height": "5mm"
  },
  "center": {
    "x": "3mm",
    "y": "1mm"
  },
  "source_component_id": "source_component_1",
  "schematic_component_id": "schematic_component_1",
  "port_arrangement": {
    "left_size": 3,
    "right_size": 3
  },
  "port_labels": {
    "1": "VCC",
    "2": "GND",
    "3": "OUT"
  }
}

Property	Type	Required
type	string	Yes
rotation	string, number	No
size	object	Yes
center	object	Yes
source_component_id	string	Yes
schematic_component_id	string	Yes
port_arrangement	undefined	No
port_labels	object	No

`schematic_line`

{
  "type": "schematic_line",
  "schematic_component_id": "schematic_component_1",
  "x1": "1mm",
  "x2": "2mm",
  "y1": "1mm",
  "y2": "2mm"
}

Property	Type	Required
type	string	Yes
schematic_component_id	string	Yes
x1	string, number	Yes
x2	string, number	Yes
y1	string, number	Yes
y2	string, number	Yes

`schematic_path`

{
  "type": "schematic_path",
  "schematic_component_id": "schematic_component_1",
  "fill_color": "blue",
  "is_filled": true,
  "points": [
    {
      "x": "3mm",
      "y": "1mm"
    },
    {
      "x": "3mm",
      "y": "1mm"
    },
    {
      "x": "3mm",
      "y": "1mm"
    },
    {
      "x": "3mm",
      "y": "1mm"
    },
    {
      "x": "3mm",
      "y": "1mm"
    }
  ]
}

Property	Type	Required
type	string	Yes
schematic_component_id	string	Yes
fill_color	string	No
is_filled	boolean	No
points	array	Yes

`schematic_port`

Defines a port on a schematic component

{
  "type": "schematic_port",
  "schematic_port_id": "schematic_port_1",
  "source_port_id": "source_port_1",
  "schematic_component_id": "schematic_component_1",
  "center": {
    "x": "3mm",
    "y": "1mm"
  },
  "facing_direction": "right"
}

Property	Type	Required
type	string	Yes
schematic_port_id	string	Yes
source_port_id	string	Yes
schematic_component_id	string	No
center	object	Yes
facing_direction	string	No

`schematic_text`

{
  "type": "schematic_text",
  "schematic_component_id": "schematic_component_1",
  "schematic_text_id": "schematic_text_1",
  "text": "ea nisi sunt",
  "position": {
    "x": "3mm",
    "y": "1mm"
  },
  "rotation": "90deg",
  "anchor": "center"
}

Property	Type	Required
type	string	Yes
schematic_component_id	string	Yes
schematic_text_id	string	Yes
text	string	Yes
position	object	Yes
rotation	number	No
anchor	string	No

`schematic_trace`

{
  "type": "schematic_trace",
  "schematic_trace_id": "schematic_trace_1",
  "source_trace_id": "source_trace_1",
  "edges": [
    {
      "from": {
        "x": "3mm",
        "y": "1mm"
      },
      "to": {
        "x": "3mm",
        "y": "1mm"
      },
      "from_schematic_port_id": "from_schematic_port_1",
      "to_schematic_port_id": "to_schematic_port_1"
    },
    {
      "from": {
        "x": "3mm",
        "y": "1mm"
      },
      "to": {
        "x": "3mm",
        "y": "1mm"
      },
      "from_schematic_port_id": "from_schematic_port_1",
      "to_schematic_port_id": "to_schematic_port_1"
    }
  ]
}

Property	Type	Required
type	string	Yes
schematic_trace_id	string	Yes
source_trace_id	string	Yes
edges	array	Yes

Pcb

`pcb_component`

Defines a component on the PCB

{
  "type": "pcb_component",
  "pcb_component_id": "pcb_component_1",
  "source_component_id": "source_component_1"
}

Property	Type	Required
type	string	Yes
pcb_component_id	string	Yes
source_component_id	string	Yes

`pcb_hole`

Defines a hole on the PCB

{
  "type": "pcb_hole",
  "hole_diameter": "0.08in",
  "x": "3mm",
  "y": "1mm"
}

Property	Type	Required
type	string	Yes
hole_diameter	number	Yes
x	string, number	Yes
y	string, number	Yes

`pcb_plated_hole`

Defines a plated hole on the PCB

{
  "type": "pcb_plated_hole",
  "outer_diameter": "1.2mm",
  "hole_diameter": "0.08in",
  "x": "3mm",
  "y": "1mm",
  "layers": ["top", "bottom"],
  "pcb_component_id": "pcb_component_1",
  "pcb_port_id": "pcb_port_1"
}

Property	Type	Required
type	string	Yes
outer_diameter	number	Yes
hole_diameter	number	Yes
x	string, number	Yes
y	string, number	Yes
layers	array	Yes
port_hints	array	No
pcb_component_id	string	No
pcb_port_id	string	No

`pcb_port`

Defines a port on the PCB

{
  "type": "pcb_port",
  "pcb_port_id": "pcb_port_1",
  "source_port_id": "source_port_1",
  "x": "3mm",
  "y": "1mm",
  "layers": ["top", "bottom"]
}

Property	Type	Required
type	string	Yes
pcb_port_id	string	Yes
source_port_id	string	Yes
x	string, number	Yes
y	string, number	Yes
layers	array	Yes

`pcb_text`

Defines text on the PCB

{
  "type": "pcb_text",
  "text": "proident eu",
  "x": "3mm",
  "y": "1mm",
  "align": "bottom-left",
  "width": "5mm",
  "height": "5mm",
  "lines": 1
}

Property	Type	Required
type	string	Yes
text	string	Yes
x	string, number	Yes
y	string, number	Yes
align	string	Yes
width	string, number	Yes
height	string, number	Yes
lines	number	Yes

`pcb_trace`

{
  "type": "pcb_trace",
  "source_trace_id": "source_trace_1",
  "pcb_trace_id": "pcb_trace_1",
  "route": [
    {
      "route_type": "wire",
      "x": "3mm",
      "y": "1mm",
      "width": "5mm",
      "start_pcb_port_id": "start_pcb_port_1",
      "end_pcb_port_id": "end_pcb_port_1",
      "layer": "top"
    },
    {
      "route_type": "via",
      "x": "3mm",
      "y": "1mm",
      "from_layer": "top",
      "to_layer": "bottom"
    },
    {
      "route_type": "wire",
      "x": "3mm",
      "y": "1mm",
      "width": "5mm",
      "start_pcb_port_id": "start_pcb_port_1",
      "end_pcb_port_id": "end_pcb_port_1",
      "layer": "top"
    },
    {
      "route_type": "wire",
      "x": "3mm",
      "y": "1mm",
      "width": "5mm",
      "layer": "top"
    },
    {
      "route_type": "wire",
      "x": "3mm",
      "y": "1mm",
      "width": "5mm",
      "start_pcb_port_id": "start_pcb_port_1",
      "end_pcb_port_id": "end_pcb_port_1",
      "layer": "top"
    }
  ]
}

Property	Type	Required
type	string	Yes
source_trace_id	string	Yes
pcb_trace_id	string	Yes
route	array	Yes

`pcb_trace_error`

Defines a trace error on the PCB

{
  "pcb_error_id": "pcb_error_1",
  "type": "pcb_error",
  "error_type": "pcb_trace_error",
  "message": "dolor",
  "pcb_trace_id": "pcb_trace_1",
  "source_trace_id": "source_trace_1",
  "pcb_component_ids": ["pcb_component_1"],
  "pcb_port_ids": ["pcb_port_1", "pcb_port_2"]
}

Property	Type	Required
pcb_error_id	string	Yes
type	string	Yes
error_type	string	Yes
message	string	Yes
pcb_trace_id	string	Yes
source_trace_id	string	Yes
pcb_component_ids	array	Yes
pcb_port_ids	array	Yes

`pcb_via`

Defines a via on the PCB

{
  "type": "pcb_via",
  "x": "3mm",
  "y": "1mm",
  "outer_diameter": "1.2mm",
  "hole_diameter": "0.08in",
  "from_layer": "top",
  "to_layer": "bottom",
  "layers": ["top", "bottom"]
}

Property	Type	Required
type	string	Yes
x	string, number	Yes
y	string, number	Yes
outer_diameter	string, number	No
hole_diameter	string, number	No
from_layer	undefined	No
to_layer	undefined	No
layers	array	Yes

Misc

`any_soup_element`

`capacitance`

"1uF"

`current`

"1A"

`distance`

"10mm"

`inductance`

"1mH"

`layer_ref`

"top"

`layer_string`

"inner-6"

`length`

"1m"

`pcb_route_hint`

{
  "x": "3mm",
  "y": "1mm",
  "via": true,
  "via_to_layer": "inner-1"
}

Property	Type	Required
x	string, number	Yes
y	string, number	Yes
via	boolean	No
via_to_layer	undefined	No

`pcb_route_hints`

[
  {
    "x": "5mm",
    "y": "6mm",
    "via": false
  }
]

`pcb_smtpad`

Defines an SMT pad on the PCB

{
  "type": "pcb_smtpad",
  "shape": "circle",
  "x": "3mm",
  "y": "1mm",
  "radius": "5mm",
  "layer": "top",
  "port_hints": ["1", "left"],
  "pcb_component_id": "pcb_component_1",
  "pcb_port_id": "pcb_port_1"
}

`point`

{
  "x": "3mm",
  "y": "1mm"
}

Property	Type	Required	Description
x	string, number	Yes
y	string, number	Yes

`position`

{
  "x": "3mm",
  "y": "1mm"
}

Property	Type	Required	Description
x	string, number	Yes
y	string, number	Yes

`resistance`

"1k"

`rotation`

"90deg"

`size`

{
  "width": "5mm",
  "height": "5mm"
}

Property	Type	Required	Description
width	number	Yes
height	number	Yes

`time`

"60s"

`voltage`

"5V"

Core Components

Footprint Components

Schematic Symbol Components

Layout Engines

Advanced

​Overview

​Units

​Source

​source_simple_capacitor

​source_simple_resistor

​Schematic

​schematic_box

​schematic_component

​schematic_line

​schematic_path

​schematic_port

​schematic_text

​schematic_trace

​Pcb

​pcb_component

​pcb_hole

​pcb_plated_hole

​pcb_port

​pcb_text

​pcb_trace

​pcb_trace_error

​pcb_via

​Misc

​any_soup_element

​capacitance

​current

​distance

​inductance

​layer_ref

​layer_string

​length

​pcb_route_hint

​pcb_route_hints

​pcb_smtpad

​point

​position

​resistance

​rotation

​size

​time

​voltage