DOCSEARCHbyAlgolia
Submit Docs

pcb Toolchain

repository·main·Indexed 18 days ago

https://github.com/diodeinc/pcb

A command-line toolchain for circuit board design using Zener, a Starlark-based language. It manages the full lifecycle from schematic description and dependency management to generating KiCad layout files. The ecosystem includes specialized crates such as gerberx2 for Gerber X2 parsing and writing, ipc2581 for XML parsing and validation, pcb-eda for KiCad symbol library parsing, and pcb-layout for synchronizing Zener netlists with KiCad PCB files.

Tokens
115K
Snippets
358
Records
539
Agent score
58%

What's inside pcb

  1. Overview of pcb-diode-api

    main

    pcb-diode-api provides the internal service clients utilized by the PCB CLI. It acts as the interface for interacting with various backend services, including:

    • Authentication: Managing user identity and sessions.
    • Search: Querying components or data.
    • BOM Matching: Aligning Bill of Materials data.
    • Release Uploads: Handling the uploading of PCB releases.
    • Routing: Managing routing logic/services.
    • Remote Sandboxes: Interacting with isolated execution environments.

  3. Overview of the gerberx2 crate

    main

    The gerberx2 crate is a Rust library designed to parse and write Gerber X2 fabrication layers. It is built to preserve the ordered command stream and X2 attributes of a file while providing a high-level, typed interface for interacting with:

    • Apertures: Typed aperture definitions.
    • Graphics State: The current state of the drawing engine.
    • Graphical Objects: Individual elements like flashes, draws, arcs, and regions.

    Supported Gerber X2 Features

    • Fixed-format coordinates
    • Flashes, draws, arcs, and regions
    • Step-and-repeat blocks
    • Aperture macros and block apertures
    • Polarity changes
    • Attributes for files, apertures, and objects

    Implementation Details

    • Non-destructive Writing: The writer emits Gerber constructs without flattening native macros or block apertures, ensuring the output maintains the original structure.
    • Scope: This crate is a low-level library. It does not include a CLI, IPC-2581 conversion policies, or high-level export/comparison logic. Those features must be implemented by the consuming crate.

  4. Overview of pcb-docgen

    main

    pcb-docgen is a library crate designed to generate Markdown documentation for the pcb doc command. It works by extracting metadata from Zener package sources, specifically focusing on:

    • File docstrings
    • Module signatures
    • Exported library symbols

    Note that pcb-docgen is a library and does not provide its own standalone binary target; it is invoked via the pcb CLI tool.

  5. Use pcb-ui for terminal UI elements

    main

    pcb-ui is a utility crate providing terminal-based UI components used by the PCB CLI. It includes:

    • Spinners and Progress Bars: These write to stderr to avoid interfering with standard output.
    • Status Styles: Pre-defined text styles for terminal output.
    • Text Utilities: Helpers for width-aware truncation, padding, and alignment.
    • Input Handling: The suspend method allows hiding active indicators (like spinners) while the application prompts for user input.
    • Completion: Methods to consume/stop active indicators.

    To use the most common types, import pcb_ui::prelude.

    use pcb_ui::prelude::*;

  6. Parse KiCad symbol libraries with pcb-eda

    main

    The pcb-eda crate is used to parse KiCad symbol libraries into the EDA data model used by the PCB toolchain. It extracts and preserves symbols, pins, internal connectivity, sourcing metadata, and the original S-expression (if available).

    Key abstractions:

    • Symbol: Used to read a single-symbol .kicad_sym file.
    • SymbolLibrary: Used to read multi-symbol files or split .kicad_symdir directories.

    Note: This crate does not handle downloading EDA assets or generating Zener source.

  7. Use the Zener evaluator in browser applications via pcb-zen-wasm

    main
    pcb-zen-wasm provides a WebAssembly (Wasm) interface for the Zener evaluator, allowing browser-based applications to perform evaluations. The package is built and published as an npm package using wasm-pack via the bin/build-wasm-bundle.sh build script.

  8. Use the pcb ipc2581 command group

    main

    pcb-ipc2581-tools provides the pcb ipc2581 command group (aliased to pcb ipc) for exporting PCB data, generating fabrication panels, and managing BOMs.

    Available Commands

    CommandPurpose
    infoReport board, layer, drill, and stackup metadata.
    bomExport the bill of materials.
    cplExport component placement data.
    htmlExport an HTML board summary.
    outlineExport a KiCad-compatible DXF outline.
    renderRender one layer as terminal graphics, SVG, or PNG.
    dfmCheck generated Gerber geometry for narrow features.
    gerberExport fabrication layers and drill files.
    viewExport a filtered IPC-2581 function-mode document.
    board-array createCreate a rectangular board array.
    fab-panel createTile assembly panels into a supported fabrication panel size.
    edit bomAdd approved alternatives to BOM entries.

    Run pcb ipc2581 <command> --help to view specific arguments and output options.

  9. Overview of the Zener language

    main
    Zener is a domain-specific language (DSL) built on Starlark used for describing PCB schematics. It extends Starlark with hardware-specific primitives including components, symbols, nets, interfaces, physical quantities, and hierarchical circuit modules. The underlying language behavior is governed by the Starlark specification and starlark-rust type extensions.

  10. How cross-file identity is maintained during import

    main

    To ensure stability across hierarchical sheets and files, the importer does not use reference designators (e.g., R1, C1) to join records. Reference designators are unstable and can change or collide.

    Instead, the importer uses a KiCadUuidPathKey, which uniquely identifies an instance by combining the sheet UUID path and the symbol UUID:

    KiCadUuidPathKey = (sheetpath.tstamps, symbol_uuid)

    This allows the importer to correctly join schematic, netlist, and layout records even if designators are modified.

  11. Importing symbols and modules in Zener

    main

    Zener .zen files use two primary methods for bringing code into scope:

    1. Symbol imports: Use load() to bring specific functions or types into the current scope.
    2. Schematic modules: Use Module() to create instantiable subcircuits from external files.

    Import Paths

    • Local files: Use relative paths (e.g., ./utils.zen).
    • Stdlib: Use the @stdlib prefix (e.g., @stdlib/units.zen). This is managed by the toolchain; do not declare it in [dependencies].
    • Remote packages: Use the full package URL (e.g., code.diode.computer/diode/registry/...). Versions are not included in the import string but must be declared in pcb.toml.
    # Symbol imports
load("./utils.zen", "helper")
load("@stdlib/units.zen", "Voltage", "Resistance")

# Schematic modules
Resistor = Module("@stdlib/generics/Resistor.zen")
Resistor(name="R1", value="10k", P1=vcc, P2=gnd)

# Remote packages (version defined in pcb.toml)
TPS54331 = Module("code.diode.computer/diode/registry/components/TPS54331/TPS54331.zen")

  12. How the rectify solver model works

    main

    The rectify solver aligns STEP models to KiCad footprints using a multi-step geometric inference process:

    1. Data Loading: Reads pads, holes, and the STEP model (embedded or referenced).
    2. Tessellation: Converts the STEP model into triangles.
    3. Rotation Evaluation: Tests the 24 axis-aligned rotations supported by KiCad.
    4. Rasterization: Creates a 0.10 mm bottom-height image for each rotation.
    5. Feature Extraction: Identifies candidate contact or pin features based on footprint type:
      • SMD: Uses low model surfaces as contact features aligned with copper pads.
      • Through-hole (THT): Extracts connected pin islands from low model cross-sections and aligns them with connected drill holes.
      • Mixed: Uses hole alignment as the primary signal and pad contact as a secondary score.
    6. Scoring: Selects the highest-scoring rotation and translation. The solver penalizes poses with missing pad/hole coverage, contacts outside expected targets, or implausible support planes.