reference-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

在Zener中创建生产级参考设计的工作流程。参考设计是将IC与其推荐的应用电路（去耦、偏置、上拉、晶振等）封装为可重用模块的设计方案。

Workflow

工作流程

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.
Study the datasheet — use the
```
datasheet-reader
```
skill, then extract the information listed in Datasheet Checklist.
Study existing reference designs — read 2–3 validated examples before writing. See Studying Existing Designs.
Create the design — scaffold the directory, write the
```
.zen
```
file section by section, build after every major section. See Design Structure.
Write the README — document interfaces, usage, and design notes. See README Template.

Validate —

pcb build reference/<NAME>

must pass. Then

pcb fmt reference/<NAME>

确保设计可获取IC定义（如有需要可使用
```
component-search
```
技能）。优先选用经过验证的注册表模块/元件；仅当需要新的本地元件包时，才将Web元件导入工作区。
研究数据手册——使用
```
datasheet-reader
```
技能，然后提取数据手册检查清单中列出的信息。
研究现有参考设计——在开始编写前，阅读2-3个经过验证的示例。详见研究现有设计。
创建设计——搭建目录结构，分节编写
```
.zen
```
文件，完成每个主要章节后执行构建。详见设计结构。
编写README文档——记录接口、使用方法和设计说明。详见README模板。
验证——执行
```
pcb build reference/<NAME>
```
必须通过。然后执行
```
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

在编写任何代码前，从扫描后的数据手册Markdown中提取以下信息：

典型应用原理图/参考电路
电源引脚及电压要求
去耦电容值及布局要求（每个电源引脚对应）
偏置电阻值及连接方式
晶振/振荡器要求（频率、负载电容）
数字接口引脚映射（匹配标准库接口如
```
Spi
```
、
```
I2c
```
、
```
Uart
```
、
```
Rgmii
```
等）
配置/引导引脚及其默认状态
复位电路要求（上拉电阻值、RC滤波器）
模拟/差分对连接及端接方式
裸露焊盘/散热焊盘连接方式

Studying Existing Designs

研究现有设计

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

bash

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.

在编写新参考设计前，从注册表缓存中读取经过验证的示例以学习设计模式。可通过以下命令查找：

bash

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

然后通过相关包文档检查缓存源码，或直接从

~/.pcb/cache/

目录读取

.zen

文件。

需要关注的关键模式：

IO接口的结构设计（哪些网络对外暴露，哪些为内部网络）
可选功能的处理方式（可选IO、
```
dnp=
```
驱动的元件、计算值）
无源元件的尺寸选型和分组方式
README文档的设计说明方式

如果现有示例与

idiomatic-zener

规范冲突，新设计需遵循

idiomatic-zener

规范。特别注意：不要对元件使用条件实例化。

Design Structure

设计结构

Directory layout and naming

目录布局与命名

Use the MPN prefix plus

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

使用MPN前缀加

后缀。示例：

DP83867ISRGZR

→

DP83867x

。

reference/<PREFIX>x/
├── <PREFIX>x.zen       # 主设计文件
├── pcb.toml            # 空文件或包含非自动依赖
└── README.md           # 使用指南

可通过

pcb new package reference/<PREFIX>x

命令搭建初始结构。

.zen file structure

.zen文件结构

Organize the file in this order:

Docstring — component name, brief description, key specs
Loads — stdlib interfaces and units needed beyond prelude
IOs — external interface of the module (power, ground, data interfaces, optional pins)
Configs — user-configurable parameters (output voltage, pull-up enable, etc.)
Internal nets — nets that don't leave the module, prefixed with
```
_
```
Component and generic imports — the main IC and passives
Main IC instantiation — connect all pins
Supporting circuitry — decoupling, bias, pull-ups, crystals, reset, etc. grouped by function
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

按以下顺序组织文件内容：

文档字符串——元件名称、简要描述、关键规格
导入项——除预导入外所需的标准库接口和单位
IO接口——模块的外部接口（电源、地、数据接口、可选引脚）
配置项——用户可配置的参数（输出电压、上拉使能等）
内部网络——不导出到模块外的网络，以
```
_
```
为前缀
元件与通用导入——主IC及无源元件
主IC实例化——连接所有引脚
辅助电路——按功能分组的去耦、偏置、上拉、晶振、复位等电路
可选功能章节——组织由配置项或可选IO控制的电路，但需保持元件实例化状态，使用
```
dnp=
```
而非条件实例化

参考设计专属规范：

内部网络使用
```
_
```
前缀：
```
_RBIAS = Net("RBIAS")
```
去耦电容分组放置在IC实例化代码附近，按照数据手册要求为每个电源引脚配置一个
当所有无源元件使用相同封装尺寸时，使用
```
passives_size
```
变量（如
```
"0402"
```
）
对非直观的参数值添加注释，注明数据手册的章节/表格编号

Build iteratively

迭代式构建

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

bash

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

完成每个主要章节后执行构建——不要写完整个文件再构建。这样可以尽早发现错误：

bash

pcb build reference/<PREFIX>x

常见错误：

接口字段名称错误——在连线前检查相关包的API
缺少导入项——添加对应的接口或单位导入
路径错误——
```
pcb build
```
命令接收的是目录路径，而非
```
.zen
```
文件路径

完成后执行格式化：

pcb fmt reference/<PREFIX>x

。

Common Passive Patterns

常见无源元件选型模式

Purpose	Typical Value	Notes
Decoupling (digital)	1µF per power pin	Place closest to pin
Decoupling (analog)	100nF C0G + 10µF	C0G for low ESR
Decoupling (bulk)	10µF–47µF	Near power input, X5R/X7R
I2C pull-ups	2.2kΩ–4.7kΩ	To VDD, value depends on bus speed and capacitance
MDIO pull-up	2.2kΩ	To VDDIO
SPI pull-up (CS)	10kΩ	Keep CS deasserted at reset
Reset RC filter	10kΩ pull-up + 100nF	~1ms time constant
Bias resistor	Per datasheet (1% tolerance)	Always use exact datasheet value
LED current limit	330Ω	~10mA at 3.3V, adjust for target current
Crystal load caps	Per crystal spec	C0G dielectric, value from crystal datasheet formula

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

用途	典型值	说明
数字电路去耦	每个电源引脚配1µF	放置在最靠近引脚的位置
模拟电路去耦	100nF C0G + 10µF	C0G电容具有低ESR特性
bulk去耦	10µF–47µF	放置在电源输入附近，选用X5R/X7R材质
I2C上拉电阻	2.2kΩ–4.7kΩ	连接至VDD，阻值取决于总线速度和电容
MDIO上拉电阻	2.2kΩ	连接至VDDIO
SPI（CS）上拉电阻	10kΩ	确保复位时CS处于无效状态
复位RC滤波器	10kΩ上拉电阻 + 100nF电容	时间常数约1ms
偏置电阻	遵循数据手册要求（1%精度）	务必使用数据手册指定的精确值
LED限流电阻	330Ω	3.3V电压下电流约10mA，可根据目标电流调整
晶振负载电容	遵循晶振规格	选用C0G介质，阻值由晶振数据手册公式计算得出

如有疑问，严格遵循数据手册推荐的参数值。无合理理由不要优化无源元件参数。

README Template

README模板

markdown

undefined

markdown

undefined

<NAME> Reference Design

<NAME> 参考设计

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

IC的简要描述及本参考设计的作用。

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

IC: MPN（封装）
- 关键电气规格（电压范围、电流、频率等）
接口: 对外暴露的总线/连接方式
保护: 如ESD、过流、热保护等相关特性（如有）

Interfaces

接口

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

名称	类型	描述
VIN	Power	输入电源（范围）
VOUT	Power	稳压输出
GND	Ground	公共地
SPI	Spi	控制接口

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, ) ```

```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

undefined

数据手册

undefined