---
title: "Esp32 OLED Counter Display"
date: 2025-11-10T19:10:33+02:00
tags: []
author: "Elias Ahokas"
showToc: true
TocOpen: false
draft: false
hidemeta: false
comments: false
description: "Desc Text."
canonicalURL: "https://canonical.url/to/page"
disableShare: false
disableHLJS: false
hideSummary: false
searchHidden: false
ShowReadingTime: true
ShowBreadCrumbs: true
ShowPostNavLinks: true
ShowWordCount: true
ShowRssButtonInSectionTermList: true
UseHugoToc: true
cover:
    image: ""
    alt: ""
    caption: ""
    relative: false
    hidden: true

---

![Project working](photo_2025-11-10_15-36-01.jpg)

Integrating LVGL embedded graphics library with SSD1306 OLED display on ESP32.

[Source code](https://git.sirian.me/sirian/oled-counter-esp32/src/branch/main)

## Project goal

Get LVGL working on a 128x64 monochrome OLED display connected to ESP32 with I2C. Quick googling resulted only in outdated libraries. This implementation uses the latest libraries to ensure future proofing.

## Main challenge

LVGL outputs pixels in a linear framebuffer format but the display uses page addressing where the screen is divided into 8 horizontal pages of 128x8 pixels. Required implementing a custom flush callback to convert between these formats.

## Implementation

- Custom I2C driver for SSD1306 using ESP-IDF's master driver API
- Multi-threaded FreeRTOS architecture separating rendering, display updates and application logic
- Pixel format conversion algorithm for transforming LVGL's I1 framebuffer to SSD1306 page format
- Queue based page transmission system for non blocking I2C operations
- Semaphore protected flush pipeline ensuring thread safe rendering