MaxUint/chinese-3.5-tft-clone-display-g
GitHub: MaxUint/chinese-3.5-tft-clone-display-g
为树莓派上一款丝印误导的 3.5 英寸 SPI LCD 克隆板提供经过逆向工程验证的可用 fbtft 驱动配置、设备树 overlay 及完整安装指南。
Stars: 0 | Forks: 0
# Pi Zero W — 3.5 英寸 "Display-G" SPI LCD：可用驱动程序与设置
本文介绍了适用于 Raspberry Pi Zero W 的 3.5 英寸 480×320 SPI 触摸显示屏 HAT 的可用且经过验证的驱动程序设置。本文所涉及的知识经过了多次逆向工程才得以获得——因为开发板上的丝印具有误导性，且没有任何原厂 overlay 能够驱动它。**真正起作用的两个文件是 `waveshare35a.dtbo`（驱动负载）和本 README。**
已于 2026-07-13 在 Raspberry Pi OS trixie（内核 6.18.34+rpt-rpi-v6, armv6l）以及供应商 Bullseye 镜像（5.15.32+）上验证通过。
## 硬件（已识别）
- 26 针 **顶部安装** HAT，带风扇。丝印为：*"3.5 inch Display-G / 480x320 / SPI 180MHz / XPT2046"* —— **该丝印只是营销文案的复制粘贴；它实际上并不是 Display-G**（真正的 Display-G 是安装在 Pi 下方的）。
- 其表现与 **Waveshare "3.5inch RPi LCD (A)"**（或其克隆版）完全一致。
- 芯片：Gowin **GW1NZ-LV1 FPGA** 实现了兼容 ILI9486 的控制器/网桥，**HR2046** 电阻式触摸屏（XPT2046 克隆版），3.3 V + 1.2 V 稳压器。背光硬连线常开。
- 显示通道为 **只写**（MISO 从未被驱动）；触摸共享 CE1 上的总线，并且确实有响应。
## 驱动程序
使用内核自带的 **fbtft `fb_ili9486`**（staging 阶段）—— 无需外部代码。所有针对开发板的特定魔法都封装在设备树 overlay 中（`waveshare35a.dtbo`，反编译版本：`waveshare35a.dts`，dtbo 的 md5 为：`d46683bf262ffa1b532851590a96907c`，提取自 Waveshare 的供应商镜像）：
| 参数 | 值 |
|---|---|
| bus | spi0.0 @ 16 MHz |
| framing | `regwidth=16`（每条命令/参数均以 16 位字发送 —— FPGA 要求如此），`buswidth=8` |
| pins | DC = GPIO24, RESET = GPIO25（低电平有效），pinctrl 占用 17/24/25 |
| panel | 480×320, `rotate=90`, `bgr=0`, `fps=30`, `txbuflen=32768` |
| touch | spi0.1 上的 ads7846 @ 50 kHz, PENIRQ = GPIO17, x-plate-ohms=20，可覆盖 `swapxy` |
Overlay 中携带的初始化序列（这是通用 ILI9486 配方无法复现的部分 —— 请注意 `B0`、`E2` 数字伽马写入，以及重复的 `36`/`11`）：
```
B0 00 Interface Mode Control = 0
11 Sleep Out (then delay 255 ms)
3A 55 COLMOD: 16 bpp
36 28 MADCTL: MV|BGR (landscape)
C2 44 Power Control 3
C5 00 00 00 00 VCOM Control
E0 0F 1F 1C 0C 0F 08 48 98 37 0A 13 04 11 0D 00 positive gamma
E1 0F 32 2E 0B 0D 05 47 75 37 06 10 03 24 20 00 negative gamma
E2 0F 32 2E 0B 0D 05 47 75 37 06 10 03 24 20 00 digital gamma (= E1)
36 28 MADCTL again
11 Sleep Out again
29 Display On
```
## 安装（适用于所有 Raspberry Pi OS）
```
sudo cp waveshare35a.dtbo /boot/firmware/overlays/
# /boot/firmware/config.txt — 确保/添加：
# dtparam=spi=on
# dtoverlay=waveshare35a
# /boot/firmware/cmdline.txt — 追加到单行：
# fbcon=map:1
sudo reboot
```
重启后：屏幕上会出现登录控制台。预期的 dmesg 特征信息：
```
fb_ili9486 spi0.0: fbtft_property_value: regwidth = 16 ... rotate = 90 ...
graphics fb1: fb_ili9486 frame buffer, 480x320, 300 KiB video memory, 32 KiB buffer memory, fps=33, spi0.0 at 16 MHz
ads7846 spi0.1: touchscreen, irq 160
```
### 为什么使用 `fbcon=map:1`（KMS 坑点）
当存在 `dtoverlay=vc4-kms-v3d`（默认）时，vc4 会尽早占用 fb0，因此 LCD 会注册为 **fb1**；在无头模式下运行时，vc4 稍后会注销 fb0，控制台将回退到 dummy 设备 → 面板虽然初始化了（黑屏）但什么都不显示。`fbcon=map:1` 会让 fbcon 在 fb1 注册的那一刻直接采用 fb1。
### 无需重启进行测试 / 调试
```
sudo dtoverlay /path/to/waveshare35a.dtbo # hot-load; fbN + touch appear
sudo sh -c 'cat /dev/urandom > /dev/fb1' # static on glass = pixel path OK
# 将 consoles 实时指向 fb1（con2fbmap 会硬编码 /dev/fb0）：
sudo ln -sf /dev/fb1 /dev/fb0
for c in 1 2 3 4 5 6; do sudo con2fbmap $c 1; done
sudo rm /dev/fb0
echo 1 | sudo tee /sys/class/vtconsole/vtcon1/bind # fbcon takes over
```
症状指南：**白屏** = 面板从未初始化（overlay 未应用 / 初始化命令错误）；**黑屏** = 驱动程序已初始化并执行了空白操作，只是控制台未被映射（参见上文）。在 6.x 内核上，dmesg 中出现有关 `bgr` 的警告（"boolean property with a value"）是无害的；如果红/蓝看起来反转了，`bgr` 就是调节项。
## X11 / 桌面注意事项
- 在面板上运行 X：使用 `xserver-xorg-video-fbdev` 并配置 `Option "fbdev" "/dev/fb1"`。
- 触摸校准（数值取自供应商镜像，放入 `/etc/X11/xorg.conf.d/` 即可）：参见 `xorg-99-calibration.conf`（`Calibration "3932 300 294 3801"`, `SwapAxes 1`）。
- 供应商镜像则使用 `fbcp` 将 fb0 镜像到 fb1，并在 fb0 上运行 X/fbturbo（`hdmi_cvt 480 320 60` 强制将 fb0 设置为面板尺寸）。**fbcp 需要旧版的 dispmanx，在 KMS 下无法工作** —— 不要在现代内核上折腾它；直接驱动 fb1 即可。
## 来源 / 恢复
- Overlay 提取自官方 Waveshare **"3.5inch RPi LCD (A)"** 预装镜像 `3.5inch RPi LCD (A)_20220404_32bit_bullusye.img`（Bullseye 32 位，2022-04-04），Google Drive 链接位于 。要使用本仓库，**不需要**该镜像本身 —— 所有相关内容都已提取到 `waveshare35a.dtbo` 和本 README 中。
- `waveshare35a.dts` 是 dtbo 的 dtc 反编译文件（如有需要，可使用 `dtc -I dts -O dtb -o waveshare35a.dtbo waveshare35a.dts` 重新编译）。
- 完整的调查历史记录（探测过程、已排除的协议、KeDei 考古）保存在本仓库的 git 历史记录中 —— 最多到 `9c220ab` 的提交记录中请参见 `DISPLAY_NOTES.md`。
标签：Linux设备树, SPI LCD, 云资产清单, 嵌入式系统, 硬件驱动, 逆向工程