Reference Design

Workflow for creating production-quality reference designs in Zener. A reference design wraps an IC with its recommended application circuit — decoupling, biasing, pull-ups, crystals, etc. — as a reusable module.

Workflow

1. Get the IC definition available to the design (use the component-search skill if needed). Prefer validated registry modules/components when they fit; import a web component into the workspace only when you need a new local component package.
2. Study the datasheet — use the datasheet-reader skill, then extract the information listed in Datasheet Checklist.
3. Study existing reference designs — read 2–3 validated examples before writing. See Studying Existing Designs.
4. Create the design — scaffold the directory, write the .zen file section by section, build after every major section. See Design Structure.
5. Write the README — document interfaces, usage, and design notes. See README Template.
6. Validate — pcb build reference/<NAME> must pass. Then pcb fmt reference/<NAME>.

Datasheet Checklist

Extract these from the scanned datasheet markdown before writing any code:

• Typical application schematic / reference circuit
• Power supply pins and voltage requirements
• Decoupling capacitor values and placement (per power pin)
• Bias resistor values and connections
• Crystal / oscillator requirements (frequency, load capacitance)
• Digital interface pin mapping (match to stdlib interfaces like Spi, I2c, Uart, Rgmii, etc.)
• Strap / bootstrap configuration pins and their default states
• Reset circuit requirements (pull-up value, RC filter)
• Analog / differential pair connections and termination
• Exposed pad / thermal pad connections

Studying Existing Designs

Before writing a new reference design, read validated examples from the registry cache to learn patterns. Find them with:

pcb search -m registry:modules "<similar function>" -f json

Then inspect the cached source with the relevant package docs or read the .zen file directly from ~/.pcb/cache/.

Key patterns to observe:

• How IOs are structured (which nets are exposed vs internal)
• How optional features are handled (optional io, dnp=-driven parts, computed values)
• How passives are sized and grouped
• How the README documents the design

If an existing example conflicts with idiomatic-zener, follow idiomatic-zener for new work. In particular, do not use conditional instantiation for components.

Design Structure

Directory layout and naming

Use the MPN prefix plus x suffix. Example: DP83867ISRGZR → DP83867x.

reference/<PREFIX>x/
├── <PREFIX>x.zen       # Main design file
├── pcb.toml            # Empty or with non-auto dependencies
└── README.md           # Usage guide

Scaffold with pcb new package reference/<PREFIX>x.

.zen file structure

Organize the file in this order:

1. Docstring — component name, brief description, key specs
2. Loads — stdlib interfaces and units needed beyond prelude
3. IOs — external interface of the module (power, ground, data interfaces, optional pins)
4. Configs — user-configurable parameters (output voltage, pull-up enable, etc.)
5. Internal nets — nets that don't leave the module, prefixed with _
6. Component and generic imports — the main IC and passives
7. Main IC instantiation — connect all pins
8. Supporting circuitry — decoupling, bias, pull-ups, crystals, reset, etc. grouped by function
9. Optional feature sections — organize circuitry controlled by config or optional io, but keep components instantiated and use dnp= rather than conditional instantiation

Reference-design-specific conventions:

• Internal nets use _ prefix: _RBIAS = Net("RBIAS")
• Group decoupling caps near the IC instantiation, one per power pin as the datasheet recommends
• Use a passives_size variable when all passives share a package size (e.g. "0402")
• Add brief comments referencing datasheet section/table for non-obvious values

Build iteratively

Build after every major section — don't write the entire file and then build. This catches errors early:

pcb build reference/<PREFIX>x

Common errors:

• Wrong interface field names — inspect the relevant package API before wiring
• Missing loads — add the interface or unit import
• Path errors — pcb build takes the directory, not the .zen file

Format when done: pcb fmt reference/<PREFIX>x.

Common Passive Patterns

When in doubt, follow the datasheet's recommended values exactly. Don't optimize passives without reason.

README Template

# <NAME> Reference Design

Brief description of the IC and what this reference design provides.

## Features
- **IC**: MPN (package)
  - Key electrical specs (voltage range, current, frequency, etc.)
- **Interfaces**: What buses/connections are exposed
- **Protection**: ESD, overcurrent, thermal features if relevant

## Interfaces

| Name | Type | Description |
|------|------|-------------|
| VIN | Power | Input supply (range) |
| VOUT | Power | Regulated output |
| GND | Ground | Common ground |
| SPI | Spi | Control interface |

## Usage

\```python
MyRef = Module("github.com/diodeinc/registry/reference/<NAME>/<NAME>.zen")

MyRef(
    name="U1",
    VIN=vin_3v3,
    VOUT=vout_1v8,
    GND=gnd,
    SPI=spi_bus,
)
\```

## Design Notes

Document key design decisions, tradeoffs, and anything non-obvious:
- Why specific passive values were chosen
- Strap pin configurations and what they select
- Thermal considerations
- Layout-sensitive connections

## References
- [Datasheet](url)