This file is a merged representation of a subset of the codebase, containing specifically included files, combined into a single document by Repomix.

<file_summary>
This section contains a summary of this file.

<purpose>
This file contains a packed representation of the entire repository's contents.
It is designed to be easily consumable by AI systems for analysis, code review,
or other automated processes.
</purpose>

<file_format>
The content is organized as follows:
1. This summary section
2. Repository information
3. Directory structure
4. Repository files (if enabled)
5. Multiple file entries, each consisting of:
  - File path as an attribute
  - Full contents of the file
</file_format>

<usage_guidelines>
- This file should be treated as read-only. Any changes should be made to the
  original repository files, not this packed version.
- When processing this file, use the file path to distinguish
  between different files in the repository.
- Be aware that this file may contain sensitive information. Handle it with
  the same level of security as you would the original repository.
</usage_guidelines>

<notes>
- Some files may have been excluded based on .gitignore rules and Repomix's configuration
- Binary files are not included in this packed representation. Please refer to the Repository Structure section for a complete list of file paths, including binary files
- Only files matching these patterns are included: **/*.md, **/*.mdx
- Files matching patterns in .gitignore are excluded
- Files matching default ignore patterns are excluded
- Files are sorted by Git change count (files with more changes are at the bottom)
</notes>

</file_summary>

<directory_structure>
docs/
  advanced/
    ai-context.mdx
    math-utils.mdx
    simple-route-json.mdx
    units.md
  building-electronics/
    designing-electronics-from-scratch.md
    ordering-prototypes.mdx
    what-are-electronics-made-of.mdx
  command-line/
    tsci-add.mdx
    tsci-auth-print-token.md
    tsci-build.md
    tsci-dev.md
    tsci-export.md
    tsci-init.md
    tsci-login.md
    tsci-push.md
    tsci-snapshot.md
  contributing/
    bounties-and-sponsorship.md
    getting-started-as-a-contributor.md
    overview-of-projects.md
    report-autorouter-bugs.md
    the-contributor-handbook.md
  elements/
    board.mdx
    breakout.mdx
    breakoutpoint.mdx
    capacitor.mdx
    chip.mdx
    crystal.mdx
    diode.mdx
    footprint.mdx
    group.mdx
    hole.mdx
    jumper.mdx
    led.mdx
    mosfet.mdx
    net.mdx
    netlabel.mdx
    pinheader.mdx
    potentiometer.mdx
    pushbutton.mdx
    resistor.mdx
    resonator.mdx
    schematictext.mdx
    solderjumper.mdx
    subcircuit.mdx
    switch.mdx
    trace.mdx
    transistor.mdx
    via.mdx
  footprints/
    constraint.mdx
    footprint-elements-vs-footprint-strings.mdx
    footprinter-strings.mdx
    platedhole.mdx
    silkscreencircle.mdx
    silkscreenline.mdx
    silkscreenpath.mdx
    silkscreenrect.mdx
    silkscreentext.mdx
    smtpad.mdx
  guides/
    importing-modules-and-chips/
      importing-from-circuit-json.mdx
      importing-from-jlcpcb.mdx
      importing-from-kicad.md
    automatic-layout.mdx
    configuring-chips.mdx
    displaying-circuit-json-on-a-webpage.mdx
    essential-elements.mdx
    layout-properties.mdx
    manual-edits.mdx
    platform-configuration.md
    port-and-net-selectors.md
    programmatically-building-circuits.md
    running-tscircuit-inside-an-iframe.mdx
    understanding-fabrication-files.md
    using-sel-references.mdx
    using-tscircuit-without-react.mdx
  intro/
    installation.md
    quickstart-cli.md
    quickstart-web.md
    what-is-tscircuit.mdx
  tutorials/
    build-a-custom-keyboard-with-tscircuit.mdx
    building-a-simple-usb-flashlight.mdx
    building-led-matrix.mdx
  web-apis/
    autorouting-api.mdx
    compile-api.md
    datasheet-api.md
    datasheet-sdk.md
    image-generation-api.mdx
    ordering-api.mdx
    the-registry-api.md
CLAUDE.md
README.md
</directory_structure>

<files>
This section contains the contents of the repository's files.

<file path="docs/advanced/math-utils.mdx">
---
title: Math Utils
description: >-
  The `@tscircuit/math-utils` package provides a set of utilities that are
  commonly used in circuit design. The `@tscircuit/math-utils` package is
  generally available in any platform that uses `tscircuit`.
---

## Overview

The `@tscircuit/math-utils` package provides a set of utilities that are
commonly used in circuit design. The `@tscircuit/math-utils` package is
generally available in any platform that uses `tscircuit`.

The source code for the `@tscircuit/math-utils` package [is available here](https://github.com/tscircuit/math-utils)


## `grid`

A utility function that generates a grid of cells with configurable dimensions, spacing, and positioning. Each cell contains its index, position (row/column), and coordinate points (center, top-left, bottom-right).

```tsx
import { grid } from "@tscircuit/math-utils"

const gridCells = grid({
  rows: 3,
  cols: 3,
  width: 300,   // optional
  height: 300,  // optional
  xSpacing: 100,  // optional, default: 1
  ySpacing: 100,  // optional, default: 1
  offsetX: 0,     // optional, default: 0
  offsetY: 0,     // optional, default: 0
  yDirection: "cartesian", // optional, default: "cartesian"
  centered: true  // optional, default: true
})

export default () => (
  <board width="30mm" height="30mm">
    {gridCells.map((cell) => (
      <led
        name={`LED${cell.index}`}
        footprint="led_0402"
        schX={cell.center.x}
        schY={cell.center.y}
        pcbX={cell.center.x}
        pcbY={cell.center.y}
      />
    ))}
  </board>
)
```

The array of `GridCellPositions` contains:
- `index`: Sequential cell number
- `row`, `col`: Grid position
- `center`, `topLeft`, `bottomRight`: Coordinate points
</file>

<file path="docs/advanced/simple-route-json.mdx">
---
title: Simple Route JSON
description: >-
  Simple Route JSON (SRJ) is a lightweight, straightforward format designed to
  describe a Printed Circuit Board (PCB) routing problem. It serves as a common
  intermediary representation used by `tscircuit` autorouters, simplifying the
  complex details often found in full PCB design files.
---

## Overview

Simple Route JSON (SRJ) is a lightweight, straightforward format designed to describe a Printed Circuit Board (PCB) routing problem. It serves as a common intermediary representation used by [`tscircuit` autorouters](https://github.com/tscircuit/unravel-autorouter), simplifying the complex details often found in full PCB design files.

The primary goal of SRJ is to provide only the essential information required for a routing algorithm:
1.  Where routing is allowed (layers, board boundaries).
2.  Where routing is forbidden (obstacles, keep-out areas).
3.  What needs to be connected (nets and their associated pins/pads).
4.  Basic routing constraints (minimum trace width).

SRJ can be directly generated from more comprehensive formats like [Circuit JSON](https://circuitjson.com), stripping away details irrelevant to the core routing task (e.g., specific component models, schematic information beyond connectivity). It shares conceptual similarities with the industry-standard [Specctra DSN (Design)](https://github.com/tscircuit/dsn-converter) format, but aims for greater simplicity and modern JSON representation.

:::info
A formal specification with versioning is planned for the future. To stay updated on its release and other tscircuit developments, please subscribe to [the tscircuit newsletter](https://blog.tscircuit.com/).
:::

## Format Structure

A Simple Route JSON file is a single JSON object containing the definition of the board layout, obstacles, and connections needed for routing.

```typescript
export interface SimpleRouteJson {
  /** The total number of conductive layers on the PCB. */
  layerCount: number;

  /** The default or minimum width for traces. Specific trace segments might override this if the format evolves, but currently used as a general guideline. Units are implicit (e.g., mm, inches) and must be consistent throughout the file. */
  minTraceWidth: number;

  /** An array of obstacles on the board, such as component pads, mounting holes, or keep-out areas. */
  obstacles: Obstacle[];

  /** An array defining the electrical connections (nets) that need to be routed. */
  connections: Array<SimpleRouteConnection>;

  /** The bounding box defining the extents of the routing area. */
  bounds: { minX: number; maxX: number; minY: number; maxY: number };

  /** [Optional] The routing solution provided by an autorouter. This array contains the actual paths of the traces. It is typically absent in the input file given to a router and present in the output file. */
  traces?: SimplifiedPcbTrace[];
}
```

## Top-Level Properties

### `layerCount`

*   **Type:** `number`
*   **Description:** An integer specifying the total number of conductive layers available for routing on the PCB. Layers are typically identified by string names (e.g., `"top"`, `"inner1"`, `"bottom"`) within other parts of the format (like `obstacles` and `connections`). While `layerCount` provides the total number, the specific layer names used must be consistent throughout the file.

### `minTraceWidth`

*   **Type:** `number`
*   **Description:** Specifies the default or minimum trace width to be used by the autorouter. This acts as a global constraint. Future versions or specific router implementations might allow per-net or per-segment width rules, but this provides a baseline.
*   **Units:** Units (e.g., millimeters, inches) are not explicitly defined by the format. It is crucial that the same unit system is used consistently for all dimensional values (`minTraceWidth`, `obstacles`, `bounds`, coordinates) within a single SRJ file. Millimeters (mm) are commonly used.

### `obstacles`

*   **Type:** `Array<Obstacle>`
*   **Description:** An array containing objects that represent areas on the PCB where routing is either restricted or represents a connection point. Obstacles can be physical component pads, mounting holes, board edges defined as keep-outs, or explicit keep-out zones.

```typescript
export type Obstacle = {
  /** The shape of the obstacle. Currently, only "rect" is standard. Oval shapes might be included in future revisions. */
  type: "rect"; // NOTE: most datasets do not contain ovals

  /** An array of layer names (strings) on which this obstacle exists. An obstacle can span multiple layers (e.g., a plated through-hole pad). */
  layers: string[];

  /** The center coordinates of the obstacle. */
  center: { x: number; y: number };

  /** The width of the rectangular obstacle. */
  width: number;

  /** The height of the rectangular obstacle. */
  height: number;

  /** An array of connection names (strings) that this obstacle is part of. If this obstacle is a pad for a net (e.g., "GND", "VCC"), the net name(s) will be listed here. If the array is empty, the obstacle is typically a keep-out area or an unconnected feature. */
  connectedTo: string[];
};
```
*   **`type`**: Defines the geometry. Currently `"rect"` is the standard.
*   **`layers`**: Specifies which layer(s) the obstacle occupies. Important for multi-layer routing.
*   **`center`, `width`, `height`**: Define the geometry and position of the rectangle. Units must be consistent with `minTraceWidth` and `bounds`.
*   **`connectedTo`**: This critical field links obstacles (like pads) to the electrical nets defined in the `connections` array. If an obstacle represents a pin for the "VCC" net, `connectedTo` would contain `["VCC"]`.

### `connections`

*   **Type:** `Array<SimpleRouteConnection>`
*   **Description:** Defines the sets of points that need to be electrically connected. Each object in the array represents a single net (e.g., power, ground, signal).

```typescript
export interface SimpleRouteConnection {
  /** The unique name of the connection or net (e.g., "GND", "VCC", "DATA0"). This name is referenced by Obstacle.connectedTo. */
  name: string;

  /** An array of points that must be connected together to form this net. Each point typically corresponds to the center of an obstacle (pad) belonging to this net. */
  pointsToConnect: Array<{
    /** The x-coordinate of the connection point. */
    x: number;
    /** The y-coordinate of the connection point. */
    y: number;
    /** The layer name (string) on which this connection point resides. */
    layer: string;
  }>;
}
```
*   **`name`**: A unique string identifier for the net. This is used to link `Obstacle` objects (pads) to their respective nets.
*   **`pointsToConnect`**: An array listing the specific locations (`x`, `y`, `layer`) that the router must connect. These points usually align with the `center` coordinates and `layers` of the corresponding `Obstacle` objects linked via the `name`.

### `bounds`

*   **Type:** `object`
*   **Description:** Defines the rectangular boundary of the area where routing is permitted. Traces should generally not extend beyond these limits.
*   **Structure:**
    *   `minX`: The minimum x-coordinate of the routing area.
    *   `maxX`: The maximum x-coordinate of the routing area.
    *   `minY`: The minimum y-coordinate of the routing area.
    *   `maxY`: The maximum y-coordinate of the routing area.
*   **Units:** Must be consistent with other dimensional values in the file.

### `traces` (Optional)

*   **Type:** `Array<SimplifiedPcbTrace>`
*   **Description:** This array represents the output of an autorouter – the actual geometric paths (traces and vias) that implement the required connections. It is typically **not present** in the input SRJ file given to the router.
*   **Presence:** Included in the SRJ file *after* routing has been successfully completed.

```typescript
export type SimplifiedPcbTrace = {
  /** Identifier indicating the object type. Always "pcb_trace". */
  type: "pcb_trace";

  /** A unique identifier for this specific trace path. */
  pcb_trace_id: string;

  /** [Optional] The name of the connection/net this trace belongs to. Links the solved route back to the SimpleRouteConnection definition. */
  connection_name?: string;

  /** An array defining the geometry of the trace path, composed of wire segments and vias. */
  route: Array<
    | {
        /** Indicates a straight wire segment on a single layer. */
        route_type: "wire";
        /** The x-coordinate of the *end* point of the wire segment. */
        x: number;
        /** The y-coordinate of the *end* point of the wire segment. */
        y: number;
        /** The width of this wire segment. */
        width: number;
        /** The layer name (string) this wire segment is on. */
        layer: string;
      }
    | {
        /** Indicates a via connecting two layers. */
        route_type: "via";
        /** The x-coordinate of the via's center. */
        x: number;
        /** The y-coordinate of the via's center. */
        y: number;
        /** The layer name (string) the via transitions *to*. */
        to_layer: string;
        /** The layer name (string) the via transitions *from*. */
        from_layer: string;
      }
  >;
};
```
*   **`type`**: Always `"pcb_trace"`.
*   **`pcb_trace_id`**: Unique ID for the trace.
*   **`connection_name`**: Links trace to the net name from `connections`.
*   **`route`**: An ordered array describing the path:
    *   **`wire`**: Represents a straight segment of copper trace. The segment runs from the end point of the previous element in the `route` array (or an initial connection point) to the specified `(x, y)` coordinate on the given `layer` with the specified `width`.
    *   **`via`**: Represents a vertical connection between layers at `(x, y)`, transitioning from `from_layer` to `to_layer`. Note that physical via characteristics (drill size, annular ring) are not detailed in this simplified format.

## Example

```json
{
  "layerCount": 2,
  "minTraceWidth": 0.15,
  "obstacles": [
    {
      "type": "rect",
      "layers": ["top"],
      "center": { "x": 10, "y": 10 },
      "width": 1.2,
      "height": 1.2,
      "connectedTo": ["VCC"]
    },
    {
      "type": "rect",
      "layers": ["top"],
      "center": { "x": 30, "y": 10 },
      "width": 1.2,
      "height": 1.2,
      "connectedTo": ["VCC"]
    },
    {
      "type": "rect",
      "layers": ["bottom"],
      "center": { "x": 20, "y": 25 },
      "width": 1.2,
      "height": 1.2,
      "connectedTo": ["GND"]
    },
    {
      "type": "rect",
      "layers": ["bottom"],
      "center": { "x": 40, "y": 25 },
      "width": 1.2,
      "height": 1.2,
      "connectedTo": ["GND"]
    },
    {
      "type": "rect",
      "layers": ["top", "bottom"], // Keepout on both layers
      "center": { "x": 25, "y": 15 },
      "width": 5,
      "height": 3,
      "connectedTo": [] // Empty means it's a keepout
    }
  ],
  "connections": [
    {
      "name": "VCC",
      "pointsToConnect": [
        { "x": 10, "y": 10, "layer": "top" },
        { "x": 30, "y": 10, "layer": "top" }
      ]
    },
    {
      "name": "GND",
      "pointsToConnect": [
        { "x": 20, "y": 25, "layer": "bottom" },
        { "x": 40, "y": 25, "layer": "bottom" }
      ]
    }
  ],
  "bounds": {
    "minX": 0,
    "maxX": 50,
    "minY": 0,
    "maxY": 40
  },
  // --- TRACES SECTION (added by router) ---
  "traces": [
    {
      "type": "pcb_trace",
      "pcb_trace_id": "trace_vcc_1",
      "connection_name": "VCC",
      "route": [
        { "route_type": "wire", "x": 10, "y": 10, "width": 0.15, "layer": "top" }, // Start implicitly at first point
        { "route_type": "wire", "x": 20, "y": 5, "width": 0.15, "layer": "top" },
        { "route_type": "wire", "x": 30, "y": 10, "width": 0.15, "layer": "top" }  // End at second point
      ]
    },
    {
      "type": "pcb_trace",
      "pcb_trace_id": "trace_gnd_1",
      "connection_name": "GND",
      "route": [
        { "route_type": "wire", "x": 20, "y": 25, "width": 0.15, "layer": "bottom" }, // Start implicitly at first point
        // Example with a via
        { "route_type": "wire", "x": 30, "y": 25, "width": 0.15, "layer": "bottom" },
        { "route_type": "via", "x": 30, "y": 25, "from_layer": "bottom", "to_layer": "top" },
        { "route_type": "wire", "x": 30, "y": 20, "width": 0.15, "layer": "top" }, // Segment on top layer
        { "route_type": "via", "x": 30, "y": 20, "from_layer": "top", "to_layer": "bottom" },
        { "route_type": "wire", "x": 40, "y": 25, "width": 0.15, "layer": "bottom" }  // End at second point
      ]
    }
  ]
}
```

## Units and Coordinate System

The Simple Route JSON format does **not** enforce specific units (e.g., mm, mil, inches) or a coordinate system origin (e.g., top-left, bottom-left).

*   **Consistency is Key:** All dimensional values (`minTraceWidth`, obstacle `width`/`height`, `bounds`, all `x`/`y` coordinates in `obstacles`, `connections`, and `traces`) within a single SRJ file **must** use the same units.
*   **Common Practice:** Millimeters (mm) are frequently used.
*   **Origin:** The coordinate system origin is typically assumed to be top-left or bottom-left, with X increasing to the right and Y increasing downwards (top-left) or upwards (bottom-left). Consistency within the file and between the SRJ generator and consumer (the autorouter) is essential.

## Relationship to Other Formats

*   **Circuit JSON:** Simple Route JSON is a simplified derivative of Circuit JSON. Tools can convert Circuit JSON to SRJ by extracting layer stackup information, component pad locations and net assignments, board outlines, and any defined keep-out areas. Information not relevant to routing (e.g., schematic IDs, component values, 3D models) is omitted.
*   **Specctra DSN:** SRJ serves a similar purpose to DSN files – describing a routing problem. However, SRJ uses a modern JSON structure, which is often easier to parse and generate in web-based and JavaScript/TypeScript environments compared to the text-based, keyword-driven DSN format. The `dsn-converter` tool ([link](https://github.com/tscircuit/dsn-converter)) can facilitate conversion between DSN and SRJ or similar formats.

## Usage

The primary use case for Simple Route JSON is as the input and output format for `tscircuit` autorouting tools.

1.  **Input:** A PCB design tool or conversion script generates an SRJ file describing the board, obstacles, and connections. This file is fed into an autorouter.
2.  **Output:** The autorouter processes the input SRJ, computes the trace paths, and outputs a new SRJ file that includes the original data plus the `traces` array detailing the solution.
3.  **Post-processing:** The output SRJ (with traces) can then be converted back into a format compatible with PCB design software (like Circuit JSON, KiCad, Eagle, etc.) to integrate the routing solution into the full PCB design.
``````markdown
---
title: Simple Route JSON
---

## Overview

Simple Route JSON (SRJ) is a lightweight, straightforward format designed to describe a Printed Circuit Board (PCB) routing problem. It serves as a common intermediary representation used by `tscircuit` autorouters, simplifying the complex details often found in full PCB design files.

The primary goal of SRJ is to provide only the essential information required for a routing algorithm:
1.  Where routing is allowed (layers, board boundaries).
2.  Where routing is forbidden (obstacles, keep-out areas).
3.  What needs to be connected (nets and their associated pins/pads).
4.  Basic routing constraints (minimum trace width).

SRJ can be directly generated from more comprehensive formats like [Circuit JSON](https://circuitjson.com), stripping away details irrelevant to the core routing task (e.g., specific component models, schematic information beyond connectivity). It shares conceptual similarities with the industry-standard [Specctra DSN (Design)](https://github.com/tscircuit/dsn-converter) format, but aims for greater simplicity and modern JSON representation.

:::info
A formal specification with versioning is planned for the future. To stay updated on its release and other tscircuit developments, please subscribe to [the tscircuit newsletter](https://blog.tscircuit.com/).
:::

## Format Structure

A Simple Route JSON file is a single JSON object containing the definition of the board layout, obstacles, and connections needed for routing.

```typescript
export interface SimpleRouteJson {
  /** The total number of conductive layers on the PCB. */
  layerCount: number;

  /** The default or minimum width for traces. Specific trace segments might override this if the format evolves, but currently used as a general guideline. Units are implicit (e.g., mm, inches) and must be consistent throughout the file. */
  minTraceWidth: number;

  /** An array of obstacles on the board, such as component pads, mounting holes, or keep-out areas. */
  obstacles: Obstacle[];

  /** An array defining the electrical connections (nets) that need to be routed. */
  connections: Array<SimpleRouteConnection>;

  /** The bounding box defining the extents of the routing area. */
  bounds: { minX: number; maxX: number; minY: number; maxY: number };

  /** [Optional] The routing solution provided by an autorouter. This array contains the actual paths of the traces. It is typically absent in the input file given to a router and present in the output file. */
  traces?: SimplifiedPcbTrace[];
}
```

## Top-Level Properties

### `layerCount`

*   **Type:** `number`
*   **Description:** An integer specifying the total number of conductive layers available for routing on the PCB. Layers are typically identified by string names (e.g., `"top"`, `"inner1"`, `"bottom"`) within other parts of the format (like `obstacles` and `connections`). While `layerCount` provides the total number, the specific layer names used must be consistent throughout the file.

### `minTraceWidth`

*   **Type:** `number`
*   **Description:** Specifies the default or minimum trace width to be used by the autorouter. This acts as a global constraint. Future versions or specific router implementations might allow per-net or per-segment width rules, but this provides a baseline.
*   **Units:** Units (e.g., millimeters, inches) are not explicitly defined by the format. It is crucial that the same unit system is used consistently for all dimensional values (`minTraceWidth`, `obstacles`, `bounds`, coordinates) within a single SRJ file. Millimeters (mm) are commonly used.

### `obstacles`

*   **Type:** `Array<Obstacle>`
*   **Description:** An array containing objects that represent areas on the PCB where routing is either restricted or represents a connection point. Obstacles can be physical component pads, mounting holes, board edges defined as keep-outs, or explicit keep-out zones.

```typescript
export type Obstacle = {
  /** The shape of the obstacle. Currently, only "rect" is standard. Oval shapes might be included in future revisions. */
  type: "rect"; // NOTE: most datasets do not contain ovals

  /** An array of layer names (strings) on which this obstacle exists. An obstacle can span multiple layers (e.g., a plated through-hole pad). */
  layers: string[];

  /** The center coordinates of the obstacle. */
  center: { x: number; y: number };

  /** The width of the rectangular obstacle. */
  width: number;

  /** The height of the rectangular obstacle. */
  height: number;

  /** An array of connection names (strings) that this obstacle is part of. If this obstacle is a pad for a net (e.g., "GND", "VCC"), the net name(s) will be listed here. If the array is empty, the obstacle is typically a keep-out area or an unconnected feature. */
  connectedTo: string[];
};
```
*   **`type`**: Defines the geometry. Currently `"rect"` is the standard.
*   **`layers`**: Specifies which layer(s) the obstacle occupies. Important for multi-layer routing.
*   **`center`, `width`, `height`**: Define the geometry and position of the rectangle. Units must be consistent with `minTraceWidth` and `bounds`.
*   **`connectedTo`**: This critical field links obstacles (like pads) to the electrical nets defined in the `connections` array. If an obstacle represents a pin for the "VCC" net, `connectedTo` would contain `["VCC"]`.

### `connections`

*   **Type:** `Array<SimpleRouteConnection>`
*   **Description:** Defines the sets of points that need to be electrically connected. Each object in the array represents a single net (e.g., power, ground, signal).

```typescript
export interface SimpleRouteConnection {
  /** The unique name of the connection or net (e.g., "GND", "VCC", "DATA0"). This name is referenced by Obstacle.connectedTo. */
  name: string;

  /** An array of points that must be connected together to form this net. Each point typically corresponds to the center of an obstacle (pad) belonging to this net. */
  pointsToConnect: Array<{
    /** The x-coordinate of the connection point. */
    x: number;
    /** The y-coordinate of the connection point. */
    y: number;
    /** The layer name (string) on which this connection point resides. */
    layer: string;
  }>;
}
```
*   **`name`**: A unique string identifier for the net. This is used to link `Obstacle` objects (pads) to their respective nets.
*   **`pointsToConnect`**: An array listing the specific locations (`x`, `y`, `layer`) that the router must connect. These points usually align with the `center` coordinates and `layers` of the corresponding `Obstacle` objects linked via the `name`.

### `bounds`

*   **Type:** `object`
*   **Description:** Defines the rectangular boundary of the area where routing is permitted. Traces should generally not extend beyond these limits.
*   **Structure:**
    *   `minX`: The minimum x-coordinate of the routing area.
    *   `maxX`: The maximum x-coordinate of the routing area.
    *   `minY`: The minimum y-coordinate of the routing area.
    *   `maxY`: The maximum y-coordinate of the routing area.
*   **Units:** Must be consistent with other dimensional values in the file.

### `traces` (Optional)

*   **Type:** `Array<SimplifiedPcbTrace>`
*   **Description:** This array represents the output of an autorouter – the actual geometric paths (traces and vias) that implement the required connections. It is typically **not present** in the input SRJ file given to the router.
*   **Presence:** Included in the SRJ file *after* routing has been successfully completed.

```typescript
export type SimplifiedPcbTrace = {
  /** Identifier indicating the object type. Always "pcb_trace". */
  type: "pcb_trace";

  /** A unique identifier for this specific trace path. */
  pcb_trace_id: string;

  /** [Optional] The name of the connection/net this trace belongs to. Links the solved route back to the SimpleRouteConnection definition. */
  connection_name?: string;

  /** An array defining the geometry of the trace path, composed of wire segments and vias. */
  route: Array<
    | {
        /** Indicates a straight wire segment on a single layer. */
        route_type: "wire";
        /** The x-coordinate of the *end* point of the wire segment. */
        x: number;
        /** The y-coordinate of the *end* point of the wire segment. */
        y: number;
        /** The width of this wire segment. */
        width: number;
        /** The layer name (string) this wire segment is on. */
        layer: string;
      }
    | {
        /** Indicates a via connecting two layers. */
        route_type: "via";
        /** The x-coordinate of the via's center. */
        x: number;
        /** The y-coordinate of the via's center. */
        y: number;
        /** The layer name (string) the via transitions *to*. */
        to_layer: string;
        /** The layer name (string) the via transitions *from*. */
        from_layer: string;
      }
  >;
};
```
*   **`type`**: Always `"pcb_trace"`.
*   **`pcb_trace_id`**: Unique ID for the trace.
*   **`connection_name`**: Links trace to the net name from `connections`.
*   **`route`**: An ordered array describing the path:
    *   **`wire`**: Represents a straight segment of copper trace. The segment runs from the end point of the previous element in the `route` array (or an initial connection point) to the specified `(x, y)` coordinate on the given `layer` with the specified `width`.
    *   **`via`**: Represents a vertical connection between layers at `(x, y)`, transitioning from `from_layer` to `to_layer`. Note that physical via characteristics (drill size, annular ring) are not detailed in this simplified format.

## Example

```json
{
  "layerCount": 2,
  "minTraceWidth": 0.15,
  "obstacles": [
    {
      "type": "rect",
      "layers": ["top"],
      "center": { "x": 10, "y": 10 },
      "width": 1.2,
      "height": 1.2,
      "connectedTo": ["VCC"]
    },
    {
      "type": "rect",
      "layers": ["top"],
      "center": { "x": 30, "y": 10 },
      "width": 1.2,
      "height": 1.2,
      "connectedTo": ["VCC"]
    },
    {
      "type": "rect",
      "layers": ["bottom"],
      "center": { "x": 20, "y": 25 },
      "width": 1.2,
      "height": 1.2,
      "connectedTo": ["GND"]
    },
    {
      "type": "rect",
      "layers": ["bottom"],
      "center": { "x": 40, "y": 25 },
      "width": 1.2,
      "height": 1.2,
      "connectedTo": ["GND"]
    },
    {
      "type": "rect",
      "layers": ["top", "bottom"], // Keepout on both layers
      "center": { "x": 25, "y": 15 },
      "width": 5,
      "height": 3,
      "connectedTo": [] // Empty means it's a keepout
    }
  ],
  "connections": [
    {
      "name": "VCC",
      "pointsToConnect": [
        { "x": 10, "y": 10, "layer": "top" },
        { "x": 30, "y": 10, "layer": "top" }
      ]
    },
    {
      "name": "GND",
      "pointsToConnect": [
        { "x": 20, "y": 25, "layer": "bottom" },
        { "x": 40, "y": 25, "layer": "bottom" }
      ]
    }
  ],
  "bounds": {
    "minX": 0,
    "maxX": 50,
    "minY": 0,
    "maxY": 40
  },
  // --- TRACES SECTION (added by router) ---
  "traces": [
    {
      "type": "pcb_trace",
      "pcb_trace_id": "trace_vcc_1",
      "connection_name": "VCC",
      "route": [
        { "route_type": "wire", "x": 10, "y": 10, "width": 0.15, "layer": "top" }, // Start implicitly at first point
        { "route_type": "wire", "x": 20, "y": 5, "width": 0.15, "layer": "top" },
        { "route_type": "wire", "x": 30, "y": 10, "width": 0.15, "layer": "top" }  // End at second point
      ]
    },
    {
      "type": "pcb_trace",
      "pcb_trace_id": "trace_gnd_1",
      "connection_name": "GND",
      "route": [
        { "route_type": "wire", "x": 20, "y": 25, "width": 0.15, "layer": "bottom" }, // Start implicitly at first point
        // Example with a via
        { "route_type": "wire", "x": 30, "y": 25, "width": 0.15, "layer": "bottom" },
        { "route_type": "via", "x": 30, "y": 25, "from_layer": "bottom", "to_layer": "top" },
        { "route_type": "wire", "x": 30, "y": 20, "width": 0.15, "layer": "top" }, // Segment on top layer
        { "route_type": "via", "x": 30, "y": 20, "from_layer": "top", "to_layer": "bottom" },
        { "route_type": "wire", "x": 40, "y": 25, "width": 0.15, "layer": "bottom" }  // End at second point
      ]
    }
  ]
}
```

## Units and Coordinate System

The Simple Route JSON format does **not** enforce specific units (e.g., mm, mil, inches) or a coordinate system origin (e.g., top-left, bottom-left).

*   **Consistency is Key:** All dimensional values (`minTraceWidth`, obstacle `width`/`height`, `bounds`, all `x`/`y` coordinates in `obstacles`, `connections`, and `traces`) within a single SRJ file **must** use the same units.
*   **Common Practice:** Millimeters (mm) are frequently used.
*   **Origin:** The coordinate system origin is typically assumed to be top-left or bottom-left, with X increasing to the right and Y increasing downwards (top-left) or upwards (bottom-left). Consistency within the file and between the SRJ generator and consumer (the autorouter) is essential.

## Relationship to Other Formats

*   **Circuit JSON:** Simple Route JSON is a simplified derivative of Circuit JSON. Tools can convert Circuit JSON to SRJ by extracting layer stackup information, component pad locations and net assignments, board outlines, and any defined keep-out areas. Information not relevant to routing (e.g., schematic IDs, component values, 3D models) is omitted.
*   **Specctra DSN:** SRJ serves a similar purpose to DSN files – describing a routing problem. However, SRJ uses a modern JSON structure, which is often easier to parse and generate in web-based and JavaScript/TypeScript environments compared to the text-based, keyword-driven DSN format. The `dsn-converter` tool ([link](https://github.com/tscircuit/dsn-converter)) can facilitate conversion between DSN and SRJ or similar formats.

## Usage

The primary use case for Simple Route JSON is as the input and output format for `tscircuit` autorouting tools.

1.  **Input:** A PCB design tool or conversion script generates an SRJ file describing the board, obstacles, and connections. This file is fed into an autorouter.
2.  **Output:** The autorouter processes the input SRJ, computes the trace paths, and outputs a new SRJ file that includes the original data plus the `traces` array detailing the solution.
3.  **Post-processing:** The output SRJ (with traces) can then be converted back into a format compatible with PCB design software (like Circuit JSON, KiCad, Eagle, etc.) to integrate the routing solution into the full PCB design.
```
</file>

<file path="docs/advanced/units.md">
---
title: tscircuit Units
---

In tscircuit you can specify a unit explicitly with a string e.g. "0.1mm", but
you can also also specify numbers without units and the unit will be inferred
from [platform](../guides/platform-configuration.md), [board configuration](../elements/board.mdx), [subcircuit configuration](../elements/subcircuit.mdx)
or the defaults below

## Default Units

By default, tscircuit uses the following base units:

| Measurement Type | Base Unit | Description  |
| ---------------- | --------- | ------------ |
| Length           | mm        | Millimeters  |
| Time             | ms        | Milliseconds |
| Mass             | g         | Grams        |
| Angle            | deg       | Degrees      |
| Frequency        | Hz        | Hertz        |
| Volume           | ml        | Milliliters  |
| Voltage          | V         | Volts        |
| Current          | A         | Amperes      |
| Resistance       | Ω         | Ohms         |
| Capacitance      | F         | Farads       |
| Inductance       | H         | Henries      |

Base units are chosen based on the industry convention.
</file>

<file path="docs/building-electronics/designing-electronics-from-scratch.md">
---
title: Designing Electronics from Scratch
sidebar_position: 2
description: A comprehensive guide to electronics design workflow - from requirements analysis through system diagramming, schematic capture, PCB layout, to final manufacturing
---

## Overview

Typically electronics engineers go through the following steps when designing
a new electronic device.

1. Requirements Analysis
2. System Diagramming
3. Schematic Capture
4. PCB Layout
5. Ordering

## Requirements Analysis

This stage is all about making sure you have a clear idea of what the device
should do. Your development and cost preferences are a huge factor here.

1. What should the device do?
2. How much power is needed?
3. How much processing power do I need?
4. Do I want to run linux, MicroPython, or low-level C code? Do I even need
   to run code?
5. How much does cost matter?
6. Should I use only parts available from turn-key manufacturers like JLCPCB?

## System Diagramming

In this phase we create a diagram overview of the system and how things connect
together abstractly

1. What components should I use?
2. How do things connect together at a high level?

The system diagram can instantly communicate how your design works to others.

### System Diagram Example 1: Bluetooth Humidity and CO2 Sensor

Here's an example of a system diagram for a simple IoT device that takes
humidity and CO2 measurements and can communicate them via bluetooth.

<figure>
<img src="/img/system-diagram-1.png" alt="System Diagram Example 1" />
<figcaption>System Diagram Example 1</figcaption>
</figure>

## Schematic Capture

In this phase we create a schematic diagram of the system and how things connect
together.

1. Using reference designs, datasheets or pre-made modules, create all the
   elements of the circuit in tscircuit
2. Run design checks to make sure the circuit is hooked up correctly

In this phase you should create chip modules or [import third party chips](../guides/importing-modules-and-chips/importing-from-jlcpcb.mdx)
as you build up your circuit. You shouldn't be configuring chips in
the same file that connects all your chips together- give each chip it's own
module.

After the schematics look good, you can export to a readable netlist and upload
the netlist to AI tools like OpenAI O1 to get a review and make sure everything
is connected properly! This is also a good stage to get your schematic reviewed
by your team members.

## PCB Layout

In this phase we create a layout of the circuit on a PCB.

tscircuit automatically autoroutes the circuit for you, but you may still need
to "drag'n'drop" components in the PCB viewer to the locations you want them to
be in. Use [manual editing](../guides/manual-edits.mdx) to drag'n'drop
components on the PCB.

## Ordering

In this phase we order the PCB from a manufacturer. Typically this is done
by downloading [Fabrication Files](../guides/understanding-fabrication-files.md)
and "dragging and dropping" them into a manufacturer's website.

Sometimes you'll want to assemble the PCB yourself (or sometimes just a single
component that your manufacturer doesn't have!). In this case, you'll need a
lab setup to facilitate soldering.

Check out our guide on [Ordering Prototypes](./ordering-prototypes.mdx) to learn more.
</file>

<file path="docs/building-electronics/ordering-prototypes.mdx">
---
title: Ordering Prototypes
sidebar_position: 4
description: After you've designed your device, you can use fabrication files to get your device fully assembled. The two most popular services for ordering prototypes are JLCPCB and PCBWay.
---

## Overview

After [you've designed your device](./designing-electronics-from-scratch.md),
you can use [fabrication files](../guides/understanding-fabrication-files.md)
to get your device fully assembled.

The two most popular services for
ordering prototypes are [JLCPCB](https://jlcpcb.com) and [PCBWay](https://pcbway.com).

## Ordering Through tscircuit Platform

The easiest way to order your prototypes is through the tscircuit platform, which handles the entire ordering process for you. Before placing your order, there are two important component properties that affect the ordering process:

### Using `doNotPlace` Prop

Components with the `doNotPlace` prop set to `true` will not be included in the parts selection for ordering. This is useful for components that you plan to solder manually or that are not available through the supplier.

```tsx
<resistor resistance="10k" name="R1" footprint="0402" doNotPlace />
```

### Using `supplierPartNumbers` Prop

The `supplierPartNumbers` prop allows you to specify exact part numbers from suppliers, helping to ensure the correct components are selected during ordering. This is particularly useful for specific or critical components.

```tsx
<capacitor 
  capacitance="100nF" 
  supplierPartNumbers={{
    jlcpcb: "C14663"
  }}
  name="C1"
  footprint="0402"
/>
```

### Ordering Steps

Here's how the ordering process works:

### 1. Get Order Quotes

Navigate to the view packages page where you'll find the order button for your circuit.

<figure>
<img src="/img/ordering-button.png" />
<figcaption>The order button is present on your project's view packages page</figcaption>
</figure>

### 2. Select Your Vendor and Quote

When you click the order button, a dialog will appear showing quotes from different vendors. Currently, JLCPCB is the only available vendor, with more vendors coming soon. Compare the prices, lead times, and shipping options, then select your preferred vendor and click continue.

<figure>
<img src="/img/order-quote-dialog.png" />
<figcaption>Compare quotes from multiple vendors and select the best option for your needs</figcaption>
</figure>

### 3. Complete Your Order

Finally, you'll be redirected to a secure Stripe checkout page where you can enter your payment details and shipping address. Your PCB will be delivered directly to your specified address.

<figure>
<img src="/img/stripe-checkout.png" />
<figcaption>Secure checkout with Stripe handles payment and shipping details</figcaption>
</figure>

## Uploading [Fabrication Files](../guides/understanding-fabrication-files.md)

Most fabrication or turn-key assembly services allow you to directly upload 3 types of files:

- Gerbers
- Bill of Materials (BOM CSV)
- Pick'n'Place File (CSV)

These files are all available inside your [Fabrication Files zip file](../guides/understanding-fabrication-files.md) when
you export from tscircuit.

<figure>
<img src="/img/jlcpcb-upload.png" />
<figcaption>Many fabricators allow you to directly drop fabrication files on their website!</figcaption>
</figure>

## Assembling your own boards

It can sometimes be easier to assemble your own boards, this gives you more
control over your inventory and can lower the cost of your prototypes since
assembly services often have a minimum order quantity.

Even if you're assembling your own board, you should still order your PCB
from a fabrication service. PCBs require a chemical etching process to do
at home and it's rarely worth the hassle to do it yourself.

When you're assembling your own board, you can create a printout of your
Assembly View to make it easier to place components. In an assembly view,
the "pin1" location is marked with a cut corner. This can help you verify
the orientation of each component as you place it.

<figure>
<img src="/img/assembly-view-in-editor.png" />
</figure>
</file>

<file path="docs/building-electronics/what-are-electronics-made-of.mdx">
---
title: What are electronics made of?
sidebar_position: 1
description: >-
  In this tutorial, we're going to be talking about the different elements that
  make up a Printed Circuit Board (PCB). For each element, we'll show different
  ways that the element can be represented in tscircuit.
---


## Overview

In this tutorial, we're going to be talking about the different elements that
make up a Printed Circuit Board (PCB). For each element, we'll show different
ways that the element can be represented in tscircuit.

## What is copper? Why are PCBs green?

Copper is a conductive material that's used on a PCB to make an electrical
connection between chips. A PCB is mostly made up of fiberglass with a small
layer of precisely etched copper. The fiberglass is non-conductive and often
coated with non-conductive green "soldermask" to cover parts of the copper that
aren't meant to be connected to chips.

<figure style={{ textAlign: "center" }}>
<img style={{ width: 400, height: 240, objectFit: "cover" }} src="/img/ai-pcb-1.webp" alt="AI Generated PCB Image" />
<figcaption>An AI-generated PCB image. All the yellow parts represent copper, while the green parts represent fiberglass with a green soldermask</figcaption>
</figure>

A PCB can be thought of as a bunch of "printed" copper separated by fiberglass
sections that "insulate" or don't conduct electricity. We "glue" (solder) chips
to the copper "pads" to add them to the circuit.

## What are PCB layers?

When you print on a piece of paper, you can print "single-sided" or "double-sided",
PCBs can also be printed singled-sided or double-sided! The "front" of the PCB
is called the "top" layer, and the "back" of the PCB is called the "bottom" layer.

We can "print" copper to each of these layers to draw lots of wires and connect
lots of chips. Sometimes a wire needs to "go over"/"go under" another wire
because the wires aren't allowed to cross. When this happens, we can use the
"back" or "bottom layer" of the PCB to draw the wire so that the wires don't
accidentally touch.

## Vias

Vias are holes that connect different layers of PCB. Let's say you have a chip
on the top layer of a PCB and the back layer of a PCB. How can you connect them?
The copper on the top needs some way to "pass through" to the bottom layer.

This is where vias come in. A via is a hole that is "filled with copper" so that
the top layer can pass to the bottom.

<figure>
<img src="/img/via.png" alt="Vias" /> 
<figcaption>Vias connect different layers of a PCB</figcaption> 
</figure>

<CircuitPreview defaultView="pcb" code={`


export default () => (
  <footprint>
    <via
      toLayer="bottom"
      fromLayer="top"
      holeDiameter="0.25mm"
      outerDiameter="0.6mm"
    />
  </footprint>
)

`} />


## Plated Holes

A plated hole is similar to a via but it's hollow so that you can push metal pins
through it. This is important for chips that have big pins that need to fit into
holes. Chips with big pins that must go through holes are called "through-hole"
chips, and chips with small
pins are called "surface-mount" chips.

<CircuitPreview defaultView="pcb" code={`

export default () => (
  <footprint>
    <platedhole
      shape="circle"
      x="5mm"
      y="2.4mm"
      holeDiameter="0.25mm"
      outerDiameter="0.35mm"
    />
  </footprint>
)

`} />

## Unplated Holes "Regular Holes"

Unplated holes or "regular holes" are just holes in the printed circuit board
without any copper around them. They don't electrically connect anything, but
can be very helpful for mounting the printed circuit board.

<CircuitPreview defaultView="pcb" code={`

export default () => (
  <footprint>
    <hole diameter="1mm" />
  </footprint>
)

`} />

## Traces

Traces are the wires that connect the components on a PCB. They are made of
copper and mostly covered by green soldermask so that they don't accidentally
conduct to each other if something conductive like a wire or piece of metal falls
across them.

We represent traces in PCB viewers with different colors depending on what
layer they fall on. In tscircuit, traces are always autorouted, so you don't
need to tell it which path to take- it'll automatically find one that makes sure
it doesn't cross any other traces.

Traces allow chips to "talk" to each other and for power to be shared across all
chips.

<CircuitPreview defaultView="pcb" code={`

export default () => (
  <board width="10mm" height="10mm">
    <resistor
      resistance="1k"
      footprint="0402"
      name="R1"
      schX={3}
      pcbX={3}
    />
    <capacitor
      capacitance="1000pF"
      footprint="0402"
      name="C1"
      schX={-3}
      pcbX={-3}
    />
    <trace from=".R1 > .pin1" to=".C1 > .pin1" />
  </board>
)

`} />

## What are inner layers?

Inner layers are layers of PCB that aren't visible, they're sandwiched on the
inside. Sometimes this is useful when you have a lot of wires to connect and
it's almost impossible to stop them from crossing each other.

<figure>
<img src="/img/pcb-layers.png" alt="Inner layers" /> 
<figcaption>Inner layers are layers of PCB that aren't visible, they're sandwiched on the inside. Excellent image from <a href="https://www.pcbway.com/blog/Engineering_Technical/3_STEPS_How_to_determine_calculate_number_of_PCB_layers.html">pcbway</a></figcaption> 
</figure>
</file>

<file path="docs/command-line/tsci-add.mdx">
---
title: tsci add
---

`tsci add` is the same as `npm add` or `bun add`, but defaults to the tscircuit
registry. If your project has the [tsci `.npmrc`](../web-apis/the-registry-api.md#using-the-tscircuit-npm-registry), you can just do `bun add @tsci/<author>.<package>`
and it has the same effect.

```
> tsci add seveibar/PICO_W
# Added @tsci/seveibar.PICO_W@0.0.1
```

You can then import the module and use it for your board!


<CircuitPreview
  defaultView="pcb"
  code={`


import { PICO_W } from "@tsci/seveibar.PICO_W"

export default () => (
    <PICO_W name="U1" />
)

`}
/>
</file>

<file path="docs/command-line/tsci-auth-print-token.md">
---
title: tsci auth print-token
---

`tsci auth print-token` prints your current tscircuit API token. This token can be used with the advanced web APIs such as the [Datasheet API](../web-apis/datasheet-api.md).

## Usage

```bash
tsci auth print-token
```

Make sure you have previously logged in with [`tsci login`](./tsci-login.md). The command will output a token string that you can pass in the `Authorization: Bearer <token>` header of API requests.
</file>

<file path="docs/command-line/tsci-build.md">
---
title: tsci build
description: Generate circuit JSON from your source files
---

`tsci build` runs the TSCircuit evaluator and writes `circuit.json` files.

## Usage

```bash
tsci build [file] [--ignore-errors] [--ignore-warnings]
```

### Arguments
- `file` *(optional)* – path to a `.tsx` file to build. If omitted, the command searches for a project entrypoint such as `index.tsx` or the `mainEntrypoint` defined in `tscircuit.config.json`. In addition, all files matching the `*.circuit.tsx` pattern are built automatically.

### Output
Output files are placed in a `dist/` directory relative to your project. The main entrypoint produces `dist/circuit.json`. Each `*.circuit.tsx` file generates its own subdirectory. For example, `src/blink.circuit.tsx` becomes `dist/src/blink/circuit.json`.

### Options
- `--ignore-errors` – do not exit with code `1` on evaluation errors.
- `--ignore-warnings` – suppress warning messages.

Use this command before publishing or in CI to ensure your circuits evaluate correctly.
</file>

<file path="docs/command-line/tsci-dev.md">
---
title: tsci dev
sidebar_position: 2
---

`tsci dev` runs a web server that lets you see a preview of your electronics
in your web browser.

After you run `tsci dev` you should see a preview of your entrypoint file in
your web browser on https://localhost:3020

![tsci dev result](../../static/img/tsci-dev.png)

![browser](../../static/img/pcb-runframe.png)
</file>

<file path="docs/command-line/tsci-export.md">
---
title: tsci export
---

import ImageWithCaption from "../../src/components/ImageWithCaption"

## Overview

`tsci export` can be used to convert a `tsx` file or `circuit.json` file into
various output formats including schematics, PCB layouts, fabrication files, and more.

<ImageWithCaption
  src="/img/tsci-dev-export.png"
  alt="Export options in the web interface"
  caption="Export options available in the web interface after running tsci dev"
/>

## Usage

```bash
tsci export <file> [options]
```

### Arguments
- `<file>`: Path to the source file (`.tsx` or `.circuit.json`)

### Options
- `-f, --format <format>`: Output format (defaults to "json")
- `-o, --output <path>`: Custom output file path

## Supported Formats

The following export formats are supported:

| Format | Description |
|--------|-------------|
| `circuit-json`| Circuit JSON format |
| `schematic-svg` | Schematic view as SVG |
| `pcb-svg` | PCB layout as SVG |
| `readable-netlist` | Human-readable netlist |
| `specctra-dsn` | Specctra DSN format for autorouting |

## Examples

Export to circuit JSON:
```bash
tsci export circuit.tsx
```

Export as schematic SVG:
```bash
tsci export circuit.tsx -f schematic-svg
```

Export PCB layout with custom output path:
```bash
tsci export circuit.tsx -f pcb-svg -o my-pcb-layout.svg
```

Export to Specctra DSN format:
```bash
tsci export circuit.tsx -f specctra-dsn
```

## Output Files

By default, the exported file will be saved in the same directory as the input file, with a filename based on the input filename and the chosen format. For example:

- Input: `my-circuit.tsx`
- Format: `pcb-svg`
- Default output: `my-circuit-pcb.svg`

You can override the output location using the `-o` or `--output` option.
</file>

<file path="docs/command-line/tsci-login.md">
---
title: tsci login
sidebar_position: 1
---

`tsci login` allows you to login to the tscircuit registry. You don't need to
login to tscircuit to use any tools, but logging in does enable the following
great features:

- Cloud Autorouting (`autorouter="auto-cloud"`)
- Package Management (publishing and automatic bundling)

:::info
You don't need a tscircuit account to download and use other people's packages
:::

`tsci login` will take you to a login page where you'll sign in with Github.
After the login flow you'll have have token on your machine that authenticates
you to publish packages or use the cloud autorouter.

## Logout

To logout again, just run `tsci logout`

## Other Auth Functions

Run `tsci auth --help` to see other auth functions, such as printing your token
for use with the [Registry API](../web-apis/the-registry-api.md)
</file>

<file path="docs/command-line/tsci-push.md">
---
title: tsci push
sidebar_position: 2
description: |
  tsci push uploads your package to the tscircuit registry for module re-use
---

tscircuit code, like React code, is distributed as a "package". `tsci push` uploads your package to the [tscircuit registry](https://tscircuit.com/trending) to enable sharing with your team.

After publishing, you can use the [tsci add](https://docs.tscircuit.com/command-line/tsci-add) command to install your package as part of a larger circuit.

After running `tsci push` you can see your package on your tscircuit registry page. Packages default to private visibility, but you can change this from your registry page to enable sharing your package with the broader ecosystem.

import tsciPushImage from "../../static/img/tsci-push.png"
import registrySnippetImage from "../../static/img/registry-snippet.png"
import ImageWithCaption from "../../src/components/ImageWithCaption";

<ImageWithCaption
  src={tsciPushImage}
  alt="tsci push command result"
  caption="Result of running tsci push command"
/>

<ImageWithCaption
  src={registrySnippetImage}
  alt="snippet in registry"
  caption="Browser view of the package in the tscircuit Registry"
/>
</file>

<file path="docs/command-line/tsci-snapshot.md">
---
title: tsci snapshot
description: Generate schematic and PCB snapshots for regression tests
---

`tsci snapshot` renders your boards to SVG images and compares them with saved snapshots.

## Usage

```bash
tsci snapshot [options]
```

### Options
- `-u, --update` – write new snapshots to disk.
- `--3d` – also generate 3D preview snapshots.

### Which files are snapped?
The command searches the current project for:
- the detected entrypoint (using the same logic as `tsci build`)
- any files matching `*.board.tsx` or `*.circuit.tsx`

This pattern allows standalone board files (ending in `.circuit.tsx`) to be tested alongside your main project.

### Snapshot location
Snapshots are stored next to each source file in a `__snapshots__` directory. For a file `test.board.tsx` you will see:

```
__snapshots__/test.board-pcb.snap.svg
__snapshots__/test.board-schematic.snap.svg
```

If `--3d` is specified, a `-3d.snap.svg` is also produced.

Running without `--update` verifies that the generated output matches the existing snapshots. Differences cause a non-zero exit code.
</file>

<file path="docs/contributing/bounties-and-sponsorship.md">
---
title: Bounties and Sponsorship
---

tscircuit has thousands dollars (USD) of bounties opened every month in over
50 new weekly issues. We also automatically sponsor regular contributors
hundreds of dollars each based on their contributions, which we track with Github's API
in our weekly [contribution-tracker](https://github.com/tscircuit/contribution-tracker)
(resets every Wednesday)

Many people follow the [bounties channel on discord](https://discord.com/channels/1233487248129921135/1301957862762872832) or our [bounty board](https://console.algora.io/org/tscircuit/bounties?status=open)
to find issues to contribute to, but **this is actually the hardest way to get bounties!**

:::tip

You can quickly find issues (with or without bounties) by [spinning the wheel of issues](https://issues.tscircuit.com/)

:::

**The easiest way to get bounties and sponsorship is to _actually use tscircuit and try to build a circuit_.** When you
find something confusing or buggy, create an issue. When you create an issue that
gets bountied, you get extra points on the contribution tracker and you become
the best person to fix the issue because you understand it so well! If you
continually do this, you'll find that their are infinite issues to be done!

To be eligible for Github Sponsorship, you must be in a supported country and
have Github Sponsors enabled on your Github profile.
</file>

<file path="docs/contributing/getting-started-as-a-contributor.md">
---
title: Getting Started as a Contributor
sidebar_position: 1
---

tscircuit is a great project to contribute to if you're familiar with Typescript
and React.

:::tip

Make sure you've [joined the discord server](https://tscircuit.com/join) so we
can help you get started and reviewed quickly!

:::

tscircuit is composed of over 200 repositories, but every project uses [bun](https://bun.sh),
so make sure to install bun before you start contributing.

To contribute to tscircuit, you need to make [Pull Requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) from a fork of a repository.

:::tip

You can quickly find issues (with or without bounties) by [spinning the wheel of issues](https://issues.tscircuit.com/)

:::

## Before You Start

1. Make sure bun is installed on your system
2. Make sure you've signed up at [tscircuit.com](https://tscircuit.com) and have followed a tutorial in the docs to create a circuit board

## Recommended Contribution Order

We recommend the following order for contributing to tscircuit. Contributing to repositories in this order will make sure you have a good understanding of the tscircuit ecosystem.

If you're not able to find an issue in the repo, ask on discord! Maintainers often forget to create issues even though there are many problems they need solved!

## 1. [tscircuit/schematic-symbols](https://github.com/tscircuit/schematic-symbols)

Difficulty: ⭐ (easy) · [Issues](https://github.com/tscircuit/schematic-symbols/issues) · [Repo](https://github.com/tscircuit/schematic-symbols)

[![GitHub issues](https://img.shields.io/github/issues/tscircuit/schematic-symbols)](https://github.com/tscircuit/schematic-symbols/issues)

This is a large repository of schematic symbols, you can view the [symbols here](https://symbols.tscircuit.com)

![Schematic Symbols Project](../../static/img/symbols.png)

We also have a [video tutorial](https://blog.tscircuit.com/i/149495167/help-us-build-the-largest-library-of-schematic-symbols) for contributing to this project!

## 2. [tscircuit/footprinter](https://github.com/tscircuit/footprinter)

Difficulty: ⭐⭐ (medium) · [Issues](https://github.com/tscircuit/footprinter/issues) · [Repo](https://github.com/tscircuit/footprinter)

[![GitHub issues](https://img.shields.io/github/issues/tscircuit/footprinter)](https://github.com/tscircuit/footprinter/issues)

This is a project that generates the "footprint" where a chip is placed on a circuit board from a string.

For example, you might turn the string "quad24" into the image below:

![Footprinter Project](../../static/img/footprinter.webp)

Here's the [video tutorial for contributing to footprinter](https://blog.tscircuit.com/p/learn-how-to-contribute-to-tscircuits)

## 3. [tscircuit/cli](https://github.com/tscircuit/cli)

Difficulty: ⭐⭐ (medium) · [Issues](https://github.com/tscircuit/cli/issues) · [Repo](https://github.com/tscircuit/cli)

[![GitHub issues](https://img.shields.io/github/issues/tscircuit/cli)](https://github.com/tscircuit/cli/issues)

This is the main development tool for tscircuit. It provides a local development server and package management. The CLI is what you use when you run `tsci dev` or `tsci init`.

## 4. [tscircuit.com](https://github.com/tscircuit/tscircuit.com)

Difficulty: ⭐⭐ (medium) · [Issues](https://github.com/tscircuit/tscircuit.com/issues) · [Repo](https://github.com/tscircuit/tscircuit.com)

[![GitHub issues](https://img.shields.io/github/issues/tscircuit/tscircuit.com)](https://github.com/tscircuit/tscircuit.com/issues)

This is the main website for tscircuit, it features an editor for circuit boards! You should try it at [tscircuit.com](https://tscircuit.com)!

There are a lot of issues in this repo,

## 5. [circuit-to-svg](https://github.com/tscircuit/circuit-to-svg)

Difficulty: ⭐⭐ (medium) · [Issues](https://github.com/tscircuit/circuit-to-svg/issues) · [Repo](https://github.com/tscircuit/circuit-to-svg)

[![GitHub issues](https://img.shields.io/github/issues/tscircuit/circuit-to-svg)](https://github.com/tscircuit/circuit-to-svg/issues)

This is a library that converts [Circuit JSON](https://github.com/tscircuit/circuit-json) into SVG files. We use
this all over the place, including in almost all of our
tests!

## 6. [tscircuit/core](https://github.com/tscircuit/core)

Difficulty: ⭐⭐⭐ (hard) · [Issues](https://github.com/tscircuit/core/issues) · [Repo](https://github.com/tscircuit/core)

[![GitHub issues](https://img.shields.io/github/issues/tscircuit/core)](https://github.com/tscircuit/core/issues)

This is the core library that powers tscircuit. It contains all the logic for converting React components into circuit boards, schematics and PCBs.

The core library is written in Typescript and uses React. It's a great project to contribute to if you want to learn about how tscircuit works under the hood.

Here's a [video tutorial for contributing to core](https://blog.tscircuit.com/p/learn-how-to-contribute-to-tscircuits-core).
</file>

<file path="docs/contributing/overview-of-projects.md">
---
title: Overview of Projects
sidebar_position: 2
---

| Repo                                                                          | Description                                                                                    | Open Issues                                                                                                                                 |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [tscircuit/core](https://github.com/tscircuit/core)                           | Core library that powers tscircuit, handles conversion of React components into circuit boards | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/core)](https://github.com/tscircuit/core/issues)                           |
| [tscircuit/schematic-symbols](https://github.com/tscircuit/schematic-symbols) | Library of schematic symbols used across tscircuit                                             | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/schematic-symbols)](https://github.com/tscircuit/schematic-symbols/issues) |
| [tscircuit/footprinter](https://github.com/tscircuit/footprinter)             | Generates PCB footprints from string descriptions                                              | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/footprinter)](https://github.com/tscircuit/footprinter/issues)             |
| [tscircuit/circuit-to-svg](https://github.com/tscircuit/circuit-to-svg)       | Converts Circuit JSON into SVG files                                                           | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/circuit-to-svg)](https://github.com/tscircuit/circuit-to-svg/issues)       |
| [tscircuit/tscircuit.com](https://github.com/tscircuit/tscircuit.com)         | Main website and circuit board editor                                                          | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/tscircuit.com)](https://github.com/tscircuit/tscircuit.com/issues)         |
| [tscircuit/cli](https://github.com/tscircuit/cli)                             | Main development tool for tscircuit, provides local development server and package management  | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/cli)](https://github.com/tscircuit/cli/issues)                             |
| [tscircuit/runframe](https://github.com/tscircuit/runframe)                   | React component to preview and run tscircuit circuits                                          | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/runframe)](https://github.com/tscircuit/runframe/issues)                   |
| [tscircuit/pcb-viewer](https://github.com/tscircuit/pcb-viewer)               | React component for viewing PCBs                                                               | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/pcb-viewer)](https://github.com/tscircuit/pcb-viewer/issues)               |
| [tscircuit/3d-viewer](https://github.com/tscircuit/3d-viewer)                 | React component for viewing 3D previews                                                        | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/3d-viewer)](https://github.com/tscircuit/3d-viewer/issues)                 |
| [tscircuit/easyeda-converter](https://github.com/tscircuit/easyeda-converter) | Command line utility for converting JLCPCB footprints to tscircuit                             | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/easyeda-converter)](https://github.com/tscircuit/easyeda-converter/issues) |
</file>

<file path="docs/contributing/report-autorouter-bugs.md">
---
title: Report an Autorouter Bug
description: Learn how to report an autorouter bug so that the tscircuit team can fix it.
---

import YouTubeEmbed from '../../src/components/YouTubeEmbed';

## Overview

You can report autorouter bugs by going to `Errors -> Open Autorouter Log -> Report Bug` inside the tscircuit interface.

When you report a bug, your autorouting data is sent to the tscircuit API so that the autorouting developers can debug the issue.

<YouTubeEmbed youtubeId="lXedg8mlP1s" />

## Simulating your bug with the Autorouting Debugger

After you've created a bug report, you can take things a step further by
downloading your reproduction to the codebase. To do this, you should do
the following:

1. Clone the [tscircuit-autorouter](https://github.com/tscircuit/tscircuit-autorouter) repository.
2. Run `bun i` to install the dependencies.
3. Run `bun run bug-report <url-to-your-bug-report>` to download the reproduction. This will output the name of your bug report directory
4. Run `bun run start` and search for your bug report directory, it will
   appear inside the autorouting debugger.


## Helping Contributors solve your autorouting bug

- [Create a high density solving fixture for your problem](https://youtu.be/cANWCNp_ggg)
</file>

<file path="docs/contributing/the-contributor-handbook.md">
---
title: The Contributor Handbook
---

We have some important patterns that make contributing to
tscircuit more consistent, we document these in [our handbook repo](https://github.com/tscircuit/handbook).

Here are a couple of really important ones:

1. [Use Yalc](https://github.com/tscircuit/handbook/blob/main/guides/using-yalc.md) - tscircuit uses many repositories so it can be hard to test different repositories interacting.
2. [Code Styles](https://github.com/tscircuit/handbook/blob/main/guides/code.md) - tscircuit has some consistent code patterns we use in every project. This makes the code more universally understood. Definitely note the banned words section!

Read the [full handbook here](https://github.com/tscircuit/handbook).
</file>

<file path="docs/elements/board.mdx">
---
title: <board />
sidebar_position: 1
---

The `<board />` element is a root element that contains all the chips and traces
to create a PCB.

You can think of a `<board />` like a `<body />` element in HTML. Everything
goes in a board!



<CircuitPreview defaultView="pcb" code={`

  export default () => (
    <board width="10mm" height="10mm">
      <resistor resistance="1k" footprint="0402" name="R1" />
    </board>
  )

`} />


## Board Properties

### Customizing the Size of the Board

Generally you'll use the `width` and `height` properties to define the size of
the board.

### Setting the `autorouter`

Boards or [subcircuits](./subcircuit.mdx) can specify what autorouter should be
used to route any traces within them.

Usually you'll want to use an autorouter preset:

- `autorouter="auto"` - Uses the [platform configuration](../guides/platform-configuration.md). For tscircuit.com this defaults to `sequential-trace`.
- `autorouter="sequential-trace"` - Iterate over each trace and use tscircuit's fast built-in autorouter. This method is fast and deterministic but often fails with over 50 traces.
- `autorouter="auto-local"` - Use the platform configuration, but only route locally (do not make API calls)
- `autorouter="auto-cloud"` - Use the platform configuration for 

For complex boards with over 50 traces, you should use `autorouter="auto-cloud"`
to take advantage of tscircuit's cloud autorouters, which internally use the popular
[freerouting](https://github.com/freerouting/freerouting) library.

You can also specify a custom autorouter object to use your own autorouter.

<CircuitPreview defaultView="pcb" code={`
  export default () => (
    <board
      width="20mm"
      height="20mm"
      autorouter={{
        serverUrl: "https://registry-api.tscircuit.com",
        serverMode: "job",
        inputFormat: "simplified",
      }}
    >
      <chip name="U1" footprint="soic8" pcbX={5} pcbY={0} />
      <resistor
        name="R1"
        pcbX={-5}
        pcbY={0}
        resistance={100}
        footprint="0402"
      />
      <trace from=".U1 > .pin1" to=".R1 > .pin1" />
    </board>
  )
`} />

Learn more about [the Autorouting API here](../web-apis/autorouting-api.mdx)


### Custom Board Outlines

You can specify a custom outline for your board by passing an `outline` prop.
The PCB you get will have this outline cut out, this is great when you want a
board that's not a rectangle!

<CircuitPreview defaultView="pcb" code={`

export default () => (
  <board
    outline={[
      { x: -22.5, y: 24.5 },
      { x: 22.5, y: 24.5 },
      { x: 22.5, y: 16.5 },
      { x: 20.5, y: 16.5 },
      { x: 20.5, y: 12.5 },
      { x: 22.5, y: 12.5 },
      { x: 22.5, y: 2.5 },
      { x: 18, y: -1.5 },
      { x: 18, y: -18 },
      { x: -18, y: -18 },
      { x: -18, y: -1.5 },
      { x: -22.5, y: 2.5 },
      { x: -22.5, y: 12.5 },
      { x: -20.5, y: 12.5 },
      { x: -20.5, y: 16.5 },
      { x: -22.5, y: 16.5 },
      { x: -22.5, y: 24.5 },
    ]}

    // These are currently required due to this issue:
    // https://github.com/tscircuit/core/issues/564
    width="50mm"
    height="50mm"
  />
)

`} />

## Flexible PCBs

:::info
Interested in flexible PCBs? Upvote [this issue on Github](https://github.com/tscircuit/tscircuit/issues/510)!
:::
</file>

<file path="docs/elements/breakout.mdx">
---
title: <breakout />
description: >-
  A breakout is a container that lets you route nets out of a group at explicit points.
---

## Overview

A `<breakout />` is similar to a [`<group />`](./group.mdx) but is meant for situations where you
want to guide the autorouter on exactly where connections should exit the group.
Inside a breakout you can place [`<breakoutpoint />`](./breakoutpoint.mdx) elements
to define those exit locations.


<CircuitPreview defaultView="pcb" code={`
export default () => (
  <board width="20mm" height="20mm">
    <breakout autorouter="auto">
      <resistor
        name="R1"
        resistance="1k"
        footprint="0402"
        pcbX={0}
        pcbY={0}
      />
      <capacitor
        name="C1"
        capacitance="1uF"
        footprint="0402"
        pcbX={2}
        pcbY={0}
      />
      <trace from="R1.2" to="C1.1" />
      <breakoutpoint connection="R1.1" pcbX={5} pcbY={5} />
    </breakout>
  </board>
)
`} />

## Properties

`<breakout />` accepts all the layout properties of `<group />` plus a few extras:

| Property | Description |
|----------|-------------|
| `padding` | Uniform padding around the breakout region. |
| `paddingLeft` / `paddingRight` / `paddingTop` / `paddingBottom` | Control padding for each side individually. |
| `autorouter` | Autorouter configuration inherited by children. |
</file>

<file path="docs/elements/breakoutpoint.mdx">
---
title: <breakoutpoint />
description: >-
  Specifies a PCB location where a connection inside a breakout should exit.
---

## Overview

A `<breakoutpoint />` marks the XY coordinate that the autorouter should use when
connecting a net or pin inside a [`<breakout />`](./breakout.mdx) to the rest of
the board. Breakout points only exist on the PCB and do not have a schematic
representation.


<CircuitPreview defaultView="pcb" code={`
export default () => (
  <board width="20mm" height="20mm">
    <breakout autorouter="auto">
      <resistor name="R1" resistance="1k" footprint="0402" pcbX={0} pcbY={0} />
      <breakoutpoint connection="R1.1" pcbX={5} pcbY={5} />
    </breakout>
  </board>
)
`} />

## Properties

| Property | Description |
|----------|-------------|
| `connection` | Port or net selector inside the breakout that should connect here. |
| `pcbX` / `pcbY` | Board coordinates of the breakout point. |
</file>

<file path="docs/elements/chip.mdx">
---
title: <chip />
sidebar_position: 1
---


The `<chip />` is the most common and most powerful built-in tscircuit element.
You can represent virtually any "single-part" electronic component with `<chip />`,
it is extremely flexible.

## Simple Chips

Here's an example of typical `<chip />` usage. We specify a footprint string and
the pin labels that should be used for the schematic representation.

<CircuitPreview alwaysShowCode defaultView="schematic" code={`
import type { CommonLayoutProps } from "tscircuit"

interface Props extends CommonLayoutProps {
  name: string
}

export const A555Timer = (props: Props) => {
  return (
    <chip
      footprint="soic8"
      pinLabels={{
        pin1: "VCC",
        pin2: "DISCH",
        pin3: "THRES",
        pin4: "CTRL",
        pin5: "GND",
        pin6: "TRIG",
        pin7: "OUT",
        pin8: "RESET"
      }}
      {...props}
    />
  )
}
`} />

## Customizing the Schematic Representation

You can alter how a chip appears on the schematic by using the `schPinArrangement`
, `schPinStyles` and `schWidth` properties.

### `schPinArrangement`

`schPinArrangement` controls the arrangement of the pins on the schematic box
representing the chip. You can use this to group similar pins together e.g. to
group GPIO pins together.

:::note
`schPortArrangement` was renamed to `schPinArrangement` in 2025.
:::

<CircuitPreview splitView defaultView="schematic" code={`

export default () => (
  <board width="10mm" height="10mm">
    <chip
      name="U1"
      footprint="soic8"
      schPortArrangement={{
        leftSide: {
          direction: "top-to-bottom",
          pins: ["VCC", "DISCH", "THRES", "CTRL"],
        },
        rightSide: {
          direction: "bottom-to-top",
          pins: ["GND", "TRIG", "OUT", "RESET"],
        },
      }}
      pinLabels={{
        pin1: "VCC",
        pin2: "DISCH",
        pin3: "THRES",
        pin4: "CTRL",
        pin5: "GND",
        pin6: "TRIG",
        pin7: "OUT",
        pin8: "RESET"
      }}
    />
  </board>
)
`}
/>

You can also place pins on the top or bottom of the schematic box.

<CircuitPreview splitView defaultView="schematic" code={`

export default () => (
  <board width="10mm" height="10mm">
    <chip
      name="U1"
      footprint="soic8"
      schPortArrangement={{
        topSide: {
          direction: "left-to-right",
          pins: ["VCC"],
        },
        bottomSide: {
          direction: "left-to-right",
          pins: ["GND"],
        },
        leftSide: {
          direction: "top-to-bottom",
          pins: ["DISCH", "THRES", "CTRL"],
        },
        rightSide: {
          direction: "bottom-to-top",
          pins: ["TRIG", "OUT", "RESET"],
        },
      }}
      pinLabels={{
        pin1: "VCC",
        pin2: "DISCH",
        pin3: "THRES",
        pin4: "CTRL",
        pin5: "GND",
        pin6: "TRIG",
        pin7: "OUT",
        pin8: "RESET"
      }}
    />
  </board>
)
`} />

### `schPinStyles`

`schPinStyles` controls the style of the pins on the schematic box 

<CircuitPreview splitView defaultView="schematic" code={`

export default () => (
    <board width="10mm" height="10mm">
      <chip
        name="U1"
        footprint="soic8"
        schPinArrangement={{
          topSide: {
            direction: "left-to-right",
            pins: ["VCC"],
          },
          bottomSide: {
            direction: "left-to-right",
            pins: ["GND"],
          },
          leftSide: {
            direction: "top-to-bottom",
            pins: ["DISCH", "THRES", "CTRL"],
          },
          rightSide: {
            direction: "bottom-to-top",
            pins: ["TRIG", "OUT", "RESET"],
          },
        }}
        schPinStyle={{
          pin1: {
            bottomMargin: 0.2
          },
          GND: {
            rightMargin: "0.5mm"
          },
          THRES: {
            topMargin: 0.5
          },
          OUT: {
            topMargin: 1,
            bottomMargin: "1mm"
          }
        }}
        // This is the future syntax for schPinStyle!
        //   schPinStyle={{
          //   pin1: {
            //   marginBottom: 0.2,
          //   },
          //   GND: { marginRight: "0.5mm" },
          //   THRES: { marginTop: 0.5 },
          //   OUT: {
            //   marginTop: 1,
            //   marginBottom: "1mm",
          //   },
        //   }}
        pinLabels={{
          pin1: "VCC",
          pin2: "DISCH",
          pin3: "THRES",
          pin4: "CTRL",
          pin5: "GND",
          pin6: "TRIG",
          pin7: "OUT",
          pin8: "RESET",
        }}
      />
    </board>
)
`} />


### Custom Footprints

Often you will have a chip that you want to carefully specify the position of
each pad, plated hole, silkscreen line or other PCB element. To do this, just
insert a `<footprint />` component instead of string for the `footprint` prop.

Here's an example of a chip with a custom footprint:

<CircuitPreview splitView defaultView="pcb" code={`

export default () => (
  <board width="10mm" height="10mm">
    <chip
      name="U1"
      footprint={
        <footprint>
          <platedhole
            portHints={["4"]}
            pcbX="3.2499299999998357mm"
            pcbY="-2.249932000000058mm"
            outerDiameter="1.9999959999999999mm"
            holeDiameter="1.3000228mm"
            shape="circle"
          />
          <platedhole
            portHints={["2"]}
            pcbX="3.2499299999998357mm"
            pcbY="2.249932000000058mm"
            outerDiameter="1.9999959999999999mm"
            holeDiameter="1.3000228mm"
            shape="circle"
          />
          <platedhole
            portHints={["1"]}
            pcbX="-3.2499299999999494mm"
            pcbY="2.249932000000058mm"
            outerDiameter="1.9999959999999999mm"
            holeDiameter="1.3000228mm"
            shape="circle"
          />
          <platedhole
            portHints={["3"]}
            pcbX="-3.2499299999999494mm"
            pcbY="-2.249932000000058mm"
            outerDiameter="1.9999959999999999mm"
            holeDiameter="1.3000228mm"
            shape="circle"
          />
          <silkscreenpath
            route={[
              { x: -2.2743160000001126, y: -2.999994000000015 },
              { x: 2.274315999999999, y: -2.999994000000015 },
            ]}
          />
          <silkscreenpath
            route={[
              { x: -2.999994000000129, y: 1.0999978000000965 },
              { x: -2.999994000000129, y: -0.999998000000005 },
            ]}
          />
          <silkscreenpath
            route={[
              { x: 3.0999937999998792, y: 1.0279888000000028 },
              { x: 3.0999937999998792, y: -1.0999977999999828 },
            ]}
          />
          <silkscreenpath
            route={[
              { x: -1.99999600000001, y: 2.999994000000015 },
              { x: 2.274315999999999, y: 2.999994000000015 },
            ]}
          />
        </footprint>
      }
      schPortArrangement={{
        leftSide: {
          direction: "top-to-bottom",
          pins: [1, 3],
        },
        rightSide: {
          direction: "bottom-to-top",
          pins: [4, 2],
        },
      }}
    />
  </board>
)
`} />

For more information about custom footprints, check out the [<footprint /> element](./footprint.mdx)

### Internally Connected Pins

Some chips, such as a standard 4 pin pushbutton, have pins that are internally
connected. This can be useful to represent for simulation or to enable omitting
pins from a schematic.


<CircuitPreview defaultView="code" code={`

export default () => (
  <board width="10mm" height="10mm">
    <chip
      name="U1"
      footprint="pushbutton"
      internallyConnectedPins={[
        ["pin1", "pin4"],
        ["pin2", "pin3"]
      ]}
    />
  </board>
)

`} />


:::note
You may not want to do this for power or ground pins on boards where you're
expected to connect the pins specifically externally. For example, if you have
several V5 pins that each need a decoupling capacitor, it would be better to
manage the connections explicitly with traces (perhaps using `maxTraceLength`!)
even if they are internally connected.
:::

### Externally Connected Pins

To indicate that pins should be externally connected, you can use the `externallyConnectedPins` props.
Just like the `internallyConnectedPins` prop, this is an array of arrays of pin labels, where each
sub-array represents a group of pins that should be connected together.

<CircuitPreview defaultView="code" code={`

export default () => (
  <board width="10mm" height="10mm">
    <chip
      name="U1"
      footprint="soic8"
      pinLabels={{
        pin1: "VCC",
        pin2: "DISCH",
        pin3: "THRES",
        pin4: "CTRL",
        pin5: "GND",
        pin6: "TRIG",
        pin7: "OUT",
        pin8: "RESET"
      }}
      externallyConnectedPins={[
        ["GND", "DISCH"],
        ["TRIG", "VCC"]
      ]}
    />
  </board>
)

`} />

## Specifying the Manufacturer Part Number or Supplier Part Numbers

tscircuit will attempt to find matching parts based on the `manufacturerPartNumber`
and `footprint` that was provided. If you know the exact part from your supplier
you'd like to use, you should set the `supplierPartNumbers` property as shown
below:

<CircuitPreview
  defaultView="pcb"
  code={`

import { createUseComponent } from "@tscircuit/core"
import type { CommonLayoutProps } from "@tscircuit/props"


interface Props extends CommonLayoutProps {
  name: string
}

export const Diode1N4148WS = (props: Props) => {
  return (
    <diode
      {...props}
      supplierPartNumbers={{
        jlcpcb: ["C57759"]
      }}
      footprint={
        <footprint>
          <smtpad
            portHints={["1"]}
            pcbX="-1.1725910000000113mm"
            pcbY="0mm"
            width="0.9999979999999999mm"
            height="0.7500112mm"
            shape="rect"
          />
          <smtpad
            portHints={["2"]}
            pcbX="1.1725910000000113mm"
            pcbY="0mm"
            width="0.9999979999999999mm"
            height="0.7500112mm"
            shape="rect"
          />
          <silkscreenpath
            route={[
              { x: 0.9012427999999773, y: -0.726211400000011 },
              { x: 0.9012427999999773, y: -0.5199887999999646 },
            ]}
          />
          <silkscreenpath
            route={[
              { x: 0.9012427999999773, y: 0.726211400000011 },
              { x: 0.9012427999999773, y: 0.5299964000000728 },
            ]}
          />
          <silkscreenpath
            route={[
              { x: -0.8512047999998913, y: 0.726211400000011 },
              { x: 0.9012427999999773, y: 0.726211400000011 },
            ]}
          />
          <silkscreenpath
            route={[
              { x: -0.8512047999998913, y: -0.726211400000011 },
              { x: 0.9012427999999773, y: -0.726211400000011 },
            ]}
          />
          <silkscreenpath
            route={[
              { x: -0.44676059999994777, y: 0.726211400000011 },
              { x: -0.44676059999994777, y: -0.726211400000011 },
            ]}
          />
        </footprint>
      }
      cadModel={{
        objUrl:
          "https://modelcdn.tscircuit.com/easyeda_models/download?uuid=973acf8a660c48b1975f1ba1c890421a&pn=C57759",
        rotationOffset: { x: 0, y: 0, z: 0 },
        positionOffset: { x: 0, y: 0, z: 0 },
      }}
      schPinSpacing={0.75}
      schPortArrangement={{
        leftSide: {
          direction: "top-to-bottom",
          pins: [1],
        },
        rightSide: {
          direction: "bottom-to-top",
          pins: [2],
        },
      }}
    />
  )
}


`}

/>

If you don't specify `supplierPartNumbers`, tscircuit will automatically scan
for in-stock parts and select a chip using vendor APIs in the Cloud API using
the [platform parts engine](../guides/platform-configuration.md)

### Supported Suppliers

The following are the supported supplier keys. The list is [maintained here](https://github.com/tscircuit/props/blob/main/lib/common/layout.ts#L56) and you can [request additional suppliers by creating an issue](https://github.com/tscircuit/props/issues/new?template=Blank+issue&title=Supplier%20Request%3A%20)

Available supplier keys:

- jlcpcb
- digikey
- mouser
- macrofab
- pcbway
- lcsc

You can also insert custom keys for your organization and they will be copied to
the output [Circuit JSON](https://github.com/tscircuit/circuit-json)


## Type-safe Chips: `ChipProps` and Chip Selectors

tscircuit has a type called `ChipProps` that can be used to properly define
components that wrap a `<chip />` element. By using `ChipProps`, you're
making it 

```tsx
import { sel, type ChipProps } from "tscircuit"

const pinLabels = {
  pin1: "VCC",
  pin2: "DISCH",
  pin3: "THRES",
  pin4: "CTRL",
  pin5: "GND",
  pin6: "TRIG",
  pin7: "OUT",
  pin8: "RESET"
} as const

export const A555Timer = (props: ChipProps<typeof pinLabels>) => (
  <chip
    footprint="soic8"
    pinLabels={pinLabels}
    {...props}
  />
)
```

:::warning
Make sure to have `as const` when you're defining your `pinLabels`, if you're
missing this the types won't work!
:::

You can also use the `sel` object to access the pins of a chip for traces!

```tsx
import { sel } from "tscircuit"
import { A555Timer } from "./a555timer"
import { PowerRegulator } from "./power-regulator"

export default () => {
  return (
    <board width="10mm" height="10mm">
      <PowerRegulator name="M1" />

      <A555Timer
        name="U1"
        connections={{
          GND: "net.GND",
          VCC: sel.M1(PowerRegulator).V5
        }}
      />
    </board>
  )
}
```


## Importing Chips from JLCPCB, KiCad or Circuit JSON

There are a lot of ways to import a chip configuration, each with their own
guide! This is often much easier and reliable than configuring a chip yourself.

- [Importing Components from JLCPCB](../guides/importing-modules-and-chips/importing-from-jlcpcb.mdx)
- [Importing Components from KiCad](../guides/importing-modules-and-chips/importing-from-kicad.md)
</file>

<file path="docs/elements/crystal.mdx">
---
title: <crystal />
sidebar_position: 7
description: >-
  A crystal oscillator provides a stable clock signal essential for timing
  applications and microcontroller operations.
---

## Overview

A crystal oscillator provides a stable clock signal essential for timing applications and microcontroller operations.


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <board width="50mm" height="50mm">
      <crystal
        name="XT1"
        frequency="16MHz"
        loadCapacitance="18pF"
        footprint="hc49"
      />
    </board>
  )`}
/>


## Properties

| Property         | Type                  | Description                                                                                           | Example                |
| ---------------- | --------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------- |
| `frequency`      | number or string      | The operating frequency of the crystal oscillator.                                                  | `16e6` or `"16MHz"`    |
| `loadCapacitance`| number or string      | The load capacitance required for stable operation.                                                 | `18pF`                 |
| `pinVariant`     | PinVariant (optional) | Optional property to select a pin configuration variant if multiple options exist.                    | `"2pin"`            |
</file>

<file path="docs/elements/diode.mdx">
---
title: <diode />
description: >-
  Diodes are semiconductor devices that allow current to flow primarily in one
  direction, making them ideal for rectification, signal clipping, and
  protection against reverse voltage. They are essential in power supply
  circuits and for protecting sensitive components from voltage spikes.
---

## Overview

Diodes are semiconductor devices that allow current to flow primarily in one direction, making them ideal for rectification, signal clipping, and protection against reverse voltage. They are essential in power supply circuits and for protecting sensitive components from voltage spikes.


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <diode name="D1" footprint="0402" />
  )
`}
/>

In this example, the diode is placed on a board using the default footprint "smd-diode".

## Properties

| Property         | Type     | Description                            | Example |
| ---------------- | -------- | -------------------------------------- | ------- |
| `forwardVoltage` | `number` | The forward voltage drop of the diode. | `0.7V`  |

## Pins

Diodes have two pins:

- `pin1`/`anode`/`pos` - The positive terminal where current enters.
- `pin2`/`cathode`/`neg` - The negative terminal where current exits.
</file>

<file path="docs/elements/footprint.mdx">
---
title: <footprint />
---

## Overview

Within a `<footprint />` element you can define PCB elements such as [`<platedhole />`](../footprints/platedhole.mdx)
or [`<smtpad />`](../footprints/smtpad.mdx).

Here's an example of a chip with a custom footprint:

<CircuitPreview splitView defaultView="pcb" code={`

export default () => (
  <board width="10mm" height="10mm">
    <chip
      name="U1"
      footprint={
        <footprint>
          <platedhole
            portHints={["4"]}
            pcbX="3.2499299999998357mm"
            pcbY="-2.249932000000058mm"
            outerDiameter="1.9999959999999999mm"
            holeDiameter="1.3000228mm"
            shape="circle"
          />
          <platedhole
            portHints={["2"]}
            pcbX="3.2499299999998357mm"
            pcbY="2.249932000000058mm"
            outerDiameter="1.9999959999999999mm"
            holeDiameter="1.3000228mm"
            shape="circle"
          />
          <platedhole
            portHints={["1"]}
            pcbX="-3.2499299999999494mm"
            pcbY="2.249932000000058mm"
            outerDiameter="1.9999959999999999mm"
            holeDiameter="1.3000228mm"
            shape="circle"
          />
          <platedhole
            portHints={["3"]}
            pcbX="-3.2499299999999494mm"
            pcbY="-2.249932000000058mm"
            outerDiameter="1.9999959999999999mm"
            holeDiameter="1.3000228mm"
            shape="circle"
          />
          <silkscreenpath
            route={[
              { x: -2.2743160000001126, y: -2.999994000000015 },
              { x: 2.274315999999999, y: -2.999994000000015 },
            ]}
          />
          <silkscreenpath
            route={[
              { x: -2.999994000000129, y: 1.0999978000000965 },
              { x: -2.999994000000129, y: -0.999998000000005 },
            ]}
          />
          <silkscreenpath
            route={[
              { x: 3.0999937999998792, y: 1.0279888000000028 },
              { x: 3.0999937999998792, y: -1.0999977999999828 },
            ]}
          />
          <silkscreenpath
            route={[
              { x: -1.99999600000001, y: 2.999994000000015 },
              { x: 2.274315999999999, y: 2.999994000000015 },
            ]}
          />
        </footprint>
      }
      schPortArrangement={{
        leftSide: {
          direction: "top-to-bottom",
          pins: [1, 3],
        },
        rightSide: {
          direction: "bottom-to-top",
          pins: [4, 2],
        },
      }}
    />
  </board>
)
`} />
</file>

<file path="docs/elements/group.mdx">
---
title: <group />
description: A group is the basic container element that can contain other elements.
---

## Overview

A group is the basic container element that can contain other elements.

By default, a group doesn't have any effect on the circuit.


<CircuitPreview
  defaultView="schematic"
  showTabs={false}
  code={`
  import { sel } from "tscircuit"

  export default () => (
    <board width="10mm" height="10mm">
      <resistor name="R1" resistance="1k" schX={-2} />
      <group schY={-3}>
        <resistor name="R2" resistance="1k" schX={2} />
        <trace from={sel.R1.pin2} to={sel.R2.pin1} />
      </group>
    </board>
  )
  `}
/>


## Moving multiple components via a `<group />`

`<group />` elements can be used to move multiple components at once.

In the example below every schematic symbol inside the `<group />` will be moved
5mm to the right and 3mm up.

```tsx
<group schX={5} schY={3}>
  <resistor name="R1" resistance="1k" footprint="0402" />
  <resistor name="R2" resistance="1k" footprint="0402" schY={2} />
  <resistor name="R3" resistance="1k" footprint="0402" schY={2} />
</group>
```

We can similarly use a `<group />` to move multiple PCB elements at once:

```tsx
<group pcbX={5} pcbY={3}>
  <resistor name="R1" resistance="1k" footprint="0402" />
  <resistor name="R2" resistance="1k" footprint="0402" pcbY={2} />
  <resistor name="R3" resistance="1k" footprint="0402" pcbY={2} />
</group>
```
</file>

<file path="docs/elements/hole.mdx">
---
title: <hole />
---

## Overview

A hole can be used for mounting and doesn't have any conductive properties, for
a hole with a conductive ring of copper see [`<platedhole />`](../footprints/platedhole.mdx).

Holes do not have a schematic representation.

Holes can be used inside of a [`<footprint />`](./footprint.mdx) or
as a standalone element.


<CircuitPreview
  defaultView="3d"
  code={`export default () => (
    <hole diameter="3mm" x={10} y={10} />
  )`}
/>
</file>

<file path="docs/elements/jumper.mdx">
---
title: <jumper />
description: A simple connector that typically uses a pinrow footprint but can be used for custom layouts as well.
---

## Overview

A `<jumper />` represents a small multi-pin connector, commonly a male or female header using a `pinrow` style footprint. You can think of it as a flexible connector that can be placed anywhere on the board much like a `<chip />`.


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <board width="10mm" height="10mm">
      <jumper name="J1" footprint="pinrow4" />
    </board>
  )
  `}
/>

The example above is adapted from the [core tests](https://github.com/tscircuit/core/blob/main/tests/components/normal-components/jumper.test.tsx).

## Properties

`<jumper />` shares many of the common component properties such as `pcbX`, `pcbY` and `footprint`. The full TypeScript interface is defined in [`@tscircuit/props`](https://github.com/tscircuit/props/blob/main/lib/components/jumper.ts):

```ts
export interface JumperProps extends CommonComponentProps {
  manufacturerPartNumber?: string
  pinLabels?: Record<number | string, string | string[]>
  schPinStyle?: SchematicPinStyle
  schPinSpacing?: number | string
  schWidth?: number | string
  schHeight?: number | string
  schDirection?: "left" | "right"
  schPortArrangement?: SchematicPortArrangement
  /** Number of pins on the jumper (2 or 3) */
  pinCount?: 2 | 3
  /**
   * Groups of pins that are internally connected
   * e.g., [["1","2"], ["2","3"]]
   */
  internallyConnectedPins?: string[][]
}
```

Jumpers are often placed using footprints such as `pinrow8` or `pinrow6_female_rows2`, but you can also provide a custom `<footprint />` just like with `<chip />`.

### Internally Connected Pins

Use the `internallyConnectedPins` prop when the jumper has pins that should be shorted (bridged) together by default. Pins can be referenced by their labels.

<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <board width="10mm" height="10mm">
      <jumper
        name="J2"
        footprint="pinrow3"
        pinCount={3}
        pinLabels={{ 1: "A", 2: "B", 3: "C" }}
        internallyConnectedPins={[["A", "B"], ["B", "C"]]}
      />
    </board>
  )
  `}
/>

| Property | Type | Description |
| -------- | ---- | ----------- |
| `pinCount` | `2` \| `3` | Number of pins on the jumper |
| `internallyConnectedPins` | `string[][]` | Groups of pins that are internally connected |
| `manufacturerPartNumber` | `string` | Manufacturer part number |
| `pinLabels` | `Record<number \| string, string \| string[]>` | Labels for pins or sets of pins |
| `schPinStyle` | `SchematicPinStyle` | Style used for pins in the schematic |
| `schPinSpacing` | `number` \| `string` | Spacing between schematic pins |
| `schWidth` | `number` \| `string` | Width of the schematic symbol |
| `schHeight` | `number` \| `string` | Height of the schematic symbol |
| `schDirection` | `"left"` \| `"right"` | Direction the jumper faces in the schematic |
| `schPortArrangement` | `SchematicPortArrangement` | Arrangement of ports in the schematic |
</file>

<file path="docs/elements/led.mdx">
---
title: <led />
description: >-
  Light emitting diodes are diodes that emit light when current
  passes through them. They are commonly used as indicators on a circuit board
  such as a "power on indicator" or "data transfer in progress indicator
---

## Overview

Light emitting diodes are [diodes](./diode.mdx) that emit light when current
passes through them. They are commonly used as indicators on a circuit board
such as a "power on indicator" or "data transfer in progress indicator".


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <led name="LED1" footprint="0603" color="red" />
  )
`}
/>

## Properties

| Property         | Example Value | Description                                                      |
| ---------------- | ------------- | ---------------------------------------------------------------- |
| `color`          | `red`         | The color of the LED. `red` LEDs are most common.                |
| `forwardVoltage` | `1.6V`        | The voltage drop across the LED when forward current is applied. |

### Common LED Footprints

The following represent the most common footprints for LEDs based on [jlcsearch](https://jlcsearch.tscircuit.com),
you can provide these as the `footprint` property to the `led` element e.g. `<led footprint="led0603" />`

| Footprint | ~JLCPCB Popularity |
| --------- | ------------------ |
| `led0603` | 37%                |
| `led0805` | 23%                |
| `led1206` | 10%                |
| `led0402` | 4%                 |

## Automatic Part Selection

LEDs are automatically selected according to their color and footprint using
the [platform parts engine](../guides/platform-configuration.md)
</file>

<file path="docs/elements/mosfet.mdx">
---
title: <mosfet />
description: >-
  A MOSFET or "metal-oxide-semiconductor field-effect transistor" is a type of
  transistor that is used to control the flow of current through a circuit.
---

## Overview

A MOSFET or "metal-oxide-semiconductor field-effect transistor" is a type of transistor that is used to control the flow of current through a circuit.


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <mosfet
      name="Q1"
      channelType="n"
      mosfetMode="depletion"
      footprint="sot23"
    />
  )
`}
/>

## Properties

| Property      | Description                                         | Example       |
| ------------- | --------------------------------------------------- | ------------- |
| `channelType` | The type of channel the MOSFET has (`n`, `p`)       | `"n"`         |
| `mosfetMode`  | The mode of the MOSFET (`enhancement`, `depletion`) | `"depletion"` |
</file>

<file path="docs/elements/net.mdx">
---
title: <net />
sidebar_position: 6.5
description: >-
  The `<net />` element represents a bunch of traces that are all connected. You
  should use nets for representing power buses such as "V5", "V3_3" and "GND"
---

## Overview

The `<net />` element represents a bunch of traces that are all connected. You
should use nets for representing power buses such as "V5", "V3_3" and "GND"

When using a `<net />`, you're being less specific than when you explicitly
connect ports with `<trace />` elements. A net simply groups together traces
that share the same name, letting the autorouter handle the actual routing
between them.


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <group>
      <capacitor capacitance="1uF" footprint="0603" name="C1" />
      <net name="V5" />
      <trace from="net.V5" to=".C1 .pos" />
    </group>
  )
  `}
/>


## Net Properties

Nets can have properties that will pass onto any PCB trace within them. The 
trace properties can be automatically used for autorouting adjustments or to
validate connections (such as validating that a chip is connected to a power
source)

| Property | Description |
| -------- | ----------- |
| `isForPower`  | The net is used to deliver power ("V5", "V3_3") |  
| `isGround` | The net is used as a ground path |

## Implicit Nets

If you use a net in a [port or net selector](../guides/port-and-net-selectors.md)
e.g. `"net.V5"` and there is not `<net name="V5" />`, then you are implicitly
creating that net. tscircuit treats it exactly as if you had declared
`<net name="V5" />` in your design.
</file>

<file path="docs/elements/netlabel.mdx">
---
title: <netlabel />
description: >-
  The `<netlabel />` element attaches a text label to a net on the schematic.
  It replaces the old `<netalias />` element.
---

## Overview

`<netlabel />` places a small label on a schematic net so you can easily
identify power rails and other connections. It is especially useful in
conjunction with the `connections` prop of components or modules to
show where a net connects.


The preview below uses `leftView="code"` and `rightView="schematic"` to show the
schematic alongside the example code.

<CircuitPreview
  leftView="code"
  rightView="schematic"
  code={`
    import { sel } from "tscircuit"
    export default () => (
      <board routingDisabled>
        <chip
          name="U1"
          manufacturerPartNumber="I2C_SENSOR"
          footprint="soic4"
          pinLabels={{
            pin1: "SCL",
            pin2: "SDA",
            pin3: "VCC",
            pin4: "GND",
          }}
          schPinArrangement={{
            leftSide: {
              direction: "top-to-bottom",
              pins: ["SCL", "SDA", "VCC", "GND"],
            },
          }}
          connections={{
            SCL: sel.net.SCL,
            SDA: sel.net.SDA,
            VCC: sel.net.V3_3,
            GND: sel.net.GND,
          }}
        />
        <netlabel
          schX={-2}
          schY={-1}
          anchorSide="top"
          net="GND"
          connection="U1.GND"
        />
        <netlabel
          schX={-2}
          schY={0.8}
          net="VCC"
          connection="U1.VCC"
          anchorSide="bottom"
        />
      </board>
    )
  `}
/>

## Properties

| Property | Description | Example |
| -------- | ----------- | ------- |
| `net` | Name of the net that the label represents | `"VCC"` |
| `connection` | [Port selector](../guides/port-and-net-selectors.md) of the point the label attaches to | `"U1.VCC"` |
| `anchorSide` | Which side of the connection to place the label. One of `"top"`, `"bottom"`, `"left"`, or `"right"` | `"top"` |
| `schX`, `schY` | Position of the label on the schematic | `0`, `-1` |
| `text` | Custom text for the label (defaults to the net name) | `"V3_3"` |

Use `<netlabel />` to clearly mark nets in your schematic, especially for
power rails or when multiple wires join at a single connection point.
</file>

<file path="docs/elements/pinheader.mdx">
---
title: <pinheader />
description: The `<pinheader />` element is used to create a male or female pin header with configurable spacing and number of pins.
---

## Overview

The `<pinheader />` element is used to create a male or female pin header
with configurable spacing and number of pins.


## Example

<CircuitPreview
  defaultView="schematic"
  code={`export default () => (
    <pinheader
      name="J1"
      pinCount={8}
      gender="male"
      pitch="2.54mm"
      doubleRow={true}
      showSilkscreenPinLabels={true}
      pinLabels={["VCC", "GND", "SDA", "SCL", "MISO", "MOSI", "SCK", "CS"]}
      x={10}
      y={10}
    />
  )
`}
/>

## Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| pinCount | number | (required) | Number of pins in the header |
| pitch | number \| string | "2.54mm" | Distance between pins |
| schFacingDirection | "up" \| "down" \| "left" \| "right" | "right" | Direction the header faces in schematic view |
| gender | "male" \| "female" | "male" | Whether the header is male or female |
| showSilkscreenPinLabels | boolean | false | Whether to show pin labels in silkscreen |
| doubleRow | boolean | false | Whether the header has two rows of pins |
| holeDiameter | number \| string | "1mm" | Diameter of the through-hole for each pin |
| platedDiameter | number \| string | "1.7mm" | Diameter of the plated area around each hole |
| pinLabels | string[] | undefined | Labels for each pin |
| facingDirection | "left" \| "right" | "right" | Direction the header is facing |
| x | number | 0 | X position of the component |
| y | number | 0 | Y position of the component |
| rotation | number | 0 | Rotation of the component in degrees |
| id | string | auto-generated | Unique identifier for the component |
</file>

<file path="docs/elements/potentiometer.mdx">
---
title: <potentiometer />
description: >-
  A potentiometer is a three-terminal resistor with a sliding or rotating contact
  that forms an adjustable voltage divider. You can also attach two terminals to
  create a variable resistor.
---

## Overview

A potentiometer is a three-terminal resistor with a sliding or rotating contact
that forms an adjustable voltage divider. You can also attach two terminals to
create a variable resistor.


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <board width="10mm" height="10mm">
      <potentiometer
        name="P1"
        maxResistance="10k"
        footprint="pinrow3"
      />
    </board>
  )
  `}
/>

## Variants (two or three terminals)

The `<potentiometer />` element can be configured with two or three terminals
using the `pinVariant` prop.

| Pin Variant | Description |
| ----------- | ----------- |
| `two_pin` | Two terminals |
| `three_pin` | Three terminals |

<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <board width="10mm" height="10mm">
      <potentiometer
        name="P1"
        maxResistance="10k"
        pinVariant="three_pin"
        footprint="pinrow3"
      />
    </board>
  )
  `}
/>
</file>

<file path="docs/elements/pushbutton.mdx">
---
title: <pushbutton />
description: >-
  Pushbuttons a common type of switch normally open momentary switch. They are
  commonly used as a reset or pairing button.
---

## Overview

Pushbuttons a common type of switch normally open momentary switch. They are
commonly used as a reset or pairing button.


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <board width="10mm" height="10mm">
      <pushbutton
        name="SW1"
        footprint="pushbutton"
      />
    </board>
  )
  
  `}
/>

## Pins

| Pin  | Aliases    | Description |
| ------- | -- |----------- |
| `1` | `side1` | One of the left side pins  |
| `2` | `side1` | One of the left side pins |
| `3` | `side2` | One of the right side pins |
| `4` | `side2` | One of the right side pins |

:::info
The pins are internally connected, so you only need to connect one of the
left or right pins.
:::

## Example: A small keyboard grid of pushbuttons

<CircuitPreview
  defaultView="schematic"
  code={`
  import { grid } from "@tscircuit/math-utils"

  export default () => (
    <board width="36mm" height="36mm">
      {grid({
        rows: 3,
        cols: 3,
      }).map((cell) => (
        <pushbutton
          name={\`SW\${cell.index}\`}
          footprint="pushbutton"
          schX={cell.center.x * 2}
          schY={cell.center.y}
          pcbX={cell.center.x * 12}
          pcbY={cell.center.y * 12}
        />  
      ))}
    </board>
  )
  `}
/>
</file>

<file path="docs/elements/resistor.mdx">
---
title: <resistor />
sidebar_position: 2
description: >-
  A `<resistor />` is an extremely common element of electronic designs. It limits
  the flow of electricity and is critial to making sure digital signals are
  properly "pulled up" or "pulled down" to set their default value as `1` or `0`
---

## Overview

A `<resistor />` is an extremely common element of electronic designs. It limits
the flow of electricity and is critial to making sure digital signals are
properly "pulled up" or "pulled down" to set their default value as `1` or `0`

A resistor element has two pins and is non-polar, meaning it doesn't matter if
you place it on backwards (it resists electricity identically either way!)

When specifying a resistor, you'll usually want to give it a footprint string
such as `0402` or `0603` to indicate it's size. You can see the most popular
resistor sizes for different power ratings at [jlcsearch](https://jlcsearch.tscircuit.com/resistors/list)


<CircuitPreview
  defaultView="schematic"
  code={`

export default () => (
    <resistor
      name="R1"
      footprint="0402"
      resistance="1k"
    />
)

  `}
/>

## Pins

A resistor has the following pins and aliases

| Pin # | Aliases | Description |
| ---------- | ------- | ----------- |
| pin1 | left, pos | The left side pin in normal orientation |
| pin2 | right, neg | The right side pin in normal orientation |

:::note
For convenience, you can use the `pos` and `neg` aliases for the resistor. This
can help to remember which pin is which for the purpose of pulling up or pulling
down a signal, but the resistor is non-polar so `pos`/`neg` are meaningless. 
:::
## Tolerances

Resistors can be made to different tolerances. In particular, you might care
about the following resistor characteristics:

- **tolerance** - a percentage given with a string, e.g. `tolerance="5%"`. This specifies how accurate the resistance needs to be
- **powerRating** - a wattage e.g. "5W" indicating how much power can transfer through the resistor for normal operation
- **temperatureOperatingRange** - a string indicating the listed range for the resistor's operating temperature `"-15F-150F"`

## Automatic Part Selection

You generally don't need to specify `supplierPartNumbers` with a resistor, tscircuit
will use the [platform parts engine](../guides/platform-configuration.md) to
automatically search vendors for a part matching your tolerances.
</file>

<file path="docs/elements/resonator.mdx">
---
title: <resonator />
---

## Overview

Resonators are common components used to provide a stable frequency reference for
circuits. They are often used in clock circuits or as a timing element.


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <board width="10mm" height="10mm">
      <resonator
        name="X1"
        frequency="16MHz"
        loadCapacitance="5pF"
        footprint="hc49"
      />
    </board>
  )
  `}
/>
</file>

<file path="docs/elements/schematictext.mdx">
---
title: <schematictext />
description: The `<schematictext />` element places text directly on the schematic.
---

## Overview

`<schematictext />` is a primitive element used to display standalone text on the schematic. It does not appear on the PCB.


<CircuitPreview
  hide3DTab
  hidePCBTab
  defaultView="schematic"
  code={`
  export default () => (
    <board width="10mm" height="10mm">
      <schematictext text="Hello" schX={2} schY={3} color="red" anchor="center" />
    </board>
  )
  `}
/>


## Properties

| Property | Type | Description |
|---------|------|-------------|
| `text` | string | The text string to render. |
| `schX` | length | X coordinate of the text. |
| `schY` | length | Y coordinate of the text. |
| `anchor` | enum | Anchor position such as `"center"`, `"left"`, `"right"`, `"top"`, `"bottom"`, or corner positions. Defaults to `"center"`. |
| `fontSize` | number | Font size in schematic units. Default `1`. |
| `color` | string | Color of the text, specified as a hex string. Default `"#000000"`. |
| `schRotation` | angle | Rotation of the text in degrees. Default `0`. |
</file>

<file path="docs/elements/solderjumper.mdx">
---
title: <solderjumper />
description: Small pads that can be cut or bridged with solder for configuration options.
---

## Overview

A `<solderjumper />` is a tiny jumper made from exposed pads on the PCB. These pads can be bridged or cut to change the circuit after manufacturing. While a regular `<jumper />` usually uses a header-style footprint, solder jumpers are often just copper pads separated by a thin gap.


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <solderjumper name="SJ1" footprint="solderjumper2_bridged12" bridgedPins={[["1","2"]]} />
  )
  `}
/>

This snippet is based on the tests from [tscircuit/core](https://github.com/tscircuit/core/blob/main/tests/components/normal-components/solderjumper.test.tsx).

If you provide the `bridgedPins` property, tscircuit will create a small trace connecting those pins by default. You can cut the trace to open the connection or solder across the pads to reconnect them.

## Properties

The `<solderjumper />` component extends `<jumper />` with one additional property. From [`@tscircuit/props`](https://github.com/tscircuit/props/blob/main/lib/components/solderjumper.ts):

```ts
export interface SolderJumperProps extends JumperProps {
  /** Pins that are bridged with solder by default */
  bridgedPins?: string[][]
}
```

Use solder jumpers when you need a configuration option that can be easily changed with a soldering iron.
</file>

<file path="docs/elements/subcircuit.mdx">
---
title: <subcircuit />
description: >-
  A `<subcircuit />` is a powerful organizational element in tscircuit that
  represents a collection of elements that are tightly coupled. Subcircuits are
  often used for a small functional block, such as a voltage regulator.
---

## Overview

A `<subcircuit />` is a powerful organizational element in tscircuit that
represents a collection of elements that are tightly coupled. Subcircuits are
often used for a small functional block, such as a voltage regulator.

Within a subcircuit, you can have a custom autorouter or isolated nets from the
larger circuits. You can also re-use reference designators. Your subcircuit is
essentially isolated from other subcircuits.


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <board width="10mm" height="10mm">
      <subcircuit name="subcircuit1" schX={-2}>
        <resistor name="R1" resistance="1k" />
      </subcircuit>
      <subcircuit name="subcircuit2" schX={2}>
        <resistor name="R2" resistance="1k"  />
      </subcircuit>
      <trace from=".subcircuit1 .R1 .pin1" to=".subcircuit2 .R2 .pin1" />
    </board>
  )
  `}
/>

## Reuse Reference Designators

Reusing reference designators is typically considered a bad practice, but in
tscircuit reference designators are intelligently prefixed prior to being
written on the silkscreen. This means that you can design your subcircuits
without worrying about whether or not a reference designator has been previously
used.

Within a subcircuit, you'll never select inside of another subcircuit without
explicitly specifying the subcircuit `name` in a selector. This means you never
need to worry about other `R1` or `C1` selectors from other subcircuits, they
will not be selected unless you explicitly include a subcircuit selector
e.g. `.somesubcircuit .R1`

<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <board width="10mm" height="10mm">
      <subcircuit name="subcircuit1" schX={-2}>
        <resistor name="R1" resistance="1k" />
      </subcircuit>
      <subcircuit name="subcircuit2" schX={2}>
        <resistor name="R1" resistance="1k" />
      </subcircuit>
      <trace from=".subcircuit1 .R1 .pin1" to=".subcircuit2 .R1 .pin1" />
    </board>
  )
  `}
/>

## Configuring the Autorouter

Subcircuits can have a custom autorouter configuration. This will be inherited
by any children subcircuits.

To specify a custom autorouter configuration, just set the `autorouter` property
on a `<subcircuit />` element.

```tsx
<subcircuit autorouter="auto-cloud">
  <resistor name="R1" resistance="1k" footprint="0402" />
  <resistor name="R2" resistance="1k" footprint="0402" />
  {/* ... */}
</subcircuit>
```

Specifying custom autorouter settings for subcircuits can be extremely useful
when you have a tricky section of components that have special requirements.

Read more about [the autorouter prop here](./board.mdx#setting-the-autorouter).
</file>

<file path="docs/elements/switch.mdx">
---
title: <switch />
description: A switch is a mechanical device that can be used to connect or disconnect a circuit.
---

## Overview

A switch is a mechanical device that can be used to connect or disconnect a
circuit.


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <switch name="SW1" type="spst" />
  )
  `}
/>

## Properties

| Property | Type | Description |
| -------- | -------- | -------- |
| `type` | `"spst"` \| `"spdt"` \| `"dpst"` \| `"dpdt"` | The type of switch |
| `isNormallyClosed` | `boolean` | Whether the switch is normally closed |


## Types of Switches

| Type | Description |
| ---- | ----------- |
| `spst` | Single Pole Single Throw - The simplest switch type with one input and one output |
| `spdt` | Single Pole Double Throw - One input that can be connected to either of two outputs |
| `dpst` | Double Pole Single Throw - Two separate inputs each connecting to their own output |
| `dpdt` | Double Pole Double Throw - Two separate inputs that can each connect to either of two outputs |

<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <group>
      <switch name="SW1" type="spst" schX={-1} schY={-1} />
      <switch name="SW1" type="spdt" schX={1} schY={-1} />
      <switch name="SW3" type="dpst" schX={-1} schY={1} />
      <switch name="SW4" type="dpdt" schX={1} schY={1} />
    </group>
  )
  `}
/>


## When to use `<switch />` vs `<pushbutton />`

You should always use `<pushbutton />` or any more specific switch element
when possible. `<switch />` is a more generic element with less defaults.
</file>

<file path="docs/elements/trace.mdx">
---
title: <trace />
sidebar_position: 5
description: >-
  The `<trace />` element represents an electrical connection between two or
  more points in your circuit. Traces can connect components, nets, or specific
  pins on components.
---


## Overview

The `<trace />` element represents an electrical connection between two or more points in your circuit. Traces can connect components, nets, or specific pins on components.

## Basic Usage

Here's a simple example connecting two components:

<CircuitPreview defaultView="pcb" code={`
  export default () => (
    <board width="10mm" height="10mm">
      <resistor name="R1" resistance="1k" footprint="0402" pcbX={-2} schX={-2} />
      <capacitor name="C1" capacitance="100nF" footprint="0402" pcbX={2} />
      <trace
        from=".R1 > .pin1"
        to=".C1 > .pin1"
      />
    </board>
  )
`} />

## Trace Properties

| Property | Description | Example |
| -------- | ----------- | ------- |
| `from` | Starting point of the trace using a [port selector](../guides/port-and-net-selectors.md) | `".R1 > .pin1"` |
| `to` | Ending point of the trace using a [port selector](../guides/port-and-net-selectors.md) | `".C1 > .pin1"` |
| `maxLength` | Maximum length the trace can be (optional) | `"10mm"` |
| `minLength` | Minimum length the trace must be (optional) | `"5mm"` |
| `width` | Width of the trace (optional) | `"0.2mm"` |

## Connecting to Nets

Traces can connect to named nets like power and ground:

<CircuitPreview defaultView="schematic" code={`
  export default () => (
    <board width="10mm" height="10mm">
      <resistor name="R1" resistance="1k" footprint="0402" />
      <trace from=".R1 > .pin1" to="net.GND" />
      <trace from=".R1 > .pin2" to="net.VCC" />
    </board>
  )
`} />

## Autorouting

Traces are automatically routed by tscircuit's [autorouting system](./board.mdx#setting-the-autorouter). The autorouter will:

1. Find a path between components that doesn't intersect other traces
2. Use vias to change layers when needed
3. Respect any length constraints specified
4. Try to minimize the number of vias used

You can customize the autorouting behavior by setting the `autorouter` property on the parent [`<board />`](./board.mdx) or [`<subcircuit />`](./subcircuit.mdx).

## Length Constraints 

Sometimes you need traces to be exactly a certain length, like for high-speed signals. You can use `maxLength` and `minLength`:

<CircuitPreview defaultView="pcb" code={`
export default () => (
  <board width="20mm" height="20mm">
    <chip name="U1" footprint="soic8" pcbX={-5} />
    <chip name="U2" footprint="soic8" pcbX={5} />
    <trace
      from=".U1 > .pin1"
      to=".U2 > .pin1"
      maxLength="15mm"
      minLength="12mm"
    />
  </board>
)
`} />

## Differential Pairs

For high-speed signals, you often need pairs of traces to have matched lengths. You can use the `differentialPairKey` property to group traces:

:::info
The `differentialPairKey` property is in beta and not available on all autorouters yet!
:::

<CircuitPreview defaultView="pcb" code={`
  export default () => (
    <board width="20mm" height="20mm">
      <chip name="U1" footprint="soic8" pcbX={-5} />
      <chip name="U2" footprint="soic8" pcbX={5} />
      <trace
        from=".U1 > .pin1"
        to=".U2 > .pin1"
        differentialPairKey="pair1"
      />
      <trace
        from=".U1 > .pin2"
        to=".U2 > .pin2"
        differentialPairKey="pair1"
      />
    </board>
  )
`} />

The autorouter will ensure both traces in the pair have the same length.

## Net vs Direct connections

There are generally two ways that traces are represented on a PCB "Rats Nest" 
or on a schematic and they have very different results:

- **Net** - A trace that connects a net to a component pin.
  - `<trace from="net.GND" to=".R1 > .pin1" />`
- **Direct** - A trace that connects two component pins directly.
  - `<trace from=".R1 > .pin1" to=".C2 > .pin2" />`

When you specify a trace with a net, the autorouter will look for the best
place to tie into the net. This means you're not specifying the exact location
where the trace will go.

When using net connections we use a Rats Nest on a PCB view or a net label on a
schematic view. When you see a dotted line on a Rats Nest, you should think of
it as a _possible_ connection point, but not necessarily the final place where
the autorouter will connect to the net.
</file>

<file path="docs/elements/transistor.mdx">
---
title: <transistor />
description: >-
  A transistor is a three-terminal semiconductor device that can amplify or
  switch electronic signals. It is a fundamental component in many electronic
  circuits, including amplifiers, oscillators, and digital logic gates.
---

## Overview

A transistor is a three-terminal semiconductor device that can amplify or switch electronic signals. It is a fundamental component in many electronic circuits, including amplifiers, oscillators, and digital logic gates.


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <transistor
      name="Q1"
      type="npn"
      footprint="sot23"
    />
  )
`}
/>

There are different types of transistors, so where possible you should use the
most specific element to represent your use case

- [`<transistor />`](./transistor.mdx) - Generic transistor
- [`<mosfet />`](./mosfet.mdx) - MOSFET transistor

## Properties

| Property | Description                                                     | Example |
| -------- | --------------------------------------------------------------- | ------- |
| `type`   | The type of transistor (`npn`, `pnp`, `mosfet`, `igbt`, `jfet`) | `"npn"` |
</file>

<file path="docs/elements/via.mdx">
---
title: <via />
description: >-
  A via is a plated hole that connects different layers of a PCB. Vias are
  commonly used to route traces between layers and for thermal management.
---

## Overview

A via is a plated hole that connects different layers of a PCB. Vias are
commonly used to route traces between layers and for thermal management.

Vias do not have a schematic representation.

You generally do not need to manually create vias, they will be handled
automatically by the [autorouter](./board.mdx#setting-the-autorouter).


<CircuitPreview
  defaultView="pcb"
  code={`export default () => (
    <via
      fromLayer="top"
      toLayer="bottom"
      outerDiameter="0.8mm"
      holeDiameter="0.4mm"
      x={10}
      y={10}
    />
  )`}
/>

## Properties


| Property | Type | Default | Description |
|----------|------|---------|-------------|
| fromLayer | string | "top" | Starting layer for the via |
| toLayer | string | "bottom" | Ending layer for the via |
| holeDiameter | number \| string | "0.4mm" | Diameter of the plated hole |
| outerDiameter | number \| string | "0.8mm" | Outer diameter of the copper annular ring |
| x | number | 0 | PCB X position of the via |
| y | number | 0 | PCB Y position of the via |
</file>

<file path="docs/footprints/constraint.mdx">
---
title: <constraint />
description: >-
  The `<constraint />` element is used to enforce geometric relationships
  between different elements in a PCB footprint. Constraints can set specific
  distances and alignments, such as center-to-center, edge-to-edge, or ensuring
  two elements line up along the same axis.
---

## Overview

The `<constraint />` element is used to enforce geometric relationships between different elements in a PCB footprint. Constraints can set specific distances and alignments, such as center-to-center, edge-to-edge, or ensuring two elements line up along the same axis.

Below is a reference example that demonstrates how constraints are used within a footprint. This example is part of a test suite to validate that a KeyswitchSocket component is correctly flipped when placed on different layers of a board.


<CircuitPreview defaultView="pcb" code={`

  /**
   * A switch shaft you can use to connect a pluggable Kailh socket.
   */
  const KeyswitchSocket = (props: {
    name: string
    pcbX?: number
    pcbY?: number
    layer?: "top" | "bottom"
  }) => (
    <chip
      {...props}
      cadModel={{
        objUrl: "/easyeda/C5184526",
      }}
      footprint={
        <footprint>
          {/* <silkscreentext text={props.name} /> */}
          <smtpad
            shape="rect"
            width="2.55mm"
            height="2.5mm"
            portHints={["pin1"]}
            layer="top"
          />
          <smtpad
            shape="rect"
            width="2.55mm"
            height="2.5mm"
            portHints={["pin2"]}
            layer="top"
          />
          <hole name="H1" diameter="3mm" />
          <hole name="H2" diameter="3mm" />
          <constraint xDist="6.35mm" centerToCenter left=".H1" right=".H2" />
          <constraint yDist="2.54mm" centerToCenter top=".H1" bottom=".H2" />
          <constraint edgeToEdge xDist="11.3mm" left=".pin1" right=".pin2" />
          <constraint sameY for={[".pin1", ".H1"]} />
          <constraint sameY for={[".pin2", ".H2"]} />
          <constraint
            edgeToEdge
            xDist={(11.3 - 6.35 - 3) / 2}
            left=".pin1"
            right=".H1"
          />
        </footprint>
      }
    />
  )

  export default () => (
    <board width="40mm" height="40mm">
      <KeyswitchSocket name="SW1" pcbX={-10} pcbY={0} layer="top" />
      <KeyswitchSocket name="SW2" pcbX={10} pcbY={0} layer="bottom" />
    </board>
  )


`} />

## Key Constraints Summary

- `<constraint xDist="..." centerToCenter ... />`: Defines a constraint based on the center positions of two elements.
- `<constraint edgeToEdge xDist="..." ... />`: Sets a fixed distance between the edges of two elements.
- `<constraint sameY for={["...", "..."]} />`: Ensures that multiple elements share the same Y coordinate.

Use these constraints to help align footprint elements consistently across your designs.
</file>

<file path="docs/footprints/footprint-elements-vs-footprint-strings.mdx">
---
title: Footprint Elements vs Strings
sidebar_position: 1
---

When setting the `footprint` property for an element, you can either
use [footprinter strings](./footprinter-strings.mdx) or use the [`<footprint />`](../elements/footprint.mdx)
element and manually specify pad positions.

Footprinter strings are often quicker, more concise, and have the benefit of often
mapping to a 3d model.



<CircuitPreview code={`
  export default () => (
    <group>
      <resistor name="R1" footprint="0402" resistance="1k" pcbX={-3} />
      <resistor name="R2" footprint={
        <footprint>
          <smtpad portHints={["1"]} pcbX={-0.5} shape="rect" width={0.6} height={0.6} />
          <smtpad portHints={["2"]} pcbX={0.5} shape="rect" width={0.6} height={0.6} />
          <silkscreenpath route={[
            {x: -0.1, y: 0.2},
            {x: 0.1, y: 0.2}
          ]} />
          <silkscreenpath route={[
            {x: -0.1, y: -0.2}, 
            {x: 0.1, y: -0.2}
          ]} />
        </footprint>
      } pcbX={3} resistance="1k" />
    </group>
  )
`} />
</file>

<file path="docs/footprints/footprinter-strings.mdx">
---
title: Footprinter Strings
sidebar_position: 2
description: >-
  You can quickly specify the footprint and 3d model for any element by setting
  the `footprint` property to a string. 
---

## Overview

You can quickly specify the footprint and 3d model for any element by setting
the `footprint` property to a string. 

import FootprintPreview from "@site/src/components/FootprintPreview"

<FootprintPreview footprint="0402" />

## dip

Dual in-line package.

<FootprintPreview footprints={["dip", "dip16_p1.27_id0.6mm_od0.9mm", "dip8_wide"]} />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `p`       | `"2.54mm"` | Pitch. Space between pins |
| `id`      | `"1mm"`  | Inner diameter (hole diameter) of plated holes |
| `od`      | `"1.5mm"`| Outer diameter (copper diameter) of plated holes |
| `w`       | `"300mil"` | Distance between columns |
| `wide`    | `false`   | Wide DIP style (600mil between columns) |
| `narrow`    | `true`   | Narrow DIP style (300mil between columns) |


## axial

Basic through-hole “axial” resistor or diode footprint.

Examples:

- `axial`
- `axial_p0.1in`

<FootprintPreview footprint="axial" />

`axial` parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `p`       | `"2.54mm"` | Pitch. Space between pins |
| `id`      | `"0.7mm"`  | Inner diameter (hole diameter) of plated holes |
| `od`      | `"1mm"`    | Outer diameter (copper diameter) of plated holes |

## 0402

Standard imperial 0402 package. `1.0mm × 0.5mm`

<FootprintPreview footprint="0402" />

## 0603

Standard imperial 0603 package. `1.6mm × 0.8mm`

<FootprintPreview footprint="0603" />

## 0805

Standard imperial 0805 package. `2.0mm × 1.2mm`

<FootprintPreview footprint="0805" />

## 1206

Standard imperial 1206 package. `3.2mm × 1.6mm`

<FootprintPreview footprint="1206" />

## 1210

Standard imperial 1210 package. `3.2mm × 2.5mm`

<FootprintPreview footprint="1210" />

## soic

Small Outline Integrated Circuit (SOIC) footprint.

<FootprintPreview footprints={["soic", "soic16_w7mm_p0.8mm"]} />

**Parameters:**

| Parameter     | Default    | Description                                                             |
|---------------|------------|-------------------------------------------------------------------------|
| `num_pins`    | `8`        | Number of pins in the package.                                          |
| `w`           | `"5.3mm"`  | Overall package width.                                                  |
| `p`           | `"1.27mm"` | Pin pitch (center-to-center distance between adjacent pins).            |
| `pl`          | `"1.0mm"`  | Pin length.                                                             |
| `pw`          | `"0.6mm"`  | Pin width.                                                              |
| `legsoutside` | `false`    | If true, positions pins outside the package body; otherwise, pins are inset. |

---

## bga

Ball Grid Array (BGA) footprint.

<FootprintPreview footprints={["bga9", "bga16_p2mm", "bga14_p1.5mm_missing(1,2)"]} />

**Parameters:**

| Parameter   | Default       | Description                                                                      |
|-------------|---------------|----------------------------------------------------------------------------------|
| `num_pins`  | `64`          | Total number of solder balls.                                                    |
| `grid`      | _calculated_  | Grid dimensions as an object (e.g. `{ x: N, y: N }`). If unspecified, a square grid is assumed. |
| `p`         | `"0.8mm"`     | Ball pitch: center-to-center distance between adjacent balls.                   |
| `w`         | _none_        | Package width (optional).                                                        |
| `h`         | _none_        | Package height (optional).                                                       |
| `ball`      | _none_        | Ball diameter (optional).                                                        |
| `pad`       | _none_        | Pad size for each ball (optional).                                               |
| `tlorigin`  | `false`       | Use top-left numbering for balls.                                                |
| `blorigin`  | `false`       | Use bottom-left numbering for balls.                                             |
| `trorigin`  | `false`       | Use top-right numbering for balls.                                               |
| `brorigin`  | `false`       | Use bottom-right numbering for balls.                                            |
| `missing`   | `[]`          | List of balls to omit (by number or position) to accommodate design needs.       |

## tssop

Thin-Shrink Small Outline Package (TSSOP) footprint. Default configuration is 6.1mm width with 0.65mm pitch.

<FootprintPreview footprints={["tssop20", "tssop20_w6.5mm_p0.65mm"]} />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `num_pins` | `8` | Number of pins in the package |
| `w` | `"6.1mm"` | Overall package width |
| `p` | `"0.65mm"` | Pin pitch (center-to-center distance between adjacent pins) |
| `pw` | _calculated_ | Pin width (calculated from pitch if not specified) |
| `pl` | _calculated_ | Pin length (calculated from pin width if not specified) |

## stampboard

A breakout board with configurable pins on all sides. Can include inner holes for mounting.

<FootprintPreview footprints={["stampboard_left10_right10_bottom4_top0_w21mm_p2.54mm", "", "stampboard_left20_right20_bottom3_top2_w21mm_p2.54mm_innerhole"]} />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `w` | `"22.58mm"` | Board width |
| `h` | _calculated_ | Board height (calculated from number of pins if not specified) |
| `left` | `20` | Number of pins on left side |
| `right` | `20` | Number of pins on right side |
| `top` | `2` | Number of pins on top side |
| `bottom` | `2` | Number of pins on bottom side |
| `p` | `"2.54mm"` | Pin pitch |
| `pw` | `"1.6mm"` | Pin width |
| `pl` | `"2.4mm"` | Pin length |
| `innerhole` | `false` | Whether to include inner mounting holes |
| `innerholeedgedistance` | `"1.61mm"` | Distance of inner holes from edge |

## stampreceiver

Similar to stampboard but with modified pad dimensions for receiving a stampboard component.

<FootprintPreview footprints={["stampreceiver_left20_right20_bottom3_top2_w21mm_p2.54mm", "", "stampreceiver_left20_right20_bottom3_top2_w21mm_p2.54mm_innerhole"]} />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `w` | `"22.58mm"` | Board width |
| `h` | _calculated_ | Board height (calculated from number of pins if not specified) |
| `left` | `20` | Number of pins on left side |
| `right` | `20` | Number of pins on right side |
| `top` | `2` | Number of pins on top side |
| `bottom` | `2` | Number of pins on bottom side |
| `p` | `"2.54mm"` | Pin pitch |
| `pw` | `"1.6mm"` | Pin width |
| `pl` | `"3.2mm"` | Pin length |
| `innerhole` | `false` | Whether to include inner mounting holes |
| `innerholeedgedistance` | `"1.61mm"` | Distance of inner holes from edge |

## hc49

Standard HC49 crystal footprint.

<FootprintPreview footprint="hc49" />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `p` | `"4.88mm"` | Pin pitch |
| `id` | `"0.6mm"` | Inner diameter of plated holes |
| `od` | `"1.2mm"` | Outer diameter of plated holes |
| `w` | `"5.6mm"` | Package width |
| `h` | `"3.5mm"` | Package height |

## to92

TO-92 transistor package footprint, available in triangular or inline arrangements.

<FootprintPreview footprints={["to92", "to92_inline"]} />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `p` | `"1.27mm"` | Pin pitch |
| `id` | `"0.72mm"` | Inner diameter of plated holes |
| `od` | `"0.95mm"` | Outer diameter of plated holes |
| `w` | `"4.5mm"` | Package width |
| `h` | `"4.5mm"` | Package height |
| `arrangement` | `"triangular"` | Pin arrangement, either "triangular" or "inline" |

## to220

TO-220 package footprint with configurable number of pins.

<FootprintPreview footprints={["to220_2", "to220_3", "to220_4"]} />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `num_pins` | `3` | Number of pins (specify using format "to220_N") |
| `p` | `"5.0mm"` | Pin pitch |
| `id` | `"1.0mm"` | Inner diameter of plated holes |
| `od` | `"1.9mm"` | Outer diameter of plated holes |
| `w` | `"13mm"` | Package width |
| `h` | `"7mm"` | Package height |

## ssop

Shrink Small Outline Package (SSOP) footprint.

<FootprintPreview footprints={["ssop8", "ssop16"]} />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `num_pins` | `8` | Number of pins in the package |
| `w` | `"3.9mm"` | Overall package width |
| `p` | `"1.27mm"` | Pin pitch (center-to-center distance between adjacent pins) |
| `pw` | _calculated_ | Pin width (calculated from pitch if not specified) |
| `pl` | _calculated_ | Pin length (calculated from pin width if not specified) |

## sop8

8-pin Small Outline Package (SOP) footprint.

<FootprintPreview footprint="sop8" />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `num_pins` | `8` | Fixed at 8 pins |
| `w` | _inherited_ | Overall package width |
| `p` | _inherited_ | Pin pitch |
| `pl` | `"1.5mm"` | Pin length |
| `pw` | `"0.6mm"` | Pin width |

## qfp

Quad Flat Package (QFP) footprint with configurable number of pins.

<FootprintPreview footprints={["qfp32", "qfp44"]} />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `num_pins` | `32` | Total number of pins (must be divisible by 4) |
| `body_size` | `"7mm"` | Size of the package body (square) |
| `p` | `"0.8mm"` | Pin pitch (center-to-center distance between adjacent pins) |
| `pw` | `"0.25mm"` | Pin width |
| `pl` | `"0.6mm"` | Pin length (exposed pad length) |

## qfn

Quad Flat No-Lead (QFN) package footprint with configurable number of pins.

<FootprintPreview footprints={["qfn20", "qfn32"]} />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `num_pins` | `20` | Total number of pins (must be divisible by 4) |
| `body_size` | `"4mm"` | Size of the package body (square) |
| `p` | `"0.5mm"` | Pin pitch (center-to-center distance between adjacent pins) |
| `pw` | `"0.25mm"` | Pin width |
| `pl` | `"0.4mm"` | Pin length (exposed pad length) |

## sot23

Small Outline Transistor (SOT-23) footprint with 3 pins.

<FootprintPreview footprint="sot23" />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `num_pins` | `3` | Fixed at 3 pins |
| `body_size` | `"2.9mm"` | Size of the package body |
| `p` | `"0.95mm"` | Pin pitch |
| `pw` | `"0.4mm"` | Pin width |
| `pl` | `"0.6mm"` | Pin length |

## sot23_5

Small Outline Transistor (SOT-23-5) footprint with 5 pins.

<FootprintPreview footprint="sot23_5" />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `num_pins` | `5` | Fixed at 5 pins |
| `body_size` | `"2.9mm"` | Size of the package body |
| `p` | `"0.95mm"` | Pin pitch |
| `pw` | `"0.4mm"` | Pin width |
| `pl` | `"0.6mm"` | Pin length |

## sot223

Small Outline Transistor (SOT-223) footprint with 4 pins.

<FootprintPreview footprint="sot223" />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `num_pins` | `4` | Fixed at 4 pins |
| `body_size` | `"6.5mm"` | Size of the package body |
| `p` | `"2.3mm"` | Pin pitch |
| `pw` | `"0.7mm"` | Pin width |
| `pl` | `"0.8mm"` | Pin length |

## pinrow

Row of pins suitable for male or female pin headers. If `_male` or `_female`
is specified the 3d model will update accordingly.

<FootprintPreview footprint="pinrow4" />

Parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `num_pins` |  | Number of pins |
| `p` | `"2.3mm"` | Pin pitch |
| `id` | `"1mm"` | Inner diameter |
| `od` | `"1.5mm"` | Outer diameter |
| `male` | `true` | Male header |
| `female` | `false` | Female header |
</file>

<file path="docs/footprints/platedhole.mdx">
---
title: <platedhole />
description: >-
  The `<platedhole />` element is used to represent a plated through hole on a
  PCB.
---

## Overview

The `<platedhole />` element is used to represent a plated through hole on a PCB.


<CircuitPreview
  defaultView="pcb"
  code={`
  export default () => (
    <board width="10mm" height="10mm">
      <chip name="U1" footprint={
        <footprint>
          <platedhole
            pcbX="0mm"
            pcbY="0mm"
            shape="circle"
            holeDiameter="1mm"
            outerDiameter="2mm"
            portHints={["pin1"]}
          />
        </footprint>
      } />
    </board>
  )
  `}
/>

## Plated Hole Shapes

There are 3 types of plated holes:

- `circle` - A circular plated hole
- `oval` - An oval plated hole
- `pill` - A pill-shaped plated hole (rounded rectangle)

Each shape has different properties

## Properties

| Property      | Shape      | Description                                    |
| ------------- | ---------- | ---------------------------------------------- |
| holeDiameter  | circle     | The diameter of the inner hole                 |
| outerDiameter | circle     | The diameter of the outer copper pad           |
| innerWidth    | oval, pill | The width of the inner hole                    |
| innerHeight   | oval, pill | The height of the inner hole                   |
| outerWidth    | oval, pill | The width of the outer copper pad              |
| outerHeight   | oval, pill | The height of the outer copper pad             |
| portHints     | all        | Array of port names that this hole connects to |
| pcbX          | all        | X position of the hole center on the PCB       |
| pcbY          | all        | Y position of the hole center on the PCB       |
| name          | all        | Optional name identifier for the plated hole   |
</file>

<file path="docs/footprints/silkscreencircle.mdx">
---
title: <silkscreencircle />
---

## Overview

Silkscreen circles are often used to indicate "pin1" on a chip.


<CircuitPreview code={`
  export default () => (
    <group>
      <footprint>
        <silkscreencircle pcbX={0} pcbY={0} radius={1} />
      </footprint>
    </group>
  )
`} />
</file>

<file path="docs/footprints/silkscreenline.mdx">
---
title: <silkscreenline />
description: >-
  The `<silkscreenline />` element creates a line on the silkscreen layer within
  a footprint.
---

## Overview

The `<silkscreenline />` element creates a line on the silkscreen layer within a footprint.


<CircuitPreview
  defaultView="pcb"
  code={`
  export default () => (
    <board width="50mm" height="50mm">
      <footprint>
        <silkscreenline 
          x1="10mm" 
          y1="10mm" 
          x2="40mm" 
          y2="40mm"
          strokeWidth="0.1mm"
        />
      </footprint>
    </board>
  )
  `}
/>

## Properties

| Property | Description                                        |
|----------|----------------------------------------------------|
| `x1`       | X coordinate of the starting point                 |
| `y1`       | Y coordinate of the starting point                 |
| `x2`       | X coordinate of the ending point                   |
| `y2`       | Y coordinate of the ending point                   |
| `strokeWidth` | Stroke width of the line                         |

Feel free to experiment with different coordinate values to see how the silkscreen line is rendered.
</file>

<file path="docs/footprints/silkscreenpath.mdx">
---
title: <silkscreenpath />
description: >-
  The `<silkscreenpath />` element is used to define a custom drawn path on the
  silkscreen layer.
---

## Overview

The `<silkscreenpath />` element is used to define a custom drawn path on the silkscreen layer.
It supports the following properties:

- route: an array of coordinate objects (each with x and y) that define the path.
- strokeWidth: defines the width of the path's stroke.


<CircuitPreview
  defaultView="pcb"
  code={`
  export default () => (
    <board width="100mm" height="100mm">
      <chip name="U1" footprint={
        <footprint>
          <silkscreenpath 
            strokeWidth="0.5mm"
            route={[
                { x: "0mm", y: "20mm" },
                { x: "-1.53mm", y: "19.88mm" },
                { x: "-3.04mm", y: "19.52mm" },
                { x: "-4.50mm", y: "18.93mm" },
                { x: "-5.88mm", y: "18.09mm" },
                { x: "-7.16mm", y: "17.04mm" },
                { x: "-8.32mm", y: "15.78mm" },
                { x: "-9.33mm", y: "14.33mm" },
                { x: "-10.17mm", y: "12.72mm" },
                { x: "-10.82mm", y: "10.98mm" },
                { x: "-11.27mm", y: "9.13mm" },
                { x: "-11.52mm", y: "7.23mm" },
                { x: "-11.55mm", y: "5.29mm" },
                { x: "-11.37mm", y: "3.36mm" },
                { x: "-10.98mm", y: "1.47mm" },
                { x: "-10.39mm", y: "0mm" },
                
                { x: "10.39mm", y: "0mm" },
                { x: "39.61mm", y: "0mm" },
                
                { x: "39.61mm", y: "0mm" },
                { x: "41.08mm", y: "0.12mm" },
                { x: "42.59mm", y: "0.48mm" },
                { x: "44.05mm", y: "1.07mm" },
                { x: "45.43mm", y: "1.91mm" },
                { x: "46.71mm", y: "2.96mm" },
                { x: "47.87mm", y: "4.22mm" },
                { x: "48.88mm", y: "5.67mm" },
                { x: "49.72mm", y: "7.28mm" },
                { x: "50.37mm", y: "9.02mm" },
                { x: "50.82mm", y: "10.87mm" },
                { x: "51.07mm", y: "12.77mm" },
                { x: "51.10mm", y: "14.71mm" },
                { x: "50.92mm", y: "16.64mm" },
                { x: "50.53mm", y: "18.53mm" },
                { x: "49.94mm", y: "20mm" },
                
                { x: "49.94mm", y: "20mm" },
                { x: "0mm", y: "20mm" }
            ]}
          />
        </footprint>
      } pcbX={-15} />
    </board>
  )
  `}
/>

## Properties

| Property    | Type   | Description                                                          |
| ----------- | ------ | -------------------------------------------------------------------- |
| route       | Array  | An array of objects containing x and y coordinates to define a path. |
| strokeWidth | String | The width of the drawn path.                                         |

Feel free to experiment with different routes and strokeWidth values.
</file>

<file path="docs/footprints/silkscreenrect.mdx">
---
title: <silkscreenrect />
---

## Overview

Silkscreen rectangles can be used to encapsulate a rectangular area around a
chip


<CircuitPreview code={`
  export default () => (
    <group>
      <footprint>
        <silkscreenrect pcbX={0} pcbY={0} width={1} height={1} />
      </footprint>
    </group>
  )
`} />
</file>

<file path="docs/footprints/silkscreentext.mdx">
---
title: <silkscreentext />
description: >-
  The `<silkscreentext />` element is used to add text to the silkscreen layer
  within a PCB footprint.
---

## Overview

The `<silkscreentext />` element is used to add text to the silkscreen layer within a PCB footprint.


<CircuitPreview
  defaultView="pcb"
  code={`
  export default () => (
    <board width="10mm" height="10mm">
      <silkscreentext text="Hello, World!" fontSize="1mm" />
    </board>
  )`}
/>



## Properties

| Property        | Type   | Description                                                                                                   |
|-----------------|--------|---------------------------------------------------------------------------------------------------------------|
| `text`            | string | The text string to display.                                                                                   |
| `anchorAlignment` | enum   | Alignment of the text. One of "center", "top_left", "top_right", "bottom_left", "bottom_right". Defaults to "center". |
| `font`            | enum   | Optional. The font type, e.g. `"tscircuit2024"`.                                                                |
| `fontSize`        | length | Optional. The size of the font.                                                                               |
</file>

<file path="docs/footprints/smtpad.mdx">
---
title: <smtpad />
description: The `<smtpad />` element is used to represent a surface mount pad.
---

## Overview

The `<smtpad />` element is used to represent a surface mount pad.


<CircuitPreview
  defaultView="schematic"
  code={`
  export default () => (
    <board width="10mm" height="10mm">
      <chip name="U1" footprint={
        <footprint>
          <smtpad
            pcbX="0mm"
            pcbY="0mm"
            layer="top"
            shape="rect"
            width="5mm"
            height="5mm"
            portHints={["pin1"]}
          />
        </footprint>
      } />
    </board>
  )
  `}
/>

## SMT Pad Shapes

There are 3 main types of smtpads:

- `rect` - A rectangular pad
- `circle` - A circular pad
- `pill` - A pill-shaped pad

Each smtpad shape has different properties

## Properties

| Property    | Shape        | Description                                                    |
| ----------- | ------------ | -------------------------------------------------------------- |
| width       | rect, pill   | The width of the pad                                           |
| height      | rect, pill   | The height of the pad                                          |
| radius      | circle, pill | The radius of the pad (for circle) or corner radius (for pill) |
| ccwRotation | rect         | Counter-clockwise rotation angle in degrees                    |
| portHints   | all          | Array of port names that this pad connects to                  |
| pcbX        | all          | X position of the pad center on the PCB                        |
| pcbY        | all          | Y position of the pad center on the PCB                        |
| layer       | all          | Which layer the pad is on ("top" or "bottom")                  |
</file>

<file path="docs/guides/importing-modules-and-chips/importing-from-circuit-json.mdx">
---
title: Importing from Circuit JSON
description: You can import Circuit JSON into tscircuit components.
---

## Overview

You can import [Circuit JSON](https://github.com/tscircuit/circuit-json) into
tscircuit components.

Circuit JSON is normally an output of tscircuit code, but sometimes it can
be a helpful intermediate format so is used to generate tscircuit code.

## via Web

:::note
TODO we're still writing this section!
:::

## via CLI

:::note
TODO we're still writing this section!
:::

## Programmatically Converting Circuit JSON to tscircuit code

You can use the [circuit-json-to-tscircuit](https://github.com/tscircuit/circuit-json-to-tscircuit)
module to programmatically convert circuit json into tscircuit code.
</file>

<file path="docs/guides/importing-modules-and-chips/importing-from-jlcpcb.mdx">
---
title: Importing from JLCPCB
sidebar_position: 2
description: JLCPCB has a massive component catalog of 3d models and footprints.
---

import YouTubeEmbed from '../../../src/components/YouTubeEmbed';

## Overview

JLCPCB has a massive component catalog of 3d models and footprints.

## Web Import

You can import JLCPCB components on [tscircuit.com](https://tscircuit.com). After
importing the snippet, it'll be given a package name like `@tsci/YOUR_NAME.CHIP_NAME`
and available for import from the tscircuit registry.

<figure>
  <img src="/img/tscircuit-new-import-part.png" />
  <figcaption>Step 1: Go to `tscircuit.com` and press the "new" button</figcaption>
</figure>

<figure>
  <img src="/img/tscircuit-import-jlcpcb-button.png" />
  <figcaption>Step 2: Click "Import JLCPCB Component"</figcaption>
</figure>

<figure>
  <img src="/img/tscircuit-jlcpcb-dialog.png" />
  <figcaption>Step 3: Paste in the JLCPCB Part Number</figcaption>
</figure>

<figure>
  <img src="/img/jlcpcb-part-number.png" />
  <figcaption>You can find the JLCPCB Part Number on JLCPCB's website</figcaption>
</figure>

<figure>
  <img src="/img/example-imported-jlcpcb-component.png" />
  <figcaption>An example of an imported JLCPCB component</figcaption>
</figure>

After your component has been added to tscircuit, you can import it as a
`@tsci/*` import like this:

```tsx
import { ESP32_WROOM_32DC } from "@tsci/AnasSarkiz.ESP32_WROOM_32DC"

export default () => (
  <board width="10mm" height="10mm">
    <ESP32_WROOM_32DC />
  </board>
)
```


## CLI Import

To import JLCPCB components using the tsci dev environment, follow these steps:

1. Run `tsci dev` to start the development server
2. In the tsci dev environment, navigate to "File -> Import"

<YouTubeEmbed youtubeId="tFCGAa81KUs" />

After importing, you can use the component in your circuit like this:

```tsx
import { ComponentName } from "@tsci/imported-component"

export default () => (
  <board width="10mm" height="10mm">
    <ComponentName />
  </board>
)
```
</file>

<file path="docs/guides/importing-modules-and-chips/importing-from-kicad.md">
---
title: Importing from KiCad
sidebar_position: 3
description: You can import KiCad components or projects into tscircuit.
---

## Overview

You can import KiCad components or projects into tscircuit.

To import from KiCad, you should understand the different file formats KiCad
uses:

- Files for KiCad components
  - `kicad_mod` - PCB footprint file for a single component
  - `kicad_sym` - Schematic symbol file for a single component
- Files for KiCad projects
  - `kicad_pro` - KiCad project file
  - `kicad_pcb` - KiCad PCB board file
  - `kicad_sch` - KiCad Schematic board file

:::info
We're still building KiCad import directly into tscircuit.com, stay tuned for
when that's available!
:::

## Importing KiCad Components

Currently the easiest way to import KiCad components is to go to [kicad-component.tscircuit.com](https://kicad-component.tscircuit.com/)
and upload your `kicad_mod` and/or `kicad_sym` file.

### Importing KiCad Components using the CLI

Using tscircuit's [open-source KiCad component converter](https://github.com/tscircuit/kicad-component-converter),
we can convert KiCad files on the command line.

First install the component converter:

```bash
npm install -g kicad-mod-converter
```

Next, run the following command to convert your KiCad files:

```bash
# Convert a directory ./my-footprints.pretty to a tscircuit project
kicad-mod-converter convert-kicad-directory --input-dir ./my-footprints.pretty --output-dir ./my-tscircuit-footprints
```

### Importing KiCad Components Programmatically

```bash
bun add kicad-mod-converter
```

```tsx
import { parseKicadModToCircuitJson } from "kicad-component-converter"
import { readFileSync } from "node:fs"

const fileContent = readFileSync("SW_SP3T_PCM13.kicad_mod")
const circuitJson = await parseKicadModToCircuitJson(fileContent)
/* [
 *  {
 *    "type": "pcb_smtpad",
 *    "x": 0.345,
 *    ...
 */
```

[Circuit JSON](https://github.com/tscircuit/circuit-json) can then be converted
into regular tscircuit modules using [circuit-json-to-tscircuit](https://github.com/tscircuit/circuit-json-to-tscircuit)
</file>

<file path="docs/guides/automatic-layout.mdx">
---
title: Automatic Layout
---

:::warning
Automatic layout is in beta! We're changing and improving the layout algorithms,
if it doesn't work for you stay tuned! Many changes are on the way!
:::

You can automatically lay out schematics and PCBs using the `schAutoLayoutEnabled` and
`pcbAutoLayoutEnabled` props.

## Automatic Schematic Layout

Here's an example of a Pico-driven nine key keyboard with `schAutoLayoutEnabled`:



<CircuitPreview
  defaultView="schematic"
  code={`

import { SmdDiode } from "@tsci/seveibar.SmdDiode"
import { Key } from "@tsci/seveibar.Key"
import { Pico2 } from "@tsci/seveibar.pico2"

const rowToMicroPin = {
  0: "GP0",
  1: "GP1",
  2: "GP10",
}
const colToMicroPin = {
  0: "GP19",
  1: "GP17",
  2: "GP5",
}

export default () => (
  <board width="100mm" height="100mm" schTraceAutoLabelEnabled schAutoLayoutEnabled>
    <Pico2 name="U1" pcbX={-30} />
    {grid({ sizeX: 3, sizeY: 3, pitch: 19.05, offset: { x: 20, y: 0 } }).map(
      ({ x, y, row, col }, index) => {
        const schOffX = 5 + x/6
        const schOffY = -y / 8
        return (
          <group key={\`Kgroup\${index}\`}>
            <Key pcbX={x} pcbY={y} schX={schOffX} schY={schOffY + 0.5} name={\`K\${index + 1}\`} />
            <SmdDiode
              pcbX={x}
              pcbY={y - 13}
              layer="bottom"
              name={\`D\${index + 1}\`}
            />
            <trace from={\`.D\${index + 1} .pin1\`} to={\`.K\${index + 1} .pin1\`} />
            <trace
              from={\`.D\${index + 1} .pin2\`}
              to={\`.U1 .\${rowToMicroPin[row]}\`}
            />
            <trace
              from={\`.K\${index + 1} .pin2\`}
              to={\`.U1 .\${colToMicroPin[col]}\`}
            />
          </group>
        )
      }
    )}
  </board>
)

function grid(opts: {
  sizeX: number
  sizeY: number
  pitch: number
  offset?: { x: number; y: number }
}): Array<{ x: number; y: number; row: number; col: number }> {
  const { sizeX, sizeY, pitch, offset = { x: 0, y: 0 } } = opts
  const points: Array<{ x: number; y: number; row: number; col: number }> = []
  const startX = (-(sizeX - 1) * pitch) / 2
  const startY = (-(sizeY - 1) * pitch) / 2
  for (let row = 0; row < sizeY; row++) {
    for (let col = 0; col < sizeX; col++) {
      points.push({
        x: startX + col * pitch + offset.x,
        y: startY + row * pitch + offset.y,
        row,
        col,
      })
    }
  }
  return points
}

`}

/>

## Automatic PCB Layout

:::warning
PCB Autolayout is not currently available but coming soon! If you're interested
in PCB Autolayout you should [upvote this issue on GitHub](https://github.com/tscircuit/tscircuit/issues/511)
:::
</file>

<file path="docs/guides/configuring-chips.mdx">
---
title: Configuring Chips
sidebar_position: 1.5
---

import ChipPage from "../elements/chip.mdx"

<ChipPage />
</file>

<file path="docs/guides/displaying-circuit-json-on-a-webpage.mdx">
---
title: Displaying Circuit JSON on a Webpage
---

[Circuit JSON](https://github.com/tscircuit/circuit-json) is a universal
intermediary format for representing an electronic circuit. It contains PCB,
Schematic, 3D, Bill of Materials and simulation information.

tscircuit code always converts into Circuit JSON, which can be displayed in
any of our React components

:::tip
You can also upload your Circuit JSON to [circuitjson.com](https://circuitjson.com)
for a quick preview!
:::


![Circuit JSON Pipeline](../../static/img/circuit-json-explain.png)

## React: Display all available previews with `<CircuitJsonPreview />`

The `<CircuitJsonPreview />` component is a simple way to display all available
previews for a Circuit JSON array. You can use it by installing the `@tscircuit/runframe`
package and importing it into your `React` project.

```tsx
import { CircuitJsonPreview } from "@tscircuit/runframe"
import { renderToCircuitJson } from "lib/dev/render-to-circuit-json"

export default () => (
  <CircuitJsonPreview
    circuitJson={renderToCircuitJson(
      <board width="10mm" height="10mm">
        <resistor name="R1" resistance="1k" footprint="0402" />
      </board>,
    )}
  />
)
```

You should see something like this:

![RunFrame Preview](../../static/img/runframe-example.png)

For more examples and usage, check out the [runframe repo](https://github.com/tscircuit/runframe)
and the [examples directory](https://github.com/tscircuit/runframe/tree/main/examples)!

:::info
Have tscircuit code and want to skip converting to Circuit JSON? Try using the
`<RunFrame />` component directly to build your circuit in the browser!
:::

### React: Running tscircuit code in the browser (no Circuit JSON needed!)

The `<RunFrame />` component is a simple way to run tscircuit code in the browser.
RunFrame loads the tscircuit runtime (and all the dependencies to build Typescript
code) into a WebWorker and runs the code in the background.

To use RunFrame, you must provide a `fsMap` object. This object maps file paths
to file contents. Files inside this "filesystem map" can import each other, this
is super useful when you have many files to import such as a `manual-edits.json`
file!

```tsx
import { RunFrame } from "@tscircuit/runframe"

export default () => (
  <RunFrame
    fsMap={{
      "main.tsx":
`
circuit.add(
  <board width="10mm" height="10mm">
    <resistor name="R1" resistance="1k" footprint="0402" />
    <capacitor name="C1" capacitance="1uF" footprint="0603" pcbX={4} />
    <trace from=".R1 .pin1" to=".C1 .pin1" />
  </board>
)
`,
    }}
    entrypoint="main.tsx"
  />
)
```

You can see different examples of how RunFrame looks for different circuits
on the [RunFrame online examples page](https://runframe.vercel.app/)

`<RunFrame />` automatically handles imports from the tscircuit registry



## Displaying Circuit JSON without React

Are you interested in this? Please [upvote this issue](https://github.com/tscircuit/tscircuit/issues/508)
so we can prioritize it!
</file>

<file path="docs/guides/essential-elements.mdx">
---
title: Essential Elements
sidebar_position: 1
description: >-
  There are some essential elements you'll need for almost every circuit you make,
  this doc gives a brief overview of each of them so you can jump right in and
  get started building electronics!
---


## Overview

There are some essential elements you'll need for almost every circuit you make,
this doc gives a brief overview of each of them so you can jump right in and
get started building electronics!

| Element                                      | Description                                                                                                               |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| [`<board />`](../elements/board.mdx)         | The root element of a circuit, defines the size of the board and settings like the autorouting method that should be used |
| [`<chip />`](../elements/chip.mdx)           | A packaged integrated circuit (IC).                                                                                       |
| [`<trace />`](../elements/trace.mdx)         | Represents a connection between different chips.                                                                          |
| [`<led />`](../elements/led.mdx)             | Light emitting diode, a small light often used to represent power or status indicators                                    |
| [`<resistor />`](../elements/resistor.mdx)   | Resists the flow of electrical current.                                                                                   |
| [`<capacitor />`](../elements/capacitor.mdx) | Stores electrical charge. Often used to smooth out voltage fluctuations.                                                  |
| [`<diode />`](../elements/diode.mdx)         | Allows current to flow in one direction.                                                                                  |

## The Essential Elements

### [`<board />`](../elements/board.mdx)

The `<board />` element is the root container for your circuit, similar to how `<body />` works in HTML. Every circuit needs a board! You can customize the size using `width` and `height` props, or even create custom board outlines for non-rectangular shapes.

<CircuitPreview defaultView="pcb" code={`

export default () => (
    <board width="10mm" height="10mm">
      <resistor resistance="1k" footprint="0402" name="R1" />
    </board>
)`
} />

### [`<chip />`](../elements/chip.mdx)

The `<chip />` element is the most versatile component in tscircuit - it can represent virtually any packaged electronic component. You specify a footprint and pin labels, and can customize how it appears in both schematic and PCB views. Here's a simple example:

<CircuitPreview defaultView="schematic" code={`
export default () => (
    <board width="10mm" height="10mm">
      <chip
        name="U1" 
        footprint="soic8"
        pinLabels={{
          pin1: "VCC",
          pin2: "DISCH", 
          pin3: "THRES",
          pin4: "CTRL",
          pin5: "GND",
          pin6: "TRIG",
          pin7: "OUT",
          pin8: "RESET"
        }}
      />
    </board>
)`} />

You can control pin arrangements, add custom footprints, specify internally connected pins, and more. The `<chip />` element is commonly used for ICs, connectors, buttons, and other discrete components.
</file>

<file path="docs/guides/platform-configuration.md">
---
title: Platform Configuration
description: >-
  The Platform Configuration allows you to change tscircuit behavior to best
  suit the platform the tscircuit code is running on.
---

## Overview

The Platform Configuration allows you to change tscircuit behavior to best suit
the platform the tscircuit code is running on.

Some use cases:

- Organizations may want to customize the cloud autorouter to avoid sending sensitive designs outside your company
- Organizations may want to use their own internal registry for importing circuits instead of [tscircuit.com](https://tscircuit.com)
- For [autorouting.com](https://autorouting.com), we configure the platform to not perform any autorouting

## Customizing the Platform

All of the following features of the platform can be configured:

- **partsEngine** - The engine used to automatically find parts matching component specifications
- **registryApiUrl** - The registry to use, defaults to `https://registry-api.tscircuit.com`. See [Registry API](../web-apis/the-registry-api.md) for more details
- **cloudAutorouterUrl** - The cloud autorouter to use, defaults to a tscircuit cloud service that uses freerouting
- Disable specific circuit outputs to optimize build times, such as disabling autorouting

### The Default Platform

The tscircuit default platform configuration sources parts from multiple vendors
and uses the tscircuit backend for autorouting and `@tsci/*` imports.

Current vendors used for automatic part sourcing:

- [JLCPCB](https://jlcpcb.com)
- Digikey (coming soon!)
- Mouser (coming soon!)

For each vendor, tscircuit populates multiple available chips. This means even
if tscircuit finds parts for a vendor, you don't have to use that vendor!

## Using your Platform

:::info
Want more platform features? Tell us about your use case in [this GitHub Discussion!](https://github.com/orgs/tscircuit/discussions/514)
:::

When you initialize a `RootCircuit`, you can provide the platform configuration
as the `{ platform }` parameter:

```tsx
import { RootCircuit } from "@tscircuit/core"

const circuit = new RootCircuit({
  platform: {
    registryApiUrl: "https://my-tscircuit-registry.mycompany.com",
  },
})
```

This can also be provided to modules like `@tscircuit/eval` to evaluate tscircuit
code:

```tsx
import { CircuitRunner } from "@tscircuit/eval-webworker"
import myPartsEngine from "./my-parts-engine"

const circuitRunner = new CircuitRunner({
  platform: {
    partsEngine: myPartsEngine,
  },
})

await circuitRunner.execute(`
circuit.add(
  <board width="10mm" height="10mm">
    <led name="LED1" footprint="0603" color="red" />
  </board>
)`)

await circuitRunner.renderUntilSettled()

const circuitJson = await circuitRunner.getCircuitJson()
```

:::info
Interested in running the entire tscircuit platform privately inside your company?
We're happy to help! Reach out to **enterprise@tscircuit.com**
:::
</file>

<file path="docs/guides/port-and-net-selectors.md">
---
title: Port and Net Selectors
---

Selectors are a string used to reference a port, net or any component. They're most
commonly used in traces like this:

```tsx
<trace from=".R1 > .pin1" to=".C1 > .pos" />
```

However they can also be used anywhere where a port is referenced, for example to indicate what a capacitor should decouple or a resistor should pullup to:

```tsx
<resistor pullupFor=".U1 > .GPIO1" pullupTo="net.VCC" />

<capactor decouplingFor=".U1 .VCC" decouplingTo="net.GND" />
```

Selectors use the same semantics as CSS selectors:

- `>` means "direct child"
- `.` means "name" (in CSS, this can be any class name, but in tscircuit components are limited to a single name)
- `.U1` means "something with the name `U1`"
- `net.GND` means "a net with the name `GND`"

## Selectors don't cross subcircuit boundaries unless told to

When a selector is specified, it's resolved relative to the
subcircuit of the component where it's specified.

This means within a subcircuit the selector `.U1` will match any component with the name `U1` anywhere in that subcircuit without going into other subcircuits.

Subcircuits can be nested and have names, so you can use this
to reference components in nested subcircuits:

```tsx
<subcircuit>
  <subcircuit name="S1">
    <resistor name="R1" />
  </subcircuit>
  <capacitor name="C1" />

  {/* We must include ".S1" in the selector to select the resistor from the inner subcircuit */}
  <trace from=".S1 .R1 .pin1" to=".C1 .pos" />
</subcircuit>
```

Because subcircuits are isolated from each other, you can
re-use reference designators in different subcircuits (globally
unique reference designators are generated on export)
</file>

<file path="docs/guides/programmatically-building-circuits.md">
---
title: Programmatically Building Circuits
---

This guide is about using tscircuit inside of scripts, APIs or inside the browser. Maybe you want to create a website that allows your users drag'n'drop to create custom electronics and turn their designs into real circuits automatically.

For most users, there is no need to programmatically build circuits, you can use the [command line](../command-line/tsci-dev.md) or the [online editor](../intro/quickstart-web.md) to build and export your circuits into any supported format.

If you're not using Typescript or prefer a "zero-installation" setup, you can fully build your circuits with complex parameters using the [Registry API](../web-apis/the-registry-api.md)

## Using `@tscircuit/core` directly

`@tscircuit/core` is the core library for tscircuit, it converts React code into [Circuit JSON](https://github.com/tscircuit/circuit-json), a universally intermediary format that represents an electronic device.

Here's an example of how to use `@tscircuit/core` directly to build a circuit into Circuit JSON:

```tsx
import { RootCircuit } from "@tscircuit/core"

const circuit = new RootCircuit()

circuit.add(
  <board width="10mm" height="10mm">
    <resistor resistance="1k" footprint="0402" name="R1" schX={3} pcbX={3} />
    <capacitor
      capacitance="1000pF"
      footprint="0402"
      name="C1"
      schX={-3}
      pcbX={-3}
    />
    <trace from=".R1 > .pin1" to=".C1 > .pin1" />
  </board>
)

await circuit.renderUntilSettled()

console.log(circuit.getCircuitJson())
```

This will output a long [Circuit JSON](https://github.com/tscircuit/circuit-json) array that you can convert into many
other formats or display directly inside a [CircuitJsonPreview](./displaying-circuit-json-on-a-webpage.mdx) component.

## Evaluating Typescript Circuits

`@tscircuit/eval` can be used to evaluate Typescript/React code and
automatically import modules from the tscircuit registry.

```tsx
import { CircuitRunner } from "@tscircuit/eval"

const circuitRunner = new CircuitRunner()

await circuitRunner.execute(`
import { RedLed } from "@tsci/seveibar.red-led"

circuit.add(
  <board width="10mm" height="10mm">
    <RedLed name="LED1" />
  </board>
)`)

await circuitRunner.renderUntilSettled()

const circuitJson = await circuitRunner.getCircuitJson()

// Display or convert the circuit json to any other format!
```

### Evaluating tscircuit inside a web worker

```tsx
import { createCircuitWebWorker } from "@tscircuit/eval/webworker"

const circuitWebWorker = createCircuitWebWorker()

await circuitWebWorker.execute(`
import { RedLed } from "@tsci/seveibar.red-led"

circuit.add(
  <board width="10mm" height="10mm">
    <RedLed />
  </board>
)
`)

await circuitWebWorker.renderUntilSettled()

const circuitJson = await circuitWebWorker.getCircuitJson()
```

## Converting Circuit JSON to other formats

You can convert [Circuit JSON](https://github.com/tscircuit/circuit-json) to many
other formats:

- [Gerber files](https://github.com/tscircuit/circuit-json-to-gerber)
- [Specctra DSN Autorouting files](https://github.com/tscircuit/dsn-converter)
- [Pick'n'Place Files](https://github.com/tscircuit/circuit-json-to-pnp-csv)
- [PCB and Schematic SVGs](https://github.com/tscircuit/circuit-to-svg)
- [Bill of Materials](https://github.com/tscircuit/circuit-json-to-bom-csv)
- [SPICE netlists and simulations](https://github.com/tscircuit/circuit-json-to-spice)
</file>

<file path="docs/guides/running-tscircuit-inside-an-iframe.mdx">
---
title: Running tscircuit inside an iframe
description: >-
  tscircuit can be evaluated inside an iframe. This makes it easy to embed
  snippets on a webpage without complex build systems.
---

## Overview

tscircuit can be evaluated inside an iframe. This makes it easy to embed
snippets on a webpage without complex build systems.

Here's an example of an iframe running a tscircuit snippet:

import { TscircuitIframe } from "../../src/components/TscircuitIframe"

<TscircuitIframe
  fsMap={{
    "main.tsx": `circuit.add(
      <board width="10mm" height="10mm">
        <resistor name="R1" footprint="0402" resistance="1k" />
      </board>
    )`,
  }}
  entrypoint="main.tsx"
/>

## Running tscircuit inside an iframe

To run tscircuit inside an iframe, perform the following steps:

1. Add an iframe that points to `"https://runframe.tscircuit.com/iframe.html"`
2. Listen for the `runframe_ready_to_receive` message from the iframe
3. Send the code you want to run to the iframe via `postMessage`

Here's a fully working example:

```html
<!DOCTYPE html>
<html>
  <head>
    <title>RunFrame Host</title>
  </head>
  <body>
    <iframe
      id="runframe"
      src="https://runframe.tscircuit.com/iframe.html"
      style="width: 100%; height: 600px; border: none;"
    ></iframe>

    <script>
      const iframe = document.getElementById("runframe")

      // Listen for ready message from iframe
      window.addEventListener("message", (event) => {
        if (event.data?.runframe_type === "runframe_ready_to_receive") {
          // Send circuit configuration
          iframe.contentWindow.postMessage(
            {
              runframe_type: "runframe_props_changed",
              runframe_props: {
                fsMap: {
                  "main.tsx": `circuit.add(<resistor resistance="1k" />)`,
                },
                entrypoint: "main.tsx",
              },
            },
            "*"
          )
        }
      })
    </script>
  </body>
</html>
```

## React iframe wrapper for tscircuit

An iframe wrapper is available to simplify the process of running tscircuit
inside an iframe. To use it, add the `@tscircuit/runframe` package to your
project and use the [`RunFrameWithIframe` component](https://github.com/tscircuit/runframe/blob/main/lib/components/RunFrameWithIframe/RunFrameWithIframe.tsx) like so:

```tsx
import { RunFrameWithIframe } from "@tscircuit/runframe/iframe"

export default () => (
  <RunFrameWithIframe
    fsMap={{
      "main.tsx": `circuit.add(<resistor resistance="1k" />)`,
    }}
    entrypoint="main.tsx"
  />
)
```
</file>

<file path="docs/guides/understanding-fabrication-files.md">
---
title: Understanding Fabrication Files
description: >-
  Fabrication files are files that can be uploaded to a fabricator or turn-key
  manufacturer to get an entire circuit board made. tscircuit includes three
  main types of files inside our fabrication files `zip`:
---

## Overview

Fabrication files are files that can be uploaded to a fabricator or turn-key
manufacturer to get an entire circuit board made. tscircuit includes three
main types of files inside our fabrication files `zip`:

- **Gerbers** These represent each copper layer of the PCB. We also include
  drilling holes and board cutouts
- **Bill Of Materials CSV**
- **Pick'n'Place CSV** These

## How to get fabrication files

### Web

On the web, you can just hit "Download" or "Export" on any circuit, then hit "Fabrication Files"

<figure>
<img src="/img/online-editor-download.png" alt="Online Editor Download Button" />
<figcaption>Downloading fabrication files from the online editor</figcaption>
</figure>

### CLI

The easiest way to get fabrication files is to go to `File > Export > Fabrication Files`
in the web browser after doing `tsci dev`

<figure>
<img src="/img/tsci-dev-export.png" alt="CLI Export Button" />
<figcaption>Downloading fabrication files from the online editor</figcaption>
</figure>

## What's inside the zip file?

The zip file contains three types of files:

- `gerbers` Describes the copper layers of your PCB
- `bill-of-materials.csv` This is a csv file with the components in the circuit and their
  quantity.
- `pick-n-place.csv` This is a csv file with the components in the circuit and their
  position on the board.

<figure>
<img className="img-rounded" src="/img/jlcpcb-upload.png" />
<figcaption>Many fabricators allow you to directly drop fabrication files on their website!</figcaption>
</figure>
</file>

<file path="docs/guides/using-tscircuit-without-react.mdx">
---
title: Using tscircuit without React
---

{/* tscircuit uses React by default for strong guarantees about how
components are imported and used, but you can also use tscircuit
without react. */}

:::tip
If you're interested in using tscircuit without react, please let us know
by [upvoting this issue!](https://github.com/tscircuit/tscircuit/issues/508)
:::

:::info
Are you interested in using tscircuit inside an iframe? Check out [this article](./running-tscircuit-inside-an-iframe.mdx)
:::
</file>

<file path="docs/intro/installation.md">
---
title: Installation
sidebar_position: 2
---

## Dependencies

To use tscircuit, you'll need to have [npm](https://npmjs.com) or [bun](https://bun.sh) installed. We recommend using [bun](https://bun.sh) for its speed and ease of use.

## Installing tscircuit

To install tscircuit's command line tool, just run:

```bash
npm install -g tscircuit

# or

bun install --global tscircuit
```

This will install a `tsci` command globally!

:::info
If you're using [tscircuit online](https://tscircuit.com), you can skip installation. tscircuit is fully-featured and usable online!
:::

You can test it out by running `tsci --help`!

```bash
tsci --help

Usage: tsci [options] [command]

CLI for developing tscircuit snippets

# Options:
#   -V, --version            output the version number
#   -h, --help               display help for command

# Commands:
#   init                     Initialize a new TSCircuit project in the current directory
#   dev [options] [file]     Start development server for a snippet
#   clone <snippet>          Clone a snippet from the registry
#   auth                     Login/logout
#   login                    Login to tscircuit registry
#   config                   Manage tscircuit CLI configuration
#   export [options] <file>  Export tscircuit code to various formats
#   help [command]           display help for command
```

You can also run `tsci` without any arguments to start the interactive CLI.

```bash
tsci

# ? Choose command ›
# ❯   tsci init - Initialize a new TSCircuit project in the current directory
#     tsci dev - Start development server for a snippet
#     tsci clone - Clone a snippet from the registry
#     tsci auth - Login/logout
#     tsci login - Login to tscircuit registry
#     tsci config - Manage tscircuit CLI configuration
#     tsci export - Export tscircuit code to various formats
```

### Creating a new project

The easiest way to create a template project is to use `tsci init` inside a project directory.

```bash
mkdir my-project

cd my-project

tsci init
```

This will bootstrap a fresh tscircuit project! Read more about
starting the development server and exporting files in our
[Quickstart CLI Guide](./quickstart-cli.md).

## Installing `tscircuit` per project

You can install `tscircuit` on a per-project basis by installing it as a dev dependency.

```bash
npm add -D tscircuit

# or

bun add -D tscircuit
```

## TypeScript Configuration

If TypeScript can't find the tscircuit types in your project, add the `types` field to your `tsconfig.json`:

```json
{
  "compilerOptions": {
    "types": ["tscircuit"]
  }
}
```

## Next Steps

Now that you've installed tscircuit, you can start developing your first electronic device!

- [Quickstart CLI Guide](./quickstart-cli.md)
- [Understanding essential tscircuit elements](../guides/essential-elements.mdx)
- [What are electronics made of?](../building-electronics/what-are-electronics-made-of.mdx)
</file>

<file path="docs/intro/quickstart-web.md">
---
title: Quickstart Web
sidebar_position: 3
---

You can use tscircuit online without installing anything on [tscircuit.com](https://tscircuit.com)!

## Using the Online Editor

The [tscircuit online editor](https://tscircuit.com/editor) is a full Typescript editor with syntax highlighting, autocomplete, type-checking and tools for importing snippets and configuring chips.

There are two types of projects you can create in the online editor.

- **board**: a fully-functional electronic device that you can order
- **module**: a reusable component, usually a specific chip or subcircuit, that you can use across many boards or to break up a complex board into smaller, more manageable pieces.

To get started, let's create a simple board.

You can use the "New" button on [tscircuit.com](https://tscircuit.com) and select
"board" to open the editor with a blank board:

<img className="img-rounded img-400" src="/img/new-board.png" />

The editor will open with a template board that looks like this:

<img className="img-rounded img-400" src="/img/editor-with-template-board-3d.png" />

You can now edit the board by adding or removing elements! Check out the
[essential elements guide](../guides/essential-elements.mdx) to learn more about
the available elements. If you've already got an idea of what you want to build,
try breaking down the problem into modules using our [designing electronics from scratch guide](../building-electronics/designing-electronics-from-scratch.md)

After you make a change, click the "Run" button to see your changes applied. You
can use the PCB, Schematic, and 3D views to make sure everything is correctly
aligned.

When you're ready to manufacture your board, click the "Download" button to
download [fabrication files.](../guides/understanding-fabrication-files.md)

<img className="img-rounded img-400" src="/img/online-editor-download.png" />

When you're ready to order your board, check out the [ordering prototypes guide](../building-electronics/ordering-prototypes.mdx). You can
electronics fully assembled and ready to use from the many services that accept
our standard fabrication files.

## Using the AI Assistant

Our AI assistant is available in beta but is undergoing a big overhaul. We'll update this section when we're happy with it!
</file>

<file path="docs/intro/what-is-tscircuit.mdx">
---
title: What is tscircuit?
slug: /
sidebar_position: 1
---

import YouTubeEmbed from '../../src/components/YouTubeEmbed';

tscircuit is an open-source React/Typescript electronics toolchain and ecosystem
for creating, previewing, simulating and manufacturing Printed Circuit Boards
(PCBs).

React and Typescript are standard tools that revolutionized the web development
ecosystem. tscircuit combines the powerful static analysis of Typescript with
the modular component system of React to make developing electronics faster,
easier and more automated. To generate tscircuit with AI chat, check out our
[AI context](../advanced/ai-context.mdx)

<YouTubeEmbed youtubeId="HAd5_ZJgg50" />

Here's an example of a basic tscircuit electronic device, it's the USB
flashlight that we make in [this tutorial](../tutorials/building-a-simple-usb-flashlight.mdx).


<CircuitPreview defaultView="3d" code={`
import { usePushButton } from "@tsci/seveibar.push-button"
import { useUsbC } from "@tsci/seveibar.smd-usb-c"

export default () => {
  const USBCPort = useUsbC("USBC")
  const Button = usePushButton("SW1")
  return (
    <board width="12mm" height="30mm">
      <USBCPort
        GND1="net.GND"
        GND2="net.GND"
        VBUS1="net.VBUS"
        VBUS2="net.VBUS"
        pcbY={-10}
        schX={-4}
      />
      <led name="LED" color="red" footprint="0603" pcbY={12} schY={2} />
      <Button pcbY={0} pin2=".R1 > .pos" pin3="net.VBUS" schY={-2} />
      <resistor name="R1" footprint="0603" resistance="1k" pcbY={7} />
      <trace from=".R1 .neg" to=".LED .pos" />
      <trace from=".LED .neg" to="net.GND" />
    </board>
  )
}
`} />

This small snippet of code helps demonstrate the power of tscircuit. From those
40 lines, we were able to create a full PCB, Schematic and 3D preview. Not only
that, but we can export this circuit to [Fabrication Files](../guides/understanding-fabrication-files)
and get it fabricated and assembled. In fact we did!

import usbcflashlight from "@site/static/img/usbcflashlight_20250123_1816894.jpg"

<div style={{ display: "flex", justifyContent: "center", marginBottom: 18 }}>
<img style={{maxWidth: 400}} src={usbcflashlight} alt="USB Flashlight PCB After Manufacturing" />
</div>

It may not seem like much, but tscircuit just handled a _lot_ of work for us!

- Automatic Part Selection and Bill of Materials Generation
- Autorouting
- Schematic and PCB Layout
- 3D Model Generation
- Fabrication File Generation

...and it ran completely in our browser!

tscircuit isn't limited to simple circuits like this. You can keep adding
elements, creating modules and combining them to create more and more complex
circuits. Here's an example of a [simple 3x3 macrokeypad based on the PICO2!](https://tscircuit.com/seveibar/nine-key-keyboard)


<CircuitPreview code={`
import NineKeyKeyboard from "@tsci/seveibar.nine-key-keyboard"

export default () => <NineKeyKeyboard />
`} />

We ordered this one too!

import macrokeypad from "@site/static/img/macrokeypad.png"

<div style={{ display: "flex", justifyContent: "center", marginBottom: 24 }}>
<img style={{maxHeight: 400}} src={macrokeypad} alt="3x3 Macrokeypad" />
</div>

Depending on your experience level with electronics, you may want to get started
with any of the following resources:

- [Learn about the Essential tscircuit Elements](../guides/essential-elements)
- [How do I design an electronic device from scratch with tscircuit?](../building-electronics/designing-electronics-from-scratch)
- [Install tscircuit locally](./installation.md)
- [Explore tscircuit electronics online](https://tscircuit.com)
- [Drop our AI context into your Claude or OpenAI project](../advanced/ai-context.mdx)
</file>

<file path="docs/tutorials/build-a-custom-keyboard-with-tscircuit.mdx">
---
title: Building a Keyboard with tscircuit
description: >-
  This tutorial guides you through creating a custom mechanical keyboard PCB
  using tscircuit. We'll cover setting up your environment, understanding the
  core components, building a key matrix, creating a simple 4-key keyboard, and
  finally scaling up to a standard 60% layout using data from Keyboard Layout
  Editor.
---

 // Assuming you have this component
import { TscircuitIframe } from "../../src/components/TscircuitIframe" // Assuming you have this component

## Overview

This tutorial guides you through creating a custom mechanical keyboard PCB using tscircuit. We'll cover setting up your environment, understanding the core components, building a key matrix, creating a simple 4-key keyboard, and finally scaling up to a standard 60% layout using data from Keyboard Layout Editor.

We'll be using a Raspberry Pi Pico as the microcontroller, Kailh Choc-style key switches, and standard diodes for the matrix.

<TscircuitIframe defaultActiveTab="cad" code={`
import { PICO } from "@tsci/seveibar.PICO";
import { type KLELayout, KeyMatrix, layouts } from "@tsci/seveibar.keyboard-utils";

const rowPins = ["net.ROW0", "net.ROW1", "net.ROW2", "net.ROW3", "net.ROW4"];
const colPins = ["net.COL0", "net.COL1", "net.COL2", "net.COL3", "net.COL4", "net.COL5", "net.COL6", "net.COL7", "net.COL8", "net.COL9", "net.COL10", "net.COL11", "net.COL12", "net.COL13", "net.COL14"];

export default () => (
  <board routingDisabled>
    {/* Place the Pico */}
    <PICO
      name="U1"
      pcbX={-150} // Position Pico to the left
      pcbY={20}
      layer="bottom"
      pcbRotation="90deg"
      connections={{
        // Connect Pico pins to our row/column nets
        GP15: rowPins[0], // Row 0
        GP16: rowPins[1], // Row 1
        GP17: rowPins[2], // Row 2
        GP18: rowPins[3], // Row 3
        GP19: rowPins[4], // Row 4
        GP0: colPins[0],  // Col 0
        GP1: colPins[1],  // Col 1
        GP2: colPins[2],  // Col 2
        GP3: colPins[3],  // Col 3
        GP4: colPins[4],  // Col 4
        GP5: colPins[5],  // Col 5
        GP6: colPins[6],  // Col 6
        GP7: colPins[7],  // Col 7
        GP8: colPins[8],  // Col 8
        GP9: colPins[9],  // Col 9
        GP10: colPins[10],  // Col 10
        GP11: colPins[11],  // Col 11
        GP12: colPins[12],  // Col 12
        GP13: colPins[13],  // Col 13
        GP14: colPins[14],  // Col 14
      }}
    />

    {/* Place the KeyMatrix */}
    <KeyMatrix
      layout={layouts.default60}
      rowToMicroPin={rowPins}
      colToMicroPin={colPins}
      pcbX={25} // Position matrix to the right
      pcbY={10}
    />
  </board>
)
`} />

## 1. Set Up Your Environment

Before we start building, let's get your development environment ready.

### Prerequisites

You need [Node.js](https://nodejs.org/) or [Bun](https://bun.sh/) installed on your system.

### Install tscircuit CLI

Install the tscircuit command-line interface (CLI) globally using npm or bun:

```bash
npm install -g @tscircuit/cli
# or
bun install -g @tscircuit/cli
```

This installs the `tsci` command, which you can use to create, develop, and export tscircuit projects.

### Create a New Project

Navigate to where you want to create your project and run `tsci init`:

```bash
mkdir my-keyboard
cd my-keyboard
tsci init
```

This command bootstraps a new tscircuit project with a basic structure, including an `index.tsx` file (our main circuit definition), `package.json`, `tsconfig.json`, and other necessary configuration files.

### Run the Development Server

Start the tscircuit development server by running:

```bash
tsci dev
```

This command compiles your `index.tsx` file and serves it on `http://localhost:3020` (or the next available port). Open this URL in your browser. You should see a live preview of your circuit, including PCB, Schematic, and 3D views. The server watches for file changes and automatically updates the preview.

import BrowserPreviewImage from "../../static/img/pcb-runframe.png";

<ImageWithCaption src={BrowserPreviewImage} caption={`Browser preview of a freshly initialized project with \"tsci init\"`} />

## 2. Import the Main Components

A keyboard PCB primarily consists of three types of components:

1.  **Microcontroller:** The "brain" that scans the keys and communicates with the computer. We'll use a Raspberry Pi Pico.
2.  **Key Switches:** The physical buttons you press. We'll use a generic Kailh Choc footprint component.
3.  **Diodes:** Prevent "ghosting" (incorrect key press readings) in the matrix.

Let's import these into our project.

First, you'll need to install the packages containing the `Pico` and `Key` components:

```bash
tsci add @tsci/seveibar.PICO @tsci/seveibar.Key
```

Now, let's import and preview each component to see what we're working with:

### Microcontroller (Raspberry Pi Pico)

We import the `PICO` component. It provides the necessary footprint and pin definitions for the Raspberry Pi Pico.

<CircuitPreview defaultView="3d" code={`
import { PICO } from "@tsci/seveibar.PICO";

export default () => (
  <board width="50mm" height="60mm">
    <PICO name="U1" />
  </board>
);
`} />

### Hot-Swappable Key Switch (Kailh Choc Style)

We import a `Key` component, representing a single switch with its footprint. This
component is comprised of a couple different footprints and 3d models, but when
placed on the board is just a small plastic piece that key switches can be
pressed into.

<CircuitPreview defaultView="3d" code={`
import { Key } from "@tsci/seveibar.Key";

export default () => (
  <board width="30mm" height="30mm">
    <Key name="K1" />
  </board>
);
`} />

### Diode (1N4148WS SMD)

Let's import a diode component. The 1N4148WS is one of the most in-stock and common
diodes according to [jlcsearch](https://jlcsearch.tscircuit.com/diodes/list). We
can use the `File > Import` menu to quickly add it to our project. You should get
something like this. It's also provided as an export from the `@tsci/seveibar.keyboard-utils` package.


<CircuitPreview defaultView="3d" code={`
import { A_1N4148WS } from "@tsci/seveibar.keyboard-utils"

export default () => (
  <board width="20mm" height="20mm">
    <A_1N4148WS name="D1" />
  </board>
)
`} />

## 3. Create the KeyMatrix Component

Connecting each key switch directly to the microcontroller would require a large number of pins, especially for full-size keyboards. Instead, keyboards use a **matrix scanning** technique.

### How Matrix Scanning Works

1.  **Grid Layout:** Keys are arranged logically in a grid of rows and columns.
2.  **Connections:** Each key switch connects a specific row wire to a specific column wire when pressed.
3.  **Scanning:** The microcontroller activates one row (or column) at a time and checks which columns (or rows) become active. This identifies the pressed key(s) at the intersection.
4.  **Diodes:** A diode is placed in series with each switch. This prevents "ghosting," where pressing multiple keys simultaneously might falsely register additional key presses. The diode ensures current flows only in one direction (typically from column to row, or vice-versa depending on the scanning direction).

### The `KeyMatrix` Component

A `KeyMatrix` component, perfect for matrix scanning, is provided as part of the
`@tsci/seveibar.keyboard-utils` package. You can check out the [source code here](https://tscircuit.com/seveibar/keyboard-utils)

The `KeyMatrix` component takes a `layout` definition from [keyboard-layout-editor](http://www.keyboard-layout-editor.com/) and constructs a matrix of keys and diodes automatically.

```tsx
import { KeyMatrix } from "@tsci/seveibar.keyboard-utils"

export default () => (
  <board width="60mm" height="60mm">
    <KeyMatrix
      layout={[
        ["1", "2"],
        ["3", "4"],
      ]}
      rowToMicroPin={["net.ROW0", "net.ROW1"]}
      colToMicroPin={["net.COL0", "net.COL1"]}
    />
  </board>
)
```

## 4. Create a Basic 4-Key Keyboard

Now, let's use our `KeyMatrix` component to create a simple 2x2 keyboard.

We'll define the layout directly in our `index.tsx` and map the rows/columns to Pico pins.

<CircuitPreview defaultView="3d" code={`
import { PICO } from "@tsci/seveibar.PICO";
import { type KLELayout, KeyMatrix } from "@tsci/seveibar.keyboard-utils";

// Define a simple 2x2 layout
const simpleLayout: KLELayout = [
  ["1", "2"],
  ["3", "4"],
]

// Map rows and columns to Pico pins (using net names for clarity)
const rowPins = ["net.ROW0", "net.ROW1"];
const colPins = ["net.COL0", "net.COL1"];

export default () => (
  <board>
    {/* Place the Pico */}
    <PICO
      name="U1"
      pcbX={-25} // Position Pico to the left
      schX={-5}
      pcbRotation="90deg"
      connections={{
        // Connect Pico pins to our row/column nets
        GP15: rowPins[0], // Row 0
        GP16: rowPins[1], // Row 1
        GP0: colPins[0],  // Col 0
        GP1: colPins[1],  // Col 1
      }}
    />

    {/* Place the KeyMatrix */}
    <KeyMatrix
      layout={simpleLayout}
      rowToMicroPin={rowPins}
      colToMicroPin={colPins}
      schX={5}
      pcbX={25} // Position matrix to the right
      pcbY={10}
    />
  </board>
)

`} />

You now have a functional 4-key macropad PCB design!


## 5. Import a Standard Layout (60% Keyboard)

Manually defining layouts for larger keyboards is tedious. We can use data directly from [Keyboard Layout Editor](http://www.keyboard-layout-editor.com/). This website allows you to design layouts graphically and export them as JSON data, which matches our `KLELayout` type.

import KLEExampleImage from "../../static/img/kle-example.png";
import ImageWithCaption from "../../src/components/ImageWithCaption";

<ImageWithCaption src={KLEExampleImage} alt="Keyboard Layout Editor" caption={<span>How to get JSON from <a href="https://www.keyboard-layout-editor.com/" target="_blank" rel="noopener noreferrer">keyboard-layout-editor.com</a></span>} />

Let's use the `default60` layout provided by the `@tsci/seveibar.keyboard-utils` package. It looks like this:

```tsx title="keyboard-layouts/default60.tsx"
export const default60 = [
  [
    "~\n`", "!\n1", "@\n2", "#\n3", "$\n4", "%\n5", "^\n6", "&\n7", "*\n8", "(\n9", ")\n0", "_\n-", "+\n=", { w: 2 }, "Backspace",
  ],
  [
    { w: 1.5 }, "Tab", "Q", "W", "E", "R", "T", "Y", "U", "I", "O", "P", "{\n[", "}\n]", { w: 1.5 }, "|\n\\",
  ],
  [
    { w: 1.75 }, "Caps Lock", "A", "S", "D", "F", "G", "H", "J", "K", "L", ":\n;", "\"\n'", { w: 2.25 }, "Enter",
  ],
  [
    { w: 2.25 }, "Shift", "Z", "X", "C", "V", "B", "N", "M", "<\n,", ">\n.", "?\n/", { w: 2.75 }, "Shift",
  ],
  [
    { w: 1.25 }, "Ctrl", { w: 1.25 }, "Win", { w: 1.25 }, "Alt", { a: 7, w: 6.25 }, "", { a: 4, w: 1.25 }, "Alt", { w: 1.25 }, "Win", { w: 1.25 }, "Menu", { w: 1.25 }, "Ctrl",
  ],
];
```

Now, update `index.tsx` to use this layout. We also need to expand our `rowPins` and `colPins` to match the requirements of a 60% keyboard (typically 5 rows and up to 15 columns).

<CircuitPreview defaultView="pcb" code={`
import { PICO } from "@tsci/seveibar.PICO";
import { type KLELayout, KeyMatrix, layouts } from "@tsci/seveibar.keyboard-utils";

// We'll need more rows and columns for a 60% keyboard
const rowPins = ["net.ROW0", "net.ROW1", "net.ROW2", "net.ROW3", "net.ROW4"];
const colPins = ["net.COL0", "net.COL1", "net.COL2", "net.COL3", "net.COL4", "net.COL5", "net.COL6", "net.COL7", "net.COL8", "net.COL9", "net.COL10", "net.COL11", "net.COL12", "net.COL13", "net.COL14"];

export default () => (
  <board>
    {/* Place the Pico */}
    <PICO
      name="U1"
      pcbX={-150} // Position Pico to the left
      pcbY={20}
      layer="bottom"
      pcbRotation="90deg"
      connections={{
        // Connect Pico pins to our row/column nets
        GP15: rowPins[0], // Row 0
        GP16: rowPins[1], // Row 1
        GP17: rowPins[2], // Row 2
        GP18: rowPins[3], // Row 3
        GP19: rowPins[4], // Row 4
        GP0: colPins[0],  // Col 0
        GP1: colPins[1],  // Col 1
        GP2: colPins[2],  // Col 2
        GP3: colPins[3],  // Col 3
        GP4: colPins[4],  // Col 4
        GP5: colPins[5],  // Col 5
        GP6: colPins[6],  // Col 6
        GP7: colPins[7],  // Col 7
        GP8: colPins[8],  // Col 8
        GP9: colPins[9],  // Col 9
        GP10: colPins[10],  // Col 10
        GP11: colPins[11],  // Col 11
        GP12: colPins[12],  // Col 12
        GP13: colPins[13],  // Col 13
        GP14: colPins[14],  // Col 14
      }}
    />

    {/* Place the KeyMatrix */}
    <KeyMatrix
      layout={layouts.default60}
      rowToMicroPin={rowPins}
      colToMicroPin={colPins}
      pcbX={25} // Position matrix to the right
      pcbY={10}
    />
  </board>
)

`} />

With this setup, you can easily swap `default60` with any other KLE layout JSON data to generate different keyboard PCBs!

## Next Steps

*   **Firmware:** You'll need firmware (like KMK, QMK, or ZMK) for the Raspberry Pi Pico to scan the matrix and act as a USB keyboard. Try using MicroPython with the Pico!
*   **Export:** Use `tsci export` or the download button in the web UI to get Gerber files for manufacturing.
*   **Manufacturing:** Order your PCB from a manufacturer like JLCPCB or PCBWay. See our guide on [Ordering Prototypes](../building-electronics/ordering-prototypes).
*   **Assembly:** Solder the components (Pico, diodes, key switches) onto your manufactured PCB.

Happy building!
</file>

<file path="docs/tutorials/building-a-simple-usb-flashlight.mdx">
---
title: Building a Simple USB Flashlight
---

## Overview

This tutorial will walk you through building a simple USB flashlight using
tscircuit.


<TscircuitIframe defaultView="3d" code={`
import { usePushButton } from "@tsci/seveibar.push-button"
import { useUsbC } from "@tsci/seveibar.smd-usb-c"

export default () => {
  const USBCPort = useUsbC("USBC")
  const Button = usePushButton("SW1")
  return (
    <board width="12mm" height="30mm">
      <USBCPort
        GND1="net.GND"
        GND2="net.GND"
        VBUS1="net.VBUS"
        VBUS2="net.VBUS"
        pcbY={-10}
        schX={-4}
      />
      <led name="LED" color="red" footprint="0603" pcbY={12} schY={2} />
      <Button pcbY={0} pin2=".R1 > .pos" pin3="net.VBUS" schY={-2} />
      <resistor name="R1" footprint="0603" resistance="1k" pcbY={7} />
      <trace from=".R1 .neg" to=".LED .pos" />
      <trace from=".LED .neg" to="net.GND" />
    </board>
  )
}
`} />
</file>

<file path="docs/tutorials/building-led-matrix.mdx">
---
title: Building a 3x5 LED Matrix
description: >-
  This tutorial will walk you through building a 3x5 LED matrix controlled by a
  Raspberry Pi Pico using tscircuit.
---

## Overview

This tutorial will walk you through building a 3x5 LED matrix controlled by a Raspberry Pi Pico using tscircuit.


<TscircuitIframe defaultView="3d" code={`
import { WS2812B_2020 as LedWithIc } from "@tsci/seveibar.WS2812B_2020"
import { usePICO_W } from "@tsci/seveibar.PICO_W"
import { grid } from "@tscircuit/math-utils"


type Point = { x: number; y: number }

type GridCellPositions = {
  index: number
  center: Point
  topLeft: Point
  bottomRight: Point
}

type GridOptions = {
  rows: number
  cols: number
  xSpacing?: number
  ySpacing?: number
  width?: number
  height?: number
  offsetX?: number
  offsetY?: number
  yDirection?: "cartesian" | "up-is-negative"
}

export default () => {
  const U1 = usePICO_W("U1")
  return (
    <board
      width="65mm"
      height="52mm"
      routingDisabled
    >
      <U1 pcbRotation="90deg" pcbX={-15} pcbY={0} />
      {grid({ cols: 3, rows: 5, xSpacing: 8, ySpacing: 5, offsetX: 20, offsetY: 5 }).map(
        ({ center, index }) => {
          const ledName = "LED" + (index + 1)
          const prevLedName = index > 0 ? "LED" + (index) : null
          return (
            <>
              <LedWithIc schX={center.x/2} schY={5 + center.y/2} name={ledName} pcbX={center.x} pcbY={center.y} />
              <trace from={".LED" + (index + 1) + " .GND"} to="net.GND" />
              <trace from={".LED" + (index + 1) + " .VDD"} to="net.V5" />
              {prevLedName && <trace from={".LED" + (index) + " .DO"} to={".LED" + (index + 1) + " .DI"} />}
            </>
          )
        }
      )}

      <trace from=".LED1 .DI" to={U1.GP6_SPI0SCK_I2C1SDA} />
      <trace from={U1.GND1} to="net.GND" />
      <trace from={U1.GND2} to="net.GND" />
      <trace from={U1.GND3} to="net.GND" />
      <trace from={U1.GND4} to="net.GND" />
      <trace from={U1.GND5} to="net.GND" />
      <trace from={U1.GND6} to="net.GND" />
      <trace from={U1.GND7} to="net.GND" />

      <trace from={U1.VBUS} to="net.V5" />

    </board>
  )
}

`} />

## Objectives of Building an LED Matrix

Some practical applications of building an LED Matrix include:

- **Signage** - Building signs for events, products, etc.
- **Data Visualization Tool** - Displaying real-time data metrics like GitHub contributions, website traffic, or temperature readings through color intensity
- **Interactive Notification System** - Creating a physical notification system for emails, social media, or calendar events with customizable brightness levels

## LED Matrix Requirements

- The LED matrix must be WiFi-controllable
- The matrix layout pattern must be grid-based
- Each LED should be individually controllable for brightness and color

## System Diagram

The matrix connects to the Pico microcontroller via a data chain. The Pico connects to WiFi through the `PICO_W` module.
The components and connections between them are shown in the diagram below:

![System Diagram](../../static/img/tutorials/led-matrix/matrix-system-requirements.png)

## Schematic Capture

Let's import the Pico microcontroller and LED components by following the steps in the [Importing from JLCPCB](/guides/importing-modules-and-chips/importing-from-jlcpcb) section.  

We will follow the following steps to build the circuit step by step:
1. Import the Pico microcontroller Schematic
2. Import the LED Schematic
3. Chain two LEDs together
4. Chain many LEDs together
5. Connect the Pico to the LED matrix

### Pico Schematic
Schematic of the Pico microcontroller [imported from JLCPCB](/guides/importing-modules-and-chips/importing-from-jlcpcb) is shown below:
<CircuitPreview splitView={false} hidePCBTab hide3DTab defaultView="schematic" code={`
import { createUseComponent } from "@tscircuit/core"
import type { CommonLayoutProps } from "@tscircuit/props"

const pinLabels = {
  "pin1": [
    "pin1",
    "GP0_SPI0RX_I2C0SDA_UART0TX"
  ],
  "pin2": [
    "pin2",
    "GP1_SPI0CSn_I2C0SCL_UART0RX"
  ],
  "pin3": [
    "pin3",
    "GND1"
  ],
  "pin4": [
    "pin4",
    "GP2_SPI0SCK_I2C1SDA"
  ],
  "pin5": [
    "pin5",
    "GP3_SPI0TX_I2C1SCL"
  ],

  "pin6": [
    "pin6",
    "GP4_SPI0RX_I2C0SDA_UART1TX"
  ],
  "pin7": [
    "pin7",
    "GP5_SPI0CSn_I2C0SCL_UART1RX"
  ],
  "pin8": [
    "pin8",
    "GND3"
  ],
  "pin9": [
    "pin9",
    "GP6_SPI0SCK_I2C1SDA"
  ],
  "pin10": [
    "pin10",
    "GP7_SPI0TX_I2C1SCL"
  ],
  "pin11": [
    "pin11",
    "GP8_SPI1RX_I2C0SDA_UART1TX"
  ],
  "pin12": [
    "pin12",
    "GP9_SPI1CSn_I2C0SCL_UART1RX"
  ],
  "pin13": [
    "pin13",
    "GND4"
  ],
  "pin14": [
    "pin14",
    "GP10_SPI1SCK_I2C1SDA"
  ],
  "pin15": [
    "pin15",
    "GP11_SPI1TX_I2C1SCL"
  ],
  "pin16": [
    "pin16",
    "GP12_SPI1RX_I2C0SDA_UART0TX"
  ],
  "pin17": [
    "pin17",
    "GP13_SPI1CSn_I2C0SCL_UART0RX"
  ],
  "pin18": [
    "pin18",
    "GND6"
  ],
  "pin19": [
    "pin19",
    "GP14_SPI1SCK_I2C1SDA"
  ],
  "pin20": [
    "pin20",
    "GP15_SPI1TX_I2C1SCL"
  ],
  "pin21": [
    "pin21",
    "GP16_SPI0RX_UART0RX"
  ],
  "pin22": [
    "pin22",
    "GP17_SPI0CSn_UART0TX"
  ],
  "pin23": [
    "pin23",
    "GND7"
  ],
  "pin24": [
    "pin24",
    "GP18_SPI0SCK_I2C1SDA"
  ],
  "pin25": [
    "pin25",
    "GP19_SPI0TX_I2C1SCL"
  ],
  "pin26": [
    "pin26",
    "GP20_I2C0SDA"
  ],
  "pin27": [
    "pin27",
    "GP21_I2C0SCL"
  ],
  "pin28": [
    "pin28",
    "GND5"
  ],
  "pin29": [
    "pin29",
    "GP22"
  ],
  "pin30": [
    "pin30",
    "RUN"
  ],
  "pin31": [
    "pin31",
    "GP26_ADC0_I2C1SDA"
  ],
  "pin32": [
    "pin32",
    "GP27_ADC1_I2C1SCL"
  ],
  "pin33": [
    "pin33",
    "GND_AGND"
  ],
  "pin34": [
    "pin34",
    "GP28_ADC2"
  ],
  "pin35": [
    "pin35",
    "ADC_VREF"
  ],
  "pin36": [
    "pin36"
  ],
  "pin37": [
    "pin37",
    "3V3_EN"
  ],
  "pin38": [
    "pin38",
    "GND2"
  ],
  "pin39": [
    "pin39",
    "VSYS"
  ],
  "pin40": [
    "pin40",
    "VBUS"
  ],
  "pin41": [
    "pin41",
    "TP6"
  ],
  "pin42": [
    "pin42",
    "TP5"
  ],
  "pin43": [
    "pin43",
    "TP4"
  ],
  "pin44": [
    "pin44",
    "TP3"
  ],
  "pin45": [
    "pin45",
    "TP2"
  ],
  "pin46": [
    "pin46",
    "TP1"
  ]
} as const

interface Props extends CommonLayoutProps {
  name: string
}

export const PICO_W = (props: Props) => {
  return (
    <chip
      {...props}
      schWidth={5}
      cadModel={{
        objUrl: "https://modelcdn.tscircuit.com/easyeda_models/download?uuid=07c2e528ec9a4008b33211831b7000e1&pn=C7203003",
        rotationOffset: { x: 0, y: 0, z: 0 },
        positionOffset: { x: 0, y: 0, z: 0 },
      }}
      pinLabels={pinLabels}
      supplierPartNumbers={{
  "jlcpcb": [
    "C7203003"
  ]
}}
      manufacturerPartNumber="PICO_W"
      footprint={<footprint>
        <smtpad portHints={["pin41"]} pcbX="-10.940014949999977mm" pcbY="-2.499740999999972mm" width="1.499997mm" height="1.499997mm" shape="rect" />
<smtpad portHints={["pin42"]} pcbX="-13.44013695000001mm" pcbY="-2.499740999999972mm" width="1.499997mm" height="1.499997mm" shape="rect" />
<smtpad portHints={["pin43"]} pcbX="-15.940004950000002mm" pcbY="-2.499740999999972mm" width="1.499997mm" height="1.499997mm" shape="rect" />
<smtpad portHints={["pin44"]} pcbX="-24.239962950000063mm" pcbY="-0.999870999999871mm" width="1.499997mm" height="1.499997mm" shape="rect" />
<smtpad portHints={["pin45"]} pcbX="-24.239962950000063mm" pcbY="1.0001250000000255mm" width="1.499997mm" height="1.499997mm" shape="rect" />
<smtpad portHints={["pin46"]} pcbX="-20.939994949999914mm" pcbY="0.00012700000002041634mm" width="1.499997mm" height="1.499997mm" shape="rect" />
<smtpad portHints={["pin1"]} pcbX="-24.07003695000003mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin40"]} pcbX="-24.07003695000003mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin2"]} pcbX="-21.530036950000067mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin39"]} pcbX="-21.530036950000067mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin3"]} pcbX="-18.99003694999999mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin38"]} pcbX="-18.99003694999999mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin4"]} pcbX="-16.450036950000026mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin37"]} pcbX="-16.450036950000026mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin5"]} pcbX="-13.910036950000062mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin36"]} pcbX="-13.910036950000062mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin6"]} pcbX="-11.370036949999985mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin35"]} pcbX="-11.370036949999985mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin7"]} pcbX="-8.830036950000022mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin34"]} pcbX="-8.830036950000022mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin8"]} pcbX="-6.290036950000058mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin33"]} pcbX="-6.290036950000058mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin9"]} pcbX="-3.7500369499999806mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin32"]} pcbX="-3.7500369499999806mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin10"]} pcbX="-1.210036950000017mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin31"]} pcbX="-1.210036950000017mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin11"]} pcbX="1.3299630499999466mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin30"]} pcbX="1.3299630499999466mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin12"]} pcbX="3.869963050000024mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin29"]} pcbX="3.869963050000024mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin13"]} pcbX="6.409963049999988mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin28"]} pcbX="6.409963049999988mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin14"]} pcbX="8.949963049999951mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin27"]} pcbX="8.949963049999951mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin15"]} pcbX="11.489963049999915mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin26"]} pcbX="11.489963049999915mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin16"]} pcbX="14.029963049999992mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin25"]} pcbX="14.029963049999992mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin17"]} pcbX="16.569963049999956mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin24"]} pcbX="16.569963049999956mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin18"]} pcbX="19.10996304999992mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin23"]} pcbX="19.10996304999992mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin19"]} pcbX="21.649963049999997mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin22"]} pcbX="21.649963049999997mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin20"]} pcbX="24.18996304999996mm" pcbY="-9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<smtpad portHints={["pin21"]} pcbX="24.18996304999996mm" pcbY="9.689973000000009mm" width="1.5999967999999998mm" height="3.1999935999999995mm" shape="rect" />
<silkscreenpath route={[{"x":17.601101449999874,"y":-10.499877399999946},{"x":18.078900849999968,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":25.55998825000006,"y":3.5711383999999953},{"x":25.55998825000006,"y":-3.5710622000000285}]} />
<silkscreenpath route={[{"x":25.22110144999988,"y":-10.499877399999946},{"x":25.55998825000006,"y":-10.499877399999946},{"x":25.55998825000006,"y":-3.5710622000000285}]} />
<silkscreenpath route={[{"x":25.55998825000006,"y":3.5711383999999953},{"x":25.55998825000006,"y":10.500080600000047},{"x":25.22110144999988,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":-25.101048350000042,"y":10.499953600000026},{"x":-25.439808149999976,"y":10.499953600000026}]} />
<silkscreenpath route={[{"x":-25.439935149999997,"y":10.500080600000047},{"x":-25.439935149999997,"y":-10.499877399999946},{"x":-25.101099149999982,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":-26.739830950000055,"y":3.9996363999999858},{"x":-26.339603149999903,"y":3.9996363999999858},{"x":-26.339603149999903,"y":-4.000245999999834},{"x":-26.739830950000055,"y":-4.000245999999834}]} />
<silkscreenpath route={[{"x":-26.339603149999903,"y":-3.8089332000000695},{"x":-25.465233549999994,"y":-3.8089332000000695},{"x":-25.439808149999976,"y":-3.834358599999973}]} />
<silkscreenpath route={[{"x":-26.339603149999903,"y":3.8025069999999914},{"x":-25.439808149999976,"y":3.8025069999999914}]} />
<silkscreenpath route={[{"x":-26.739830950000055,"y":3.9996363999999858},{"x":-26.739830950000055,"y":-4.000245999999834}]} />
<silkscreenpath route={[{"x":-22.561099150000132,"y":10.500080600000047},{"x":-23.03889855,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":-20.021099150000055,"y":10.500080600000047},{"x":-20.498898550000035,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":-17.48109915000009,"y":10.500080600000047},{"x":-17.95889855000007,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":-14.941099150000014,"y":10.500080600000047},{"x":-15.418898550000108,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":-12.40109915000005,"y":10.500080600000047},{"x":-12.87889855000003,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":-9.861099150000086,"y":10.500080600000047},{"x":-10.338898550000067,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":-7.321099150000123,"y":10.500080600000047},{"x":-7.79889854999999,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":-4.7810991500000455,"y":10.500080600000047},{"x":-5.258898550000026,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":-2.241099150000082,"y":10.500080600000047},{"x":-2.7188985500000626,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":0.29890084999999544,"y":10.500080600000047},{"x":-0.17889855000009902,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":2.838900849999959,"y":10.500080600000047},{"x":2.3611014499998646,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":5.378900849999923,"y":10.500080600000047},{"x":4.901101449999942,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":7.918900849999886,"y":10.500080600000047},{"x":7.441101450000019,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":10.458900849999964,"y":10.500080600000047},{"x":9.98110144999987,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":12.998900849999927,"y":10.500080600000047},{"x":12.521101449999946,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":15.538900850000005,"y":10.500080600000047},{"x":15.06110144999991,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":18.078900849999968,"y":10.500080600000047},{"x":17.601101449999874,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":20.618900849999932,"y":10.500080600000047},{"x":20.14110144999995,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":23.158900849999895,"y":10.500080600000047},{"x":22.68110145000003,"y":10.500080600000047}]} />
<silkscreenpath route={[{"x":22.68110145000003,"y":-10.499877399999946},{"x":23.158900849999895,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":20.14110144999995,"y":-10.499877399999946},{"x":20.618900849999932,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":15.06110144999991,"y":-10.499877399999946},{"x":15.538900850000005,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":12.521101449999946,"y":-10.499877399999946},{"x":12.998900849999927,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":9.98110144999987,"y":-10.499877399999946},{"x":10.458900849999964,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":7.441101450000019,"y":-10.499877399999946},{"x":7.918900849999886,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":4.901101449999942,"y":-10.499877399999946},{"x":5.378900849999923,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":2.3611014499998646,"y":-10.499877399999946},{"x":2.838900849999959,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":-0.17889855000009902,"y":-10.499877399999946},{"x":0.29890084999999544,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":-2.7188985500000626,"y":-10.499877399999946},{"x":-2.241099150000082,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":-5.258898550000026,"y":-10.499877399999946},{"x":-4.7810991500000455,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":-7.79889854999999,"y":-10.499877399999946},{"x":-7.321099150000123,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":-10.338898550000067,"y":-10.499877399999946},{"x":-9.861099150000086,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":-12.87889855000003,"y":-10.499877399999946},{"x":-12.40109915000005,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":-15.418898550000108,"y":-10.499877399999946},{"x":-14.941099150000014,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":-17.95889855000007,"y":-10.499877399999946},{"x":-17.48109915000009,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":-20.498898550000035,"y":-10.499877399999946},{"x":-20.021099150000055,"y":-10.499877399999946}]} />
<silkscreenpath route={[{"x":-23.03889855,"y":-10.499877399999946},{"x":-22.561099150000132,"y":-10.499877399999946}]} />
      </footprint>}
    />
  )
}

export const usePICO_W = createUseComponent(PICO_W, pinLabels)
`} />

### LED Schematic
We are using IC LEDs (specifically [WS2812B](https://jlcpcb.com/partdetail/Worldsemi-WS2812B2020/C965555)), which have an RGB LED and control chip integrated into the same package. These IC LEDs offer several advantages over traditional RGB LEDs:

- **Simplified Wiring** - Only 4 pins needed (VDD, GND, Data In, Data Out) compared to 4+ pins for traditional RGB LEDs
- **Serial Communication** - LEDs can be daisy-chained together, requiring only one data pin from the microcontroller
- **Individual Control** - Each LED in the chain can be controlled independently for color and brightness

<CircuitPreview splitView={false} hidePCBTab hide3DTab defaultView="schematic" code={`
import { createUseComponent } from "@tscircuit/core"
import type { CommonLayoutProps } from "@tscircuit/props"

const pinLabels = {
  "pin1": [
    "pin1",
    "DO"
  ],
  "pin2": [
    "pin2",
    "GND"
  ],
  "pin3": [
    "pin3",
    "DI"
  ],
  "pin4": [
    "pin4",
    "VDD"
  ]
} as const

interface Props extends CommonLayoutProps {
  name: string,
}

export const WS2812B_2020 = (props: Props) => {
  return (
    <chip
      {...props}
      cadModel={{
        objUrl: "https://modelcdn.tscircuit.com/easyeda_models/download?uuid=caa88715b11f4aa189b02e52bbb84e4f&pn=C965555",
        rotationOffset: { x: 0, y: 0, z: 0 },
        positionOffset: { x: 0, y: 0, z: -0.07 },
      }}
      schPortArrangement={{
        leftSide: {
          direction: "top-to-bottom",
          pins: ["DI", "GND"]
        },
        rightSide: {
          direction: "top-to-bottom",
          pins: ["VDD", "DO"]
        }
      }}
      pinLabels={pinLabels}
      supplierPartNumbers={{
  "jlcpcb": [
    "C965555"
  ]
}}
      manufacturerPartNumber="WS2812B_2020"
      footprint={<footprint>
        <smtpad portHints={["pin1"]} pcbX="-0.9150349999999889mm" pcbY="0.5500369999999748mm" width="0.8999982mm" height="0.6999986mm" shape="rect" />
<smtpad portHints={["pin2"]} pcbX="-0.9150349999999889mm" pcbY="-0.5500369999999748mm" width="0.8999982mm" height="0.6999986mm" shape="rect" />
<smtpad portHints={["pin3"]} pcbX="0.9150349999999889mm" pcbY="-0.5500369999999748mm" width="0.8999982mm" height="0.6999986mm" shape="rect" />
<smtpad portHints={["pin4"]} pcbX="0.9150349999999889mm" pcbY="0.5500369999999748mm" width="0.8999982mm" height="0.6999986mm" shape="rect" />
<silkscreenpath route={[{"x":-0.24998679999998785,"y":0.7499603999999636},{"x":-0.09999980000009145,"y":0.7499603999999636},{"x":-0.09999980000009145,"y":-0.6500114000000394},{"x":-0.09999980000009145,"y":-0.6999986000000717},{"x":-0.24998679999998785,"y":-0.6999986000000717}]} />
<silkscreenpath route={[{"x":-0.24998679999998785,"y":0.7499603999999636},{"x":-0.24998679999998785,"y":-0.7000239999999849}]} />
<silkscreenpath route={[{"x":-1.299997400000052,"y":1.1499850000000151},{"x":-1.299997400000052,"y":1.1381486000000223}]} />
<silkscreenpath route={[{"x":0.9999979999998914,"y":1.0999977999999828},{"x":-0.999998000000005,"y":1.0999977999999828}]} />
<silkscreenpath route={[{"x":-0.999998000000005,"y":-1.0999977999999828},{"x":0.9999979999998914,"y":-1.0999977999999828}]} />
      </footprint>}
    />
  )
}

export const useWS2812B_2020 = createUseComponent(WS2812B_2020, pinLabels)
`} />

### Chaining Two LEDs together

To connect two LEDs together, we need to connect the data output `DO` of the first LED to the data input `DI` of the second LED. This creates a chain of LEDs.

<CircuitPreview hidePCBTab hide3DTab defaultView="schematic" code={`
import { WS2812B_2020 as LedWithIc } from "@tsci/seveibar.WS2812B_2020"

export default () => (
  <board>
   {/* First LED */}
    <LedWithIc 
      schX={0} 
      schY={0} 
      name={"LED1"} 
    />
    {/* Second LED */}
    <LedWithIc 
      schX={5} 
      schY={0} 
      name={"LED2"} 
    />

    {/* Connecting the LEDs to GND and VDD */}
    <trace from={".LED1 .GND"} to="net.GND" />
    <trace from={".LED1 .VDD"} to="net.V5" />

    <trace from={".LED2 .GND"} to="net.GND" />
    <trace from={".LED2 .VDD"} to="net.V5" />

    {/* Connecting the LEDs together */}
    <trace from={".LED1 .DO"} to={".LED2 .DI"} />
  </board>
)
`} />

### Connecting Pico to the LED Matrix

The Pico is connected to the LED matrix via a general purpose input/output (GPIO) pin in this example we are using `GP6`,
and the other pins of the Pico are connected to ground.

<CircuitPreview hidePCBTab hide3DTab defaultView="schematic" code={`
import { usePICO_W } from "@tsci/seveibar.PICO_W"
import { WS2812B_2020 as LedWithIc } from "@tsci/seveibar.WS2812B_2020"

export default () => {
  const U1 = usePICO_W("U1")
  return (
    <board
      width="60mm"
      height="60mm"
    >
      {/* Pico microcontroller */}
      <U1 />

      {/* LED */}
      <LedWithIc 
        name={"LED1"} 
        schX={-5}
      />

      {/* Connecting the LED to GND and VDD */}
      <trace from={".LED1 .GND"} to="net.GND" />
      <trace from={".LED1 .VDD"} to="net.V5" />

      {/* Connecting the LED to the Pico GP6 pin */}
      <trace from=".LED1 .DI" to={U1.GP6_SPI0SCK_I2C1SDA} />

      {/* Connecting the Pico to GND */}
      <trace from={U1.GND1} to="net.GND" />
      <trace from={U1.GND2} to="net.GND" />
      <trace from={U1.GND3} to="net.GND" />
      <trace from={U1.GND4} to="net.GND" />
      <trace from={U1.GND5} to="net.GND" />
      <trace from={U1.GND6} to="net.GND" />
      <trace from={U1.GND7} to="net.GND" />

      {/* Connecting the Pico to the power supply */}
      <trace from={U1.VBUS} to="net.V5" />
    </board>
  )
}
`} />

### Chaining many LEDs together

#### LED Matrix Layout
We can connect multiple LEDs together by chaining them, but doing this for a large number of LEDs would be tedious.
Luckily, tscircuit has a [helper function to create a grid](https://github.com/tscircuit/math-utils) of components. We will be using that helper function to create our matrix layout.

Here we are using the [`grid`](https://github.com/tscircuit/math-utils/blob/main/src/grid.ts) function to create a 3x5 LED matrix. The `grid` function takes in the number of columns and rows, and the spacing between the components.

<CircuitPreview hidePCBTab hide3DTab defaultView="schematic" code={`
import { WS2812B_2020 as LedWithIc } from "@tsci/seveibar.WS2812B_2020"
import { grid } from "@tscircuit/math-utils"

export default () => {
  return (
    <board width="65mm" height="52mm" routingDisabled>
      {/* 3x5 LED matrix */}
      {grid({ cols: 3, rows: 5, xSpacing: 8, ySpacing: 5, offsetX: 20, offsetY: 5 }).map(
        ({ center, index }) => {
          const ledName = "LED" + (index + 1)
          const prevLedName = index > 0 ? "LED" + (index) : null
          return (
            <>
              {/* LED */}
              <LedWithIc schX={center.x/2} schY={5 + center.y/2} name={ledName} />

              {/* Connecting the LED to GND and VDD */}
              <trace from={".LED" + (index + 1) + " .GND"} to="net.GND" />
              <trace from={".LED" + (index + 1) + " .VDD"} to="net.V5" />

              {/* Connecting the LED to the previous LED */}
              {prevLedName && <trace from={".LED" + (index) + " .DO"} to={".LED" + (index + 1) + " .DI"} />}
            </>
          )
        }
      )}
    </board>
  )
}
`}
/>

### Connecting the Pico to the LED matrix

Here we are merging all the learnings from the previous examples to create a complete circuit. The Pico is connected to the LED matrix via the `GP6` pin, and the other pins of the Pico are connected to ground.
The `GP6` pin is connected to the data input `DI` of the first LED, and the data output `DO` of each LED is connected to the data input `DI` of the next LED in the chain.
While connecting the LEDs together, we are also connecting the `GND` and `VDD` pins of the LEDs to ground and 5V supply respectively.

Complete circuit is shown below:

<CircuitPreview hidePCBTab hide3DTab defaultView="schematic" code={`
import { usePICO_W } from "@tsci/seveibar.PICO_W"
import { WS2812B_2020 as LedWithIc } from "@tsci/seveibar.WS2812B_2020"
import { grid } from "@tscircuit/math-utils"

export default () => {
  const U1 = usePICO_W("U1")
  return (  
    <board width="60mm" height="60mm" routingDisabled>
      {/* Pico microcontroller */}
      <U1 />

      {/* LED matrix */}
      {grid({ cols: 3, rows: 5, xSpacing: 8, ySpacing: 5, offsetX: 20 }).map(
        ({ center, index }) => {
          const ledName = "LED" + (index + 1)
          const prevLedName = index > 0 ? "LED" + (index) : null
          return (
            <>
              {/* LED */}
              <LedWithIc schX={center.x/2} schY={5 + center.y/2} name={ledName} />

              {/* Connecting the LED to GND and VDD */}
              <trace from={".LED" + (index + 1) + " .GND"} to="net.GND" />
              <trace from={".LED" + (index + 1) + " .VDD"} to="net.V5" />

              {/* Connecting the LED to the previous LED */}
              {prevLedName && <trace from={".LED" + (index) + " .DO"} to={".LED" + (index + 1) + " .DI"} />}
            </>
          )
        }
      )}

      {/* Connecting the Pico to the LED matrix using GP6 pin */}
      <trace from={U1.GP6_SPI0SCK_I2C1SDA} to={".LED1 .DI"} />

      {/* Connecting the Pico to GND */}
      <trace from={U1.GND1} to="net.GND" />
      <trace from={U1.GND2} to="net.GND" />
      <trace from={U1.GND3} to="net.GND" />
      <trace from={U1.GND4} to="net.GND" />
      <trace from={U1.GND5} to="net.GND" />
      <trace from={U1.GND6} to="net.GND" />
      <trace from={U1.GND7} to="net.GND" />
    </board>
  )
}
`} />

## PCB Layout

We can translate our schematic into a PCB layout by specifying the physical positions of components on the board.

Here we are adding the positions of the components on the PCB:
- Pico microcontroller is added at `pcbX={-15} pcbY={0}` with a rotation of `90deg` (Rotation is needed for the Pico to be in the correct orientation)
- LEDs are added at positions calculated by the grid function with a spacing of `8mm` horizontally and `5mm` vertically

<CircuitPreview  hide3DTab defaultView="pcb" code={`
import { usePICO_W } from "@tsci/seveibar.PICO_W"
import { WS2812B_2020 as LedWithIc } from "@tsci/seveibar.WS2812B_2020"
import { grid } from "@tscircuit/math-utils"

export default () => {
  const U1 = usePICO_W("U1")
  return (  
    <board width="65mm" height="60mm" routingDisabled>
      {/* Pico microcontroller */}
      <U1 pcbRotation="90deg" pcbX={-15} pcbY={0} />

      {/* LED matrix */}
      {grid({ cols: 3, rows: 5, xSpacing: 8, ySpacing: 5, offsetX: 20, offsetY: 5 }).map(
        ({ center, index }) => {
          const ledName = "LED" + (index + 1)
          const prevLedName = index > 0 ? "LED" + (index) : null
          return (
            <>
              {/* LED */}
              <LedWithIc schX={center.x/2} schY={5 + center.y/2} name={ledName} pcbX={center.x} pcbY={center.y} />

              {/* Connecting the LED to GND and VDD */}
              <trace from={".LED" + (index + 1) + " .GND"} to="net.GND" />
              <trace from={".LED" + (index + 1) + " .VDD"} to="net.V5" />

              {/* Connecting the LED to the previous LED */}
              {prevLedName && <trace from={".LED" + (index) + " .DO"} to={".LED" + (index + 1) + " .DI"} />}
            </>
          )
        }
      )}

      {/* Connecting the Pico to the LED matrix using GP6 pin */}
      <trace from={U1.GP6_SPI0SCK_I2C1SDA} to={".LED1 .DI"} />

      {/* Connecting the Pico to GND */}
      <trace from={U1.GND1} to="net.GND" />
      <trace from={U1.GND2} to="net.GND" />
      <trace from={U1.GND3} to="net.GND" />
      <trace from={U1.GND4} to="net.GND" />
      <trace from={U1.GND5} to="net.GND" />
      <trace from={U1.GND6} to="net.GND" />
      <trace from={U1.GND7} to="net.GND" />
    </board>
  )
}
`} />


Check out this circuit in our [Playground](https://tscircuit.com/editor?snippet_id=e30ad928-3432-49a4-826c-f50cae1490ef).

## Ordering the PCB

You can order this PCB by downloading the fabrication files and uploading them to JLCPCB. Follow the instructions from [here](/building-electronics/ordering-prototypes).

## Controlling the LED Matrix

The LED matrix can be controlled through a simple web interface that provides a visual grid for controlling individual LEDs. The control system includes:

<table>
  <tr>
    <td>
      <img src="/img/tutorials/led-matrix/led-matrix-board.png" alt="LED Matrix board" />
    </td>
    <td>
      <img src="/img/tutorials/led-matrix/web-interface-1.png" alt="LED Matrix web interface" />
    </td>
  </tr>
</table>


1. **Web Interface**: A 3x5 grid interface where clicking each cell cycles through:
   - Off (Gray)
   - Red
   - Green
   - Blue

2. **API Integration**: The matrix state can be controlled and monitored through REST endpoints, making it easy to integrate with other applications.

3. **Pico W Connection**: The matrix connects to WiFi using the Pico W's wireless capabilities, allowing for remote control through the web interface.

The complete implementation, including the web interface and Pico W code, is available in our [LED Matrix Server repository](https://github.com/tscircuit/led-matrix-server).
</file>

<file path="docs/web-apis/autorouting-api.mdx">
---
title: Autorouting API
description: >-
  tscircuit allows heavy customization of the autorouting process. In tscircuit
  you can use local or cloud autorouters, use different autorouters for different
  subcircuits, and disable autorouting entirely.
---


## Overview

tscircuit allows heavy customization of the autorouting process. In tscircuit
you can use local or cloud autorouters, use different autorouters for different
subcircuits, and disable autorouting entirely.

This page provides details on the autorouting cloud API so you can import your
own cloud autorouter.

## Using Custom Autorouters

Here's an example of how a customer autorouter can be configured with tscircuit:

<CircuitPreview defaultView="pcb" code={`
  export default () => (
    <board
      width="20mm"
      height="20mm"
      autorouter={{
        serverUrl: "https://registry-api.tscircuit.com",
        serverMode: "job",
        inputFormat: "simplified",
      }}
    >
      <chip name="U1" footprint="soic8" pcbX={5} pcbY={0} />
      <resistor
        name="R1"
        pcbX={-5}
        pcbY={0}
        resistance={100}
        footprint="0402"
      />
      <trace from=".U1 > .pin1" to=".R1 > .pin1" />
    </board>
  )
`} />

### The Autorouter Object

The autorouter object is used to configure the autorouter. The following properties are supported:

- `serverUrl`: The URL of the autorouter server.
- `serverMode`: [`job`]( or `solve-endpoint`
- `inputFormat`: The format of the input to the autorouter server.

## Input and Output Formats

### Simplified Input/Output

The `simplified` input format is simple to build an autorouter for. It contains
a JSON object with the desired connections to make and the obstacles the algorithm must
avoid to solve the routing problem.

When using the `simplified` input format, the `/autorouting/jobs/create` and/or `/autorouting/solve`
endpoint must accept a `input_simple_route_json` file with the following interface:

```tsx
interface SimpleRouteJson {
  layerCount: number
  minTraceWidth: number
  obstacles: Obstacle[]
  connections: Array<SimpleRouteConnection>
  bounds: { minX: number; maxX: number; minY: number; maxY: number }
}

interface Obstacle {
  type: "rect"
  layers: string[]
  center: { x: number; y: number }
  width: number
  height: number
  connectedTo: string[]
}

interface SimpleRouteConnection {
  name: string
  pointsToConnect: Array<{ x: number; y: number; layer: string }>
}
```

Here's an example of a `SimpleRouteJson` object:

```json
{
  "layerCount": 2,
  "minTraceWidth": 0.2,
  "obstacles": [
    {
      "type": "rect",
      "layers": ["top"],
      "center": { "x": 30, "y": 25 },
      "width": 10,
      "height": 8,
      "connectedTo": ["power"]
    },
    {
      "type": "rect",
      "layers": ["bottom"],
      "center": { "x": 70, "y": 25 },
      "width": 12,
      "height": 6,
      "connectedTo": ["ground"]
    }
  ],
  "connections": [
    {
      "name": "power_net",
      "pointsToConnect": [
        { "x": 10, "y": 10, "layer": "top" },
        { "x": 90, "y": 40, "layer": "bottom" }
      ]
    },
    {
      "name": "ground_net",
      "pointsToConnect": [
        { "x": 20, "y": 20, "layer": "top" },
        { "x": 80, "y": 30, "layer": "top" }
      ]
    }
  ],
  "bounds": {
    "minX": 0,
    "maxX": 100,
    "minY": 0,
    "maxY": 50
  }
}
```

When in `simplified` mode you should respond with an
`output_simple_route_json` object that adds a `traces` field to the original
input object.

```json
{
  "output_simple_route_json": {
    // ...the original input object fields
    "traces": [
      {
        "type": "pcb_trace",
        "pcb_trace_id": "trace_1",
        "route": [
          {
            "route_type": "via",
            "x": 45,
            "y": 25,
            "from_layer": "top",
            "to_layer": "bottom"
          },
          {
            "route_type": "wire",
            "x": 45,
            "y": 25,
            "width": 0.2,
            "layer": "bottom"
          },
          {
            "route_type": "wire",
            "x": 60,
            "y": 35,
            "width": 0.2,
            "layer": "bottom"
          }
        ]
      }
    ]
  }
}
```

The `traces` field should match this type:

```tsx
type SimplifiedPcbTraces = Array<{
  type: "pcb_trace"
  pcb_trace_id: string
  route: Array<
    | {
        route_type: "wire"
        x: number
        y: number
        width: number
        layer: string
      }
    | {
        route_type: "via"
        x: number
        y: number
        to_layer: string
        from_layer: string
      }
  >
}>
```


### Circuit JSON Input/Output

When using `inputFormat: "circuit_json"` you the API must accept `{ input_circuit_json }` and
respond with PCB traces in the format `{ output_pcb_traces }` that can be concatenated to the Circuit JSON to complete the circuit.

## Choosing a `serverMode`

When you're implementing the autorouter API, you can choose to implement either
the `job` API (recommended) or the `solve-endpoint` API. The `solve-endpoint` is easier because
it's a single endpoint, but has many limitations because it must perform the
autorouting in the lifecycle of a single request.

When defining your autorouter object, you can choose the `serverMode` and `inputFormat`
to correspond to what you've implemented.

## The `solve-endpoint` API

| Endpoint |  Description |
| -------- | ----------- |
| `/autorouting/solve` | Takes autorouting input and returns the solved routes | 

### `solve-endpoint` with `simplified` input

```
POST /autorouting/solve

{
  "input_simple_route_json": {
    // ...
  }
}

RESPONSE:

{
  "output_simple_route_json": {
    // ...
  }
}
```

### `solve-endpoint` with `circuit_json` input

```
POST /autorouting/solve

{
  "input_circuit_json": {
    // ...
  }
}

RESPONSE:

{
  "output_pcb_traces": [
    {
      "type": "pcb_trace",
      "pcb_trace_id": "trace_1",
      "route": [
        // ...
      ]
    }
  ]
}
```

## The `job` API

The `job` autorouting API allows you to perform long-running autorouting jobs for
large circuits. When using the `job` API, you must use the `"circuit_json"` input format.

| Endpoint |  Description |
| -------- | ----------- |
| `/autorouting/jobs/create` | Create the autorouting job | 
| `/autorouting/jobs/get`    | Get the status of the autorouting job |
| `/autorouting/jobs/cancel` | Cancel the autorouting job |
| `/autorouting/jobs/get_output` | Get the solved routes from a completed autorouting job |

:::info
Here's the [source code](https://github.com/tscircuit/core/blob/main/lib/components/primitive-components/Group/Group.ts#L232) in tscircuit core where the `job` API is used to autoroute a circuit. You can
see that each endpoint is called in order
:::

```
POST /autorouting/jobs/create
{
  "input_simple_route_json": {
    // ...
  },
  "autostart": true
}

RESPONSE:

{
  "autorouting_job": {
    "autorouting_job_id": "1234567890",
    // ...
  }
}



GET /autorouting/jobs/get?autorouting_job_id=1234567890

RESPONSE:

{
  "autorouting_job": {
    "is_running": false,
    "is_finished": true,
    // ...
  }
}


GET /autorouting/jobs/get_output?autorouting_job_id=1234567890

RESPONSE:

{
  "autorouting_job_output": {
    "output_pcb_traces": [
      // ...
    ]
  }
}
```

## Additional Configuration

Additional configuration parameters can be passed to either the `/autorouting/jobs/create`
endpoint or the `/autorouting/solve` endpoint to configure the autorouter.

| Parameter | Example Value | Description |
| --------- | ------------- | ----------- |
| `display_name` | `"Nine-key Macropad"` | A display name for the autorouting job. Useful for debugging! |
| `provider` | `"freerouting"` | The autorouting algorithm to use |
| `subcircuit_id` | `"subcircuit_source_group_1"` | To support subcircuit autorouting, you must accept this parameter and only solve for the subset of routes within the subcircuit. |
</file>

<file path="docs/web-apis/compile-api.md">
---
title: Compile API
sidebar_position: 2
---

# compile.tscircuit.com

Compiles tscircuit user code into [Circuit JSON](https://github.com/tscircuit/circuit-json).

## API Usage

The API provides endpoints to compile tscircuit JSX/TSX code into circuit JSON.

### Compile Endpoint

#### `GET /compile`

Compile tscircuit code via GET request with compressed code parameter.

```http
GET /compile?code={compressed_code}
```

- `code`: Compressed Base64 string of tscircuit JSX/TSX code (generated using `@tscircuit/create-snippet-url`)
- Alternatively, you can use `fs_map` parameter with a compressed JSON object mapping filenames to code

**Example using fetch:**

```javascript
import { getCompressedBase64SnippetString } from "@tscircuit/create-snippet-url"

const circuitCode = `
export default () => (
  <resistor name="R1" resistance="1k" />
)`

const compressedCode = getCompressedBase64SnippetString(circuitCode)
const response = await fetch(
  `https://compile.tscircuit.com/api/compile?code=${encodeURIComponent(
    compressedCode
  )}`
)
const data = await response.json()
// data.circuit_json contains the compiled circuit
```

The response also includes a `logs` array detailing events during the compile process. The first entry records the version of `tscircuit` used for the build.

#### `POST /compile`

Compile tscircuit code via POST request with an filesystem map.

```http
POST /compile
Content-Type: application/json

{
  "fs_map": {
    "user-code.tsx": "export default () => <resistor name=\"R1\" resistance=\"1k\" />"
  }
}
```

- Request body should contain a JSON object with an `fs_map` property
- `fs_map` is an object mapping filenames to their content as strings

**Example using fetch:**

```javascript
const response = await fetch("https://compile.tscircuit.com/api/compile", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fs_map: {
      "user-code.tsx": `
        export default () => (
          <capacitor name="C1" capacitance="10uF" />
        )
      `,
    },
  }),
})
const data = await response.json()
// data.circuit_json contains the compiled circuit
```

### Health Check

`GET /api/health`

Returns a status indicating if the service is operational. The response also includes the version of `tscircuit` used by the compile server:

```json
{
  "ok": true,
  "compile_server_health": { "tscircuit_version": "<version>" }
}
```

## Development

```bash
bun run start
```
</file>

<file path="docs/web-apis/datasheet-api.md">
---
title: Datasheet API
sidebar_position: 4
---

The tscircuit Datasheet API allows you to store and retrieve parsed datasheet information for electronic components.

Use `https://api.tscircuit.com` as the base URL for these endpoints.

## `/datasheets/get`

Retrieves stored datasheet information. You can look up a datasheet either by its UUID or by the chip name.

```http
GET /datasheets/get?chip_name=<name>
POST /datasheets/get { "datasheet_id": "<uuid>" }
```

**Parameters**
- `datasheet_id` – Optional UUID of the datasheet.
- `chip_name` – Optional string chip identifier.

**Response**
```json
{
  "datasheet": {
    "datasheet_id": "<uuid>",
    "chip_name": "<name>",
    "datasheet_pdf_urls": ["https://..."],
    "pin_information": [ /* pin objects */ ]
  }
}
```

### Pin Information Schema

Each entry in `pin_information` describes one pin on the device and has the
following structure:

```json
{
  "pin_number": "1",
  "name": ["VCC"],
  "description": "Power supply for the device.",
  "capabilities": ["power"]
}
```

`pin_number` is always a string and may include alphanumeric values (e.g. `"1"`
or `"A1"`). The `name` array contains all aliases for the pin. `description` is
a human‑readable explanation of the pin's function and `capabilities` enumerates
how the pin can be used.

### Example Response Snippet

Below is an excerpt from the RP2040 datasheet entry:

```bash
$ curl https://api.tscircuit.com/datasheets/get?chip_name=RP2040 | jq '.datasheet.pin_information[:1]'
[
  {
    "name": [
      "IOVDD"
    ],
    "pin_number": "1",
    "description": "Power supply for digital GPIOs, nominal voltage 1.8V to 3.3V.",
    "capabilities": [
      "Power Supply (Digital IO)"
    ]
  }
]
```

## `/datasheets/create`

Creates a new datasheet entry so it can later be parsed and fetched.
This endpoint requires an API token. You can print your token with the [`tsci auth print-token`](../command-line/tsci-auth-print-token.md) command.

```http
POST /datasheets/create
{
  "chip_name": "<name>",
}
```

**Response**
```json
{
  "datasheet_id": "<uuid>",
  "chip_name": "<name>",
  "datasheet_pdf_urls": null,
  "pin_information": null
}
```

After creation the datasheet will be processed asynchronously to find pdf urls and extract pin information.
</file>

<file path="docs/web-apis/datasheet-sdk.md">
---
title: Retrieve datasheets with the SDK
sidebar_position: 5
---

The [`@tscircuit/api`](https://github.com/tscircuit/api) package provides a
convenient client for interacting with the Datasheet API. To follow the examples
below you'll need an API token which can be obtained with the
[`tsci auth print-token`](../command-line/tsci-auth-print-token.md) command.

## Installation

```bash
npm install @tscircuit/api
```

## Basic usage

```ts
import { TscircuitApiClient } from "@tscircuit/api"

const client = new TscircuitApiClient({ apiKey: "your-api-key" })
```

### Create a datasheet

```ts
const datasheet = await client.datasheets.create({ chip_name: "RP2040" })
```

### Get a datasheet

Retrieve by id or by chip name:

```ts
// by id
const dsById = await client.datasheets.get({ datasheet_id: datasheet.datasheet_id })

// by chip name
const dsByName = await client.datasheets.get({ chip_name: "RP2040" })
```

### Convenience helper

`findCreateWait` will look up a datasheet by `chip_name`, create it if needed and
then poll until the `pin_information` field is populated.

```ts
const processed = await client.datasheets.findCreateWait({ chip_name: "RP2040" })
```

The promise resolves when processing completes or throws on timeout.

### Example response

A successful call to `datasheets/get` returns all datasheet fields. Below is an
abbreviated example for the RP2040:

```json
{
  "datasheet": {
    "datasheet_id": "2a51fc64-5154-4513-ad7c-29429bdc973e",
    "chip_name": "RP2040",
    "datasheet_pdf_urls": [
      "https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf"
    ],
    "pin_information": [
      {
        "name": ["IOVDD"],
        "pin_number": "1",
        "description": "Power supply for digital GPIOs, nominal voltage 1.8V to 3.3V.",
        "capabilities": ["Power Supply (Digital IO)"]
      }
    ]
  }
}
```
</file>

<file path="docs/web-apis/image-generation-api.mdx">
# Image Generation API

The tscircuit image generation API allows you to dynamically create visual representations of your circuits in various formats. This guide explains how to use the dedicated subdomains for generating SVGs, PNGs, and 3D renderings of your circuits.

## Get images for a package

Every package has images automatically generated for it. You can place these images
in your README, website, or anywhere you'd like to display the latest version of your circuit.

You can access the images at the following URLs:

| View Type | URL |
|-----------|-----|
| **PCB** | `https://api.tscircuit.com/snippets/images/<author>/<package name>/pcb.png` |
| **Schematic** | `https://api.tscircuit.com/snippets/images/<author>/<package name>/schematic.png` |
| **3D** | `https://api.tscircuit.com/snippets/images/<author>/<package name>/3d.png` |

Here are examples of the three image types available for the "seveibar/nine-key-keyboard" package:

| PCB | Schematic | 3D |
|-----|-----------|-----|
| ![PCB](https://api.tscircuit.com/snippets/images/seveibar/nine-key-keyboard/pcb.png) | ![Schematic](https://api.tscircuit.com/snippets/images/seveibar/nine-key-keyboard/schematic.png) | ![CAD](https://api.tscircuit.com/snippets/images/seveibar/nine-key-keyboard/3d.png) |



## Generate Images for any Code String

The recommended way to generate image URLs is to use the official `@tscircuit/create-snippet-url` package:

```bash
npm install @tscircuit/create-snippet-url
# or
bun add @tscircuit/create-snippet-url
```

This package handles URL encoding, compression, and proper formatting:

```javascript
import { createSvgUrl, createPngUrl } from '@tscircuit/create-snippet-url';

// Create a URL to view the PCB SVG
const svgUrl = createSvgUrl(
  `
export default () => (
  <board width="10mm" height="10mm">
    <resistor resistance="1k" footprint="0402" name="R1" schX={3} pcbX={3} />
  </board>
)
`,
  "pcb" // View type: "pcb", "schematic", or "3d"
);

// Create a PNG URL
const pngUrl = createPngUrl(
  tscircuitCode,
  "pcb" // View type: "pcb", "schematic", or "3d"
);
```

## SVG Generation API

The `svg.tscircuit.com` subdomain provides endpoints for generating SVG renderings of your circuits.

### Basic Usage

```
https://svg.tscircuit.com/?svg_type=<type>&code=<compressed-code>
```

### Parameters

| Parameter | Description | Required |
|-----------|-------------|----------|
| `svg_type` | View type: `pcb`, `schematic`, or `3d` | Yes |
| `code` | Compressed and encoded circuit code | Yes |
| `width` | Width of the SVG in pixels | No (default: 800) |
| `height` | Height of the SVG in pixels | No (default: 600) |
| `dark_mode` | Enable dark mode rendering | No (default: false) |
| `zoom` | Zoom level for the view | No |
| `download` | Set to "true" to download as file | No |

### Direct SVG Generation Example

```javascript
import { getCompressedBase64SnippetString } from '@tscircuit/create-snippet-url';

const tscircuitCode = `
export default () => (
  <board width="10mm" height="10mm">
    <resistor resistance="1k" footprint="0402" name="R1" schX={3} pcbX={3} />
  </board>
)`;

const compressedCode = getCompressedBase64SnippetString(tscircuitCode);
const svgUrl = `https://svg.tscircuit.com/?svg_type=pcb&code=${encodeURIComponent(compressedCode)}`;
```

## PNG Generation API

The `png.tscircuit.com` subdomain allows you to generate PNG renderings of your circuits.

### Basic Usage

```
https://png.tscircuit.com/?view=<type>&code=<compressed-code>
```

### Parameters

| Parameter | Description | Required |
|-----------|-------------|----------|
| `view` | View type: `pcb`, `schematic`, or `3d` | Yes |
| `code` | Compressed and encoded circuit code | Yes |
| `width` | Width of the PNG in pixels | No (default: 800) |
| `height` | Height of the PNG in pixels | No (default: 600) |
| `scale` | Scale factor for rendering (for high-DPI) | No (default: 1) |
| `dark_mode` | Enable dark mode rendering | No (default: false) |
| `transparent` | Use transparent background | No (default: false) |
| `download` | Set to "true" to download as file | No |

## 3D Rendering API

For 3D renderings of PCBs, use the dedicated endpoints:

### Basic Usage

```
https://svg.tscircuit.com/?svg_type=3d&code=<compressed-code>
```

### Parameters

| Parameter | Description | Required |
|-----------|-------------|----------|
| `svg_type` | Must be set to `3d` | Yes |
| `code` | Compressed and encoded circuit code | Yes |
| `width` | Width of the rendering in pixels | No (default: 800) |
| `height` | Height of the rendering in pixels | No (default: 600) |
| `angle` | Camera angle in degrees | No (default: 45) |
| `zoom` | Zoom level | No (default: 1.0) |
| `show_components` | Show 3D components | No (default: true) |
| `wireframe` | Show wireframe rendering | No (default: false) |

### Example: Embedding a 3D View

```jsx
import React from 'react';
import { createSvgUrl } from '@tscircuit/create-snippet-url';

const Circuit3DViewer = ({ circuitCode }) => {
  const viewerUrl = createSvgUrl(circuitCode, "3d");
  
  return (
    <iframe 
      src={viewerUrl}
      width="800"
      height="600"
      style={{ border: 'none' }}
      title="3D Circuit Viewer"
    />
  );
};
```

## Browser Preview

You can also use the browser preview feature:

```javascript
import { createBrowserPreviewUrl } from '@tscircuit/create-snippet-url';

const previewUrl = createBrowserPreviewUrl(
  tscircuitCode,
  "pcb" // optional view type
);
```

## Code Format

The code format expected by all of these endpoints is a React component that exports a default function returning a circuit. For example:

```jsx
export default () => (
  <board width="20mm" height="20mm">
    <resistor resistance="1k" footprint="0402" name="R1" pcbX={0} pcbY={0} />
    <capacitor capacitance="10uF" footprint="0805" name="C1" pcbX={5} pcbY={5} />
    <trace from=".R1 > .pin1" to=".C1 > .pin1" />
  </board>
)
```

## Rate Limits and Authentication

Free usage of the image generation APIs is rate-limited. For production applications, consider:

1. Using an API key (contact support for details)
2. Caching generated images when possible
3. Self-hosting the rendering service for high-volume applications

## Best Practices

- Use the official `@tscircuit/create-snippet-url` package instead of manually constructing URLs
- Cache images when possible to reduce bandwidth and processing overhead
- Use appropriate image dimensions to minimize bandwidth
- For interactive applications, use lower quality/size during manipulation, then higher quality for final rendering
- When embedding in web applications, include width and height attributes to prevent layout shifts
</file>

<file path="docs/web-apis/ordering-api.mdx">
---
title: Ordering API
description: Public endpoints for creating and retrieving orders through the tscircuit API
sidebar_position: 3
---

## Authentication

All ordering endpoints require a valid session. Include your authentication token or session cookie in every request.

### Create an Order

`POST /orders/create`

Creates a new order for a PCB circuit. Provide either a `package_release_id` or the full `circuit_json`. Optionally specify a `customs_category`.

```json
{
  "package_release_id": "string (uuid, optional)",
  "circuit_json": [ /* circuit JSON array, optional */ ],
  "customs_category": "string (optional)"
}
```

Either `package_release_id` or `circuit_json` must be supplied.

**Response**

```json
{
  "order": {
    "order_id": "string (uuid)",
    "account_id": "string (uuid)",
    "is_running": false,
    "is_started": false,
    "is_finished": false,
    "error": null,
    "has_error": false,
    "created_at": "string (ISO timestamp)",
    "started_at": "string (ISO timestamp or null)",
    "completed_at": "string (ISO timestamp or null)",
    "circuit_json": [ /* circuit JSON array */ ],
    "customs_category": "string"
  }
}
```

Example request:

```bash
curl -X POST https://api.tscircuit.com/orders/create \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"package_release_id": "123e4567-e89b-12d3-a456-426614174000"}'
```

### Get Order Details

`GET /orders/get` or `POST /orders/get`

Fetch details of a specific order.

Request parameters (query or JSON body):

```json
{
  "order_id": "string (uuid)"
}
```

**Response**

```json
{
  "order": {
    "order_id": "string (uuid)",
    "account_id": "string (uuid)",
    "is_running": false,
    "is_started": false,
    "is_finished": false,
    "error": null,
    "has_error": false,
    "created_at": "string (ISO timestamp)",
    "started_at": "string (ISO timestamp or null)",
    "completed_at": "string (ISO timestamp or null)",
    "circuit_json": [ /* circuit JSON array */ ],
    "customs_category": "string"
  }
}
```

Example request:

```bash
curl -X GET "https://api.tscircuit.com/orders/get?order_id=123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer <token>"
```

## Additional Notes

- Timestamps are returned in ISO-8601 format.
- Errors follow this structure:

```json
{
  "error_code": "string",
  "message": "string"
}
```
## Order Quote API

The Order Quote API lets you retrieve pricing quotes for PCB orders. Quotes include component pricing, PCB costs, shipping options, and overall totals.

### Endpoint

#### Create an Order Quote
`POST /order_quotes/create`

Creates a new order quote for a PCB package release. Currently only the `jlcpcb` vendor is supported.

Request body:

```json
{
  "package_release_id": "string (UUID)",
  "vendor_name": "jlcpcb"
}
```

Response example:

```json
{
  "order_quote_id": "string (UUID)"
}
```

#### Get an Order Quote
`GET /order_quotes/get?order_quote_id={uuid}` or `POST /order_quotes/get`

Request body:

```json
{
  "order_quote_id": "string (UUID)"
}
```

Response example:

```json
{
  "order_quote": {
    "order_quote_id": "123e4567-e89b-12d3-a456-426614174000",
    "vendor_name": "jlcpcb",
    "is_completed": true,
    "quoted_components": [
      {
        "manufacturer_part_number": "CC0603KRX7R9BB101",
        "quantity": 10,
        "total_cost": 0.5,
        "available": true
      }
    ],
    "bare_pcb_cost": 20.0,
    "shipping_options": [
      { "carrier": "dhl", "service": "express", "cost": 9.5 }
    ],
    "total_cost_without_shipping": 25.0
  }
}
```

Returns `404` if the quote is not found or not accessible.

## See Also

- [Authentication Guide](#)
</file>

<file path="docs/web-apis/the-registry-api.md">
---
title: Registry API
sidebar_position: 1
---

The tscircuit Registry API is an extension of the NPM Registry API that allows for additional features, such as building Circuit JSON in the cloud, automatic bundling to ESM and CommonJS, and more versioning automations.

## Using the tscircuit NPM Registry

The [regular public NPM registry API](https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md) is available via `npm.tscircuit.com`. You can install endpoints from this registry
by adding the following line to your `.npmrc` (or in
any project with a `package.json` file)

```
@tsci:registry=https://npm.tscircuit.com
```

This line says "any package starting with @tsci should
go to the tscircuit registry instead of the npm registry"

So you can now do `bun add @tsci/seveibar.usb-c-flashlight` to install that
circuit to your npm project!

## tscircuit Package Format

Every tscircuit package is in the format `@tsci/<author>.<package_name>` to
avoid conflicts with other npm packages.

## Advanced Bundling Endpoints

tscircuit runs an ESM and CJS bundling service, you can use these
services to get a bundled version of any circuit, this is great
for dynamic loading and execution, e.g. we use it in our [tscircuit/import](https://github.com/tscircuit/import) module!

## Advanced Registry Endpoints

You can use your tscircuit CLI token to use the advanced API at `https://registry-api.tscircuit.com`.

You can get a tscircuit auth token with `tsci auth print-token`. After you get this token, you just need to add the `Authorization: Bearer ${token}` header to each API request.

The following endpoints are available:

| Endpoint                   | Purpose                                                      |
| -------------------------- | ------------------------------------------------------------ |
| `/package_files/list`      | List all the files in a package                              |
| `/package_files/create`    | Add a file to a package                                      |
| `/package_files/download`  | Download a file from a package                               |
| `/packages/search`         | Search for a package                                         |
| `/packages/list`           | List your packages                                           |
| `/package_releases/create` | Create a new release (version) of a package                  |
| `/package_releases/update` | Update a package release, e.g. to lock it from modifications |
| `/package_releases/get`    | Get a package release                                        |
| `/package_releases/list`   | List package releases for a package                          |

More information about our Advanced Registry API is coming soon, including a full OpenAPI specification!

## Advanced Autorouting Endpoints

You can also use the registry to perform autorouting jobs for a
[Circuit JSON](https://github.com/tscircuit/circuit-json) file.

| Endpoint                       | Purpose                              |
| ------------------------------ | ------------------------------------ |
| `/autorouting/jobs/create`     | Create a new autorouting job         |
| `/autorouting/jobs/get`        | Get the status of an autorouting job |
| `/autorouting/jobs/get_output` | Get the output of an autorouting job |

## Endpoint Documentation

### `/packages/search`

Search for a package by name.

```
POST /packages/search
{
  "query": "555timer"
}

RESPONSE:

{
  "packages": [
    {
      "name": "@tsci/555timer",
      "version": "1.0.0",
      "description": "A 555 timer circuit"
    }
  ]
}
```
</file>

<file path="CLAUDE.md">
# tscircuit docs - Development Guidelines

## Commands
- **Start development server**: `bun run start`
- **Build site**: `bun run build`
- **Serve built site**: `bun run serve`
- **Type check**: `bun run typecheck`
- **Format code**: `bunx @biomejs/biome format --write .`
- **Lint code**: `bunx @biomejs/biome lint .`

## Code Style
- **Formatting**: Use Biome formatter with space indentation
- **Imports**: Use organized imports (auto-sortable by Biome)
- **JSX**: Use double quotes for JSX attributes
- **Semicolons**: Prefer to omit except when necessary
- **Naming**: Use kebab-case for filenames
- **Types**: TypeScript is used throughout, explicit "any" is allowed
- **Error handling**: Follow React/Docusaurus error boundary patterns
- **Markdown**: Follow standard Docusaurus MDX patterns

## Documentation Standards
- Keep documentation concise and example-focused
- Include working code examples where possible
- Use proper heading hierarchy (h1 → h2 → h3)
- Images should include descriptive alt text
</file>

<file path="README.md">
# [docs.tscircuit.com](https://docs.tscircuit.com)

This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.

Run `bun i` and `bun run start` to start a local development server.
</file>

<file path="docs/advanced/ai-context.mdx">
---
title: AI Context
description: Learn how to use our AI context to help you design with tscircuit
---

import YouTubeEmbed from '../../src/components/YouTubeEmbed';

## Overview

<YouTubeEmbed youtubeId="Uve8xaVsPUQ" />

You can drop our AI context into your Claude or OpenAI project by downloading
the [`ai.txt`](https://docs.tscircuit.com/ai.txt) file and dropping it into your project.

This will teach Claude and OpenAI about tscircuit so it can help you design
boards or access tricky or hidden pieces of the documentation!

You can also use [chat.tscircuit.com](https://chat.tscircuit.com) for a prebuilt version of the AI.
It contains live preview for a great development experience.
</file>

<file path="docs/command-line/tsci-init.md">
---
title: tsci init
sidebar_position: 0
description: Initialize a new TSCircuit project
---

`tsci init` bootstraps a fresh project in the current directory. It creates the
basic files needed to start developing a board, including:

- `index.tsx` – your main circuit entrypoint
- `package.json` with the required dependencies
- `tsconfig.json`
- `.gitignore` and other configuration files

You can run the command interactively or pass `-y` to accept all defaults.

```bash
mkdir my-circuit
cd my-circuit
# Initialize with prompts
tsci init
# or skip prompts
tsci init -y
```

After initialization you will see a directory structure similar to the following:

```text
my-circuit/
├─ index.tsx
├─ package.json
├─ tsconfig.json
└─ tscircuit.config.json
```

import tsciInitImage from "../../static/img/tsci-init.png";
import ImageWithCaption from "../../src/components/ImageWithCaption";

<ImageWithCaption
  src={tsciInitImage}
  alt="tsci init output"
  caption="Terminal output from a successful tsci init"
/>

Next, run `tsci dev` to start the development server and view your circuit in the
browser.
</file>

<file path="docs/elements/capacitor.mdx">
---
title: <capacitor />
sidebar_position: 3
description: >-
  A `<capacitor />` stores electrical energy in an electric field. Capacitors
  are commonly used for filtering, energy storage, and timing circuits. Unlike
  resistors, capacitors can be polarized (like electrolytic capacitors) or
  non-polarized (like ceramic capacitors).
---

## Overview

A `<capacitor />` stores electrical energy in an electric field. Capacitors are commonly used for filtering, energy storage, and timing circuits. Unlike resistors, capacitors can be polarized (like electrolytic capacitors) or non-polarized (like ceramic capacitors).

A capacitor element has two pins. Polarized capacitors must be placed with correct orientation to avoid damage.

When specifying a capacitor, you'll need to provide a footprint string (like `0402` or `0805`) and capacitance value. Popular capacitor types and sizes can be found at [jlcsearch](https://jlcsearch.tscircuit.com/capacitors/list).


<CircuitPreview
  defaultView="schematic"
  code={`

  export default () => (
    <capacitor
      name="C2"
      footprint="axial_p5mm"
      capacitance="10μF"
      polarized
    />
  )

  `}
/>

## Pins

A capacitor has the following pins and aliases:

| Pin # | Aliases (Polarized) | Description |
| ---------- | ------- | ----------- |
| pin1 | pos, anode, left | The positive terminal (required for polarized capacitors) |
| pin2 | neg, cathode, right | The negative terminal (must be connected properly for polarized caps) |

:::warning
For polarized capacitors, you must connect the positive and negative pins correctly. Reversing polarity can cause capacitor failure or even explosion!
:::

## Specifications

Capacitors can be configured with these key properties:

- **capacitance** - The capacitance value specified as a string e.g. `"100nF"` or `"2.2μF"`
- **voltageRating** - Maximum voltage the capacitor can handle e.g. `"25V"`
- **tolerance** - Capacitance tolerance percentage e.g. `"±10%"`
- **temperatureCoefficient** - Temperature stability specification e.g. `"X7R"`
- **equivalentSeriesResistance** - ESR value for critical applications e.g. `"0.5Ω"`

## Automatic Part Selection

Like resistors, tscircuit will automatically select suitable capacitor parts based on your specifications through the [platform parts engine](../guides/platform-configuration.md). For specialized capacitors (e.g., low ESR, high voltage), you may want to specify `supplierPartNumbers` explicitly.

## Schematic Orientation

Polarized capacitors can display their positive and negative pins in different orientations. Use the `schOrientation` property to control the symbol orientation instead of manually setting `schRotation`.

Valid orientation values are:

- `horizontal`
- `vertical`
- `pos_left`
- `pos_right`
- `pos_top`
- `pos_bottom`
- `neg_left`
- `neg_right`
- `neg_top`
- `neg_bottom`

```tsx
<capacitor
  name="C1"
  capacitance="1uF"
  polarized
  schOrientation="pos_left"
  schX={0}
  schY={0}
  connections={{ pos: "net.POS", neg: "net.NEG" }}
/>```
</file>

<file path="docs/guides/layout-properties.mdx">
---
title: Using Layout Properties
description: >-
    There are many ways to layout your schematic and PCB with tscircuit including
    automatic layout and manual edits. In this
    article we'll discuss how to programmatically lay out a board using layout properties like
    `schX`/`schY` and `pcbX` and `pcbY`
---

## Overview

There are many ways to layout your schematic and PCB with tscircuit including
[automatic layout](./automatic-layout.mdx) and [manual edits](./manual-edits.mdx). In this
article we'll discuss how to programmatically lay out a board using layout properties like
`schX`/`schY` and `pcbX` and `pcbY`

All position properties default to `mm` but you can pass a string with any distance
unit. For example, `pcbX="0.1in"` is the same as `pcbX="2.54mm"`.


## PCB Layout Properties

The following properties can be placed on nearly any tscircuit element to control
its position on the board:

| Property | Description | Example Value |
| -------- | ----------- | ------------- |
| `pcbX`   | Set the center X position of the element | `0` |
| `pcbY`   | Set the center Y position of the element | `0` |
| `pcbRotation` | Set the rotation of the element | `"90deg"` |

Here's an example of moving a resistor with default properties versus custom
layout properties:


<CircuitPreview defaultView="pcb" code={`

export default () => (
    <resistor
      name="R1"
      footprint="0805"
      resistance="1k"
    />
)

`} />

<CircuitPreview defaultView="pcb" code={`

export default () => (
    <resistor
      name="R1"
      footprint="0805"
      resistance="1k"
      pcbX="3mm"
      pcbY="2.5mm"
      pcbRotation="90deg"
    />
)

`} />

:::info
To see positions and measure distances in the PCB Viewer, you can press "d" on
your keyboard to toggle measurement mode.

<figure>
<img src="/img/pcb-dimension-mode.png" alt="PCB Viewer Measurement Mode" />
<figcaption>PCB Viewer Measurement Mode, press "d" to toggle when using the PCB tool</figcaption>
</figure>

:::



## Schematic Layout Properties

The following properties can be placed on a schematic element to control its position on the board:

| Property | Description | Example Value |
| -------- | ----------- | ------------- |
| `schX`   | Set the center X position of the element | `0` |
| `schY`   | Set the center Y position of the element | `0` |
| `schRotation` | Set the rotation of the element | `"90deg"` |
| `schOrientation` | Orient the symbol based on positive/negative pin direction. Accepts `"horizontal"`, `"vertical"`, `"pos_left"`, `"pos_right"`, `"pos_top"`, `"pos_bottom"`, `"neg_left"`, `"neg_right"`, `"neg_top"`, or `"neg_bottom"`. | `"pos_left"` |

Here's an example of moving a resistor with default properties versus custom
schematic layout properties:

<CircuitPreview defaultView="schematic" code={`

export default () => (
    <resistor
      name="R1"
      footprint="0805"
      resistance="1k"
    />
)

`} />

<CircuitPreview defaultView="schematic" code={`

export default () => (
    <resistor
      name="R1"
      footprint="0805"
      resistance="1k"
      // schX="3mm"
      // schY="2.5mm"
      schRotation="90deg"
    />
)

`} />
</file>

<file path="docs/guides/manual-edits.mdx">
---
title: Manual Edits
---
import YouTubeEmbed from "../../src/components/YouTubeEmbed"

It can be cumbersome to programmatically define the locations of every component
on the PCB and schematic, but [automatic layout](./automatic-layout.mdx) can
be too uncontrolled. Manual edits allow you to use a schematic or PCB viewer
to drag and drop components.

:::info
Are you trying to programmatically define the locations of components? Check out
[using layout properties](./layout-properties.mdx) instead.
:::

Every time you drag a component, a file conventionally called `manual-edits.json`
is edited with your edits. This manual edits file is imported and can be given
as the `manualEdits` prop to a `<board />` or `<subcircuit />`

## Creating Manual Edits with a GUI

Each GUI features an "edit button" to turn on an editing mode. After you turn
on the editing mode, you can drag and drop components and your edits will
automatically edit the `manual-edits.json` file.

### Creating Manual Edits in the Schematic Viewer

In the top-right corner there is a pencil edit button. This turns on the edit
mode.

<YouTubeEmbed youtubeId="I4nH7D4K86I" />

### Creating Manual Edits in the PCB Viewer

The PCB Viewer features two edits modes:

- Edit Trace Mode
- Move Components Mode

You can find both of them by hovering over the PCB viewer.

<YouTubeEmbed youtubeId="KxLBWpUWB2M"/>

### Troubleshooting manual edits not being applied

Usually if manual edits aren't being applied, it's because you haven't imported
the `manual-edits.json` file. On the [tscircuit.com editor](https://tscircuit.com),
you'll get a warning that automatically edits your code to insert the import.

If you're editing locally, add the following lines:

```tsx
import manualEdits from "./manual-edits.json"

export default () => (
  //                                VVVV add this prop!
  <board width="10mm" height="10mm" manualEdits={manualEdits}>
    {/* ... */}
  </board>
)
```

If you're still not seeing your manual edits, select the `manual-edits.json`
file from the tscircuit editor or find the file on your filesystem. Make sure
that it changes when you drag'n'drop components.


## The Manual Edits Format


The manual edits file's format is defined in [this typescript file](https://github.com/tscircuit/props/blob/main/lib/manual-edits/manual_edits_file.ts), it contains 3 main types of edits:

- **pcb_placements** - Component positions on the PCB
- **manual_trace_hints** - "Hints" indicating where PCB traces should go
- **schematic_placements** - Component positions on the schematic

Here's an example of a manual edits file:

```json
{
  pcb_placements: [
    {
      "selector": "R1",
      "center": {
        "x": 0,
        "y": 6.869495369849336
      },
      "relative_to": "group_center",
      "_edit_event_id": "0.037205222437411756"
    }
  ]
  manual_trace_hints: []
  schematic_placements: [
    {
      selector: "R1",
      center: { x: 5, y: 5 },
      relative_to: "group_center",
    },
    {
      selector: "C1",
      center: { x: -5, y: -5 },
      relative_to: "group_center",
    },
  ]
}
```
</file>

<file path="docs/guides/using-sel-references.mdx">
---
title: Using "sel" References
---

The `sel` object is a special import that allows you to easily reference
components with a more type-safety than a string. It can also be more ergonomic
than typing out a [port selector](./port-and-net-selectors.md).

There are many ways to use `sel`, the most common are:

- [Conventional References `sel.C1.pos`](#conventional-references)
- [Type-Safe Chip Pin References `sel.U1(MyChip).VCC`](#type-safe-chip-pin-references)
- [Type-Safe Module References `sel.M1(MyModule).VCC` or `sel.M1(MyModule).U1.D0`](#type-safe-module-references)

## Conventional References

Conventional references are the most basic way to use `sel`. There is a large,
built-in mapping of conventional strings to reference components. When you
start typing `sel.`, you will see a list of the available references.


<CircuitPreview defaultView="code" code={`
import { sel } from "tscircuit"

export default () => (
  <board width="10mm" height="10mm">
    <resistor
      resistance="1k"
      footprint="0402"
      name="R1"
    />
    <capacitor
      capacitance="1000pF"
      footprint="0402"
      name="C1"
    />
    <trace from={sel.R1.pin1} to={sel.C1.pos} />
  </board>
)
`} />


The `sel` can be thought of as a very large mapping of conventional strings.

Here are some `sel` expressions and their corresponding string:

```tsx
import { sel } from "tscircuit"

sel.R1.pin1
// ".R1 > .pin1"

sel.C1.pos
// ".C1 > .pos"

sel.net.GND
// "net.GND"

sel.U1.GPIO1
// ".U1 > .GPIO1"
```

## Type-Safe Chip Pin References

The `sel` object provides enhanced type safety when working with chips by allowing you to reference pins with proper TypeScript types. There are two advanced ways to use `sel` with chips:

You can pass a chip component to `sel` to get fully type-safe pin accessors:

```tsx
import { MyChip } from "./my-chip"

const selectors = {
  U1: sel.U1(MyChip)
}

export const MyChipWithSomeTraces = () => (
  <group>
    <MyChip name="U1" />
    <trace from={selectors.U1.VCC} to="net.VCC" />
    <trace from={selectors.U1.GND} to="net.GND" />
  </group>
)
```

:::info
In order for type-safe selectors to work, you need to define your chip component
with a `ChipProps` type, like this:

```tsx
import { ChipProps } from "tscircuit"

const pinLabels = {
  pin1: "VCC",
  pin2: "GND",
  pin3: "DATA1",
  pin4: "DATA2",
} as const

const MyChip = (props: ChipProps<typeof pinLabels>) => (
  <chip {...props} pinLabels={pinLabels} />
)
```
:::

`sel.U1(MyChip).VCC` is the same as `sel.U1.VCC`,
however, when we pass `MyChip` to `sel.U1`, TypeScript will check that `MyChip`
has a pin called `VCC` and will error if it doesn't.

```tsx
import { sel } from "tscircuit"
import { MyChip } from "./my-chip"

sel.U1(MyChip).VCC
// ".U1 > .VCC"

sel.U1(MyChip).GND
// ".U1 > .GND"

// TypeScript will error on non-existent pins!
// sel.U1(MyChip).DOES_NOT_EXIST -> ERROR!
```

## Type-Safe Module References

Similarly, you can use `sel` with modules that define `connections` or `selectors` in their props. This provides type-safety for accessing the exposed ports or nested selectors of a module instance.

### Using `sel` with `connections` prop

If a module defines a `connections` prop, you can pass the module component to `sel` to get type-safe accessors for its connections:

```tsx
import { sel } from "tscircuit"

// Define a simple module that uses the `connections` prop
const MyModuleWithConnections = (props: {
  name: string
  connections: {
    GND: string
    VCC?: string // Optional connection
  }
}) => (
  <group>
    <resistor name="R1" resistance="1k" connections={{ GND: props.connections.GND }} />
    {/** etc. **/}
  </group>
)

const selM1 = sel.M1(MyModuleWithConnections)

selM1.GND // Returns ".M1 > .GND"
selM1.VCC // Returns ".M1 > .VCC"

// TypeScript will error on non-existent connection keys!
// selM1.INVALID_KEY // TypeScript error!
```

### Using `sel` with `selectors` prop

If a module defines a `selectors` prop, you can pass the module component to `sel` to get type-safe accessors for its nested selectors and their connections:

```tsx
import { sel } from "tscircuit"

// Define a simple module that uses the `selectors` prop
const MyModuleWithSelectors = (props: {
  name: string
  selectors: {
    U1: { GND: string; VCC?: string }
    R1: { pin1: string; pin2: string }
  }
}) => (
  <group>
    <chip name="U1" connections={props.selectors.U1} />
    <resistor name="R1" resistance="1k" connections={props.selectors.R1} />
  </group>
)

const selM2 = sel.M2(MyModuleWithSelectors)

selM2.U1.GND // Returns ".M2 > .U1 > .GND"
selM2.U1.VCC // Returns ".M2 > .U1 > .VCC"
selM2.R1.pin1 // Returns ".M2 > .R1 > .pin1"
selM2.R1.pin2 // Returns ".M2 > .R1 > .pin2"

// TypeScript will error on non-existent selector keys!
// selM2.U2 // TypeScript error!

// TypeScript will error on non-existent connection keys within a selector!
// selM2.U1.INVALID_KEY // TypeScript error!
```

## Custom Usage

### Generic Pin Selectors (no chip needed!)

You can also use TypeScript generics to define custom pin types directly:

```tsx
import { sel } from "tscircuit"

// Define custom pin types using generics
const selU2 = sel.U2<"custompin1" | "custompin2">()

selU2.custompin1 // Returns ".U2 > .custompin1"
selU2.custompin2 // Returns ".U2 > .custompin2"

// TypeScript will error on non-existent pins!
// selU2.doesnotexist // TypeScript error!
```

### Generic Net Selectors

You can also create custom net selectors using TypeScript generics:

```tsx
import { sel } from "tscircuit"

// Define custom net names using generics
const customNets = sel.net<"CUSTOMNET1" | "CUSTOMNET2">()

customNets.CUSTOMNET1 // "net.CUSTOMNET1"
customNets.CUSTOMNET2 // "net.CUSTOMNET2"

// TypeScript will error on non-existent nets!
// customNets.DOES_NOT_EXIST // TypeScript error!
```

### Collecting Typed Nets

You may want to group your typed nets alongside other reusable selectors:

```tsx
import { sel } from "tscircuit"

const selectors = {
  net: sel.net<"GND" | "VCC" | "V5">(),
  // ...other selectors
}

selectors.net.GND // "net.GND"
```

### Dynamic Reference Designators

You can call `sel` as a function to create selectors for any reference designator.
It's best to assign the resulting selector set to a variable so that you keep
type safety throughout your code:

```tsx
import { sel } from "tscircuit"
import { RP2040 } from "./rp2040"

const selU1 = sel.U1(RP2040)

// More explicit version for custom scenarios 
const selSJ1 = sel<"A" | "B" | "C">("SJ1")

selSJ1.A // Returns ".SJ1 > .A"
```


So `sel` is a more type-safe, conventional way of writing
[port selectors](./port-and-net-selectors.md).
</file>

<file path="docs/intro/quickstart-cli.md">
---
title: Quickstart CLI
sidebar_position: 4
description: >-
    The command line is the best way to use tscircuit. Using the CLI, you can just
    run `tsci dev` in a project and see previews of your circuit just like any
    other local development tool!
---

import YouTubeEmbed from '../../src/components/YouTubeEmbed';

## Overview

The command line is the best way to use tscircuit. Using the CLI, you can just
run `tsci dev` in a project and see previews of your circuit just like any
other local development tool!

<YouTubeEmbed youtubeId="faW4-M91rQQ" />

## Install the tscircuit CLI

You can install the tscircuit CLI by running `npm install -g @tscircuit/cli`.

## Create a new Project

First, create a new tscircuit project by running `tsci init`. This will create a new directory with all the necessary files to get started:

![tsci init result](../../static/img/tsci-init.png)

## Run the Development Server

Next, start the development server by running `tsci dev`. This will start a local server that automatically rebuilds your circuit when you make changes:

![tsci dev result](../../static/img/tsci-dev.png)

Go to https://localhost:3020. You can now see PCB, Schematic and 3D views of your circuit, which update in real-time as you make changes to your code.

![browser](../../static/img/pcb-runframe.png)

### Using the CLI Offline

To use the CLI offline, you need to disable the "Force Latest @tscircuit/eval" option in the file menu. Click on "File" in the top menu, then uncheck the "Force Latest @tscircuit/eval" option:

![Force eval option in file menu](../../static/img/force-eval.png)

## Pushing to the tscircuit Registry

<!-- TODO -->
Next, you push your project by running `tsci push`. This will push your project to your registry.
![tsci push result](../../static/img/tsci-push.png)

Go to your tscircuit account. You can now see PCB, Schematic and 3D views of your circuit in you registry. 
![browser](../../static/img/registry-snippet.png)

## Exporting to SVGs, PDF, or Fabrication Files

<!-- TODO -->

This section is coming soon!
</file>

</files>