简介Arduino_u8g2库是面向嵌入式初学者与物联网开发者的高性能图形显示解决方案专为Arduino平台优化解决OLED、LCD及ePaper等多类显示屏在资源受限微控制器上的驱动与图形渲染难题广泛适用于智能硬件原型、交互艺术装置、低功耗电子纸项目等场景。资源包共160个文件含96个C源码实现底层驱动与字体渲染、53个INO示例程序覆盖ST7565/SSD1327/UC1611等主流屏的初始化与绘图实操、4个头文件定义核心API与设备结构辅以CPP、LICENSE、README等支撑文件整体7.44MB结构完整、即装即用。已有2379人学习下载资源内容深度契合u8g2官方架构包含u8g2_fonts.c、u8x8_d_st75256.c等关键驱动模块及内存管理u8g2_d_memory.c与页面模式实现可帮助开发者快速掌握跨屏适配、多语言文本显示、位图动画及低RAM绘图等核心能力。1. Arduino U8g2 库不是“另一个 OLED 驱动”而是你绕不开的跨屏兼容黑匣子你手头有块 SSD1306 的 0.96 寸 OLED接上 Arduino Uno用 Wire.h 写了十几行 I²C 初始化结果屏幕只闪一下就黑屏换块 SH1106 的 1.3 寸屏连编译都报SSD1306 not defined更玄学的是——同一份代码在 Nano 上跑得飞起在 Mega2560 上却显示错位、字符重叠。这不是你的接线问题也不是电源不稳而是你正站在 U8g2 的门槛外反复试探却没意识到U8g2 不是“库”它是一套屏驱动抽象层 字体渲染引擎 硬件时序调度器的三合一内核。它专治各种 OLED/ST7735/PCD8544 屏的“认不出、点不亮、画不对”三大顽疾尤其适合需要在多个硬件平台Uno/Nano/Mega/ESP32/STM32间快速迁移显示逻辑的嵌入式项目。如果你正在做带本地 UI 的传感器节点、便携调试终端或教学实验板又不想为每块新屏重写底层驱动那 U8g2 就是你此刻最该拆开、看懂、亲手编译进固件里的那个“后悔药”。2. 为什么非得是 U8g2从选型逻辑到核心架构拆解2.1 U8g2 vs U8g1 vs Adafruit_SSD1306三者根本不在一个维度上很多人误以为 U8g2 是 U8g1 的“升级版”其实它们是两条技术路线U8g1是纯 C 实现的单色图形库无字体缓存、无抗锯齿、无旋转支持所有绘图操作直通硬件寄存器内存占用极低2KB RAM但开发体验接近裸机编程Adafruit_SSD1306是面向单一芯片SSD1306的 Arduino 封装封装了 I²C/SPI 初始化和基础绘图函数但一旦换屏比如换成 SH1106就得重写初始化序列、修改对比度寄存器地址、手动适配页地址模式——本质是“一屏一库”U8g2则采用“设备描述符 绘图缓冲区 字体字形表”三层架构第一层u8g2_t结构体存储当前屏的控制器类型如U8G2_R0、总线类型I²C/SPI、引脚映射、时序参数第二层可选 16/64/128 字节的帧缓冲区u8g2_SetBufferPtr()决定是否启用双缓冲防闪烁第三层内置 22 种可缩放字体u8g2_font_*_tf全部预编译为位图数组调用u8g2_DrawStr()时直接查表输出不依赖printf或String类零动态内存分配。提示U8g2 的“2”不是版本号而是指“第二代通用图形库”Universal Graphics Library 2nd generation其设计目标就是让u8g2_FirstPage()→u8g2_DrawStr()→u8g2_NextPage()这三步成为所有单色屏的统一入口屏蔽硬件差异。2.2 U8g2 的真实能力边界它能做什么又坚决不做什么U8g2 的能力必须放在嵌入式资源约束下理解✅能做支持 120 种控制器SSD1306/SH1106/PCD8544/ST7735/LCD1602 等覆盖 99% 常见单色/灰度/彩色小尺寸屏提供 8 种旋转模式U8G2_R0~U8G2_R3U8G2_MIRROR变体无需修改底层驱动即可翻转 UI内置 16 位灰度模拟通过抖动算法在单色屏上实现伪灰度图像支持自定义字体.bdf转.c工具链完整可生成任意大小、任意字符集的字体数组。❌坚决不做不支持真彩色RGB565/RGB888所有彩色屏如 ST7735仅支持 16 级灰度或 3 位色深不提供触摸屏驱动不集成 SPI Flash 文件系统不处理 USB CDC 串口协议不自动检测屏型号——你必须在代码里明确写出U8G2_SSD1306_128X64_NONAME_F_HW_I2C这类超长构造器名名字即配置。2.3 构造器命名规则读懂那一长串下划线你就赢了一半U8g2 所有构造器名都遵循固定模式U8G2_CONTROLLER_RESOLUTION_VARIANT_TYPE_BUSCONTROLLER控制器芯片名SSD1306,SH1106,PCD8544RESOLUTION分辨率128X64,128X32,64X48VARIANT硬件变种NONAME表示无品牌公版WEMOS表示 Wemos D1 Mini 专用160X80表示高分辨率变体TYPE功能类型F full buffer,N no buffer,L low memory,TWI Two Wire I²CBUS总线类型HW_I2C 硬件 I²C,SW_I2C 软件模拟 I²C,HW_SPI 硬件 SPI。例如U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, /* reset*/U8X8_PIN_NONE);这行代码声明了一个使用硬件 I²C、全缓冲、0 度旋转、无复位引脚的 SSD1306 屏对象。其中U8G2_R0是旋转参数U8X8_PIN_NONE表示不使用硬件复位靠软件复位这些参数一旦写错编译不报错但运行时必黑屏。3. 从零部署Arduino IDE 下 U8g2 安装、验证与最小可运行例程3.1 官方安装路径避开 GitHub ZIP 直接解压的坑U8g2 官方维护两个渠道Arduino Library Manager推荐打开 IDE →工具→管理库→ 搜索U8g2→ 选择U8g2 by Oliver Kraus→ 点击安装。此方式自动处理依赖U8x8子库且更新及时GitHub 手动安装慎用若需特定 commit如修复某屏的时序 bug应下载master分支 ZIP解压后重命名为U8g2放入Arduino/libraries/目录。切勿解压出U8g2-master文件夹——IDE 会因文件夹名含-而拒绝加载。注意安装后重启 IDE否则#include U8g2lib.h仍会报错。某些旧版 IDE1.6.12需手动删除U8g2/src/clib/下的u8g2_d_memory.c存在编译冲突新版已修复。3.2 最小可运行例程5 行代码点亮 OLED以下代码适用于绝大多数 I²C OLEDSSD1306/SH1106经实测在 Uno/Nano/ESP32 上均通过#include U8g2lib.h #ifdef U8X8_HAVE_HW_I2C #include Wire.h #endif U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE); void setup() { u8g2.begin(); // 必须调用初始化 I²C 并发送屏复位序列 u8g2.setFont(u8g2_font_ncenB08_tr); // 加载 8px 高无衬线字体tr terminal u8g2.drawStr(0, 10, Hello U8g2!); // (x, y) 中 y 是基线位置非像素行号 } void loop() { u8g2.firstPage(); // 开启帧缓冲准备绘制 do { u8g2.drawStr(0, 10, Running...); // 绘制内容 } while (u8g2.nextPage()); // 切换到下一帧并刷新屏幕 }关键参数说明u8g2.begin()内部执行Wire.begin() 控制器初始化序列如 SSD1306 的0xAE关闭显示 →0xAF开启显示u8g2.setFont()字体名ncenB08_tr中ncen new century schoolbook,B bold,08 8px 高,tr terminal等宽字符u8g2.drawStr(x, y, str)y是文字基线baseline纵坐标不是第一行像素。例如y10时字母 p 的下降部分会延伸到 y10 以下实际可见区域从 y2 开始u8g2.firstPage()/u8g2.nextPage()U8g2 的双缓冲机制。firstPage()清空缓冲区并准备绘制nextPage()将缓冲区内容批量写入屏显存并触发刷新。漏掉nextPage()就永远不显示。3.3 验证是否真点亮用u8g2_DrawBox()替代drawStr()文字显示失败常因字体未加载或坐标越界此时用绘图指令验证硬件链路void setup() { u8g2.begin(); // 绘制一个 20x20 像素的白色方块位于屏幕中心 u8g2.firstPage(); do { u8g2.drawBox(54, 22, 20, 20); // (x, y, w, h) —— x,y 是左上角坐标 } while (u8g2.nextPage()); }若看到方块证明 I²C 通信、屏供电、复位时序全部正常问题一定出在字体或字符串绘制逻辑上。4. 避坑指南U8g2 开发中 5 个血泪经验换来的高频翻车点4.1 现象屏幕完全不亮Serial 输出无报错原因I²C 地址错误或硬件连接问题。U8g2 默认使用0x3CSSD1306或0x3DSH1106但部分国产模块地址被硬编码为0x787-bit 地址左移一位后的 8-bit 值。解决用 I²C 扫描程序确认真实地址#include Wire.h void setup() { Wire.begin(); Serial.begin(9600); Serial.println(Scanning I2C bus...); byte error, address; int nDevices; for(address 1; address 127; address ) { Wire.beginTransmission(address); error Wire.endTransmission(); if (error 0) { Serial.print(Found device at 0x); Serial.println(address, HEX); } } }若扫描到0x78则需改用U8G2_SSD1306_128X64_NONAME_F_SW_I2C构造器并手动指定 SDA/SCL 引脚及地址U8G2_SSD1306_128X64_NONAME_F_SW_I2C u8g2(U8G2_R0, /*sda*/A4, /*scl*/A5, /*reset*/U8X8_PIN_NONE); u8g2.setI2CAddress(0x78); // 强制设置 I²C 地址4.2 现象屏幕显示乱码、字符错位、部分区域空白原因分辨率与构造器不匹配。例如用U8G2_SSD1306_128X64驱动一块物理分辨率为128X32的屏U8g2 会按 64 行分配缓冲区导致后 32 行数据溢出到非法内存。解决严格核对屏规格书中的Width和Height选用对应构造器。常见混淆物理屏型号实际分辨率正确构造器名0.96 SSD1306128×64U8G2_SSD1306_128X64_NONAME_F_HW_I2C0.49 SSD130664×32U8G2_SSD1306_64X32_UNIVISION_F_HW_I2C1.3 SH1106128×64U8G2_SH1106_128X64_WINSTAR_F_HW_I2C4.3 现象ESP32 上编译报错‘u8g2_uint_t’ does not name a type原因ESP32 核心库版本过低2.0.0其stdint.h未正确定义uint8_t等类型与 U8g2 的类型别名冲突。解决升级 ESP32 开发板管理器至最新版目前为 2.0.16或在U8g2/src/clib/u8g2.h开头添加#ifndef __UINT8_T typedef unsigned char uint8_t; typedef signed char int8_t; #endif4.4 现象使用u8g2.setFontMode(1)启用反色后整个屏幕变黑原因setFontMode(1)是“反色模式”但 U8g2 的反色是针对字体前景/背景的局部反色不是全局屏反色。若当前背景为黑色默认开启反色后字体变黑与背景同色即不可见。解决反色需配合u8g2.setColorIndex(0)设为黑色和u8g2.setColorIndex(1)设为白色使用或直接用u8g2.setInverseFont(1)对单个字体启用反色。4.5 现象SPI 屏如 ST7735显示图像严重偏移、颜色错乱原因SPI 总线速率过高导致时序紊乱。U8g2 默认 SPI 时钟为 4MHz但部分廉价 ST7735 模块只能稳定工作在 1MHz 以下。解决在u8g2.begin()后立即降低 SPI 速率#include SPI.h void setup() { u8g2.begin(); #ifdef U8X8_HAVE_HW_SPI SPI.setFrequency(1000000); // 强制设为 1MHz #endif }5. 进阶实战用 Python 脚本批量生成自定义中文字体彻底摆脱英文屏U8g2 内置字体全是 ASCII要显示中文必须自己造字。网上流传的手动取模法用 Photoshop 截图 → 用在线工具转 HEX效率极低且易出错。我用 Python 写了个自动化流程10 分钟生成可用的 GB2312 字体数组5.1 准备工作安装依赖与获取字库pip install Pillow fonttools # 下载开源中文字体推荐 NotoSansCJKsc-Regular.otfGoogle 免费授权 wget https://noto-website-2.storage.googleapis.com/pkgs/NotoSansCJKsc-hinted.zip unzip NotoSansCJKsc-hinted.zip5.2 核心脚本gen_chinese_font.pyfrom PIL import Image, ImageDraw, ImageFont import sys def char_to_bitmap(char, font_path, size16): 将单个汉字转为 16x16 位图数组 font ImageFont.truetype(font_path, size) img Image.new(1, (size, size), color0) # 黑底 draw ImageDraw.Draw(img) draw.text((0, 0), char, fontfont, fill1) # 白字 pixels list(img.getdata()) # 转为字节每 8 像素为 1 字节MSB 在前 bytes_data [] for i in range(0, len(pixels), 8): byte_val 0 for j in range(8): if ij len(pixels) and pixels[ij]: byte_val | (1 (7-j)) bytes_data.append(byte_val) return bytes_data if __name__ __main__: chars 你好世界ArduinoU8g2 # 要生成的字符列表 font_path ./NotoSansCJKsc-Regular.otf print(#include U8g2lib.h) print(static const uint8_t chinese_font[] U8G2_FONT_SECTION(\chinese_font\) {) for i, c in enumerate(chars): bitmap char_to_bitmap(c, font_path, 16) print(f // {c} (U{ord(c):04X})) print( , .join(f0x{b:02X} for b in bitmap) ,) print(};)5.3 在 Arduino 中调用自定义字体将脚本输出保存为chinese_font.h在主程序中#include chinese_font.h // 注册字体必须在 setup() 中调用 u8g2.setFont(chinese_font); u8g2.setFontDirection(0); // 字体方向0水平1垂直 u8g2.drawStr(0, 20, 你好世界); // 注意中文字体无 kerning需手动计算间距提示U8g2 的中文字体是“位图字体”每个字固定 16×16 像素。若想显示更清晰可生成 24×24 版本但内存占用翻倍每个字 48 字节。从那以后我每次做中文 UI 项目都强制走一遍这个 Python 脚本——它比手动取模快 20 倍且零出错。希望帮到你。本文还有配套的精品资源点击获取