pcb

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PCB

Zener is a Starlark-based HDL for PCB design.

.zen

files define components, nets, interfaces, and modules. Key concepts:

Net: electrical connection between pins
Component: physical part with symbol, footprint, pins
Interface: reusable grouped connection pattern (e.g.,
```
Spi
```
,
```
I2c
```
,
```
Uart
```
)
Module: hierarchical subcircuit, instantiated with
```
Module("path.zen")
```

IMPORTANT: Before writing or modifying .zen code, run
pcb doc spec
to read the language specification. The spec covers syntax, built-in functions, type system, and common patterns. For specific topics:

pcb doc spec --list

shows all sections,

pcb doc spec/<section>

reads one section.

Prefer stdlib generics (

@stdlib/generics/

) over specific components when possible. Generics like

Resistor

Capacitor

Led

are parameterized by value/package and resolved to real parts at build time.

Common imports:

load("@stdlib/interfaces.zen", "Power", "Ground", "Spi", "I2c", ...)

for standard net types and interfaces.

Zener是一种基于Starlark的PCB设计硬件描述语言（HDL）。

.zen

文件用于定义元器件、网络、接口和模块。核心概念：

Net：引脚之间的电气连接
Component：带有符号、封装、引脚的物理元器件
Interface：可复用的分组连接模式（例如
```
Spi
```
、
```
I2c
```
、
```
Uart
```
）
Module：分层子电路，通过
```
Module("path.zen")
```
实例化

**重要提示：在编写或修改.zen代码之前，请运行

pcb doc spec

查看语言规范。**该规范涵盖语法、内置函数、类型系统和常见模式。如需查看特定主题：

pcb doc spec --list

会显示所有章节，

pcb doc spec/<section>

可查看单个章节。

优先使用标准库泛型（

@stdlib/generics/

）而非特定元器件。

Resistor

、

Capacitor

、

Led

等泛型可通过参数指定参数值/封装，并在构建时解析为实际元器件。

常见导入语句：使用

load("@stdlib/interfaces.zen", "Power", "Ground", "Spi", "I2c", ...)

导入标准网络类型和接口。

Datasheets

数据手册

Use

pcb scan

when a task depends on a datasheet or technical PDF.

Input: local
```
.pdf
```
path or
```
http(s)
```
URL
Command:
```
pcb scan <input>
```
Output: stdout is the resolved markdown path
Next step: read the markdown file, not the raw PDF
Images are linked from the markdown

Examples:

bash

pcb scan ./TPS54331.pdf
pcb scan https://www.ti.com/lit/gpn/tca9554

当任务需要依赖数据手册或技术PDF时，请使用

pcb scan

命令。

输入：本地
```
.pdf
```
文件路径或
```
http(s)
```
URL
命令：
```
pcb scan <input>
```
输出：标准输出为解析后的markdown文件路径
下一步：查看markdown文件，而非原始PDF
图片会从markdown文件中链接

示例：

bash

pcb scan ./TPS54331.pdf
pcb scan https://www.ti.com/lit/gpn/tca9554

CLI Commands

CLI命令

bash

undefined

bash

undefined

scaffolding

脚手架

pcb new workspace <NAME> --repo <URL> # Create new workspace with git init pcb new board <NAME> # Add board to existing workspace (boards/<NAME>/) pcb new package <PATH> # Create package at path (modules, etc.)


```bash
pcb build [PATH]         # Build and validate (default: cwd)
pcb fmt [PATH]           # Format .zen files (default: cwd)
pcb bom <FILE> -f json   # Generate BOM as JSON with availability data
pcb fork add <URL>       # Fork dependency for local dev
pcb fork remove <URL>    # Remove fork

pcb new workspace <NAME> --repo <URL> # 创建新工作区并初始化git pcb new board <NAME> # 向现有工作区添加电路板（路径：boards/<NAME>/） pcb new package <PATH> # 在指定路径创建包（如模块等）


```bash
pcb build [PATH]         # 构建并验证（默认：当前工作目录）
pcb fmt [PATH]           # 格式化.zen文件（默认：当前工作目录）
pcb bom <FILE> -f json   # 生成包含供货数据的JSON格式BOM
pcb fork add <URL>       # 复刻依赖包用于本地开发
pcb fork remove <URL>    # 移除复刻的依赖包

Component Search & Add

元器件搜索与添加

bash

pcb search -m registry:modules buck -f json
pcb search -m registry:components usb-c -f json
pcb search -m web:components STM32F103C8T6 -f json
pcb new component --component-id <ID> --part-number <MPN> --manufacturer <MFR>

```
pcb search -m registry:modules ... -f json
```
: Search registry modules and reference designs. Includes descriptions, package URLs, dependencies/dependents, and availability data for component-backed results.
```
pcb search -m registry:components ... -f json
```
: Search registry components. Includes MPN/manufacturer metadata, availability, supplier metadata, and dependency/dependent context.
```
pcb search -m web:components ... -f json
```
: Search Diode's web component database. Includes
```
component_id
```
, pricing/stock/offers, datasheets, model availability, and source.
```
pcb new component --component-id ...
```
: Download a web component into the current workspace.
```
--part-number
```
and
```
--manufacturer
```
are optional fallbacks.

bash

pcb search -m registry:modules buck -f json
pcb search -m registry:components usb-c -f json
pcb search -m web:components STM32F103C8T6 -f json
pcb new component --component-id <ID> --part-number <MPN> --manufacturer <MFR>

```
pcb search -m registry:modules ... -f json
```
：搜索注册表中的模块和参考设计。结果包含描述、包URL、依赖/被依赖关系，以及元器件相关的供货数据。
```
pcb search -m registry:components ... -f json
```
：搜索注册表中的元器件。结果包含制造商零件编号（MPN）、制造商元数据、供货情况、供应商元数据，以及依赖/被依赖上下文。
```
pcb search -m web:components ... -f json
```
：搜索Diode的在线元器件数据库。结果包含
```
component_id
```
、价格/库存/报价、数据手册、型号供货情况和来源。
```
pcb new component --component-id ...
```
：将在线元器件下载到当前工作区。
```
--part-number
```
和
```
--manufacturer
```
为可选备选参数。

MCP Tools

MCP工具

Tool	Use
`read_kicad_symbol_metadata`	Read structured KiCad symbol metadata ( `primary` typed properties + `custom_properties` ) from a `.kicad_sym` symbol. Supports `resolve_extends` and optional raw property map output.
`write_kicad_symbol_metadata`	Strict full-write of symbol metadata. Input becomes the full metadata state (unset fields/properties are removed). Supports `dry_run` for previewing changes.
`merge_kicad_symbol_metadata`	RFC 7396 JSON Merge Patch update for metadata. Use for incremental edits (object keys set/replace, `null` deletes, arrays replace whole). Supports `dry_run` .

Metadata tool notes:

These metadata tools are intended for
```
pcb mcp eval
```
scripted/structured metadata edits.

Prefer

read_kicad_symbol_metadata

first, then choose either strict

write_kicad_symbol_metadata

or incremental

merge_kicad_symbol_metadata

Canonical KiCad mapping lives under

metadata.primary

```
Reference
```
<->
```
primary.reference
```
```
Value
```
<->
```
primary.value
```
```
Footprint
```
<->
```
primary.footprint
```
```
Datasheet
```
<->
```
primary.datasheet
```
```
Description
```
<->
```
primary.description
```
```
ki_keywords
```
<->
```
primary.keywords
```
(array in JSON, space-separated string in
```
.kicad_sym
```
)

ki_fp_filters

<->

primary.footprint_filters

(array in JSON, space-separated string in

.kicad_sym

)

```
custom_properties
```
is only for non-canonical properties. Do not put canonical keys there.
Legacy note: older symbols may use
```
ki_description
```
. Reads normalize it to
```
primary.description
```
when canonical
```
Description
```
is absent; writes emit canonical
```
Description
```
.

Common gotcha:

Wrong:

metadata_patch: {custom_properties: {ki_keywords: "powerline transceiver CAN"}}

Right:

metadata_patch: {primary: {keywords: ["powerline", "transceiver", "CAN"]}}

工具	用途
`read_kicad_symbol_metadata`	从 `.kicad_sym` 符号文件中读取结构化的KiCad符号元数据（ `primary` 类型化属性 + `custom_properties` ）。支持 `resolve_extends` 参数，可选输出原始属性映射。
`write_kicad_symbol_metadata`	严格全量写入符号元数据。输入内容将成为完整的元数据状态（未设置的字段/属性会被移除）。支持 `dry_run` 参数用于预览更改。
`merge_kicad_symbol_metadata`	基于RFC 7396 JSON合并补丁更新元数据。用于增量编辑（对象键设置/替换， `null` 表示删除，数组会被整体替换）。支持 `dry_run` 参数。

元数据工具说明：

这些元数据工具用于
```
pcb mcp eval
```
脚本化/结构化的元数据编辑。
建议先使用
```
read_kicad_symbol_metadata
```
读取元数据，然后选择严格全量写入的
```
write_kicad_symbol_metadata
```
或增量编辑的
```
merge_kicad_symbol_metadata
```
。

KiCad标准元数据映射位于

metadata.primary

下：

```
Reference
```
<->
```
primary.reference
```
```
Value
```
<->
```
primary.value
```
```
Footprint
```
<->
```
primary.footprint
```
```
Datasheet
```
<->
```
primary.datasheet
```
```
Description
```
<->
```
primary.description
```
```
ki_keywords
```
<->
```
primary.keywords
```
（JSON中为数组，
```
.kicad_sym
```
中为空格分隔的字符串）
```
ki_fp_filters
```
<->
```
primary.footprint_filters
```
（JSON中为数组，
```
.kicad_sym
```
中为空格分隔的字符串）

```
custom_properties
```
仅用于存储非标准属性。请勿将标准键放置在此处。
遗留说明：较旧的符号可能使用
```
ki_description
```
。当标准
```
Description
```
不存在时，读取操作会将其标准化为
```
primary.description
```
；写入操作会输出标准的
```
Description
```
。

常见误区：

错误写法：

metadata_patch: {custom_properties: {ki_keywords: "powerline transceiver CAN"}}

正确写法：

metadata_patch: {primary: {keywords: ["powerline", "transceiver", "CAN"]}}

Documentation

文档

bash

pcb doc spec               # Full language specification
pcb doc spec --list        # List all spec sections
pcb doc spec/<section>     # Read specific section (e.g., spec/io, spec/module)
pcb doc packages           # Dependency management docs
pcb doc docs_bringup       # Guide on writing bringup docs in markdown 
pcb doc docs_changelog     # Guide on writing a changelog after every change

Package docs (stdlib, registry packages):

bash

pcb doc --package @stdlib                                           # Standard library docs
pcb doc --package @stdlib --list                                    # List files as tree
pcb doc --package @stdlib/generics                                  # Filter to subdirectory
pcb doc --package github.com/diodeinc/registry/module/<xyz>@0.1.0   # Remote package

bash

pcb doc spec               # 完整语言规范
pcb doc spec --list        # 列出所有规范章节
pcb doc spec/<section>     # 查看特定章节（例如spec/io、spec/module）
pcb doc packages           # 依赖管理文档
pcb doc docs_bringup       # 关于用markdown编写调试文档的指南
pcb doc docs_changelog     # 关于每次更改后编写变更日志的指南

包文档（标准库、注册表包）：

bash

pcb doc --package @stdlib                                           # 标准库文档
pcb doc --package @stdlib --list                                    # 以树形结构列出文件
pcb doc --package @stdlib/generics                                  # 筛选子目录
pcb doc --package github.com/diodeinc/registry/module/<xyz>@0.1.0   # 远程包文档

Part Sourcing & BOM Matching

元器件采购与BOM匹配

Generic components are matched to "house parts" (pre-qualified, good availability). Warnings like

No house cap found for ...

No house resistor found for ...

mean no house part matches the spec—adjust the spec or specify

mpn

manufacturer

to use a specific part.

pcb bom <FILE> -f json

outputs sourcing data with

availability_tier

(

"plenty"

"limited"

"insufficient"

) and distributor

offers

by region.

泛型元器件会与"内部认证元器件"（预先认证、供货稳定）进行匹配。如果出现

No house cap found for ...

或

No house resistor found for ...

等警告，说明没有符合规格的内部认证元器件——此时需要调整规格，或指定

mpn

（制造商零件编号）和

manufacturer

（制造商）来使用特定元器件。

pcb bom <FILE> -f json

命令会输出包含

availability_tier

（

"plenty"

"limited"

"insufficient"

）和各地区分销商

offers

的采购数据。