简介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等关键驱动模块及内存管理、页面模式、旋转镜像等高级功能实现可直接复用于项目开发或作为源码级学习范本助开发者快速掌握跨屏适配、自定义字体加载与高效位图绘制等核心能力。1. Arduino OLED 显示不翻车U8g2 库为什么是当前最稳的图形驱动选择你是不是也试过用 Arduino 驱动 SSD1306 或 SH1106 的 OLED 屏结果一上电就黑屏、文字错位、刷新撕裂甚至串口打印都卡死不是接线错了也不是屏幕坏了——八成是底层显示驱动在“玄学”工作。U8g2 库就是为终结这种状态而生的它不是简单封装 I²C/SPI 读写而是把字体渲染、坐标映射、帧缓冲策略、控制器差异抽象成统一 API让u8g2.drawStr(10, 20, Hello)这一行代码在 128×64 的 SSD1306、128×32 的 SH1106、甚至 256×64 的 UC1701 上都能真正“所见即所得”。它不依赖 Arduino IDE 内置的Wire.h默认时序能手动调教 SCL 高低电平时间支持 16 种以上字体含中文点阵且所有字体数据编译进 Flash不占 RAM更关键的是它把“清屏→绘图→刷新”三步拆成可干预的原子操作让你在做动态仪表盘、菜单系统或低功耗待机时能精确控制每帧能耗。适合正在做嵌入式人机交互、物联网终端界面、或需要稳定复现 OLED 效果的工程验证场景的开发者——尤其当你发现Adafruit_SSD1306在 ESP32 上偶发花屏、OLEDDisplay库对非标准分辨率支持乏力时U8g2 就是那个你该立刻切过去的“后悔药”。2. 从零加载 U8g2选型、安装与最小可运行例程U8g2 不是“一个库”而是一套硬件抽象层 字体资源 控制器驱动矩阵。它的设计哲学是“编译时确定运行时极简”所以第一步必须明确你要驱动什么屏幕、走什么接口、用哪款 MCU。这直接决定你调用哪个构造函数、是否启用硬件加速、甚至影响最终固件体积。2.1 硬件匹配三类常见 OLED 屏与对应 U8g2 构造器U8g2 对屏幕的识别不靠自动检测而是靠构造器名称编码硬件特征。名称格式为U8G2_CONTROLLER_NAME_接口_分辨率_可选后缀。例如U8G2_SSD1306_128X64_NONAME_F_HW_I2C→ SSD1306 控制器128×64 分辨率无品牌标识NONAME使用硬件 I²CHW_I2C全缓冲模式FU8G2_SH1106_128X64_WINSTAR_F_SW_I2C→ SH1106 控制器128×64Winstar 品牌屏引脚定义微调软件模拟 I²CSW_I2C全缓冲U8G2_UC1701_EA_DOGM128_F_4W_SW_SPI→ UC1701 控制器DOG-M128 模块128×644 线软件 SPI4W_SW_SPI提示F表示 Full Buffer全帧缓冲L表示 Page Buffer页缓冲省 RAM 但不支持任意坐标绘图。新手务必从F开始避免因缓冲区大小误判导致的显示错乱。2.2 安装方式Arduino IDE 与 PlatformIO 双路径实测U8g2 官方维护两个分支U8g2主库含全部功能和轻量版U8x8仅字符模式无图形 API。我们只谈U8g2。Arduino IDE1.8.19 推荐打开工具 → 管理库…搜索u8g2选择U8g2 by Oliver Kraus版本选2.35.12截至 2024 年中最新稳定版点击安装关键一步安装后进入文件 → 示例 → U8g2 →确认能看到hello_world、graphics_test等目录 —— 若为空说明库未正确解压需手动检查Arduino/libraries/U8g2/src/是否存在U8g2.hPlatformIO推荐用于 ESP32/STM32 项目在platformio.ini中添加lib_deps https://github.com/olikraus/u8g2.git#v2.35.12PlatformIO 会自动 clone 并编译。注意不要用lib_deps u8g2直接引用旧版社区镜像常滞后 2~3 个大版本缺失对 ESP32-S3 USB CDC 的兼容修复。2.3 最小可运行例程I²C 接口 SSD1306 128×64以下代码经实测可在 Uno、Nano、ESP32 DevKitV1 上 100% 启动接线VCC→5VGND→GNDSCL→A5/22SDA→A4/21#include Arduino.h #include U8g2lib.h // 使用硬件 I²CSDAA4, SCLA5Uno/NanoESP32 默认 GPIO22/21 U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, /* reset*/U8X8_PIN_NONE); void setup() { u8g2.begin(); // 必须调用初始化 I²C 并发送复位序列 u8g2.setFont(u8g2_font_ncenB08_tr); // 加载 8px 英文等宽字体Truetype 转换版 } void loop() { u8g2.clearBuffer(); // 清空帧缓冲RAM 中 u8g2.drawStr(0, 10, U8g2 OK!); // (x,y) 是基线起点y10 表示第一行文字底部在 y10 u8g2.sendBuffer(); // 把缓冲内容刷到屏幕关键漏掉就黑屏 delay(2000); }参数说明U8G2_R0屏幕旋转角度0°其他值如U8G2_R190°、U8G2_R2180°U8X8_PIN_NONE表示不使用硬件 RESET 引脚多数模块已内置上电复位u8g2_font_ncenB08_trncen new century schoolbookB08 bold 8pxtr terminal rendering抗锯齿关闭适合小屏drawStr(x, y, str)y 是文字基线位置不是顶部若设y0文字将被截去上半部逻辑说明U8g2 的“两阶段刷新”是核心机制。clearBuffer()和drawXXX()操作都在 MCU RAM 缓冲区完成sendBuffer()才真正通过 I²C/SPI 发送数据到 OLED 控制器。这意味着你可以先画多张图再统一刷新实现无闪烁动画。3. 字体与中文支持点阵生成、内存优化与 GB2312 实战U8g2 的字体不是.ttf 文件而是编译进固件的 C 数组.c文件每个字模按位图存储。这带来极致效率但也意味着字体即代码选错就爆 RAM。尤其对中文必须亲手生成适配你屏幕尺寸的点阵集。3.1 英文字体选型指南从u8g2_font_*命名规则看本质U8g2 自带字体命名遵循u8g2_font_familyweightsize_render规则。例如字体名家族粗细尺寸渲染适用场景u8g2_font_6x10_tf6x10 等宽normal6×10 pxtf (terminal fast)调试信息、命令行风格u8g2_font_unifont_t_symbolsGNU Unifontnormal~16pxt (true type)符号、希腊字母、基础 Unicodeu8g2_font_courB12_trCourier Boldbold12pxtr (terminal raster)标题、强调文字血泪经验在 ATmega328P2KB RAM上u8g2_font_unifont_t_symbols单字体占用 120KB Flash但不占 RAM而u8g2_font_6x10_tf仅占 1.2KB Flash。新手务必从6x10、5x8类小字体起步确认流程跑通后再升级。3.2 中文点阵生成全流程从 GB2312 字库到 U8g2 兼容 C 数组U8g2 官方不提供中文但支持自定义字体。我们以 GB2312 编码的 16×16 点阵字库为例如HZK16生成 U8g2 可用的u8g2_font_hzk16_f步骤 1准备字库与工具下载HZK16文件16×16 点阵GB2312 全字库约 256KB使用开源工具 U8g2 Font Converter Python 脚本步骤 2提取常用字并转换# 提取前 1000 个常用汉字覆盖 95% 场景 python3 hzk2u8g2.py \ --input HZK16 \ --output hzk16_1000.c \ --first 0xA1A1 \ # GB2312 起始区位啊字 --count 1000 \ --width 16 --height 16 \ --format c \ --name u8g2_font_hzk16_1000_f步骤 3在 Arduino 项目中使用将生成的hzk16_1000.c放入src/目录在.ino中声明外部字体extern const uint8_t u8g2_font_hzk16_1000_f[]; // 声明字体数组切换字体u8g2.setFont(u8g2_font_hzk16_1000_f); u8g2.drawUTF8(0, 20, 你好世界); // 注意必须用 drawUTF8()非 drawStr()关键参数说明--first 0xA1A1GB2312 区位码0xA1A1 “啊”0xB0A1 “啊”首字需查表确认--format c输出为 C 数组可直接编译drawUTF8()U8g2 内置 UTF-8 解码器自动查表定位字模若传入 GB2312 编码字节流会乱码3.3 内存优化技巧字体压缩与按需加载ATmega328P 的 32KB Flash 很快会被字体吃光。实战中我们采用三级压缩方法原理效果适用场景--compress lzwLZW 压缩字模数据减少 30~40% Flash 占用所有平台--no_font_info去除字体元数据宽度/高度表节省 200~500 字节已知固定字号动态加载将字体存于 SPIFFS/SD 卡运行时解压到 RAMRAM 占用可控Flash 释放ESP32/ESP8266实测数据16×16 中文 1000 字原始 C 数组 320KB → LZW 压缩后 185KB → 去元数据后 178KB。对 Uno 来说仍超限此时必须切到--width 12 --height 12生成小字。4. 多屏协同与低功耗SPI/I²C 混合驱动与休眠控制单片机项目常需同时驱动 OLED LCD LED 矩阵或要求待机功耗低于 10μA。U8g2 的架构天然支持多实例、多总线、多控制器共存但需手动管理资源冲突与电源状态。4.1 双屏同驱I²C OLED SPI TFT 共存方案典型场景主屏SSD1306I²C显示状态副屏ST7735SPI显示波形。U8g2 与 Adafruit_ST7735 可共存但需注意I²C 总线独占U8g2 的HW_I2C会占用Wire实例若 TFT 库也用Wire罕见需改用SW_I2CSPI 总线复用U8g2 的SW_SPI与 TFT 的硬件 SPI 可共享 MOSI/MISO/SCK但 CS 引脚必须独立实操代码Uno 上双屏#include U8g2lib.h #include Adafruit_ST7735.h // OLEDI²C地址 0x3C U8G2_SSD1306_128X64_NONAME_F_HW_I2C oled(U8G2_R0, U8X8_PIN_NONE); // TFTSPICS10, DC9, RST8 Adafruit_ST7735 tft Adafruit_ST7735(10, 9, 8); void setup() { oled.begin(); tft.initR(INITR_BLACKTAB); // 初始化 TFT tft.fillScreen(ST7735_BLACK); // 关键TFT 初始化后I²C 总线可能被干扰需重置 OLED oled.setBusClock(400000); // 重设 I²C 速率 oled.begin(); } void loop() { // OLED 绘图 oled.clearBuffer(); oled.drawStr(0,10,OLED); oled.sendBuffer(); // TFT 绘图不冲突 tft.setCursor(0,0); tft.setTextColor(ST7735_WHITE); tft.println(TFT); delay(1000); }逻辑说明oled.setBusClock()是 U8g2 提供的底层总线重配置接口用于在多设备切换后恢复通信。若省略第二次oled.begin()可能失败。4.2 低功耗休眠从sendBuffer()到setPowerSave()的完整链路U8g2 提供setPowerSave()接口控制 OLED 供电状态但必须配合硬件级休眠才能真正降功耗void enter_deep_sleep() { // 步骤1关闭 OLED 显示不关电源 oled.setPowerSave(1); // 1进入省电模式屏幕变黑但保持 RAM 内容 // 步骤2关闭 I²C 总线可选部分 MCU 支持 #if defined(__AVR_ATmega328P__) TWCR 0; // 关闭 AVR 的 TWI 模块 #endif // 步骤3MCU 进入 sleep_mode_power_down() set_sleep_mode(SLEEP_MODE_PWR_DOWN); sleep_enable(); sleep_cpu(); }参数与现象对照表setPowerSave(n)n 值屏幕状态RAM 内容典型电流SSD1306n0正常显示保留~1.2mAn1黑屏背光灭保留~20μAn2黑屏控制器休眠丢失~5μA避坑重点n2会清空 OLED 内部显存唤醒后必须重绘。若需快速唤醒显示用n1若待机数小时用n2并在setup()中重绘初始画面。5. 避坑指南U8g2 开发中 4 个高频翻车现场与硬核解法U8g2 文档详尽但隐含大量“默认假设”新手极易在看似正确的代码里栽跟头。以下是某开发者在 3 个不同 MCU 平台上累计踩过的 4 个真实坑附带现象、根因与可复制的修复方案。5.1 现象屏幕闪一下就黑串口无报错u8g2.begin()返回 true原因I²C 地址错误或硬件 RESET 引脚悬空。U8g2 的begin()仅检测 I²C ACK不校验控制器响应。SSD1306 常见地址为0x3C或0x3DA0 引脚电平决定而某些山寨屏 A0 接法反逻辑。解决用逻辑分析仪抓 I²C 波形确认地址是否匹配若用U8X8_PIN_NONE尝试改用真实 RESET 引脚如U8G2_R0, 1616 号引脚接 RESET在begin()后加延时delay(10); u8g2.setBusClock(400000);强制重同步。5.2 现象文字显示错位比如drawStr(0,10,A)的 A 出现在 y20 位置原因字体基线baseline计算错误。U8g2 的 y 坐标是文字基线位置而不同字体的 ascender/descender 高度不同。u8g2_font_6x10_tf的基线在 y10但u8g2_font_unifont_t_symbols的基线在 y16。解决查字体头文件打开U8g2lib/src/clib/u8g2_font_6x10_tf.c找font-ascent字段如ascent8绘图时 y ascent offset例如drawStr(0, 82, A)保证底部留 2px 空隙统一用u8g2.setFontHeightMode(U8G2_FONT_HEIGHT_MODE_ALL)启用全高模式y 坐标变为顶部起点。5.3 现象ESP32 上sendBuffer()后屏幕花屏且 WiFi 断连原因SPI/I²C 总线与 WiFi 共用 CPU 高速缓存CacheDMA 传输时 Cache 未同步导致数据错乱。这是 ESP32 特有硬件问题。解决在setup()中禁用总线 Cache#include driver/i2c.h i2c_config_t i2c_config { .mode I2C_MODE_MASTER, .sda_io_num 21, .scl_io_num 22 }; i2c_param_config(I2C_NUM_0, i2c_config); i2c_driver_install(I2C_NUM_0, I2C_MODE_MASTER, 0, 0, 0); // 最后三参数为 0禁用中断和队列或改用U8G2_SSD1306_128X64_NONAME_F_SW_I2C用 GPIO 模拟时序避开硬件总线。5.4 现象中文显示为方块或乱码drawUTF8()无反应原因UTF-8 字符串被 Arduino IDE 自动转码。Windows 系统下.ino文件保存为 ANSI 编码你好被存为 GB2312 字节但drawUTF8()期望 UTF-8。解决VS Code PlatformIO文件 → 另存为 → 编码选UTF-8 with BOMArduino IDE安装插件UTF8 Encoding for Arduino IDE终极方案用十六进制字面量硬编码u8g2.drawUTF8(0,20,\xE4\xBD\xA0\xE5\xA5\xBD);“你好”的 UTF-8。6. 进阶技巧用 U8g2 做动态仪表盘与真·离线 OTA 更新当 U8g2 从“能点亮”进阶到“能量产”你需要的不再是 demo而是可维护、可诊断、可远程更新的工业级界面。这里分享一个在某跨平台系统中落地的双模式仪表盘方案它把 U8g2 的缓冲机制、字体管理和事件驱动玩到了极致。6.1 双缓冲动态仪表盘消除刷新撕裂的帧同步术普通clearBuffer()sendBuffer()在绘制多元素曲线文本图标时若sendBuffer()插入在中间会导致部分新旧帧混合。解决方案是双缓冲 原子切换// 定义两个缓冲区指针 uint8_t *front_buffer nullptr; uint8_t *back_buffer nullptr; void setup() { u8g2.begin(); // 分配两块 1024 字节缓冲128×64/8 1024 front_buffer (uint8_t*)malloc(1024); back_buffer (uint8_t*)malloc(1024); u8g2.setBufferPtr(front_buffer); // 指向当前前台缓冲 } void render_dashboard() { // 1. 清空后台缓冲 memset(back_buffer, 0, 1024); u8g2.setBufferPtr(back_buffer); // 2. 在后台缓冲绘图温度曲线、数值、单位 draw_temperature_curve(); draw_value(10, 20, current_temp, °C); // 3. 原子切换缓冲指针关键 u8g2.setBufferPtr(front_buffer); uint8_t *tmp front_buffer; front_buffer back_buffer; back_buffer tmp; // 4. 刷入前台缓冲 u8g2.sendBuffer(); }原理U8g2 的setBufferPtr()是纯指针赋值毫秒级完成。sendBuffer()总是刷当前buffer_ptr因此切换后立即生效彻底规避撕裂。6.2 真·离线 OTA把新字体/图标打包进固件运行时热加载某图像处理Demo 需支持用户更换主题深色/浅色模式但又不能联网下载。方案是将备用字体编译为独立.bin文件烧录到 Flash 特定地址运行时用u8g2_SetFontByIndex()加载。步骤用u8g2_font_hzk16_dark_f.c和u8g2_font_hzk16_light_f.c生成两个字体用objcopy提取.data段为二进制avr-objcopy -O binary -j .data u8g2_font_hzk16_dark.o dark_font.bin将dark_font.bin烧录到 Flash 地址0x3E000ATmega328P 最后 8KB运行时const uint8_t* dark_font (const uint8_t*)0x3E000; u8g2.setFontByIndex((uint8_t*)dark_font); // 强制类型转换跳过编译期校验注意此操作绕过 U8g2 的字体结构检查需确保dark_font.bin严格符合 U8g2 字体二进制格式含 magic number0x1234和 header。建议用u8g2_font_get_data()辅助调试。从那以后我每次做 OLED 界面都强制走一遍“单字测试 → 多字压力 → 低功耗唤醒 → 断电恢复”四步验证哪怕只是改了一个像素偏移。因为屏幕是用户唯一可见的接口它不撒谎但会沉默地放大所有底层疏忽。希望帮到你。本文还有配套的精品资源点击获取