如何把OLED_UI移植到你自己的项目?STM32/ESP32/Arduino全平台移植教程
如何把OLED_UI移植到你自己的项目?STM32/ESP32/Arduino全平台移植教程
OLED_UI 是一个用 C 语言编写的丝滑 OLED 显示界面框架,内置多级菜单、磁贴主页、弹窗窗口、滑动条、GIF 动画等组件,不依赖 U8G2 等第三方图形库,对资源要求极低。本文将从目录结构讲起,带你一步步完成 OLED_UI 移植:只需要具备基本的 GPIO 控制能力,在 STM32、ESP32、Arduino、MSPM0 等平台上都可以部署,72MHz 的 STM32F103 上甚至能跑出 80Hz以上的流畅刷新率。
一、移植前:先认识 OLED_UI 的框架结构
动手之前,先克隆仓库并了解代码组织方式:
git clone https://gitcode.com/gh_mirrors/ol/OLED_UI
仓库分为两大部分:
| 目录 | 作用 | 移植时的角色 |
|---|---|---|
| OLED_UI_Core | 框架核心源码 | 你要拷贝到自己工程里的文件 |
| OLED_UI_Examples | 各平台例程 | 参考用,里面有按键、定时器等的现成实现 |
核心源码的层级一目了然:
OLED_UI_Core/HAL/OLED_UI_Core/
├── Driver/
│ ├── Hardware_Driver/ # 按键、编码器、定时器驱动 ← 需要修改
│ └── Software_Driver/ # OLED 底层驱动、字库、应用层 ← 需要少量修改
└── OLED_UI/
├── OLED_UI.c # 菜单/窗口/动画等 UI 框架 ← 一般不用改
└── OLED_UI_MenuData.c # 示例菜单数据
移植工作量其实很小,真正需要动手的只有两处:
- 软件驱动的 GPIO/通信层(点亮屏幕);
- 硬件驱动的按键、定时器、编码器(操作界面)。
二、第一步:点亮你的 OLED 屏幕
2.1 拷贝 OLED 基础库
把 OLED_UI_Core/HAL/OLED_UI_Core/Driver/Software_Driver 下的 6 个文件复制到你的工程目录,并按下表决定改不改:
| 文件 | 描述 | 是否需要修改 |
|---|---|---|
| OLED_driver.c | 底层驱动文件 | ✅ 需要 |
| OLED.h | 底层驱动头文件 | ✅ 需要 |
| OLED.c | 应用层文件 | 不需要 |
| OLED_Fonts.c | 字库文件 | 不需要 |
2.2 修改 GPIO 与通信函数
打开底层驱动文件,做两件事:
- 修改
OLED_Init(void)中的 GPIO 初始化部分,换成你自己的引脚初始化代码; - 修改 GPIO 置高/置低电平函数,适配你的 GPIO 驱动(硬件 I2C 或软件 I2C/SPI 都行)。
2.3 写一个最小测试
在你的 main 函数中测试屏幕是否工作正常:
#include "OLED.h"
int main(){
OLED_Init();
while(1){
OLED_Clear();
OLED_PrintfMix(0, 0, OLED_12X12FULL, OLED_7X12_HALF, "你好,HI.");
OLED_Update();
}
}
能显示"你好,HI."就说明 OLED 基础库移植成功,可以进入下一步。
三、第二步:移植 OLED_UI 框架本体
3.1 拷贝 UI 框架文件
将 OLED_UI_Core/HAL/OLED_UI_Core/OLED_UI 目录下的 OLED_UI.c、OLED_UI.h、OLED_UI_MenuData.c(示例菜单数据)拷入工程,以及 OLED_UI_Core/HAL/OLED_UI_Core/Driver/Hardware_Driver 下的 OLED_UI_Driver.c/.h。
3.2 实现按键与硬件接口
打开 OLED_UI_Driver.h,按实际硬件实现以下几类接口:
| 接口 | 说明 | 是否必须 |
|---|---|---|
Key_GetEnterStatus() 等 4 个宏 |
读取确认/返回/上/下按键状态 | ✅ 必须 |
Timer_Init() / Key_Init() |
定时器与按键初始化 | 定时器可选 |
Encoder_Init() / Encoder_Get() |
编码器控制 | ❌ 可选(不需要就置空、返回 0) |
Delay_ms() / Delay_s() |
延时函数 | ✅ 必须 |
其中 定时器建议配置成 20ms 周期中断,框架靠它实现精确的停留延时和帧率统计;实在没有定时器中断,也可以把 OLED_UI_InterruptHandler() 直接放进主循环调用,只是帧率统计不再精确。
3.3 主函数接线,跑通示例
#include "OLED_UI.h"
#include "OLED_UI_MenuData.h"
int main() {
OLED_UI_Init(&MainMenuPage); // 指定主菜单页面
while(1) {
OLED_UI_MainLoop(); // UI 主循环
}
}
void Timer() { // 20ms 定时器中断
OLED_UI_InterruptHandler(); // 中断服务函数
}
编译烧录后,示例菜单(列表、磁贴、弹窗、滑动条)应该都能正常操作。到这里,移植就完成了 🎉
四、不同平台怎么移植?
| 平台 | 参考例程 | 说明 |
|---|---|---|
| STM32(Keil/STM32Cube) | OLED_UI_Examples/STM32F103c8t6、OLED_UI_Examples/STM32G031G8U6 | 框架核心源码即按 STM32 HAL 风格组织,改动最小 |
| ESP32(PlatformIO/Arduino) | 见 README.md 中 ESP32 例程说明 | 按键宏可直接用 digitalRead(PIN) |
| Arduino(C/C++ 均可) | 同上 | 框架为纯 C(C99),在 C++ 的 Arduino 下也能编译 |
| MSPM0(CCS) | OLED_UI_Examples/MSPM0G3507、OLED_UI_Examples/MSPM0G3519 | 完整演示按键状态机、RGB 灯效、小游戏集成 |
移植思路完全一致:先改软件驱动点亮屏幕,再改硬件驱动接上按键,最后跑示例。拿不准某个接口怎么写时,直接翻对应平台的例程目录,里面都有现成实现可以抄作业。
五、常见问题排查清单
移植过程中最容易踩的 3 个坑:
- 中文不显示,英文正常:多半是编码问题。若源文件是 UTF-8 编码,打开 OLED_Fonts.h,把
OLED_CHN_CHAR_WIDTH的 2 改成 3(GB2312 用 2,UTF-8 用 3)。 - 显示错位或只有部分屏幕有内容:检查 OLED.h 中的
OLED_WIDTH/OLED_HEIGHT宏是否与实际分辨率一致(128×64、128×128 等)。 - I2C 通信偶尔失败:高主频 MCU 使用软件 I2C 时,建议在置高低电平的函数里加入适当延时,保证屏幕正确接收数据。
支持的屏幕型号(SSD1306/SH1106/SH1107,128×32/64/128,I2C/SPI)对照表见 README.md 中的总览部分,可按你的屏幕型号选择对应例程。
六、下一步:打造属于自己的菜单
跑通示例后,参考 README.md 中"创建自己的第一个列表类菜单"一章,只需两步就能搭建自己的界面:
- 定义
MenuItem数组(文本、回调、子菜单页指针,最后一项NULL收尾); - 定义
MenuPage结构体(菜单类型、光标样式、字体、移动动画风格等),传入OLED_UI_Init()。
框架还支持磁贴主菜单、GIF 图标、淡入淡出转场、长按加速滚动等特性,相关可配置宏都集中在 OLED_UI.h 文件头部,注释详尽,按需调整即可。
💡 小贴士:移植完成后欢迎回头看看 OLED_UI_Examples/MSPM0G3507/ccs/oeldui/README.md,里面展示了一个包含 RGB 灯效、陀螺仪、串口监视器和 3 个小游戏的完整菜单系统,是很好的进阶参考。