422 lines
16 KiB
Python
422 lines
16 KiB
Python
#!/usr/bin/env python3
|
||
# -*- coding: utf-8 -*-
|
||
r"""netlist_sem.py - KiCad Pcbnew 导出网表 (.tel) 语义化工具
|
||
|
||
将精简导出网表（$PACKAGES/$NETS，无料号、无引脚功能名）结合引脚知识库
|
||
(pinout_kb.json) 与规则引擎，生成紧凑的结构化语义图（Markdown），
|
||
供 LLM / 工程师快速理解板级连接。
|
||
|
||
用法（仓库根目录，统一 venv 解释器）:
|
||
& '.venv\Scripts\python.exe' tools/netlist_semantics/netlist_sem.py dump-pins docs/硬件平台/V0.0.tel
|
||
& '.venv\Scripts\python.exe' tools/netlist_semantics/netlist_sem.py semantic docs/硬件平台/V0.0.tel -o docs/硬件平台/V0.0_网表语义图.md
|
||
|
||
纯标准库实现，无第三方依赖。
|
||
"""
|
||
|
||
import argparse
|
||
import json
|
||
import os
|
||
import re
|
||
import sys
|
||
from collections import OrderedDict, defaultdict
|
||
|
||
# ---------------------------------------------------------------- 解析
|
||
|
||
REF_RE = re.compile(r'^[A-Z]{1,4}\d+$')
|
||
|
||
|
||
def _group_entries(lines, is_start=None):
|
||
"""按条目分组。is_start(ln) 判断是否新条目起始行；缺省：非空白起始行=新条目。"""
|
||
if is_start is None:
|
||
def is_start(ln):
|
||
return ln[0] not in ' \t'
|
||
entries = []
|
||
cur = []
|
||
for ln in lines:
|
||
if ln.strip() == '':
|
||
continue
|
||
if is_start(ln):
|
||
if cur:
|
||
entries.append('\n'.join(cur))
|
||
cur = [ln]
|
||
else:
|
||
if not cur:
|
||
cur = [ln.strip()]
|
||
else:
|
||
cur.append(ln.strip())
|
||
if cur:
|
||
entries.append('\n'.join(cur))
|
||
return entries
|
||
|
||
|
||
def _tokens_after(text, sep=';'):
|
||
head, _, tail = text.partition(sep)
|
||
tail = tail.replace(',', ' ')
|
||
return head.strip(), [t for t in tail.split() if t]
|
||
|
||
|
||
def _parse_package(entry):
|
||
"""解析单个 PACKAGE 条目，返回 (fp, value, [refs])。
|
||
兼容两种行格式：
|
||
单行: FP ! FP ! '{Value}' ; REF1 REF2 ...
|
||
多行: FP ! FP ! '{Value}' , 然后续行列 REF
|
||
字段(封装/值)取首行按 ! 分割；refs 取首行 ';' 之后 + 所有续行。
|
||
"""
|
||
lines = entry.split('\n')
|
||
first = lines[0].strip()
|
||
head = first.split(';', 1)[0] if ';' in first else first
|
||
fields = [x.strip() for x in head.split('!')]
|
||
fp = fields[0] if fields else ''
|
||
value = fields[2].strip().rstrip(',') if len(fields) > 2 else ''
|
||
refpart = first.split(';', 1)[1] if ';' in first else ''
|
||
if len(lines) > 1:
|
||
refpart = (refpart + '\n' if refpart else '') + '\n'.join(lines[1:])
|
||
toks = re.split(r'[\s,]+', refpart.replace(',', ' '))
|
||
refs = [t for t in toks if t and REF_RE.match(t)]
|
||
return fp, value, refs
|
||
|
||
|
||
def parse_netlist(path):
|
||
"""解析 .tel。返回 (packages, nets)
|
||
packages: {ref: {'fp': 封装, 'value': 值}}
|
||
nets: {net: [(ref, pin), ...]}
|
||
"""
|
||
with open(path, encoding='utf-8', errors='replace') as f:
|
||
text = f.read()
|
||
|
||
sections = {}
|
||
name, buf = None, []
|
||
for ln in text.splitlines():
|
||
if ln.startswith('$'):
|
||
if name:
|
||
sections[name] = buf
|
||
name = ln.strip().lstrip('$')
|
||
buf = []
|
||
elif name:
|
||
buf.append(ln)
|
||
if name:
|
||
sections[name] = buf
|
||
|
||
packages = {}
|
||
for entry in _group_entries(sections.get('PACKAGES', []),
|
||
lambda ln: ' ! ' in ln):
|
||
fp, value, refs = _parse_package(entry)
|
||
if not fp:
|
||
continue
|
||
for r in refs:
|
||
packages[r] = {'fp': fp, 'value': value}
|
||
|
||
nets = {}
|
||
for entry in _group_entries(sections.get('NETS', [])):
|
||
head, toks = _tokens_after(entry)
|
||
name = head.strip().strip("'\"")
|
||
if not name:
|
||
continue
|
||
pins = []
|
||
for t in toks:
|
||
ref, _, pin = t.rpartition('.')
|
||
if REF_RE.match(ref) and pin:
|
||
pins.append((ref, pin))
|
||
if pins:
|
||
nets[name] = pins
|
||
|
||
return packages, nets
|
||
|
||
|
||
def build_pin_index(packages, nets):
|
||
"""pin_index[ref][pin] = [net, ...]；unused_refs = 有封装无网络的位号"""
|
||
pin_index = defaultdict(lambda: defaultdict(list))
|
||
seen_refs = set()
|
||
for net, pins in nets.items():
|
||
for ref, pin in pins:
|
||
pin_index[ref][pin].append(net)
|
||
seen_refs.add(ref)
|
||
for ref in list(pin_index):
|
||
if ref not in packages:
|
||
pass # 网络中出现但 PACKAGES 缺失（如被 DNP 隐藏），仍保留
|
||
unused = [r for r in packages if r not in seen_refs]
|
||
return pin_index, sorted(unused)
|
||
|
||
|
||
# ---------------------------------------------------------------- 知识库
|
||
|
||
def load_kb(path):
|
||
"""返回 (instances, nets)
|
||
instances: {ref: {mpn, pkg, desc}}
|
||
nets: {net: {func, gpio, note}}
|
||
说明：本工程 KiCad 符号引脚号为任意编号（非数据手册脚号，如 U17.133=PB3），
|
||
故语义标注落在【网络名】与【位号】两级，不做引脚级断言。
|
||
"""
|
||
with open(path, encoding='utf-8') as f:
|
||
kb = json.load(f)
|
||
return kb.get('instances', {}), kb.get('nets', {})
|
||
|
||
|
||
# ---------------------------------------------------------------- 分类规则
|
||
|
||
GROUND_NETS = {'GND', 'AGND', 'PGND', 'CGND'}
|
||
RAIL_NETS = {'3.3V', '5V', 'C3.3V', 'G3.3V', 'AVCC', 'AVDDL', 'STM_VDDA', 'VDD50'}
|
||
CLOCK_NETS = {'XI', 'XO', 'RXI', 'RXO', 'CLOCK'}
|
||
|
||
|
||
def classify_net(name, pins=None, pin_index=None):
|
||
"""返回 (类别, 说明)。类别: GND / POWER / CLOCK / SIGNAL
|
||
串行时钟 (SCK/SCL/SCLK) 归 SIGNAL（接口信号），仅系统/晶振时钟归 CLOCK。"""
|
||
if name in GROUND_NETS or name.endswith('_GND'):
|
||
return 'GND', '地'
|
||
if name in RAIL_NETS or re.fullmatch(r'\d+\.\d+V', name) or name.startswith('VDD'):
|
||
return 'POWER', '电源轨'
|
||
if name in CLOCK_NETS:
|
||
return 'CLOCK', '时钟'
|
||
return 'SIGNAL', '信号'
|
||
|
||
|
||
# 接口分组规则：按网名匹配（顺序敏感，先匹配先归组）
|
||
INTERFACE_RULES = [
|
||
('以太网 MDI', 'U2 RTL8305 双口 MDI → T1 网络变压器 + J1/J2 RJ45（端口A/B）；U1 CH395F 侧为无名网',
|
||
lambda n: n in ('RX_P', 'RX_N', 'TX_P', 'TX_N') or
|
||
re.fullmatch(r'RX[AB]_[PN]|TX[AB]_[PN]', n) is not None),
|
||
('SPI-NAND (SPI1)', 'U17 SPI1 → U18 74LVC16245 → U19 GD5F2GQ5UE NAND（双向缓冲）',
|
||
lambda n: n.startswith('GD_') or n in ('SPI1_SOMI', 'SPI1_SIMO')),
|
||
('SPI-ETH (SPI2)', 'U17 SPI2 → U1 CH395F（SPI 以太网）',
|
||
lambda n: n.startswith('CH395F_')),
|
||
('I2C-时钟', 'U17 I2C → U16 SD2506 时钟/RTC 芯片',
|
||
lambda n: n in ('SD_SDA', 'SD_SCL')),
|
||
('UART-ST', 'U17 USART → U9/U10/U11 隔离器 → RS232/RS485 通道',
|
||
lambda n: re.fullmatch(r'ST_(TX|RX)\d', n) is not None or n == 'ST_DIR4'),
|
||
('RS-485', 'U11 信号隔离 + U8 光耦(DIR) → U15 TP8485E → U12 ESD → CN1 485 总线',
|
||
lambda n: n in ('RS485_A', 'RS485_B', 'TX4', 'RX4', 'DIR4')),
|
||
('RS-232', 'U9/U10 隔离 → U13 双通道 232 收发器 → RS232 总线（CN1 / U14）',
|
||
lambda n: re.fullmatch(r'RS232_(TX|RX)\d', n) is not None or
|
||
re.fullmatch(r'[TR]X\d', n) is not None),
|
||
('LCD 8080 并口', 'U17 FSMC → H1 16P 排针 → 板外 LCD（16bit 8080 并口）',
|
||
lambda n: n.startswith('LCD_')),
|
||
('ADC 并口', 'U17 FSMC 读 ↔ U3 TPAFE5160（16bit + 控制线）',
|
||
lambda n: n.startswith('TP_') or re.fullmatch(r'DB\d+', n) is not None),
|
||
('ADC 输入', 'U3 TPAFE5160 8 通道输入（经 R 分压/保护至 AIN）',
|
||
lambda n: n.startswith('AIN') or n.startswith('ADC')),
|
||
('按键', 'U17 GPIO 按键（上拉 3.3V，低有效）',
|
||
lambda n: re.fullmatch(r'KEY\d+', n) is not None),
|
||
('子板接口 (U18)', 'U17 ↔ U18 74LVC16245 ↔ U5 WINGTAT 子板（继电器/告警/状态/外键）',
|
||
lambda n: n.startswith('EXTK') or n.startswith('HT_') or n.startswith('ST_IN_') or
|
||
n.endswith('_LED') or n in ('RELAY_STO', 'H16', 'V15', 'J3', 'F3', 'K3', 'RAS',
|
||
'DQM0', 'DQM1', 'WAIT1', 'SDCKE', 'CF_P', 'CF_Q',
|
||
'V_ZL1', 'V_ZL2', 'R16')),
|
||
('SWD/JTAG 调试', 'U17 调试口 → H2 3P 排针（SWCLK/SWDIO/GND）',
|
||
lambda n: n in ('SWCLK', 'SWDIO', 'NRST')),
|
||
('状态指示', '板级 LED / PHY 中断 / 显示控制',
|
||
lambda n: re.fullmatch(r'LED\d+', n) is not None or
|
||
n in ('PBLED', 'DIS_EEE', 'INT')),
|
||
]
|
||
|
||
|
||
def group_interfaces(signals):
|
||
groups = OrderedDict()
|
||
ungrouped = []
|
||
for net in signals:
|
||
placed = False
|
||
for gname, gdesc, pat in INTERFACE_RULES:
|
||
if pat(net):
|
||
groups.setdefault(gname, {'desc': gdesc, 'nets': []})['nets'].append(net)
|
||
placed = True
|
||
break
|
||
if not placed:
|
||
ungrouped.append(net)
|
||
return groups, ungrouped
|
||
|
||
|
||
# ---------------------------------------------------------------- 输出
|
||
|
||
def render_semantic(packages, nets, pin_index, instances, nets_kb):
|
||
L = []
|
||
ap = L.append
|
||
|
||
def net_ann(net):
|
||
"""网络语义注释（来自知识库 nets 表）；无名网($..)返回空。"""
|
||
if net.startswith('$'):
|
||
return ''
|
||
ann = nets_kb.get(net)
|
||
if not ann:
|
||
return ''
|
||
bits = []
|
||
if ann.get('func'):
|
||
bits.append(ann['func'])
|
||
if ann.get('gpio'):
|
||
bits.append(ann['gpio'])
|
||
if ann.get('note'):
|
||
bits.append(ann['note'])
|
||
return ' '.join(bits)
|
||
|
||
ics = sorted((r for r in pin_index if r.startswith('U')),
|
||
key=lambda r: int(re.sub(r'\D', '', r) or 0))
|
||
oths = sorted((r for r in pin_index if not r.startswith('U')))
|
||
|
||
ap('# V0.0 网表语义图（自动生成）')
|
||
ap('')
|
||
ap('> 由 `tools/netlist_semantics/netlist_sem.py` 从 `V0.0.tel` + `pinout_kb.json` 生成。')
|
||
ap('> 网表仅含位号/引脚号/网名；MPN 与信号语义由知识库补全。')
|
||
ap('> 注意：KiCad 符号引脚号为任意编号（非数据手册脚号，如 U17.133=PB3），引脚功能以【网名+知识库】为准。')
|
||
ap('')
|
||
ap('## 1. 概览')
|
||
ap('')
|
||
ap(f'- 元件位号: {len(packages)} 组 / 网络: {len(nets)} 条')
|
||
n_gnd = sum(1 for n in nets if n in GROUND_NETS or n.endswith('_GND'))
|
||
n_rail = sum(1 for n in nets if n in RAIL_NETS)
|
||
n_unnamed = sum(1 for n in nets if n.startswith('$'))
|
||
ap(f'- 地网络: {n_gnd} / 电源轨: {n_rail} / 未命名(内部)网: {n_unnamed}')
|
||
ap('')
|
||
|
||
# --- 电源域
|
||
ap('## 2. 电源与地')
|
||
ap('')
|
||
ap('| 网络 | 类别 | 连接引脚数 | 主要去向 |')
|
||
ap('|---|---|---|---|')
|
||
for net in sorted(nets, key=lambda n: (n not in RAIL_NETS, n not in GROUND_NETS, n)):
|
||
cat, _ = classify_net(net, nets[net], pin_index)
|
||
if cat not in ('GND', 'POWER'):
|
||
continue
|
||
pins = nets[net]
|
||
ics_hit = sorted(set(r for r, _ in pins if r.startswith('U')))
|
||
others = sorted(set(r for r, _ in pins if not r.startswith('U')))
|
||
dest = ', '.join(ics_hit[:4] + (['…'] if len(ics_hit) > 4 else []))
|
||
if others:
|
||
dest += f" / {len(others)}×被动件"
|
||
ap(f'| {net} | {cat} | {len(pins)} | {dest} |')
|
||
ap('')
|
||
|
||
# --- 接口
|
||
groups, ungrouped = group_interfaces(
|
||
[n for n in nets if not n.startswith('$') and
|
||
classify_net(n, nets[n], pin_index)[0] == 'SIGNAL'])
|
||
ap('## 3. 接口与总线')
|
||
ap('')
|
||
for gname, g in groups.items():
|
||
ap(f'### {gname}')
|
||
ap('')
|
||
ap(f'{g["desc"]}')
|
||
ap('')
|
||
ap('| 网络 | 语义（知识库） | 连接 |')
|
||
ap('|---|---|---|')
|
||
for net in g['nets']:
|
||
pins = nets[net]
|
||
desc = ', '.join(f'{r}.{p}' for r, p in pins[:8]) + (' …' if len(pins) > 8 else '')
|
||
ap(f'| {net} | {net_ann(net) or "—"} | {desc} |')
|
||
ap('')
|
||
if ungrouped:
|
||
ap('### 未归类信号')
|
||
ap('')
|
||
ap(', '.join(ungrouped))
|
||
ap('')
|
||
|
||
# --- 芯片引脚
|
||
ap('## 4. 芯片引脚')
|
||
ap('')
|
||
for ref in ics:
|
||
info = instances.get(ref, {})
|
||
mpn = info.get('mpn', '?')
|
||
desc = info.get('desc', '')
|
||
fp = packages.get(ref, {}).get('fp', '?')
|
||
pins = pin_index[ref]
|
||
ap(f'### {ref} — {mpn}')
|
||
ap('')
|
||
if desc:
|
||
ap(f'{desc}')
|
||
ap('')
|
||
ap(f'封装: `{fp}`（{len(pins)} 脚入网）')
|
||
ap('')
|
||
ap('| Pin | 网络 | 语义（知识库） |')
|
||
ap('|---|---|---|')
|
||
|
||
def _key(kv):
|
||
p = kv[0]
|
||
m = re.fullmatch(r'(\d+)', p)
|
||
return (0, int(m.group(1))) if m else (1, p)
|
||
|
||
for pin, nets_h in sorted(pins.items(), key=_key):
|
||
uniq = sorted(set(nets_h))
|
||
ann = '；'.join(a for a in (net_ann(n) for n in uniq) if a) or '—'
|
||
ap(f'| {pin} | {", ".join(uniq)} | {ann} |')
|
||
ap('')
|
||
|
||
# --- 其余器件
|
||
ap('## 5. 连接件/晶振/变压器/无源/分立')
|
||
ap('')
|
||
ap('| 位号 | 器件（知识库 MPN） | 引脚→网络 |')
|
||
ap('|---|---|---|')
|
||
for ref in oths:
|
||
info = instances.get(ref, {})
|
||
mpn = info.get('mpn', '')
|
||
fp = packages.get(ref, {}).get('fp', '?')
|
||
what = f'{mpn}（{fp}）' if mpn else fp
|
||
pins = pin_index[ref]
|
||
desc = '; '.join(f'{p}→{", ".join(sorted(set(ns)))}'
|
||
for p, ns in sorted(pins.items(), key=lambda kv: kv[0]))
|
||
ap(f'| {ref} | {what} | {desc} |')
|
||
ap('')
|
||
|
||
# 文件结尾必须恰好一个换行：pre-commit end-of-file-fixer 同时禁止
|
||
# “无结尾换行”和“结尾空行”（双换行）。rstrip 归一化末尾多余换行
|
||
# （含上方收尾的 ap('')），今后增删末尾行也不会破坏提交门禁。
|
||
return '\n'.join(L).rstrip('\n') + '\n'
|
||
|
||
|
||
def dump_pins(packages, nets):
|
||
pin_index, unused = build_pin_index(packages, nets)
|
||
print(f'== PACKAGES: {len(packages)} refs; NETS: {len(nets)} ==')
|
||
print(f'== refs in packages but on no net: {unused} ==')
|
||
ics = sorted((r for r in pin_index if r.startswith('U')),
|
||
key=lambda r: int(re.sub(r'\D', '', r) or 0))
|
||
oths = sorted(r for r in pin_index if not r.startswith('U'))
|
||
for ref in ics + oths:
|
||
fp = packages.get(ref, {}).get('fp', '?')
|
||
pins = pin_index[ref]
|
||
print(f'\n### {ref} [{fp}] ({len(pins)} pins)')
|
||
|
||
def _key(kv):
|
||
p = kv[0]
|
||
m = re.fullmatch(r'(\d+)', p)
|
||
return (0, int(m.group(1))) if m else (1, p)
|
||
|
||
for pin, nets_h in sorted(pins.items(), key=_key):
|
||
print(f' {pin:>4} {", ".join(sorted(set(nets_h)))}')
|
||
|
||
|
||
# ---------------------------------------------------------------- main
|
||
|
||
def main():
|
||
here = os.path.dirname(os.path.abspath(__file__))
|
||
ap = argparse.ArgumentParser(
|
||
description='KiCad Pcbnew .tel 网表语义化（解析 + 引脚知识库 + 规则引擎）')
|
||
sub = ap.add_subparsers(dest='cmd', required=True)
|
||
|
||
p1 = sub.add_parser('dump-pins', help='按位号列出 引脚→网络（用于编制知识库）')
|
||
p1.add_argument('netlist')
|
||
|
||
p2 = sub.add_parser('semantic', help='生成语义图 Markdown')
|
||
p2.add_argument('netlist')
|
||
p2.add_argument('-o', '--out', default=None,
|
||
help='输出文件（缺省打印到 stdout）')
|
||
p2.add_argument('--kb', default=os.path.join(here, 'pinout_kb.json'))
|
||
|
||
a = ap.parse_args()
|
||
packages, nets = parse_netlist(a.netlist)
|
||
if a.cmd == 'dump-pins':
|
||
dump_pins(packages, nets)
|
||
else:
|
||
pin_index, unused = build_pin_index(packages, nets)
|
||
instances, nets_kb = load_kb(a.kb)
|
||
doc = render_semantic(packages, nets, pin_index, instances, nets_kb)
|
||
if a.out:
|
||
with open(a.out, 'w', encoding='utf-8', newline='\n') as f:
|
||
f.write(doc)
|
||
print(f'written: {a.out} ({len(doc)} chars)')
|
||
else:
|
||
sys.stdout.write(doc)
|
||
print(f'[stats] packages={len(packages)} nets={len(nets)} '
|
||
f'kb_instances={len(instances)} kb_nets={len(nets_kb)} unused={unused}',
|
||
file=sys.stderr)
|
||
|
||
|
||
if __name__ == '__main__':
|
||
main()
|