当前位置：首页 > news >正文

STM32移植U8G2

news 来源：原创 2025/5/2 5:40:16

STM32 移植 U8G2

u8g2 （Universal 8bit Graphics Library version2 的缩写）是用于嵌入式设备的单色图形库，可以在单色屏幕中绘制 GUI。u8g2 内部附带了例如 SSD13xx，ST7xx 等很多 OLED，LCD 驱动。内置多种不同大小和风格的字体，可以显示中文，其次就是图形程序实现线，框，圆等图形绘制。

1. 建立裸机工程

在移植 u8g2 之前先创建 STM32F103 的 Keil5 工程模板（如何搭建 Keil 模板这里不多介绍），用来编译 STM32 驱动源码和 u8g2 源码。这也是支持 u8g2 开发的一个单片机运行环境，并且调试好屏幕驱动，确保屏幕初始化成功。

屏幕驱动只是为了验证屏幕可行性，移植后方便排除因屏幕不显示的问题，u8g2 附带屏幕驱动程序，受支持的屏幕可以使用里面的驱动程序。整体移植操作和芯片无关，所以无论什么芯片移植方法都相同。

2. 下载源码

在 Github 官网搜索 u8g2 进行下载，或通过 https://github.com/olikraus/u8g2 链接下载，u8g2 没有发行版，所以直接下载 master 分支源码，下载后可以得到一个 u8g2-master.zip 这样的源码压缩包，如下图。

请添加图片描述

3. u8g2 文件概览

u8g2 源码主要需要使用 cppsrc/，csrc/ 这两个文件夹。分别为 u8g2 对 C++ 兼容支持库，u8g2 源码文件夹。

请添加图片描述

cppsrc 对 C++ 兼容支持，方便把 u8g2 移植到 C++ 应用。cppsrc 用 C++ 类简单封装了 u8g2 普通操作函数（实际还是依赖 csrc），如下所示，把 u8g2 移植到 C++ 应用才需要这部分代码。

/*u8g2_line.c */
void U8G2::drawLine(u8g2_uint_t x1, u8g2_uint_t y1, u8g2_uint_t x2, u8g2_uint_t y2) 
{u8g2_DrawLine(&u8g2, x1, y1, x2, y2);
}

其他就是一些说明文档，辅助工具程序，版本变更信息，LICENSE 等等，这部分保留 LICENSE（开源许可）其余可以删除精简工程。

4. 移植 u8g2

在 Keil 项目管理器新建一个 u8g2 文件夹，添加 u8g2 目录 u8g2/csrc/ 下所有的.c 文件。即使 u8g2 移植到 C++ 应用，这部分也是需要的（u8g2 C++ 部分实际还是依赖 csrc 的源码）。

请添加图片描述

添加 u8g2 的头文件目录 u8g2/csrc/，即 u8g2 源码和头文件在同一个目录。

5. 驱动函数选择

在 csrc 目录下屏幕驱动文件以 u8x8_d_xx_yy_zz.c 格式命名，其中 xx 芯片型号，yy 屏幕分辨率，zz 识别名称，zz 不是一定的，可以为空或 noname。

例如：SSD1312 芯片驱动，128x64 分辨率的 OLED，使用的驱动文件为 u8x8_d_ssd1312_128x64_noname.c

驱动配置函数通常和文件同名，在驱动文件中找到同名函数即可，比如这里就是：

uint8_t u8x8_d_ssd1312_128x64_noname(u8x8_t *u8x8, uint8_t msg, uint8_t arg_int, void *arg_ptr)

注意：驱动文件和驱动函数也可能不对应，例如 ssd1312 的驱动函数可能定义在 ssd1306 的驱动文件，这是 u8g2 为了把相近屏幕的驱动函数统一到一个文件。

如果要减小代码量，其它型号屏幕驱动和分辨率对应的 .c 驱动文件可以删除。

6. u8g2_d_setup.c

在 csrc 目录下找到这个文件，文件包含各种屏幕的配置函数，实上选择的屏幕驱动函数就会被这些配置函数调用。

屏幕配置函数以 u8g2_Setup_xx_yy_zz_gg_[1/2/f].c 命名，具体字段解释如下：

xx 芯片型号，ssd1306，sh1106 等等。

yy 通信方式，识不是一定的，i2c 表示为 i2c 接口，如果没有则表示 spi 通信。

zz 屏幕分辨率，128x64，128x80 等等。

gg 识别名称，gg 不是一定的，可以为 noname 也可以为空。

[1/2/f] 显存 BUF 大小，1：128字节，2：256 字节，f：1024 字节。

例如：SSD1312 芯片驱动，128x64 分辨率 SPI 通信的 OLED，希望使用 1024 字节显存，使用的配置函数为 u8g2_Setup_ssd1312_128x64_noname_f。

/*ssd1312 f*/
void u8g2_Setup_ssd1312_128x64_noname_f(u8g2_t *u8g2, const u8g2_cb_t *rotation, u8x8_msg_cb byte_cb, u8x8_msg_cb gpio_and_delay_cb)
{uint8_t tile_buf_height;uint8_t *buf;u8g2_SetupDisplay(u8g2, u8x8_d_ssd1312_128x64_noname, u8x8_cad_001, byte_cb, gpio_and_delay_cb);buf = u8g2_m_16_8_f(&tile_buf_height);u8g2_SetupBuffer(u8g2, buf, tile_buf_height, u8g2_ll_hvline_vertical_top_lsb, rotation);
}

可以看到上方函数调用了 u8x8_d_ssd1312_128x64_noname()，如果要减小代码量，其它的配置函数可以删除或注释，只留下选择的即可。

7. u8g2_d_memory.c

在 csrc 目录下找到 u8g2_d_memory.c，文件里面是 u8g2 对显存的定义。在屏幕配置函数中，只调用了 u8g2_m_16_8_f()，所以如果编译 u8g2 时如果提示内存不足，除此之外其它显存函数可以删除或注释。

uint8_t *u8g2_m_16_8_f(uint8_t *page_cnt)
{#ifdef U8G2_USE_DYNAMIC_ALLOC*page_cnt = 8;return 0;#elsestatic uint8_t buf[1024];*page_cnt = 8;return buf;#endif
}

8. 对接屏幕驱动

把屏幕相关的硬件控制对接给 u8g2，需要我们实现 GPIO 控制和数据发送这 2 个统一驱动函数，函数原型如下，函数名称可以自定义：

uint8_t (*u8x8_msg_cb)(u8x8_t *u8x8, uint8_t msg, uint8_t arg_int, void *arg_ptr);

最终通过注册的的方式提供给 u8g2。

8.1 对接 GPIO

把屏幕的 GPIO 控制函数按照用途对接到指定位置，比如 SPI 屏幕要对接 CS，DC，RESET 对应的 GPIO。

uint8_t u8x8_stm32_gpio_and_delay(u8x8_t *u8x8, uint8_t msg, uint8_t arg_int, void *arg_ptr)
{/**STM32 supports HW SPI, Remove unused cases like U8X8_MSG_DELAY_XXX & U8X8_MSG_GPIO_XXX */switch (msg) {case U8X8_MSG_GPIO_AND_DELAY_INIT:/*Insert codes for initialization*/break;case U8X8_MSG_DELAY_MILLI:/* ms Delay */sleep_ms(arg_int);break;#ifdef _USE_SPI/*SPI Interface*/case U8X8_MSG_GPIO_CS:/*Insert codes for SS pin control */HAL_GPIO_WritePin(GPIOA, GPIO_PIN_15, arg_int);break;case U8X8_MSG_GPIO_DC:/*Insert codes for DC pin control */HAL_GPIO_WritePin(GPIOD, GPIO_PIN_2, arg_int);break;case U8X8_MSG_GPIO_RESET:/*Insert codes for RST pin control*/HAL_GPIO_WritePin(GPIOB, GPIO_PIN_3, arg_int);break;case U8X8_MSG_GPIO_SPI_CLOCK:/*Insert codes for CLOCK pin control */break;case U8X8_MSG_GPIO_SPI_DATA:/*Insert codes for DATA pin control */break;#endif /*_USE_SPI*/#ifdef _USE_I2Ccase U8X8_MSG_GPIO_I2C_CLOCK:/*Insert codes for CLOCK pin control */HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, arg_int);break;case U8X8_MSG_GPIO_I2C_DATA:/*Insert codes for CLOCK pin control */HAL_GPIO_WritePin(GPIOA, GPIO_PIN_6, arg_int);break;
#endif /*_USE_I2C*/}return 1;
}

如果使用 GPIO 模拟时序通信还要对接模拟通信 GPIO，比如软件模拟 I2C 还要对接 SCL，SDA 对应 GPIO，同时还要对接延时函数，u8g2 才能模拟时序。

8.2 对接数据

把屏幕的数据发送函数对接到指定位置，如果屏幕使用 SPI 接口，U8X8_MSG_BYTE_SEND 对应的是 SPI 数据发送函数，可以参考如下写法：

uint8_t u8x8_byte_stm32_hw_spi(u8x8_t *u8x8, uint8_t msg, uint8_t arg_int, void *arg_ptr)
{HAL_StatusTypeDef _res = HAL_ERROR;switch (msg) {case U8X8_MSG_BYTE_SEND:/*Insert codes to transmit data*/_res = HAL_SPI_Transmit(&hspi3, arg_ptr, arg_int, TX_TIMEOUT);if (_res != HAL_OK) return 0;break;case U8X8_MSG_BYTE_INIT:/*Insert codes to begin SPI transmission*/break;case U8X8_MSG_BYTE_SET_DC:/*Control DC pin, U8X8_MSG_GPIO_DC will be called*/u8x8_gpio_SetDC(u8x8, arg_int);break;case U8X8_MSG_BYTE_START_TRANSFER:/* Select slave, U8X8_MSG_GPIO_CS will be called */u8x8_gpio_SetCS(u8x8, u8x8->display_info->chip_enable_level);sleep_ms(2);break;case U8X8_MSG_BYTE_END_TRANSFER:sleep_ms(2);/* Insert codes to end SPI transmission */u8x8_gpio_SetCS(u8x8, u8x8->display_info->chip_disable_level);break;}return 1;
}

如果屏幕使用 I2C 接口，U8X8_MSG_BYTE_SEND 对应的是 I2C 数据发送函数，可以参考如下写法：

uint8_t u8x8_byte_stm32_hw_i2c(u8x8_t *u8x8, uint8_t msg, uint8_t arg_int, void *arg_ptr)
{/**u8g2/u8x8 will never send more than 32 bytes between START_TRANSFER and END_TRANSFER */static uint8_t buffer[32] = {0};static uint8_t buf_idx = 0;uint8_t * data = NULL;switch (msg) {case U8X8_MSG_BYTE_SEND:data = (uint8_t *) arg_ptr;while (arg_int > 0) {buffer[buf_idx++] = *data;data++;arg_int--;}break;case U8X8_MSG_BYTE_INIT:/*add your custom code to init i2c subsystem*/break;case U8X8_MSG_BYTE_SET_DC:break;case U8X8_MSG_BYTE_START_TRANSFER:buf_idx = 0;break;case U8X8_MSG_BYTE_END_TRANSFER:HAL_I2C_Master_Transmit(_I2C_DEV, (DEV_ADDR << 1), buffer, buf_idx, TX_TIMEOUT);break;}return 1;
}

8.3 初始化外设

如果数据发送是通过单片机外设硬件实现实现的，初始化 u8g2 前先初始化外设和对应的 GPIO，例如这里初始化 SPI 接口，还有相应 GPIO。

void oled_spi3_init(void)
{/* USER CODE BEGIN SPI3_Init 0 *//* USER CODE END SPI3_Init 0 *//* USER CODE BEGIN SPI3_Init 1 *//* USER CODE END SPI3_Init 1 */hspi3.Instance = SPI3;hspi3.Init.Mode = SPI_MODE_MASTER;hspi3.Init.Direction = SPI_DIRECTION_2LINES;hspi3.Init.DataSize = SPI_DATASIZE_8BIT;hspi3.Init.CLKPolarity = SPI_POLARITY_LOW;hspi3.Init.CLKPhase = SPI_PHASE_1EDGE;hspi3.Init.NSS = SPI_NSS_SOFT;hspi3.Init.BaudRatePrescaler = SPI_BAUDRATEPRESCALER_2;hspi3.Init.FirstBit = SPI_FIRSTBIT_MSB;hspi3.Init.TIMode = SPI_TIMODE_DISABLE;hspi3.Init.CRCCalculation = SPI_CRCCALCULATION_DISABLE;hspi3.Init.CRCPolynomial = 10;if (HAL_SPI_Init(&hspi3) != HAL_OK){Error_Handler();}/* USER CODE BEGIN SPI3_Init 2 *//* USER CODE END SPI3_Init 2 */
}

8.4 初始化 u8g2

u8g2 没有对象初始化函数，自定义 u8g2 对象初始化函数，函数名称可以自定义，在初始化函数调用显示初始化及对应的屏幕配置函数，如下。

void u8g2_init(u8g2_t *u8g2)
{u8g2_Setup_ssd1312_128x64_noname_f(u8g2, U8G2_R2, u8x8_byte_stm32_hw_spi, u8x8_stm32_gpio_and_delay);u8g2_SetPowerSave(u8g2, 1);u8g2_InitDisplay(u8g2);u8g2_ClearDisplay(u8g2);u8g2_ClearBuffer(u8g2);u8g2_SetPowerSave(u8g2, 0);
}

可以看到这个就是前面讲解屏幕的配置函数，如下。

void u8g2_Setup_ssd1312_128x64_noname_f(u8g2_t *u8g2, const u8g2_cb_t *rotation, u8x8_msg_cb byte_cb, u8x8_msg_cb gpio_and_delay_cb);

该函数的 4 个参数含义：

(1) u8g2，指定待初始化的 u8g2 对象，即 u8g2 结构体。
(2) rotation，配置屏幕旋转方向，支持 U8G2_R0，U8G2_R1，U8G2_R2，U8G2_R3 四种旋转方向。
(3) byte_cb，注册数据通信发送函数。
(4) gpio_and_delay_cb：注册屏幕 GPIO 控制函数。

8.5 总结

把对接屏幕驱动用到的这些自定义函数统一编写到一个文件中，文件可自行命名，例如命名为 u8g2_stm32.c，并添加到 u8g2 之外的用户目录。

9. 测试函数

移植完成后编写应用程序测试 u8g2 是否正常，调用 u8g2 绘图函数在显存绘制内容，在 main 函数调用初始化 SPI 和 u8g2，注意在主循环中调用 u8g2 显存发送函数 u8g2_SendBuffer 将显存内容更新至屏幕，在此附上 u8g2 测试程序。

#include "u8g2.h"static u8g2_t u8g2 = {0};void draw(u8g2_t * u8g2_p)
{u8g2_SetFontMode(u8g2_p, 1);u8g2_SetFontDirection(u8g2_p, 0);u8g2_SetFont(u8g2_p, u8g2_font_inb24_mf);u8g2_DrawStr(u8g2_p, 0, 20, "U");u8g2_SetFontDirection(u8g2_p, 1);u8g2_SetFont(u8g2_p, u8g2_font_inb30_mn);u8g2_DrawStr(u8g2_p, 21, 8, "8");u8g2_SetFontDirection(u8g2_p, 0);u8g2_SetFont(u8g2_p, u8g2_font_inb24_mf);u8g2_DrawStr(u8g2_p, 51, 30, "g");u8g2_DrawStr(u8g2_p, 67, 30,"\xb2");u8g2_DrawHLine(u8g2_p, 2, 35, 47);u8g2_DrawHLine(u8g2_p, 3, 36, 47);u8g2_DrawVLine(u8g2_p, 45, 32, 12);u8g2_DrawVLine(u8g2_p, 46, 33, 12);u8g2_SetFont(u8g2_p, u8g2_font_4x6_tr);u8g2_DrawStr(u8g2_p, 1, 54, "github.com/olikraus/u8g2");
}void main()
{oled_spi_init();u8g2_init(&u8g2);for (;;) {u8g2_ClearBuffer(&u8g2);draw(&u8g2);u8g2_SendBuffer(&u8g2);}
}

10. 移植 C++ 版本

移植 C++ 版本基础步骤和前面小节介绍的步骤相同，除此之外现在继续在 Keil 项目管理器再新建一个 u8g2cpp 文件夹，然后添加 u8g2 目录 u8g2/cppsrc/ 下所有的 .cpp 文件。

请添加图片描述

10.1 u8g2 继承类

自定义 u8g2 对象初始化类，继承 U8G2 不是必须的。可以把类定义在 U8g2lib.h 文件中，或其他文件，类名称可以自定义。在类的构造函数调用对应的屏幕配置函数，例如调用 ssd1312 屏幕配置。

void u8g2_Setup_ssd1312_128x64_noname_f(u8g2_t *u8g2, const u8g2_cb_t *rotation, u8x8_msg_cb byte_cb, u8x8_msg_cb gpio_and_delay_cb);

再自定义初始化函数 SSD1312::Init()，调用 u8g2 显示初始化来初始化 u8g2。

extern "C" uint8_t u8x8_stm32_gpio_and_delay(u8x8_t *u8x8, uint8_t msg, uint8_t arg_int, void *arg_ptr);
extern "C" uint8_t u8x8_byte_stm32_hw_spi(u8x8_t *u8x8, uint8_t msg, uint8_t arg_int, void *arg_ptr);class SSD1312 : public U8G2 {
private:public: SSD1312(const u8g2_cb_t *rotation = U8G2_R2) : U8G2() {u8g2_Setup_ssd1312_128x64_noname_f(&u8g2, rotation, u8x8_byte_stm32_hw_spi, u8x8_stm32_gpio_and_delay);}bool Init() {/**note: call to u8x8_utf8_init is not required here, this is done in the setup procedures before*/setPowerSave(1); initDisplay(); clearDisplay(); clearBuffer(); setPowerSave(0);return 1;}
};

10.2 测试程序

调用 SSD1312 类对象方法，编写应用程序测试 u8g2 是否正常，调用 u8g2 绘图函数在显存绘制内容，初始化 u8g2 对象，在主循环中调用 sendBuffer 将显存内容更新至屏幕。

#include "U8g2lib.h"SSD1312 oled;void draw(SSD1312 * oled_p)
{oled_p->setFontMode(1);oled_p->setFontDirection(0);oled_p->setFont(u8g2_font_inb24_mf);oled_p->drawStr(0, 20, "U");oled_p->setFontDirection(1);oled_p->setFont(u8g2_font_inb30_mn);oled_p->drawStr(21, 8, "8");oled_p->setFontDirection(0);oled_p->setFont(u8g2_font_inb24_mf);oled_p->drawStr(51, 30, "g");oled_p->drawStr(67, 30,"\xb2");oled_p->drawHLine(2, 35, 47);oled_p->drawHLine(3, 36, 47);oled_p->drawVLine(45, 32, 12);oled_p->drawVLine(46, 33, 12);oled_p->setFont(u8g2_font_4x6_tr);oled_p->drawStr(1, 54, "github.com/olikraus/u8g2");
}void main()
{oled.Init();for (;;) {oled.clearBuffer();draw(&oled);oled.sendBuffer();}
}