Initial: knowledge base

2026-08-05 17:25:09 +08:00
parent bfabe83832
commit 5700eb4115
35 changed files with 5140 additions and 11 deletions
@@ -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)
+
+---