最稳路径是用硬件SPI外设手动发命令/数据，禁用软件SPI模拟；SSD1306初始化必须硬编码指定width、height、spi实例、dc引脚、rst引脚、cs引脚共6个关键参数，缺一或错配将导致黑屏、花屏或绘图错乱。
直接用硬件SPI外设 + 手动发命令/数据是最稳的路径，别碰软件SPI模拟时序——它在高频刷新或动画场景下极易错位、丢字节，尤其在STM32或ESP32这类中断密集的系统里。
SSD1306_SPI初始化必须传对这5个参数
SSD1306控制器不认“自动识别”，所有引脚和SPI外设都得硬编码指定。漏掉任一控制线，屏幕就黑着不动；接反DC或RST，可能初始化成功但后续绘图全乱。
-
width和height：必须与物理屏一致，常见是128和64；填错会导致framebuf地址越界，显示偏移或花屏 -
spi：指向已初始化好的硬件SPI实例（如STM32的hspi1，ESP32的&SPI），不能传空指针或未启用的句柄 -
dc：GPIO输出引脚，用于切换命令/数据模式；必须在每次写入前手动拉高/拉低，不能复用为普通IO -
rst：复位引脚，低电平有效；有些模块没引出该脚，此时可传nullptr，但需确认模块带内置上电复位电路 -
cs：片选引脚，低电平有效；若模块CS已接地（如部分便宜OLED），则传nullptr，否则SPI通信会失败
drawPixel、drawLine这些函数背后其实是页寻址操作
SSD1306的GDDRAM不是线性排列的，而是按8行一页（Page 0–7）、每页128字节组织。调用drawPixel(x, y)时，驱动库要算出y属于哪一页（y / 8），再算出在该页内偏移多少bit（y % 8），最后把对应bit置1。这个转换逻辑一旦出错，点就画到错行甚至错页。
- 所有图形函数（
drawLine、fillRect）都依赖framebuf的底层set_pixel实现，而它又强依赖正确的页/列映射 - 如果手动改过
SSD1306::init()里的set_page_start_address或set_column_address命令，必须同步更新帧缓冲区的内存布局，否则fill(0)清屏会只清一部分 - 双色屏（如黄蓝）需额外处理颜色位，标准
ssd1306C++驱动默认只操作单色位，强行用于双色屏会导致颜色错位
刷新屏幕前必须调用display()，且不能省略send_buffer()
MicroPython里display.show()是一体的，但C++裸驱中，display()只是把framebuf内容拷进显存；真正触发OLED刷新的是向SSD1306发送0xAF（Display On）命令——而很多开源驱动把这步藏在display()末尾，你得确认它真执行了。
立即学习“C++免费学习笔记（深入）”；
- 常见错误：调用
drawLine()后没跟display()，屏幕毫无反应；或者display()被放在while循环外，只刷一次 - 性能陷阱：频繁调用
display()（比如每画一个点就刷）会导致SPI总线拥堵，实测在10MHz SPI下，全屏刷新约1.2ms，但每点刷一次可能拖慢10倍 - 有些驱动把
send_buffer()拆成两步：先发0xB0~0xB7选页，再发128字节数据；若中间被中断打断，会出现某几行残留旧图像
最易被忽略的是DC引脚的时序配合：在SPI传输每个字节前，必须确保DC电平已稳定至少100ns（手册要求），而很多C++驱动直接GPIO置位后立刻启动SPI传输，没加微秒级延时，在高速SPI（>5MHz）下容易误判为命令字节。
