OLED Driver Usage Guide¶

Overview¶

- The OLED subsystem provides a generic, transport-agnostic interface for
controlling OLED displays. It supports multiple device types (SSD1306, SSD1309, etc.)
and multiple communication backends (I2C, SPI).

- The OLED driver architecture consists of three main layers:
- - Generic OLED Driver: The top-level interface ([oled.h](Files/oled_8h.md#file-oled.h)) that application
code interacts with. Provides a device-agnostic API for rendering and control.
- - Device Drivers: Device-specific implementations (SSD1306, SSD1309) that
provide device-specific initialization, memory layouts, and communication prefixes.
- - Transport Backends: Transport-specific implementations (I2C, SPI) that
handle the actual hardware communication with the device.

- Before initializing the OLED device, ensure your I2C interface is properly
configured. Prepare the I2C initialization parameters:
- cpp
[CFBD_OLED_IICInitsParams](Classes/structCFBD__OLED__IICInitsParams.md) i2c_config = {
.device_address = SSD1309_DRIVER_ADDRESS, // 0x78
.i2c_handle = &my_i2c_interface,
.notify_tx_complete = on_i2c_transmit_complete,
.notify_error = on_i2c_error,
}; *

- Use [CFBD_GetOLEDHandle()](Files/oled_8c.md#function-cfbd-getoledhandle) to create and initialize an OLED device:
- cpp
[CFBD_OLED](Classes/structCFBD__OLED.md) oled_device;
``
if (CFBD_GetOLEDHandle(&oled_device,
CFBD_OLEDDriverType_IIC,
&i2c_config,
CFBD_TRUE)) { // Request immediate initialization
// Device handle created successfully
} *

- Here's a complete example demonstrating the OLED driver usage:
- cpp
#include "oled.h"
#include "driver/backend/oled_iic.h"
#include "driver/device/ssd1309/ssd1309.h"
#include <stdio.h>
``
void oled_demo(void) {
// Step 1: Setup I2C configuration
[CFBD_OLED_IICInitsParams](Classes/structCFBD__OLED__IICInitsParams.md) i2c_config = {
.device_address = SSD1309_DRIVER_ADDRESS,
.i2c_handle = get_i2c_interface(),
};
``
// Step 2: Get OLED device handle
[CFBD_OLED](Classes/structCFBD__OLED.md) oled_device;
if (!CFBD_GetOLEDHandle(&oled_device,
CFBD_OLEDDriverType_IIC,
&i2c_config,
CFBD_TRUE)) {
printf("Failed to initialize OLED device\n");
return;
}
``
// Step 3: Open the display
if (!oled_device.ops->open(&oled_device)) {
printf("Failed to open OLED device\n");
return;
}
``
// Step 4: Query and display device information
uint16_t width = 0, height = 0;
oled_device.ops->self_consult(&oled_device, "width", NULL, &width);
oled_device.ops->self_consult(&oled_device, "height", NULL, &height);
printf("OLED Display: %u x %u pixels\n", width, height);
``
// Step 5: Clear the display
oled_device.ops->clear(&oled_device);
oled_device.ops->update(&oled_device);
``
// Step 6: Draw some pixels
for (uint16_t x = 0; x < width; x += 2) {
oled_device.ops->setPixel(&oled_device, x, 10);
}
oled_device.ops->update(&oled_device);
``
// Step 7: Close the display
oled_device.ops->close(&oled_device);
} *

- Most operations return CFBD_bool (TRUE/FALSE) to indicate success or failure.
Common error conditions:
- Invalid device address
- I2C communication errors
- Device not initialized or opened
- Out-of-bounds coordinate access
- Always check return values before proceeding with display operations.

- - Full frame updates: Use [update()](Files/oled__iic__130x_8c.md#function-update) for complete display refresh
- Partial updates: Use update_area() for better performance when
updating only specific regions
- Buffering: The driver maintains a local frame buffer; changes are
not visible on the display until [update()](Files/oled__iic__130x_8c.md#function-update) or update_area() is called

Updated on 2026-02-03 at 13:21:55 +0000