简介Arduino_u8g2库是一套面向Arduino开发者的图形显示库它主要适配OLED、LCD以及ePaper屏幕常用于智能家居、数据监控、手持仪表等项目中能够显著降低文本和图形界面的开发门槛并提供多国语言字体、页面模式等特色能力。压缩包约7.44MB共160个文件以.c驱动与字体源码、.ino示例工程为主同时包含.h头文件、.cpp实现文件和相关说明文档覆盖从驱动适配到API实现的完整结构。目前已有2366人参与学习下载适合刚接触显示模块的入门者以及希望快速集成屏幕的进阶开发者。资源内提供超过200种显示驱动适配代码读者可直接参考初始化流程、drawString文本输出、drawRect图形绘制等常用API并结合页面模式理解如何节省RAM、提高刷新效率。借助这些源码和示例可快速掌握从接线调试到动态界面实现的完整方法为物联网设备或交互装置增添可视化功能。 第一次拿到0.96寸OLED屏的时候我还在用Adafruit的库换一块1.3寸的屏就得换驱动、换初始化代码碰到SH1106控制器的屏更是折腾到怀疑人生。后来在一个智能小车项目里需要同时显示电池电压、转向角度和传感器日志Adafruit库的字体又少得可怜我才彻底转投u8g2。这块库几乎是Arduino圈子里驱动OLED和LCD单色屏的事实标准控制器覆盖从SSD1306、SH1106到ST7920、SSD1325等一大票自带上百种字体还支持I2C、SPI、并行等几乎所有通信方式。这篇文章就围绕u8g2库的选型逻辑、初始化细节、绘图API、中文字库和实战避坑展开适合刚入门想点亮屏幕的新手也适合正在做项目但被显示效率、字体和内存问题卡住的朋友。1. 为什么是u8g2一块屏库通吃所有单体OLED1.1 从Adafruit转过来的真实理由单纯从“点亮一块SSD1306的0.96寸屏”这个角度来说Adafruit_SSD1306和u8g2都能干。但项目一复杂差距就出来了。Adafruit库是“一屏一库”SSD1306一套、SH1106又要另一套u8g2则是“统一接口”无论你用的是哪家控制器代码主体几乎不用动改一行构造声明其它绘图逻辑照常跑。我最早是被这点吸引的。后来把1.3寸的SH1106插上去只改了构造函数连字体、坐标、绘制逻辑全部复用那一刻确实有“早该转”的感觉。1.2 覆盖范围和缓冲机制两个关键概念u8g2最核心的价值第一是控制器覆盖极广。官方README上列了SSD1306、SSD1309、SH1106、SSD1315、ST7920、SSD1325、SSD1327、LD7032等几十种基本你手里那块单色屏它都认识。第二是它提供了两种缓冲工作模式全屏缓冲Full Buffer在内存中开一整块和屏幕像素对应的缓冲区绘图操作都在缓冲区完成最后一次性sendBuffer()刷到屏幕。内存占用大——128x64的屏是1024字节但对UNO来说还能接受128x128的屏就得4096字节UNO的2KB SRAM直接爆掉这时候就必须考虑用页面缓冲模式或者换主控。页面缓冲Page Buffer屏幕被分成多个8像素高的页每次只处理其中几页通过回调或者循环调用nextPage()逐步刷新。内存占用只有原来的一小部分适合ATmega328P这种RAM紧张的老平台。选型逻辑其实很清晰RAM够就全屏缓冲写代码最舒服RAM吃紧就用页面缓冲牺牲一点代码直观性换内存。我在UNO上跑128x64屏一般直接全屏缓冲反正1024字节以内别的东西省着点就行。1.3 通信方式选I2C还是SPIu8g2构造函数的第一个长名称里已经写明了通信协议。实际选型建议很简单I2C只占两根线SDA和SCL接线最省但速度一般在400kHz以内刷新复杂动画会感觉拖沓。SPI四根线起步SCK、MOSI、CS、DC刷新速度明显快一截适合做菜单切换、数值实时更新这种动态内容。并行接口速度最快但占引脚太多Arduino UNO这种引脚本来就紧张的主控基本不推荐。我自己的习惯做桌面小摆件、静态信息屏这类不追求刷新率的用I2C做小车显示器、需要实时刷新波形或快速翻页的用SPI。如果不确定以后会不会做动画直接上SPI比较省心。2. 环境搭建与初始化从库安装到第一行像素2.1 安装库的正确姿势Arduino IDE的库管理器搜索“u8g2”作者是olikraus的那个就是。直接点Install不需要手动去GitHub下载zip。这里有两点容易踩坑不要和另一个叫“U8glib”的老库混淆。U8glib是u8g2的前身已经不太维护新项目一律用u8g2。用Arduino IDE 1.8.x还是2.x都行但2.x的库管理器偶尔会在代理环境下下载失败失败以后多半不是库本身的问题而是网络环境导致的超时重试或者检查环境变量即可。安装完以后在 文件 示例 里能看到u8g2的示例菜单里面有大量针对不同控制器的example小到SSD1306大到ST7920都能找到对应模板这一步能省掉很多手写构造函数的痛苦。2.2 读懂那一长串构造函数u8g2库最劝退新人的就是构造函数名字写出来能占两行U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, /* clock*/ SCL, /* data*/ SDA, /* reset*/ U8X8_PIN_NONE);拆开看其实是几个固定字段U8G2_固定前缀表明这是一个u8g2构造声明。SSD1306控制器型号。128X64屏幕分辨率注意这里X是大写。NONAME面板版本标识绝大部分屏填NONAME一些特殊厂商的屏会有别的代号比如“V”版本之类具体看你买的屏的规格。F代表Full Buffer全屏缓冲如果是“1”是页面缓冲的第一页模式U8G2页面缓冲模式下还有“_1”、“_2”这类分页参数。HW_I2C表示使用硬件I2C如果写SW_I2C则是软件模拟I2C。U8G2_R0是旋转方向R0不转R1、R2、R3分别是90度、180度、270度。这个命名规范是u8g2的核心设计哲学用类型名直接把配置写死让编译器替你挡掉错误。比如你换了块SPI屏只需要把最后那部分改成“_4W_SW_SPI”或者“_4W_HW_SPI”并对应调整引脚参数其他代码完全不用动。2.3 接线和最小上电示例以最常见的中景园0.96寸I2C屏为例它只引出VCC、GND、SCL、SDA四个引脚。Arduino UNO/Nano下SCL接A5、SDA接A4VCC接3.3V或5V要看屏的具体设计——大多数模块板上带稳压和电平转换可以接5V但如果是纯裸屏保险起见接3.3V。把示例里的I2C i2c例程烧进去能看到屏幕上出现字说明这块屏和接线都没问题。这里我给一个最小可用的测试代码结构#include Arduino.h #include U8g2lib.h U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, /* clock*/ SCL, /* data*/ SDA, /* reset*/ U8X8_PIN_NONE); void setup(void) { u8g2.begin(); u8g2.setFont(u8g2_font_ncenB08_tr); u8g2.drawStr(0, 20, Hello U8g2!); u8g2.sendBuffer(); } void loop(void) { }记住u8g2的逻辑先begin再设置字体然后画内容最后sendBuffer。全屏缓冲模式下所有draw函数其实是在内存里画不调用sendBuffer屏幕不会变。3. 绘图与文字API把屏幕当成一块可编程画布3.1 坐标系和基本图形u8g2的坐标系以左上角为(0,0)x轴向右y轴向下单位是像素。掌握这点后任何绘图API都很好理解。最常用的绘图函数我总结成几类像素和点u8g2.drawPixel(x, y)线条和矩形drawLine(x0, y0, x1, y1)、drawFrame(x, y, w, h)、drawBox(x, y, w, h)圆和椭圆drawCircle(x0, y0, rad)、drawEllipse(x0, y0, rx, ry)三角drawTriangle(x0, y0, x1, y1, x2, y2)位图drawXBMP(x, y, w, h, bitmap[])实心的用Box、Triangle空心轮廓用Frame、Circle这个区分很符合直觉。如果你需要画“进度条”无外乎先drawFrame画外框再用drawBox按比例填充。3.2 字体系统内置字体就够用u8g2最被低估的功能是它自带的字体库。官方文档里字体列表有几百种命名规则也很有规律比如u8g2_font_ncenB08_tr代表“New Century SchoolbookBold8像素高tr是只包含ASCII可打印字符的Latin子集”。选字体时直接取“要多大点阵、要不要加粗、要不要斜体”三个变量去列表里挑就行。要注意drawStr()函数有多个重载drawStr(x, y, text)最基础字体左上角对齐到(x,y)。drawUTF8(x, y, text)支持UTF-8编码字符串后面中文字库部分会用到。drawStr配合setFontDirection()可以绘制旋转文字。显示变量时一般这么干char buf[10]; sprintf(buf, %d.%02dV, voltage/100, voltage%100); u8g2.drawStr(0, 40, buf);这里有个容易掉进去的坑默认字体是英文半角数字和字母没问题但如果你直接往里扔中文屏幕上会出现空白或乱码。这就是中文字库的问题后面专门讲。3.3 动画和刷新策略全屏缓冲模式下做动画很简单循环里clearBuffer()、画、sendBuffer()。但直接裸循环刷屏会有闪烁感改善方法是用setFlipMode(1)翻转屏幕方向配合屏的物理刷新参数来减少视觉闪烁。我调试智能小车显示界面时的标准做法是分区域刷新把屏幕手动分成状态栏、数据区、日志区每个区域只要数据变了才重绘。u8g2本身不提供局部刷新API但你可以自己维护一个“脏矩形”逻辑——判断哪些区域变了只重画那部分。这样不仅省CPU更省RAM里缓冲区的擦写频率。对一个每秒只更新10次的静态屏用默认全量刷新完全没问题。但如果是波形显示或者滚动日志全量刷新会明显拖沓这时建议要么换SPI屏要么用页面缓冲配合局部逻辑。4. 中文字库实战让屏幕显示中文的完整方案4.1 为什么默认字体不支持中文u8g2内置字体集只覆盖Latin和少量Cyrillic等中文字符集太大动不动几千个常用字如果全量内置flash和RAM都扛不住。Arduino UNO的flash只有32KB放一套完整的16x16中文字库就要两三KB起步再加上u8g2代码本身空间会非常紧。所以中文字库的处理思路是按需取字。你需要显示哪些中文就把这些字的字模生成成一串数组然后通过u8g2的XBM绘制或者自定义字体功能输出到屏幕。4.2 个人最推荐的方案字模数组 drawXBMP如果你只是要显示固定几个词比如“电压”“速度”“状态”最省事的就是用取模软件如PCtoLCD2002把每个汉字转成16x16或12x12的点阵数组然后用drawXBMP显示。操作步骤打开PCtoLCD2002设置16x16或12x12点阵选“字模格式”为C51格式生成每个字的数组。在Arduino代码中定义一个常量二维数组或多个一维数组const unsigned char hanzi_dianya[] { 0x00,0x00, ... }; // 电字的16x16字模显示时调用u8g2.drawXBMP(0, 0, 16, 16, hanzi_dianya);这个方案只适合显示少量固定汉字。如果你想显示“当前温度25.3℃”这种动态数据直接拼字模数组会很痛苦——只能预先把“当前温度℃”这几个字都取好再配合变量数字动态拼接。4.3 进阶方案用FontTool生成Unicode字库如果你要显示的中文较多或者内容不固定比如滚动播报多行文本我更推荐用u8g2官方提供的字体转换工具。这套工具可以把TTF字体文件裁剪出你需要的字生成一个包含Unicode映射的C字库文件然后放进Arduino工程里一起编译。基本流程下载u8g2源码仓库里的tools/font/build工具或使用在线版本的u8g2字体转换页。选择一个简体中文字体TTF指定点阵尺寸12、16、24在字符映射表里挑选需要的字符范围常用字、标点、数字、字母全选。导出的C文件里会有一大段const uint8_t u8g2_font_myfont_t[]这样的数据复制到Arduino工程的同一个tab下。代码里用u8g2.setFont(u8g2_font_myfont_t)后直接u8g2.drawUTF8(0, 20, 你好世界)就能正常显示中文。这个方案才是u8g2真正强大的地方——它把中文字体也纳入和英文字体一样的渲染管线支持透明背景、旋转、反白等所有文字特效。内存上每次只多占用被选中字体的字模数据按需加载很合适嵌入式环境。4.4 动态中文字符串拼接的坑用drawUTF8时还需要注意字符串编码。如果你在Arduino IDE里直接写中文IDE会以UTF-8保存源码u8g2的drawUTF8正好接受UTF-8输入。但如果你是从串口、蓝牙模块接收中文字符可能是GBK或GB2312编码直接丢给drawUTF8就会乱码。这种情况下需要先做编码转换或者约定通讯协议统一用UTF-8。我实际做一个温湿度显示面板时就是先在PC上把可能用到的中文词表定下来生成一版32号大小的字库然后EPROM里只存数据界面上动态拼xbm数组最后效果比预想中好不少刷新也快。5. 实战避坑清单踩过的屏和库的几个深坑5.1 0.96寸屏不等于全是128x64市面上0.96寸OLED最常见的分辨率是128x64但我也买到过128x32的“缩水版”。如果误用了128x64的构造函数屏幕能亮但显示内容会错位下半部分完全空白。排查方法很简单看屏幕外观数一下屏幕玻璃上引脚数量或者看商家标注的最高分辨率。一旦确认是128x32构造函数直接换成U8G2_SSD1306_128X32_NONAME_*坐标系统自动适配不用改其他代码。5.2 I2C地址不只有0x3CSSD1306的I2C地址默认是0x3C但有相当一部分模块把SA0引脚拉高了地址变成0x3D。u8g2库默认按0x3C扫描如果你的屏插上去什么反应都没有先用I2C扫描程序打印出设备地址#include Wire.h void setup() { Serial.begin(9600); Wire.begin(); for (byte addr 1; addr 127; addr) { Wire.beginTransmission(addr); if (Wire.endTransmission() 0) { Serial.print(Found I2C: 0x); Serial.println(addr, HEX); } } } void loop() {}如果地址是0x3D但不改代码直接跑u8g2的begin不会报错但屏幕永远不亮。这种情况在初始化时给u8g2传入一个带地址的构造参数可以解决比如U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, SCL, SDA, U8X8_PIN_NONE, 0x3D)——注意不同版本的u8g2构造重载里地址参数位置可能不同参考头文件里的说明即可。5.3 页面缓冲和箭头动画的时序冲突如果你选的是页面缓冲模式动画和多页绘制逻辑必须在一个“画一页、发送一页、画下一页”的循环里完成。初学者最常见的错误是把页面缓冲当成全屏缓冲用只画了一次就在loop里反复sendBuffer结果屏幕显示断断续续。正确用法是这样void drawPage(void) { u8g2.setFont(u8g2_font_ncenB08_tr); u8g2.drawStr(0, 10, Page); u8g2.drawFrame(20, 20, 30, 30); } void loop(void) { u8g2.firstPage(); do { drawPage(); } while (u8g2.nextPage()); delay(50); }这里的do-while结构让库每次渲染内存里的一页循环到全部页面发完。每次loop刷新一次完整页面动画看起来是连续性的但CPU占用确实比全屏缓冲高。5.4 供电不足导致的花屏和复位OLED模块启动瞬间电流不低如果供电线过长或者稳压模块余量不够屏幕会出现随机花屏、复位、亮度不均等问题。特别是用ESP32这类模块直接给屏供电时WiFi发射瞬间电流尖峰能把屏拉花。解决思路屏的VCC尽量从主电源端单独引线不要和舵机、电机共用一根杜邦线。在VCC和GND之间并一个100uF电解电容能显著改善供电稳定性。如果屏幕支持初始化时给reset引脚接一个Arduino引脚配合u8g2.begin()完成硬件复位也能减少上电不稳的问题。5.5 Wokwi仿真和真实硬件的差异现在很多教程用Wokwi在线仿真Arduinou8g2在Wokwi里也支持但要注意仿真环境里的I2C时序和真实硬件不完全一样。仿真下感觉“刷新挺快”的代码烧到真实UNO上可能会觉得拖沓仿真里没接上拉电阻默认也能跑但真实I2C总线必须外接4.7kΩ上拉电阻或者使用模块自带上拉。从仿真搬到真机前至少要做三件事确认引脚定义一致、确认屏的驱动型号一致、确认I2C地址一致。这三项我都分别踩过每次都是静下心来逐个核对才解决。写在最后一个小技巧调试u8g2时最容易让人抓狂的是“代码没问题但屏就是不亮”。我现在的排查习惯是先看构造函数是不是和屏完全匹配再看I2C扫描能不能找到设备最后才怀疑代码逻辑。三步走基本能解决九成问题。另外u8g2的示例代码本身就是一本很好的参考手册。每一个硬件组合都配了对应的example改几个参数就能跑通。你不需要背API只要能快速找到“我这块屏对应哪个示例文件”就算入门成功了。最后再分享一个实用经验不要一上来就追求动画和复杂字体。先把静态显示调通再逐步加动态刷新、加中文字库每一步都验证通过再走下一步。u8g2虽然强大但它本质还是“一块内存画布一个刷屏动作”的简单模型理解了这个模型剩下的就是熟练度问题。本文还有配套的精品资源点击获取