OLED_UI puts menus on small OLED panels without the U8G2 dependency

A UI layer sized for a 128x64 panel, not for a phone

OLED_UI is a user interface framework for small monochrome OLED panels, written in C under the C99 standard and aimed at embedded targets. The scope is specific: multi-level list menus, windows and the input plumbing needed to drive them from a handful of buttons. The project's own notes say it was verified to compile and run under the C++ Arduino framework as well, so it also fits the ESP32 toolchain. Two choices stand out. First, the framework does not use the U8G2 library, and the stated reason is that the program space it occupies is not especially large. Second, it is written in C, so it can be deployed on platforms that support only C, and porting it needs little more than the ability to drive GPIO. The repository layout is two directories, `OLED_UI_Core` and `OLED_UI_Examples`, which tells you the porting story is the product: you copy files into your own project and edit the ones that touch your hardware.

Two layers you copy in: the display library and the UI core

The porting guide splits the work into two file sets. The display layer is the OLED base library, and its structure follows a well known Chinese OLED tutorial that the author credits and says he modified and extended. Six files make up that layer. `OLED_Driver.c` and `OLED_Driver.h` hold the low level driver and are marked as needing modification. `OLED_Fonts.c` and `OLED_Fonts.h` hold the font data and are marked as not needing modification. `OLED.c` and `OLED.h` are the application layer and also need no changes. The UI layer adds six more files. `OLED_UI_Driver.c` and `OLED_UI_Driver.h` drive the buttons and the encoder and do need modification, `OLED_UI.c` and `OLED_UI.h` hold the implementation and need no change yet, and `OLED_UI_MenuData.c` and `OLED_UI_MenuData.h` hold the example menu data. The layering is what keeps the framework independent of your board: everything hardware specific is confined to the two driver files, and the screen facing code in `OLED.h` exposes resolution macros you edit once for your panel.

Step one: bring the panel up before the menu layer exists

The first porting step is deliberately dull. Open `OLED_Driver.c` and `OLED_Driver.h`, find `OLED_Init(void)` and replace the GPIO initialisation with your own code, then change the functions that drive a pin high or low so they call your GPIO layer. Once that is done, include the header in your main file and run a smoke test that clears the screen and writes a mixed Chinese and English string, where Chinese uses a 12x12 font and English uses a 7x12 font, then flushes the frame buffer to the panel.

        #include "OLED.h"

        int main(){
            OLED_Init();
            while(1){
                OLED_Clear();
                OLED_Update();
            }
        }

If that compiles and runs, the panel and the base library are working, and only then do you copy in the UI files. The guide also names two traps. If ASCII characters render but Chinese characters do not, the encoding is wrong: in `OLED_Fonts.h` the macro `OLED_CHN_CHAR_WIDTH` is set to 2 for GB2312 and must be changed to 3 for UTF-8, because UTF-8 gives a Chinese character three bytes. And the resolution macros `OLED_WIDTH` and `OLED_HEIGHT` in `OLED.h` must match your actual panel.

Step two: implement the input and timing hooks the UI expects

The UI layer is driven entirely by functions and macros you supply, and the guide lists them explicitly. Key state is read through four macros named for confirm, back, up and down, and the project uses macros rather than functions on purpose, to save code size and time. Hardware initialisation expects three entry points.

        void Timer_Init(void);
        void Key_Init(void);
        void Encoder_Init(void);

The encoder has its own control and read functions.

        void Encoder_Enable(void);
        void Encoder_Disable(void);
        int16_t Encoder_Get(void);

And delays are expected in microseconds, milliseconds and seconds.

        void Delay_us(uint32_t xus);
        void Delay_ms(uint32_t xms);
        void Delay_s(uint32_t xs);

The timer is specified as a 20ms interrupt, and it is the mechanism behind precise dwell delays and behind counting the frames currently being redrawn. The encoder is optional. If you do not want one, empty those functions and return 0 from the ones that return a value, and the guide says every other function remains reachable through the four keys.

The refresh rate claim rests on software SPI, and IIC needs a delay

The framework talks to the panel over software IIC or software SPI, and the project addresses the obvious objection, that a software bus cannot keep up with animation. The stated example is an STM32F103C8T6 running at 72MHz driving a 128x128 OLED over software SPI, which the notes say holds above 80Hz refresh for most of the time. That figure belongs to that bus and that controller, so treat it as a design target rather than a promise for every panel. The IIC case gets its own warning. On a fast microcontroller, software IIC needs a delay inserted into the pin high and low functions so the panel receives data correctly, and that advice does not apply to SPI. The guide also says you are free to edit the driver and use hardware IIC instead. One display behaviour is worth knowing before you design text: a string longer than the visible area scrolls automatically, so character count is not limited by panel width.

The author flags the project as mid-refactor, twice

Maintenance here is the honest part of the story. A note dated 2025.3.3 explains that a bug appeared when the author tested on ESP32 that did not occur on STM32, probably from incorrect pointer use, and that a refactor of OLED UI was planned. The note records that the project had already been refactored twice and that the next rebuild was to sit on top of the separate OLED-Basic-Lib project, with the underlying code reorganised and refresh adapted to the full range of screens. A later note dated 2025.4.7 says the framework was reorganised, the code became safer and smaller, but that the result was still imperfect and had not been released, and that the author was stepping away for a while because of other commitments. The project would not be abandoned, the note says, and maintenance would continue once the author had time. The page still states that the project is being tidied up and optimised. The repository has no GitHub releases, and the last push was on 2026-04-28, which is the date to weigh when you decide whether to depend on it.

Screen and example coverage is partial, and the table says so

The support matrix is honest about what is finished. Of the listed controllers, a 128x64 SSD1306 over IIC and a 128x128 SH1107 over SPI have working examples, while the 128x32 SSD1306 and SSD1305, the 128x64 SH1106 on either bus, and the 128x128 SH1107 over IIC are marked as still to come. On the microcontroller side, examples exist for the STM32F103C8T6 under Keil5 and for the ESP32 under VSCode PlatformIO with the Arduino framework, while the STC8051U, the Infineon TC264 and the TI MSPm0g3507g are listed as planned with their respective IDEs. The licence is Apache 2.0, which is permissive enough for commercial firmware with the notice retained. The practical read is that OLED_UI is a workable foundation for a small OLED menu system, best suited to a team that wants the menu structure and the driver split and accepts writing the hardware glue and the remaining panel support itself.

Editorial conclusion

Adopt OLED_UI when you are driving a small OLED panel from an MCU with a C toolchain, you want menus rather than hand drawn screens, and you are willing to own the port by editing the driver files. Skip it if you need a mature widget set, if your panel resolution is not covered by the listed controllers, or if you need something the author has already flagged as still in flux. Before you start, check the screen support table for your controller and confirm that the four key macros and the 20ms timer are the interface you want to implement.

Frequently asked questions

Official sources

1. bdth-7777777/OLED_UI on GitHub
2. Issues
3. License: Apache-2.0
4. README