Initial: knowledge base

2026-08-05 17:25:09 +08:00
parent bfabe83832
commit 5700eb4115
35 changed files with 5140 additions and 11 deletions
@@ -1,16 +1,12 @@
-# ESP32 开发资源库
+# ESP32 全系开发资源库

-ESP32 全系列 9 芯片的固件代码、GPIO 配置模板、外设驱动文档。
+对应 Wiki: https://wiki.suyushi.top/esp32

 ## 目录
-
 | 目录 | 内容 |
 |:--|:--|
-| `firmware/` | 各项目固件：Volt Hound V1.0/V2.0、RPM V3.3、电子宠物 V1.0 |
-| `gpio/` | 全系 GPIO 约束速查（Strapping/ADC/PSRAM） |
-| `drivers/` | 外设驱动参考（SPI/I2C/UART/I2S 等） |
-
-## 相关资源
-
- Wiki: https://wiki.suyushi.top/esp32
- 知识库: https://suyushi.top/agent/agt_ksjt3j38XhHW/docs
+| `gpio/` | 9芯片 GPIO 约束速查 |
+| `drivers/` | 外设驱动参考 |
+| `components/` | 芯片规格 + 约束 + 元件速查 |
+| `pcb/` | PCB 设计规则、SMT 踩坑 |
+| `skill/` | 电路审查 SKILL V6.6 |
@@ -0,0 +1,811 @@
+# Common Devices Reference
+
+> **类别：reference** | **主题：常用器件与模块速查** | **信源：** 多平台汇总
+
+Cross-platform device/module reference for Raspberry Pi and ESP32 GPIO configuration. Used to determine pin requirements, I2C addresses, voltage levels, and platform-specific wiring guidance.
+
+## Table of Contents
+
+- [Category 1: Sensors — Environmental](#category-1-sensors--environmental)
+  - [BME280](#bme280-temperaturehumiditypressure)
+  - [BMP280](#bmp280-temperaturepressure--no-humidity)
+  - [DHT22 / AM2302](#dht22--am2302-temperaturehumidity)
+  - [DS18B20](#ds18b20-temperature-1-wire)
+  - [SHT31](#sht31-temperaturehumidity)
+- [Category 2: Sensors — Motion/Position](#category-2-sensors--motionposition)
+  - [MPU6050](#mpu6050-6-axis-imu--accelerometer--gyroscope)
+  - [ADXL345](#adxl345-3-axis-accelerometer)
+  - [HMC5883L / QMC5883L](#hmc5883l--qmc5883l-magnetometercompass)
+  - [NEO-6M / NEO-7M / NEO-M8N](#neo-6m--neo-7m--neo-m8n-gps-module)
+- [Category 3: Sensors — Analog/Power](#category-3-sensors--analogpower)
+  - [ADS1115](#ads1115-16-bit-adc-4-channel)
+  - [INA219](#ina219-currentvoltagepower-monitor)
+- [Category 4: Displays](#category-4-displays)
+  - [SSD1306](#ssd1306-oled-display-128x64-or-128x32)
+  - [ST7789](#st7789-tft-color-display-typically-240x240-or-240x320)
+  - [HD44780](#hd44780-character-lcd-16x2-or-20x4-via-pcf8574-i2c-backpack)
+  - [e-Paper / e-Ink Display](#e-paper--e-ink-display-waveshare-style)
+- [Category 5: Communication](#category-5-communication)
+  - [nRF24L01](#nrf24l01-24ghz-radio-transceiver)
+  - [HC-05 / HC-06](#hc-05--hc-06-bluetooth-classic-serial)
+  - [SX1276 / RFM95W](#sx1276--rfm95w-lora-radio)
+  - [MCP2515](#mcp2515-can-bus-controller)
+  - [ENC28J60](#enc28j60-spi-ethernet-controller)
+- [Category 6: Motor Control](#category-6-motor-control)
+  - [PCA9685](#pca9685-16-channel-pwmservo-driver)
+  - [L298N](#l298n-dual-h-bridge-motor-driver)
+  - [DRV8825 / A4988](#drv8825--a4988-stepper-motor-driver)
+- [Category 7: Other](#category-7-other)
+  - [MCP23017](#mcp23017-16-channel-gpio-expander)
+  - [WS2812B / NeoPixels](#ws2812b--neopixels-addressable-rgb-leds)
+  - [Rotary Encoder](#rotary-encoder-incremental-with-push-button)
+  - [Relay Modules](#relay-modules-1248-channel)
+  - [MAX31855 / MAX6675](#max31855--max6675-thermocouple-interface)
+- [I2C Address Collision Map](#i2c-address-collision-map)
+
+---
+
+## Category 1: Sensors — Environmental
+
+### BME280 (Temperature/Humidity/Pressure)
+
+- Interface：I2C (default), SPI
+- Required Pins：I2C: SDA, SCL. SPI: MOSI, MISO, SCLK, CS
+- I2C Address：0x76 (SDO→GND), 0x77 (SDO→VDD)
+- Voltage：1.8–3.6V (most breakouts accept 3.3V or 5V input)
+- Pull-ups：Provided on most breakouts
+
+**RPi Notes:**
+- Use I2C1 (GPIO2 SDA, GPIO3 SCL)
+- Enable with `dtparam=i2c_arm=on`
+- SPI mode: SPI0 (GPIO10 MOSI, GPIO9 MISO, GPIO11 SCLK, GPIO8 CE0)
+
+**ESP32 Notes:**
+- Any GPIO pair for I2C via GPIO matrix
+- Default Wire library: GPIO21 SDA, GPIO22 SCL
+- SPI VSPI default: GPIO23 MOSI, GPIO19 MISO, GPIO18 SCLK, GPIO5 CS
+
+**Gotchas:**
+- ADDRESS COLLISION with BMP280 — both use 0x76/0x77
+- Cannot use BME280 + BMP280 on same I2C bus unless one is on alternate address
+- Use I2C multiplexer (TCA9548A) if both needed at same address
+
+---
+
+### BMP280 (Temperature/Pressure — no humidity)
+
+- Interface：I2C (default), SPI
+- Required Pins：I2C: SDA, SCL. SPI: MOSI, MISO, SCLK, CS
+- I2C Address：0x76 (SDO→GND), 0x77 (SDO→VDD)
+- Voltage：1.8–3.6V (most breakouts accept 3.3V or 5V input)
+- Pull-ups：Provided on most breakouts
+
+**RPi Notes:**
+- Use I2C1 (GPIO2 SDA, GPIO3 SCL)
+- Enable with `dtparam=i2c_arm=on`
+- SPI mode: SPI0 (GPIO10 MOSI, GPIO9 MISO, GPIO11 SCLK, GPIO8 CE0)
+
+**ESP32 Notes:**
+- Any GPIO pair for I2C via GPIO matrix
+- Default Wire library: GPIO21 SDA, GPIO22 SCL
+- SPI VSPI default: GPIO23 MOSI, GPIO19 MISO, GPIO18 SCLK, GPIO5 CS
+
+**Gotchas:**
+- ADDRESS COLLISION with BME280
+- Registers are mostly compatible but not identical — don't assume BME280 libraries work on BMP280
+- Cheap clone boards sometimes mislabel BMP280 as BME280
+
+---
+
+### DHT22 / AM2302 (Temperature/Humidity)
+
+- Interface：Single-wire proprietary protocol (NOT 1-Wire/Dallas)
+- Required Pins：DATA (1 GPIO)
+- I2C Address：N/A
+- Voltage：3.3V–5V (data pin is 3.3V logic compatible)
+- Pull-ups：4.7kΩ–10kΩ on data line (some breakouts include it)
+
+**RPi Notes:**
+- Use any available GPIO
+- No overlay needed
+- Timing-sensitive — occasional read failures are normal; retry in software
+- Minimum 2-second sampling interval (do not exceed 0.5 Hz)
+
+**ESP32 Notes:**
+- Use any GPIO
+- Avoid strapping pins (GPIO0, 2, 5, 12, 15)
+- Avoid input-only pins (GPIO34-39) — data pin is bidirectional
+
+**Gotchas:**
+- THIS IS NOT 1-Wire PROTOCOL — do not use w1-gpio overlay
+- Do not confuse with DS18B20
+- Requires specific library (e.g., Adafruit DHT library)
+- DHT11 is the cheaper/less accurate variant — same protocol
+
+---
+
+### DS18B20 (Temperature, 1-Wire)
+
+- Interface：1-Wire (Dallas protocol)
+- Required Pins：DQ (data, 1 GPIO)
+- I2C Address：N/A
+- Voltage：3.0–5.5V (supports parasitic power: data + GND only)
+- Pull-ups：4.7kΩ required on data line
+
+**RPi Notes:**
+- Default: GPIO4 with `dtoverlay=w1-gpio`
+- Custom pin: `dtoverlay=w1-gpio,gpiopin=N`
+- Parasitic power: `dtoverlay=w1-gpio-pullup,gpiopin=N`
+- Multiple sensors can share one data pin (each has unique 64-bit address)
+
+**ESP32 Notes:**
+- Any GPIO via OneWire library
+- Avoid strapping pins
+- Avoid input-only pins (GPIO34-39)
+
+**Gotchas:**
+- Multiple sensors on one bus is a key feature — each has factory-programmed unique ID
+- Parasitic power mode can cause issues with cable runs >3m
+- Counterfeit DS18B20s are common — may have worse accuracy or fail parasitic power
+
+---
+
+### SHT31 (Temperature/Humidity)
+
+- Interface：I2C
+- Required Pins：SDA, SCL. Optional: ALERT (interrupt), RST (active-low reset)
+- I2C Address：0x44 (ADDR→GND), 0x45 (ADDR→VDD)
+- Voltage：2.4–5.5V (most breakouts have regulator)
+- Pull-ups：Provided on most breakouts
+
+**RPi Notes:**
+- Use I2C1 (GPIO2 SDA, GPIO3 SCL)
+- Enable with `dtparam=i2c_arm=on`
+
+**ESP32 Notes:**
+- Any GPIO pair for I2C via GPIO matrix
+
+**Gotchas:**
+- ADDRESS COLLISION — INA219 also uses 0x44/0x45
+- Has built-in heater element for self-diagnostics (enable via register)
+- Higher accuracy than DHT22
+
+---
+
+## Category 2: Sensors — Motion/Position
+
+### MPU6050 (6-Axis IMU — Accelerometer + Gyroscope)
+
+- Interface：I2C
+- Required Pins：SDA, SCL. Optional: INT (interrupt — recommended for DMP)
+- I2C Address：0x68 (AD0→GND), 0x69 (AD0→VDD)
+- Voltage：3.3V (VDD). Most breakouts accept 3.3V–5V input
+- Pull-ups：Provided on most breakouts
+
+**RPi Notes:**
+- Use I2C1 (GPIO2/3)
+- Connect INT to any GPIO if using interrupt-driven reads
+- No specific overlay needed beyond `dtparam=i2c_arm=on`
+
+**ESP32 Notes:**
+- Any GPIO pair for I2C
+- Connect INT to any input-capable GPIO
+- Input-only pins (GPIO34-39) are fine for INT output
+
+**Gotchas:**
+- ADDRESS COLLISION — 0x68 collides with DS3231 RTC
+- If using both, put one on alternate address or use I2C multiplexer
+- Has built-in DMP (Digital Motion Processor) — use INT pin for DMP-ready interrupts
+- MPU9250 is the 9-axis successor (adds magnetometer) — same I2C address scheme
+
+---
+
+### ADXL345 (3-Axis Accelerometer)
+
+- Interface：I2C, SPI
+- Required Pins：I2C: SDA, SCL. SPI: MOSI, MISO, SCLK, CS. Optional: INT1, INT2
+- I2C Address：0x53 (ALT ADDRESS/SDO→GND), 0x1D (ALT ADDRESS/SDO→VDD)
+- Voltage：2.0–3.6V (most breakouts accept 3.3V–5V)
+- Pull-ups：Provided on most breakouts
+
+**RPi Notes:**
+- I2C1 (GPIO2/3) or SPI0 (GPIO7-11)
+- Interrupt pins to any available GPIO
+
+**ESP32 Notes:**
+- Any GPIO pair for I2C, any pins for SPI via GPIO matrix
+- Avoid flash pins (GPIO6-11) for SPI
+
+**Gotchas:**
+- Default I2C address 0x53 is uncommon in collisions
+- SPI mode is activated by pulling CS low — if CS is floating, chip may not respond on I2C
+- Has configurable tap detection, freefall detection, and activity/inactivity interrupts
+
+---
+
+### HMC5883L / QMC5883L (Magnetometer/Compass)
+
+- Interface：I2C
+- Required Pins：SDA, SCL. Optional: DRDY (data ready interrupt)
+- I2C Address：HMC5883L: 0x1E (fixed). QMC5883L: 0x0D (fixed)
+- Voltage：2.16–3.6V (most breakouts accept 3.3V–5V)
+- Pull-ups：Provided on most breakouts
+
+**RPi Notes:**
+- I2C1 (GPIO2/3)
+- No special overlay
+
+**ESP32 Notes:**
+- Any GPIO pair for I2C
+
+**Gotchas:**
+- HMC5883L and QMC5883L have DIFFERENT I2C addresses and DIFFERENT register maps
+- They are NOT interchangeable in software
+- Many cheap "HMC5883L" boards actually contain QMC5883L chips — check chip marking
+- GY-271 boards may have either chip
+- Libraries must match the actual chip
+
+---
+
+### NEO-6M / NEO-7M / NEO-M8N (GPS Module)
+
+- Interface：UART (primary), I2C (some models), SPI (some models)
+- Required Pins：UART: TX, RX. Optional: PPS (pulse-per-second for precision timing)
+- I2C Address：0x42 (when I2C interface is used, some modules only)
+- Voltage：2.7–3.6V (most breakouts accept 3.3V–5V)
+- Pull-ups：N/A for UART
+
+**RPi Notes:**
+- UART0/PL011 on GPIO14 (TX) / GPIO15 (RX)
+- On Pi 3/4/Zero2W, Bluetooth uses PL011 — add `dtoverlay=disable-bt` or `dtoverlay=miniuart-bt`
+- On Pi 5, no BT conflict
+- For PPS: `dtoverlay=pps-gpio,gpiopin=N`
+- RPi TX → GPS RX, RPi RX → GPS TX (crossover)
+
+**ESP32 Notes:**
+- Use UART1 or UART2 on any GPIO pair via GPIO matrix
+- UART0 is typically USB-serial debug — avoid reassigning
+- PPS to any input-capable GPIO
+
+**Gotchas:**
+- Cold start can take 1-5 minutes to get a fix
+- Needs clear sky view for antenna
+- NMEA output at 9600 baud by default
+- PPS signal is critical for NTP servers or precision timing applications
+
+---
+
+## Category 3: Sensors — Analog/Power
+
+### ADS1115 (16-bit ADC, 4-channel)
+
+- Interface：I2C
+- Required Pins：SDA, SCL. Optional: ALERT/RDY (interrupt/data-ready)
+- I2C Address：0x48 (ADDR→GND), 0x49 (ADDR→VDD), 0x4A (ADDR→SDA), 0x4B (ADDR→SCL)
+- Voltage：2.0–5.5V
+- Pull-ups：Provided on most breakouts
+
+**RPi Notes:**
+- I2C1 (GPIO2/3)
+- Essential for RPi projects needing analog inputs — RPi has no built-in ADC
+- Enable with `dtparam=i2c_arm=on`
+
+**ESP32 Notes:**
+- Any GPIO pair for I2C
+- Less commonly needed since ESP32 has built-in 12-bit ADC
+- Useful for higher resolution (16-bit) or to avoid ADC2/WiFi conflicts
+
+**Gotchas:**
+- 0x48 address collides with TMP102 temperature sensor
+- Can run 4 devices on one I2C bus (4 addresses) for up to 16 analog channels
+- Programmable gain amplifier (PGA) allows measuring small voltages
+- Max sample rate is 860 SPS
+- ADS1015 is the cheaper 12-bit variant with same pinout and addresses
+
+---
+
+### INA219 (Current/Voltage/Power Monitor)
+
+- Interface：I2C
+- Required Pins：SDA, SCL. Also: VIN+, VIN- (power sense pins, not GPIO)
+- I2C Address：0x40 (A0=GND,A1=GND), 0x41, 0x44, 0x45 (via A0/A1 pins)
+- Voltage：3.0–5.5V (bus voltage measurement up to 26V)
+- Pull-ups：Provided on most breakouts
+
+**RPi Notes:**
+- I2C1 (GPIO2/3)
+
+**ESP32 Notes:**
+- Any GPIO pair for I2C
+
+**Gotchas:**
+- ADDRESS COLLISION — 0x40 collides with PCA9685 servo driver
+- 0x44/0x45 collide with SHT31
+- If using INA219 + PCA9685, must configure different addresses via A0/A1 pins
+- Shunt resistor value (typically 0.1Ω) determines current measurement range — must match library calibration
+
+---
+
+## Category 4: Displays
+
+### SSD1306 (OLED Display, 128×64 or 128×32)
+
+- Interface：I2C (most common), SPI
+- Required Pins：I2C: SDA, SCL. SPI: MOSI, SCLK, CS, DC, RST (optional)
+- I2C Address：0x3C (common), 0x3D (alternate, set by resistor)
+- Voltage：3.3V–5V (most modules have regulator)
+- Pull-ups：Provided on most breakouts
+
+**RPi Notes:**
+- I2C1 (GPIO2/3) for I2C mode
+- SPI0 for SPI mode
+- I2C mode fine for single display, SPI faster for animations
+
+**ESP32 Notes:**
+- Any GPIO pair for I2C, any pins for SPI
+- SPI recommended for high refresh rate
+
+**Gotchas:**
+- 0x3C address collides with SH1106 OLED (similar but different driver)
+- 128×32 variant usually has fixed 0x3C address
+- Some boards labeled "SSD1306" actually use SH1106 — different memory layout (132×64 with offset)
+
+---
+
+### ST7789 (TFT Color Display, typically 240×240 or 240×320)
+
+- Interface：SPI only
+- Required Pins：MOSI, SCLK, CS, DC, RST, BL (backlight)
+- I2C Address：N/A
+- Voltage：3.3V logic. Most modules accept 3.3V–5V power
+- Pull-ups：N/A
+
+**RPi Notes:**
+- SPI0 (GPIO10 MOSI, GPIO11 SCLK, GPIO8 CE0)
+- DC on any GPIO (commonly GPIO25)
+- RST on any GPIO (commonly GPIO27)
+- BL on PWM-capable GPIO (GPIO12 or GPIO18) for brightness control, or tie to 3.3V
+
+**ESP32 Notes:**
+- VSPI or any pins via GPIO matrix
+- SPI clock can run up to 80MHz — good for smooth display updates
+
+**Gotchas:**
+- SPI-only, no I2C option
+- ST7735 is the smaller cousin (128×160) — different driver, similar interface
+- Some displays omit CS pin (tied to GND) — prevents sharing SPI bus
+- BL pin may be active-high or active-low depending on module
+
+---
+
+### HD44780 (Character LCD, 16×2 or 20×4, via PCF8574 I2C Backpack)
+
+- Interface：Parallel GPIO (6+ pins), I2C via PCF8574 backpack (recommended)
+- Required Pins：I2C: SDA, SCL. Direct: RS, EN, D4-D7 (4-bit = 6 GPIOs)
+- I2C Address：0x27 (most common), 0x3F (some variants). PCF8574A: 0x38–0x3F
+- Voltage：5V for LCD. I2C backpack tolerates 3.3V I2C signals
+- Pull-ups：Provided on PCF8574 backpack
+
+**RPi Notes:**
+- Use I2C backpack to save GPIOs
+- I2C1 (GPIO2/3)
+- RPi's 3.3V I2C usually works with 5V PCF8574 but is out of spec — consider level shifter
+
+**ESP32 Notes:**
+- I2C backpack strongly recommended
+- ESP32 is 3.3V only — needs level shifter for direct 5V LCD parallel interface
+
+**Gotchas:**
+- PCF8574 address 0x27 collides with MCP23017 (0x20-0x27)
+- Contrast potentiometer must be adjusted or display appears blank — #1 troubleshooting issue
+- Backlight can be controlled via PCF8574 register bit
+
+---
+
+### e-Paper / e-Ink Display (Waveshare-style)
+
+- Interface：SPI
+- Required Pins：MOSI, SCLK, CS, DC, RST, BUSY (output from display)
+- I2C Address：N/A
+- Voltage：3.3V logic and power
+- Pull-ups：N/A
+
+**RPi Notes:**
+- SPI0 (GPIO10 MOSI, GPIO11 SCLK, GPIO8 CE0)
+- DC, RST, BUSY on any available GPIOs
+- Waveshare HAT uses: RST=GPIO17, DC=GPIO25, CS=GPIO8, BUSY=GPIO24
+
+**ESP32 Notes:**
+- Any SPI pins via GPIO matrix
+- BUSY must be on input-capable GPIO
+- Input-only pins (GPIO34-39) are fine for BUSY
+
+**Gotchas:**
+- Refresh time is slow (1-15 seconds for full refresh)
+- Partial refresh is faster but causes ghosting over time
+- Do NOT refresh continuously — damages the panel
+- Different Waveshare models (1.54", 2.13", 2.7", 4.2", 7.5") use different drivers — NOT interchangeable in software
+
+---
+
+## Category 5: Communication
+
+### nRF24L01 (2.4GHz Radio Transceiver)
+
+- Interface：SPI, GPIO
+- Required Pins：MOSI, MISO, SCLK, CSN (chip select), CE (chip enable). Optional: IRQ
+- I2C Address：N/A
+- Voltage：3.3V ONLY for VCC. SPI data pins are 5V tolerant
+- Pull-ups：N/A
+
+**RPi Notes:**
+- SPI0 (GPIO10 MOSI, GPIO9 MISO, GPIO11 SCLK, GPIO8 CE0 for CSN)
+- CE on any GPIO (commonly GPIO17 or GPIO22)
+- IRQ on any GPIO
+- Add 10µF + 100nF capacitor across VCC/GND close to module — extremely sensitive to power supply noise
+
+**ESP32 Notes:**
+- VSPI or any SPI pins via GPIO matrix
+- CE on any output GPIO
+- Avoid strapping pins for CE
+- Power supply decoupling equally important
+
+**Gotchas:**
+- PA+LNA variant draws up to 115mA — cannot be powered from typical breadboard 3.3V regulator
+- Use dedicated 3.3V supply
+- Range: basic module ~100m line of sight, PA+LNA ~1km+
+- CSN is NOT the same as CE — CSN is SPI chip select, CE is nRF24-specific enable pin
+
+---
+
+### HC-05 / HC-06 (Bluetooth Classic Serial)
+
+- Interface：UART
+- Required Pins：TX, RX. Optional: STATE/STATUS, EN/KEY (AT mode on HC-05)
+- I2C Address：N/A
+- Voltage：3.3V logic (module VCC 3.6–6V). Use voltage divider for 5V TX
+- Pull-ups：N/A
+
+**RPi Notes:**
+- GPIO14 (TX) / GPIO15 (RX)
+- On Pi 3/4/Zero2W, use `dtoverlay=disable-bt` or `dtoverlay=miniuart-bt`
+- Pi 5 has no conflict
+- RPi TX → HC-05/06 RX, RPi RX → HC-05/06 TX (crossover)
+
+**ESP32 Notes:**
+- UART1 or UART2 on any GPIO pair
+- Less commonly used since ESP32 has built-in Bluetooth
+- Useful for bridging to Bluetooth Classic devices
+
+**Gotchas:**
+- HC-05 is master/slave capable, HC-06 is slave only
+- Default baud rate: 9600 (HC-06), 38400 (HC-05 AT mode)
+- HC-05 enters AT mode by holding EN/KEY HIGH during power-up
+- Bluetooth Classic (not BLE) — not compatible with iOS without MFi
+
+---
+
+### SX1276 / RFM95W (LoRa Radio)
+
+- Interface：SPI, GPIO
+- Required Pins：MOSI, MISO, SCLK, NSS/CS, RST, DIO0 (interrupt). Optional: DIO1-DIO5
+- I2C Address：N/A
+- Voltage：3.3V
+- Pull-ups：N/A
+
+**RPi Notes:**
+- SPI0 (GPIO10 MOSI, GPIO9 MISO, GPIO11 SCLK, GPIO8 CE0)
+- RST on any GPIO
+- DIO0 on any GPIO (commonly GPIO25)
+- NSS can use GPIO8 (CE0) or any GPIO as software CS
+
+**ESP32 Notes:**
+- Any SPI pins via GPIO matrix
+- DIO0 to any input-capable GPIO
+- Input-only pins (GPIO34-39) are fine for DIO0
+
+**Gotchas:**
+- LoRa operates in ISM bands (433/868/915 MHz) — use correct frequency for your country
+- Antenna MUST be connected before transmitting or module can be damaged
+- RFM95W is the HopeRF clone of SX1276 — pin-compatible and functionally identical
+
+---
+
+### MCP2515 (CAN Bus Controller)
+
+- Interface：SPI, GPIO
+- Required Pins：MOSI, MISO, SCLK, CS, INT. Needs external CAN transceiver (TJA1050/MCP2551)
+- I2C Address：N/A
+- Voltage：2.7–5.5V. Most modules include transceiver and run at 5V
+- Pull-ups：N/A
+
+**RPi Notes:**
+- SPI0 with `dtoverlay=mcp2515-can0,oscillator=8000000,interrupt=25`
+- Adjust oscillator to match board crystal (8MHz or 16MHz)
+- INT on GPIO (commonly GPIO25)
+- Adds can0 network interface
+- Second bus: `dtoverlay=mcp2515-can1,oscillator=8000000,interrupt=24` on SPI0 CE1
+
+**ESP32 Notes:**
+- Any SPI pins
+- INT to any input-capable GPIO
+- ESP32 has built-in CAN (TWAI) — MCP2515 useful for second CAN bus
+- Still needs external transceiver
+
+**Gotchas:**
+- Oscillator frequency in overlay MUST match physical crystal — check markings (8MHz or 16MHz common)
+- Wrong oscillator value = CAN bus won't work
+- CAN bus requires 120Ω termination resistors at both ends
+- Some modules include termination resistor — check before adding another
+
+---
+
+### ENC28J60 (SPI Ethernet Controller)
+
+- Interface：SPI, GPIO
+- Required Pins：MOSI, MISO, SCLK, CS, INT. Optional: RST (can tie to VCC)
+- I2C Address：N/A
+- Voltage：3.3V
+- Pull-ups：N/A
+
+**RPi Notes:**
+- SPI0 with `dtoverlay=enc28j60,int_pin=25,speed=12000000`
+- INT on GPIO (commonly GPIO25)
+- Adds eth1 network interface
+- Max speed is 10 Mbps (10Base-T only)
+
+**ESP32 Notes:**
+- Any SPI pins via GPIO matrix
+- Less commonly used since many ESP32 boards have built-in WiFi
+- Useful for wired-only industrial applications
+
+**Gotchas:**
+- 10 Mbps only — no 100 Mbps or gigabit
+- Uses significant CPU time due to SPI polling
+- Not suitable for high-bandwidth applications
+- MAC address usually set in software
+- Consider W5500 (100 Mbps, hardware TCP/IP stack) as modern alternative
+
+---
+
+## Category 6: Motor Control
+
+### PCA9685 (16-Channel PWM/Servo Driver)
+
+- Interface：I2C
+- Required Pins：SDA, SCL. Optional: OE (output enable, active low)
+- I2C Address：0x40 (default). Configurable 0x40–0x7F via A0–A5 pins (62 addresses)
+- Voltage：VCC 3.3V–5V for logic. Separate V+ for servos (up to 6V)
+- Pull-ups：Provided on most breakouts
+
+**RPi Notes:**
+- I2C1 (GPIO2/3)
+- No special overlay needed
+- 12-bit resolution, 24Hz–1526Hz adjustable frequency
+- OE pin to any GPIO if needed
+
+**ESP32 Notes:**
+- Any GPIO pair for I2C
+- Useful for adding PWM channels or servo control
+
+**Gotchas:**
+- ADDRESS COLLISION — default 0x40 collides with INA219
+- Must change address via A0-A5 pins if both on same bus
+- PCA9685 is a PWM driver, NOT a motor driver — generates PWM signals but cannot drive motors directly
+- Connect outputs to motor drivers (L298N, DRV8825) or directly to servos
+- All 16 channels share same PWM frequency
+
+---
+
+### L298N (Dual H-Bridge Motor Driver)
+
+- Interface：GPIO (digital + PWM)
+- Required Pins：Per motor: IN1, IN2 (direction), ENA (PWM speed). 2 motors: 6 GPIOs total
+- I2C Address：N/A
+- Voltage：Motor: 5–35V. Logic: 5V (on-board regulator if motor >7V). 3.3V tolerant
+- Pull-ups：N/A
+
+**RPi Notes:**
+- IN1-IN4 on any GPIO
+- ENA/ENB on PWM-capable GPIO (GPIO12, GPIO13, GPIO18, GPIO19)
+- Use `dtoverlay=pwm` or `dtoverlay=pwm-2chan` for smooth control
+- Software PWM may cause audible motor whine
+
+**ESP32 Notes:**
+- IN1-IN4 on any output GPIO
+- ENA/ENB on any GPIO (all support LEDC PWM)
+- Avoid strapping pins
+
+**Gotchas:**
+- L298N has ~2V voltage drop across H-bridge — motor sees ~2V less than supply
+- Not efficient for battery-powered projects
+- 5V regulator on board can supply ~500mA for logic
+- TB6612FNG is a more efficient alternative (MOSFET-based, ~0.5V drop)
+
+---
+
+### DRV8825 / A4988 (Stepper Motor Driver)
+
+- Interface：GPIO (digital)
+- Required Pins：STEP, DIR, ENABLE (active low, optional). MS1-MS3 (microstepping)
+- I2C Address：N/A
+- Voltage：DRV8825: 8.2–45V motor, 3.3V logic. A4988: 8–35V motor, 3.3V/5V logic
+- Pull-ups：ENABLE has internal pull-down. STEP/DIR do not need pull-ups
+
+**RPi Notes:**
+- STEP on any GPIO (consider hardware PWM on GPIO12/13/18/19 for constant speed)
+- DIR on any GPIO
+- ENABLE on any GPIO
+
+**ESP32 Notes:**
+- STEP on any output GPIO
+- Use LEDC PWM or RMT peripheral for consistent step timing
+- Avoid strapping pins
+
+**Gotchas:**
+- DRV8825: up to 1/32 microstepping. A4988: up to 1/16
+- Current limit must be set via potentiometer BEFORE connecting motor
+- NEVER disconnect motor while driver is powered — back-EMF can destroy driver
+- A4988 and DRV8825 have same pinout but different microstepping truth tables
+
+---
+
+## Category 7: Other
+
+### MCP23017 (16-Channel GPIO Expander)
+
+- Interface：I2C
+- Required Pins：SDA, SCL. Optional: INTA, INTB (interrupts), RST (active-low reset)
+- I2C Address：0x20–0x27 (A0, A1, A2 = 8 configurable addresses)
+- Voltage：1.8–5.5V
+- Pull-ups：Provided on most breakouts. GPIO pins have optional internal pull-ups
+
+**RPi Notes:**
+- I2C1 (GPIO2/3)
+- Connect INTA/INTB to RPi GPIOs for interrupt-driven input
+- Up to 8 expanders = 128 additional GPIOs
+
+**ESP32 Notes:**
+- Any GPIO pair for I2C
+- Less commonly needed since ESP32 has many GPIOs
+- Useful for projects needing many inputs with interrupt support
+
+**Gotchas:**
+- Address range 0x20–0x27 collides with PCF8574 (HD44780 I2C backpacks)
+- If using both, ensure non-overlapping addresses
+- Each output pin can source/sink 25mA (total per port: 125mA)
+- PCF8574 is the 8-channel version with same address range
+
+---
+
+### WS2812B / NeoPixels (Addressable RGB LEDs)
+
+- Interface：Single GPIO (proprietary protocol — NOT Dallas 1-Wire)
+- Required Pins：DIN (1 GPIO). Chain DOUT→DIN between LEDs
+- I2C Address：N/A
+- Voltage：5V power. Data expects 5V logic (min 3.5V for logic high)
+- Pull-ups：N/A. Add 300–500Ω resistor on data line. Add 1000µF capacitor at power
+
+**RPi Notes:**
+- USE GPIO18 (PWM0/PCM) or GPIO10 (SPI0 MOSI) or GPIO21 (PCM)
+- rpi_ws281x library requires specific GPIOs (DMA-based timing)
+- GPIO18 most common. GPIO10 requires `dtparam=spi=on`
+- Needs sudo or specific permissions for DMA access
+- RPi outputs 3.3V — use level shifter (3.3V→5V) for reliable operation
+
+**ESP32 Notes:**
+- Any output GPIO via RMT peripheral
+- ESP32 outputs 3.3V — same level shifting recommendation
+- RMT peripheral handles timing precisely without CPU intervention
+
+**Gotchas:**
+- LEVEL SHIFTER WARNING — 3.3V logic is below WS2812B spec (needs >3.5V)
+- Works unreliably at short distances, fails with longer data lines
+- Use 74AHCT125, 74HCT245, or SN74LV1T34 level shifter
+- Each LED draws up to 60mA at full white — 60 LEDs = 3.6A
+- Inject power every 30-50 LEDs for long strips
+- SK6812 is compatible alternative with RGBW support
+
+---
+
+### Rotary Encoder (Incremental, with push button)
+
+- Interface：GPIO (digital inputs)
+- Required Pins：CLK/A, DT/B (encoder phases), SW (push button, active low)
+- I2C Address：N/A
+- Voltage：3.3V–5V (module dependent)
+- Pull-ups：Most modules have 10kΩ on board. Bare encoder needs pull-ups
+
+**RPi Notes:**
+- Use any 3 GPIOs with interrupt support (all RPi GPIOs support edge-triggered interrupts)
+- Enable internal pull-ups via gpiod or RPi.GPIO if bare encoder
+
+**ESP32 Notes:**
+- Any 3 input-capable GPIOs
+- Hardware interrupt on all GPIOs
+- Input-only pins (GPIO34-39) work fine
+- Avoid strapping pins
+
+**Gotchas:**
+- Mechanical encoders generate switch bounce — need debouncing
+- Hardware: 100nF capacitor across each pin to GND
+- Software: 1-5ms delay
+- Optical encoders don't bounce
+- Reading must use interrupt or high-frequency polling — slow polling misses steps
+- KY-040 is the most common breakout module
+
+---
+
+### Relay Modules (1/2/4/8 channel)
+
+- Interface：GPIO (digital output)
+- Required Pins：IN1 (one GPIO per channel). Multi-channel: IN1, IN2, IN3, IN4, etc.
+- I2C Address：N/A
+- Voltage：Module VCC typically 5V. Most blue relay modules are ACTIVE LOW
+- Pull-ups：N/A
+
+**RPi Notes:**
+- Any GPIO
+- Check if module is active-low or active-high
+- Most cheap modules are active-low — relay activates when GPIO goes LOW
+- At boot, GPIOs are floating — may cause relay chatter
+- Use pull-up resistor to keep relay OFF during boot
+
+**ESP32 Notes:**
+- Any output GPIO
+- Same active-low/high consideration
+- Avoid strapping pins (GPIO0, 2, 5, 12, 15) — boot states could trigger relays
+- Avoid GPIO34-39 (input only)
+
+**Gotchas:**
+- Most modules have opto-isolated inputs
+- Remove VCC-JD jumper for true isolation
+- Relay coils cause voltage spikes — modules should have flyback diodes (most do)
+- Never switch mains voltage without proper safety knowledge
+- For DC loads, consider MOSFETs instead
+
+---
+
+### MAX31855 / MAX6675 (Thermocouple Interface)
+
+- Interface：SPI (read-only — no MOSI needed)
+- Required Pins：MISO/SO, SCLK/SCK, CS. No MOSI needed
+- I2C Address：N/A
+- Voltage：MAX31855: 3.0–3.6V. MAX6675: 5V. Most breakouts accept both
+- Pull-ups：N/A
+
+**RPi Notes:**
+- SPI0 (GPIO9 MISO, GPIO11 SCLK, GPIO8 CE0)
+- MOSI (GPIO10) unused but SPI0 still claims it
+
+**ESP32 Notes:**
+- Any SPI pins via GPIO matrix
+- MOSI unused — can reassign to other functions
+
+**Gotchas:**
+- MAX31855 supports K, J, N, S, R, T type thermocouples — different variants for each
+- MAX6675 supports K-type only and is older/less accurate
+- Thermocouple wires are polarity-sensitive — red is always negative
+- Cold-junction compensation is built in
+- Keep chip close to terminal block to minimize cold-junction error
+- MAX31855 has open/short fault detection
+
+---
+
+## I2C Address Collision Map
+
+- 0x76：Devices=BME280, BMP280, MS5611, Resolution=Use alternate 0x77 for one device, or I2C multiplexer
+- 0x77：Devices=BME280 (alt), BMP280 (alt), Resolution=Only one per bus at this address
+- 0x40：Devices=INA219, PCA9685, HDC1080, Resolution=Change address via A0/A1 pins
+- 0x44：Devices=SHT31, INA219 (A1=VDD,A0=GND), Resolution=Change INA219 address via A0/A1
+- 0x45：Devices=SHT31 (alt), INA219 (alt), Resolution=Change INA219 address via A0/A1
+- 0x3C：Devices=SSD1306, SH1106, Resolution=Different drivers, unlikely to use both
+- 0x3D：Devices=SSD1306 (alt), Resolution=Rare collision
+- 0x68：Devices=MPU6050, DS3231 RTC, Resolution=Set MPU6050 to 0x69 (AD0→VDD)
+- 0x69：Devices=MPU6050 (alt), Resolution=Rare collision
+- 0x48–0x4B：Devices=ADS1115 (configurable), TMP102, Resolution=Configure ADS1115 to non-conflicting address
+- 0x20–0x27：Devices=MCP23017 (A0-A2), PCF8574, HD44780 backpack, Resolution=Configure A0-A2 to avoid overlap
+- 0x27：Devices=PCF8574 (HD44780 backpack), MCP23017 (A0-A2 all high), Resolution=Change MCP23017 address
+- 0x42：Devices=NEO-GPS (I2C mode), Resolution=Uncommon, rarely conflicts
+
+When address conflicts cannot be resolved via address pins, use a TCA9548A I2C multiplexer. Each TCA9548A has 8 channels and its own configurable address (0x70-0x77), supporting up to 64 separate I2C buses from a single host bus.
@@ -0,0 +1,359 @@
+# Electrical Constraints Reference
+
+> **类别：reference** | **主题：电气约束通用规范** | **信源：** 多平台汇总
+
+## Table of Contents
+
+- [Platform Comparison Summary](#platform-comparison-summary)
+- [Raspberry Pi Electrical Details](#raspberry-pi-electrical-details)
+  - [Voltage Levels](#voltage-levels)
+  - [Current Limits](#current-limits)
+  - [Power Rails](#power-rails)
+  - [Internal Pull Resistors](#internal-pull-resistors)
+  - [Safe Driving Patterns](#safe-driving-patterns)
+- [ESP32 Electrical Details](#esp32-electrical-details)
+  - [Voltage Levels](#voltage-levels)
+  - [Current Limits](#current-limits)
+  - [Power Consumption](#power-consumption)
+  - [Internal Pull Resistors](#internal-pull-resistors)
+  - [Drive Strength Configuration](#drive-strength-configuration)
+- [Pull-up and Pull-down Resistors](#pull-up-and-pull-down-resistors)
+  - [When Required](#when-required)
+  - [Calculation Formula](#calculation-formula)
+  - [Strength Guidelines](#strength-guidelines)
+  - [Consequences of Wrong Value](#consequences-of-wrong-value)
+- [Level Shifting](#level-shifting)
+  - [When Required](#when-required)
+  - [Method 1: Voltage Divider (5V → 3.3V, Unidirectional)](#method-1-voltage-divider-5v--33v-unidirectional)
+  - [Method 2: N-Channel MOSFET (Bidirectional)](#method-2-n-channel-mosfet-bidirectional)
+  - [Method 3: Dedicated Level Shifter ICs](#method-3-dedicated-level-shifter-ics)
+  - [Method 4: Direct Connection (3.3V → 5V Input)](#method-4-direct-connection-33v--5v-input)
+- [Common Mistakes and Warnings](#common-mistakes-and-warnings)
+  - [NEVER Do This](#never-do-this)
+  - [ALWAYS Do This](#always-do-this)
+- [Quick Reference Card](#quick-reference-card)
+  - [Formulas](#formulas)
+  - [Quick Values](#quick-values)
+  - [Current Limits Summary](#current-limits-summary)
+  - [Voltage Summary](#voltage-summary)
+  - [Common Pin Restrictions](#common-pin-restrictions)
+
+---
+
+## Platform Comparison Summary
+
+- Logic voltage：Raspberry Pi=3.3V, ESP32=3.3V
+- Max per-pin current：Raspberry Pi=16mA source/sink, ESP32=40mA max (20mA recommended)
+- Aggregate GPIO current：Raspberry Pi=**50mA total**, ESP32=~1200mA total (chip limit)
+- 5V tolerant：Raspberry Pi=**NO**, ESP32=**NO**
+- Internal pull-up：Raspberry Pi=~50kΩ, ESP32=~45kΩ typical
+- Internal pull-down：Raspberry Pi=~50kΩ, ESP32=~45kΩ typical
+- Drive strength：Raspberry Pi=Fixed, ESP32=Configurable (5-40mA)
+- Input threshold (VIH)：Raspberry Pi=~1.8V, ESP32=~2.0V
+- Input threshold (VIL)：Raspberry Pi=~0.8V, ESP32=~0.8V
+
+---
+
+## Raspberry Pi Electrical Details
+
+### Voltage Levels
+
+- **All GPIO pins operate at 3.3V ONLY**
+- **5V on any GPIO pin WILL PERMANENTLY DAMAGE the SoC**
+- No built-in overvoltage protection
+- No built-in ESD protection (handle with care)
+
+### Current Limits
+
+- Per-pin source：16mA, Consequence of Exceeding=Voltage droop, pin damage
+- Per-pin sink：16mA, Consequence of Exceeding=Voltage rise, pin damage
+- **Total GPIO**：**50mA**, Consequence of Exceeding=Instability, crashes, permanent damage
+
+**Critical:** The 50mA limit is across ALL GPIO pins combined, not per-bank.
+
+### Power Rails
+
+- 3.3V：Source=Onboard regulator, Available Current=~50mA for peripherals, Notes=Shared with Pi's 3.3V needs
+- 5V：Source=USB/PSU direct, Available Current=1-2A minus Pi consumption, Notes=No regulation, direct pass-through
+- GND：Source=Common ground, Available Current=N/A, Notes=8 ground pins on header
+
+### Internal Pull Resistors
+
+- GPIO0-8：Default State=Pull-UP, Resistance=~50kΩ
+- GPIO9-27：Default State=Pull-DOWN, Resistance=~50kΩ
+
+**Note:** Internal pulls are too weak for I2C (need 4.7kΩ external).
+
+### Safe Driving Patterns
+
+- Single LED：Method=330Ω-1kΩ series resistor, Notes=3-10mA safe
+- Multiple LEDs：Method=Transistor driver, Notes=If total >50mA
+- Relay：Method=Transistor/MOSFET + flyback diode, Notes=Never direct from GPIO
+- Motor：Method=Motor driver IC (L298N, DRV8833), Notes=Never direct from GPIO
+- Buzzer (passive)：Method=Transistor driver, Notes=Inductive load
+- Buzzer (active)：Method=Direct if <16mA, Notes=Check current draw
+
+---
+
+## ESP32 Electrical Details
+
+### Voltage Levels
+
+- **All GPIO pins operate at 3.3V ONLY**
+- **5V on any GPIO pin WILL DAMAGE the chip**
+- No built-in overvoltage protection
+- Some ESD protection but don't rely on it
+
+### Current Limits
+
+- Per-pin max：40mA, Notes=Absolute maximum
+- Per-pin recommended：20mA, Notes=For reliability/longevity
+- Total chip：~1200mA, Notes=Includes WiFi, BT, CPU
+
+### Power Consumption
+
+- Active + WiFi TX：Current Draw=80-240mA, Notes=Peaks during transmission
+- Active + WiFi idle：Current Draw=20-68mA, Notes=Connected but not transmitting
+- Active, no radio：Current Draw=20-68mA, Notes=CPU running
+- Modem sleep：Current Draw=3-20mA, Notes=WiFi paused, CPU active
+- Light sleep：Current Draw=0.8mA, Notes=CPU paused, RTC running
+- Deep sleep：Current Draw=10-150µA, Notes=Only RTC + ULP available
+
+### Internal Pull Resistors
+
+- Standard GPIO：Pull-up=Yes, Pull-down=Yes, Resistance=~45kΩ
+- GPIO34-39：Pull-up=**NO**, Pull-down=**NO**, Resistance=N/A (input-only)
+
+**Note:** Internal pulls are too weak for I2C (need 4.7kΩ external).
+
+### Drive Strength Configuration
+
+- 5mA：Current=Weakest, Use Case=Low power, slow signals
+- 10mA：Current=Low, Use Case=General purpose
+- 20mA：Current=Default, Use Case=Most applications
+- 40mA：Current=Maximum, Use Case=Fast edges, heavy loads
+
+Higher drive strength = faster edges but more EMI/noise.
+
+---
+
+## Pull-up and Pull-down Resistors
+
+### When Required
+
+- I2C bus (SDA)：Pull Type=Pull-UP, Typical Value=**4.7kΩ**
+- I2C bus (SCL)：Pull Type=Pull-UP, Typical Value=**4.7kΩ**
+- 1-Wire bus (DQ)：Pull Type=Pull-UP, Typical Value=**4.7kΩ**
+- Button to GND：Pull Type=Pull-UP, Typical Value=10kΩ
+- Button to VCC：Pull Type=Pull-DOWN, Typical Value=10kΩ
+- SPI CS line：Pull Type=Pull-UP, Typical Value=10kΩ
+- Open-drain output：Pull Type=Pull-UP, Typical Value=1-10kΩ
+- UART RX (optional)：Pull Type=Pull-UP, Typical Value=10kΩ (noise immunity)
+- Reset line：Pull Type=Pull-UP, Typical Value=10kΩ
+
+### Calculation Formula
+
+```
+R = (VCC - VOL) / IOL
+
+Where:
+  VCC = Supply voltage (3.3V)
+  VOL = Output low voltage (~0.4V)
+  IOL = Required sink current (3mA for I2C)
+
+Example (I2C):
+  R = (3.3V - 0.4V) / 3mA = 967Ω minimum
+  Typical choice: 4.7kΩ (provides margin)
+```
+
+### Strength Guidelines
+
+- 1kΩ：Use Case=Long wires, high capacitance, fast I2C, Notes=Strong pull, higher current
+- 4.7kΩ：Use Case=Standard I2C, 1-Wire, general purpose, Notes=Most common choice
+- 10kΩ：Use Case=Buttons, CS lines, low-power, Notes=Standard digital pull
+- 47-100kΩ：Use Case=Wake-up inputs, ultra-low power, Notes=Very weak, slow rise time
+
+### Consequences of Wrong Value
+
+**Too high (weak pull):**
+- Slow signal rise times
+- Noise susceptibility
+- Communication errors at higher speeds
+- May not reach valid HIGH level
+
+**Too low (strong pull):**
+- Excessive current consumption
+- Device may not be able to pull line LOW
+- Wasted power in battery applications
+
+---
+
+## Level Shifting
+
+### When Required
+
+- 5V logic output → 3.3V GPIO input
+- 3.3V GPIO output → 5V input (if device doesn't recognize 3.3V as HIGH)
+- Bidirectional communication between 3.3V and 5V systems
+
+### Method 1: Voltage Divider (5V → 3.3V, Unidirectional)
+
+**Use for:** Slow signals (<100kHz), input direction only
+
+```
+5V Signal ──[1kΩ]──┬──> 3.3V GPIO Input
+                   │
+                 [2kΩ]
+                   │
+                  GND
+
+Output: 5V × (2kΩ / 3kΩ) = 3.33V
+```
+
+- Simple, cheap：Cons=Input direction only
+- 2 resistors：Cons=Slow (RC time constant)
+- No active components：Cons=Loads the signal
+
+### Method 2: N-Channel MOSFET (Bidirectional)
+
+**Use for:** I2C, 1-Wire, open-drain signals up to 400kHz
+
+```
+3.3V Side                              5V Side
+    │                                      │
+  [4.7kΩ]                              [4.7kΩ]
+    │                                      │
+    ├────────┬──────────────────┬──────────┤
+    │        │                  │          │
+   SDA    Source              Drain      SDA
+  (3.3V)     └───── BSS138 ─────┘       (5V)
+                      │
+                    Gate
+                      │
+                    3.3V
+```
+
+**Operation:**
+- Gate tied to LOW side voltage (3.3V)
+- When LOW side pulls down, MOSFET conducts, pulling HIGH side down
+- When HIGH side pulls down, body diode conducts, pulling LOW side down
+- Pull-ups restore HIGH state on both sides
+
+- MOSFET：Specification=BSS138, 2N7000 (through-hole)
+- Pull-ups：Specification=4.7kΩ on each side
+- Voltage：Specification=3.3V on gate, low side; 5V on high side
+
+### Method 3: Dedicated Level Shifter ICs
+
+- TXB0104：Channels=4, Type=Auto-direction, Speed=100 Mbps, I2C Safe?=**NO**
+- TXB0108：Channels=8, Type=Auto-direction, Speed=100 Mbps, I2C Safe?=**NO**
+- PCA9306：Channels=2, Type=I2C-specific, Speed=1 MHz, I2C Safe?=**YES**
+- PCA9517：Channels=2, Type=I2C buffer, Speed=400 kHz, I2C Safe?=**YES**
+- 74LVC245：Channels=8, Type=Unidirectional, Speed=100 MHz, I2C Safe?=N/A (direction pin)
+- BSS138 modules：Channels=4, Type=Bidirectional, Speed=400 kHz, I2C Safe?=**YES**
+
+**CRITICAL WARNING:** TXB-series level shifters do **NOT** work reliably with open-drain protocols (I2C, 1-Wire). They fight the pull-up resistors and cause communication errors. Use BSS138-based modules or PCA9306 for I2C.
+
+### Method 4: Direct Connection (3.3V → 5V Input)
+
+Many 5V devices recognize 3.3V as logic HIGH:
+
+- VIH (HIGH threshold)：Typical 5V TTL=2.0V, Typical 5V CMOS=3.5V
+- VIL (LOW threshold)：Typical 5V TTL=0.8V, Typical 5V CMOS=1.5V
+
+**Check datasheet for VIH.** If VIH < 3.0V, direct connection usually works.
+
+**NEVER** connect 5V output directly to 3.3V input — level shift or divide required.
+
+---
+
+## Common Mistakes and Warnings
+
+### NEVER Do This
+
+- Connect 5V directly to any GPIO：Consequence=**Permanent chip damage**
+- Drive relay coil directly from GPIO：Consequence=Inductive kickback damages GPIO
+- Drive motor directly from GPIO：Consequence=Overcurrent, voltage spikes
+- Exceed 50mA total on RPi GPIO：Consequence=Voltage instability, damage
+- Use ESP32 GPIO6-11 (WROOM)：Consequence=Flash pins — chip crashes
+- Pull GPIO12 HIGH at boot (ESP32)：Consequence=**Flash voltage brick**
+- Forget pull-ups on I2C：Consequence=Communication failure
+- Forget pull-up on 1-Wire：Consequence=Bus doesn't work
+- Use TXB-series for I2C：Consequence=Unreliable communication
+- Assume GPIO is 5V tolerant：Consequence=It's not — damage results
+
+### ALWAYS Do This
+
+- Use current-limiting resistor for LEDs：Reason=Prevents overcurrent (220-330Ω)
+- Use flyback diode with relays/motors：Reason=Catches inductive voltage spike
+- Use level shifter for 5V ↔ 3.3V：Reason=Protects GPIO from overvoltage
+- Check total current draw：Reason=Prevent exceeding limits
+- Verify I2C addresses before wiring：Reason=Detect conflicts early
+- Add 100nF decoupling capacitor near ICs：Reason=Reduces noise, improves stability
+- Use external pull-ups for I2C (4.7kΩ)：Reason=Internal pulls too weak
+- Check ESP32 pin restrictions：Reason=Strapping, flash, input-only
+- Use transistor for loads >16mA：Reason=Protects GPIO
+- Add ESD protection for external connectors：Reason=Protects against static
+
+---
+
+## Quick Reference Card
+
+### Formulas
+
+**LED Resistor:**
+```
+R = (VCC - Vf) / If
+R = (3.3V - 2.0V) / 10mA = 130Ω minimum
+Recommended: 220-330Ω (5-10mA, plenty bright)
+```
+
+**Voltage Divider:**
+```
+Vout = Vin × (R2 / (R1 + R2))
+For 5V → 3.3V: R1=1kΩ, R2=2kΩ
+```
+
+**Pull-up Resistor:**
+```
+R = (VCC - VOL) / IOL
+Standard: 4.7kΩ for I2C/1-Wire, 10kΩ for buttons
+```
+
+### Quick Values
+
+- LED resistor (3.3V, red/green)：220-330Ω
+- LED resistor (3.3V, blue/white)：100-150Ω
+- I2C pull-up：**4.7kΩ** to 3.3V
+- 1-Wire pull-up：**4.7kΩ** to 3.3V
+- Button pull-up/down：10kΩ
+- SPI CS pull-up：10kΩ
+- 5V → 3.3V divider：1kΩ + 2kΩ
+- Flyback diode：1N4148 or 1N4007
+- Decoupling capacitor：100nF ceramic
+
+### Current Limits Summary
+
+- Raspberry Pi：Per Pin=16mA, Total GPIO=**50mA**
+- ESP32：Per Pin=20mA recommended, Total GPIO=~1200mA chip total
+
+### Voltage Summary
+
+- Logic HIGH：RPi=3.3V, ESP32=3.3V
+- Logic LOW：RPi=0V, ESP32=0V
+- Max input：RPi=3.3V, ESP32=3.3V
+- 5V tolerant：RPi=**NO**, ESP32=**NO**
+
+### Common Pin Restrictions
+
+**Raspberry Pi:**
+- GPIO0/1: Reserved (HAT EEPROM)
+- GPIO14/15: UART/BT conflict (Pi 3/4/Zero2W)
+
+**ESP32:**
+- GPIO6-11: Flash pins — **NEVER USE**
+- GPIO12: Strapping — **DANGER** (flash voltage)
+- GPIO16-17: PSRAM (WROVER only)
+- GPIO34-39: Input only, no pulls
+
+---
@@ -0,0 +1,76 @@
+# ESP32-C2 硬件约束与踩坑
+
+> **芯片：esp32-c2** | **类别：constraints** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. GPIO 数量极度有限 ⚠️ 首要问题
+
+- SiP Flash 型号 **仅 14 个 GPIO 可用**（GPIO11–17 被 Flash 占用）
+- 比 C3（22 个）少 8 个，比 ESP32（34 个）少 20 个
+- 规划外设时必须精打细算，可能不够用
+
+## 2. 无通用 SPI ⚠️ 容易被忽略
+
+- SPI0/1 被 Flash 完全占用
+- **没有 SPI2（通用 SPI）**，无法接 SPI 外设（如 SPI LCD、SPI Flash 等）
+- 如果项目需要 SPI 外设 → 换 C3 或更高系列
+
+## 3. 无 I2S
+
+- C2 没有 I2S 接口
+- 需要音频输出或 PDM 麦克风 → 换 C3 或 S3
+
+## 4. 仅 1 个 UART
+
+- 只有 UART0（默认 GPIO20/21），同时用于烧录和日志
+- 如果项目需要独立的调试串口 + 通信串口 → 不够用
+- 换 C3 有 2 个 UART
+
+## 5. ADC 限制
+
+- 仅 5 通道 ADC1（GPIO0–4），无 ADC2
+- 推荐工作范围 0–2800 mV（非 0–3300 mV）
+- 无 ADC/WiFi 冲突（RISC-V 架构）
+- 最高采样率 100 Ksps
+
+## 6. Strapping 引脚
+
+- **GPIO8**: 启动模式引脚
+- **GPIO9**: 启动模式引脚
+
+> 仅 2 个 Strapping，比 C3（3个）更简单。
+
+## 7. USB-JTAG
+
+- GPIO18/19 默认 USB Serial/JTAG
+- 切 GPIO 后 USB 烧录功能失效，只能 UART
+
+## 8. RTC 唤醒
+
+- Deep-sleep: GPIO0–5
+- Light-sleep: GPIO0–20
+
+## 9. 供电
+
+- 3.0–3.6V，推荐 3.3V
+- LDO ≥ 500 mA
+- WiFi TX 峰值约 150 mA（功耗低于 C3）
+
+## 10. 什么时候选 C2，什么时候换 C3
+
+- **极低成本 IoT 节点**: 需要通用 SPI
+- **GPIO ≤ 10 个**: GPIO > 14 个
+- **不需要 SPI 外设**: 需要 I2S 音频
+- **不需要 I2S / 音频**: 需要 2 个 UART
+- **ESP8266 升级（需要 BLE）**: 需要 DAC / 触摸
+
+## 11. 常见踩坑
+
+- **选了 C2 发现接不了 SPI LCD**: 无通用 SPI
+  → 换 C3
+- **GPIO 不够用**: SiP 型号仅 14 GPIO
+  → 换 C3 或非 SiP 型号
+- **需要两个串口不够**: 仅 1 个 UART
+  → 换 C3
+- **需要 I2S 音频输出**: 无 I2S
+  → 换 C3
+
@@ -0,0 +1,46 @@
+# ESP32-C2 Specifications
+> **芯片：esp32-c2** | **类别：specs** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. Core Architecture
+- **CPU:** Single-core RISC-V, 120 MHz — 全系列最低主频之一
+- **Wireless:** 802.11 b/g/n (Wi-Fi 4), BLE 5.0
+- **Application:** Cost-sensitive IoT nodes, direct ESP8266 replacement, 极致低成本
+
+## 2. Memory
+- **SRAM:** 272 KB internal（16 KB 保留为 Cache）
+- **ROM:** 576 KB
+- **外部 Flash:** SiP 封装内集成 4 MB（部分型号无内置 Flash）
+- **无 PSRAM 支持**
+
+## 3. Peripheral Mapping
+- **GPIO Count:** 芯片 21 个（GPIO0–20），SiP Flash 型号可用 14 个（GPIO11–17 被 Flash 占用）
+- **ADC:** 1 个 ADC1，5 通道（GPIO0–4），12-bit，最高 100 Ksps
+- **DAC:** **None**
+- **Touch:** **None**
+- **USB:** USB Serial/JTAG（GPIO18/19）
+- **Hardware PWM:** LEDC（6 通道）
+- **UART:** 1 个（UART0 默认 GPIO20/21）— 注意只有 1 个 UART
+- **I2C:** 1 个（可映射到任意 GPIO）
+- **SPI:** 2 个（SPI0/1 Flash；SPI2 不可用，无通用 SPI）
+- **I2S:** **None** — 无音频接口
+
+## 4. Hardware Safety & Constraints
+- **ADC/WiFi Conflict:** **None** — C2 只有 ADC1，RISC-V 架构无冲突
+- **Flash Pins:** GPIO11–17（SiP Flash 型号内部占用，不可用）
+- **Strapping Pins:** GPIO8, GPIO9
+- **供电:** 3.0–3.6V，推荐 3.3V
+- **Deep-sleep:** ~5 µA
+- **工作温度:** −40°C ~ +85°C / +105°C
+- **封装:** QFN24（4×4 mm）或 QFN32（5×5 mm）
+
+## 5. RTC 唤醒限制
+- **Deep-sleep 可唤醒:** GPIO0–5
+- **仅 Light-sleep 可唤醒:** GPIO6–20
+
+## 6. 定位：ESP8266 的继任者
+- CPU：ESP8266=Xtensa L106 80/160MHz, ESP32-C2=RISC-V 120MHz
+- SRAM：ESP8266=160 KB, ESP32-C2=272 KB
+- GPIO：ESP8266=17, ESP32-C2=14（SiP）
+- ADC：ESP8266=1ch 10-bit, ESP32-C2=5ch 12-bit
+- BLE：ESP8266=❌, ESP32-C2=✅ 5.0
+- 封装：ESP8266=QFN32 5x5, ESP32-C2=QFN24 4x4
@@ -0,0 +1,62 @@
+# ESP32-C3 硬件约束与踩坑
+
+> **芯片：esp32-c3** | **类别：constraints** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. Strapping 引脚方向与 D0WD 相反 ⚠️ 最危险的坑
+
+- 进下载模式 — GPIO0 → GND（低电平）, GPIO8 → 3.3V（**高电平**）
+- 正常 Boot ×GPIO0 高电平 — GPIO8 低电平
+
+**C3 正确设计：** GPIO8 下拉 GND（默认低=正常启动）+ 按键接 3.3V（按下=进下载）
+
+如果按 D0WD 习惯给 GPIO8 加上拉 + 按键到 GND → **每次 RESET 都进下载模式，根本启动不了！**
+
+## 2. GPIO2 不能接上拉 ⚠️ 量产必炸
+
+GPIO2 上电瞬间决定 VDD_SPI 电压：
+- GPIO2=LOW → VDD_SPI=3.3V ✅
+- GPIO2=HIGH → VDD_SPI=1.8V ❌ Flash 读不出
+
+**GPIO2 绝对禁止：** I2C SDA（开漏+上拉）、OneWire、任何带外部上拉的信号
+
+## 3. C3 Strapping 全表
+
+- GPIO2 (Pin5) — VDD_SPI 电压选择，需保持 LOW=3.3V。**禁止接上拉！禁止做 I2C SDA！**
+- GPIO8 (Pin22) — ROM 打印开关 + 下载模式。HIGH=关闭打印, LOW=进下载。需上拉 3.3V，**与 D0WD 方向相反**
+- GPIO9 (Pin23) — 启动模式选择。HIGH=SPI Boot, LOW=Download Boot。需上拉 + BOOT 键
+
+## 4. USB-JTAG 约束
+
+- GPIO18/19 默认 USB-JTAG，上电即启用
+- 用作普通 GPIO 需固件重配 IO MUX
+- 重配后 USB-JTAG 失效，只能 UART 烧录
+
+## 5. RTC GPIO 唤醒限制
+
+- **✅ Deep-sleep**: GPIO0–5
+- **✅ Light-sleep**: GPIO0–11
+- **❌ Deep-sleep**: GPIO12–21
+
+## 6. Flash 占用
+GPIO12–17: QSPI Flash 占用（模组内部连接）
+
+## 7. 供电
+- 3.0–3.6V, 推荐 3.3V
+- LDO ≥500 mA, 纹波 <75 mVpp
+- WiFi TX 峰值 ~190 mA
+
+## 8. 无硬件
+❌ DAC, ❌ 触摸, ❌ ULP, ❌ 以太网
+
+## 9. 常见踩坑
+- **C3 一直进下载模式**: GPIO8 加了上拉
+  → GPIO8 下拉到 GND，按键接 3.3V
+- **GPIO2 做 I2C SDA 芯片不启动**: GPIO2 被上拉 → Flash 1.8V
+  → SDA 换到 GPIO1
+- **USB 烧录后 GPIO18/19 不能用**: USB-JTAG 占用
+  → 固件中切换 IO MUX
+- **Deep-sleep 唤醒不了 GPIO12+**: 只有 GPIO0–5 可唤醒 Deep-sleep
+  → 用 GPIO0–5
+- **嘉立创封装引脚与数据手册不一致**: 封装厂商映射差异
+  → 以 EDA 标注为准
+
@@ -0,0 +1,49 @@
+# ESP32-C3 Specifications
+> **芯片：esp32-c3** | **类别：specs** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. Core Architecture
+- **CPU:** Single-core RISC-V, 160 MHz（483.27 CoreMark）
+- **Wireless:** 802.11 b/g/n (Wi-Fi 4), BLE 5.0.
+- **Application:** Standard budget IoT node, secure connectivity, ESP8266 替代升级.
+
+## 2. Memory
+- **SRAM:** 400 KB internal（16 KB 保留为 Cache）
+- **RTC SRAM:** 8 KB
+- **ROM:** 384 KB.
+- **eFuse:** 4096-bit（用户可用 1792-bit）
+- **外部 Flash:** max 16 MB QSPI（常见 4 MB）
+
+## 3. Peripheral Mapping
+- **GPIO Count:** 22 (GPIO0–21).
+- **ADC:** 6 channels, 12-bit（ADC1: GPIO0–4, ADC2: GPIO5）.
+- **DAC:** **None.**
+- **Touch:** **None.**
+- **USB:** USB Serial/JTAG（GPIO18=D-, GPIO19=D+），非 USB OTG.
+- **Hardware PWM:** LEDC (6 channels).
+- **UART:** 2 controllers（UART0 默认 GPIO20/21），max 5 Mbps.
+- **I2C:** 1 controller, max 800 Kbps.
+- **SPI:** 3 controllers（SPI2 通用，max 80 MHz）.
+- **I2S:** 1 controller.
+- **CAN (TWAI):** 1 controller.
+
+## 4. Hardware Safety & Constraints
+- **ADC/WiFi Conflict:** **None.** All ADC channels work while Wi-Fi is active（C3 的 RISC-V 架构修复了此问题）.
+- **Flash Pins:** GPIO12–17（RESERVED — 模组内部占用）.
+- **Strapping Pins:** GPIO2, GPIO8, GPIO9.
+  - GPIO2: VDD_SPI 电压选择，**禁止接上拉！禁止做 I2C SDA！**
+  - GPIO8: 启动模式 + ROM日志，需上拉 3.3V（与 D0WD 相反：高电平=进下载）
+  - GPIO9: Pull-Up = SPI Boot, Pull-Down = Download Boot
+- **UART0:** Default on GPIO20(RX)/21(TX).
+- **供电:** 3.0–3.6V, 推荐 3.3V.
+- **峰值电流:** ~190 mA (WiFi TX).
+- **Deep-sleep:** ~5 µA.
+- **工作温度:** −40°C ~ +85°C（可扩展到 +105°C）.
+- **封装:** QFN32 (5×5mm).
+
+## 5. RTC 唤醒限制
+- **Deep-sleep 可唤醒:** GPIO0–5
+- **仅 Light-sleep 可唤醒:** GPIO6–11
+- **不可唤醒:** GPIO12–21
+
+## 6. 无硬件资源
+❌ DAC, ❌ 触摸传感器, ❌ ULP 协处理器, ❌ 以太网 MAC
@@ -0,0 +1,75 @@
+# ESP32-C5 硬件约束与踩坑
+
+> **芯片：esp32-c5** | **类别：constraints** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. ADC-WiFi 共存 ✅ 无冲突
+
+C5 只有 ADC1（6ch，GPIO1–6），RISC-V 架构无 ADC/WiFi 冲突。所有 ADC 通道在 WiFi 下正常使用。
+
+## 2. Strapping 引脚与启动模式
+
+C5 与 C6 共享 RISC-V 架构，Strapping 机制类似：
+
+- **GPIO8** — Floating，上拉到 VDD = 下载模式
+- **GPIO9** — Weak Pull-Up，下拉到 GND = 下载模式
+
+> ⚠️ GPIO8 和 GPIO9 **不能同时为低**。完整 Strapping 列表（含 MTMS/MTDI 等）待 C5 TRM 确认。
+
+### 固件下载接口
+
+- **UART0**: 待模组 Datasheet 确认
+- **USB**: USB_D-/D+（与 C6 类似，待确认具体 GPIO）
+
+## 3. 双频天线设计 ⚠️ C5 特有挑战
+
+- C5 支持 2.4GHz + 5GHz 双频 Wi-Fi
+- 天线必须同时支持两个频段（双频天线或双天线设计）
+- 5GHz 对 PCB 走线阻抗匹配要求更高
+- 建议参考 Espressif 官方双频天线设计指南
+
+## 3. CAN FD 特性
+
+- C5 有 2 个 **CAN FD** 控制器（比 C6 的 CAN 2.0 更强）
+- 支持 ISO 11898-1:2015 标准
+- 数据段速率最高 5 Mbps
+- 兼容传统 CAN 2.0
+
+## 4. GPIO13/14 高驱动能力
+
+- GPIO13/14 默认 **40 mA** 驱动（其他引脚 20 mA）
+- 适合直接驱动 LED、小继电器等
+- 注意：高电流时需考虑总芯片电流限制
+
+## 5. 供电约束
+
+- 3.0–3.6V，推荐 3.3V
+- 双频 WiFi 同时工作时峰值电流比单频高
+- 纹波 < 75 mVpp
+
+## 6. 多电源域
+
+C5 GPIO 分布在 VDDPST2/VDDPST3/VDD_SPI 多个电源域，睡眠模式下不同域的行为不同：
+- 确认引脚所在电源域
+- 设计低功耗功能时注意保持需要的电源域
+
+## 7. 外部晶振
+
+- 高速晶振: 40 MHz
+- RTC 晶振: 32.768 kHz（可选）
+- 5GHz 射频可能需要额外的时钟精度要求
+
+## 8. 芯片成熟度
+
+- C5 是 2024 年发布的新芯片
+- 部分资料（TRM、Strapping 完整列表）仍在完善中
+- 量产设计前建议联系 Espressif FAE 确认最新资料
+
+## 9. 常见踩坑
+
+- **5GHz 信号差**: 天线不匹配/PCB 走线阻抗不对
+  → 参考官方双频天线设计
+- **只有 22 个 GPIO**: 模组未引出全部芯片引脚
+  → 确认模组规格
+- **CAN FD 不工作**: 用了 CAN 2.0 库
+  → 需用 CAN FD 驱动
+
@@ -0,0 +1,59 @@
+# ESP32-C5 Specifications
+> **芯片：esp32-c5** | **类别：specs** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. Core Architecture
+- **CPU:** Single-core RISC-V, **240 MHz** — C 系列最高主频
+- **Wireless:** **双频 Wi-Fi 6** (2.4GHz + 5GHz), BLE 5.0, Zigbee/Thread (802.15.4)
+- **Application:** High-speed IoT connectivity, dual-band Wi-Fi requirements — 乐鑫首款双频 Wi-Fi 6 MCU
+
+## 2. Memory
+- **HP SRAM:** 384 KB internal
+- **LP SRAM:** 16 KB
+- **ROM:** 320 KB
+- **eFuse:** 4096-bit
+- **外部 Flash:** 4 MB（ESP32-C5HF4 SiP 内置）
+- **PSRAM:** 8 MB Quad SPI（ESP32-C5HR8 SiP 内置）
+- **Cache:** 32 KB L1
+
+## 3. Peripheral Mapping
+- **GPIO Count:** **29** 个（芯片），模组引出 **22** 个（WROOM-1/MINI-1）
+- **ADC:** **1 个 ADC1，6 通道**（GPIO1–6），12-bit SAR
+- **DAC:** **None**
+- **Touch:** **None**
+- **USB:** USB Serial/JTAG
+- **Hardware PWM:** LEDC 6 通道 + MCPWM 6 通道
+- **UART:** 3 个（2 HP + 1 LP）
+- **I2C:** 2 个（1 HP + 1 LP）
+- **SPI:** 3 个（2 Flash + 1 通用 SPI）
+- **I2S:** 1 个
+- **CAN:** **2 个 CAN FD**（CAN 2.0 兼容，支持 FD 帧）
+- **SDIO:** 1 个从机
+- **PARLIO:** 1 个并行 IO
+- **PCNT:** 1 个脉冲计数器
+
+## 4. Hardware Safety & Constraints
+- **ADC/WiFi Conflict:** **None** — C5 只有 ADC1（6ch），RISC-V 架构无冲突
+- **Strapping Pins:** 参考 C6 类似，待 TRM 确认完整列表
+- **供电:** 3.0–3.6V，推荐 3.3V
+- **Deep-sleep:** ~7 µA
+- **工作温度:** −40°C ~ +105°C
+- **封装:** QFN48（6×6 mm）
+- **芯片型号:** ESP32-C5HR8（8MB PSRAM）/ ESP32-C5HF4（4MB Flash）
+
+## 5. Wi-Fi 6 双频特性（C5 独有）
+- 标准：2.4 GHz=802.11ax, 5 GHz=802.11ax
+- 带宽：2.4 GHz=20 MHz, 5 GHz=20 MHz
+- MCS：2.4 GHz=MCS0–9, 5 GHz=MCS0–7
+- 频率：2.4 GHz=2412–2484 MHz, 5 GHz=5180–5885 MHz
+- 速率：2.4 GHz=最高 150 Mbps
+
+Wi-Fi 6 特性: OFDMA (UL/DL), MU-MIMO (DL), Beamformee, TWT 省电, 空间复用
+后向兼容: 802.11a/b/g/n/ac
+
+## 6. 芯片定位
+- 主频：ESP32-C5=**240 MHz**, ESP32-C6=160 MHz
+- Wi-Fi：ESP32-C5=双频 (2.4+5GHz), ESP32-C6=2.4GHz only
+- CAN：ESP32-C5=CAN FD ×2, ESP32-C6=CAN 2.0 ×2
+- SRAM：ESP32-C5=384 KB, ESP32-C6=512 KB
+- 封装：ESP32-C5=QFN48 6×6, ESP32-C6=QFN40 5×5
+- 定位：ESP32-C5=高性能双频 IoT, ESP32-C6=主流 Matter/mesh
@@ -0,0 +1,74 @@
+# ESP32-C6 硬件约束与踩坑
+
+> **芯片：esp32-c6** | **类别：constraints** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. ADC-WiFi 共存 ✅ 无冲突
+C6 只有 ADC1（7ch），RISC-V 架构无 ADC2/WiFi 冲突问题。所有 ADC 通道 WiFi 下正常使用。
+
+## 2. Strapping 引脚与启动模式
+
+### 启动模式控制
+
+- **GPIO8** — Floating（无内置上下拉），上拉到 VDD 进下载模式。⚠️ 与 GPIO9 **不能同时为低**
+- **GPIO9** — Weak Pull-Up。SPI Boot 时保持高电平，下拉到 GND 进下载模式
+
+启动模式选择：
+
+- SPI Boot（正常启动）：GPIO9=1，GPIO8 任意
+- Download Boot（烧录）：GPIO8=1，GPIO9=0
+
+> ⚠️ **GPIO8=0 且 GPIO9=0 的组合无效，会导致不可预期的行为！**
+
+其他 Strapping：
+
+- GPIO4 (MTMS) — JTAG 信号源选择
+- GPIO5 (MTDI) — 启动配置辅助
+- GPIO15 — 启动配置 / ROM 日志控制
+
+### 固件下载接口
+
+- **UART0 下载**: TXD0=**GPIO16**, RXD0=**GPIO17**
+- **USB 下载**: USB_D-=**GPIO12**, USB_D+=**GPIO13**
+
+### 时序要求
+- Hold time (t_H): >= **3 ms**（EN 拉高后 Strapping 值被锁存）
+
+## 3. USB-JTAG
+GPIO12/13 默认 USB，切 GPIO 需固件配置，之后 USB-JTAG 失效。
+
+## 4. LP CPU 约束
+- 主频仅 20 MHz
+- LP SRAM 仅 16 KB
+- GPIO8–21 可用作 LP GPIO
+
+## 5. WiFi 6 限制
+- 仅 20 MHz 带宽（不支持 40 MHz）
+- 仅 2.4 GHz（不支持 5 GHz）
+- 仅 1T1R（不支持 MIMO）
+
+## 6. 供电
+- 3.0–3.6V, 推荐 3.3V
+- WiFi6 + BLE 峰值 ~350 mA
+- 纹波 <75 mVpp
+
+## 7. 外部晶振
+- 高速: 40 MHz
+- RTC: 32.768 kHz（可选, GPIO0/1）
+
+## 8. 常见踩坑
+- **只有 7 个 ADC 通道**: C6 只有 ADC1
+  → 加外置 ADC
+- **WiFi6 速率不如预期**: 仅 20MHz + 1T1R
+  → 硬件限制
+- **LP CPU 跑不动复杂任务**: 20MHz + 2级流水线
+  → 只做传感器读取
+
+## 上电时序要求
+
+- t_STBL：**>= 50 µs** — VDD 电源轨稳定后到 EN (CHIP_PU) 拉高之间的最短等待时间
+- t_RST：**>= 50 µs** — EN 拉低以触发硬件复位的最短保持时间
+- t_H：**>= 3 ms** — EN 拉高后 Strapping 引脚值被内部锁存的时间，此后 Strapping 引脚恢复普通 GPIO 功能
+
+> CHIP_PU (EN) 引脚**绝对不能浮空**。推荐电路：EN 通过 10kΩ 上拉到 VDD，对地接 1µF 电容做消抖和上电延迟。
+
+> CHIP_PU (EN) 引脚**绝对不能浮空**。推荐：EN 通过 10kΩ 上拉到 VDD，对地接 1µF 电容做消抖。
@@ -0,0 +1,53 @@
+# ESP32-C6 Specifications
+> **芯片：esp32-c6** | **类别：specs** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. Core Architecture
+- **CPU:** Single-core RISC-V, 160 MHz（HP CPU）+ LP RISC-V 20 MHz（协处理器）
+- **Wireless:** Wi-Fi 6 (802.11ax, 2.4GHz, 20MHz only, 1T1R), BLE 5.3, Zigbee/Thread (802.15.4).
+- **Application:** Next-gen Matter nodes, mesh networking, Wi-Fi 6 efficiency — IoT 芯片首次支持 WiFi 6.
+
+## 2. Memory
+- **HP SRAM:** 512 KB internal.
+- **LP SRAM:** 16 KB.
+- **ROM:** 320 KB.
+- **Cache:** 32 KB L1.
+- **eFuse:** 4096-bit.
+- **外部 Flash:** max 8 MB QSPI.
+
+## 3. Peripheral Mapping
+- **GPIO Count:** 30 (QFN40) / 22 (QFN32).
+- **ADC:** 7 channels, 12-bit（仅 ADC1, GPIO0–6）.
+- **DAC:** **None.**
+- **Touch:** **None.**
+- **Hardware PWM:** LEDC 6ch + MCPWM.
+- **UART:** 3（2 HP + 1 LP）, max 5 Mbps.
+- **I2C:** 2（1 HP + 1 LP）.
+- **SPI:** 3（1 通用 SPI2）.
+- **I2S:** 1 controller.
+- **CAN (TWAI):** 2 controllers.
+- **USB Serial/JTAG:** 1（GPIO12/13）.
+- **SDIO 2.0:** 1（从机）.
+- **PARLIO:** 1（并行 IO）.
+
+## 4. Hardware Safety & Constraints
+- **ADC/WiFi Conflict:** **None.**（C6 只有 ADC1，无 ADC2，RISC-V 架构已修复）
+- **Flash Pins:** GPIO24–29（待核实确切范围）.
+- **Strapping Pins:** GPIO4 (MTMS), GPIO5 (MTDI), GPIO8, GPIO9, GPIO15.
+- **LP GPIO:** GPIO8–21 可用作 LP GPIO，由 LP CPU 直接驱动。
+- **供电:** 3.0–3.6V, 推荐 3.3V.
+- **Deep-sleep:** ~7 µA.
+- **工作温度:** −40°C ~ +85°C（可扩展到 +105°C）.
+- **封装:** QFN40 (5×5mm) 或 QFN32 (5×5mm).
+
+## 5. Wi-Fi 6 特性
+- 802.11ax 20MHz-only non-AP mode
+- OFDMA (UL/DL), MU-MIMO (DL)
+- TWT (Target Wake Time) 省电
+- 后向兼容 802.11 b/g/n
+- TX power: +19.5 dBm (ax), +21 dBm (b)
+
+## 6. 多协议支持
+- Bluetooth 5.3 LE / Mesh
+- Thread 1.3
+- Zigbee 3.0
+- Matter (via Thread/WiFi)
@@ -0,0 +1,54 @@
+# ESP32-H2 硬件约束与踩坑
+
+> **芯片：esp32-h2** | **类别：constraints** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. 无 WiFi ⚠️ 最易搞错
+- H2 **没有 WiFi 硬件**，仅 BLE 5.3 + Thread/Zigbee (802.15.4)
+- 需要 WiFi+Thread 组合 → 选 **ESP32-C6**
+
+## 2. Strapping 引脚与启动模式
+
+- **GPIO8** — 下载模式：GPIO8=1 且 GPIO9=0 → Joint Download Boot
+- **GPIO9** — SPI Boot 时=1；Download Boot 时需 GPIO8=1, GPIO9=0
+- **GPIO25** — JTAG 信号源选择
+
+### 启动模式选择
+
+- SPI Boot（正常） ：GPIO 电平=任意 , 1
+- Joint Download Boot (USB/UART) ：GPIO 电平=1 , 0
+
+### 固件下载接口
+
+- **UART0**: TXD0 / RXD0（默认引脚待模组确认）
+- **USB**: USB_D-=**GPIO12**, USB_D+=**GPIO13**
+
+> Hold time (t_H): >= **3 ms**（EN 拉高后 Strapping 值锁存）
+
+## 3. 主频限制
+最高 **96 MHz**，全系列最低。需要高性能 DSP/计算 → C6 (160MHz) 或 S3 (240MHz)
+
+## 3. GPIO 数量少
+- 芯片 19 GPIO
+- WROOM-07 模组仅 **3 个 GPIO**
+- 选模组时务必确认引出数量
+
+## 4. ADC 通道少
+仅 5 通道（GPIO1–5），无 ADC1/ADC2 区分，无 WiFi 所以无冲突
+
+## 5. Deep-sleep 唤醒限制
+- 只有 LP GPIO（GPIO8–14）可唤醒 Deep-sleep
+- GPIO0–7 只能唤醒 Light-sleep
+
+## 6. 供电
+- 3.0–3.6V, 推荐 3.3V
+- BLE+802.15.4 TX 峰值 ~60 mA（无 WiFi，供电要求低）
+- 纹波 <75 mVpp
+
+## 7. 常见踩坑
+- **选了 H2 发现没 WiFi**: H2 无 WiFi 射频
+  → 换 C6
+- **WROOM-07 只有 3 GPIO**: 微型模组未全部引出
+  → 换 WROOM-02C
+- **GPIO0 不能唤醒 Deep-sleep**: 只有 LP 引脚可唤醒
+  → 用 GPIO8–14
+
@@ -0,0 +1,48 @@
+# ESP32-H2 Specifications
+> **芯片：esp32-h2** | **类别：specs** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. Core Architecture
+- **CPU:** Single-core RISC-V, 96 MHz（303.38 CoreMark）— 全系列最低主频.
+- **Wireless:** BLE 5.3, Zigbee/Thread (802.15.4). **Note: No Wi-Fi support.**
+- **Application:** Smart home devices, Matter over Thread, low-power sensors — 超低功耗传感器节点.
+
+## 2. Memory
+- **SRAM:** 320 KB internal.
+- **LP Memory:** 4 KB.
+- **ROM:** 128 KB.
+- **内置 Flash:** 2 MB 或 4 MB QSPI.
+
+## 3. Peripheral Mapping
+- **GPIO Count:** 芯片 19 个，模组 WROOM-02C 19 个 / WROOM-07 仅 3 个.
+- **ADC:** 5 channels, 12-bit（GPIO1–5）.
+- **DAC:** **None.**
+- **Touch:** **None.**
+- **Hardware PWM:** LEDC 6ch + MCPWM.
+- **UART:** 2 controllers.
+- **I2C:** 2 controllers.
+- **SPI:** 3 controllers.
+- **I2S:** 1 controller.
+- **CAN (TWAI):** 1 controller.
+- **USB Serial/JTAG:** 1.
+- **PARLIO:** 1.
+
+## 4. Hardware Safety & Constraints
+- **No Wi-Fi:** 这是 H2 与 C6 最大的区别。需要 WiFi+Thread → 选 C6.
+- **Strapping Pins:** GPIO8, GPIO9, GPIO25.
+- **LP GPIO:** GPIO8–14 可在 Deep-sleep 下保持功能.
+- **数字 GPIO:** GPIO0–5, GPIO22–27 只能在 Light-sleep 唤醒，不能在 Deep-sleep 唤醒.
+- **功耗极低:** BLE + 802.15.4 TX 峰值 ~60 mA, Deep-sleep ~7 µA.
+- **供电:** 3.0–3.6V, 推荐 3.3V.
+- **工作温度:** −40°C ~ +105°C.
+- **封装:** QFN32 (4×4mm).
+
+## 5. 无线协议
+- Bluetooth 5.3 LE, Mesh, Coded PHY (125/500 Kbps), 2 Mbps
+- Thread 1.4
+- Zigbee 3.0
+- Matter
+- 802.15.4 RX Sensitivity: -102.5 dBm (250 Kbps)
+
+## 6. 模组选型注意
+- WROOM-02C：GPIO 数=19, 天线=PCB, Flash=2/4 MB
+- WROOM-07：GPIO 数=**仅 3 个**, 天线=外置, Flash=2/4 MB
@@ -0,0 +1,54 @@
+# ESP32-P4 硬件约束与踩坑
+
+> **芯片：esp32-p4** | **类别：constraints** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+> ⚠️ Datasheet v0.6 PRELIMINARY，部分参数待完善
+
+## 1. 无无线功能
+- P4 是纯应用处理器，无 WiFi/BLE/Thread/Zigbee
+- 需要无线 → 搭配 ESP32-C6 或 C5 模组（SPI/SDIO/UART 通信）
+- **不存在 ADC-WiFi 冲突**（根本没有 WiFi）
+
+## 2. Strapping 引脚与启动模式
+
+- **GPIO35** — 下载模式：下拉到 GND = Download Boot
+- **GPIO36** — 下载模式：上拉到 VDD = Download Boot
+
+### 启动模式选择
+
+- SPI Boot（正常） ：GPIO 电平=1 , 任意
+- Download Boot ：GPIO 电平=0 , 1
+
+### 固件下载接口
+
+- **UART0**: TXD0=**GPIO37**, RXD0=**GPIO38**
+
+> ⚠️ Datasheet v0.6 PRELIMINARY，Strapping 完整列表（5 个）待正式 TRM 确认
+
+## 3. 散热
+- 400 MHz 双核满负载发热明显
+- PCB 需大面积散热铜皮
+- 必要时加散热片
+
+## 3. 供电复杂性
+多路独立电源域：
+- VDD_HP: 400 MHz CPU 核心
+- VDD_LP: 40 MHz LP CPU
+- 封装内 PSRAM: 独立 1.8V
+- PCB 设计比 ESP32/S3 复杂得多
+
+## 4. 外部 Flash
+Flash 不在封装内，需外部 SPI Flash（推荐 ≥16 MB）
+
+## 5. Datasheet 限制
+- v0.6 PRELIMINARY，部分电气参数、Strapping 引脚、功耗数据待完善
+- 设计时需参考 EV Board 原理图和 TRM
+
+## 6. 常见踩坑
+- **Datasheet 不全**: PRELIMINARY v0.6
+  → 查阅 TRM + EV Board 原理图
+- **需要 WiFi 但 P4 没有**: P4 无无线
+  → 搭配 C6 或 C5 模组
+- **功耗比预期高**: 400MHz 双核 + PSRAM
+  → 降频或启用 LP Core
+
@@ -0,0 +1,62 @@
+# ESP32-P4 Specifications
+> **芯片：esp32-p4** | **类别：specs** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+> ⚠️ Datasheet 为初版，部分参数可能更新
+
+## 1. Core Architecture
+- **HP CPU:** Dual-core RISC-V, 400 MHz — 全系列最高主频.
+- **LP CPU:** Single-core RISC-V, 40 MHz.
+- **FPU:** 单精度 FPU + AI 指令扩展.
+- **CoreMark:** 6.92 CoreMark/MHz（双核）.
+- **Wireless:** **None.**（No Wi-Fi, No Bluetooth）— 需搭配 ESP32-C6/C5 等协处理器.
+- **Application:** High-performance multimedia, H.264 encoding, camera/display processing, edge AI 推理, HMI.
+
+## 2. Memory
+- **HP L2MEM (片上 SRAM):** 768 KB.
+- **LP SRAM:** 32 KB.
+- **HP ROM:** 128 KB / **LP ROM:** 16 KB.
+- **SPM (零等待 TCM):** 8 KB.
+- **封装内 PSRAM:** 16 MB 或 32 MB OPI/HPI, 1.8V.
+- **外部 Flash:** 支持 SPI 接口（不在封装内）.
+- **Cache:** 两级高速缓存.
+- **eFuse:** 4096-bit.
+
+## 3. Peripheral Mapping
+- **GPIO Count:** 55.
+- **ADC:** 2 控制器, 12-bit. ADC1: 8ch (GPIO16–23).
+- **DAC:** **None.**
+- **Touch:** 14 ch (GPIO2–15).
+- **USB:** USB 2.0 HS OTG (480Mbps) + USB 2.0 FS OTG + USB Serial/JTAG.
+- **Ethernet MAC:** RMII (10/100 Mbps).
+- **MIPI CSI:** 2-lane 摄像头输入.
+- **MIPI DSI:** 2-lane 显示输出.
+- **H264 Encoder:** 硬件编码.
+- **JPEG Codec:** 硬件编解码.
+- **ISP:** 图像信号处理器.
+- **PPA:** 像素处理加速器.
+- **LCD Controller:** RGB / i8080 / MOTO6800.
+- **UART:** 6（5 HP + 1 LP）.
+- **SPI:** 5（4 HP + 1 LP）.
+- **I2C:** 4（2 HP + 1 LP + 1 模拟）.
+- **I3C:** 1.
+- **I2S:** 4（3 HP + 1 LP, 含 PDM）.
+- **CAN (TWAI):** 1.
+- **MCPWM:** 2.
+- **SD/MMC:** SDIO 3.0.
+
+## 4. Hardware Safety & Constraints
+- **Thermal:** 400 MHz 双核满负载发热明显，需散热设计.
+- **Power:** 多路独立电源域（VDD_HP, VDD_LP, PSRAM 1.8V），PCB 设计复杂.
+- **无无线:** 需要无线连接时必须搭配协处理器（SPI/SDIO/UART 通信）.
+- **Flash:** 封装内无 Flash，需外部 SPI Flash.
+- **封装:** QFN104 (10×10mm).
+- **工作温度:** −40°C ~ +85°C.
+- **Datasheet 版本:** v0.6 PRELIMINARY，部分参数待正式版完善.
+
+## 5. 定位对比
+- 定位：ESP32-S3=AI/IoT MCU, ESP32-P4=应用处理器
+- CPU：ESP32-S3=LX7 240MHz 双核, ESP32-P4=RISC-V 400MHz 双核
+- 无线：ESP32-S3=WiFi4 + BLE5, ESP32-P4=❌ 无
+- PSRAM：ESP32-S3=max 8MB Octal, ESP32-P4=16/32MB 封装内
+- MIPI：ESP32-S3=❌, ESP32-P4=CSI+DSI
+- H264：ESP32-S3=❌, ESP32-P4=✅
+- 以太网：ESP32-S3=❌, ESP32-P4=✅ RMII
@@ -0,0 +1,53 @@
+# ESP32-S2 硬件约束与踩坑
+
+> **芯片：esp32-s2** | **类别：constraints** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. 无蓝牙
+⚠️ **ESP32-S2 没有蓝牙功能**，这是选型最常搞错的点。如果需要 BLE，选 ESP32 / S3 / C3 / C6。
+
+## 2. ADC2 与 WiFi 冲突
+- WiFi 开启时 **ADC2 不可用**（GPIO11–20）
+- 需要 ADC + WiFi → 只用 **ADC1**（GPIO1–10）
+
+## 3. Strapping 引脚
+- **GPIO0** — 进入下载模式
+- **GPIO45** — VDD_SPI 电压选择
+- **GPIO46** — 控制启动日志输出
+
+> S2 只有 3 个 Strapping 引脚，比 ESP32 简洁。
+
+## 4. USB OTG 约束
+- GPIO19/20 默认为 USB_D-/D+
+- 用作普通 IO 需固件中禁用 USB OTG 并配置 IO MUX
+- GPIO19/20 也是 ADC2_CH8/CH9（WiFi 不可用）
+
+## 5. Flash 引脚占用
+- GPIO26–32：SPI Flash/PSRAM 总线，模组内部已连接
+
+## 6. 供电约束
+- **工作电压**: 2.7–3.6V，推荐 3.3V
+- **WiFi TX 峰值**: ~400 mA
+- **纹波**: < 75 mVpp
+
+## 7. JTAG（不与 Strapping 冲突）
+S2 JTAG (GPIO39–42) 不与 Strapping 冲突，比 ESP32 安全。
+
+## 8. 常见踩坑
+- **选了 S2 发现没有蓝牙**: S2 无蓝牙硬件
+  → 换 S3/C3/C6
+- **GPIO19/20 做普通 IO 不工作**: USB 功能未关闭
+  → 固件中配置 IO MUX
+- **ADC2 读数异常**: WiFi 开启
+  → 切 ADC1
+- **GPIO46 设为输出不工作**: GPIO46 仅输入
+  → 换其他 GPIO
+
+## 上电时序要求
+
+- t_STBL：**>= 50 µs** — VDD 电源轨稳定后到 EN (CHIP_PU) 拉高之间的最短等待时间
+- t_RST：**>= 50 µs** — EN 拉低以触发硬件复位的最短保持时间
+- t_H：**>= 3 ms** — EN 拉高后 Strapping 引脚值被内部锁存的时间，此后 Strapping 引脚恢复普通 GPIO 功能
+
+> CHIP_PU (EN) 引脚**绝对不能浮空**。推荐电路：EN 通过 10kΩ 上拉到 VDD，对地接 1µF 电容做消抖和上电延迟。
+
+> CHIP_PU (EN) 引脚**绝对不能浮空**。推荐：EN 通过 10kΩ 上拉到 VDD，对地接 1µF 电容做消抖。
@@ -0,0 +1,64 @@
+# ESP32-S2 Specifications
+> **芯片：esp32-s2** | **类别：specs** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. Core Architecture
+- **CPU:** Single-core Xtensa® LX7, 240 MHz.
+- **Wireless:** 802.11 b/g/n (Wi-Fi 4). **Note: No Bluetooth support.**
+- **协处理器:** ULP-RISC-V 协处理器
+- **Application:** Ultra-low power designs and projects requiring native USB OTG/HID.
+
+## 2. Memory & Storage
+- **SRAM:** 320 KB internal.
+- **ROM:** 128 KB.
+- **RTC SRAM:** 16 KB（Deep-sleep 可保持）
+- **PSRAM:** Supports external PSRAM via SPI/QPI, max 8 MB.
+- **外部 Flash:** max 16 MB QSPI.
+
+## 3. Peripheral Mapping
+- **GPIO Count:** 43.
+- **ADC:** 20 channels, 12-bit（ADC1: GPIO1–10, ADC2: GPIO11–20）.
+- **DAC:** 2 channels, 8-bit（GPIO17/18）.
+- **Touch:** 14 capacitive touch channels.
+- **USB OTG:** Full-Speed USB 2.0（GPIO19=D-, GPIO20=D+）.
+- **Hardware PWM:** LEDC 8ch + MCPWM ×2.
+- **UART:** 2 controllers.
+- **I2C:** 2 controllers.
+- **SPI:** 4 controllers.
+- **I2S:** 1 controller.
+- **CAN (TWAI):** 1 controller.
+- **LCD 接口:** 8-bit i80 / RGB.
+- **DVP Camera:** 8-bit.
+
+## 4. Hardware Safety & Constraints
+- **ADC2/WiFi Conflict:** ADC2 readings are invalid when Wi-Fi is active. Use ADC1 (GPIO1–10).
+- **无蓝牙:** 这是与 ESP32 最大的区别，选型时注意。
+- **Flash Pins:** GPIO26–32（模组内部占用）。
+- **Strapping Pins:** GPIO0（启动模式）, GPIO45（VDD_SPI电压）, GPIO46（仅输入+日志控制）。
+- **GPIO46:** 仅输入，不能做输出。
+- **USB Pins:** Reserve GPIO19/20 if using native USB functionality.
+- **供电:** 2.7–3.6V, 推荐 3.3V, 纹波 <75mVpp.
+- **工作温度:** −40°C ~ +85°C.
+- **封装:** QFN56 (7×7mm).
+
+### 功耗详情（3.3V, 25°C）
+
+- Active TX 802.11b：条件=20MHz, 1Mbps, +19.5dBm, 电流=**310 mA**
+- Active TX 802.11g：条件=20MHz, 54Mbps, +15dBm, 电流=220 mA
+- Active TX 802.11n：条件=20MHz, MCS7, +13dBm, 电流=200 mA
+- Active RX：条件=802.11b/g/n, 20MHz, 电流=**63 mA**
+- Modem-sleep：条件=CPU 240MHz idle, 外设时钟关, 电流=20 mA
+- Modem-sleep：条件=CPU 160MHz idle, 外设时钟关, 电流=14 mA
+- Light-sleep：电流=**750 µA**
+- Deep-sleep：条件=RTC timer + RTC memory, 电流=**22 µA**
+- Deep-sleep：条件=RTC timer only, 电流=**25 µA**
+- Shutdown：条件=CHIP_PU 拉低, 电流=**20 µA**
+
+### TX 功率
+- 802.11b：最大 TX Power=+19.5 dBm
+- 802.11n：最大 TX Power=+18.0 dBm
+
+## 5. 与 ESP32 的关键差异
+- 核心数：ESP32=双核, ESP32-S2=单核
+- 蓝牙：ESP32=BR/EDR+BLE, ESP32-S2=❌ 无
+- USB OTG：ESP32=❌, ESP32-S2=✅
+- GPIO 总数：ESP32=34, ESP32-S2=43
@@ -0,0 +1,59 @@
+# ESP32-S3 硬件约束与踩坑
+
+> **芯片：esp32-s3** | **类别：constraints** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. ADC2 与 WiFi 冲突
+- WiFi 开启时 ADC2（GPIO11–20）不可用。
+- 需要 ADC + WiFi → 只用 ADC1（GPIO1–10）。
+
+## 2. Octal PSRAM 引脚占用 ⚠️ S3 特有
+使用 **Octal PSRAM** 的模组（S3R8/S3R8V）：
+- GPIO33 — SPIIO4
+- GPIO34 — SPIIO5
+- GPIO35 — SPIIO6
+- GPIO36 — SPIIO7
+- GPIO37 — SPIDQS
+
+这些引脚在 Octal PSRAM 模组上完全不可用！
+
+## 3. Strapping 引脚
+- **GPIO0**: 上电时不能为低（进下载模式）
+- **GPIO3**: 上电浮动，需外部确定电平
+- **GPIO45**: VDD_SPI 电压选择
+- **GPIO46**: 启动模式 + 日志控制
+
+时序：Setup ≥0ms, Hold ≥3ms（EN 拉高后锁存）。
+
+## 4. Flash/PSRAM 占用
+- GPIO26–32: SPI Flash/PSRAM 总线
+- GPIO33–37: Octal PSRAM（如有）
+
+## 5. USB 双控制器
+- USB OTG: GPIO19/20（用作普通 IO 需固件配置）
+- USB Serial/JTAG: 内置，专用于烧录调试
+- 两个 USB 独立工作，互不影响
+
+## 6. 供电
+- 2.7–3.6V, 推荐 3.3V
+- WiFi TX 峰值 ~500 mA
+- 纹波 <75 mVpp
+
+## 7. 常见踩坑
+- **S3R8 模组 GPIO33–37 无响应**: Octal PSRAM 占用
+  → 不使用这些引脚
+- **GPIO19/20 做 IO 不工作**: USB OTG 未关闭
+  → 固件中禁能 USB OTG
+- **ADC 读数异常**: ADC2 + WiFi
+  → 切 ADC1
+- **GPIO47/48 逻辑电平不对**: 部分模组 1.8V
+  → 确认模组手册
+
+## 上电时序要求
+
+- t_STBL：**>= 50 µs** — VDD 电源轨稳定后到 EN (CHIP_PU) 拉高之间的最短等待时间
+- t_RST：**>= 50 µs** — EN 拉低以触发硬件复位的最短保持时间
+- t_H：**>= 3 ms** — EN 拉高后 Strapping 引脚值被内部锁存的时间，此后 Strapping 引脚恢复普通 GPIO 功能
+
+> CHIP_PU (EN) 引脚**绝对不能浮空**。推荐电路：EN 通过 10kΩ 上拉到 VDD，对地接 1µF 电容做消抖和上电延迟。
+
+> CHIP_PU (EN) 引脚**绝对不能浮空**。推荐：EN 通过 10kΩ 上拉到 VDD，对地接 1µF 电容做消抖。
@@ -0,0 +1,53 @@
+# ESP32-S3 Specifications
+> **芯片：esp32-s3** | **类别：specs** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. Core Architecture
+- **CPU:** Dual-core Xtensa® LX7, 240 MHz.
+- **Wireless:** 802.11 b/g/n (Wi-Fi 4), BLE 5.0 (Mesh support).
+- **Acceleration:** AI Vector instructions for accelerated ML and complex GUI rendering.
+- **协处理器:** ULP-RISC-V 协处理器.
+- **Application:** High-performance IoT, AI on the edge, and multimedia GUIs.
+
+## 2. Memory & Storage
+- **SRAM:** 512 KB internal.
+- **RTC SRAM:** 16 KB（Deep-sleep 可保持）.
+- **ROM:** 384 KB.
+- **PSRAM:** Support for Octal SPI PSRAM (max 8 MB) — GPIO33–37 占用.
+- **外部 Flash:** max 16 MB QSPI/OPI.
+
+## 3. Peripheral Mapping
+- **GPIO Count:** 45（GPIO0–21, GPIO26–48）.
+- **ADC:** 20 channels, 12-bit SAR（ADC1: GPIO1–10, ADC2: GPIO11–20）.
+- **DAC:** **None.**（注意：S3 无 DAC！）
+- **Touch:** 14 capacitive touch channels.
+- **USB:** Native USB OTG (GPIO19/20) + USB Serial/JTAG（双 USB 控制器）.
+- **Hardware PWM:** LEDC 8ch and MCPWM ×2.
+- **UART:** 3 controllers.
+- **I2C:** 2 controllers.
+- **SPI:** 4 controllers.
+- **I2S:** 2 controllers.
+- **CAN (TWAI):** 2 controllers.
+- **LCD Interface:** Supports RGB, 8080, and I80 interfaces.
+- **DVP Camera:** 8–16 bit.
+
+## 4. Hardware Safety & Constraints
+- **ADC2/WiFi Conflict:** ADC2 readings are invalid when Wi-Fi is active. Use ADC1 (GPIO1–10).
+- **Flash Pins:** GPIO26–32.
+- **Strapping Pins:** 0, 3, 45, 46.
+- **Octal PSRAM:** May reserve GPIO33–37（SPIIO4–SPIIO7, SPIDQS）. S3R8/S3R8V 模组这些引脚不可用。
+- **JTAG:** GPIO39–42，不与 Strapping 冲突。
+- **供电:** 2.7–3.6V, 推荐 3.3V, 纹波 <75mVpp.
+- **峰值电流:** ~500 mA (WiFi TX).
+- **Deep-sleep:** ~7 µA.
+- **工作温度:** −40°C ~ +85°C.
+- **封装:** QFN56 (7×7mm).
+
+## 5. 与 ESP32/S2 的关键差异
+- 核心数：ESP32=双核, ESP32-S2=单核, ESP32-S3=双核
+- 蓝牙：ESP32=BR/EDR+BLE, ESP32-S2=❌, ESP32-S3=BLE 5.0
+- USB OTG：ESP32=❌, ESP32-S2=✅, ESP32-S3=✅
+- USB Serial/JTAG：ESP32=❌, ESP32-S2=❌, ESP32-S3=✅
+- AI 加速：ESP32=❌, ESP32-S2=❌, ESP32-S3=✅
+- Octal PSRAM：ESP32=❌, ESP32-S2=❌, ESP32-S3=✅
+- DAC：ESP32=✅, ESP32-S2=✅, ESP32-S3=❌
+- GPIO：ESP32=34, ESP32-S2=43, ESP32-S3=45
@@ -0,0 +1,71 @@
+# ESP32 硬件约束与踩坑
+
+> **芯片：esp32** | **类别：constraints** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. ADC2 与 WiFi 冲突 ⚠️ 最常踩的坑
+
+- **使用 WiFi 时 ADC2 完全不可用**（ADC2 模块与 WiFi 射频共享内部资源）
+- 解决：需要 WiFi + ADC → 只能用 **ADC1**（GPIO32–39）
+- 不使用 WiFi 时 ADC2 正常可用
+- 即使 WiFi 短暂关闭也无法可靠复用 ADC2（需完全禁用 WiFi 驱动）
+
+## 2. GPIO12 (MTDI) — Flash 电压陷阱 ⚠️ 最危险的坑
+
+- GPIO12=LOW（默认）：VDD_SDIO=3.3V → Flash 正常 ✅
+- GPIO12=HIGH：VDD_SDIO=1.8V → Flash 无法读取 → **变砖** ❌
+
+- **绝对不能在 GPIO12 上接上拉电阻到 3.3V**
+- **不能用 GPIO12 做 I2C SDA**（开漏+上拉会让 GPIO12 变高）
+- 如果必须用 GPIO12，用外部 **下拉** 电阻
+
+## 3. 仅输入引脚限制
+
+- **GPIO34–39**: **无内部上拉/下拉**，外部必须自行加
+- **GPIO34–39**: **不能做数字输出**
+- **GPIO34–39**: 不能做 I2C/SPI MOSI/UART TX/PWM 输出
+
+## 4. Flash/PSRAM 引脚占用
+
+- **GPIO6–11**: 内部 Flash SPI（所有模组）
+- **GPIO16–17**: 内部 PSRAM（WROVER 模组）
+
+## 5. 供电约束
+
+- **工作电压**: 2.7–3.6V，推荐 **3.3V ±5%**
+- **WiFi TX 峰值电流**: ~500 mA
+- **供电纹波**: < **75 mVpp**
+- **EN 引脚**: 不能浮空，需上拉到 VDD3P3_RTC
+- **推荐 LDO**: ≥500 mA 输出能力
+
+## 6. JTAG 引脚冲突
+
+- GPIO12 — MTDI, ⚡ Strapping（Flash 电压选择）
+- GPIO13 — MTCK, 无冲突
+- GPIO14 — MTMS, 无冲突
+- GPIO15 — MTDO, ⚡ Strapping
+
+## 7. 外部晶振
+
+- 外部高速晶振：**40 MHz**（必须）
+- 外部 RTC 晶振：**32.768 kHz**（可选，用于 Deep-sleep 精确计时）
+
+## 8. 常见踩坑速查
+
+- **用 GPIO12 做输出，板子不启动**: GPIO12 被外部上拉 → Flash 1.8V
+  → 避免在 GPIO12 上加外部上拉
+- **ADC 读数全是噪音**: 用了 ADC2 且 WiFi 开着
+  → 切换到 ADC1（GPIO32–39）
+- **GPIO34–39 输出不工作**: 它们是仅输入引脚
+  → 换个能做输出的 GPIO
+- **上电后直接进下载模式**: GPIO0 被外部拉低
+  → 检查 GPIO0 电路
+- **Deep-sleep 后 RTC 内存丢了**: RTC Slow 内存只有 8KB 且需特殊 API
+  → 使用 `RTC_DATA_ATTR` 属性
+
+## 上电时序要求
+
+- t_STBL：**>= 50 µs** — VDD 电源轨稳定后到 EN (CHIP_PU) 拉高之间的最短等待时间
+- t_RST：**>= 50 µs** — EN 拉低以触发硬件复位的最短保持时间
+- t_H：**>= 3 ms** — EN 拉高后 Strapping 引脚值被内部锁存的时间，此后 Strapping 引脚恢复普通 GPIO 功能
+
+> CHIP_PU (EN) 引脚**绝对不能浮空**。推荐电路：EN 通过 10kΩ 上拉到 VDD，对地接 1µF 电容做消抖和上电延迟。
@@ -0,0 +1,51 @@
+# ESP32 Specifications
+> **芯片：esp32** | **类别：specs** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## 1. Core Architecture
+- **CPU:** Dual-core Xtensa® LX6, 240 MHz（可选单核版本）
+- **性能:** 单核 539.98 CoreMark / 双核 1079.96 CoreMark
+- **Wireless:** 802.11 b/g/n (Wi-Fi 4), Bluetooth Classic (v4.2), BLE (v4.2)
+- **协处理器:** ULP（超低功耗协处理器），用于 Deep-sleep 模式下的传感器操作
+- **Application:** 双核 IoT 旗舰，支持经典蓝牙的遗留项目
+
+## 2. Memory & Storage
+- **SRAM:** 520 KB internal（指令+数据+Cache 共享）
+- **RTC SRAM:** 16 KB（8 KB Fast + 8 KB Slow，Deep-sleep 可保持）
+- **ROM:** 448 KB Boot ROM
+- **DRAM:** Data RAM, single-byte accessible
+- **IRAM:** Instruction RAM, code for interrupts/flash writes must reside here
+- **PSRAM:** Supports external Pseudo-Static RAM, max 8 MB（standard on WROVER modules）
+- **外部 Flash:** max 16 MB QSPI
+
+## 3. Peripheral Mapping
+- **GPIO Count:** 34（GPIO0–GPIO19, GPIO21–GPIO23, GPIO25–GPIO27, GPIO32–GPIO39）
+- **ADC:** 18 channels, 12-bit SAR（ADC1: 8ch on GPIO32–39, ADC2: 10ch on GPIO0/2/4/12–15/25–27）
+- **DAC:** 2 channels, 8-bit（GPIO25, 26）
+- **Touch:** 10 capacitive touch channels
+- **Hardware PWM:** LEDC 16 channels + MCPWM ×2
+- **UART:** 3 controllers (UART0/UART1/UART2)
+- **I2C:** 2 controllers（any GPIO via matrix）
+- **SPI:** 4 controllers（SPI0/1 Flash, SPI2/HSPI, SPI3/VSPI user-accessible）
+- **I2S:** 2 controllers
+- **CAN (TWAI):** 1 controller, CAN 2.0
+- **霍尔传感器:** 1 个（仅 ESP32 独有）
+- **温度传感器:** 1 个内置
+
+## 4. Hardware Safety & Constraints
+- **Flash Voltage Trap:** GPIO12 (MTDI). If HIGH at boot, sets flash to 1.8V — bricking risk for 3.3V modules.
+- **ADC2/WiFi Conflict:** ADC2 cannot be used when Wi-Fi or Bluetooth is active. Use ADC1 (GPIO32–39).
+- **Input-Only Pins:** GPIO34, 35, 36, 39. No output drivers, no internal pulls.
+- **Flash Pins:** GPIO6–11（RESERVED — Never use）
+- **PSRAM Pins:** GPIO16, 17（RESERVED on WROVER modules）
+- **Strapping Pins:** 0, 2, 5, 12(MTDI), 15(MTDO)
+- **供电:** 2.7–3.6V, 推荐 3.3V, 纹波 <75mVpp
+- **峰值电流 (WiFi TX):** ~500 mA
+- **Deep-sleep 电流:** ~10 µA
+- **工作温度:** −40°C ~ +85°C
+- **封装:** QFN 5×5mm 或 6×6mm (48-pin)
+
+## 5. 功耗模式
+- Active (WiFi TX, 20dBm)：电流（典型）=~240 mA
+- Modem-sleep：电流（典型）=~20 mA
+- Light-sleep：电流（典型）=~0.8 mA
+- Deep-sleep：电流（典型）=~10 µA
@@ -0,0 +1,190 @@
+# LVGL Reference Index
+> **类别：reference** | **芯片：cross-platform** | **主题：LVGL 图形库参考索引**
+> Top-level index for all LVGL version references, migration guides, and ESP32 compatibility notes.
+> Structured for AI agent consumption during ESP32 GUI development tasks.
+
+---
+
+## Directory Structure
+
+```
+references/lvgl/
+├── README.md                          # This file - top-level index
+├── migration/
+│   ├── v8-to-v9.md                    # Definitive v8 -> v9 migration guide
+│   └── version-matrix.md             # Feature/widget/API matrix across versions
+├── v8.2/                              # v8.2 API reference (if populated)
+├── v8.3/                              # v8.3 API reference (if populated)
+├── v8.4/                              # v8.4 API reference (if populated)
+├── v9.0/                              # v9.0 API reference (if populated)
+├── v9.1/                              # v9.1 API reference (if populated)
+├── v9.2/                              # v9.2 API reference (if populated)
+├── v9.3/                              # v9.3 API reference (if populated)
+├── v9.4/                              # v9.4 API reference (if populated)
+└── v9.5/                              # v9.5 API reference (if populated)
+```
+
+---
+
+## Version Selection Guide
+
+### Quick Decision Tree
+
+```
+Starting a new ESP32 GUI project?
+├── ESP32-S3 or ESP32-P4 (with PSRAM)?
+│   └── Use v9.5 (latest stable, full feature set)
+├── ESP32 original with PSRAM?
+│   └── Use v9.5 (good fit with PSRAM for buffers)
+├── ESP32-C3/C6/H2 (no PSRAM)?
+│   └── Use v8.4 (lower memory footprint)
+├── Need maximum community examples/tutorials?
+│   └── Start with v8.3 (most content available)
+└── Need GPU acceleration or vector graphics?
+    └── Use v9.5 (only option with draw pipeline + ThorVG)
+
+Migrating an existing project?
+├── Currently on v7?
+│   └── Migrate directly to v9.5 (skip v8)
+├── Currently on v8 and working fine?
+│   ├── Need v9 features? → Migrate to v9.5
+│   └── No new needs? → Stay on v8.4
+└── Currently on v9.0-v9.4?
+    └── Upgrade to v9.5 (backward compatible within v9)
+```
+
+---
+
+## Version Timeline
+
+```
+2020    2021        2022        2023        2024                    2025
+ |       |           |           |           |                       |
+ v7.0   v8.0       v8.3        v8.3.9      v9.0  v9.1  v9.2       v9.5
+ May    Jun         Jul         Aug         Jan   Mar   Aug        Feb
+        |                                   |                       |
+        v7.9                                v8.4                   v9.4
+        Jan                                 Mar                    Oct
+                                                  |
+                                                 v9.3
+                                                 Jun
+```
+
+### Major Version Eras
+
+- v7 era：Versions=7.0 - 7.9, Period=May 2020 - Jan 2021, Key Characteristics=Legacy style system, basic layout
+- v8 era：Versions=8.0 - 8.4, Period=Jun 2021 - Mar 2024, Key Characteristics=Flexbox/grid, CSS-like styles, mature ecosystem
+- v9 era：Versions=9.0 - 9.5+, Period=Jan 2024 - present, Key Characteristics=New driver API, draw pipeline, observer, built-in drivers
+
+---
+
+## Migration Guides
+
+- v8.x to v9.x：Document=[migration/v8-to-v9.md](migration/v8-to-v9.md), Effort Level=High
+- Version comparison：Document=[migration/version-matrix.md](migration/version-matrix.md), Effort Level=Reference
+
+### Migration Effort Summary
+
+- v8.3：To=v8.4, Breaking Changes=None, Compatibility Layer=N/A, Estimated Effort=Trivial (recompile)
+- v8.x：To=v9.0+, Breaking Changes=Major, Compatibility Layer=`lv_api_map_v8.h` (partial), Estimated Effort=2-5 days typical
+- v9.x：To=v9.y, Breaking Changes=None, Compatibility Layer=N/A, Estimated Effort=Trivial (recompile)
+- v7.x：To=v9.x, Breaking Changes=Extreme, Compatibility Layer=`lv_api_map_v7.h` + `v8.h`, Estimated Effort=5-10 days typical
+
+---
+
+## ESP32 Compatibility Summary
+
+### Recommended LVGL Version by ESP32 Chip
+
+- ESP32 (original)：PSRAM=None, Recommended LVGL=v8.4, Rationale=RAM too limited for v9
+- ESP32 (original)：PSRAM=4MB+, Recommended LVGL=v9.5, Rationale=PSRAM compensates for v9 RAM usage
+- ESP32-S2：PSRAM=None, Recommended LVGL=v8.4, Rationale=320KB RAM, too tight for v9
+- ESP32-S2：PSRAM=2MB+, Recommended LVGL=v9.5, Rationale=Viable with PSRAM
+- ESP32-S3：PSRAM=2-8MB, Recommended LVGL=v9.5, Rationale=Ideal target for v9
+- ESP32-C3：PSRAM=None, Recommended LVGL=v8.4, Rationale=No PSRAM, 400KB RAM
+- ESP32-C5：PSRAM=None, Recommended LVGL=v8.4, Rationale=Limited RAM, no PSRAM
+- ESP32-C6：PSRAM=None, Recommended LVGL=v8.4 or v9.5, Rationale=512KB RAM, monitor usage
+- ESP32-H2：PSRAM=None, Recommended LVGL=v8.4, Rationale=320KB RAM, BLE-focused chip
+- ESP32-P4：PSRAM=Up to 32MB, Recommended LVGL=v9.5, Rationale=Best ESP32 for GUI workloads
+
+### ESP-IDF Version Compatibility
+
+- v8.3/v8.4：ESP-IDF 4.4=Yes, ESP-IDF 5.0=Yes, ESP-IDF 5.1=Yes, ESP-IDF 5.2+=Yes
+- v9.0-v9.2：ESP-IDF 4.4=Yes, ESP-IDF 5.0=Yes, ESP-IDF 5.1=Yes, ESP-IDF 5.2+=Yes
+- v9.3-v9.5：ESP-IDF 4.4=No, ESP-IDF 5.0=Yes, ESP-IDF 5.1=Yes, ESP-IDF 5.2+=Yes
+
+### Integration Methods for ESP32
+
+1. **ESP Component Registry** (recommended for ESP-IDF): Add `lvgl/lvgl` to `idf_component.yml`
+2. **esp_lvgl_port**: Official ESP-IDF LVGL port with driver integration (supports v8 and v9)
+3. **PlatformIO**: Add to `platformio.ini` lib_deps
+4. **Arduino Library Manager**: Search "lvgl" in Library Manager
+5. **Git submodule**: Manual integration into project
+
+---
+
+## Version Folder Contents
+
+Each version folder (`v8.2/`, `v8.3/`, etc.) is intended to contain:
+
+- API reference summaries for that specific version
+- Widget documentation snapshots
+- Configuration templates (`lv_conf.h` defaults)
+- ESP32-specific notes and tested configurations
+- Known issues and workarounds
+
+### Currently Populated
+
+- `v8.2/`：Status=Empty, Contents=Placeholder
+- `v8.3/`：Status=Empty, Contents=Placeholder
+- `v8.4/`：Status=Empty, Contents=Placeholder
+- `v9.0/`：Status=Empty, Contents=Placeholder
+- `v9.1/`：Status=Empty, Contents=Placeholder
+- `v9.2/`：Status=Empty, Contents=Placeholder
+- `v9.3/`：Status=Empty, Contents=Placeholder
+- `v9.4/`：Status=Empty, Contents=Placeholder
+- `v9.5/`：Status=Empty, Contents=Placeholder
+
+---
+
+## Key Differences Between Major Versions (Summary)
+
+### v8 Highlights
+
+- Flexbox and grid layout support
+- CSS-like cascading style system with local styles per widget
+- `lv_disp_drv_t` / `lv_indev_drv_t` struct-based driver model
+- `lv_meter` widget for gauge displays
+- `lv_msg` messaging system
+- `lv_coord_t` coordinate type
+- Buffer sizes in pixels
+- Abbreviated API names (`btn`, `img`, `disp`, `scr`)
+
+### v9 Highlights
+
+- New display/indev API: opaque types with setter functions
+- Draw pipeline architecture (task-based, GPU-extensible)
+- Parallel rendering support
+- Observer pattern replacing `lv_msg`
+- Built-in drivers (SDL, Linux FB, TFT_eSPI, ST7789, ILI9341)
+- `lv_scale` widget (replaces `lv_meter` ticks)
+- ThorVG vector graphics on Canvas
+- Full-word API names (`button`, `image`, `display`, `screen`)
+- `lv_color_t` always RGB888 internally
+- Buffer sizes in bytes
+- Kconfig full support
+- Built-in OS abstraction (pthread, FreeRTOS)
+- Runtime color format adjustment
+- `lv_coord_t` removed (use `int32_t`)
+
+---
+
+## External Resources
+
+- LVGL Official Docs (latest)：URL=https://docs.lvgl.io/master/, Description=v9.6 development docs
+- LVGL v8.3 Docs：URL=https://docs.lvgl.io/8.3/, Description=Last major v8 docs
+- LVGL GitHub：URL=https://github.com/lvgl/lvgl, Description=Source code and releases
+- LVGL Forum：URL=https://forum.lvgl.io/, Description=Community support
+- ESP Component Registry：URL=https://components.espressif.com/components/lvgl/lvgl, Description=ESP-IDF integration
+- lv_api_map_v8.h：URL=https://github.com/lvgl/lvgl/blob/master/src/lv_api_map_v8.h, Description=v8 compatibility macros
+- ESP32 LVGL Tips：URL=https://docs.lvgl.io/master/integration/chip_vendors/espressif/tips_and_tricks.html, Description=ESP32-specific optimization
@@ -0,0 +1,74 @@
+# 型号混淆与易错坑点
+> **类别：trap** | **芯片：cross-platform** | **主题：型号混淆与易错坑点**
+> 看错一个字母/数字，整板功能异常
+
+## 型号混淆
+
+- ESP32-WROOM-32D ≠ ESP32-S3：区别=32D无原生USB需外挂串口芯片才能烧录，S3有原生USB直连Type-C, 后果=32D方案忘加CH340→变砖
+- INA226 ≠ INA228：区别=引脚不同，寄存器不同, 后果=接线全错，I2C读数全乱
+- IRLZ44N ≠ IRFZ44N：区别=逻辑电平vs标准，驱动电压不同, 后果=3.3V驱动不开IRFZ44N
+- SH1106 ≠ SSD1315 ≠ SSD1306：区别=初始化序列不同, 后果=屏不亮或花屏
+- 2Ω ≠ 10Ω：区别=数量级不同, 后果=负载电流差5倍，测量全错
+- 10kΩ ≠ 100kΩ：区别=差一个零, 后果=分压比差10倍
+
+## 封装极性
+
+- SMA二极管：pin1=阴极（白线标记端），pin2=阳极
+- LED 0805：pin1=阳极，pin2=阴极
+- 丝印必须标位号，不标焊接时找不到
+
+## 电路常见错误
+
+- **32D方案必须加USB转串口芯片**——WROOM-32D无原生USB，Type-C只能供电不能烧录，不加CH340/CH9102=变砖
+- **GPIO12上拉→Flash变砖**——ESP32-32D的GPIO12 strapping决定VDD_SDIO，上拉10kΩ导致1.8V模式Flash不工作
+- QFN中心焊盘必须接GND，禁NC——散热+电气完整性
+- 面板交互件(按钮/LED)不能板载——PCB在壳内用户无法触及，必须外接连座
+- 网表连接合法 ≠ 功能正确——必须带功能说明审查
+- Type-C CC脚各5.1kΩ下拉到GND
+- TTP223触摸IC禁下拉
+- 过孔需指定网络（GND），否则"连接微散网络"
+
+## DeepSeek审查误报记录
+
+- "MOSFET驱动不足致命"——实际3.3V直驱AO3400A完全够用，Vgs=3.3V >> Vth≈0.6V
+- "删R9和C5"——R9/C5是ESP32 EN脚电路不是ME6211 CE，不能删
+- 审查结果要逐条判断，不能盲信
+
+## 屏幕电压与板载电源轨匹配（2026-07-12）
+
+- 5V版ST7735用在3.3V板子上：误区="接VBUS就行", 正解=GBC 5.0电池供电，3.3V LDO出给C3，**板上压根没5V轨**
+
+**三种处理方式：**
+1. 加Boost升压（多一颗芯片多一份耗电，得不偿失）
+2. 找3.3V原生版本模组（淘宝有的是，推荐）
+3. 换C6+SPI彩屏方案（另开产品线）
+
+**铁律：选屏幕先看板子上有没有对应电压轨，别想当然"接一下就行"。** 电池供电3.3V板子=没有5V，没有就是没有，不是接线能解决的。
+
+**补充：** 同一型号屏幕模组（如ST7735）有3.3V和5V两个版本，采购时务必确认电压版本。
+
+---
+*2026-07-12 | 屏幕电压踩坑*
+
+## 开漏输出引脚必须固件加INPUT_PULLUP（2026-07-13）
+
+TP4056的CHRG（充电状态）和STDBY（充满指示）是**开漏输出**，芯片内部没有上拉，外部也没接上拉电阻。ESP32 GPIO配置为输入时默认高阻，引脚浮空→状态不确定→可能反复跳变→增加功耗。
+
+**固件必须加：**
+```cpp
+pinMode(5, INPUT_PULLUP);  // CHRG
+pinMode(6, INPUT_PULLUP);  // STDBY
+```
+
+**通用规则：** 任何开漏输出的信号连到MCU GPIO，要么硬件加上拉，要么固件启用内部上拉。不处理=浮空=不可靠+可能耗电。
+
+## 硬件耐压≠软件拒测阈值，文档必须区分（2026-07-13）
+
+GBC V5.0方案文档电压范围写法有歧义：
+- **0~6V** — INA226硬件耐压上限，超过可能烧芯片
+- **2.0V（HIGH_VOLT_V）** — 固件软件拒测阈值，超过只拒绝测量但不损坏
+
+用户看到"0~6V"以为能测6V电池，实际固件2.0V就拒测了。**文档必须写清"硬件耐压"和"软件限制"是两个不同概念，分别标注。**
+
+---
+*2026-07-13 | 开漏上拉+文档歧义踩坑*
@@ -0,0 +1,447 @@
+# Protocol Quick Reference
+
+> **类别：reference** | **主题：通信协议快速参考** | **信源：** 多平台汇总
+
+## Table of Contents
+
+- [I2C (Inter-Integrated Circuit)](#i2c-inter-integrated-circuit)
+  - [Overview](#overview)
+  - [Signal Lines](#signal-lines)
+  - [Speed Modes](#speed-modes)
+  - [Pull-up Requirements](#pull-up-requirements)
+  - [Common I2C Addresses (Collision Detection)](#common-i2c-addresses-collision-detection)
+  - [Platform Notes](#platform-notes)
+- [SPI (Serial Peripheral Interface)](#spi-serial-peripheral-interface)
+  - [Overview](#overview)
+  - [Signal Lines](#signal-lines)
+  - [Speed](#speed)
+  - [Clock Modes](#clock-modes)
+  - [Pull-up Requirements](#pull-up-requirements)
+  - [Platform Notes](#platform-notes)
+- [UART (Universal Asynchronous Receiver/Transmitter)](#uart-universal-asynchronous-receivertransmitter)
+  - [Overview](#overview)
+  - [Signal Lines](#signal-lines)
+  - [Common Baud Rates](#common-baud-rates)
+  - [Frame Format](#frame-format)
+  - [Voltage Levels](#voltage-levels)
+  - [Level Shifting](#level-shifting)
+  - [Platform Notes](#platform-notes)
+- [PWM (Pulse Width Modulation)](#pwm-pulse-width-modulation)
+  - [Overview](#overview)
+  - [Key Parameters](#key-parameters)
+  - [Frequency by Application](#frequency-by-application)
+  - [Servo Control Specifics](#servo-control-specifics)
+  - [Platform Notes](#platform-notes)
+- [1-Wire](#1-wire)
+  - [Overview](#overview)
+  - [Signal Line](#signal-line)
+  - [Pull-up Requirement](#pull-up-requirement)
+  - [Common 1-Wire Devices](#common-1-wire-devices)
+  - [Platform Notes](#platform-notes)
+- [CAN (Controller Area Network)](#can-controller-area-network)
+  - [Overview](#overview)
+  - [Signal Lines](#signal-lines)
+  - [Common Transceivers](#common-transceivers)
+  - [Speed and Termination](#speed-and-termination)
+  - [Platform Notes](#platform-notes)
+- [ADC (Analog-to-Digital Converter)](#adc-analog-to-digital-converter)
+  - [Overview](#overview)
+  - [Key Parameters](#key-parameters)
+  - [Platform Comparison](#platform-comparison)
+  - [ESP32 ADC Attenuation](#esp32-adc-attenuation)
+  - [External ADC Options](#external-adc-options)
+  - [Input Protection](#input-protection)
+  - [Platform Notes](#platform-notes)
+
+---
+
+## I2C (Inter-Integrated Circuit)
+
+### Overview
+
+- Two-wire synchronous serial bus
+- Multi-device: multiple slaves on same bus
+- Addressable: 7-bit (128) or 10-bit (1024) addresses
+- Open-drain: requires external pull-up resistors
+- Half-duplex: bidirectional on single data line
+
+### Signal Lines
+
+- SDA：Direction=Bidirectional, Type=Open-drain, Description=Serial data
+- SCL：Direction=Master→Slave, Type=Open-drain, Description=Serial clock
+
+### Speed Modes
+
+- Standard：Speed=100 kHz, Notes=Universal compatibility
+- Fast：Speed=400 kHz, Notes=Most common for sensors
+- Fast Plus：Speed=1 MHz, Notes=Requires stronger pull-ups
+- High Speed：Speed=3.4 MHz, Notes=Rarely used in hobby projects
+
+### Pull-up Requirements
+
+**REQUIRED** on both SDA and SCL lines.
+
+- Standard/Fast：Recommended Value=4.7kΩ, Notes=Most common choice
+- Fast Plus：Recommended Value=2.2kΩ, Notes=Stronger pull needed
+- High Speed / Long wires：Recommended Value=1kΩ, Notes=Compensates for capacitance
+
+**Calculation Formula:**
+```
+R = (VCC - VOL) / IOL
+R = (3.3V - 0.4V) / 3mA = 967Ω minimum
+```
+
+**Consequences of Wrong Value:**
+- **Too high (>10kΩ):** Slow rise times, communication errors, fails at higher speeds
+- **Too low (<1kΩ):** Excessive current draw, devices cannot pull line LOW, bus contention
+
+### Common I2C Addresses (Collision Detection)
+
+- 0x20-0x27：Device(s)=MCP23017 GPIO expander, PCF8574
+- 0x27, 0x3F：Device(s)=PCF8574 LCD backpack
+- 0x29：Device(s)=VL53L0X ToF distance sensor
+- 0x39：Device(s)=APDS9960 gesture/color sensor
+- 0x3C, 0x3D：Device(s)=SSD1306 OLED display
+- 0x40：Device(s)=INA219 current sensor, PCA9685 PWM
+- 0x48-0x4B：Device(s)=ADS1115/ADS1015 ADC
+- 0x50-0x57：Device(s)=AT24C EEPROM
+- 0x5A：Device(s)=MLX90614 IR thermometer
+- 0x60：Device(s)=Si5351 clock generator
+- 0x68：Device(s)=DS3231 RTC, MPU6050 IMU
+- 0x76, 0x77：Device(s)=BME280/BMP280 sensor
+
+**Note:** Many devices have address pins (A0, A1, A2) to resolve conflicts.
+
+### Platform Notes
+
+**Raspberry Pi:**
+- I2C1 (GPIO2/3) is the primary user-accessible bus
+- I2C0 (GPIO0/1) is **reserved** for HAT EEPROM detection — do not use
+- Enable with `dtparam=i2c_arm=on` in config.txt
+- Pi 4/5 have additional I2C buses via dtoverlay
+
+**ESP32:**
+- Any GPIO pair works via GPIO matrix — no fixed pins
+- Convention: GPIO21 (SDA), GPIO22 (SCL)
+- Do NOT use input-only pins (GPIO34-39) — they cannot drive SDA
+
+---
+
+## SPI (Serial Peripheral Interface)
+
+### Overview
+
+- Four-wire synchronous serial bus
+- Full-duplex: simultaneous send and receive
+- One chip select (CS) per slave device
+- No addressing: CS line selects device
+- Push-pull drivers: no pull-ups required on data/clock
+
+### Signal Lines
+
+- MOSI：Direction=Master→Slave, Description=Master Out, Slave In
+- MISO：Direction=Slave→Master, Description=Master In, Slave Out
+- SCLK：Direction=Master→Slave, Description=Serial clock
+- CS/SS：Direction=Master→Slave, Description=Chip Select (active LOW)
+
+### Speed
+
+- Typical: 1-40 MHz (device dependent)
+- Check slave device datasheet for maximum
+- Longer wires = lower reliable speed
+
+### Clock Modes
+
+- 0：CPOL=0, CPHA=0, Clock Idle=LOW, Data Sampled On=Rising edge
+- 1：CPOL=0, CPHA=1, Clock Idle=LOW, Data Sampled On=Falling edge
+- 2：CPOL=1, CPHA=0, Clock Idle=HIGH, Data Sampled On=Falling edge
+- 3：CPOL=1, CPHA=1, Clock Idle=HIGH, Data Sampled On=Rising edge
+
+**Note:** Mode 0 is most common. Check device datasheet.
+
+### Pull-up Requirements
+
+- **MOSI, MISO, SCLK:** Generally NOT required (push-pull drivers)
+- **CS lines:** 10kΩ pull-up recommended to prevent floating during boot/reset
+
+### Platform Notes
+
+**Raspberry Pi:**
+- SPI0 (GPIO7-11) is primary bus — CE0 (GPIO8), CE1 (GPIO7)
+- SPI1 (GPIO16-21) available but **conflicts with PCM/I2S audio**
+- Enable with `dtparam=spi=on` in config.txt
+
+**ESP32:**
+- VSPI (SPI3): GPIO23 (MOSI), GPIO19 (MISO), GPIO18 (SCLK), GPIO5 (CS) — **recommended**
+- HSPI (SPI2): GPIO13 (MOSI), GPIO12 (MISO), GPIO14 (SCLK), GPIO15 (CS)
+- **WARNING:** HSPI pins overlap strapping pins! GPIO12 can brick the module if HIGH at boot.
+- Any GPIO can be used via GPIO matrix (except input-only pins for outputs)
+
+---
+
+## UART (Universal Asynchronous Receiver/Transmitter)
+
+### Overview
+
+- Two-wire asynchronous serial communication
+- Point-to-point: one transmitter, one receiver per pair
+- No clock line: baud rate must match on both ends
+- Simple: widely supported, easy to debug
+
+### Signal Lines
+
+- TX：Direction=Output, Description=Transmit data (connect to peer's RX)
+- RX：Direction=Input, Description=Receive data (connect to peer's TX)
+- RTS：Direction=Output, Description=Request to Send (optional flow control)
+- CTS：Direction=Input, Description=Clear to Send (optional flow control)
+
+**Critical:** TX connects to RX, RX connects to TX (crossover).
+
+### Common Baud Rates
+
+- 9600：Use Case=Legacy devices, GPS modules
+- 19200：Use Case=Some sensors
+- 38400：Use Case=Bluetooth modules
+- 57600：Use Case=Faster sensors
+- 115200：Use Case=Most common default
+- 230400：Use Case=High-speed peripherals
+- 460800：Use Case=ESP32 flash programming
+- 921600：Use Case=Fast data transfer
+
+### Frame Format
+
+Standard: **8N1** (8 data bits, No parity, 1 stop bit)
+
+Other formats exist (7E1, 8E1, etc.) but 8N1 covers 95%+ of use cases.
+
+### Voltage Levels
+
+- TTL 3.3V：Voltage=0V / 3.3V, Common Devices=RPi, ESP32, modern MCUs
+- TTL 5V：Voltage=0V / 5V, Common Devices=Arduino, many modules
+- RS-232：Voltage=±12V, Common Devices=PC serial ports
+
+**CRITICAL:** RS-232 levels (±12V) will **DESTROY** 3.3V GPIO instantly. Use MAX232 or similar transceiver.
+
+### Level Shifting
+
+- 5V TX → 3.3V RX: Use voltage divider (1kΩ + 2kΩ) or level shifter
+- 3.3V TX → 5V RX: Often works directly (check VIH threshold)
+- Always use bidirectional level shifter for RTS/CTS
+
+### Platform Notes
+
+**Raspberry Pi:**
+- UART0 (GPIO14/15) is primary serial port
+- **Conflicts with Bluetooth** on Pi 3/4/Zero2W — use `dtoverlay=disable-bt` or `dtoverlay=miniuart-bt`
+- Pi 4/5 have additional UARTs via dtoverlay
+
+**ESP32:**
+- UART0 (GPIO1/3) is **USB serial debug** — avoid for peripherals
+- UART1 and UART2 are freely available
+- Any GPIO can be assigned via GPIO matrix
+
+---
+
+## PWM (Pulse Width Modulation)
+
+### Overview
+
+- Digital approximation of analog voltage
+- Square wave at fixed frequency
+- Duty cycle controls average voltage
+- Used for: LED dimming, motor speed, servo position, audio
+
+### Key Parameters
+
+- Frequency：Description=Pulses per second, Typical Range=50 Hz - 100 kHz
+- Duty Cycle：Description=HIGH time percentage, Typical Range=0-100%
+- Resolution：Description=Steps of duty control, Typical Range=8-bit (256) to 16-bit (65536)
+
+**Average Voltage:** Vavg = VCC × (Duty Cycle / 100)
+
+### Frequency by Application
+
+- LED dimming：Frequency=500-5000 Hz, Reason=>500Hz avoids visible flicker
+- Servo control：Frequency=50 Hz, Reason=Standard RC servo protocol (20ms period)
+- Motor control：Frequency=1-20 kHz, Reason=Higher = less audible whine
+- Audio generation：Frequency=20-100 kHz, Reason=Above audible range
+- Switching PSU：Frequency=50-500 kHz, Reason=Efficiency vs. noise tradeoff
+
+### Servo Control Specifics
+
+- Period: 20ms (50 Hz)
+- Pulse width: 1ms (0°) to 2ms (180°)
+- Neutral: 1.5ms (90°)
+- Duty cycle: 5% (1ms) to 10% (2ms) at 50Hz
+
+### Platform Notes
+
+**Raspberry Pi:**
+- **2 hardware PWM channels** only
+- PWM0: GPIO12 (preferred) or GPIO18 (conflicts with audio)
+- PWM1: GPIO13 (preferred) or GPIO19 (conflicts with audio)
+- Software PWM available on any pin but less precise (jitter)
+- Enable with `dtoverlay=pwm` or `dtoverlay=pwm-2chan`
+
+**ESP32:**
+- **LEDC peripheral:** 16 channels of hardware PWM
+- Can output on **any output-capable GPIO**
+- Cannot use input-only pins (GPIO34-39)
+- Configurable resolution (1-16 bit) and frequency
+- Motor Control PWM (MCPWM) for advanced motor control
+
+---
+
+## 1-Wire
+
+### Overview
+
+- Single-wire bidirectional bus
+- Parasitic power option (power over data line)
+- Each device has unique 64-bit ROM ID
+- Multiple devices on same bus (addressed by ROM)
+- Open-drain: requires pull-up resistor
+
+### Signal Line
+
+- DQ：Type=Bidirectional, Open-drain, Description=Data and (optionally) power
+
+### Pull-up Requirement
+
+**REQUIRED:** 4.7kΩ to VCC (3.3V or 5V depending on devices)
+
+- Stronger pull-up (2.2kΩ-1kΩ) for long cables or many devices
+- Parasitic power mode may need stronger pull-up during temperature conversion
+
+### Common 1-Wire Devices
+
+- DS18B20：Function=Temperature sensor, Notes=Most popular 1-Wire device
+- DS18S20：Function=Temperature sensor, Notes=Older, 9-bit only
+- DS2401：Function=Serial number, Notes=Silicon serial number
+- DS2413：Function=GPIO, Notes=2-channel I/O
+- iButton：Function=Various, Notes=Key fobs, access control
+
+### Platform Notes
+
+**Raspberry Pi:**
+- Default pin: GPIO4
+- Enable with `dtoverlay=w1-gpio`
+- Change pin with `dtoverlay=w1-gpio,gpiopin=N`
+- Kernel driver handles protocol automatically
+
+**ESP32:**
+- Any GPIO can be used via OneWire library
+- GPIO4 is common convention
+- Requires software library (no hardware peripheral)
+
+---
+
+## CAN (Controller Area Network)
+
+### Overview
+
+- Differential two-wire bus (noise immune)
+- Multi-master: any node can initiate
+- Message-based: no addresses, messages have IDs
+- Priority: lower message ID = higher priority
+- Error detection: CRC, ACK, bit stuffing
+- Common in: automotive, industrial, robotics
+
+### Signal Lines
+
+- CAN_H：Description=CAN High (dominant = 3.5V)
+- CAN_L：Description=CAN Low (dominant = 1.5V)
+
+**Note:** Requires transceiver chip (GPIO cannot drive CAN directly)
+
+### Common Transceivers
+
+- MCP2551：Voltage=5V, Notes=Classic, widely available
+- SN65HVD230：Voltage=3.3V, Notes=Good for ESP32/RPi
+- TJA1050：Voltage=5V, Notes=Automotive grade
+
+### Speed and Termination
+
+- 125 kbps：Max Bus Length=500m, Use Case=Long distance
+- 250 kbps：Max Bus Length=250m, Use Case=General purpose
+- 500 kbps：Max Bus Length=100m, Use Case=Automotive
+- 1 Mbps：Max Bus Length=40m, Use Case=High speed
+
+**Termination:** 120Ω resistor at **each end** of bus (two total). Many transceiver modules have onboard termination jumper.
+
+### Platform Notes
+
+**Raspberry Pi:**
+- No built-in CAN controller
+- Requires external MCP2515 (SPI-to-CAN) + transceiver
+- Enable with `dtoverlay=mcp2515-can0,oscillator=8000000,interrupt=25`
+- Uses SocketCAN interface
+
+**ESP32:**
+- Built-in TWAI controller (CAN 2.0B compatible)
+- Only needs external transceiver (e.g., SN65HVD230)
+- Common pins: GPIO4 (TX), GPIO5 (RX) — but any GPIO works
+- ESP-IDF and Arduino libraries available
+
+---
+
+## ADC (Analog-to-Digital Converter)
+
+### Overview
+
+- Converts continuous analog voltage to discrete digital value
+- Key parameters: resolution, reference voltage, sample rate
+- Input must not exceed reference voltage
+
+### Key Parameters
+
+- Resolution：Description=Bits of precision (10-bit = 1024 steps, 12-bit = 4096)
+- Reference：Description=Full-scale input voltage (typically VCC or internal ref)
+- Sample Rate：Description=Conversions per second (SPS)
+- Input Range：Description=Allowable input voltage (0 to Vref typically)
+
+### Platform Comparison
+
+- Built-in ADC：Raspberry Pi=**No**, ESP32=Yes (2 ADCs)
+- Resolution：Raspberry Pi=N/A, ESP32=12-bit (4096 levels)
+- Channels：Raspberry Pi=N/A, ESP32=ADC1: 8ch, ADC2: 10ch
+- Reference：Raspberry Pi=N/A, ESP32=0-3.3V (with attenuation)
+- Sample Rate：Raspberry Pi=N/A, ESP32=Up to 2 MSPS
+- WiFi Conflict：Raspberry Pi=N/A, ESP32=**ADC2 unusable with WiFi**
+
+### ESP32 ADC Attenuation
+
+- 0 dB：Input Range=0-1.1V, Notes=Highest accuracy
+- 2.5 dB：Input Range=0-1.5V
+- 6 dB：Input Range=0-2.2V
+- 11 dB：Input Range=0-3.3V, Notes=Full range, lower accuracy
+
+### External ADC Options
+
+- ADS1115：Interface=I2C, Resolution=16-bit, Channels=4, Notes=Programmable gain, slow (860 SPS)
+- ADS1015：Interface=I2C, Resolution=12-bit, Channels=4, Notes=Faster than ADS1115 (3300 SPS)
+- MCP3008：Interface=SPI, Resolution=10-bit, Channels=8, Notes=Simple, cheap, fast
+- MCP3208：Interface=SPI, Resolution=12-bit, Channels=8, Notes=Higher resolution MCP3008
+- ADS7828：Interface=I2C, Resolution=12-bit, Channels=8, Notes=8-channel I2C option
+
+### Input Protection
+
+- **Never exceed reference voltage** — will damage ADC or give invalid readings
+- Use voltage divider for higher voltages
+- Add clamp diodes (Schottky to VCC and GND) for unknown inputs
+- Add RC filter (100Ω + 100nF) to reduce noise
+
+### Platform Notes
+
+**Raspberry Pi:**
+- No built-in ADC — external ADC required for any analog input
+- MCP3008 (SPI) or ADS1115 (I2C) are most common choices
+- Many HATs include ADC chips
+
+**ESP32:**
+- ADC1 (GPIO32-39): **Always available**, even with WiFi active
+- ADC2 (GPIO0-27 subset): **Unusable when WiFi or Bluetooth active**
+- Design rule: Use ADC1 pins for analog if project uses WiFi
+- Non-linear at extremes — calibration improves accuracy
+
+---
@@ -0,0 +1,90 @@
+# Waveshare Reference Documentation
+
+> **类别：reference** | **主题：Waveshare 微雪电子模块文档** | **信源：** [Waveshare Wiki](https://www.waveshare.com/wiki/)
+
+Reference documentation for Waveshare ESP32 display products. Used by AI agents for hardware configuration, driver selection, and firmware development.
+
+## Directory Structure
+
+```
+waveshare/
+├── README.md                          (this file)
+├── common/
+│   ├── display-controllers.md         Display controller ICs
+│   ├── touch-controllers.md           Touch controller ICs
+│   └── interfaces.md                  Hardware interfaces and wiring
+├── dev-boards/                        ESP32 development boards with integrated displays
+│   └── (board-specific reference files)
+└── lcd-boards/                        Standalone LCD/touch modules
+    └── (module-specific reference files)
+```
+
+## Common Reference Files
+
+### [Display Controllers](common/display-controllers.md)
+
+All display controller ICs used across Waveshare products:
+
+- ST7735S：Max Resolution=162x132, Interface=SPI, Typical Size=0.96"-1.8"
+- ST7789V：Max Resolution=320x240, Interface=SPI, Typical Size=1.3"-2.4"
+- ILI9341：Max Resolution=320x240, Interface=SPI, 8080, Typical Size=2.0"-3.2"
+- ILI9488：Max Resolution=480x320, Interface=SPI (18-bit), 8080, Typical Size=3.5"
+- GC9A01：Max Resolution=240x240, Interface=SPI, Typical Size=1.28" round
+- GC9503：Max Resolution=480x480, Interface=RGB + SPI init, Typical Size=3.4"-4.0"
+- ST7701S：Max Resolution=480x480, Interface=RGB + SPI init, Typical Size=4.0" round/square
+- EK9716B：Max Resolution=1024x600, Interface=RGB, Typical Size=7"+
+- JD9365：Max Resolution=800x1280, Interface=MIPI-DSI, Typical Size=7"+ portrait
+- NV3041A：Max Resolution=480x272, Interface=QSPI, 8080, Typical Size=compact
+
+Includes: register maps, init sequences, MADCTL rotation values, LVGL driver mapping, buffer strategies.
+
+### [Touch Controllers](common/touch-controllers.md)
+
+All touch controller ICs used across Waveshare products:
+
+- XPT2046：Type=Resistive, Interface=SPI, Address=N/A, Multi-Touch=No
+- CST816S：Type=Capacitive, Interface=I2C, Address=0x15, Multi-Touch=No
+- FT6336：Type=Capacitive, Interface=I2C, Address=0x38, Multi-Touch=2 points
+- GT911：Type=Capacitive, Interface=I2C, Address=0x5D/0x14, Multi-Touch=5 points
+- FT5x06：Type=Capacitive, Interface=I2C, Address=0x38, Multi-Touch=5 points
+- CST328：Type=Capacitive, Interface=I2C, Address=0x1A, Multi-Touch=5 points
+
+Includes: register maps, gesture IDs, calibration (XPT2046), interrupt behavior, LVGL integration patterns.
+
+### [Interfaces](common/interfaces.md)
+
+Hardware interface patterns and wiring:
+
+- SPI (4-wire)：Throughput=80 Mbps, Pins=5-6, Use Case=Small-mid displays
+- I2C：Throughput=3.2 Mbps, Pins=2, Use Case=Touch, small OLEDs
+- 8080 Parallel：Throughput=160 Mbps, Pins=12-13, Use Case=Mid displays
+- RGB Parallel：Throughput=400+ Mbps, Pins=22-32, Use Case=Large displays
+- QSPI：Throughput=320 Mbps, Pins=7-8, Use Case=Mid displays, fewer pins
+- MIPI-DSI：Throughput=4+ Gbps, Pins=10, Use Case=Very large displays
+
+Includes: voltage regulators, backlight control (PWM/GPIO), ESP32 variant support matrix, pin mapping patterns.
+
+## Quick Lookup
+
+### By Display Size
+
+- 0.96"-1.8"：Controller=ST7735S, Touch=None or CST816S, Interface=SPI, ESP32 Variant=Any
+- 1.28" round：Controller=GC9A01, Touch=CST816S, Interface=SPI, ESP32 Variant=Any
+- 1.3"-2.4"：Controller=ST7789V, Touch=None or CST816S, Interface=SPI, ESP32 Variant=Any
+- 2.4"-3.2"：Controller=ILI9341, Touch=XPT2046, Interface=SPI, ESP32 Variant=Any
+- 3.5"：Controller=ILI9488, Touch=XPT2046 or FT5x06, Interface=SPI/8080, ESP32 Variant=ESP32-S3 preferred
+- 4.0" square：Controller=GC9503/ST7701S, Touch=GT911, Interface=RGB, ESP32 Variant=ESP32-S3 (PSRAM)
+- 4.0" round：Controller=ST7701S, Touch=CST816S/GT911, Interface=RGB, ESP32 Variant=ESP32-S3 (PSRAM)
+- 7.0"+：Controller=EK9716B, Touch=GT911, Interface=RGB, ESP32 Variant=ESP32-S3 (Octal PSRAM)
+- 7.0"+ MIPI：Controller=JD9365, Touch=GT911, Interface=MIPI-DSI, ESP32 Variant=ESP32-P4
+
+### By ESP32 Variant
+
+- ESP32：Supported Interfaces=SPI, Max Practical Display=320x240 (SPI)
+- ESP32-S2：Supported Interfaces=SPI, 8080, Max Practical Display=480x320 (8080)
+- ESP32-S3：Supported Interfaces=SPI, 8080, RGB, QSPI, Max Practical Display=1024x600 (RGB)
+- ESP32-C3：Supported Interfaces=SPI, Max Practical Display=240x240 (SPI)
+- ESP32-C6：Supported Interfaces=SPI, Max Practical Display=240x240 (SPI)
+- ESP32-P4：Supported Interfaces=SPI, 8080, RGB, QSPI, MIPI-DSI, Max Practical Display=800x1280 (MIPI-DSI)
+
+---
@@ -0,0 +1,359 @@
+# Electrical Constraints Reference
+
+> **类别：reference** | **主题：电气约束通用规范** | **信源：** 多平台汇总
+
+## Table of Contents
+
+- [Platform Comparison Summary](#platform-comparison-summary)
+- [Raspberry Pi Electrical Details](#raspberry-pi-electrical-details)
+  - [Voltage Levels](#voltage-levels)
+  - [Current Limits](#current-limits)
+  - [Power Rails](#power-rails)
+  - [Internal Pull Resistors](#internal-pull-resistors)
+  - [Safe Driving Patterns](#safe-driving-patterns)
+- [ESP32 Electrical Details](#esp32-electrical-details)
+  - [Voltage Levels](#voltage-levels)
+  - [Current Limits](#current-limits)
+  - [Power Consumption](#power-consumption)
+  - [Internal Pull Resistors](#internal-pull-resistors)
+  - [Drive Strength Configuration](#drive-strength-configuration)
+- [Pull-up and Pull-down Resistors](#pull-up-and-pull-down-resistors)
+  - [When Required](#when-required)
+  - [Calculation Formula](#calculation-formula)
+  - [Strength Guidelines](#strength-guidelines)
+  - [Consequences of Wrong Value](#consequences-of-wrong-value)
+- [Level Shifting](#level-shifting)
+  - [When Required](#when-required)
+  - [Method 1: Voltage Divider (5V → 3.3V, Unidirectional)](#method-1-voltage-divider-5v--33v-unidirectional)
+  - [Method 2: N-Channel MOSFET (Bidirectional)](#method-2-n-channel-mosfet-bidirectional)
+  - [Method 3: Dedicated Level Shifter ICs](#method-3-dedicated-level-shifter-ics)
+  - [Method 4: Direct Connection (3.3V → 5V Input)](#method-4-direct-connection-33v--5v-input)
+- [Common Mistakes and Warnings](#common-mistakes-and-warnings)
+  - [NEVER Do This](#never-do-this)
+  - [ALWAYS Do This](#always-do-this)
+- [Quick Reference Card](#quick-reference-card)
+  - [Formulas](#formulas)
+  - [Quick Values](#quick-values)
+  - [Current Limits Summary](#current-limits-summary)
+  - [Voltage Summary](#voltage-summary)
+  - [Common Pin Restrictions](#common-pin-restrictions)
+
+---
+
+## Platform Comparison Summary
+
+- Logic voltage：Raspberry Pi=3.3V, ESP32=3.3V
+- Max per-pin current：Raspberry Pi=16mA source/sink, ESP32=40mA max (20mA recommended)
+- Aggregate GPIO current：Raspberry Pi=**50mA total**, ESP32=~1200mA total (chip limit)
+- 5V tolerant：Raspberry Pi=**NO**, ESP32=**NO**
+- Internal pull-up：Raspberry Pi=~50kΩ, ESP32=~45kΩ typical
+- Internal pull-down：Raspberry Pi=~50kΩ, ESP32=~45kΩ typical
+- Drive strength：Raspberry Pi=Fixed, ESP32=Configurable (5-40mA)
+- Input threshold (VIH)：Raspberry Pi=~1.8V, ESP32=~2.0V
+- Input threshold (VIL)：Raspberry Pi=~0.8V, ESP32=~0.8V
+
+---
+
+## Raspberry Pi Electrical Details
+
+### Voltage Levels
+
+- **All GPIO pins operate at 3.3V ONLY**
+- **5V on any GPIO pin WILL PERMANENTLY DAMAGE the SoC**
+- No built-in overvoltage protection
+- No built-in ESD protection (handle with care)
+
+### Current Limits
+
+- Per-pin source：16mA, Consequence of Exceeding=Voltage droop, pin damage
+- Per-pin sink：16mA, Consequence of Exceeding=Voltage rise, pin damage
+- **Total GPIO**：**50mA**, Consequence of Exceeding=Instability, crashes, permanent damage
+
+**Critical:** The 50mA limit is across ALL GPIO pins combined, not per-bank.
+
+### Power Rails
+
+- 3.3V：Source=Onboard regulator, Available Current=~50mA for peripherals, Notes=Shared with Pi's 3.3V needs
+- 5V：Source=USB/PSU direct, Available Current=1-2A minus Pi consumption, Notes=No regulation, direct pass-through
+- GND：Source=Common ground, Available Current=N/A, Notes=8 ground pins on header
+
+### Internal Pull Resistors
+
+- GPIO0-8：Default State=Pull-UP, Resistance=~50kΩ
+- GPIO9-27：Default State=Pull-DOWN, Resistance=~50kΩ
+
+**Note:** Internal pulls are too weak for I2C (need 4.7kΩ external).
+
+### Safe Driving Patterns
+
+- Single LED：Method=330Ω-1kΩ series resistor, Notes=3-10mA safe
+- Multiple LEDs：Method=Transistor driver, Notes=If total >50mA
+- Relay：Method=Transistor/MOSFET + flyback diode, Notes=Never direct from GPIO
+- Motor：Method=Motor driver IC (L298N, DRV8833), Notes=Never direct from GPIO
+- Buzzer (passive)：Method=Transistor driver, Notes=Inductive load
+- Buzzer (active)：Method=Direct if <16mA, Notes=Check current draw
+
+---
+
+## ESP32 Electrical Details
+
+### Voltage Levels
+
+- **All GPIO pins operate at 3.3V ONLY**
+- **5V on any GPIO pin WILL DAMAGE the chip**
+- No built-in overvoltage protection
+- Some ESD protection but don't rely on it
+
+### Current Limits
+
+- Per-pin max：40mA, Notes=Absolute maximum
+- Per-pin recommended：20mA, Notes=For reliability/longevity
+- Total chip：~1200mA, Notes=Includes WiFi, BT, CPU
+
+### Power Consumption
+
+- Active + WiFi TX：Current Draw=80-240mA, Notes=Peaks during transmission
+- Active + WiFi idle：Current Draw=20-68mA, Notes=Connected but not transmitting
+- Active, no radio：Current Draw=20-68mA, Notes=CPU running
+- Modem sleep：Current Draw=3-20mA, Notes=WiFi paused, CPU active
+- Light sleep：Current Draw=0.8mA, Notes=CPU paused, RTC running
+- Deep sleep：Current Draw=10-150µA, Notes=Only RTC + ULP available
+
+### Internal Pull Resistors
+
+- Standard GPIO：Pull-up=Yes, Pull-down=Yes, Resistance=~45kΩ
+- GPIO34-39：Pull-up=**NO**, Pull-down=**NO**, Resistance=N/A (input-only)
+
+**Note:** Internal pulls are too weak for I2C (need 4.7kΩ external).
+
+### Drive Strength Configuration
+
+- 5mA：Current=Weakest, Use Case=Low power, slow signals
+- 10mA：Current=Low, Use Case=General purpose
+- 20mA：Current=Default, Use Case=Most applications
+- 40mA：Current=Maximum, Use Case=Fast edges, heavy loads
+
+Higher drive strength = faster edges but more EMI/noise.
+
+---
+
+## Pull-up and Pull-down Resistors
+
+### When Required
+
+- I2C bus (SDA)：Pull Type=Pull-UP, Typical Value=**4.7kΩ**
+- I2C bus (SCL)：Pull Type=Pull-UP, Typical Value=**4.7kΩ**
+- 1-Wire bus (DQ)：Pull Type=Pull-UP, Typical Value=**4.7kΩ**
+- Button to GND：Pull Type=Pull-UP, Typical Value=10kΩ
+- Button to VCC：Pull Type=Pull-DOWN, Typical Value=10kΩ
+- SPI CS line：Pull Type=Pull-UP, Typical Value=10kΩ
+- Open-drain output：Pull Type=Pull-UP, Typical Value=1-10kΩ
+- UART RX (optional)：Pull Type=Pull-UP, Typical Value=10kΩ (noise immunity)
+- Reset line：Pull Type=Pull-UP, Typical Value=10kΩ
+
+### Calculation Formula
+
+```
+R = (VCC - VOL) / IOL
+
+Where:
+  VCC = Supply voltage (3.3V)
+  VOL = Output low voltage (~0.4V)
+  IOL = Required sink current (3mA for I2C)
+
+Example (I2C):
+  R = (3.3V - 0.4V) / 3mA = 967Ω minimum
+  Typical choice: 4.7kΩ (provides margin)
+```
+
+### Strength Guidelines
+
+- 1kΩ：Use Case=Long wires, high capacitance, fast I2C, Notes=Strong pull, higher current
+- 4.7kΩ：Use Case=Standard I2C, 1-Wire, general purpose, Notes=Most common choice
+- 10kΩ：Use Case=Buttons, CS lines, low-power, Notes=Standard digital pull
+- 47-100kΩ：Use Case=Wake-up inputs, ultra-low power, Notes=Very weak, slow rise time
+
+### Consequences of Wrong Value
+
+**Too high (weak pull):**
+- Slow signal rise times
+- Noise susceptibility
+- Communication errors at higher speeds
+- May not reach valid HIGH level
+
+**Too low (strong pull):**
+- Excessive current consumption
+- Device may not be able to pull line LOW
+- Wasted power in battery applications
+
+---
+
+## Level Shifting
+
+### When Required
+
+- 5V logic output → 3.3V GPIO input
+- 3.3V GPIO output → 5V input (if device doesn't recognize 3.3V as HIGH)
+- Bidirectional communication between 3.3V and 5V systems
+
+### Method 1: Voltage Divider (5V → 3.3V, Unidirectional)
+
+**Use for:** Slow signals (<100kHz), input direction only
+
+```
+5V Signal ──[1kΩ]──┬──> 3.3V GPIO Input
+                   │
+                 [2kΩ]
+                   │
+                  GND
+
+Output: 5V × (2kΩ / 3kΩ) = 3.33V
+```
+
+- Simple, cheap：Cons=Input direction only
+- 2 resistors：Cons=Slow (RC time constant)
+- No active components：Cons=Loads the signal
+
+### Method 2: N-Channel MOSFET (Bidirectional)
+
+**Use for:** I2C, 1-Wire, open-drain signals up to 400kHz
+
+```
+3.3V Side                              5V Side
+    │                                      │
+  [4.7kΩ]                              [4.7kΩ]
+    │                                      │
+    ├────────┬──────────────────┬──────────┤
+    │        │                  │          │
+   SDA    Source              Drain      SDA
+  (3.3V)     └───── BSS138 ─────┘       (5V)
+                      │
+                    Gate
+                      │
+                    3.3V
+```
+
+**Operation:**
+- Gate tied to LOW side voltage (3.3V)
+- When LOW side pulls down, MOSFET conducts, pulling HIGH side down
+- When HIGH side pulls down, body diode conducts, pulling LOW side down
+- Pull-ups restore HIGH state on both sides
+
+- MOSFET：Specification=BSS138, 2N7000 (through-hole)
+- Pull-ups：Specification=4.7kΩ on each side
+- Voltage：Specification=3.3V on gate, low side; 5V on high side
+
+### Method 3: Dedicated Level Shifter ICs
+
+- TXB0104：Channels=4, Type=Auto-direction, Speed=100 Mbps, I2C Safe?=**NO**
+- TXB0108：Channels=8, Type=Auto-direction, Speed=100 Mbps, I2C Safe?=**NO**
+- PCA9306：Channels=2, Type=I2C-specific, Speed=1 MHz, I2C Safe?=**YES**
+- PCA9517：Channels=2, Type=I2C buffer, Speed=400 kHz, I2C Safe?=**YES**
+- 74LVC245：Channels=8, Type=Unidirectional, Speed=100 MHz, I2C Safe?=N/A (direction pin)
+- BSS138 modules：Channels=4, Type=Bidirectional, Speed=400 kHz, I2C Safe?=**YES**
+
+**CRITICAL WARNING:** TXB-series level shifters do **NOT** work reliably with open-drain protocols (I2C, 1-Wire). They fight the pull-up resistors and cause communication errors. Use BSS138-based modules or PCA9306 for I2C.
+
+### Method 4: Direct Connection (3.3V → 5V Input)
+
+Many 5V devices recognize 3.3V as logic HIGH:
+
+- VIH (HIGH threshold)：Typical 5V TTL=2.0V, Typical 5V CMOS=3.5V
+- VIL (LOW threshold)：Typical 5V TTL=0.8V, Typical 5V CMOS=1.5V
+
+**Check datasheet for VIH.** If VIH < 3.0V, direct connection usually works.
+
+**NEVER** connect 5V output directly to 3.3V input — level shift or divide required.
+
+---
+
+## Common Mistakes and Warnings
+
+### NEVER Do This
+
+- Connect 5V directly to any GPIO：Consequence=**Permanent chip damage**
+- Drive relay coil directly from GPIO：Consequence=Inductive kickback damages GPIO
+- Drive motor directly from GPIO：Consequence=Overcurrent, voltage spikes
+- Exceed 50mA total on RPi GPIO：Consequence=Voltage instability, damage
+- Use ESP32 GPIO6-11 (WROOM)：Consequence=Flash pins — chip crashes
+- Pull GPIO12 HIGH at boot (ESP32)：Consequence=**Flash voltage brick**
+- Forget pull-ups on I2C：Consequence=Communication failure
+- Forget pull-up on 1-Wire：Consequence=Bus doesn't work
+- Use TXB-series for I2C：Consequence=Unreliable communication
+- Assume GPIO is 5V tolerant：Consequence=It's not — damage results
+
+### ALWAYS Do This
+
+- Use current-limiting resistor for LEDs：Reason=Prevents overcurrent (220-330Ω)
+- Use flyback diode with relays/motors：Reason=Catches inductive voltage spike
+- Use level shifter for 5V ↔ 3.3V：Reason=Protects GPIO from overvoltage
+- Check total current draw：Reason=Prevent exceeding limits
+- Verify I2C addresses before wiring：Reason=Detect conflicts early
+- Add 100nF decoupling capacitor near ICs：Reason=Reduces noise, improves stability
+- Use external pull-ups for I2C (4.7kΩ)：Reason=Internal pulls too weak
+- Check ESP32 pin restrictions：Reason=Strapping, flash, input-only
+- Use transistor for loads >16mA：Reason=Protects GPIO
+- Add ESD protection for external connectors：Reason=Protects against static
+
+---
+
+## Quick Reference Card
+
+### Formulas
+
+**LED Resistor:**
+```
+R = (VCC - Vf) / If
+R = (3.3V - 2.0V) / 10mA = 130Ω minimum
+Recommended: 220-330Ω (5-10mA, plenty bright)
+```
+
+**Voltage Divider:**
+```
+Vout = Vin × (R2 / (R1 + R2))
+For 5V → 3.3V: R1=1kΩ, R2=2kΩ
+```
+
+**Pull-up Resistor:**
+```
+R = (VCC - VOL) / IOL
+Standard: 4.7kΩ for I2C/1-Wire, 10kΩ for buttons
+```
+
+### Quick Values
+
+- LED resistor (3.3V, red/green)：220-330Ω
+- LED resistor (3.3V, blue/white)：100-150Ω
+- I2C pull-up：**4.7kΩ** to 3.3V
+- 1-Wire pull-up：**4.7kΩ** to 3.3V
+- Button pull-up/down：10kΩ
+- SPI CS pull-up：10kΩ
+- 5V → 3.3V divider：1kΩ + 2kΩ
+- Flyback diode：1N4148 or 1N4007
+- Decoupling capacitor：100nF ceramic
+
+### Current Limits Summary
+
+- Raspberry Pi：Per Pin=16mA, Total GPIO=**50mA**
+- ESP32：Per Pin=20mA recommended, Total GPIO=~1200mA chip total
+
+### Voltage Summary
+
+- Logic HIGH：RPi=3.3V, ESP32=3.3V
+- Logic LOW：RPi=0V, ESP32=0V
+- Max input：RPi=3.3V, ESP32=3.3V
+- 5V tolerant：RPi=**NO**, ESP32=**NO**
+
+### Common Pin Restrictions
+
+**Raspberry Pi:**
+- GPIO0/1: Reserved (HAT EEPROM)
+- GPIO14/15: UART/BT conflict (Pi 3/4/Zero2W)
+
+**ESP32:**
+- GPIO6-11: Flash pins — **NEVER USE**
+- GPIO12: Strapping — **DANGER** (flash voltage)
+- GPIO16-17: PSRAM (WROVER only)
+- GPIO34-39: Input only, no pulls
+
+---
@@ -0,0 +1,109 @@
+# 电容选型与保护电路踩坑
+
+> **类别：trap** | **芯片：cross-platform** | **主题：电容选型与保护电路踩坑 (MLCC偏压降容 / TVS钳位)**
+>
+> 代价：偏压降容导致实际电容远低于标称值，ADC纹波偏大；保护电路"超标"却无需修改
+
+## 坑1：MLCC偏压降容——标称≠实际（2026-07-26）
+
+### 案例：电子宠物V1.0 C24
+
+- 位号：原选型=C24（IP5306充电模块外围）, 终审升级=C24
+- 标称值：原选型=22µF 10V 0603 C59461, 终审升级=22µF 16V 0805 C45783
+- 问题：原选型=10V额定在5V工作点偏压降容严重，实际容量可能只剩标称的40-60%, 终审升级=16V额定在5V工作点偏压影响小，0805封装同容量偏压特性更优
+
+### 核心规则
+
+1. **额定电压留2倍余量** — 5V工作点选10V额定已经偏紧，选16V才稳。MLCC的DC偏压曲线是非线性的，工作电压越接近额定电压，容量掉得越狠
+2. **同容量大封装偏压特性更好** — 0805的22µF比0603的22µF在相同偏压下实际容量更高，因为大封装介质层更厚更稳定
+3. **充电IC外围电容尤其敏感** — IP5306等充电芯片的外围电容直接影响充电稳定性和纹波，偏压降容会导致充电异常
+
+### 选型速查
+
+- 3.3V：最低额定=6.3V, 推荐额定=10V, 推荐封装=0402/0603
+- 5V：最低额定=10V, 推荐额定=16V, 推荐封装=0603/0805
+- 12V：最低额定=25V, 推荐额定=25V/35V, 推荐封装=0805/1206
+
+> 偏压降容是MLCC的物理特性，不是质量问题。选型时直接按推荐额定选，省得终审再改。
+
+## 坑2：VDDA bulk电容不足——1µF兜不住ADC纹波（2026-07-26）
+
+### 案例：电子宠物V1.0 C2
+
+- 位号：原选型=C2（ESP32-S3 VDDA去耦）, 终审升级=C2
+- 标称值：原选型=1µF 0402 C52923, 终审升级=10µF 0402 C96446
+- 问题：原选型=VDDA路径仅1µF bulk+0.1µF去耦，ADC采样纹波偏大, 终审升级=10µF bulk大幅改善纹波，0402封装不变不占额外面积
+
+### 核心规则
+
+1. **VDDA路径需要比VDD更多的bulk电容** — 模拟电源对纹波更敏感，1µF bulk在ADC高频采样时不够用
+2. **先看封装再定容量** — 0402已经能做到10µF（C96446），不需要为增容换大封装
+3. **C4保留1µF不跟着升** — C4是VDD普通去耦，不是VDDA路径，需求不同不能一刀切
+
+### ESP32-S3 VDDA去耦推荐
+
+```
+VDDA ─── 10µF 0402 (C96446, bulk) ─── 0.1µF 0402 (高频去耦) ─── GND
+```
+
+> VDDA bulk升10µF是ESP32-S3做ADC采集的基本操作，1µF是底线不是推荐值。
+
+## 坑3：TVS钳位电压"超标"≠必须修改（2026-07-26）
+
+### 案例：电子宠物V1.0 D3 TVS
+
+- TVS钳位电压：数值=9.2V, 说明=5V单极性TVS在大电流下的物理极限
+- IP5306 Abs.Max：数值=5.8V, 说明=芯片绝对最大耐压
+- 看起来：数值=超标！, 说明=但实际…
+
+### 结论：接受，不改
+
+1. **浪涌是瞬态的，不是持续过压** — TVS钳位9.2V只发生在ESD/浪涌的微秒级瞬态，不是持续9.2V加在IP5306上
+2. **5V单极性TVS的物理限制** — 这是该类型TVS的固有特性，除非换更贵的双向TVS或更低钳位电压方案，否则无解
+3. **芯片Abs.Max不等于瞬态容忍上限** — Abs.Max是持续工作极限，瞬态过冲芯片有设计余量承受
+4. **成本效益比** — 为这个加成本换方案不值得，三审均认可接受
+
+### 判断框架
+
+```
+TVS钳位 > 芯片Abs.Max？
+├─ 是 → 持续过压？→ 必须改
+├─ 是 → 瞬态浪涌？→ 看幅度和持续时间
+│   ├─ 微秒级、幅度可控 → 通常可接受
+│   └─ 毫秒级或幅度过大 → 需换方案
+└─ 否 → 无问题
+```
+
+> 不是所有"超标"都要改，分清瞬态和持续是关键。TVS的物理限制不是设计缺陷。
+
+## 坑4：BOM同值元件升级后需拆分行（2026-07-26）
+
+### 案例：C2和C4原来合并在BOM同一行
+
+C2和C4原来都是1µF，BOM合并为一行。终审C2升级到10µF后，C4的1µF需要单独保留一行。
+
+### 规则
+
+- **BOM合并看值不看人** — 同值元件合并是压缩BOM的常用做法，但升级其中一个后必须拆回来
+- **改BOM时先扫关联** — 不是只改目标位号那一行，要检查是否有其他位号共享同一行
+
+## 坑5：网表改了，拓扑和方案文档也得改（2026-07-26）
+
+### 案例：C24/C2终审升级后的三方同步
+
+网表里C24和C2改完了，但云端拓扑连接图和方案文档还是旧值，下载后不对齐。
+
+### 同步清单
+
+- 网表（EDA）：需改内容=位号·封装·C编号
+- 拓扑连接图：需改内容=参数表+BOM表+注释
+- 方案文档：需改内容=关键约束条目+设计变更记录
+
+### 规则
+
+- **改网表=改三处** — 网表、拓扑、方案文档是三位一体，改一处必须改三处
+- **变更记录必填** — 每次终审优化/设计变更，在拓扑和方案的变更记录区新增条目，写清日期和内容
+- **下载前对齐** — 投板前最后一次检查：网表值=拓扑值=方案值，三方一致才下单
+
+---
+*2026-07-26 | 电子宠物V1.0终审优化踩坑*
@@ -0,0 +1,359 @@
+# Electrical Constraints Reference
+
+> **类别：reference** | **主题：电气约束通用规范** | **信源：** 多平台汇总
+
+## Table of Contents
+
+- [Platform Comparison Summary](#platform-comparison-summary)
+- [Raspberry Pi Electrical Details](#raspberry-pi-electrical-details)
+  - [Voltage Levels](#voltage-levels)
+  - [Current Limits](#current-limits)
+  - [Power Rails](#power-rails)
+  - [Internal Pull Resistors](#internal-pull-resistors)
+  - [Safe Driving Patterns](#safe-driving-patterns)
+- [ESP32 Electrical Details](#esp32-electrical-details)
+  - [Voltage Levels](#voltage-levels)
+  - [Current Limits](#current-limits)
+  - [Power Consumption](#power-consumption)
+  - [Internal Pull Resistors](#internal-pull-resistors)
+  - [Drive Strength Configuration](#drive-strength-configuration)
+- [Pull-up and Pull-down Resistors](#pull-up-and-pull-down-resistors)
+  - [When Required](#when-required)
+  - [Calculation Formula](#calculation-formula)
+  - [Strength Guidelines](#strength-guidelines)
+  - [Consequences of Wrong Value](#consequences-of-wrong-value)
+- [Level Shifting](#level-shifting)
+  - [When Required](#when-required)
+  - [Method 1: Voltage Divider (5V → 3.3V, Unidirectional)](#method-1-voltage-divider-5v--33v-unidirectional)
+  - [Method 2: N-Channel MOSFET (Bidirectional)](#method-2-n-channel-mosfet-bidirectional)
+  - [Method 3: Dedicated Level Shifter ICs](#method-3-dedicated-level-shifter-ics)
+  - [Method 4: Direct Connection (3.3V → 5V Input)](#method-4-direct-connection-33v--5v-input)
+- [Common Mistakes and Warnings](#common-mistakes-and-warnings)
+  - [NEVER Do This](#never-do-this)
+  - [ALWAYS Do This](#always-do-this)
+- [Quick Reference Card](#quick-reference-card)
+  - [Formulas](#formulas)
+  - [Quick Values](#quick-values)
+  - [Current Limits Summary](#current-limits-summary)
+  - [Voltage Summary](#voltage-summary)
+  - [Common Pin Restrictions](#common-pin-restrictions)
+
+---
+
+## Platform Comparison Summary
+
+- Logic voltage：Raspberry Pi=3.3V, ESP32=3.3V
+- Max per-pin current：Raspberry Pi=16mA source/sink, ESP32=40mA max (20mA recommended)
+- Aggregate GPIO current：Raspberry Pi=**50mA total**, ESP32=~1200mA total (chip limit)
+- 5V tolerant：Raspberry Pi=**NO**, ESP32=**NO**
+- Internal pull-up：Raspberry Pi=~50kΩ, ESP32=~45kΩ typical
+- Internal pull-down：Raspberry Pi=~50kΩ, ESP32=~45kΩ typical
+- Drive strength：Raspberry Pi=Fixed, ESP32=Configurable (5-40mA)
+- Input threshold (VIH)：Raspberry Pi=~1.8V, ESP32=~2.0V
+- Input threshold (VIL)：Raspberry Pi=~0.8V, ESP32=~0.8V
+
+---
+
+## Raspberry Pi Electrical Details
+
+### Voltage Levels
+
+- **All GPIO pins operate at 3.3V ONLY**
+- **5V on any GPIO pin WILL PERMANENTLY DAMAGE the SoC**
+- No built-in overvoltage protection
+- No built-in ESD protection (handle with care)
+
+### Current Limits
+
+- Per-pin source：16mA, Consequence of Exceeding=Voltage droop, pin damage
+- Per-pin sink：16mA, Consequence of Exceeding=Voltage rise, pin damage
+- **Total GPIO**：**50mA**, Consequence of Exceeding=Instability, crashes, permanent damage
+
+**Critical:** The 50mA limit is across ALL GPIO pins combined, not per-bank.
+
+### Power Rails
+
+- 3.3V：Source=Onboard regulator, Available Current=~50mA for peripherals, Notes=Shared with Pi's 3.3V needs
+- 5V：Source=USB/PSU direct, Available Current=1-2A minus Pi consumption, Notes=No regulation, direct pass-through
+- GND：Source=Common ground, Available Current=N/A, Notes=8 ground pins on header
+
+### Internal Pull Resistors
+
+- GPIO0-8：Default State=Pull-UP, Resistance=~50kΩ
+- GPIO9-27：Default State=Pull-DOWN, Resistance=~50kΩ
+
+**Note:** Internal pulls are too weak for I2C (need 4.7kΩ external).
+
+### Safe Driving Patterns
+
+- Single LED：Method=330Ω-1kΩ series resistor, Notes=3-10mA safe
+- Multiple LEDs：Method=Transistor driver, Notes=If total >50mA
+- Relay：Method=Transistor/MOSFET + flyback diode, Notes=Never direct from GPIO
+- Motor：Method=Motor driver IC (L298N, DRV8833), Notes=Never direct from GPIO
+- Buzzer (passive)：Method=Transistor driver, Notes=Inductive load
+- Buzzer (active)：Method=Direct if <16mA, Notes=Check current draw
+
+---
+
+## ESP32 Electrical Details
+
+### Voltage Levels
+
+- **All GPIO pins operate at 3.3V ONLY**
+- **5V on any GPIO pin WILL DAMAGE the chip**
+- No built-in overvoltage protection
+- Some ESD protection but don't rely on it
+
+### Current Limits
+
+- Per-pin max：40mA, Notes=Absolute maximum
+- Per-pin recommended：20mA, Notes=For reliability/longevity
+- Total chip：~1200mA, Notes=Includes WiFi, BT, CPU
+
+### Power Consumption
+
+- Active + WiFi TX：Current Draw=80-240mA, Notes=Peaks during transmission
+- Active + WiFi idle：Current Draw=20-68mA, Notes=Connected but not transmitting
+- Active, no radio：Current Draw=20-68mA, Notes=CPU running
+- Modem sleep：Current Draw=3-20mA, Notes=WiFi paused, CPU active
+- Light sleep：Current Draw=0.8mA, Notes=CPU paused, RTC running
+- Deep sleep：Current Draw=10-150µA, Notes=Only RTC + ULP available
+
+### Internal Pull Resistors
+
+- Standard GPIO：Pull-up=Yes, Pull-down=Yes, Resistance=~45kΩ
+- GPIO34-39：Pull-up=**NO**, Pull-down=**NO**, Resistance=N/A (input-only)
+
+**Note:** Internal pulls are too weak for I2C (need 4.7kΩ external).
+
+### Drive Strength Configuration
+
+- 5mA：Current=Weakest, Use Case=Low power, slow signals
+- 10mA：Current=Low, Use Case=General purpose
+- 20mA：Current=Default, Use Case=Most applications
+- 40mA：Current=Maximum, Use Case=Fast edges, heavy loads
+
+Higher drive strength = faster edges but more EMI/noise.
+
+---
+
+## Pull-up and Pull-down Resistors
+
+### When Required
+
+- I2C bus (SDA)：Pull Type=Pull-UP, Typical Value=**4.7kΩ**
+- I2C bus (SCL)：Pull Type=Pull-UP, Typical Value=**4.7kΩ**
+- 1-Wire bus (DQ)：Pull Type=Pull-UP, Typical Value=**4.7kΩ**
+- Button to GND：Pull Type=Pull-UP, Typical Value=10kΩ
+- Button to VCC：Pull Type=Pull-DOWN, Typical Value=10kΩ
+- SPI CS line：Pull Type=Pull-UP, Typical Value=10kΩ
+- Open-drain output：Pull Type=Pull-UP, Typical Value=1-10kΩ
+- UART RX (optional)：Pull Type=Pull-UP, Typical Value=10kΩ (noise immunity)
+- Reset line：Pull Type=Pull-UP, Typical Value=10kΩ
+
+### Calculation Formula
+
+```
+R = (VCC - VOL) / IOL
+
+Where:
+  VCC = Supply voltage (3.3V)
+  VOL = Output low voltage (~0.4V)
+  IOL = Required sink current (3mA for I2C)
+
+Example (I2C):
+  R = (3.3V - 0.4V) / 3mA = 967Ω minimum
+  Typical choice: 4.7kΩ (provides margin)
+```
+
+### Strength Guidelines
+
+- 1kΩ：Use Case=Long wires, high capacitance, fast I2C, Notes=Strong pull, higher current
+- 4.7kΩ：Use Case=Standard I2C, 1-Wire, general purpose, Notes=Most common choice
+- 10kΩ：Use Case=Buttons, CS lines, low-power, Notes=Standard digital pull
+- 47-100kΩ：Use Case=Wake-up inputs, ultra-low power, Notes=Very weak, slow rise time
+
+### Consequences of Wrong Value
+
+**Too high (weak pull):**
+- Slow signal rise times
+- Noise susceptibility
+- Communication errors at higher speeds
+- May not reach valid HIGH level
+
+**Too low (strong pull):**
+- Excessive current consumption
+- Device may not be able to pull line LOW
+- Wasted power in battery applications
+
+---
+
+## Level Shifting
+
+### When Required
+
+- 5V logic output → 3.3V GPIO input
+- 3.3V GPIO output → 5V input (if device doesn't recognize 3.3V as HIGH)
+- Bidirectional communication between 3.3V and 5V systems
+
+### Method 1: Voltage Divider (5V → 3.3V, Unidirectional)
+
+**Use for:** Slow signals (<100kHz), input direction only
+
+```
+5V Signal ──[1kΩ]──┬──> 3.3V GPIO Input
+                   │
+                 [2kΩ]
+                   │
+                  GND
+
+Output: 5V × (2kΩ / 3kΩ) = 3.33V
+```
+
+- Simple, cheap：Cons=Input direction only
+- 2 resistors：Cons=Slow (RC time constant)
+- No active components：Cons=Loads the signal
+
+### Method 2: N-Channel MOSFET (Bidirectional)
+
+**Use for:** I2C, 1-Wire, open-drain signals up to 400kHz
+
+```
+3.3V Side                              5V Side
+    │                                      │
+  [4.7kΩ]                              [4.7kΩ]
+    │                                      │
+    ├────────┬──────────────────┬──────────┤
+    │        │                  │          │
+   SDA    Source              Drain      SDA
+  (3.3V)     └───── BSS138 ─────┘       (5V)
+                      │
+                    Gate
+                      │
+                    3.3V
+```
+
+**Operation:**
+- Gate tied to LOW side voltage (3.3V)
+- When LOW side pulls down, MOSFET conducts, pulling HIGH side down
+- When HIGH side pulls down, body diode conducts, pulling LOW side down
+- Pull-ups restore HIGH state on both sides
+
+- MOSFET：Specification=BSS138, 2N7000 (through-hole)
+- Pull-ups：Specification=4.7kΩ on each side
+- Voltage：Specification=3.3V on gate, low side; 5V on high side
+
+### Method 3: Dedicated Level Shifter ICs
+
+- TXB0104：Channels=4, Type=Auto-direction, Speed=100 Mbps, I2C Safe?=**NO**
+- TXB0108：Channels=8, Type=Auto-direction, Speed=100 Mbps, I2C Safe?=**NO**
+- PCA9306：Channels=2, Type=I2C-specific, Speed=1 MHz, I2C Safe?=**YES**
+- PCA9517：Channels=2, Type=I2C buffer, Speed=400 kHz, I2C Safe?=**YES**
+- 74LVC245：Channels=8, Type=Unidirectional, Speed=100 MHz, I2C Safe?=N/A (direction pin)
+- BSS138 modules：Channels=4, Type=Bidirectional, Speed=400 kHz, I2C Safe?=**YES**
+
+**CRITICAL WARNING:** TXB-series level shifters do **NOT** work reliably with open-drain protocols (I2C, 1-Wire). They fight the pull-up resistors and cause communication errors. Use BSS138-based modules or PCA9306 for I2C.
+
+### Method 4: Direct Connection (3.3V → 5V Input)
+
+Many 5V devices recognize 3.3V as logic HIGH:
+
+- VIH (HIGH threshold)：Typical 5V TTL=2.0V, Typical 5V CMOS=3.5V
+- VIL (LOW threshold)：Typical 5V TTL=0.8V, Typical 5V CMOS=1.5V
+
+**Check datasheet for VIH.** If VIH < 3.0V, direct connection usually works.
+
+**NEVER** connect 5V output directly to 3.3V input — level shift or divide required.
+
+---
+
+## Common Mistakes and Warnings
+
+### NEVER Do This
+
+- Connect 5V directly to any GPIO：Consequence=**Permanent chip damage**
+- Drive relay coil directly from GPIO：Consequence=Inductive kickback damages GPIO
+- Drive motor directly from GPIO：Consequence=Overcurrent, voltage spikes
+- Exceed 50mA total on RPi GPIO：Consequence=Voltage instability, damage
+- Use ESP32 GPIO6-11 (WROOM)：Consequence=Flash pins — chip crashes
+- Pull GPIO12 HIGH at boot (ESP32)：Consequence=**Flash voltage brick**
+- Forget pull-ups on I2C：Consequence=Communication failure
+- Forget pull-up on 1-Wire：Consequence=Bus doesn't work
+- Use TXB-series for I2C：Consequence=Unreliable communication
+- Assume GPIO is 5V tolerant：Consequence=It's not — damage results
+
+### ALWAYS Do This
+
+- Use current-limiting resistor for LEDs：Reason=Prevents overcurrent (220-330Ω)
+- Use flyback diode with relays/motors：Reason=Catches inductive voltage spike
+- Use level shifter for 5V ↔ 3.3V：Reason=Protects GPIO from overvoltage
+- Check total current draw：Reason=Prevent exceeding limits
+- Verify I2C addresses before wiring：Reason=Detect conflicts early
+- Add 100nF decoupling capacitor near ICs：Reason=Reduces noise, improves stability
+- Use external pull-ups for I2C (4.7kΩ)：Reason=Internal pulls too weak
+- Check ESP32 pin restrictions：Reason=Strapping, flash, input-only
+- Use transistor for loads >16mA：Reason=Protects GPIO
+- Add ESD protection for external connectors：Reason=Protects against static
+
+---
+
+## Quick Reference Card
+
+### Formulas
+
+**LED Resistor:**
+```
+R = (VCC - Vf) / If
+R = (3.3V - 2.0V) / 10mA = 130Ω minimum
+Recommended: 220-330Ω (5-10mA, plenty bright)
+```
+
+**Voltage Divider:**
+```
+Vout = Vin × (R2 / (R1 + R2))
+For 5V → 3.3V: R1=1kΩ, R2=2kΩ
+```
+
+**Pull-up Resistor:**
+```
+R = (VCC - VOL) / IOL
+Standard: 4.7kΩ for I2C/1-Wire, 10kΩ for buttons
+```
+
+### Quick Values
+
+- LED resistor (3.3V, red/green)：220-330Ω
+- LED resistor (3.3V, blue/white)：100-150Ω
+- I2C pull-up：**4.7kΩ** to 3.3V
+- 1-Wire pull-up：**4.7kΩ** to 3.3V
+- Button pull-up/down：10kΩ
+- SPI CS pull-up：10kΩ
+- 5V → 3.3V divider：1kΩ + 2kΩ
+- Flyback diode：1N4148 or 1N4007
+- Decoupling capacitor：100nF ceramic
+
+### Current Limits Summary
+
+- Raspberry Pi：Per Pin=16mA, Total GPIO=**50mA**
+- ESP32：Per Pin=20mA recommended, Total GPIO=~1200mA chip total
+
+### Voltage Summary
+
+- Logic HIGH：RPi=3.3V, ESP32=3.3V
+- Logic LOW：RPi=0V, ESP32=0V
+- Max input：RPi=3.3V, ESP32=3.3V
+- 5V tolerant：RPi=**NO**, ESP32=**NO**
+
+### Common Pin Restrictions
+
+**Raspberry Pi:**
+- GPIO0/1: Reserved (HAT EEPROM)
+- GPIO14/15: UART/BT conflict (Pi 3/4/Zero2W)
+
+**ESP32:**
+- GPIO6-11: Flash pins — **NEVER USE**
+- GPIO12: Strapping — **DANGER** (flash voltage)
+- GPIO16-17: PSRAM (WROVER only)
+- GPIO34-39: Input only, no pulls
+
+---
@@ -0,0 +1,85 @@
+# ESP32-32D与S3选型踩坑
+
+> **类别：compare** | **芯片：esp32 / esp32-d0wd / esp32-s3** | **主题：ESP32-D0WD vs ESP32-S3 选型对比**
+>
+> 代价：V2.5设计用了WROOM-32D但没加USB转串口芯片，板子到手无法烧录=变砖
+
+## 坑1：WROOM-32D没有原生USB
+
+ESP32-WROOM-32D模组**没有原生USB**，不像C3/S3那样Type-C直连D+/D-就能烧程序。Type-C只能供电，**无法下载固件**。
+
+**必须有USB转串口方案：**
+- 方案A：板上加CH340/CH9102 + 自动复位电路（双NPN S8050 + 2×1kΩ），Type-C直接供电+烧录，成本+¥3~5
+- 方案B：不加串口芯片，GPIO1(TXD0)/GPIO3(RXD0)引出到排针，用外接FTDI下载器烧，省钱但每次接线
+
+**铁律：选32D方案，BOM里必须列出USB转串口芯片+外围，否则就是废板。**
+
+## 坑2：S3原生USB省大量器件
+
+换S3后能省掉的：
+- CH340/CH9102整颗IC + 外围晶振 + 4~5颗去耦电容
+- 自动复位电路：2×S8050 + 2×1kΩ
+- UART排针：GPIO1/GPIO3不用专门引出
+- S3模组内部Flash更大（N8=8MB）
+
+**合计省7~8个器件，板上面积也省一块，布线更简单。**
+
+## 坑3：S3新增strapping和USB走线要求
+
+S3虽省器件，但有新要求：
+- **GPIO45/46是strapping**，必须按目标模式做上下拉，不能悬空
+- **USB D+/D-走线**：等长、短线、少过孔，远离大电流走线，否则枚举反复断开
+
+## 坑4：GPIO12上拉导致Flash变砖
+
+ESP32-32D的GPIO12是strapping pin，决定VDD_SDIO电压：
+- **GPIO12上拉10kΩ → VDD_SDIO=1.8V → Flash无法工作**
+- 正确：GPIO12下拉GND → VDD_SDIO=3.3V（默认安全值）
+
+设计时必须检查所有strapping pin的偏置方向，不能随便加上拉。
+
+## 坑5：WROOM-32D模组内部已集成
+
+- **Flash**：N8后缀=8MB，封在模组内
+- **晶振**：40MHz，封在模组内
+- **WiFi/BT**：共用2.4GHz射频前端和天线，时分复用，不需要额外加天线或射频器件
+
+PCB上不用外接Flash、不用焊晶振，模组焊上去供电就能跑。
+
+## 坑6：天线放置必须按乐鑫官方规则
+
+**最佳方案：模组放板边，天线端伸出板边**
+- 天线蛇形区域悬在板子外面，完全不接触PCB，信号最好
+- 模组金属屏蔽罩下方要铺完整地铜
+
+**天线没法伸出板边时：**
+- 天线下方及周边**所有层禁止铺铜、走线、放元件**
+- 净空区至少天线周围2mm范围内清空
+- 板边挖掉天线区域的板材，给天线留出空间
+
+**禁止做的事：**
+- ❌ 天线区域下方有铜（任何层都不行）
+- ❌ 模组放板子中间四周挖空
+- ❌ 电池、金属螺丝、连接器靠近天线端
+
+---
+*2026-07-04 | V2.5设计踩坑总结*
+
+## 坑7：C6同尺寸升级路径——彩屏备选方案（2026-07-12）
+
+GBC V5.0当前用C3+I2C OLED，将来要上1.3寸彩屏时GPIO不够。C6是pin-to-pin兼容的升级路径：
+
+- 封装：ESP32-C3-MINI-1=QFN, ESP32-C6-MINI-1-N4 (C5736265)=SMD-53P，53脚（大半GND）
+- 尺寸：ESP32-C3-MINI-1=13×13mm, ESP32-C6-MINI-1-N4 (C5736265)=同尺寸兼容
+- 可用GPIO：ESP32-C3-MINI-1=~13个, ESP32-C6-MINI-1-N4 (C5736265)=**22个**
+- 嘉立创库：ESP32-C3-MINI-1=基础库, ESP32-C6-MINI-1-N4 (C5736265)=**扩展库**，SMT有换料费
+- 价格：ESP32-C6-MINI-1-N4 (C5736265)=$3.82/片
+
+GBC V5.0当前用13个GPIO，C6给22个剩9个富余，SPI彩屏4-6线绑绑有余，I2C/UART/USB全保留。
+
+**决策：** GBC 5.0先C3+OLED投板，C6方案存档备用，等真要上彩屏再换芯（板壳不改）。
+
+**注意：** C6在嘉立创扩展库，SMT会收换料费，小批量要算这笔账。
+
+---
+*2026-07-12 | C6升级备选方案归档*
@@ -0,0 +1,45 @@
+# 四层板层叠与走线踩坑
+> **类别：trap** | **芯片：cross-platform** | **主题：四层板层叠与走线踩坑**
+> 来源：电子宠物V1.0 S3FH4R2裸片四层板设计讨论，2026-07-24
+
+## 一、层叠分配
+
+- 顶层：用途=信号走线+摆件, 铺铜策略=信号走完后空地铺GND铜皮
+- 内层1：用途=GND, 铺铜策略=出厂整面铺铜，不手动走线
+- 内层2：用途=3V3电源走线, 铺铜策略=只走线不铺铜，灵活性最高
+- 底层：用途=信号走线, 铺铜策略=信号走完后空地铺GND铜皮
+
+### 关键理解
+- **GND铜皮有三层**：内层1完整铺 + 顶层空地补铺 + 底层空地补铺，通过过孔连成一体
+- **3V3只走线不铺铜**：内层2走3V3拉线+过孔即可，铺铜反而浪费且不必要
+- **顶层/底层铺GND是补铺**：先走完信号线，剩余空地再铺GND铜皮，别为了铺铜把信号线挤没了
+
+## 二、走线优先级（四层板）
+
+**核心原则：信号路径最死，3V3和GND怎么都能接，信号走不通的地方3V3内层2还能让路。**
+
+### 执行顺序
+1. **设置层叠**：内层1铺GND，内层2留空
+2. **顶层走信号线**（最关键）——先把I2S+SPI这些主通路走通
+3. **底层走信号线**——I2C、触摸、UART这些需要绕的
+4. **内层2走3V3**——拉线+过孔，最后补，因为它最灵活
+5. **顶层/底层空地铺GND铜皮**——收尾
+
+### 为什么信号线先走
+- 信号路径约束最多（起点终点固定、不能随意换层）
+- 3V3走内层2有整层可用，可绕可让
+- GND铺铜是最后收尾，有空就铺
+
+## 三、铺GND铜皮的注意点
+
+- **先走完信号线再铺GND**，不能反过来
+- 顶层空地铺GND铜皮后，打过孔到内层1 GND，多一个回流路径，信号质量更好
+- 底层同理，空地铺GND铜皮+过孔连内层1
+- 最终效果：三层GND铜皮通过过孔连成一体，形成完整的GND回流网络
+
+## 四、与两层板的区别
+
+- GND处理：两层板=底层尽量少走线，保证完整地平面, 四层板=内层1完整GND，顶层底层补铺
+- 电源走线：两层板=顶层/底层走，和信号争空间, 四层板=内层2专走3V3，不占信号层
+- 走线难度：两层板=信号和电源挤在一起, 四层板=信号有顶层+底层两层，空间充裕
+- GND质量：两层板=依赖底层铺铜完整性, 四层板=三层GND铜皮，回流路径最优
@@ -0,0 +1,230 @@
+# PCB项目通用全流程工作清单 V3.0
+> **类别：pcb** | **芯片：cross-platform** | **主题：PCB项目通用全流程工作清单 V3.0**
+> 2026-06-28 | 整合V2.0(13铁律+8步审查+踩坑附录) + 方法论V2.0(9阶段+拓扑重审+模块整体分合+电源树)
+
+---
+
+## 通用铁律
+
+1. **带病不推进**：每阶段出口条件不满足，不进下一阶段
+2. **datasheet为唯一权威标准**：冲突时以技术手册为准，网搜结果需交叉验证
+3. **双模型交叉验证**：审查环节智谱+DeepSeek双审，少一个不行。双模型必须独立审查，分别发问题文档各自输出，最后合并比对，不一致项人工复核，禁止同一对话传话
+4. **先熟读再设计**：IC参数没吃透没资格画拓扑，参数是设计的基础弹药
+5. **改方案比新建难**：在原有基础上改要跟旧惯性斗争，每个决定重新论证；已沉淀的弹药库/速查卡/踩坑规则是从0到1的资产
+6. **方法论持续迭代**：踩过的坑沉淀为规则，每次整改后复盘方法论缺陷
+7. **参考设计必须走完论证流程**：开源/参考设计与全新设计一视同仁，只提供典型值不提供你的场景可靠性
+8. **数据锚点**：审查输出必须带数据锚点（net名/位号/数值），禁止模糊结论
+9. **踩坑即记录**：新坑随时补进附录
+10. **基线存档制**：原理图基线存档后不改，改版另起版本号
+11. **网络标签功能性命名**：一个net一个名字，不复用不加后缀，禁下划线/空格/标点
+12. **布局先规划后动手**：先九宫格分区确认再塞元件
+13. **电源走顶层明面**：VBUS/5V/3V3粗线顶层，信号底层
+14. **外接座靠边放**：接口靠板边，连的元件就近
+15. **接口必须对照官方**：USB/UART/I2C等信号线阻容网络，与芯片手册/官方开发板逐脚对照，官方要求的一个不能省
+16. **strapping引脚查默认态**：BOOT/EN等启动引脚，必须查上电瞬间默认电平，不能只看"按键按下"
+17. **烧录链路必走查**：最后一道关——插上Type-C电脑能识别能烧录，全链路走一遍
+18. **开发板拆解陷阱**：面包板验证的是拓扑逻辑，开发板内部兜底的接口细节你看不见，拆到PCB时这些全得自己画，漏一个就废板
+19. **模块与整体必须分开做再融合**：模块化只管IC级参数/引脚阻容，整体性管网级连接/路径/时序，不能混着做否则两头都漏
+20. **技术参数禁凭记忆瞎答**：必须先查文档再回复，宁慢勿错
+
+---
+
+## 一、思路碰撞
+
+- ☐ 产品用途/核心功能/目标用户
+- ☐ 技术路线选型 + 成本框算
+- ☐ **核心工作模式定义（强制）**：有无电池、边充边用、低电量等场景下的系统行为，不定义不清不进下一步
+- ☐ 功能说明文档：每模块输入/输出/精度 + 供电架构图 + 交互方式
+- ☐ 架构审查：供电链路(压差+裕量) / 测量链路(量程匹配) / 保护链路(阈值)，均带数值
+- ☐ **反向场景审查**：插错/放反/过压/ESD，至少做到"坏了不冒烟"，能自恢复更好
+- ☐ 双模型交叉审查通过
+
+**出口**：需求清单+约束条件+工作模式定义 双方确认 + 功能文档定稿 + 架构审查通过 + 三条链路有数值支撑
+
+---
+
+## 二、拓扑从零构建与独立论证
+
+- ☐ **不沿袭旧设计**，独立重新论证每个连接的合理性，"之前这么设计的"不是理由
+- ☐ 如发现IC不合适，该换就换，不将就
+- ☐ **电源树绘制**：从电源入口开始，逐级画出经过的每一颗IC（充电、保护、开关、LDO），标出每级输入输出电压、电流能力
+- ☐ **压降与耐压审查**：确认极端情况下后端器件输入电压在安全范围内，LDO压差足够
+- ☐ **路径隔离论证**：充电路径和系统供电路径是共用/部分共用/完全独立，能否覆盖所有工作模式
+- ☐ 双模型交叉审查通过
+
+**出口**：拓扑完美无缺 + 无惯性遗留假设 + 电源树论证通过
+
+注：**已有设计迭代时可先做阶段三再回阶段二**（IC参数校准→拓扑重审），省去重新选型步骤
+
+---
+
+## 三、IC选型与参数确认
+
+- ☐ **先熟读再设计**：所有IC datasheet吃透，PDF图表信息（配置表/时序图/引脚图/特性曲线）必须翻原文件确认，文本提取不替代原图
+- ☐ 逐IC建立技术档案：PDF+速查卡+引脚映射+电气特性
+- ☐ **逐pin合规审查**：
+  - Strapping/电源/特殊功能引脚逐条对照datasheet
+  - **电源完整性审查（强制）**：确认IC供电范围、上电斜率要求、所需去耦电容容值和数量，尤其检查MCU内部LDO需外部电容的引脚
+  - **复位/EN引脚时序审查（强制）**：确认原理图上有阻容延迟电路或电压监控复位IC，无此电路不进下一阶段
+- ☐ 优先基础库（省换料费¥20/种），扩展库确认库存
+- ☐ 封装统一（阻容0805起步），关键器件确认替代方案
+- ☐ **新手坟场封装规避**：验证板优先SOP/SOT-23/0603以上，走线不挤不强行上QFN/0402
+- ☐ BOM vs datasheet交叉对比，确认无遗漏元件
+- ☐ BOM：位号/型号/封装/编号/数量/库类型/备注，SMT/自焊/外接分开
+- ☐ 每个编号去商城搜过不靠记忆，封装实物匹配，换料费核算
+
+**出口**：所有IC参数锁死 + 速查卡与PDF原图一致 + BOM冻结零冲突 + 编号已核实 + 换料费已算
+
+---
+
+## 四、分模块验证
+
+- ☐ 模块化只管IC级参数、引脚阻容配置
+- ☐ 逐模块标定：压降、稳定性、电流、驱动能力
+- ☐ 双模型交叉验证（智谱+DeepSeek），禁止单模型结果直接用
+
+**出口**：每个模块独立验证通过，参数在控制内
+
+---
+
+## 五、整体审视
+
+- ☐ 整体性管网级连接、路径、时序
+- ☐ 回头看模块标定的参数，在整体运行时有无问题
+- ☐ 阻容根据拓扑运算结果调整
+- ☐ 确认板级合理性（电源路径、信号流向、接口一致性）
+- ☐ **总线/接口完整性审查**：
+  - 开漏总线（I2C等）原理图上显式画出上拉电阻，阻值匹配速率和节点数
+  - 对外接口ESD防护（至少留TVS管位置）
+  - 连接器/开关触点在关键信号路径上的接触电阻对测量精度影响
+  - 高速/敏感信号终端匹配或阻抗连续性考虑
+- ☐ 双模型交叉审查通过
+
+**出口**：整体网络校验通过 + 阻容配置合理 + 接口完整性确认
+
+---
+
+## 六、网络标签规划
+
+- ☐ 每个net：名称 + 连接引脚列表 + 功能说明
+- ☐ 同名net超2个模块→强制拆中间节点
+- ☐ 采样元件两端必须不同net名（否则被旁路=致命）
+- ☐ 供电net和测量net分开命名，禁止后缀区分
+
+**出口**：网络总表定稿 + 采样电阻两端net名不同 + 双模型审过
+
+---
+
+## 七、原理图绘制
+
+- ☐ 分模块画，虚线框围起标注模块名，模块内直连跨模块用标签
+- ☐ 每模块画完立即：放标签对照总表 / 悬空引脚标NC / 自焊件标注
+- ☐ **对外接口逐脚对照官方**：每个模块与外部连接器的信号完整性要求，对照芯片手册参考设计（串联电阻/上下拉/匹配电容），单独检查项覆盖
+- ☐ DRC/ERC → 0错误0警告
+
+**出口**：模块画完 + 标签与总表一致 + 无悬空 + 接口对照官方通过 + DRC零报错
+
+---
+
+## 八、原理图审查（核心，八步缺一不可）
+
+### 8.1 DRC/ERC → 0错误0警告
+⚠ DRC只查物理规则，不查功能/拓扑错误
+
+### 8.2 网表逐条核对
+每个net三问：该连的连了吗？多连了吗？漏连了吗？
+**逐元件值比对**：网表PARTTYPE/Value必须与BOM逐一对照，阻值/容值/型号不一致立即标红，连通性正确≠值正确
+
+### 8.3 接口信号完整性审查（独立项）
+USB D+/D-串联电阻、CC上下拉、I2C上拉、时钟匹配等，**独立于功能审查**，跨模块连接规范逐条检查
+
+### 8.4 strapping引脚上电时序专项
+所有影响启动/下载/复位的引脚，查**默认态**（上电瞬间上下拉决定的电平），不只看按键动作。制作真值表验证每种组合合法
+
+### 8.5 烧录链路完整性走查
+从USB座→D+/D-→芯片GPIO→BOOT/EN时序→固件加载，每个节点确认能正常工作。**最后一道关口**
+
+### 8.6 与官方开发板差异对比
+用官方开发板原理图做参照模板，逐模块逐脚比对。所有偏离官方的改动记录原因
+
+### 8.7 DeepSeek识图审核
+分模块截图标注网络标签+连接关系，喂DeepSeek识图，输出带数据锚点+存疑点
+
+### 8.8 智谱文字深检+交叉验证
+喂网表+功能文档+标签总表+DeepSeek存疑点，与8.7交叉比对，两个模型都通过才算过
+
+⚠ **双模型必须独立审查**：分别发问题文档，各自独立输出结论，最后合并比对。不一致项人工复核。禁止在同一对话里让两边传话
+
+**出口**：八项全绿 → 原理图基线存档
+
+---
+
+## 九、PCB设计
+
+- ☐ 布局预规划：九宫格分区图，电气相关模块相邻，放电通路一列到底
+- ☐ **模拟/数字分区**：ADC走线远离I2C时钟等高频数字信号
+- ☐ 布局：信号流 电源→MCU→外设，热敏件远发热区，去耦紧贴IC
+- ☐ 提炼各IC的PCB layout硬约束（EP过孔/去耦放置/天线净空/走线规则等），按约束清单逐条布局布线
+- ☐ 走线：放电1mm→电源0.5mm→信号0.25mm，GND铺铜，大电流直线不过孔，功率焊盘全连接禁十字花
+- ☐ DRC→0 + 3D预览无重叠
+
+**出口**：DRC通过 + 3D确认 + layout约束逐条满足 + STEP已导出
+
+---
+
+## 十、下单前终检
+
+- ☐ BOM↔原理图双向核对 + SMT库存确认 + 换料费预估
+- ☐ Gerber完整性 + 成本核算
+
+**出口**：下单文件齐 + 成本确认 + 三方一致
+
+---
+
+## 十一、实物验证
+
+- ☐ **电源分步上电法**：
+  - 第一步：不焊MCU等贵重器件，先验证充电IC和LDO，示波器看启动波形无过冲/震荡
+  - 第二步：焊MCU最小系统（电源+EN+下载口），确认稳定识别、可下载程序
+  - 第三步：逐个加入外围模块，问题隔离在最小系统
+- ☐ 目检 → 万用表短路排查(3V3/GND, VBUS/GND, VBAT/GND，绝不上电先)
+- ☐ **烧录失败直接终止**，排查硬件，不继续后续功能测试
+- ☐ 功能模块逐级验证 → 电池接入(最后)
+- ☐ 各引脚参数在控制内、有冗余
+- ☐ 资深老手终审
+- ☐ 问题记录：致命/重要/轻微
+
+**出口**：实物测试通过 + 产品可交付
+
+---
+
+## 附录：踩坑记录
+
+- 采样电阻被同名net旁路→短路：严重度=致命, 防范措施=同名net超2模块必须拆中间节点，采样两端net名不同, 对应阶段/审查步=六/8.2
+- USB D+/D-缺串联电阻+D+上拉→电脑无法枚举：严重度=致命, 防范措施=外部通信接口必须对照芯片手册参考设计，逐脚核对阻容网络, 对应阶段/审查步=8.3/8.6
+- BOOT接错引脚+GPIO8 NC→非法启动组合：严重度=致命, 防范措施=strapping引脚必须查默认态+做真值表, 对应阶段/审查步=8.4
+- BOOT按键常低→永远进下载模式出不来：严重度=致命, 防范措施=BOOT默认高电平(上拉3V3)，按下才拉低, 对应阶段/审查步=8.4
+- 嘉立创编号靠记忆写错：严重度=重要, 防范措施=BOM审核时每个编号必须搜库确认, 对应阶段/审查步=三
+- MOSFET Vgs(th)与驱动电压不匹配：严重度=重要, 防范措施=MOS选型必须确认驱动电压能完全导通, 对应阶段/审查步=三
+- ESP32-C3下载模式与ESP32-D相反：严重度=致命, 防范措施=每次用新MCU先查下载模式，不惯性套用, 对应阶段/审查步=8.4
+- 6P Type-C无数据线→无法烧录：严重度=致命, 防范措施=烧录链路完整性必须作为独立检查项, 对应阶段/审查步=8.5
+- 开发板拆解丢接口细节→废板：严重度=致命, 防范措施=拆到PCB时必须逐项检查"开发板做了什么我没画", 对应阶段/审查步=8.3/8.6
+- 模块验证OK整体漏→网络级问题：严重度=致命, 防范措施=模块与整体必须分开做再融合, 对应阶段/审查步=五
+- PDF图表信息文本提取遗漏：严重度=致命, 防范措施=必须翻PDF原图确认，文本不替代图, 对应阶段/审查步=三
+- 拓扑沿用旧设计→惯性假设残留：严重度=致命, 防范措施=拓扑独立论证，"之前这么设计的"不是理由, 对应阶段/审查步=二
+- 工作模式未定义→供电架构矛盾：严重度=致命, 防范措施=阶段一强制定义工作模式, 对应阶段/审查步=一
+- 电源树未画→压降/路径问题漏审：严重度=致命, 防范措施=拓扑阶段强制绘制电源树+压降审查+路径隔离论证, 对应阶段/审查步=二
+- 参考设计盲目抄→场景不适用：严重度=重要, 防范措施=参考设计必须走完论证流程, 对应阶段/审查步=铁律7
+
+---
+
+## 相比V2.0增补内容
+- ✅阶段一新增工作模式定义（强制出口）
+- ✅新增阶段二：拓扑从零构建与独立论证（电源树+压降审查+路径隔离）
+- ✅阶段三强化：电源完整性审查+复位/EN时序审查为强制项
+- ✅新增阶段四：分模块验证（独立于整体审视）
+- ✅阶段五强化：总线/接口完整性审查
+- ✅阶段十一强化：电源分步上电法
+- ✅铁律增至20条，新增模块整体分合/参考设计论证/方法论迭代等
+- ✅踩坑记录增补5条（模块整体/PDF图表/拓扑惯性/工作模式/电源树/参考设计）
+- ✅整体审视与模块验证明确分离，不再混做
@@ -0,0 +1,64 @@
+# SMT下单踩坑记录
+
+> **类别：trap** | **芯片：cross-platform** | **主题：SMT下单踩坑 (封装选错 / 换料费)**
+>
+> 代价：换料费多花几十上百，元件选错封装返工
+
+## 坑1：不查基础库直接选扩展库
+
+嘉立创器件库分三级，换料费差距巨大：
+- 基础库：0元/种
+- 推荐库：¥5/种
+- 扩展库：¥20(编带)/¥30(管装)/种
+
+每次下单全量计费，无复购减免。5片小单换料费能占总成本30%+。
+
+**省费案例：**
+- R8从扩展库0.1Ω换成C25334基础库100mΩ——省¥20
+- SW2/SW3从C561516换成C720477基础库——省¥20
+- AO3400A C20917本身就是基础库，别选错成扩展库版本——省¥20
+- GBC版总计省¥60换料费
+
+## 坑2：大功率电阻基础库没有
+
+0805及以下封装的电阻基础库很全，但1206以上大功率电阻基本没有。
+
+**对策：** 大功率负载电阻手焊不进SMT（2Ω 5W绕线/5Ω 2W金属氧化膜），淘宝几毛钱一个。
+
+## 坑3：连接器占换料费大头
+
+XH4P插座每个¥20，GBC版3个就¥60。
+
+**对策：** NES版砍掉所有XH插座，OLED/电池座/开关全用焊盘直焊+飞线外接，省掉连接器换料费+省板面空间。
+
+## 坑4：经济型SMT规则
+
+- 无钢网费·无需工艺边和Mark点·最小支持10×10mm板
+- 非经济型需工艺边+Mark点+钢网费
+- 拼板用邮票孔，禁V-CUT
+- 只贴单面
+- SMT必选¥3工程核验
+
+## 坑5：扩展库有货直接贴
+
+扩展库有现货的直接交换料费贴片，不用自己买元件寄仓库。只有私有库才需要自购寄仓（耗时一两周）。
+
+## 铁律
+
+- 选型先搜基础库，搜不到再考虑扩展库
+- 连接器能用焊盘替代就用焊盘
+- 大功率电阻手焊
+- 下单前逐个确认嘉立创编号与EDA一致
+
+
+## 坑6：MOS管选型—参数好≠选它（2026-07-11）
+
+### 案例：AO3400A vs IRLML2502
+
+- 参数：AO3400A=够用(Vgs=3V3开透、Rds=30mΩ), IRLML2502 (IR/Infineon)=更好(Vgs一致性高、Rds标称更准、内置ESD)
+- 嘉立创库：AO3400A=**基础库**，几毛钱, IRLML2502 (IR/Infineon)=扩展库，加钱
+- 断货风险：AO3400A=基础库大批量不断货, IRLML2502 (IR/Infineon)=扩展库可能缺货还得换
+
+**决策：试水阶段(首批20-30台)选AO3400A，基础库稳比参数好重要。**
+
+> 量产选型权衡：参数余量 vs 采购成本。以后量大了再考虑扩展库也不迟。
@@ -0,0 +1,318 @@
+# ESP32 GPIO Pin Reference
+
+> **类别：reference** | **主题：ESP32 GPIO 引脚完整参考** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## Table of Contents
+
+- [ESP32 GPIO Model Overview](#esp32-gpio-model-overview)
+- [Pin Categories Summary](#pin-categories-summary)
+- [Complete GPIO Pin Table](#complete-gpio-pin-table)
+- [Flash and PSRAM Reservations](#flash-and-psram-reservations)
+  - [GPIO6-11: SPI Flash (NEVER USE)](#gpio6-11-spi-flash-never-use)
+  - [GPIO16-17: PSRAM (WROVER Only)](#gpio16-17-psram-wrover-only)
+- [Protocol Pin Groups](#protocol-pin-groups)
+  - [I2C (Conventional Defaults)](#i2c-conventional-defaults)
+  - [SPI Buses](#spi-buses)
+  - [UARTs](#uarts)
+  - [PWM (LEDC)](#pwm-ledc)
+  - [1-Wire](#1-wire)
+  - [DAC (Digital-to-Analog)](#dac-digital-to-analog)
+- [ADC Channel Mapping](#adc-channel-mapping)
+  - [ADC1 (Always Available — Even with WiFi)](#adc1-always-available--even-with-wifi)
+  - [ADC2 (UNAVAILABLE When WiFi Active)](#adc2-unavailable-when-wifi-active)
+- [Touch Channel Mapping](#touch-channel-mapping)
+- [RTC GPIO Mapping](#rtc-gpio-mapping)
+- [Variant Comparison Table](#variant-comparison-table)
+  - [Key Variant Notes](#key-variant-notes)
+
+---
+
+## ESP32 GPIO Model Overview
+
+The ESP32 GPIO system differs fundamentally from Raspberry Pi:
+
+- **GPIO Matrix:** Most peripherals can be routed to any GPIO through the GPIO matrix, providing flexible pin assignment (unlike RPi's fixed ALT functions)
+- **Special Pin Categories:** Certain pins have hardware restrictions — strapping pins affect boot behavior, flash pins are never usable, input-only pins cannot drive outputs
+- **Variable Capabilities:** Not all GPIOs have the same features — ADC, touch sensing, DAC, and RTC wake capabilities vary by pin
+- **Variant Differences:** ESP32 variants (S2, S3, C3, C6) have different GPIO counts, capabilities, and restrictions
+
+**Default Reference:** This document uses **ESP32-WROOM-32** as the primary reference module unless otherwise noted.
+
+---
+
+## Pin Categories Summary
+
+- **Freely Usable**：GPIOs=4, 13, 14, 16*, 17*, 18, 19, 21, 22, 23, 25, 26, 27, 32, 33, Count=15, Usage=No restrictions, safe for any purpose
+- **Strapping (use with caution)**：GPIOs=0, 2, 5, 12, 15, Count=5, Usage=Affect boot behavior — safe after boot
+- **Flash Reserved**：GPIOs=6, 7, 8, 9, 10, 11, Count=6, Usage=NEVER use — connected to SPI flash
+- **PSRAM Reserved**：GPIOs=16, 17, Count=2, Usage=Reserved on WROVER, free on WROOM
+- **Input Only**：GPIOs=34, 35, 36, 39, Count=4, Usage=Cannot output, no internal pulls
+- **Not Exposed**：GPIOs=20, 24, 28-31, 37, 38, Count=8, Usage=Not available on WROOM-32 module
+
+*GPIO16/17 are usable on WROOM but reserved for PSRAM on WROVER modules.
+
+---
+
+## Complete GPIO Pin Table
+
+Reference for ESP32-WROOM-32 module, GPIOs 0-39:
+
+- 0：Strapping=YES (boot mode), Reserved=No, I/O=I/O, ADC=ADC2_CH1, Touch=TOUCH1, RTC=RTC_GPIO11, Notes=LOW=download mode; safe after boot
+- 1：Strapping=No, Reserved=No*, I/O=I/O, Notes=UART0 TX — avoid (USB serial)
+- 2：Strapping=YES (boot mode), Reserved=No, I/O=I/O, ADC=ADC2_CH2, Touch=TOUCH2, RTC=RTC_GPIO12, Notes=Often onboard LED; safe after boot
+- 3：Strapping=No, Reserved=No*, I/O=I/O, Notes=UART0 RX — avoid (USB serial)
+- 4：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC2_CH0, Touch=TOUCH0, RTC=RTC_GPIO10, Notes=Clean — commonly used for 1-Wire
+- 5：Strapping=YES (SDIO timing), Reserved=No, I/O=I/O, Notes=Internal pull-up; VSPI CS default
+- 6：Strapping=No, Reserved=FLASH, I/O=I/O, Notes=**NEVER USE** — SPI flash CLK
+- 7：Strapping=No, Reserved=FLASH, I/O=I/O, Notes=**NEVER USE** — SPI flash D0
+- 8：Strapping=No, Reserved=FLASH, I/O=I/O, Notes=**NEVER USE** — SPI flash D1
+- 9：Strapping=No, Reserved=FLASH, I/O=I/O, Notes=**NEVER USE** — SPI flash D2
+- 10：Strapping=No, Reserved=FLASH, I/O=I/O, Notes=**NEVER USE** — SPI flash D3
+- 11：Strapping=No, Reserved=FLASH, I/O=I/O, Notes=**NEVER USE** — SPI flash CMD
+- 12：Strapping=**YES (MTDI)**, Reserved=No, I/O=I/O, ADC=ADC2_CH5, Touch=TOUCH5, RTC=RTC_GPIO15, Notes=**DANGER:** flash voltage select — see esp32-specifics.md
+- 13：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC2_CH4, Touch=TOUCH4, RTC=RTC_GPIO14, Notes=HSPI MOSI default
+- 14：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC2_CH6, Touch=TOUCH6, RTC=RTC_GPIO16, Notes=HSPI CLK default
+- 15：Strapping=YES (MTDO), Reserved=No, I/O=I/O, ADC=ADC2_CH3, Touch=TOUCH3, RTC=RTC_GPIO13, Notes=Debug log control; HSPI CS default
+- 16：Strapping=No, Reserved=PSRAM*, I/O=I/O, Notes=Free on WROOM; reserved on WROVER
+- 17：Strapping=No, Reserved=PSRAM*, I/O=I/O, Notes=Free on WROOM; reserved on WROVER
+- 18：Strapping=No, Reserved=No, I/O=I/O, Notes=VSPI CLK default
+- 19：Strapping=No, Reserved=No, I/O=I/O, Notes=VSPI MISO default
+- 20：Strapping=No, Reserved=Not exposed, I/O=I/O, Notes=Not available on WROOM-32
+- 21：Strapping=No, Reserved=No, I/O=I/O, Notes=I2C SDA default
+- 22：Strapping=No, Reserved=No, I/O=I/O, Notes=I2C SCL default
+- 23：Strapping=No, Reserved=No, I/O=I/O, Notes=VSPI MOSI default
+- 24：Strapping=No, Reserved=Not exposed, I/O=I/O, Notes=Not available on WROOM-32
+- 25：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC2_CH8, RTC=RTC_GPIO6, Notes=DAC1 output
+- 26：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC2_CH9, RTC=RTC_GPIO7, Notes=DAC2 output
+- 27：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC2_CH7, Touch=TOUCH7, RTC=RTC_GPIO17, Notes=Clean GPIO
+- 28：Strapping=No, Reserved=Not exposed, I/O=I/O, Notes=Not available on WROOM-32
+- 29：Strapping=No, Reserved=Not exposed, I/O=I/O, Notes=Not available on WROOM-32
+- 30：Strapping=No, Reserved=Not exposed, I/O=I/O, Notes=Not available on WROOM-32
+- 31：Strapping=No, Reserved=Not exposed, I/O=I/O, Notes=Not available on WROOM-32
+- 32：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC1_CH4, Touch=TOUCH9, RTC=RTC_GPIO9, Notes=ADC1 — works with WiFi
+- 33：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC1_CH5, Touch=TOUCH8, RTC=RTC_GPIO8, Notes=ADC1 — works with WiFi
+- 34：Strapping=No, Reserved=No, I/O=**INPUT**, ADC=ADC1_CH6, RTC=RTC_GPIO4, Notes=Input only, no internal pulls
+- 35：Strapping=No, Reserved=No, I/O=**INPUT**, ADC=ADC1_CH7, RTC=RTC_GPIO5, Notes=Input only, no internal pulls
+- 36：Strapping=No, Reserved=No, I/O=**INPUT**, ADC=ADC1_CH0, RTC=RTC_GPIO0, Notes=Input only (SENSOR_VP)
+- 37：Strapping=No, Reserved=Not exposed, I/O=**INPUT**, ADC=ADC1_CH1, RTC=RTC_GPIO1, Notes=Not available on WROOM-32
+- 38：Strapping=No, Reserved=Not exposed, I/O=**INPUT**, ADC=ADC1_CH2, RTC=RTC_GPIO2, Notes=Not available on WROOM-32
+- 39：Strapping=No, Reserved=No, I/O=**INPUT**, ADC=ADC1_CH3, RTC=RTC_GPIO3, Notes=Input only (SENSOR_VN)
+
+---
+
+## Flash and PSRAM Reservations
+
+### GPIO6-11: SPI Flash (NEVER USE)
+
+These pins are hardwired to the SPI flash chip on all ESP32 modules:
+
+- GPIO6：Flash Function=SPICLK, Result if Used=Chip crash/hang
+- GPIO7：Flash Function=SPIQ (D0), Result if Used=Chip crash/hang
+- GPIO8：Flash Function=SPID (D1), Result if Used=Chip crash/hang
+- GPIO9：Flash Function=SPIHD (D2), Result if Used=Chip crash/hang
+- GPIO10：Flash Function=SPIWP (D3), Result if Used=Chip crash/hang
+- GPIO11：Flash Function=SPICS0 (CMD), Result if Used=Chip crash/hang
+
+**Rule:** Never assign GPIO6-11 for any purpose. Attempting to use them will crash the chip immediately.
+
+### GPIO16-17: PSRAM (WROVER Only)
+
+- WROOM-32：GPIO16=Usable, GPIO17=Usable, Reason=No PSRAM on module
+- WROVER：GPIO16=Reserved, GPIO17=Reserved, Reason=Connected to PSRAM
+- WROVER-B：GPIO16=Reserved, GPIO17=Reserved, Reason=Connected to PSRAM
+- WROOM-32E：GPIO16=Usable, GPIO17=Usable, Reason=No PSRAM on module
+
+**Rule:** Always check module type. If using WROVER, avoid GPIO16/17.
+
+---
+
+## Protocol Pin Groups
+
+### I2C (Conventional Defaults)
+
+Unlike Raspberry Pi, ESP32 I2C can use any GPIO via the GPIO matrix:
+
+- SDA：Default GPIO=GPIO21, Notes=Convention only — any GPIO works
+- SCL：Default GPIO=GPIO22, Notes=Convention only — any GPIO works
+
+**Usage:**
+```cpp
+// Arduino
+Wire.begin(21, 22);  // SDA, SCL
+
+// ESP-IDF
+i2c_config_t conf = {
+    .sda_io_num = 21,
+    .scl_io_num = 22,
+    // ...
+};
+```
+
+**Note:** Do not use input-only pins (34-39) for I2C — they cannot drive the bus.
+
+### SPI Buses
+
+ESP32 has two user-accessible SPI buses:
+
+**VSPI (SPI3) — Recommended:**
+
+- MOSI：GPIO=GPIO23
+- MISO：GPIO=GPIO19
+- SCLK：GPIO=GPIO18
+- CS：GPIO=GPIO5, Notes=Strapping pin — safe after boot
+
+**HSPI (SPI2) — Use with caution:**
+
+- MOSI：GPIO=GPIO13
+- MISO：GPIO=GPIO12, Notes=**DANGER:** Strapping pin — see esp32-specifics.md
+- SCLK：GPIO=GPIO14
+- CS：GPIO=GPIO15, Notes=Strapping pin — safe after boot
+
+**Warning:** HSPI uses GPIO12 which is a dangerous strapping pin. Prefer VSPI unless you specifically need both SPI buses.
+
+### UARTs
+
+- UART0：TX=GPIO1, RX=GPIO3, Notes=USB serial — avoid unless needed
+- UART1：TX=Any, RX=Any, Notes=Fully remappable via GPIO matrix
+- UART2：TX=Any, RX=Any, Notes=Fully remappable via GPIO matrix
+
+**Common UART1/UART2 assignments:**
+- UART1: GPIO4 (TX), GPIO5 (RX)
+- UART2: GPIO16 (TX), GPIO17 (RX) — if not WROVER
+
+### PWM (LEDC)
+
+ESP32 PWM uses the LEDC peripheral, which can output to any GPIO:
+
+- **Channels:** 16 (8 high-speed, 8 low-speed)
+- **Resolution:** 1-16 bits
+- **Frequency:** Up to 40MHz (hardware dependent on duty resolution)
+- **Any output-capable GPIO works** — no fixed PWM pins like RPi
+
+**Rule:** Cannot use input-only pins (34-39) for PWM output.
+
+### 1-Wire
+
+- **Common Pin:** GPIO4 (by convention)
+- **Flexibility:** Any GPIO with output capability
+- **Pull-up:** Requires 4.7kΩ external pull-up to 3.3V
+
+### DAC (Digital-to-Analog)
+
+- DAC1：GPIO=GPIO25, Notes=8-bit resolution
+- DAC2：GPIO=GPIO26, Notes=8-bit resolution
+
+**Note:** DAC is only available on original ESP32 and ESP32-S2. Not available on S3, C3, or C6.
+
+---
+
+## ADC Channel Mapping
+
+### ADC1 (Always Available — Even with WiFi)
+
+- ADC1_CH0：GPIO=GPIO36, Notes=Input only (SENSOR_VP)
+- ADC1_CH1：GPIO=GPIO37, Notes=Not on WROOM-32
+- ADC1_CH2：GPIO=GPIO38, Notes=Not on WROOM-32
+- ADC1_CH3：GPIO=GPIO39, Notes=Input only (SENSOR_VN)
+- ADC1_CH4：GPIO=GPIO32, Notes=Full I/O
+- ADC1_CH5：GPIO=GPIO33, Notes=Full I/O
+- ADC1_CH6：GPIO=GPIO34, Notes=Input only
+- ADC1_CH7：GPIO=GPIO35, Notes=Input only
+
+**Design Rule:** Use ADC1 channels for analog inputs in WiFi projects.
+
+### ADC2 (UNAVAILABLE When WiFi Active)
+
+- ADC2_CH0：GPIO=GPIO4
+- ADC2_CH1：GPIO=GPIO0, Notes=Strapping pin
+- ADC2_CH2：GPIO=GPIO2, Notes=Strapping pin
+- ADC2_CH3：GPIO=GPIO15, Notes=Strapping pin
+- ADC2_CH4：GPIO=GPIO13
+- ADC2_CH5：GPIO=GPIO12, Notes=**DANGER:** Strapping pin
+- ADC2_CH6：GPIO=GPIO14
+- ADC2_CH7：GPIO=GPIO27
+- ADC2_CH8：GPIO=GPIO25, Notes=Also DAC1
+- ADC2_CH9：GPIO=GPIO26, Notes=Also DAC2
+
+**Warning:** ADC2 returns invalid readings when WiFi or Bluetooth is active. See esp32-specifics.md for details.
+
+---
+
+## Touch Channel Mapping
+
+ESP32 has 10 capacitive touch sensing channels:
+
+- TOUCH0：GPIO=GPIO4
+- TOUCH1：GPIO=GPIO0, Notes=Strapping pin
+- TOUCH2：GPIO=GPIO2, Notes=Strapping pin
+- TOUCH3：GPIO=GPIO15, Notes=Strapping pin
+- TOUCH4：GPIO=GPIO13
+- TOUCH5：GPIO=GPIO12, Notes=**DANGER:** Strapping pin
+- TOUCH6：GPIO=GPIO14
+- TOUCH7：GPIO=GPIO27
+- TOUCH8：GPIO=GPIO33, Notes=Also ADC1
+- TOUCH9：GPIO=GPIO32, Notes=Also ADC1
+
+**Notes:**
+- Touch sensing works in deep sleep via ULP coprocessor
+- ESP32-C3 and C6 do NOT have touch sensing capability
+- External components on touch pins affect sensitivity
+
+---
+
+## RTC GPIO Mapping
+
+RTC GPIOs can wake the ESP32 from deep sleep and be controlled by the ULP coprocessor:
+
+- RTC_GPIO0：GPIO=GPIO36, ADC=ADC1_CH0, Notes=Input only (SENSOR_VP)
+- RTC_GPIO1：GPIO=GPIO37, ADC=ADC1_CH1, Notes=Not on WROOM-32
+- RTC_GPIO2：GPIO=GPIO38, ADC=ADC1_CH2, Notes=Not on WROOM-32
+- RTC_GPIO3：GPIO=GPIO39, ADC=ADC1_CH3, Notes=Input only (SENSOR_VN)
+- RTC_GPIO4：GPIO=GPIO34, ADC=ADC1_CH6, Notes=Input only
+- RTC_GPIO5：GPIO=GPIO35, ADC=ADC1_CH7, Notes=Input only
+- RTC_GPIO6：GPIO=GPIO25, ADC=ADC2_CH8, Notes=DAC1
+- RTC_GPIO7：GPIO=GPIO26, ADC=ADC2_CH9, Notes=DAC2
+- RTC_GPIO8：GPIO=GPIO33, ADC=ADC1_CH5, Touch=TOUCH8
+- RTC_GPIO9：GPIO=GPIO32, ADC=ADC1_CH4, Touch=TOUCH9
+- RTC_GPIO10：GPIO=GPIO4, ADC=ADC2_CH0, Touch=TOUCH0
+- RTC_GPIO11：GPIO=GPIO0, ADC=ADC2_CH1, Touch=TOUCH1, Notes=Strapping
+- RTC_GPIO12：GPIO=GPIO2, ADC=ADC2_CH2, Touch=TOUCH2, Notes=Strapping
+- RTC_GPIO13：GPIO=GPIO15, ADC=ADC2_CH3, Touch=TOUCH3, Notes=Strapping
+- RTC_GPIO14：GPIO=GPIO13, ADC=ADC2_CH4, Touch=TOUCH4
+- RTC_GPIO15：GPIO=GPIO12, ADC=ADC2_CH5, Touch=TOUCH5, Notes=**DANGER:** Strapping
+- RTC_GPIO16：GPIO=GPIO14, ADC=ADC2_CH6, Touch=TOUCH6
+- RTC_GPIO17：GPIO=GPIO27, ADC=ADC2_CH7, Touch=TOUCH7
+
+**Deep Sleep Wake Sources:**
+- EXT0: Single RTC GPIO, level-triggered
+- EXT1: Multiple RTC GPIOs, any-high or all-low trigger
+- Touch pad wake: Any touch channel
+- ULP coprocessor: Programmable wake conditions
+
+---
+
+## Variant Comparison Table
+
+- **CPU Architecture**：ESP32=Xtensa LX6, ESP32-S2=Xtensa LX7, ESP32-S3=Xtensa LX7, ESP32-C3=RISC-V, ESP32-C6=RISC-V
+- **CPU Cores**：ESP32=2, ESP32-S2=1, ESP32-S3=2, ESP32-C3=1, ESP32-C6=1
+- **GPIO Count**：ESP32=34 (0-39), ESP32-S2=43, ESP32-S3=45, ESP32-C3=22 (0-21), ESP32-C6=30
+- **ADC Channels**：ESP32=18, ESP32-S2=20, ESP32-S3=20, ESP32-C3=6, ESP32-C6=7
+- **ADC2/WiFi Conflict**：ESP32=Yes, ESP32-S2=Yes, ESP32-S3=Yes, ESP32-C3=**No**, ESP32-C6=**No**
+- **Touch Channels**：ESP32=10, ESP32-S2=14, ESP32-S3=14, ESP32-C3=**None**, ESP32-C6=**None**
+- **DAC Channels**：ESP32=2, ESP32-S2=2, ESP32-S3=**None**, ESP32-C3=**None**, ESP32-C6=**None**
+- **USB OTG**：ESP32=No, ESP32-S2=Yes (GPIO19/20), ESP32-S3=Yes (GPIO19/20), ESP32-C3=No, ESP32-C6=No
+- **Bluetooth**：ESP32=Classic + BLE, ESP32-S2=**None**, ESP32-S3=BLE 5.0, ESP32-C3=BLE 5.0, ESP32-C6=BLE 5.0
+- **WiFi**：ESP32=802.11 b/g/n, ESP32-S2=802.11 b/g/n, ESP32-S3=802.11 b/g/n, ESP32-C3=802.11 b/g/n, ESP32-C6=**802.11ax (WiFi 6)**
+- **Thread/Zigbee**：ESP32=No, ESP32-S2=No, ESP32-S3=No, ESP32-C3=No, ESP32-C6=**Yes**
+- **Flash Pins**：ESP32=GPIO6-11, ESP32-S2=GPIO26-32, ESP32-S3=GPIO26-32, ESP32-C3=GPIO12-17, ESP32-C6=GPIO24-29
+- **Strapping Pins**：ESP32=0, 2, 5, 12, 15, ESP32-S2=0, 45, 46, ESP32-S3=0, 3, 45, 46, ESP32-C3=2, 8, 9, ESP32-C6=8, 9, 15
+
+### Key Variant Notes
+
+- **ESP32-C3/C6:** No ADC2/WiFi conflict — all ADC channels work with WiFi
+- **ESP32-S2/S3:** USB OTG requires GPIO19/20 — reserve if using native USB
+- **ESP32-C6:** Only variant with WiFi 6 and Thread/Zigbee support
+- **Touch sensing:** Only original ESP32, S2, and S3 have capacitive touch
+- **DAC:** Only original ESP32 and S2 have analog output capability
+
+---
@@ -0,0 +1,145 @@
+# ESP32 Specifics Reference
+
+> **类别：reference** | **主题：ESP32 架构深度参考 (MMU/Strapping/ADC/RTC)** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
+
+## Table of Contents
+
+- [1. Hardware Architecture & Chip Families](#1-hardware-architecture--chip-families)
+- [2. Memory Management Unit (MMU) & Heap Allocation](#2-memory-management-unit-mmu--heap-allocation)
+- [3. Peripherals, Timers & Interrupts](#3-peripherals-timers--interrupts)
+- [4. Strapping Pins Deep Dive](#4-strapping-pins-deep-dive)
+- [5. ADC2/WiFi Conflict Explained](#5-adc2wifi-conflict-explained)
+- [6. Flash and PSRAM Pin Details](#6-flash-and-psram-pin-details)
+- [7. Input-Only Pins](#7-input-only-pins)
+- [8. RTC Domain and Deep Sleep](#8-rtc-domain-and-deep-sleep)
+
+---
+
+## 1. Hardware Architecture & Chip Families
+
+When advising on hardware selection, apply the following matrix of architectures, wireless protocols, and target use cases:
+
+* **ESP32 (Original):** Dual-core Xtensa LX6, 240 MHz, Wi-Fi 4, BT Classic, BLE 4.2. Best for legacy projects requiring Bluetooth Classic.
+* **ESP32-S2:** Single-core Xtensa LX7, 240 MHz, Wi-Fi 4. Best for ultra-low power and USB OTG/HID.
+* **ESP32-S3 (Performance):** Dual-core Xtensa LX7, 240 MHz, Wi-Fi 4, BLE 5.0. Features Vector instructions for AI/ML and complex GUIs.
+* **ESP32-C2:** Single-core RISC-V, 120 MHz, Wi-Fi 4, BLE 5.0. Cost-sensitive ESP8266 replacements.
+* **ESP32-C3 (Connectivity):** Single-core RISC-V, 160 MHz, Wi-Fi 4, BLE 5.0. Standard budget IoT node.
+* **ESP32-C5:** Single-core RISC-V, 240 MHz, Dual-band Wi-Fi 6 (2.4/5GHz), BLE 5, Zigbee/Thread.
+* **ESP32-C6:** Single-core RISC-V, 160 MHz, Wi-Fi 6 (2.4GHz), BLE 5.3, Zigbee/Thread. Next-gen Matter/mesh nodes.
+* **ESP32-H2 (Hub/Home):** Single-core RISC-V, 96 MHz, BLE 5.0, Zigbee/Thread. *Crucial Note: No Wi-Fi*.
+* **ESP32-P4 (Powerhouse):** Dual-core RISC-V, 400 MHz. *Crucial Note: No wireless capabilities*. Features H.264 encoding, dual MIPI, and heavy multimedia processing.
+
+---
+
+## 2. Memory Management Unit (MMU) & Heap Allocation
+
+Understand the complex memory hierarchy managed by the MMU:
+
+* **DRAM (Data RAM):** Holds standard variables and the heap. Single-byte accessible (`MALLOC_CAP_8BIT`).
+* **IRAM (Instruction RAM):** Strictly holds executable code operating at full CPU speed. Code handling interrupts or flash writes MUST reside here. Generic access requires 32-bit alignment (`MALLOC_CAP_32BIT`).
+* **D/IRAM:** Flexible RAM usable dynamically on both data and instruction buses.
+* **RTC Memory:** Fast memory runs the ULP coprocessor; Slow memory holds `RTC_DATA_ATTR` variables during Deep Sleep.
+* **PSRAM (Pseudo-Static RAM):** External/integrated RAM mapped to virtual address space for heavy workloads.
+* **Heap Allocation:** Use capabilities-based allocation: `heap_caps_malloc(size, MALLOC_CAP_DMA)` for hardware DMA, `MALLOC_CAP_SPIRAM` for external PSRAM, and `MALLOC_CAP_SIMD` for 16-byte aligned SIMD operations.
+
+---
+
+## 3. Peripherals, Timers & Interrupts
+
+### Timers & Watchdogs
+* **GPTimer:** In ESP-IDF v5.0+, the legacy Timer Group is deprecated and replaced by GPTimer (`gptimer.h`). Requires `gptimer_config_t` (clock source, direction, resolution). Operations include `gptimer_start()`, `stop()`, and `set_raw_count()`.
+* **Watchdog Timers:** Interrupt WDT (IWDT) monitors CPU stalls from long ISRs. Task WDT (TWDT) triggers if a task fails to yield via `vTaskDelay`.
+
+### Interrupt Architecture
+* **Xtensa:** Uses internal Xtensa controller (High-level assembly, Low-level C).
+* **RISC-V:** Uses standard PLIC and CLIC.
+* **Interrupt Matrix:** Maps physical hardware interrupts to specific CPU lines (Core 0 vs Core 1).
+
+### Specialized Peripherals & Accelerators
+* **Comm Interfaces:** I2S (digital audio/PDM), TWAI (CAN 2.0B bus), USB-OTG (S2/S3 Host/Device), USB-Serial/JTAG (C3, C6, S3, H2 direct OpenOCD debug).
+* **Motor/Lighting:** LEDC (Hardware PWM), MCPWM (Advanced BLDC driving, dead-time), PCNT (Quadrature encoders).
+* **P-Series / S-Series Accelerators:** Hardware JPEG/H.264 codecs, ISP for MIPI cameras, PPA pixel blending, GDMA engines, Crypto/TRNG accelerators for Secure Boot.
+
+---
+
+## 4. Strapping Pins Deep Dive
+
+ESP32 reads the state of five GPIO pins at boot to determine operating mode. These pins are safe to use for other purposes after boot completes, but their state at reset/power-on matters.
+
+### GPIO0 — Boot Mode Selection
+
+- HIGH (default)：Result=Normal execution from flash
+- LOW：Result=Download mode (firmware upload via UART)
+
+**Details:**
+- Has internal pull-up resistor (default HIGH)
+- Safe to use after boot for any function
+- Commonly used for: buttons, capacitive touch, general I/O
+
+**Warning:** If using GPIO0 as a button input, ensure it is not held LOW during reset/power-on, or the chip will enter download mode instead of running your program.
+
+---
+
+### GPIO12 (MTDI) — DANGER — Flash Voltage Selection
+
+- **LOW (required)**：Result=3.3V flash voltage — CORRECT for most modules
+- **HIGH**：Result=1.8V flash voltage — WILL FAIL TO BOOT on 3.3V flash modules
+
+**THIS IS THE MOST DANGEROUS STRAPPING PIN**
+
+**Safe usage patterns:**
+- Use external pull-DOWN resistor if GPIO12 must be used
+- Ensure any connected device doesn't drive HIGH during boot
+- Use `espefuse.py` to permanently set flash voltage (irreversible)
+
+**Recovery from "bricked" state:**
+1. Disconnect anything from GPIO12
+2. Add pull-down resistor (10kΩ to GND) if needed
+3. Hold GPIO0 LOW
+4. Power cycle the module
+5. Flash should now be accessible via esptool
+
+---
+
+## 5. ADC2/WiFi Conflict Explained
+
+### The Problem
+ADC2 shares internal hardware resources with the WiFi RF calibration and transmission circuits. When WiFi (or Bluetooth on original ESP32) is active, ADC2 readings are unreliable or completely invalid.
+
+### ADC1 Channels (Always Safe)
+ADC1 has its own dedicated hardware and works regardless of WiFi state:
+- **GPIO32-39** (Original ESP32)
+
+### Variants Without This Conflict
+- **ESP32-C3:** Single ADC, always available
+- **ESP32-C6:** Single ADC, always available
+
+---
+
+## 6. Flash and PSRAM Pin Details
+
+### SPI Flash Pins (GPIO6-11) — NEVER USE
+These pins are hardwired to the SPI flash memory chip inside the module. Using them will immediately crash the ESP32.
+
+### PSRAM Pins (GPIO16-17) — WROVER Only
+ESP32-WROVER modules include onboard PSRAM that uses GPIO16 and GPIO17.
+
+---
+
+## 7. Input-Only Pins
+
+### GPIO34, 35, 36, 39 — Hardware Limitations
+These four pins CANNOT be used for digital output, I2C, SPI MOSI/SCLK, or UART TX. They have no internal pull resistors.
+
+---
+
+## 8. RTC Domain and Deep Sleep
+
+### RTC GPIO Overview
+Only specific GPIOs can function during deep sleep or wake the ESP32 from deep sleep.
+
+**Deep Sleep Wake Sources:**
+- EXT0: Single RTC GPIO, level-triggered
+- EXT1: Multiple RTC GPIOs
+- Touch pad wake
+- ULP coprocessor
@@ -0,0 +1,385 @@
+---
+name: 通用型电路审查SKILL
+version: "6.6"
+description: "通用型电路审查专家：两阶段八流程审查方法论。设计期（画图前）审查拓扑逻辑+元件选型+边界推演；画图后期（有PCB网表）审查网表对齐+增量验证。适用场景：电路原理图审查、PCB设计验证、硬件方案评审、拓扑逻辑检查。Use when user needs: 电路审查、原理图审查、PCB审查、电源审查、网表验证、硬件设计评审、拓扑检查、电路审核、BOM审查、Layout审查。"
+---
+
+# 电路审查专家
+
+你是一个电路审查专家，遵循严格的两阶段八流程审查方法论。你的目标是在画图前为设计排雷，在画图后为网表兜底。
+
+## 两阶段架构
+
+| 阶段 | 条件 | 输入 | 目的 |
+|------|------|------|------|
+| **设计期** | 画图前，无网表 | 方案文档 + 拓扑连接图 + 知识库 | 拓扑逻辑+元件选型+边界推演，画图前排雷 |
+| **画图后期** | 有PCB网表后 | 全部 + PCB网表 | 网表对齐+增量验证，画图后兜底 |
+
+> 设计期跑阶段0~4+6(仅电气+硬固接口+功能完整性三维度)+7；画图后期跑阶段5+6(全)+7，阶段0~4仅增量（仅增量=跳过已有结论且未修改的部分，复用已有结论须标注来源版本号，重新验证已修改部分及受影响关联项）
+
+**执行路由表：**
+
+| 用户指令 | 实际执行 |
+|----------|----------|
+| "从头审" | 设计期：0→1→2→3→4→6(三维度)→7；画图后期：0~4(仅增量)→5→6(全)→7 |
+| "审网表" / "跑阶段5" | 5→6(全)→7 |
+| "补审XX" | 指定阶段N→7（N须明确指定） |
+| "续跑" | 用户指定起始阶段N→往后顺序执行→7 |
+
+## 输入文件
+
+| 文件 | 命名规范 | 格式 | 来源 | 哪阶段用 |
+|------|----------|------|------|----------|
+| 方案文档 | `{项目名}_V{版本}_方案文档.md` | .md | 项目管理系统 | 全阶段 |
+| 拓扑连接图 | `{项目名}_V{版本}_拓扑连接图.md` | .md | 项目管理系统 | 全阶段 |
+| 知识库 | `{项目归档目录}\知识库\` | 目录 | 用户整理 | 全阶段 |
+| PCB网表 | EDA导出 | .net | 画图后期 | 阶段5 |
+| 原理图截图 | 导出/截图 | .png/.jpg | 用户截取 | 降级参考 |
+
+**知识库路径**：`{工作区根目录}\{项目名}\知识库\`
+
+**原理图图片降级策略**：无PCB网表时，用户可提供原理图截图作为参考，但AI识图不到Pin级，仅能做模块级/连接关系级辅助判断，Pin级验证仍须等网表。
+
+**知识库内容**（按项目独立，不混）：
+- IC datasheet/速查卡
+- 有datasheet的特殊器件（非标件、扩展库特殊阻容等）
+- 特殊接法件（如开尔文采样、差分走线等有独立电气要求的）
+- **不进库**：通用阻容（参数值就能说明白的）
+
+## 八阶段审查流程
+
+### 阶段0：技术文档锁定（前提门槛）
+
+**核心：文档不到场，审查不启动。**
+
+1. 从BOM清单提取所有IC型号（BOM位置以用户提供为准，可能在拓扑连接图内也可能是独立BOM文件），在知识库目录下递归搜索datasheet/速查卡（模糊匹配：型号缩略/大小写/横线变体都覆盖；匹配边界=型号前缀+核心数字，后缀仅作辅助，如ESP32-S3匹配ESP32S3/ESP32_S3，但不匹配ESP32-C3。前缀+核心数字匹配即视为文档命中，完整型号差异在阶段3元件对齐时用具体datasheet核对）
+2. **判定"关键IC"**：满足任一条件即为关键IC —— 需要外部时钟/时序才能运行的MCU和通信IC、有必接外围电路（晶振/电感/变压器/功率管/反馈网络等非通用阻容的功能性外围，不包括上拉/下拉/去耦等通用偏置）才能工作的电源管理IC/电机驱动、引脚功能需通过外部配置/strapping决定工作模式的ADC/DAC/传感器
+3. **以下豁免文档锁定**：单一功能IC（基准源/逻辑门/比较器/MOSFET/单一协议转换芯片(电平转换/协议透传无外围配置的)/ESD阵列）
+4. 输出文档清单：
+
+| IC型号 | 是否关键IC | 文档状态 | 搜索关键词 | 文件路径 |
+|--------|-----------|---------|-----------|---------|
+
+5. **有缺失→审查暂停**，输出缺失清单（型号/建议搜索关键词/厂商官网），用户补齐后指定起始阶段续跑
+6. 被动元件不强制datasheet，但BOM中关键参数（精度/额定电压/ESR/温度系数）须从BOM值或本地知识库已有文档确认，不满足则标"待确认"由用户提供
+
+**文档到位后的Pin映射提取：**
+
+**第一批：生存必需引脚（从datasheet取，不看拓扑）**
+
+| 引脚类别 | 必须提取 | 来源 |
+|----------|---------|------|
+| 全部电源引脚 | VDD/VDDIO/VDDA/VDD_USB/VDD_SPI/VBAT等所有电源域 | datasheet Pin Table |
+| 时钟/晶振引脚 | XTAL_N/XTAL_P/EXTCLK | datasheet "System Clock"章节 |
+| 复位/使能引脚 | EN/CHIP_EN/RST/nRST | datasheet Pin Table |
+| Strapping引脚 | BOOT/IO0/IO2/IO5等所有Strapping功能引脚 | datasheet "Strapping Pins"章节 |
+| 调试接口引脚 | SWD/SWDIO/SWCLK/JTAG | datasheet Pin Table |
+| Typical Application图中所有外围引脚 | 对照典型应用电路逐引脚核对 | datasheet "Typical Application"图 |
+
+**第二批：拓扑关联引脚（从拓扑取，对照datasheet确认）**
+
+| 提取方式 | 说明 |
+|----------|------|
+| 拓扑有Pin级列表 | 从拓扑提取，对照datasheet确认功能名/方向/电气特性 |
+| 拓扑只有概括描述 | 如"I2C连MCU"→从datasheet提取SCL/SDA加入此批 |
+
+> 第一批从datasheet取生存必需引脚（不看拓扑，拓扑没提=要抓的问题），第二批从拓扑取功能引脚对照datasheet确认，两批不重复互补。合并后检查引脚复用：同一封装编号被多模块占用→标⚠️冲突。
+
+#### 阶段0硬约束（全阶段必须遵守）
+
+- **禁止引用历史审查结论**：每轮审查视为首次审查，所有结论必须从当前原始网表/原理图逐条验证，不得以"之前已确认""上次查过没问题"为由跳过任何检查项。
+
+### 阶段1：拓扑理解与逻辑验证
+
+**1.1 功能模块分解与信号流**
+
+梳理6条链路信号流向（电源/信号/保护/控制/通信/地线回流），输出预期数据表——电源链路用电源轨预算表（见下方），地线回流用地隔离表（见下方），其余4条链路（信号/保护/控制/通信）用链路模板，每条链路必须有推导值（电压/电流/功率/时序等），拓扑不足以推导标"待澄清"，不猜。其余4条链路输出格式：
+
+
+
+**地域隔离表（1.1必输出，地线回流专用）：**
+
+系统中凡存在多个接地类网络（GND/BATN/AGND/PGND等），必须逐条列出，不允许用"接地"二字替代精确网络名。无多地域的系统（仅单一GND）标注"单地域，无需隔离表"即可。
+
+| 网络名 | 物理含义 | 与系统GND关系 | 中间器件 | 汇接点 |
+|--------|----------|--------------|----------|--------|
+| GND | 系统主地 | 直通 | 无 | 全板 |
+| BATN | 电池负极/保护内侧 | 隔8205A双MOS | U6(8205A) | U5.VSS |
+| AGND | 模拟地 | 隔磁珠/0Ω | FB1 | ADC采样区 |
+
+> **地域隔离铁律（后续所有阶段强制遵守）：** 遇到任何引脚接到"地类网络"，必须报出精确网络名（如BATN、AGND），禁止用"接地""接GND"等笼统描述糊弄。引脚该接的地域与实际网络不一致时标❌错误。典型场景：电池座负极必须接BATN而非GND（接GND=旁路保护电路）；DW01A去耦电容VSS端接BATN而非GND（BATN和GND之间隔着MOS，不是同一个地）。
+>
+> **方案文档地域定义段（必含）：** 当系统存在多个接地类网络时，方案文档的系统架构/电源架构段必须包含地域定义表（网络名/含义/与GND关系），作为审核时引脚接地域的对标依据。方案文档缺失此段→阶段0标注⚠️待补充，补充后才可进入后续阶段。仅单一GND的系统无需此段。
+
+
+
+**电源轨预算表（1.1必输出，电源链路专用）：**
+
+| 电源轨 | 电压范围 | 精度要求 | 最大电流 | 纹波要求 | 来源器件 | 负载清单 |
+
+**1.2 拓扑逻辑验证**
+
+| 检查项 | 防什么错 | 方法 |
+|--------|---------|------|
+| 电源链路完整性 | 中间断链 | 逐轨追踪从源到负载，每个中间节点必须有元件 |
+| 信号流方向 | 输出→输出短路 | 每个电气网络最多1个驱动源（二极管OR-ing/I2C多主等合法例外）；开漏需上拉 |
+| 悬空输入检测 | 噪声/不确定 | 非NC输入必须有驱动源；先查datasheet有无内部上下拉 |
+| 二极管方向 | 反接不保护 | 阴极阳极接法与功能一致 |
+| MOSFET接法 | 源极跟随器误做开关 | D/S/G接法与功能一致 |
+| 并联/串联正确性 | 分流/分压计算错 | 等效值与设计意图一致 |
+| 多电源轨时序 | 上电顺序违反IC要求 | 多电源域系统须检查各轨上电时序是否满足IC要求的先后顺序和延迟 |
+| ADC信号链完整性 | 传感器→ADC链路失配 | 传感器输出范围→信号调理增益→ADC输入范围→参考电压精度全链路匹配 |
+| 多电源/多开关操作状态组合 | 电源选择开关与充电/供电同时接入导致保护被绕过 | 含多电源选择开关(如J2电源开关)/连接器(如USB+电池双输入)的系统，须列出所有开关状态组合矩阵(闭合×断开×USB插入×拔出×电池在位×不在位)，推演每种组合下的供电路径，确认充电IC/保护IC不被绕过 |
+
+### 阶段2：基础完整性检查
+
+**核心：先查"有没有"再查"对不对"。**
+
+**执行分支：**
+- 含MCU → 逐项过1-15
+- 含FPGA → MCU专项替换为FPGA专项（JTAG配置链/电源排序/配置存储器），其余共用项照过
+- 无处理器（纯模拟/电源板） → 跳过MCU专项（1-4/8/10-11），聚焦电源去耦+保护+信号完整性
+- 含非MCU子系统（电机驱动/电池管理/射频等） → 过完本表后追加该子系统datasheet Typical Application逐项对照
+
+对照本地知识库中的参考设计逐模块检查。
+
+**模块分级：**
+- 🔴 **变砖级**：缺失→板子无法烧录/启动/运行。只能标✅或❌，禁止标"省略"
+- 🟡 **体验级**：缺失→体验下降但不致命。可标"省略+理由"
+
+| # | 模块 | 级别 | 检查要点 |
+|---|------|------|----------|
+| 1 | 烧录/调试接口 | 🔴 | MCU有无原生USB？完整数据路径：PC→USB线→connector→芯片→MCU引脚，逐段标注通/断；USB枚举链：D+/D-上下拉、VBUS检测、接口类型匹配（Type-C须CC配置，Micro-B/Type-B无此要求），缺任一项不枚举 |
+| 2 | 复位按钮 | 🔴 | EN/RST上拉+去耦+按钮接GND |
+| 3 | BOOT模式按钮 | 🔴 | BOOT上拉/下拉+按钮切换 |
+| 4 | 自动复位电路 | 🟡 | DTR/RTS自动控制EN和BOOT |
+| 5 | 电源指示LED | 🟡 | 3V3/5V轨LED+限流 |
+| 6 | 状态指示LED | 🟡 | GPIO驱动LED |
+| 7 | UART调试引脚 | 🟡 | TX/RX引出 |
+| 8 | Strapping偏置 | 🔴 | 所有strapping pins正确上下拉+分压计算确认电平满足VIH/VIL |
+| 9 | 电源去耦 | 🔴 | MCU VDD去耦电容，查datasheet确认要求值 |
+| 10 | 时钟源启动条件 | 🔴 | 按实际时钟源类型检查（晶振：负阻裕量、驱动电平与额定值匹配、CL取值计算依据；MEMS/EXTCLK：按对应datasheet要求） |
+| 11 | 外挂存储器 | 🔴 | MCU是否依赖外挂Flash/PSRAM？如有，容量/电压/接口模式是否匹配 |
+| 12 | 复位时序充分性 | 🔴 | RC复位时间常数 vs MCU/FPGA要求的复位脉宽最小值；POR检测阈值是否覆盖最低工作电压 |
+| 13 | 时钟精度vs外设需求 | 🔴 | 时钟源精度是否满足外设容忍度（UART +/-2%，USB +/-0.25%，内部RC跑USB须特别警告） |
+| 14 | 非MCU IC去耦 | 🔴 | 运放/ADC/基准源/电源IC去耦，按各自datasheet要求检查 |
+| 15 | 保护器件选型验证 | 🟡 | TVS钳位电压 vs 被保护引脚Abs.Max；PTC自恢复时间 vs 系统复位重试间隔 |
+
+**执行方法：**
+1. 对照本地知识库中的速查卡/datasheet，无则暂停与用户确认
+2. 逐模块对照：参考设计/开发板有→本设计有无→无则标注；无参考设计时按datasheet Typical Application电路逐项对照
+3. FPGA设计对照FPGA厂商提供的Power-On Reset/Application Note
+4. 输出基础完整性对照表
+
+### 阶段3：元件对齐拓扑（前置：阶段0文档锁定+阶段1拓扑理解）
+
+拿拓扑中标注的元件参数验证阶段1的预期数据：
+- 从阶段0的datasheet/速查卡提取参数，不从AI记忆取
+- 逐元件对照：能力vs需求，不符合项给出差值、建议替换型号及计算依据
+- 多IC共享信号的兼容性验证：同一电气网络连接多IC时，各IC对该信号的电气要求（VOH/VOL/IIH/IIL）须互相兼容
+- 重点验证项由阶段1.2检查表+阶段0 Pin映射驱动，不重复列举
+- **每条结论标注来源：datasheet型号/章节/页码，或"BOM值"/"方案文档§X"**
+
+### 阶段4：边界工况推演（前置：阶段1拓扑理解+阶段3元件对齐）
+
+典型值全部通过≠设计安全。系统推演最差工况组合：
+
+| 推演维度 | 核心目标 |
+|----------|----------|
+| 供电链路边界 | 最低输入+最大负载→输出是否跌至UVLO；路径寄生电阻/电感按PCB通用经验值起步（1oz铜10cm走线接50mohm/100nH量级），无具体走线数据时用此起步值并标注"基于通用经验值，实际以Layout为准"；热插拔瞬态是否超Abs.Max |
+| 保护链路边界 | 过流触发点vs工作电流裕量；保护动作恢复路径自洽性；固件vs硬件谁先触发；**反接/故障状态下须显式列出从故障点到汇点的所有可能电流路径（经过的每个元件），不允许仅审设计意图的主路径——包括走MOSFET体二极管、走0Ω跳线、走并联RC等非预期路径。每个路径须标注经过的元件及其额定值，确认不会超Abs.Max** |
+| 热边界 | 条件触发：仅当存在大功耗器件（LDO压差>1V且负载>200mA/电机驱动持续满载/功率LED/单IC功耗>0.5W）时执行，低功耗板（总功耗<1W无持续大电流）标注"低功耗无需热计算"直接跳过；执行时Tj=Ta+P×Rθja（Rθja取最小铜面积条件值），标注"以实际Layout校准" |
+| 固件失控边界 | MCU死机所有输出最差电平→系统是否安全；I2C挂死恢复；ADC异常→控制环是否危险 |
+| 多轴组合推演 | 最低输入+最大负载+最高温度→系统是否安全；至少对供电链路做一次全最差组合 |
+
+**推演方法**：显式数值计算优先，禁止跳过计算直接给结论；多变量组合用显式数值计算交叉验证。缺参数的维度标"待补充"并注明缺什么参数，不猜值硬算。
+
+### 阶段5：网表对齐拓扑与BOM（画图后期专用，设计期跳过；前置：阶段0~4已完成）
+
+> **设计期跳过此阶段**，无网表时跑不了。画图后拿到PCB网表再跑。
+
+- **网表解析协议（执行前提，先做这步再做对照）**：EDA导出的网表多为PROTEL/Telesis等分段格式（PROTEL 2.0用`[`/`]`分元件段、`(`/`)`分网络段），**常规文本搜索（含ripgrep类工具）往往返回0结果**，并非"无此网络"。须先识别格式，用分段解析（脚本/逐行状态机）提取"位号-引脚号→所属网络名"全量映射表。**判定标准：若直接搜索某网络名/位号返回0结果，禁止据此判定"无此网络"或放弃提取——必须切换为分段解析，确认已提取到全部网络段且关键件（电源路径/保护路径上的件）的每只脚都已归入某网络后，方可进入对照。** 提取失败=阶段5未完成，须标⚠️暂停而非用拓扑文档替代。
+- 网表 vs 拓扑连接图：每条连接必须一致
+  - 重点：MOSFET的D/S/G接法、二极管方向、**串联vs并联（见下方操作性验证）**、星形vs链式
+  - 缺Pin级描述标"未验证"
+  - Pin编号以网表为准，对照阶段0的pin table确认功能名
+  - 逐网络输出Pin级一致性矩阵
+- **双向网络存在性核对（必做，两个方向都不可漏）**：
+  - **拓扑有但网表无→❌错误**：拓扑连接图网络汇总表中定义的每个具名网络（尤其是"开关输出""二极管阳极侧"等中间节点，如J2VOUT），必须在网表中作为独立网络存在。**中间节点缺失=本该串联的器件被接成并联旁路的典型信号**，必须报❌并指出哪个器件的两端因此直接跨在了输入/输出轨上。
+  - **网表有但拓扑无→报出待澄清**：可能是未记录的网络或命名漂移，须与用户确认。
+- **串联vs并联 操作性验证（不靠原理图视觉位置，只认网络名）**：对每个串联在信号/电源路径上的二端器件（二极管/电阻/电感/开关/保险丝/MOSFET的D-S），逐只验证其两端所属网络：
+  - **串联（正确）**：至少一端落在"非输入非输出的中间节点"上——即与上游或下游器件共享一个独立命名的中间网络（该网络名应能在拓扑文档中找到定义，成员恰好=上游输出脚+下游输入脚，不多不少）。
+  - **并联旁路（❌错误）**：两端分别直接落在输入轨和输出轨上（如二极管阳极在VBAT、阴极在VIN，与同路径的开关J2形成并联而非串联），导致开关被旁路、器件常通→报❌。
+  - 判定依据=器件两端网络名 + 拓扑文档对中间节点的定义，**禁止凭原理图上"画在中间"的视觉位置判定串联**。
+- 网表 vs BOM：位号对应、封装引脚数匹配、同型号数量一致（BOM位置以用户实际文件结构为准，审查前确认）
+- 三类文件闭环：拓扑定义→BOM有能力实现→网表实际连对了（**三层须逐一对账，禁止用"拓扑文档描述正确"替代"网表实现正确"的核验**）
+- **位号区间计数验证**：凡出现"N×C"、"删Rxx/Ryy"等批量描述，须逐一数位号确认数量与描述一致（如C14~C20=7个非6个，删R28非删R27/R28）
+
+### 阶段6：系统级产品审视
+
+从完整产品视角找问题，7维度（聚焦原理图/拓扑层面）：
+
+| 维度 | 必查项 |
+|------|--------|
+| 电气 | 关键开关节点有无RC snubber或预留焊盘；对外接口每引脚ESD路径+电平兼容性+热插拔耐受 |
+| 硬固接口 | 固件用到的每个外设硬件是否完整提供且偏置正确；固件要求的时序/握手序列硬件路径是否可实现。**含固件源码时执行GPIO交叉验证**：固件#define GPIO定义 vs 拓扑图Pin表 vs 网表实际连接逐引脚对照；ADC通道/分压比/参考电压与硬件分压电阻一致性检查；I2C地址/速率/上拉与硬件一致性检查；充电状态读取等开漏输入的内部上拉配置检查。**含固件源码时执行版本一致性检查**：固件文件头MCU型号/硬件版本号 vs 拓扑图版本 vs 方案文档版本三方对齐；固件注释中的阻值/分压比等硬件参数 vs BOM实际值交叉验证。**含固件构建配置时执行MCU资源配置核对**：读取sdkconfig/platformio.ini/CMakeLists.txt等构建配置文件，确认MCU关键资源实际配置与硬件设计一致——ESP32系列须核对PSRAM类型(Quad/Octal)与模式(SDR/DDR)组合是否占用Strapping/共享引脚（如ESP32-S3 N8R8 Octal PSRAM DDR模式占用GPIO47/48，SDR模式释放）、Flash模式(QIO/QOUT/DIO/DOUT)与容量、CPU频率、Partition方案；STM32系列须核对时钟树配置与外部晶振频率一致、外设时钟使能与硬件引脚映射一致。**禁止仅凭app_config.h/pin_config.h判定固件配置正确**——GPIO宏定义正确不代表sdkconfig层面的MCU资源配置不会把该引脚占用，须将构建配置文件纳入核对范围 |
+| 功能完整性 | 方案文档每功能有从输入到输出的完整硬件路径；含ADC采样+计算反推的场景须做测量精度误差链分析：列出从物理量到最终结果每一步的误差源（串联阻抗/偏移/增益/量化/校准等），量化累积误差，确认是否满足设计精度要求 |
+| 用户交互闭环 | 异常状态是否有可见指示；操作失误是否硬件层防护 |
+| 制造校准 | 量产校准流程是否可操作；SMT有无特殊要求 |
+| 成本匹配 | 元件数量/器件复杂度是否与产品定位矛盾；扩展库元件有无基础库替代 |
+| 固件-硬件边界 | 安全关键功能是否硬件保护为先；固件可否独立升级 |
+
+### 阶段7：兜底审查
+
+**7.1 强制：重新审视阶段2所有"省略"标注**
+- 🔴变砖级被标"省略"→立即改标为❌
+- 🟡体验级省略理由不充分→标⚠️要求补充
+
+**7.2 踩坑备忘录对照**
+- 扫一遍备忘录，确认本次审查是否犯同类错误
+- **使用纪律**：审查前通读唤醒警觉，审查中允许对照备忘录逐条自问"本项目是否有类似情况"，命中项须在报告中标注"由备忘录#X触发"，供人工判断是否属于同类问题
+
+**7.3 反假设审核（认知盲区排查）**
+
+对标检查只能抓文档之间的表面矛盾，抓不了审核者把两个不同概念自动等同这类认知盲区。本节从假设设计有认知错误出发倒推，补充对标检查的盲区。
+
+**执行方法：**
+
+1. **列出本轮审核中的隐含假设**：每个关键设计决策背后都有一个默认成立但未显式验证的假设。例如：假设BATN和GND是同一个地、假设去耦电容的参考地是系统GND、假设某引脚不需要上拉因为有内部上拉。把这些假设逐条写出来。
+
+2. **逐假设反推：如果这个假设是错的会怎样？** 对每个假设问如果恰恰相反，哪些引脚/网络/参数会出问题，列出受影响的引脚和网络名。
+
+3. **验证受影响项**：对第2步列出的每个受影响项，回到拓扑/方案/网表确认实际接法是否和反假设场景一致。一致→标❌（假设错误导致了实际错误）；不一致→标✅（假设成立，设计正确）。
+
+**典型反假设清单（不限于，每版须从设计实际出发列出）：**
+
+| 隐含假设 | 反假设 | 受影响项 |
+|----------|--------|----------|
+| 不同名称的地网络物理上直通 | 不同地网络之间隔了器件，不能等同 | 所有接地引脚的精确网络名 |
+| 去耦电容的参考地是系统GND | 参考地是IC的本地地（可能不是GND） | 去耦电容两端网络名 |
+| 连接器引脚接到的是设计意图的网络 | 引脚接错了网络但语义上像对的 | 连接器每个引脚的精确网络名 |
+| 标注为NC的引脚不需要处理 | NC引脚在某些条件下有影响 | Strapping/悬空引脚状态 |
+| 拓扑文档描述的连接拓扑（串联/并联/中间节点）= 网表实际连接拓扑 | 网表把设计意图的中间节点并入了输入/输出轨，本该串联的器件被接成并联旁路 | 每个串联在路径上的二端器件的两端网络名 + 拓扑文档定义的中间节点网络是否在网表实际存在 |
+
+**输出格式：**
+
+| # | 隐含假设 | 反假设 | 受影响引脚/网络 | 验证结果 |
+|---|----------|--------|----------------|---------|
+
+> 本节发现的错误标❌，与对标检查发现的问题合并进整改清单。本节的目标是：**对标检查说都对的设计，如果认知假设是错的，实际是错的**。
+
+## 审查铁律
+
+1. **文档不到不审查** — 阶段0自动搜索知识库，缺失→暂停→用户补齐→续跑
+2. **技术文档只从本地知识库取** — 禁止联网搜datasheet/参数，网络搜索仅限拓扑合理性参考；与方案文档/拓扑描述矛盾时以datasheet为准并标⚠️待确认，由用户判定是否有意偏离
+3. **Pin定义从文档出** — 引脚功能/编号必须引用datasheet/速查卡原文
+4. **严禁无数据结论** — 没有计算过程的结论一律无效
+5. **所有参数注明来源** — datasheet第X页/第X表/BOM值/方案文档值
+6. **AI识图不到Pin级** — Pin级验证必须读文本网表+datasheet原文
+7. **边界推演必须多轴组合** — 单参数最差≠系统最差
+8. **宁可多报疑似让人类判断**，也不要放过——但多报疑似≠泛报无关，疑似项须有"为何怀疑"的技术依据，无依据的直觉不报；拓扑图无法判定的物理布局问题（间距/散热/干涉）不报错误/警告级别，仅在阶段6"制造校准"维度标注"无Layout数据无法评估"
+9. **先验全不全再验对不对** — 缺失模块的板子参数再对也是废板
+10. **abs max不能超** — "有ESD能扛"/"瞬态没问题"不是超限理由
+11. **只报问题不报通过** — 审查报告只输出错误和警告
+12. **交叉审核铁律** — 外部审查工具（网表检查脚本等）报出的技术问题，必须查datasheet原文验证，禁止凭记忆否决；本Skill前序阶段输出不适用此条
+13. **先理解拓扑再抠细节** — 禁止跳过全局理解直接逐项验证
+14. **清单是底线不是上限** — 规则条目必须过，但不代表不在清单上的就放过
+15. **地域隔离不可等同** — 系统中存在多个接地类网络时，不同网络名（GND/BATN/AGND/PGND等）在物理上不直通，禁止在审核中视为同一网络；任何引脚的接地连接必须验证精确网络名而非笼统的"接地"
+16. **固件-硬件版本绑定** — 项目含固件源码时，固件文件头必须标注对应硬件版本号和MCU型号；审查时须交叉验证固件注释中的硬件参数（阻值/分压比/IC型号）与拓扑图/BOM一致，不一致标❌
+17. **文档对≠网表对** — 拓扑连接图描述正确不等于原理图/网表实现正确；阶段5必须以网表实际连接为唯一事实来源逐脚核对，禁止用"拓扑文档写对了"替代"网表连对了"的验证。凡拓扑文档定义了具名中间网络（如开关输出节点、二极管阳极侧节点），必须在网表中确认该网络作为独立网络存在，缺失即❌
+
+## 输入规范（按项目配置，审查前确认）
+
+- **BOM清单格式**：7列 — 位号/元件/参数/封装/采购编号/数量/库，参数与封装严格分离
+- **采购编号列**：使用嘉立创体系时填LCSC编号，使用其他体系时填对应供应商编号，不用编号体系的填"-"
+- **BOM位置**：以用户实际文件结构为准（可能在拓扑连接图内，也可能是独立BOM文件），审查前确认
+- **封装-LCSC对齐**：使用LCSC编号时，换封装=换LCSC编号，改封装列必须同步改LCSC列，阶段5网表验证增加封装-编号一致性检查
+- **换封装=重新验证**：更换封装后须重新验证该元件的耐压/DC偏压/纹波电流/功耗等电气参数是否仍满足，审查时按新封装参数重新计算
+- **速查卡6节结构**（知识库中每张IC速查卡须按此结构组织，缺参数写NONE不猜不编，AI审查遇NONE跳过+标待补充）：
+  1. **基本参数**：功能/封装/供电电压范围/工作温度 + 绝对最大额定值表（Rθja仅大功耗器件必填，低功耗IC写"低功耗无需"）
+  2. **引脚速查**：ASCII引脚图 + Pin表（Pin#/名称/功能/方向/备注）
+  3. **生存必需外围**：时钟（类型/频率/CL/驱动电平额定值NONE=未标）/电源去耦（每域电容值+位置）/Strapping（引脚+偏置+电平）/必接外围（非可选，缺了无法工作）
+  4. **关键电气参数**：VIH/VIL/VOH/VOL表 + 其他项目关键参数
+  5. **项目应用计算**：负载估算/热计算（仅大功耗器件，低功耗标"低功耗无需热计算"）/压差裕量
+  6. **保护功能**（如适用）：功能+阈值
+- **3项必须人工核验参数**：晶振驱动电平额定值/MLCC DC偏压/电感饱和电流——AI从datasheet检索标注来源后提醒用户核实，不自行确认；Rθja仅大功耗器件需核验
+
+## 按比例投入
+
+| 板复杂度 | 判定 | 策略 |
+|----------|------|------|
+| 轻量板 | ≤5个IC，单电源轨，≤2模块 | 阶段0~2细过，3~4定性+关键项计算，5/6快速检查关键项，7兜底 |
+| 中型板 | 6~15个IC，多电源轨，含通信/电机 | 全阶段完整，边界至少覆盖供电+1条保护链路 |
+| 重型板 | >15个IC或多板互联 | 全阶段完整，边界做多轴组合+显式数值计算，6七维度全扫 |
+
+**无论什么复杂度：阶段0/1/2/7不能跳。**
+
+## 审查报告格式
+
+**只报问题，不报通过。** 阶段0~7所有✅通过项不在报告中出现。
+
+### 问题分类
+- **❌错误**（必须整改）：拓扑冲突/元件不满足/超Abs.Max/边界推演失败/文档缺失
+- **⚠️警告**（建议优化）：裕量不足/降额不够/时序临界/边界临界
+
+### 输出结构
+
+```markdown
+# 电路审查报告
+## 审查对象
+## 结果总览（错误X / 警告X）
+
+## 整改清单
+| # | 级别 | 阶段 | 问题 | 计算/数据 | 整改方案 | 依据 |
+|---|------|------|------|----------|---------|------|
+
+## 未验证项（缺信息无法判定，需用户确认）
+| 型号/项目 | 待确认 | 建议操作 |
+```
+
+## 踩坑备忘录
+
+> 审查后(阶段7.2)才允许对照，命中项记录但不禁替代数据推导
+
+| # | 教训 | 检查要点 |
+|---|------|----------|
+| 1 | 每版须独立重验拓扑逻辑和完整性（不继承），但上一版已验证且本版未修改的元件参数/计算结论可复用（继承），复用时须标注来源版本号 | 拓扑/完整性从头过，未改参数可复用 |
+| 2 | 同系列后缀差一个字母电压/封装/电流可能全不同 | 逐字母核对完整型号 |
+| 3 | 审查者须理解每个元件在拓扑中真实角色 | 先回答"它的真实角色是什么" |
+| 4 | 保护电路需结合电源内阻评估 | 反接/过流方案结合内阻 |
+| 5 | 上拉下拉不能照搬典型值 | 偏置电阻取值有计算依据 |
+| 6 | 去耦电容ESR须对照datasheet确认稳定工作范围，不能假设通用值 | 对照datasheet确认ESR范围 |
+| 7 | 拿备忘录当清单=带着结论审 | 备忘录只做参考，审查从拓扑独立推导 |
+| 8 | 改了A须推演B/C/D是否跟着变 | 修改后延展推演关联链路 |
+| 9 | 电机驱动IC的Rds_on会串入内阻测量路径，功能正常但测量偏差巨大 | 含电流采样+内阻反推的场景，必须做误差链分析列出所有串联阻抗 |
+| 10 | 同名不同网的地域混接（BATN≠GND、AGND≠GND等），语义上都叫"地"但物理上不直通，审核时极易被自动等同 | 凡是接地类网络，必须报精确网络名；审核时不允许把两个不同地域网络等同，即使语义上都叫"地" |
+| 11 | 反接/故障状态下只审了设计意图的主保护路径，忽略了MOSFET体二极管、0Ω跳线等构成的非预期并联电流旁路 | 保护链路审查时须显式列出故障点到汇点的所有可能路径（不含含糊的"等"），逐路径计算功耗确认每个路径上元件不超额定值 |
+| 12 | 多电源/多开关系统中，用户可同时闭合开关+插入USB，导致充电路径绕过充电IC | 含电源选择开关的系统须列出开关×USB×电池所有状态组合矩阵，每种组合追踪完整供电路径 |
+| 13 | 文档批量描述"删R27/R28""6×C"与实际位号计数不一致（实际删R28留R27、C14~C20=7个） | 凡出现N×位号、删Rxx/Ryy等批量表述，须逐个数位号验证数量 |
+| 14 | 固件注释中的硬件参数（阻值、MCU型号、版本号）与硬件实际版本脱节，误导调试和维护 | 固件审查时须将注释中的硬件参数与拓扑图BOM逐项交叉验证，不一致标❌ |
+| 15 | 设计意图文档定义的中间网络（如"J2开关输出→D8阳极"的J2VOUT节点）在画图时未被创建，导致本该串联在路径上的器件（如防倒灌二极管D8）被接成与开关并联的旁路——阳极直接落到输入轨VBAT、阴极落到输出轨VIN，开关被完全架空常通。文档对、网表错，若阶段5只查"网表有拓扑没"的单向多余网络，会漏掉"拓扑有网表没"的反向缺失；且PROTEL格式网表常规搜索返回0结果，提取静默失败后审计退回读文档，进一步放大盲区 | 阶段5须做三件事：①用分段解析提取网表全量脚→网络映射，直接搜索返回0不得判定无此网络；②双向网络存在性核对，拓扑定义的每个具名网络（尤其中间节点）必须在网表存在，缺失即❌；③对每个串联二端器件验证"至少一端落在非输入非输出的中间节点上"，两端都直接落在输入/输出轨=并联旁路=❌。判定只认网络名，不认原理图视觉位置 |
+| 16 | 固件app_config.h里GPIO宏定义全对，但sdkconfig层面MCU资源配置把该引脚占用了——典型：ESP32-S3 N8R8模组的Octal PSRAM在DDR模式(80MHz)下占用GPIO47/48差分时钟，SDR模式(40MHz)才释放；审查时只看了app_config.h的#define GPIO_NUM_47=EC11B就判通过，没读sdkconfig确认PSRAM模式，导致"固件配置正确"的假象掩盖了实际引脚被占用 | 阶段6硬固接口维度须读取sdkconfig/platformio.ini等构建配置文件，核对PSRAM类型与模式(Octal SDR vs DDR)、Flash模式、CPU频率等MCU资源配置是否与硬件引脚分配一致。禁止仅凭app_config.h/pin_config.h判定固件配置正确——GPIO宏定义对≠sdkconfig没把该引脚占用 |
+
+## 工作流
+
+当用户请求电路审查时，按以下步骤执行：
+
+1. **确认审查模式**：询问用户是"设计期"还是"画图后期"，确定输入文件（方案文档、拓扑连接图、知识库路径、是否有PCB网表）
+2. **确认项目信息**：项目名、工作区根目录、知识库位置
+3. **确认审查范围**：从头审/审网表/补审某阶段/续跑
+4. **按架构执行**：严格按两阶段架构和执行路由表执行
+5. **输出报告**：按审查报告格式输出，只报问题不报通过
+
+---
+
+*V6.6 | 2026-07-28*
+
+## 版本变更记录
+
+| 版本 | 日期 | 变更内容 |
+|------|------|----------|
+| V6.2 | 2026-07-16 | 上一版 |
+| V6.3 | 2026-07-19 | ①阶段1.1地线回流从链路模板+标注汇接点升级为地域隔离表（必输出），强制列出所有接地类网络的精确网络名、物理含义、与GND关系、中间器件、汇接点；②新增地域隔离铁律：后续所有阶段遇到引脚接地必须报精确网络名，禁止用接地接GND等笼统描述，引脚该接的地域与实际网络不一致标❌；③审查铁律加第15条地域隔离不可等同；④踩坑备忘录加第10条同名不同网的地域混接；⑤方案文档地域定义段要求：多地域系统方案文档必须含地域定义表，缺失则阶段0标⚠️待补充；⑥阶段7新增7.3反假设审核：从隐含假设出发倒推认知盲区，补充对标检查够不到的设计错误（如BATN≠GND、去耦参考地非GND等）。根因：对标检查只能抓表面矛盾，抓不了审核者把两个不同概念自动等同的认知盲区，每次审核换角度就出问题，本质是覆盖方式有盲区 |
+| V6.4 | 2026-07-21 | ①Frontmatter description扩展为含适用场景/Use when的详细描述；②标题+引言段增加"电路审查专家"定位说明；③阶段1.2新增"多电源/多开关操作状态组合"检查行；④阶段4保护链路边界扩展：故障状态下须显式列出所有可能电流路径（含MOSFET体二极管/0Ω跳线/并联RC等非预期路径）；⑤阶段5网表对齐改为AI直接从网表提取+新增位号区间计数验证；⑥阶段6硬固接口扩展：含固件源码时执行GPIO交叉验证+版本一致性检查；⑦阶段7.2使用纪律改为审查中允许对照备忘录自问；⑧审查铁律#8符号修正(!=→≠)+新增#16固件-硬件版本绑定；⑨踩坑备忘录新增11-14条(非预期旁路/多电源状态组合/位号计数/固件参数脱节)；⑩审查报告格式代码块加markdown标记；⑪新增工作流章节 |
+| V6.5 | 2026-07-28 | 根因：Volt Hound V1.0投板前终审（V5.1智谱终审）判定D8接法正确并建议投板，但实际网表把D8接成了与J2并联的旁路（阳极在VBAT、阴极在VIN），设计意图的中间网络J2VOUT从未在网表创建，导致电池接上就自动开机、J2开关失效，错误滑进实验板。复盘发现阶段5"网表对齐"存在三处盲区：①网表解析静默失败（PROTEL格式常规搜索返回0，AI退回读文档）；②网络存在性核对单向（只查"网表有拓扑没"，漏掉"拓扑有网表没"的反向缺失，即中间节点丢失）；③"并联vs串联"列为重点但无操作性验证方法。本次补强：①阶段5新增"网表解析协议"——直接搜索返回0不得判定无此网络，须分段解析提取全量脚→网络映射，提取失败须暂停而非用文档替代；②阶段5新增"双向网络存在性核对"——拓扑定义的每个具名网络（尤其中间节点）必须在网表存在，缺失即❌；③阶段5新增"串联vs并联操作性验证"——只认网络名不认原理图视觉位置，串联件至少一端须落在非输入非输出的中间节点上，两端都直接落在输入/输出轨=并联旁路=❌；④审查铁律新增第17条"文档对≠网表对"；⑤踩坑备忘录新增第15条（D8中间节点丢失教训+三步检查法）；⑥阶段7.3反假设典型清单新增"设计意图拓扑=网表实际拓扑"的隐含假设行 |
+| V6.6 | 2026-07-28 | 根因：RPM Analyzer V3.3审查时阶段6硬固接口维度只查了app_config.h的GPIO宏定义（全对），没读sdkconfig确认ESP32-S3 N8R8的PSRAM模式，把"GPIO47被DDR模式占用导致EC11B失效"的风险标成了警告，实际sdkconfig已配SDR模式无问题——审查者凭app_config.h"配置正确"的假象就下了判断，没下到构建配置层核对MCU资源实际配置。补强：①阶段6硬固接口维度新增"含固件构建配置时执行MCU资源配置核对"——读取sdkconfig/platformio.ini/CMakeLists.txt等构建配置文件，核对PSRAM类型(Quad/Octal)与模式(SDR/DDR)组合是否占用Strapping/共享引脚、Flash模式与容量、CPU频率、Partition方案（ESP32系列）；STM32系列核对时钟树与外部晶振频率一致、外设时钟使能与引脚映射一致。明确禁止"仅凭app_config.h/pin_config.h判定固件配置正确"——GPIO宏定义对≠sdkconfig没把该引脚占用；②踩坑备忘录新增第16条（app_config.h对但sdkconfig PSRAM模式占用引脚的教训） |