198 行
8.8 KiB
Python
198 行
8.8 KiB
Python
# -*- coding: utf-8 -*-
|
||
u"""ESP32-S3 引脚占用审计 —— 直接读 `五路直供电源板设计.md` §8.1 的 GPIO 表。
|
||
|
||
/c/Python314/python .claude/s3_pin_audit.py
|
||
/c/Python314/python .claude/s3_pin_audit.py --octal # 按八线 PSRAM(R8) 严格判
|
||
/c/Python314/python .claude/s3_pin_audit.py --free # 顺便列出还空着的脚
|
||
|
||
## 为什么自己写而不是用现成的
|
||
|
||
社区那个 `agodianel/esp32-claude-workbench` 的 `esp32_pin_audit`（78★）
|
||
**判据全是 ESP32-classic 的，全仓库没有芯片型号分支**，放到 S3 上双向都错：
|
||
|
||
FORBIDDEN_PINS = {6,7,8,9,10,11} # classic 的内部 flash；S3 上是普通 IO → 假警报
|
||
STRAPPING_PINS = {0,2,12,15} # S3 是 {0,3,45,46}
|
||
INPUT_ONLY_PINS = {34,...,39} # S3 **没有**仅输入脚 → 假警报
|
||
（S3 真正的 flash/PSRAM 脚 26~32 它一个都不查 → **静默漏报，这条最要命**）
|
||
|
||
一个自信地给错答案的检查器比没有检查器更糟，所以这里按 Espressif 官方文档重写。
|
||
|
||
## 判据出处
|
||
|
||
`docs.espressif.com/.../esp32s3/api-reference/peripherals/gpio.html`（2026-09-07 核对）：
|
||
|
||
· 物理存在 GPIO0~21 与 GPIO26~48，**22~25 不存在**
|
||
· GPIO26~32 供 SPI flash / PSRAM，不建议他用
|
||
· 用八线(Octal) flash 或 PSRAM 时 **GPIO33~37 也被占**（接 SPIIO4~7 / SPIDQS）
|
||
· strapping 脚是 **GPIO0 / 3 / 45 / 46**
|
||
· GPIO19 / 20 默认给 USB-Serial-JTAG，改作普通 IO 则 USB-JTAG 失效
|
||
· ADC1 = GPIO1~10，ADC2 = GPIO11~20（**ADC2 在 Wi-Fi 工作时不可用**）
|
||
· **没有任何仅输入脚**（这一条与 ESP32-classic 不同）
|
||
"""
|
||
from __future__ import print_function
|
||
|
||
import argparse
|
||
import io
|
||
import os
|
||
import re
|
||
import sys
|
||
|
||
HERE = os.path.dirname(os.path.abspath(__file__))
|
||
DOC = os.path.join(HERE, '..', u'五路直供电源板设计.md')
|
||
|
||
# --- ESP32-S3 事实表（改这里要附官方出处）----------------------------------
|
||
EXISTS = set(range(0, 22)) | set(range(26, 49)) # 22~25 不存在
|
||
FLASH_PSRAM = set(range(26, 33)) # 26~32 恒占
|
||
OCTAL_ONLY = set(range(33, 38)) # 33~37 仅八线版占用
|
||
STRAPPING = {0: u'boot 模式', 3: u'JTAG 源选择',
|
||
45: u'VDD_SPI 电压选择', 46: u'boot / ROM 日志'}
|
||
USB_JTAG = {19: u'USB D−', 20: u'USB D+'}
|
||
ADC1 = set(range(1, 11))
|
||
ADC2 = set(range(11, 21))
|
||
UART0 = {43: u'U0TXD', 44: u'U0RXD'}
|
||
|
||
|
||
def parse_doc_pins(path):
|
||
u"""从设计文档的 §8.1 表里抓 `| ... | IOxx | ... | `信号` | ...` 行。
|
||
|
||
表里有历史版本的重复表格，同一个 IO 可能出现多次 —— 以**最后一次**为准
|
||
（文档是顺序追加的，后面的是改版后的定稿）。
|
||
"""
|
||
if not os.path.exists(path):
|
||
return None, u'找不到设计文档 %s' % path
|
||
txt = io.open(path, encoding='utf-8', errors='replace').read()
|
||
pins = {}
|
||
# 表列：| 模块脚 | GPIO | 方向/边 | 信号 | 去哪儿 |
|
||
# ⚠️ 不能用「一行一个 IO」的正则：`| 13 / 14 | IO19 / IO20 | 东 |
|
||
# `USB_DM` / `USB_DP` |` 这种**一行两脚**会整行匹配失败 ——
|
||
# 结果 IO19/20 既不在已分配里、又被算进「空闲脚」，正是静默漏报。
|
||
# 所以按列切开，把该列里的 IO 号和信号名成对取出。
|
||
for line in txt.splitlines():
|
||
if not line.startswith(u'|'):
|
||
continue
|
||
cells = line.split(u'|')
|
||
if len(cells) < 6:
|
||
continue
|
||
nums = [int(x) for x in re.findall(r'IO(\d{1,2})\b', cells[2])]
|
||
if not nums:
|
||
continue
|
||
sigs = re.findall(r'`([^`]+)`', cells[4])
|
||
if not sigs: # 信号列没打反引号的，退回整格文本
|
||
s = re.sub(r'[*\s]', u'', cells[4])
|
||
sigs = [s] if s else []
|
||
for i, n in enumerate(nums):
|
||
sig = sigs[i] if i < len(sigs) else (sigs[-1] if sigs else u'')
|
||
sig = sig.strip().strip(u'*')
|
||
if sig and sig not in (u'同', u'—'):
|
||
pins[n] = sig
|
||
return pins, None
|
||
|
||
|
||
def audit(pins, octal):
|
||
findings = [] # (等级, GPIO, 信号, 说明)
|
||
reserved = set(FLASH_PSRAM)
|
||
if octal:
|
||
reserved |= OCTAL_ONLY
|
||
|
||
for n in sorted(pins):
|
||
sig = pins[n]
|
||
if n not in EXISTS:
|
||
findings.append((u'ERROR', n, sig,
|
||
u'ESP32-S3 上**没有** GPIO%d（22~25 是空缺）' % n))
|
||
continue
|
||
if n in FLASH_PSRAM:
|
||
findings.append((u'ERROR', n, sig,
|
||
u'SPI flash / PSRAM 恒占（26~32），拿来做 IO 会起不来'))
|
||
elif n in OCTAL_ONLY:
|
||
lvl = u'ERROR' if octal else u'WARN'
|
||
findings.append((lvl, n, sig,
|
||
u'八线(R8/Octal) flash/PSRAM 版占用 33~37；'
|
||
u'换 R8 料就冲突%s' % (u'' if octal else u'（当前按非八线判）')))
|
||
if n in STRAPPING:
|
||
findings.append((u'WARN', n, sig,
|
||
u'strapping 脚（%s）—— 外部电路不能在上电瞬间把它拉错'
|
||
% STRAPPING[n]))
|
||
if n in USB_JTAG:
|
||
findings.append((u'INFO', n, sig,
|
||
u'USB-Serial-JTAG 的 %s，占了就没有原生 USB 调试口'
|
||
% USB_JTAG[n]))
|
||
if n in UART0:
|
||
findings.append((u'WARN', n, sig,
|
||
u'ROM 默认 UART0 %s，占了会跟启动日志抢线' % UART0[n]))
|
||
# ADC2 只在真的当模拟输入用时才有 Wi-Fi 冲突
|
||
if n in ADC2 and re.search(r'NTC|ADC|AIN|VSENSE|TEMP', sig, re.I):
|
||
findings.append((u'ERROR', n, sig,
|
||
u'落在 ADC2（GPIO11~20），**Wi-Fi 一开 ADC2 就读不了**；'
|
||
u'模拟量要挪到 ADC1 = GPIO1~10'))
|
||
return findings, reserved
|
||
|
||
|
||
def main():
|
||
ap = argparse.ArgumentParser()
|
||
ap.add_argument('--octal', action='store_true',
|
||
help=u'按八线 PSRAM（WROOM-1 R8）严格判，33~37 视为占用')
|
||
ap.add_argument('--free', action='store_true', help=u'列出还空着的脚')
|
||
ap.add_argument('--doc', default=DOC)
|
||
a = ap.parse_args()
|
||
|
||
pins, err = parse_doc_pins(a.doc)
|
||
if err:
|
||
print(err)
|
||
return 2
|
||
if not pins:
|
||
print(u'在文档里没抓到 IOxx 行 —— §8.1 的表格式可能改了，先看一眼再说。')
|
||
return 2
|
||
|
||
print(u'从 %s 抓到 %d 个已分配 GPIO：' % (os.path.basename(a.doc), len(pins)))
|
||
print(u' ' + u', '.join(u'IO%d=%s' % (n, pins[n]) for n in sorted(pins)))
|
||
print()
|
||
|
||
findings, reserved = audit(pins, a.octal)
|
||
order = {u'ERROR': 0, u'WARN': 1, u'INFO': 2}
|
||
findings.sort(key=lambda f: (order[f[0]], f[1]))
|
||
|
||
if not findings:
|
||
print(u'✓ 没有发现问题。')
|
||
else:
|
||
icon = {u'ERROR': u'❌', u'WARN': u'⚠️ ', u'INFO': u'ℹ️ '}
|
||
for lvl, n, sig, msg in findings:
|
||
print(u'%s [%-5s] IO%-2d %-16s %s' % (icon[lvl], lvl, n, sig, msg))
|
||
|
||
ne = sum(1 for f in findings if f[0] == u'ERROR')
|
||
nw = sum(1 for f in findings if f[0] == u'WARN')
|
||
print(u'\n合计：ERROR %d，WARN %d，INFO %d'
|
||
% (ne, nw, len(findings) - ne - nw))
|
||
|
||
# 冲突：同一个脚被分给两个信号（parse 已经按最后一次覆盖，这里查文档正文里
|
||
# 是否还有别的表把同一信号挂到两个脚上）
|
||
rev = {}
|
||
for n, s in pins.items():
|
||
rev.setdefault(s, []).append(n)
|
||
dup = {s: v for s, v in rev.items() if len(v) > 1}
|
||
if dup:
|
||
print(u'\n⚠️ 同一信号出现在多个脚上（多半是文档里的历史表没清）：')
|
||
for s, v in sorted(dup.items()):
|
||
print(u' %-16s → %s' % (s, ', '.join(u'IO%d' % x for x in sorted(v))))
|
||
|
||
if a.free:
|
||
used = set(pins)
|
||
free = sorted(EXISTS - used - reserved - set(STRAPPING) - set(UART0))
|
||
print(u'\n还空着的脚（已排除 flash/PSRAM %s、strapping、UART0）：'
|
||
% (u'26~37' if a.octal else u'26~32'))
|
||
print(u' ' + u', '.join(u'IO%d' % n for n in free))
|
||
# ⚠️ ADC1 里也要把 strapping 剔掉：IO3 是 ADC1_CH2，但它是 JTAG 源选择
|
||
# strapping 脚，挂个 NTC 分压上去会在上电瞬间把它拉到中间电平。
|
||
adc1_free = sorted(ADC1 - used - set(STRAPPING) - reserved)
|
||
adc1_strap = sorted((ADC1 - used) & set(STRAPPING))
|
||
print(u' 其中 ADC1（能在 Wi-Fi 下用的模拟脚）还剩：%s'
|
||
% (u', '.join(u'IO%d' % n for n in adc1_free) if adc1_free else u'无'))
|
||
if adc1_strap:
|
||
print(u' （%s 也是 ADC1，但同时是 strapping 脚，接模拟量要先确认上电电平）'
|
||
% u', '.join(u'IO%d' % n for n in adc1_strap))
|
||
|
||
return 1 if ne else 0
|
||
|
||
|
||
if __name__ == '__main__':
|
||
sys.exit(main())
|