/zener-language

name: zener-language
description: Read or edit Zener HDL, package APIs, and tool-managed dependencies.

Zener Language

Zener is Starlark plus PCB-specific modules, typed electrical connections, physical parts, sourcing, layout, and diagnostics.

Discover Before Authoring

Use `pcb list -m -json @stdlib` or `pcb list -m -json <package>[@<version>]` to find a package's local source directory, then read its `.zen` files for the public API and exact behavior.

For CLI behavior, use the installed command's `--help`; do not invent or infer subcommands or flags. When version history matters, inspect the installed version and nearby entries in the [`pcb` changelog](https://github.com/diodeinc/pcb/blob/main/CHANGELOG.md) instead of relying on old examples.

Modules and Components

A `.zen` file can be:

• a normal Starlark module imported with `load()`; or
• an instantiable schematic module imported with `Module()`.

Relative paths stay within the current package. Cross-package imports use full package URLs:

load("./helpers.zen", "helper")
LocalBlock = Module("./LocalBlock.zen")
RemoteBlock = Module("github.com/org/repo/modules/RemoteBlock.zen")

An instantiation passes `name=...`, its public `io()` and `config()` inputs, and optional `dnp` and `properties` arguments.

`name` establishes instance-path identity, not a fixed reference designator. Refdes-like names are only annotation hints; exact source-reference preservation is not supported.

Use refdes-like names only when the user explicitly asks. In that case, set `prefix=` on the underlying `Component()` to match the refdes prefix.

`Component()` creates a physical part from `name`, `symbol`, and `pins`. The selected symbol is the authority for its footprint, part identity, datasheet, and pins. Keep those properties correct in `.kicad_sym` rather than repeating them in Zener. Omit true `no_connect` pins; they are wired to `NotConnected()` automatically.

Use `Symbol(library, name=...)` for multi-symbol libraries. Use `Part(mpn=..., manufacturer=...)` only when the symbol does not already provide part identity.

`Project()` takes `layout = False` or `schematic = False` to disable either. Use one declaration per entrypoint with a config-independent path relative to its `.zen` file; use separate entrypoints for distinct projects.

IO and Config

Define public electrical connections as flat top-level assignments:

VDD = io(Power(voltage="3.0V to 5.5V"))
GND = io(Ground)
EN = io(Net, optional=True)

Do not introduce legacy `Pins = struct(...)` wrappers in new or touched APIs.

With `optional=True`, an omitted IO receives an automatically generated net or interface.

`Net` is the base connection type. `Power`, `Ground`, `NotConnected`, and stdlib interfaces add constraints and semantics. Across an `io()` boundary, `NotConnected` can promote to any net type, a specialized net can demote to `Net`, and a plain `Net` does not automatically gain specialized semantics. Adapt intentionally with casts such as `Power(net, voltage=...)` or `Net(power_net)`.

Use stdlib interfaces such as `DiffPair`, `I2c`, `I3c`, `Spi`, `Qspi`, `Uart`, `Usart`, `Swd`, `Jtag`, `Usb2`, and `Usb3` when the grouped protocol semantics are meaningful.

Use `UartPair()` and `UsartPair()` when a point-to-point link should cross-connect the two endpoints.

Declare a voltage range on every public `Power` IO unless the API is intentionally generic.

Define non-electrical choices with typed `config()`:

output_voltage = config(Voltage, default="3.3V", allowed=["3.3V", "5V"])

Load physical value types from `@stdlib/units.zen`: `Voltage`, `Current`, `Resistance`, `Capacitance`, `Inductance`, `Impedance`, `Frequency`, `Temperature`, `Time`, and `Power`. String defaults and allowed values auto-convert to the declared physical type. Use enums for non-physical modes and strategies. Expose application-level choices rather than internal passive values or implementation details.

Physical constructors accept point values, engineering notation, ranges, and tolerances. Arithmetic tracks units. Equality between two physical values is strict; use `.matches(...)` for coercive comparison with a string or scalar. Inspect the installed API for other operations.

Enum defaults use the selected string value:

Mode = enum("PULLUP", "PULLDOWN")
mode = config(Mode, default="PULLUP")

Stable Topology

Configs may change values and `dnp=` state, but should not add, remove, or reconnect schematic instances. Stable instance and net identity preserves layout and reviewability.

• Compute a selected value on one component when the nets do not change.
• Instantiate every mutually exclusive strap or option and DNP the inactive alternatives.
• Do not use conditional instantiation to change topology.
• Use an IC's internal pull-up or pull-down for its default mode when appropriate; add external bias components with `dnp=` only for populated alternatives.

Put non-trivial electrical calculations in named functions. Cite the relevant datasheet equation or table and snap calculated values with the appropriate stdlib E-series helper.

The available E-series helpers in `@stdlib/utils.zen` are `e3`, `e6`, `e12`, `e24`, `e48`, `e96`, and `e192`.

Use `check`, `warn`, `error`, and stdlib checks for enforceable electrical constraints rather than documenting them only in comments.

For reusable power-rail boundary checks, inspect and prefer `voltage_within(...)` from `@stdlib/checks.zen` instead of duplicating the constraint.

Public Compatibility

Reusable-package compatibility includes the public `io()` and `config()` API, entrypoints, behavior, layout, and physical integration assumptions. A build of the current package does not prove existing consumers remain compatible.

If consumers must change to adopt an update, treat it as breaking. Document the migration and use a breaking commit.

Schematic Position State

Inspect the root declaration and its