> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Schematics

> Upload and version EDA files, create hardware projects, inspect parsed connectivity, and reference schematic nets and parts inside chat prompts.

Upload schematic sources to give Embedder hardware context from the design itself. The parser extracts components, pins, nets, buses, interfaces, power domains, and functional blocks. Embedder then checks firmware assumptions against that parsed data.

## Upload to the current project

Select a project, then run:

```txt theme={"system"}
/upload-schematics
```

Choose at least one source file. The files are uploaded for parsing and copied into:

```txt theme={"system"}
.embedder/schematics/sources/
```

Parsed versions, history, and the latest design diff are stored beside the source directory. Generated KiCad companions from other EDA formats are stored in:

```txt theme={"system"}
.embedder/schematics/synthesized/
```

Each source file can be up to 100 MB.

## Supply a complete design

Upload a complete schematic set from one EDA tool at a time:

* **KiCad:** include every `.kicad_sch` sheet. Include `.kicad_pro` so Embedder can identify the root sheet. A `.kicad_pcb` file is optional.
* **Altium:** include the `.SchDoc` sheets. `.PrjPcb` and `.PcbDoc` files are optional.
* **Eagle:** include the `.sch` file. The `.brd` file is optional.
* **PADS:** upload the `.asc` netlist.
* **Xpedition:** upload the `.hkp` export.
* **EDIF:** upload one `.edf`, `.edn`, or `.eds` netlist.

Project and layout files alone do not contain the schematic connectivity required by the parser. A KiCad `.kicad_pro` or `.kicad_pcb`, Altium `.PrjPcb` or `.PcbDoc`, or Eagle `.brd` must accompany its schematic source.

For hierarchical KiCad designs, missing child sheets produce a partial netlist. Upload the root and every referenced child sheet together.

<Warning>
  Source files are flattened to their basenames in the project store. Two
  selected files with the same basename are rejected. Rename one before
  uploading.
</Warning>

## Create a project from schematics

You can create a project without selecting a platform from the catalog:

<Steps>
  <Step title="Open project creation">
    Run `/project` and choose to create a project.
  </Step>

  <Step title="Choose Upload schematics">
    Select **Upload schematics** at the top of the platform list.
  </Step>

  <Step title="Select the complete source set">
    Add the files for one supported EDA tool. Enter a project name when
    prompted.
  </Step>

  <Step title="Wait for parsing">
    Embedder creates the project, uploads the files, waits for parsed design
    data, and selects the new project.
  </Step>
</Steps>

The parser can match detected parts to platform and peripheral catalog entries. Unmatched integrated circuits remain available in the parsed component data.

## Add a custom platform

Choose **Add a platform** from the platform picker when your hardware is not in the catalog. Enter the platform name and attach at least one document or schematic file.

The flow creates a project and a custom platform component with manufacturer `Custom`. You can combine PDFs with supported schematic sources. Custom platform creation is available only when your account or organization enables custom components; otherwise Embedder shows the feature gate.

Use this route when the platform identity and its documentation should be explicit. Use **Upload schematics** when you want the platform inferred from the design.

## Manage schematic versions

After the first upload, `/upload-schematics` asks how to handle the next source set:

* **New version:** replace the active source set and append a new version.
* **Amend current version, add files only:** keep the current files and add only new basenames. Collisions are skipped.
* **Amend current version, replace by filename:** replace matching basenames and keep the other current files.

A version records the source hash, file list, detected MCU, component and net counts, current Git branch and commit, parse tool, and creation time. Amending preserves the original creation time and records an amendment time.

Embedder compares a new version with the preceding parsed design. The diff can report added, removed, and changed components; net changes; pin changes; and power-domain changes. The next fresh agent context receives the latest diff once so the agent can check firmware impact.

If files recorded by the current version are missing from `sources/`, Embedder disables amendment. Start a new version and select the complete set so missing files are not silently dropped.

## Reference schematic entities

Use `@sch:` tokens to attach one parsed entity to a prompt:

```txt theme={"system"}
Check whether the driver uses the pins from @sch:component:U1.
Explain every consumer on @sch:net:+3V3.
Compare initialization order with @sch:power_domain:VDD_IO.
```

The token format is:

```txt theme={"system"}
@sch:<kind>:<id>
```

Supported kinds are:

* `component`: a reference designator, its pins, and connected nets
* `net`: a net and its component-pin connections
* `sheet`: a sheet name and its components
* `bus`: a parsed bus by name or ID
* `power_domain`: a power domain by name or ID
* `functional_block`: a functional block by name or ID
* `layer`: a PCB layer name

The `@sch:` prefix and kind are case-sensitive. IDs can contain letters, numbers, underscores, dots, plus signs, hyphens, and slashes. Repeated tokens are expanded once. An unresolved token adds no schematic reference data.

Layer references identify a conventional PCB layer but do not include geometry. Use the schematic or board viewer for geometric inspection.

Embedder appends resolved entity data to the hidden model message while preserving your original prompt. The reference catalog is generated from the active parsed version.

## Query the parsed design

The agent receives a compact hardware summary automatically. Ask for detailed data when needed:

```txt theme={"system"}
Use schematic info to list the pins and nets for the IMU.
Show the I2C interfaces and detected device addresses.
Trace the 3.3 V power domain from its source to every consumer.
```

The `schematicInfo` operation can return:

* Overview counts and major blocks
* Components and pin mappings
* Nets and connections
* Power domains
* Functional blocks
* Interfaces
* Buses

Local parsed data takes precedence. If no local version exists, Embedder can query parsed schematics attached to the selected project.

## Open EDA files

Native KiCad sheets and boards open in the integrated KiCanvas viewer. A `.kicad_pro` file identifies the root `.kicad_sch` with the same basename when present.

For other supported formats:

* Altium `.PcbDoc` files use an existing synthesized KiCad board or an on-demand conversion. Embedder prefers `kicad-cli` and can fall back to its local converter.
* Altium `.SchDoc`, Eagle, PADS, Xpedition, and EDIF uploads can produce synthesized `.kicad_sch` files during backend parsing.
* Raw EDIF netlists are not opened directly. The picker opens their synthesized KiCad sheets.

The original sources remain under `sources/`, so the agent can inspect text-based KiCad and Eagle files when parsed data is incomplete. Binary Altium documents should be queried through parsed schematic data or their synthesized companions.