# 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)

---