WireViz 官方教程精讲:从零开始用 YAML 绘制线束接线图与物料清单

原创2026-10-03 15:15:211,119 阅读
文章标签:开发工具CLI硬件开发

WireViz 官方教程精讲:从零开始用 YAML 绘制线束接线图与物料清单

导读

本文是 WireViz 官方教程(tutorial/readme.md)的完整精讲。WireViz 是一个通过 YAML 描述文件自动生成接线图(Graphviz SVG/PNG)、HTML 预览与 BOM(物料清单,TSV)的开源工具。教程由 8 个递进式示例构成,从最小可用接线图开始,逐步覆盖参数与颜色、引脚定义(pinout)、屏蔽、模板复用、线束(bundle)、端子(ferrule)、菊花链(daisy chain)以及零件号与附加物料。读完本文,你将掌握 WireViz 全部核心语法,并能独立写出可生成专业线束图纸与 BOM 的 YAML 文件。

每个示例的源码 YAML、生成的图(PNG/SVG)与 BOM(TSV)都保存在仓库的 tutorial/ 目录下,示例 tutorialNN.yml、tutorialNN.bom.tsv 与本文代码块一一对应,可随时对照验证。

01 - 最小可用示例(Bare-bones)

目标与要点

  • 最小可用示例(Minimum working example);
  • 仅使用 1 对 1 的顺序接线(1-to-1 sequential wiring)。

完整代码

connectors:
  X1:
    pincount: 4
  X2:
    pincount: 4

cables:
  W1:
    wirecount: 4
    length: 1

connections:
  -
    - X1: [1-4]
    - W1: [1-4]
    - X2: [1-4]

逐段解读

  • connectors:定义所有用到的连接器。X1、X2 各有一个 pincount: 4,表示 4 引脚。WireViz 会自动为引脚编号为 1、2、3、4(详见 docs/syntax.md 中 pins 的说明:"if omitted, is autofilled with [1, 2, ..., pincount]")。
  • cables:定义电缆。W1 有 4 根导线(wirecount: 4),长度 1(单位默认为米,length 的数值默认以米为单位,详见 docs/syntax.md)。
  • connections:定义接线。每一条 - 是一个"连接组(connection set)",组内元素必须在 connectors 与 cables 之间交替出现。本示例将 X1 的引脚 1-4 依次接到 W1 的导线 1-4,再接到 X2 的引脚 1-4。

注意 [1-4] 这种写法:<int>-<int> 会自动展开为范围,例如 1-4 展开为 1,2,3,4;反向写 9-7 也会展开为 9,8,7(见 docs/syntax.md 的 "Multiple parallel connections" 一节)。

输出

生成的 BOM

运行后生成的 tutorial01.bom.tsv 内容如下:

Id	Description	Qty	Unit	Designators
1	Cable, 4 wires	1	m	W1
2	Connector, 4 pins	2		X1, X2

可以看到:电缆按 1 米计(Unit 为 m),两个同规格连接器合并为一行(Designators 列为 X1, X2)。

02 - 添加参数与颜色(Parameters and colors)

新增能力

  • 为连接器和电缆添加参数;
  • 从 mm² 自动换算等效 AWG 线规;
  • 非顺序接线(non-sequential wiring)。

完整代码

connectors:
  X1:
    pincount: 4
    # More connector parameters:
    type: Molex KK 254
    subtype: female
  X2:
    pincount: 4
    type: Molex KK 254
    subtype: female

cables:
  W1:
    wirecount: 4
    # more cable parameters:
    length: 1
    gauge: 0.25 mm2
    show_equiv: true # auto-calculate AWG equivalent
    colors: [WH, BN, GN, YE]

connections:
  -
    - X1: [1-4]
    - W1: [1-4]
    # non-sequential wiring:
    - X2: [1,2,4,3]

解读

  • type / subtype:连接器的型号与子型号(如 Molex KK 254 母头),会显示在图中并进入 BOM 描述。
  • gauge: 0.25 mm2:线规。WireViz 支持的格式(见 docs/syntax.md):<int/float> mm2 按平方毫米理解;<int> AWG 按 AWG 理解;裸数字默认按 mm²;字符串则使用自定义单位且不参与自动换算。
  • show_equiv: true:显示等效线规。默认值为 false;设为 true 后,WireViz 会在 mm² 与 AWG 之间自动换算并在图中展示结果。
  • colors: [WH, BN, GN, YE]:为 4 根导线分别指定颜色(白、棕、绿、黄)。颜色使用两个大写字母的短代码,完整颜色表见 docs/syntax.md 与 src/wireviz/wv_colors.py(如 BK 黑、RD 红、OG 橙、YE 黄、GN 绿、BU 蓝、VT 紫、BN 棕等)。多色(条纹)导线可直接拼接短码,如 GNYE 表示绿黄。
  • 非顺序接线:X2: [1,2,4,3] 让 X2 的第 4、3 引脚与 X1 的第 3、4 引脚交叉连接,图中会如实画出交叉关系。

输出

03 - 引脚定义、屏蔽与模板(Pinouts, shielding, templates, I)

新增能力

  • 连接器引脚定义(pinout):pinlabels 隐式决定引脚数(pincount implicit in pinout);
  • 电缆颜色编码(color code);
  • 电缆屏蔽与屏蔽层接线;
  • 模板(YAML anchor / alias 复用)。

完整代码

connectors:
  X1: &template1 # define a template for later use
    pinlabels: [GND, VCC, RX, TX] # pincount implicit in pinout
    type: Molex KK 254
    subtype: female
  X2:
    <<: *template1 # reuse template

cables:
  W1:
    wirecount: 4
    length: 1
    gauge: 0.25 mm2
    show_equiv: true
    color_code: DIN # auto-assign colors based on DIN 47100
    shield: true # add cable shielding

connections:
  -
    - X1: [1-4]
    - W1: [1-4]
    - X2: [1,2,4,3]
  - # connect the shielding to a pin
    - X1: 1
    - W1: s

解读

  • 模板(Template):X1: &template1 定义 YAML 锚点(anchor),X2: <<: *template1 通过 YAML 合并键(merge key)继承全部属性。这样同规格连接器只需定义一次。若需覆盖个别参数,只需在继承后重新赋值(见示例 04)。
  • 引脚定义:pinlabels: [GND, VCC, RX, TX] 有 4 个标签,引脚数自动取列表长度(pincount 隐式)。此后既可用引脚号(1),也可用唯一标签(如 RX)来引用引脚。
  • 颜色编码:color_code: DIN 根据 DIN 47100 标准自动为 4 根导线分配颜色。WireViz 内置的颜色编码定义在 src/wireviz/wv_colors.py 的 COLOR_CODES 中,支持 DIN(DIN 47100)、IEC(IEC 60757)、TEL/TELALT(25 对颜色码)、T568A/T568B(以太网线序)与 BW(黑白交替),详见 docs/syntax.md 的 "Cable color codes" 一节。
  • 屏蔽(Shield):shield: true 为电缆添加屏蔽层,图中以细黑线表示;也支持用颜色值(如 shield: BN)渲染屏蔽层颜色。屏蔽层在接线时以特殊导线 ID s 引用:本例第二条连接组把 X1 的引脚 1 接到 W1 的屏蔽层 s。

输出

04 - 模板进阶、注释、美式标准与线性菊花链(Templates II, notes, American standards, daisy chaining I)

新增能力

  • 覆盖模板参数(overriding template parameters);
  • 为连接器和电缆添加注释节点(notes);
  • 美式标准:直接使用 AWG 线规与 IEC 颜色编码;
  • 线性菊花链(linear daisy chain):适合较短的链式连接。

完整代码

connectors:
  X1: &template_con
    pinlabels: [GND, VCC, SCL, SDA]
    type: Molex KK 254
    subtype: male
    notes: to microcontroller # add notes
  X2:
    <<: *template_con # use template
    subtype: female   # but override certain parameters
    notes: to accelerometer
  X3:
    <<: *template_con
    subtype: female
    notes: to temperature sensor

cables:
  W1: &template_cbl
    wirecount: 4
    length: 0.3
    gauge: 24 AWG # specify gauge in AWG directly
    color_code: IEC # IEC 62 colors also supported
    notes: This cable is a bit longer
  W2:
    <<: *template_cbl
    length: 0.1
    notes: This cable is a bit shorter

connections:
  -
    - X1: [1-4]
    - W1: [1-4]
    - X2: [1-4]
  - # daisy chain connectors (in line)
    - X2: [1-4]
    - W2: [1-4]
    - X3: [1-4]

解读

  • 覆盖模板参数:X2、X3 继承 X1 的模板后将 subtype 改为 female,notes 改为各自的去向(accelerometer / temperature sensor)。W2 继承电缆模板后缩短长度并改写注释。这正是模板的典型用法:共享共性、覆盖差异。
  • 注释(notes):连接器与电缆都支持 notes 字段,显示在对应节点框中(见 docs/syntax.md 的 Connector/Cable attributes)。notes 还支持多行字符串(| 块或 "\n" 转义,见 docs/syntax.md 的 "Multiline strings" 一节)。
  • AWG 直接指定:gauge: 24 AWG 表示直接在 AWG 体系下指定线规,无需 mm² 换算。WireViz 同时支持美制 AWG 与公制 mm² 两种表述。
  • IEC 颜色编码:color_code: IEC 按 IEC 60757 标准分配颜色("ROY G BIV":棕、红、橙、黄、绿、蓝、紫、灰、白、黑,见 src/wireviz/wv_colors.py 的 COLOR_CODES["IEC"])。
  • 线性菊花链:第二个连接组 X2 -> W2 -> X3 把三个器件串联成一条直线链。连接组内元素不限数量("The maximum number of items is unlimited",见 docs/syntax.md),因此一条链可串联任意多个器件。这种写法对短链最直观。

输出

05 - 端子(Ferrule)、线束(Bundle)与自定义导线颜色

新增能力

  • 端子(ferrule):
    • 比连接器更简单;
    • 图形表示紧凑;
    • 只有一个引脚、只能有一根连接、没有编号(designator)的自动生成端子;
    • 定义一次,按需自动生成多个实例。
  • 线束(wire bundle):
    • 内部按电缆处理;
    • BOM 中每条导线单独列出(different treatment in BOM: each wire is listed individually);
    • 图中以虚线轮廓(dashed outline)表示。
  • 自定义导线颜色:导线数可隐含在颜色列表长度中(wirecount implicit in color list)。

完整代码

connectors:
  X1:
    pinlabels: [+12V, GND, GND, +5V]
    type: Molex 8981
    subtype: female
  F1:
    style: simple
    type: Crimp ferrule
    subtype: 0.5 mm²
    color: OG # optional color

cables:
  W1:
    category: bundle # bundle
    length: 0.3
    gauge: 0.5 mm2
    colors: [YE, BK, BK, RD] # custom colors, wirecount is implicit

connections:
  -
    - F1. # a new ferrule is auto-generated for each of the four wires
    - W1: [1-4]
    - X1: [1-4]

解读

  • 端子:F1 使用 style: simple(单引脚连接的紧凑样式,见 docs/syntax.md 的 style: <style>,simple 样式默认不显示名称与引脚数)。type: Crimp ferrule 表示压接端子,color: OG 为端子着色(可选)。
  • 自动生成(autogeneration):连接组中写 F1.——设计符后跟 . 触发自动生成(template_separator 默认字符,见 docs/syntax.md 的 "Autogeneration of items" 一节)。本例连接组有 4 条并联连接(W1: [1-4] 与 X1: [1-4]),因此 WireViz 为每条连接自动生成一个同规格端子实例,无需手工命名。
  • 线束(bundle):category: bundle 把 W1 声明为线束。语法上它与电缆相同("Internally treated as cables"),区别在于:
    • BOM 中每条导线单独成行(下例 BOM 可验证),而非整根电缆一行;
    • 图中以虚线轮廓渲染(对应 src/wireviz/Harness.py 中的 ("filled,dashed", self.options.bgcolor_bundle) 渲染逻辑,且 cable.category == "bundle" 分支生效)。
  • 导线数隐式确定:colors: [YE, BK, BK, RD] 有 4 个颜色,wirecount 自动取 4,无需再写 wirecount。WireViz 对颜色与导线数的组合规则见 docs/syntax.md:"colors only: wirecount is inferred from list length"。
  • 重复标签:pinlabels: [+12V, GND, GND, +5V] 中 GND 出现两次,WireViz 允许标签重复(引用引脚时需用引脚号,因为重复标签不唯一,见 docs/syntax.md 的 <pin> 引用规则)。

输出

06 - 自定义端子(Custom ferrules)

新增能力

  • 自定义端子(custom ferrule):
    • 允许一个端子接入多根导线(attaching more than one wire to a ferrule);
    • 需将其定义为带唯一编号的普通连接器,并添加 category: ferrule 参数。

完整代码

connectors:
  X1:
    pinlabels: [+12V, GND, GND, +5V]
    type: Molex 8981
    subtype: female
  F_10: # this is a unique ferrule
    style: simple
    type: Crimp ferrule
    subtype: 1.0 mm²
    color: YE # optional color
  F_05: # this is a ferrule that will be auto-generated on demand
    style: simple
    type: Crimp ferrule
    subtype: 0.5 mm²
    color: OG

cables:
  W1:
    category: bundle # bundle
    length: 0.3
    gauge: 0.5 mm2
    colors: [YE, BK, BK, RD] # custom colors, wirecount is implicit

connections:
    -
      - [F_05., F_10.F1, F_10.F1, F_05.]
      - W1: [1-4]
      - X1: [1-4]

解读

  • 示例 05 的端子只有一个引脚,只能接一根导线;当需要把多根导线并到一个端子(例如同规格的 BK、BK 两根线合并压接)时,就要用自定义端子。
  • F_10 是带唯一编号 F1 的自定义端子(内部标注 F_10.F1,即"模板 F_10 生成实例 F1"),F_05 则保留为按需自动生成的模板(写 F_05. 触发)。
  • 连接组第一项是一个列表 [F_05., F_10.F1, F_10.F1, F_05.]:第 2、3 条连接都指向同一个命名实例 F_10.F1,从而让两根 BK 导线共用一个 1.0 mm² 端子;第 1、4 条连接各自自动生成一个 0.5 mm² 端子 F_05.。这对应 docs/syntax.md 中"specify multiple simple connectors to attach in parallel"与"these may be unique, auto-generated, or a mix of both"的语法。
  • 实现层面,端子/线束的 category 由 src/wireviz/Harness.py 处理:对 bundle,逐线生成 BOM 项(if cable.category == "bundle": 分支),而 ferrule 类别在语法上同样通过 category 参数声明。

输出

07 - 菊花链进阶(Daisy chaining II):之字形链

新增能力

  • 之字形菊花链(zig-zag daisy chain):
    • 适合更长的链(convenient for longer chains)。

完整代码

connectors:
  X1: &template_con
    type: Molex KK 254
    subtype: female
    pinlabels: [GND, VCC, SCL, SDA]
  X2:
    <<: *template_con
  X3:
    <<: *template_con
  X4:
    <<: *template_con
  X5:
    <<: *template_con
  X6:
    <<: *template_con

cables:
  W1: &template_wire
    gauge: 0.25 mm2
    length: 0.2
    colors: [TQ, PK, YE, VT]
    category: bundle
  W2:
    <<: *template_wire
  W3:
    <<: *template_wire
  W4:
    <<: *template_wire
  W5:
    <<: *template_wire

connections:
  -
    - X1: [1-4]
    - W1: [1-4]
    - X2: [1-4]
  -
    - X3: [1-4]
    - W2: [1-4]
    - X2: [1-4]
  -
    - X3: [1-4]
    - W3: [1-4]
    - X4: [1-4]
  -
    - X5: [1-4]
    - W4: [1-4]
    - X4: [1-4]
  -
    - X5: [1-4]
    - W5: [1-4]
    - X6: [1-4]

解读

  • 当链很长时,线性连接组会变得又长又乱;之字形(zig-zag)写法把每段连接拆成独立的连接组,如 X1-W1-X2、X3-W2-X2、X3-W3-X4、X5-W4-X4、X5-W5-X6,相邻连接组共享中间器件(X2、X3、X4、X5 都出现在两个连接组中)。
  • 这种写法让长链在图中呈折叠的"之"字形排布,可读性更好,也便于增删中间节点。
  • 模板在此发挥最大价值:6 个连接器共享一个模板,5 根线束共享一个模板,整张图只需定义两次共性参数。注意线束模板中省略了 wirecount 与 length 之外的重复项,颜色列表 [TQ, PK, YE, VT] 隐式给出 4 根导线。

输出

08 - 零件号与附加物料(Part numbers and additional components)

新增能力

  • 为零件添加零件号信息(part number information):
    • 只有填写的字段才会进入图纸与 BOM(only provided fields will be added to the diagram and BOM);
  • 线束可逐线指定零件信息(bundles can have part information specified by wire);
  • 可向器件追加附加组件,或直接追加到 BOM(additional parts can be added to components or just to the BOM);
    • 附加组件的数量可按父连接器/电缆的特征成倍计算(quantities can be multiplied by features from parent connector or cable)。

完整代码

options:
  mini_bom_mode: false

connectors:
  X1: &template1 # define a template for later use
    type: Molex KK 254
    pincount: 4
    subtype: female
    manufacturer: '<a href="https://www.molex.com/">Molex</a>' # set manufacter name
    mpn: '<a href="https://www.molex.com/molex/products/part-detail/crimp_housings/0022013047">22013047</a>' # set manufacturer part number
    supplier: Digimouse
    spn: 1234
    # add a list of additional components to a part (shown in graph)
    additional_components:
      - type: Crimp # short identifier used in graph
        subtype: Molex KK 254, 22-30 AWG # extra information added to type in bom
        qty_multiplier: populated # multipier for quantity (number of populated pins)
        manufacturer: Molex # set manufacter name
        mpn: 08500030 # set manufacturer part number
      - type: Test
        qty: 1
        pn: ABC
        manufacturer: Molex
        mpn: 45454
        supplier: Mousikey
        spn: 9999
  X2:
    <<: *template1 # reuse template
    pn: CON4 # set an internal part number for just this connector
  X3:
    <<: *template1 # reuse template

cables:
  W1:
    wirecount: 4
    length: 1
    gauge: 0.25 mm2
    color_code: IEC
    manufacturer: CablesCo
    mpn: ABC123
    supplier: Cables R Us
    spn: 999-888-777
    pn: CAB1
  W2:
    category: bundle
    length: 1
    gauge: 0.25 mm2
    colors: [YE, BK, BK, RD]
    manufacturer: [WiresCo, WiresCo, WiresCo, WiresCo] # set a manufacter per wire
    mpn: [W1-YE, W1-BK, W1-BK, W1-RD]
    supplier: [WireShack, WireShack, WireShack, WireShack]
    spn: [1001, 1002, 1002, 1009]
    pn: [WIRE1, WIRE2, WIRE2, WIRE3]
    # add a list of additional components to a part (shown in graph)
    additional_components:
      - type: Sleve # short identifier used in graph
        subtype: Braided nylon, black, 3mm # extra information added to type in bom
        qty_multiplier: length # multipier for quantity (length of cable)
        unit: m
        pn: SLV-1

connections:
  - - X1: [1-4]
    - W1: [1-4]
    - X2: [1-4]
  - - X1: [1-4]
    - W2: [1-4]
    - X3: [1-4]

additional_bom_items:
  - # define an additional item to add to the bill of materials (does not appear in graph)
    description: Label, pinout information
    qty: 2
    designators:
      - X2
      - X3
    manufacturer: '<a href="https://www.bradyid.com">Brady</a>'
    mpn: '<a href="https://www.bradyid.com/wire-cable-labels/bmp71-bmp61-m611-tls-2200-nylon-cloth-wire-general-id-labels-cps-2958789">B-499</a>'
    pn: Label-ID-1

解读

  • 零件信息字段:连接器与电缆都支持 pn(内部零件号)、manufacturer(制造商)、mpn(制造商零件号)、supplier(供应商)、spn(供应商零件号)。这些字段全部可选,只有填写的字段才会出现在图与 BOM 中。字段值支持 HTML 链接,例如把 mpn 包成 <a href="..."> 即可生成可点击的零件号(HTML 输出中生效)。
  • options: mini_bom_mode: false:全局选项。默认值为 true,此时图中只显示附加组件的 BOM 条目引用与基本信息;设为 false 后,图中完整显示附加组件信息(见 docs/syntax.md 的 "Options" 一节)。示例通过该选项展示附加组件在图纸节点内的完整呈现。
  • 附加组件(additional_components):挂在连接器/电缆下,会显示在图中,同时进入 BOM。type 是图中的短标识,subtype 是 BOM 中追加到 type 的补充信息。
  • 数量倍增器(qty_multiplier):按父器件的特征自动计算数量。可选值(见 docs/syntax.md):
    • 用于连接器:pincount(引脚数)、populated(已插装引脚数)、unpopulated(未插装引脚数);
    • 用于电缆/线束:wirecount(导线数)、terminations(端接数)、length(电缆长度)、total_length(线束各导线长度之和)。
    • 本例中 Crimp 的 qty_multiplier: populated 使端子数量等于已插装引脚数(3 个连接器共 12 个),Sleve 的 qty_multiplier: length 使护套数量等于电缆长度(1 m)。
  • 线束逐线零件信息:W2 是 bundle,其 manufacturer、mpn、supplier、spn、pn 均以列表形式逐线指定(列表长度与导线数一致)。对应 src/wireviz/Harness.py 中的注释 "for bundles, individual wires can have part information" 及 if cable.category == "bundle": 的分支处理。
  • 直接加 BOM 的条目(additional_bom_items):只进 BOM、不进图。支持 description、qty、unit、designators(设计符列表)以及 pn/manufacturer/mpn/supplier/spn 等字段(见 docs/syntax.md 的 "BOM items" 一节)。

生成的 BOM

tutorial08.bom.tsv 展示了本示例的完整输出:

Id	Description	Qty	Unit	Designators	P/N	Manufacturer	MPN	Supplier	SPN
1	Cable, 4 x 0.25 mm²	1	m	W1	CAB1	CablesCo	ABC123	Cables R Us	999-888-777
2	Connector, Molex KK 254, female, 4 pins	2		X1, X3		Molex	22013047	Digimouse	1234
3	Connector, Molex KK 254, female, 4 pins	1		X2	CON4	Molex	22013047	Digimouse	1234
4	Crimp, Molex KK 254, 22-30 AWG	12		X1, X2, X3		Molex	08500030
5	Label, pinout information	2		X2, X3	Label-ID-1	Brady	B-499
6	Sleve, Braided nylon, black, 3mm	1	m	W2	SLV-1
7	Test	3		X1, X2, X3	ABC	Molex	45454	Mousikey	9999
8	Wire, 0.25 mm², BK	2	m	W2	WIRE2	WiresCo	W1-BK	WireShack	1002
9	Wire, 0.25 mm², RD	1	m	W2	WIRE3	WiresCo	W1-RD	WireShack	1009
10	Wire, 0.25 mm², YE	1	m	W2	WIRE1	WiresCo	W1-YE	WireShack	1001

对照解读:

  • X2 因为单独设置了 pn: CON4 而与 X1、X3 分成两行(Designators 分别为 X1, X3 与 X2);
  • Crimp 数量 12 = 3 个连接器 × 4 个已插装引脚(qty_multiplier: populated);
  • Sleve 数量 1、单位 m,等于 W2 长度(qty_multiplier: length);
  • 线束 W2 的每条导线单独成行(Wire, 0.25 mm², BK 等),各自的 MPN/供应商零件号/内部零件号逐行列出;
  • Label, pinout information 来自 additional_bom_items,只出现在 BOM 中。

运行方法:从 YAML 到图纸与 BOM

教程各示例都配有对应的 .gv、.svg、.png、.html 与 .bom.tsv 产物。要亲自生成这些输出,可使用 WireViz 命令行工具(入口为 src/wireviz/wv_cli.py):

python -m wireviz tutorial01.yml

默认输出格式为 hpst,即同时生成 HTML(h)、PNG(p)、SVG(s)与 TSV BOM(t)。-f/--format 支持以下格式码(详见 wv_cli.py 中的 format_codes):

格式码 输出 说明
g GV Graphviz 点脚本(中间产物)
h HTML 带内嵌图的 HTML 预览
p PNG 位图图片
s SVG 矢量图片
t TSV 物料清单(BOM)

常用选项还包括 -o/--output-dir(指定输出目录)、-O/--output-name(指定输出文件名)、-p/--prepend(预置 YAML,可叠加多个,适合共享公共定义)与 -V/--version(打印版本)。

延伸阅读

登录后查看全文
WireViz