u8g2 library usage with STM32 MCU

Several years ago I wrote couple of articles about beautiful library u8glib in context of STM32 microcontrollers. Time moves on and author of this library released newer one, u8g2. u8glib is officially deprecated and not developed anymore. We cannot afford to lose code support for our libraries, time to move to newer library!
Differences between these libraries are listed there, also there are a lot of helpful information about u8g2 library.

It is not so hard to modify your old u8glib code for newer library. I'll show you how to use this library with Nucleo-F401 board and SSD1306 display, bought on Aliexpress. Display connection is SPI, pins are GND, VCC, SCL(the same as SPI clock), SDA(the same as MOSI), RES and DC.
Wiring is:
PA5 -> SCL
PA7 -> SDA
PA9 -> OLED_RES
PC7 -> OLED_DC

I use CubeMX code generation tool to initialize all the peripheral.  OLED_RES and OLED_DC is just GPIO output. SPI1 initialized with default parameters.




u8g2 library has its own HAL wrapper, so we need to provide two necessary callbacks. One is GPIO and delay callback, the second is communication callback.  More details you can find in porting to new MCU platform guide

This is my GPIO and delay callback:

uint8_t u8x8_stm32_gpio_and_delay(U8X8_UNUSED u8x8_t *u8x8,
    U8X8_UNUSED uint8_t msg, U8X8_UNUSED uint8_t arg_int,
    U8X8_UNUSED void *arg_ptr)
{
  switch (msg)
  {
  case U8X8_MSG_GPIO_AND_DELAY_INIT:
    HAL_Delay(1);
    break;
  case U8X8_MSG_DELAY_MILLI:
    HAL_Delay(arg_int);
    break;
  case U8X8_MSG_GPIO_DC:
    HAL_GPIO_WritePin(OLED_DC_GPIO_Port, OLED_DC_Pin, arg_int);
    break;
  case U8X8_MSG_GPIO_RESET:
    HAL_GPIO_WritePin(OLED_RES_GPIO_Port, OLED_RES_Pin, arg_int);
    break;
  }
  return 1;
}

As you see,there are several messages, which should be handled. In "Porting Guide" there are two templates for both functions. Template for the GPIO and Delay callback has a lot of messages, which should be handled, but in our case most of them are unnecessary. For example, very small delays are required for software SPI communication. We have hardware SPI and we need to implement millisecond delay only. Also there are a lot of messages about pins, not related to SPI command at all.

My version of communication callback is:

uint8_t u8x8_byte_4wire_hw_spi(u8x8_t *u8x8, uint8_t msg, uint8_t arg_int,
    void *arg_ptr)
{
  switch (msg)
  {
  case U8X8_MSG_BYTE_SEND:
    HAL_SPI_Transmit(&hspi1, (uint8_t *) arg_ptr, arg_int, 10000);
    break;
  case U8X8_MSG_BYTE_INIT:
    break;
  case U8X8_MSG_BYTE_SET_DC:
    HAL_GPIO_WritePin(OLED_DC_GPIO_Port, OLED_DC_Pin, arg_int);
    break;
  case U8X8_MSG_BYTE_START_TRANSFER:
    break;
  case U8X8_MSG_BYTE_END_TRANSFER:
    break;
  default:
    return 0;
  }
  return 1;
}

As you see, two messages are just empty: U8X8_MSG_BYTE_START_TRANSFER and U8X8_MSG_BYTE_END_TRANSFER. According to this comment, possibly you can use this messages to toggle CS pin. But actually my display does not have CS pin and moreover, I think that toggling CS pin is not required after transfer. But if you will have some problems with communication, you can try to play with toggling this pin there.

I placed csrc directory of u8g2 library to Drivers directory of STM32 project, generated by CubeMX and renamed it to u8g2. Then you should add this path to includes: right click on project "Properties"->"C/C++ Build"->"Settings"->"Includes".
Include this u8g2 header in the start of main.c file:

#include "u8g2.h"

And place global u8g2 variable:

static u8g2_t u8g2;

Setup code looks like:

u8g2_Setup_ssd1306_128x64_noname_1(&u8g2, U8G2_R0, u8x8_byte_4wire_hw_spi, u8x8_stm32_gpio_and_delay_cb);
u8g2_InitDisplay(&u8g2);
u8g2_SetPowerSave(&u8g2, 0);

First line setup itself. More about startup is there. I can add only that startup functions has different endings: _1, _2 or _f: buffer size will depends on this. _1 in our case means 128 byte page buffer.

Ok, now last point, drawing procedure itself:

  while (1)
  {
    u8g2_FirstPage(&u8g2);
    do
    {
      u8g2_SetFont(&u8g2, u8g2_font_ncenB14_tr);
      u8g2_DrawStr(&u8g2, 0, 15, "Hello World!");
      u8g2_DrawCircle(&u8g2, 64, 40, 10, U8G2_DRAW_ALL);
    } while (u8g2_NextPage(&u8g2));
  }

But actually, if we'll try to compile this project, we'll get this message

Invoking: MCU GCC Linker
arm-none-eabi-gcc -mcpu=cortex-m4 -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16 -specs=nosys.specs -specs=nano.specs -T"../STM32F401RETx_FLASH.ld" -Wl,-Map=output.map -Wl,--gc-sections -o "f401_u8g2_test.elf" @"objects.list"   -lm
/home/artsin/Ac6/SystemWorkbench/plugins/fr.ac6.mcu.externaltools.arm-none.linux64_1.16.0.201807130628/tools/compiler/bin/../lib/gcc/arm-none-eabi/7.2.1/../../../../arm-none-eabi/bin/ld: f401_u8g2_test.elf section `.bss' will not fit in region `RAM'
/home/artsin/Ac6/SystemWorkbench/plugins/fr.ac6.mcu.externaltools.arm-none.linux64_1.16.0.201807130628/tools/compiler/bin/../lib/gcc/arm-none-eabi/7.2.1/../../../../arm-none-eabi/bin/ld: region `RAM' overflowed by 28920 bytes
makefile:36: recipe for target 'f401_u8g2_test.elf' failed
collect2: error: ld returned 1 exit status
make: *** [f401_u8g2_test.elf] Error 1

As we see, RAM is totally overflowed! This is due to file u8g2_d_memory.c. There are a lot of static variables, most of them is unused, but still linked into our firmware. The same is with fonts - they all will try to be linked into our FLASH region. To prevent inclusion of such dead code you should use -fdata-sections gcc option. This is what documentation says:

The operation of eliminating the unused code and data from the final executable is directly performed by the linker. In order to do this, it has to work with objects compiled with the following options: -ffunction-sections -fdata-sections.  

In SystemWorkbench for STM32 this option could be enabled there: "Properties"->"C/C++ Build"->"Settings"->"Optimization".

Ok, now it looks like that is all. Here we have result:

Source code for this example is here: https://github.com/leechwort/u8g2-stm32-example