Switch branches/tags
Nothing to show
Find file History
mainr Update u8g2_esp32_hal.c
To ensure use of GPIO32 & GPIO33 are supported (34-39 are input only), must define literal constant as 'unsigned long long', or the compiler produces code that fails to perform the required shift, resulting in corruption of the GPIO matrix.
Latest commit f182335 Mar 3, 2018
Failed to load latest commit information.
u8g2_esp32_hal.c Update u8g2_esp32_hal.c Mar 3, 2018


ESP32 U8G2 library support

There is an excellent open source library called u8g2 that can be found on Github here:


The purpose of the library is to provide a display independent driver layer for monochrome displays including LCD and OLED. The library "knows" how to driver the underlying displays as well as providing drawing primitives including text, fonts, lines and other geometrical shapes.

A version of the library is available in cleanly compiling C and compiles without incident on the ESP32-IDF framework.

However, since the library is agnostic of MCU environments and will work on a variety of boards, there has to be a mapping from the functions expected by the library to the underlying MCU board hardware. This includes driving GPIOs, I2C, SPI and more.

The code in this folder provides a mapping from U8g2 to the ESP32 ESP-IDF. This should be included in your build of U8g2 applications.

To use with the ESP32, we must invoke the u8g2_esp32_hal_init() function before invoking any of the normal U8g2 functons. What this call does is tell the ESP32 what pins we wish to map. Here is an example of SPI use:

u8g2_esp32_hal_t u8g2_esp32_hal = U8G2_ESP32_HAL_DEFAULT;
u8g2_esp32_hal.clk   = PIN_CLK;
u8g2_esp32_hal.mosi  = PIN_MOSI;
u8g2_esp32_hal.cs    = PIN_CS;
u8g2_esp32_hal.dc    = PIN_DC;
u8g2_esp32_hal.reset = PIN_RESET;

and here is an example of I2C use:

u8g2_esp32_hal_t u8g2_esp32_hal = U8G2_ESP32_HAL_DEFAULT;
u8g2_esp32_hal.sda = PIN_SDA;
u8g2_esp32_hal.scl = PIN_SCL;

Note: For I2C, after calling the display specific setup, invoke:


Note that <address> is the I2C address already shifted left to include the read/write flag. For example, if you are using an SSD1305, instead of supplying the address 0x3C which would be 0011 1100 supply 0x78 which would be 0111 1000.

The function takes as input a u8g2_esp32_hal structure instance which has the logical pins that U8g2 needs mapped to the physical pins on the ESP32 that we wish to use. If we don't use a specific pin for our specific display, set the value to be U8G2_ESP32_HAL_UNDEFINED which is the default initialization value.

Remember, ESP32 pins are not hard-coded to functions and as such, all the GPIO pins on the ESP32 are open for use. Following this initialization, we can use U8g2 as normal and described in the U8g2 documentation.

Compiling U8G2

To use the actual U8g2 library in your ESP32 project, perform the following steps:

  1. Create a directory called components in your main project directory.
  2. Change into the components directory.
  3. Run git clone https://github.com/olikraus/u8g2.git to bring in a the latest copy of u8g2 library.
  4. Change into the u8g2 directory.
  5. Create a file called component.mk
  6. Enter the following in the component.mk file:


While in principal, there should be nothing specific needed beyond this addition to make U8g2 work on the ESP32, only a small number of boards have been tested.