Initial commit: knowledge base

esp32_fail_log.md

@@ -0,0 +1,235 @@
+# ESP32翻车全记录
+
+> **类别：fail_log** | **芯片：cross-platform** | **主题：ESP32翻车全记录 (2026.05-07)**
+
+> 从2026年5月入坑到2026年7月V5.1投板，所有ESP32相关翻车事件汇总。按时间顺序排列，每条附项目版本、代价和教训。
+
+---
+
+## 一、面包板原型阶段（2026年5月）
+
+### 1. Arduino IDE板卡装错
+- **项目**：电池检测仪早期面包板验证
+- **翻车**：装了"Arduino ESP32 Boards"（只有Nano ESP32），不是"esp32 by Espressif Systems"，编译选不到ESP32 Dev Module
+- **代价**：浪费1小时
+- **教训**：搜esp32时认准Espressif Systems出品的那个
+
+### 2. ESP32经典版和C3的BOOT引脚搞混
+- **项目**：面包板接线
+- **翻车**：以为ESP32-C3的BOOT是GPIO0（经典版），实际C3是GPIO8/GPIO9控制启动模式
+- **代价**：接线错误，重新查Datasheet纠正
+- **教训**：不同ESP32型号的Strapping引脚完全不同，不能凭经验混用
+
+### 3. OLED I2C引脚随便分配
+- **项目**：面包板接线
+- **翻车**：GPIO有空就塞，没查Strapping和JTAG约束，SDA/SCL分配到哪算哪
+- **代价**：后续引脚分配推倒重来多次
+- **教训**：ESP32引脚分配必须先查Strapping/JTAG/ADC约束再分配，不能有空就塞
+
+---
+
+## 二、GBC V1.x~V2.x SMT打板阶段（2026年6月）
+
+### 4. MOSFET源极跟随器——GBC V2.0整板报废
+- **项目**：GBC V2.0（SMT打板）
+- **翻车**：AO3400A接成高侧源极跟随器（Drain接电池正极、Source接负载），Vgs被源极电压钳位，负载永远得不到满电压，Rdson非线性变化，内阻计算全错
+- **代价**：整板报废，¥420学费
+- **教训**：N-MOS做开关必须低端接法——负载在上、MOS在下、S极接地、Vgs恒定3.3V
+
+### 5. MOSFET引脚D/S画反——V2.0整板报废的同批次
+- **项目**：GBC V2.0
+- **翻车**：AO3400A SOT-23-3引脚D/S画反，左脚=D（漏极）中间=G（栅极）右脚=S（源极），原理图画反导致整板所有MOS全废
+- **代价**：与#4同批报废，¥420学费
+- **教训**：画原理图前必须对照Datasheet确认MOS引脚定义，不能信AI记忆
+
+### 6. 检流电阻与MOS并联——电流检测完全失效
+- **项目**：GBC早期拓扑
+- **翻车**：R_shunt与MOSFET并联而非串联，电流走MOS短路了检流电阻，INA226测不到电流
+- **代价**：拓扑设计推倒重来
+- **教训**：检流电阻必须串在MOS源极到GND之间，电流必须全部流过采样电阻
+
+### 7. INA226引脚号全错——VBUS和VS搞反
+- **项目**：GBC V2.0文档
+- **翻车**：功能说明文档里INA226引脚排列与TI官方Datasheet SBOS664严重不符，把VBUS(Pin5)和VS(Pin8)搞反了，还凭空多出个NC引脚。VBUS是电压采样输入引脚被当成供电脚，VS才是供电脚被当成电压采样
+- **代价**：又加了一组100kΩ分压电阻+滤波电容做ADC降级方案，后来全部删掉重做
+- **教训**：IC引脚定义必须逐条对照官方Datasheet验证，不能凭AI记忆或网上二手资料
+
+### 8. BOOT键接错引脚——GPIO8 vs GPIO9
+- **项目**：GBC V1.7
+- **翻车**：BOOT键接GPIO8，按下拉3V3。但ESP32-C3的Download模式要求GPIO8=1且GPIO9=0，开发板BOOT键接的是GPIO9不是GPIO8
+- **代价**：按BOOT键进不了下载模式
+- **教训**：ESP32-C3的BOOT键必须接GPIO9（按下接GND拉低），GPIO8必须外部上拉3V3
+
+### 9. GPIO8 NC悬空——Download模式非法组合
+- **项目**：GBC V1.8
+- **翻车**：V1.8把SW2从GPIO8改到GPIO9（纠正了#8），但GPIO8没加上拉直接NC。GPIO8内部高阻态无上下拉，按BOOT(GPIO9=0)时GPIO8=0，组合(0,0)是ESP32-C3官方明确声明的非法组合，行为未定义
+- **代价**：下载不可靠，每次都不合法
+- **教训**：GPIO8必须有10kΩ外部上拉到3V3，确保Download模式(GPIO8=1, GPIO9=0)合法
+
+### 10. 设计继承翻车——同一个MOS坑踩两遍
+- **项目**：NES版拓扑
+- **翻车**：GBC版已验证正确的低端开关接法，写NES版拓扑时凭印象重新写，又写回了源极跟随器。该抄作业的地方没抄，自己"创作"了个错的
+- **代价**：如果没被审查发现，NES版也会整板报废
+- **教训**：已验证项目的接法必须直接继承，禁止凭印象重写。该抄就抄
+
+### 11. 跳过面包板实测——SMT到手才发现问题
+- **项目**：GBC版全流程
+- **翻车**：全程没做面包板测试直接上SMT，模拟电路问题（MOS接法、检流拓扑）在网表验证和AI审查中都没被发现，SMT到手才暴露
+- **代价**：整板报废+重新打板
+- **教训**：不做面包板验证不上板，核心模拟通路必须实测确认
+
+### 12. ESP32-WROOM-32D没有原生USB——板子到手无法烧录
+- **项目**：早期选型
+- **翻车**：选了WROOM-32D模组但没加USB转串口芯片(CH340/CH9102)，Type-C只能供电无法下载固件，板子变砖
+- **代价**：废板
+- **教训**：32D没有原生USB，BOM里必须列出USB转串口芯片+外围；选C3/S3原生USB可省大量器件
+
+### 13. ESP32-32D GPIO12上拉导致Flash变砖
+- **项目**：ESP32-32D选型调研
+- **翻车**：GPIO12是Strapping引脚，决定VDD_SDIO电压。上拉10kΩ→VDD_SDIO=1.8V→外部3.3V Flash无法工作
+- **代价**：设计约束认知
+- **教训**：Strapping引脚偏置方向不能随便加，GPIO12必须下拉GND保持3.3V
+
+---
+
+## 三、GBC V3.x~V4.x整改验证阶段（2026年7月初）
+
+### 14. USB D+多余上拉——COM口存在但打不开
+- **项目**：GBC V4.7/V4.8
+- **翻车**：ESP32-C3内置D+上拉电阻，但板子上又外挂了1.5kΩ R9上拉3V3，双重上拉导致D+永远被强拉到3V3，USB主机无法正常识别设备断开/连接状态。COM6存在但通信层打不开
+- **代价**：拆掉R9才修好
+- **教训**：ESP32-C3/S3原生USB不需要外部D+上拉，只需22Ω串联电阻
+
+### 15. WDT看门狗API版本不兼容——编译失败
+- **项目**：GBC V5.0固件编译
+- **翻车**：V5.0固件用了ESP-IDF v5.1+的新版WDT API（esp_task_wdt_config_t结构体+指针参数），但当前Arduino-ESP32 Core仍为旧版签名（双参数uint32_t+bool），编译2 error
+- **代价**：重新查API写法改代码
+- **教训**：ESP32 Arduino Core版本升级会破坏API兼容性，WDT初始化代码要匹配当前Core版本
+
+### 16. INA226封装引脚映射混乱——VBUS/IN+/IN-互换了
+- **项目**：GBC V4.7/V4.8 SMT到手
+- **翻车**：KiCad封装库的引脚编号与IC物理引脚不一致（Pin8≠物理Pin8），拓扑文档的映射关系又写错了（KiCad Pin8→物理Pin3写成了VBUS但实际Pin3=IN+），导致VBUS线连到IN+、IN+连到VBUS、IN-连到A0。两块板子都一样——INA226电压读数固定0x04EF，电流读数0xFFFF
+- **代价**：两块板子INA226模拟功能全废，只能手动飞线修复
+- **教训**：封装引脚映射必须从EDA库实际焊盘图验证，不能信拓扑文档的映射注释；嘉立创EDA按功能名连的网表是安全的，按pin号连的必须核物理位置
+
+### 17. GPIO2 Strapping当SDA用——启动隐患
+- **项目**：GBC V4.8/V5.1
+- **翻车**：GPIO2是ESP32-C3三个Strapping引脚之一，启动时必须为HIGH才能正常SPI Boot。V4.8把GPIO2当I2C SDA用，4.7kΩ上拉空闲时确实HIGH，但I2C设备上电瞬间可能拉低SDA，踩在启动采样窗口(3ms)内就会干扰Boot
+- **代价**：V4.8实测4.7kΩ上拉够强没出事，但V5.0还是修了——SDA挪到GPIO1，GPIO2加专用R28(10kΩ)上拉3V3
+- **教训**：Strapping引脚不要挂总线，单独上拉锁死电平最安全
+
+### 18. GPIO2 Strapping风险理解错误——VDD_SPI炸Flash说法是错的
+- **项目**：GBC V5.0修复
+- **翻车**：皮蛋最初说"GPIO2 HIGH→VDD_SPI=1.8V→Flash炸"，这是把ESP32经典版（GPIO12/MTDI）的行为错误套用到C3上。C3的VDD_SPI由VDD3P3_CPU内部分压固定3.3V，GPIO2不控制VDD_SPI。真实风险是浮空毛刺在采样窗口被误读
+- **代价**：修复方向虽然对了（SDA换GPIO1+GPIO2上拉），但原理理解是错的
+- **教训**：不同ESP32型号的Strapping机制不同，C3≠经典版≠S3，不能套用
+
+### 19. V5.1裸片移植时V5.0修复被丢掉——GPIO2 Strapping隐患回潮
+- **项目**：GBC V5.1
+- **翻车**：V5.0已修复GPIO2 Strapping问题（SDA挪GPIO1、GPIO2加R28上拉），但V5.1换回裸片时把R28删了、GPIO1改回NC、SDA又放回GPIO2，等于V5.0的修复被丢了，V4.8的老隐患回来
+- **代价**：最终在智谱5.2终审和DeepSeek审查中被发现，重新加R27(10kΩ)上拉+SDA改GPIO1
+- **教训**：版本迁移时必须逐条检查上一版的修复项，不能因为"换封装了"就默认不需要
+
+---
+
+## 四、RPM马达测试仪相关（2026年7月）
+
+### 20. GPIO45 LED接法导致ESP32-S3变砖
+- **项目**：RPM V3.3
+- **翻车**：GPIO45是ESP32-S3的Strapping引脚，决定VDD_SPI电压（0→3.3V, 1→1.8V）。LED接成低电平亮（3V3→D3→R19→GPIO45），启动时LED正向导通把GPIO45拉高，VDD_SPI=1.8V→3.3V Flash读不出→芯片一行固件都跑不到→变砖。LED电流仅0.1mA但Vf=2.3V足以超过VIL(0.825V)
+- **代价**：如果没被智谱5.2审查发现，RPM板子到手必砖
+- **教训**：Strapping引脚上的LED必须接成启动安全方向——GPIO45接高电平有效（LED接GND侧），启动时内部下拉=LOW=LED灭=VDD_SPI=3.3V
+
+### 21. RPM邮票孔模组走标准型——加工费起飞
+- **项目**：RPM V3.3
+- **翻车**：ESP32-S3-WROOM-1-N8R8是邮票孔模组封装，嘉立创SMT只能走标准型，加工费+换料费远高于经济型。标准型2片约800元（含295元换料费）
+- **代价**：打样成本高企
+- **教训**：选模组前先查嘉立创SMT加工类型，邮票孔=标准型=贵；QFN裸片=经济型=便宜
+
+---
+
+## 五、电子宠物项目相关（2026年7月）
+
+### 22. S3-MINI-1邮票孔封装换料费高
+- **项目**：电子宠物V1.0
+- **翻车**：ESP32-S3-MINI-1也是邮票孔模组，跟RPM一样走标准型，换料费贵
+- **代价**：决定等GBC V5.1验证后换S3FH4R2裸片走经济型
+- **教训**：同#21，邮票孔是成本大坑
+
+---
+
+## 六、智谱5.2终审及整改阶段（2026年7月21日）
+
+### 23. 反接过功耗——MOSFET栅极寄生通路
+- **项目**：GBC V5.1智谱终审#1
+- **翻车**：电池反接时VBUS通过R13→Q1栅极→R18→GND形成通路，100mA+电流通过R13(1kΩ)和Q1栅极，R13功耗=0.1W超1206额定0.25V的40%，R18(10kΩ)分压可能让Q1误导通
+- **代价**：新增F1(PTC)+R15/R16换1210封装
+- **教训**：反接保护不能只看主通路，寄生路径也要算
+
+### 24. ADC源阻抗50kΩ超标
+- **项目**：GBC V5.1智谱终审警告2
+- **翻车**：R4/R31各100kΩ分压，源阻抗=50kΩ，超ESP32-C3 ADC推荐值(<10kΩ)，采样电容充不满读数偏低
+- **代价**：R4/R31从100kΩ改10kΩ（C25744零换料费），源阻抗降到5kΩ
+- **教训**：ADC分压电阻不能太大，源阻抗要在推荐值以内
+
+---
+
+## 七、M3二审假警报（2026年7月21日）
+
+### 25. M3算错DW01A过流阈值
+- **项目**：GBC V5.1 M3第6轮审查P1-3
+- **翻车**（M3的翻车）：M3假设负载电流流过R26(1kΩ)计算过流阈值=0.16mA，实际R26是DW01A的CS引脚限流电阻，CS是高阻输入，负载电流根本不走R26。真实过流阈值=0.15V÷8205A导通电阻(75mΩ)≈2A，165mA工作电流远低于此
+- **代价**：浪费审查时间
+- **教训**：AI审查报告的结论也要逐条核验，尤其是计算类结论
+
+### 26. M3张冠李戴晶振ESR规格
+- **项目**：GBC V5.1 M3第6轮审查P1-4
+- **翻车**（M3的翻车）：M3声称"ESP32-C3 datasheet v2.4 Section 2.4.2: ESR≤60Ω"，实际查datasheet原文Section 5.2建议工作条件表根本没有晶振ESR规格。60Ω来源不明，疑似从32.768kHz RTC晶振ESR≤70kΩ张冠李戴。ESP32-C3官方对40MHz晶振不设ESR限制
+- **代价**：浪费时间论证，但C424432(ESR=40Ω)确认不换
+- **教训**：AI引用的"官方规格"必须回原文验证，不能盲信
+
+---
+
+## 翻车分类统计
+
+- Strapping引脚相关：次数=7次, 典型案例=#8/9/13/17/18/19/20
+- MOSFET接法相关：次数=3次, 典型案例=#4/5/6
+- IC引脚映射/封装：次数=3次, 典型案例=#7/16/23
+- 设计继承/流程：次数=2次, 典型案例=#10/19
+- 选型/成本：次数=3次, 典型案例=#12/21/22
+- 固件/编译：次数=2次, 典型案例=#14/15
+- AI审查假警报：次数=2次, 典型案例=#25/26
+- ADC/模拟：次数=1次, 典型案例=#24
+- 面包板验证：次数=1次, 典型案例=#11
+- IDE/工具：次数=1次, 典型案例=#1
+
+---
+
+## 最贵的5条教训
+
+1. **¥420** — MOSFET源极跟随器+引脚D/S反，整板报废（#4+#5）
+2. **废板** — ESP32-32D没原生USB没加串口芯片，变砖（#12）
+3. **两板飞线** — INA226封装映射错误，模拟功能全废（#16）
+4. **差点砖** — RPM GPIO45 LED拉高Strapping变砖（#20）
+5. **两板飞线** — USB D+多余上拉COM口打不开（#14）
+
+---
+
+## 铁律沉淀
+
+从这些翻车中提炼出来的规则，已写入MEMORY.md长期执行：
+
+1. N-MOS做开关，负载在上MOS在下，S极接地，禁止源极跟随器
+2. ESP32引脚分配必须先查Strapping/JTAG/ADC约束再分配
+3. 已验证项目的接法必须直接继承，禁止凭印象重写
+4. 不做面包板验证不上板
+5. IC引脚定义必须逐条对照官方Datasheet验证
+6. Strapping引脚不要挂总线，单独上拉/下拉锁死电平
+7. 不同ESP32型号的Strapping机制不同，不能套用
+8. 封装引脚映射必须从EDA库实际焊盘图验证
+9. 版本迁移时必须逐条检查上一版修复项
+10. 邮票孔模组=标准型=贵，QFN裸片=经济型=便宜
+11. AI审查报告结论也要逐条核验，不能盲信
+12. ADC分压源阻抗要在推荐值以内
+13. 反接保护不能只看主通路，寄生路径也要算
+14. ESP32-C3/S3原生USB不需要外部D+上拉