如何把OLED_UI移植到你自己的项目?STM32/ESP32/Arduino全平台移植教程

原创2026-11-15 18:29:481,377 阅读

如何把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 # 示例菜单数据

移植工作量其实很小,真正需要动手的只有两处:

  1. 软件驱动的 GPIO/通信层(点亮屏幕);
  2. 硬件驱动的按键、定时器、编码器(操作界面)。

二、第一步:点亮你的 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 个坑:

  1. 中文不显示,英文正常:多半是编码问题。若源文件是 UTF-8 编码,打开 OLED_Fonts.h,把 OLED_CHN_CHAR_WIDTH 的 2 改成 3(GB2312 用 2,UTF-8 用 3)。
  2. 显示错位或只有部分屏幕有内容:检查 OLED.h 中的 OLED_WIDTH / OLED_HEIGHT 宏是否与实际分辨率一致(128×64、128×128 等)。
  3. I2C 通信偶尔失败:高主频 MCU 使用软件 I2C 时,建议在置高低电平的函数里加入适当延时,保证屏幕正确接收数据。

支持的屏幕型号(SSD1306/SH1106/SH1107,128×32/64/128,I2C/SPI)对照表见 README.md 中的总览部分,可按你的屏幕型号选择对应例程。

六、下一步:打造属于自己的菜单

跑通示例后,参考 README.md 中"创建自己的第一个列表类菜单"一章,只需两步就能搭建自己的界面:

  1. 定义 MenuItem 数组(文本、回调、子菜单页指针,最后一项 NULL 收尾);
  2. 定义 MenuPage 结构体(菜单类型、光标样式、字体、移动动画风格等),传入 OLED_UI_Init()。

框架还支持磁贴主菜单、GIF 图标、淡入淡出转场、长按加速滚动等特性,相关可配置宏都集中在 OLED_UI.h 文件头部,注释详尽,按需调整即可。

💡 小贴士:移植完成后欢迎回头看看 OLED_UI_Examples/MSPM0G3507/ccs/oeldui/README.md,里面展示了一个包含 RGB 灯效、陀螺仪、串口监视器和 3 个小游戏的完整菜单系统,是很好的进阶参考。

登录后查看全文
OLED_UI