esp_ssd1306 esp‐idf component

SSD1306 Display Driver (ssd1306.h)

Documentation for the ESP-IDF SSD1306 display panel driver as defined in ssd1306.h.

---

Overview

This component provides an ESP-IDF compatible driver for SSD1306-based OLED display panels, enabling easy initialization, configuration, and control over I2C. It supports common panel sizes and provides high-level drawing/text APIs including hardware/software scrolling, font support, and graphic primitives.

• Supported Panels: 128x32, 128x64, 128x128 (SSD1327)
• Platform: ESP32-S3 (ESP-IDF)
• Protocol: I2C

---

License

MIT License
Copyright (c) 2024 Eric Gionet
See LICENSE for details.

---

Features

• Initialization/configuration for popular display sizes via macros
• Font support (BDF fonts), basic text and bitmap drawing
• Hardware and software scrolling
• Drawing primitives (pixel, line, circle, rectangle, bitmap)
• Page/segment manipulation for fast graphics
• Support for display flipping, fading, and contrast control

---

Quick Usage Example

#include "ssd1306.h"

ssd1306_config_t config = SSD1306_128x64_CONFIG_DEFAULT;
ssd1306_handle_t display;
esp_err_t ret = ssd1306_init(master_i2c_bus, &config, &display);
if (ret == ESP_OK) {
    ssd1306_enable_display(display);
    ssd1306_display_text(display, 0, "Hello SSD1306!", false);
}

---

Macros

• SSD1306_128x32_CONFIG_DEFAULT
• SSD1306_128x64_CONFIG_DEFAULT
• SSD1306_128x128_CONFIG_DEFAULT

Each macro sets panel size, I2C address, clock speed, and default orientation.

---

Constants

Name	Value	Description
I2C_SSD1306_DEV_CLK_SPD	100000	Default SCL clock (Hz)
I2C_SSD1306_DEV_ADDR	0x3c	Default I2C address
SSD1306_PAGE_SEGMENT_SIZE	128	Segment size per page
SSD1306_PANEL_128x32_WIDTH	128	Width for 128x32 panel
SSD1306_PANEL_128x32_HEIGHT	32	Height for 128x32 panel
SSD1306_PANEL_128x64_WIDTH	128	Width for 128x64 panel
SSD1306_PANEL_128x64_HEIGHT	64	Height for 128x64 panel
SSD1306_PANEL_128x128_WIDTH	128	Width for 128x128 panel
SSD1306_PANEL_128x128_HEIGHT	128	Height for 128x128 panel

---

Enumerations

• ssd1306_scroll_frames_t – Frame rates for hardware scroll
• ssd1306_scroll_types_t – Scroll directions
• ssd1306_panel_sizes_t – Panel size selections (128x32, 128x64, 128x128)

---

Structures

ssd1306_config_t

Field	Type	Description
i2c_address	uint16_t	Device I2C address
i2c_clock_speed	uint32_t	SCL frequency (Hz)
panel_size	ssd1306_panel_sizes_t	Panel size selection
offset_x	uint8_t	X-axis offset
flip_enabled	bool	Display flipped when true
display_enabled	bool	Display on/off

Other structures

• ssd1306_panel_t: Panel characteristics
• ssd1306_bdf_font_t: BDF font definition
• ssd1306_page_t: Page buffer (128 segments)

---

API Reference

Initialization & Removal

• ssd1306_init(i2c_master_bus_handle_t, const ssd1306_config_t *, ssd1306_handle_t *)
• ssd1306_remove(ssd1306_handle_t) / ssd1306_delete(ssd1306_handle_t)

Panel & Page Query

• ssd1306_get_panel_size, ssd1306_get_panel_height, ssd1306_get_panel_width
• ssd1306_get_flip_state, ssd1306_get_number_of_pages
• Page/segment manipulation: ssd1306_set_pages, ssd1306_get_pages, ssd1306_display_pages

Text & Graphics

• Display text (normal, x2, x3): ssd1306_display_text, ssd1306_display_text_x2, ssd1306_display_text_x3
• Font support: ssd1306_load_bitmap_font, ssd1306_display_bdf_text, ssd1306_display_bdf_code
• Bitmaps: ssd1306_set_bitmap, ssd1306_display_bitmap, ssd1306_display_image
• Primitives: ssd1306_set_pixel, ssd1306_set_line, ssd1306_set_circle, ssd1306_set_rectangle, etc.
• Filled shapes: ssd1306_display_filled_circle, ssd1306_display_filled_rectangle
• Contrast/fade: ssd1306_set_contrast, ssd1306_display_fadeout

Scrolling

• Hardware: ssd1306_set_hardware_scroll, ssd1306_display_wrap_around
• Software: ssd1306_set_software_scroll, ssd1306_display_software_scroll_text, ssd1306_clear_display_software_scroll
• Banner/ticker: ssd1306_display_textbox_banner, ssd1306_display_textbox_ticker

Display Control

• Enable/disable: ssd1306_enable_display, ssd1306_disable_display
• Clear: ssd1306_clear_display, ssd1306_clear_display_page

Buffers & Manipulation

• ssd1306_copy_bit
• ssd1306_invert_buffer
• ssd1306_flip_buffer
• ssd1306_rotate_byte

Firmware Version

• ssd1306_get_fw_version() – Get firmware version as string
• ssd1306_get_fw_version_number() – Get firmware version as integer

---

Dependencies

• <esp_err.h>
• <driver/i2c_master.h>
• "ssd1306_version.h"
• "type_utils.h"

---

References

• SSD1306 Datasheet
• ESP-IDF I2C Master API Docs

---