component-search

---
name: component-search
description: Search for and add electronic components and reusable subcircuits to a Zener PCB project. Use when designing a board, module, or subsystem and you need a part package, a reusable module, or a component package that may already include application circuitry. Covers `pcb search` (registry:modules, registry:components, web:components) and `pcb new component` for importing web components into a workspace.
license: MIT
---

# Component Search

Find and add components and reusable subcircuits to a Zener project. Use this workflow any time you need a part or subcircuit that isn't already in the workspace or covered by stdlib generics.

## Hard Stop Before Manual Creation

If `pcb search` and `pcb new component` don't produce a usable part, don't fall back to manual component/symbol/footprint creation. Report what failed, offer manual creation as an option, and get explicit user confirmation. In interactive mode, prefer `ask`.

## Search Priority

Always search in this order. Move down only when the higher tier doesn't have what fits.

1. **`pcb search -m registry:modules <query> -f json`** — Reusable subcircuits and composed modules. Best option when the design work is already done.
2. **`pcb search -m registry:components <query> -f json`** — Component packages in the registry. These may range from generated signatures to richer packages with integrated application circuitry.
3. **`pcb search -m web:components <MPN> -f json`** — Diode's web component database (CSE, LCSC sources). Fallback: returns a `component_id` that must be imported with `pcb new component`.

If the user asks for a specific MPN, still try registry first before falling back to web.

## Search Tips

- **Registry search** is richly indexed — it supports MPN search, manufacturer name search, semantic/functional queries, and lexical keyword matching. Use descriptive queries freely: `"buck converter 3.3V"`, `"Texas Instruments LDO"`, `"USB-C connector"`.
- **Web components search is strict MPN-only.** Only use exact or partial manufacturer part numbers: `"TPS54331"`, `"STM32F103C8T6"`. Do NOT include descriptions, keywords, or functional terms in the query — they will cause the search to fail or return irrelevant results. Strip everything except the MPN.
- All commands output JSON with `-f json`. Parse results programmatically to evaluate options.
- Registry results include `dependencies` (what they use) and `dependents` (who uses them) for context.
- Web results include `model_availability` showing whether ECAD and STEP models are available. The same MPN may appear from multiple sources (DigiKey, CSE, LCSC) with different model availability; check all returned results before concluding models are unavailable.
- **Try multiple queries.** Parts go by different names — full MPN, base family, orderable variant, manufacturer alias. If the first search doesn't find what you need, try alternative names before giving up.
- Use `pcb doc --package <url>@<version>` to inspect a registry module's io/config interface before using it.

## Choosing Between Results

Pick when there's a clear winner. Present tradeoffs and ask only when genuinely ambiguous.

Selection heuristics in priority order:

1. **Functional fit** — does it meet the electrical requirements?
2. **ECAD + STEP availability** — strongly prefer results with both models available.
3. **Package** — prefer leadless packages (QFN, DFN, LGA, WLCSP) over leaded alternatives (SOIC, TSSOP, QFP) when multiple package options exist.
4. **Sourcing** — prefer in-stock parts. Check `availability` fields for stock counts and pricing.
5. **Source quality** — for web:components, prefer CSE source over LCSC.
6. **Registry adoption** — more `dependents` in registry results means more battle-tested.

## Using Registry Results

Registry modules and component packages (Flows 1 and 2) are used directly via `Module()` with the registry URL. Auto-dep handles `pcb.toml` updates automatically — just use the URL and build.

```python
# Component package with integrated application circuitry
LDO = Module("github.com/diodeinc/registry/components/AP2112Kx/AP2112Kx.zen")

LDO(
    name="LDO_3V3",
    VIN=vbus_5v0,
    VOUT=vdd_3v3,
    GND=gnd,
)
```

```python
# Component package from registry:components search
TPS54331 = Module("github.com/diodeinc/registry/components/TPS54331D/TPS54331D.zen")
```

Use `pcb doc --package <url>@<version>` to check available io/config before wiring into a design.

## Importing Web Components

Web component results (Flow 3) require an import step before use.

1. Search: `pcb search -m web:components <MPN> -f json`
2. Pick a result and extract its `component_id`, `part_number`, and `manufacturer`.
3. Import:

```bash
pcb new component --component-id <ID> --part-number <MPN> --manufacturer <MFR>
```

This downloads the symbol, footprint, and STEP model and generates a package into `components/<manufacturer>/<mpn>/`. Datasheet artifacts are placed under `docs/` in the component directory. The `.kicad_sym` file is the source of truth for the primitive component interface; the generated `.zen` file starts as an auto-generated signature and may later grow into a richer reusable design in the same package. If the component already exists in the workspace, it skips and reports the existing path.

4. Use the imported component via `Module()` with the local workspace path:

```python
ESP32 = Module("./components/Espressif_Systems/ESP32-S3-WROOM-1-N16R8/ESP32-S3-WROOM-1-N16R8.zen")
```

## Command Reference

### Search

```bash
# Reusable modules (fast, local index)
pcb search -m registry:modules <query> -f json

# Component packages (fast, local index)
pcb search -m registry:components <query> -f json

# Web component database (network, slower, MPN-ONLY queries)
pcb search -m web:components <MPN> -f json
```

### Import

```bash
# Import a web component into the workspace
pcb new component --component-id <ID> [--part-number <MPN>] [--manufacturer <MFR>]
```

### Inspect

```bash
# Read a registry package's io/config interface
pcb doc --package <url>@<version>
```

## Verifying Sourcing with `pcb bom`

After adding components to a design, use `pcb bom` to check sourcing and availability:

```bash
pcb bom boards/MyBoard/MyBoard.zen -f json
```

The JSON output is a list of BOM entries, each with:
- `designator`, `mpn`, `manufacturer`, `package`, `value`, `description`
- `availability` — per-entry sourcing data:
  - `us` / `global` — regional summary with `price`, `stock`, `alt_stock`
  - `offers` — individual distributor offers with `region`, `distributor`, `stock`, `price`

### Fixing BOM issues

- **"No house cap/resistor found"** warnings during build mean no pre-qualified generic part matches the spec. Adjust the value, package, or voltage rating, or specify an explicit `part=Part(mpn=..., manufacturer=...)` where appropriate.
- **Low stock or no offers** — search for alternative parts using the component search flows above, then update the design.
- **Checking availability** — look at `stock` counts across regions. Parts with zero stock and only `alt_stock` may have long lead times.