# thingpulse/esp8266-oled-ssd1306 architecture

> Architecture diagram of the GitHub repository thingpulse/esp8266-oled-ssd1306, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thingpulse/esp8266-oled-ssd1306
- Repository: https://github.com/thingpulse/esp8266-oled-ssd1306

## Overview

This is an Arduino/ESP8266/ESP32 and mbed OLED driver for SSD1306 and SH1106 displays. An application chooses a display adapter, draws text and graphics into the shared display buffer, then transfers the rendered content over I2C or SPI to the physical OLED. The UI helper adds callback-driven frames, timed transitions, animations, and indicators. The graph preserves the documented transport/controller options; relationships for adapters whose implementations were not excerpted are shown as unverified where appropriate.

Main entry points: [`src/OLEDDisplay.h`](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/OLEDDisplay.h) (Display API), [`src/SSD1306Wire.h`](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SSD1306Wire.h) (SSD1306 Wire), [`src/SH1106Wire.h`](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SH1106Wire.h) (SH1106 Wire), [`src/OLEDDisplayUi.cpp`](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/OLEDDisplayUi.cpp) (Frame UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_render["Rendering"]
  node_renderer["Display Renderer<br/>[OLEDDisplay.cpp]"]
  node_display_api["Display API<br/>[OLEDDisplay.h]"]
  node_fonts["Built-in Fonts<br/>[OLEDDisplayFonts.h]"]
end

subgraph group_ui["Screen UI"]
  node_screen_ui["Frame UI<br/>[OLEDDisplayUi.cpp]"]
  node_ui_api["UI API<br/>[OLEDDisplayUi.h]"]
end

subgraph group_i2c["I2C Adapters"]
  node_ssd_wire["SSD1306 Wire<br/>[SSD1306Wire.h]"]
  node_sh_wire["SH1106 Wire<br/>[SH1106Wire.h]"]
  node_ssd_brzo["SSD1306 Brzo<br/>[SSD1306Brzo.h]"]
  node_sh_brzo["SH1106 Brzo<br/>[SH1106Brzo.h]"]
  node_ssd_mbed["SSD1306 mbed I2C<br/>[SSD1306I2C.h]"]
  node_ssd_selector["SSD1306 Selector<br/>[SSD1306.h]"]
  node_sh_selector["SH1106 Selector<br/>[SH1106.h]"]
end

subgraph group_other["Other Adapters"]
  node_ssd_spi["SSD1306 SPI<br/>[SSD1306Spi.h]"]
  node_sh_spi["SH1106 SPI<br/>[SH1106Spi.h]"]
end

node_application(("Application"))
node_oled_hardware["OLED Display"]

node_application -->|"selects I2C"| node_ssd_wire
node_application -->|"selects I2C"| node_sh_wire
node_application -->|"selects Brzo I2C"| node_ssd_brzo
node_application -->|"selects Brzo I2C"| node_sh_brzo
node_application -->|"selects SPI"| node_ssd_spi
node_application -->|"selects SPI"| node_sh_spi
node_application -->|"selects mbed I2C"| node_ssd_mbed
node_application -->|"configures frames"| node_screen_ui
node_screen_ui -->|"initializes display"| node_renderer
node_screen_ui -->|"draws frames"| node_renderer
node_display_api -->|"includes font data"| node_fonts
node_ssd_wire -->|"extends renderer API"| node_display_api
node_sh_wire -->|"extends renderer API"| node_display_api
node_ssd_brzo -->|"extends renderer API"| node_display_api
node_sh_brzo -.->|"extends renderer API"| node_display_api
node_ssd_mbed -->|"extends renderer API"| node_display_api
node_ssd_spi -->|"extends renderer API"| node_display_api
node_sh_spi -->|"extends renderer API"| node_display_api
node_ssd_selector -->|"selects adapter"| node_ssd_wire
node_sh_selector -->|"selects adapter"| node_sh_wire
node_renderer -.->|"renders through adapter"| node_oled_hardware
node_ssd_wire -->|"transfers over I2C"| node_oled_hardware
node_sh_wire -->|"transfers over I2C"| node_oled_hardware
node_ssd_brzo -->|"transfers over Brzo"| node_oled_hardware
node_sh_brzo -.->|"transfers over Brzo"| node_oled_hardware
node_ssd_spi -->|"transfers over SPI"| node_oled_hardware
node_sh_spi -->|"transfers over SPI"| node_oled_hardware
node_ssd_mbed -.->|"transfers over I2C"| node_oled_hardware

click node_renderer "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/OLEDDisplay.cpp"
click node_display_api "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/OLEDDisplay.h"
click node_fonts "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/OLEDDisplayFonts.h"
click node_screen_ui "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/OLEDDisplayUi.cpp"
click node_ui_api "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/OLEDDisplayUi.h"
click node_ssd_wire "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SSD1306Wire.h"
click node_sh_wire "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SH1106Wire.h"
click node_ssd_brzo "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SSD1306Brzo.h"
click node_sh_brzo "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SH1106Brzo.h"
click node_ssd_mbed "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SSD1306I2C.h"
click node_ssd_spi "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SSD1306Spi.h"
click node_sh_spi "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SH1106Spi.h"
click node_ssd_selector "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SSD1306.h"
click node_sh_selector "https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SH1106.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_renderer,node_display_api,node_fonts toneBlue
class node_screen_ui,node_ui_api toneAmber
class node_ssd_wire,node_sh_wire,node_ssd_brzo,node_sh_brzo,node_ssd_mbed,node_ssd_selector,node_sh_selector toneMint
class node_ssd_spi,node_sh_spi toneRose
class node_application,node_oled_hardware toneIndigo
```

## Components

### Rendering

- [Display Renderer](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/OLEDDisplay.cpp): `src/OLEDDisplay.cpp`
- [Display API](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/OLEDDisplay.h): `src/OLEDDisplay.h`
- [Built-in Fonts](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/OLEDDisplayFonts.h): `src/OLEDDisplayFonts.h`

### Screen UI

- [Frame UI](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/OLEDDisplayUi.cpp): `src/OLEDDisplayUi.cpp`
- [UI API](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/OLEDDisplayUi.h): `src/OLEDDisplayUi.h`

### I2C Adapters

- [SSD1306 Wire](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SSD1306Wire.h): `src/SSD1306Wire.h`
- [SH1106 Wire](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SH1106Wire.h): `src/SH1106Wire.h`
- [SSD1306 Brzo](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SSD1306Brzo.h): `src/SSD1306Brzo.h`
- [SH1106 Brzo](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SH1106Brzo.h): `src/SH1106Brzo.h`
- [SSD1306 mbed I2C](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SSD1306I2C.h): `src/SSD1306I2C.h`
- [SSD1306 Selector](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SSD1306.h): `src/SSD1306.h`
- [SH1106 Selector](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SH1106.h): `src/SH1106.h`

### Other Adapters

- [SSD1306 SPI](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SSD1306Spi.h): `src/SSD1306Spi.h`
- [SH1106 SPI](https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/src/SH1106Spi.h): `src/SH1106Spi.h`

### Other components

- **Application**
- **OLED Display**

## Connections

- Application → SSD1306 Wire: selects I2C (evidence: `README.md`)
- Application → SH1106 Wire: selects I2C (evidence: `README.md`)
- Application → SSD1306 Brzo: selects Brzo I2C (evidence: `README.md`)
- Application → SH1106 Brzo: selects Brzo I2C (evidence: `README.md`)
- Application → SSD1306 SPI: selects SPI (evidence: `README.md`)
- Application → SH1106 SPI: selects SPI (evidence: `README.md`)
- Application → SSD1306 mbed I2C: selects mbed I2C (evidence: `README.md`)
- Application → Frame UI: configures frames (evidence: `README.md`)
- Frame UI → Display Renderer: initializes display (evidence: `src/OLEDDisplayUi.cpp`)
- Frame UI → Display Renderer: draws frames (evidence: `src/OLEDDisplayUi.cpp`)
- Display API → Built-in Fonts: includes font data (evidence: `src/OLEDDisplay.h`)
- SSD1306 Wire → Display API: extends renderer API (evidence: `src/SSD1306Wire.h`)
- SH1106 Wire → Display API: extends renderer API (evidence: `src/SH1106Wire.h`)
- SSD1306 Brzo → Display API: extends renderer API (evidence: `src/SSD1306Brzo.h`)
- SH1106 Brzo → Display API: extends renderer API (evidence: `src/SH1106Brzo.h`)
- SSD1306 mbed I2C → Display API: extends renderer API (evidence: `src/SSD1306I2C.h`)
- SSD1306 SPI → Display API: extends renderer API (evidence: `src/SSD1306Spi.h`)
- SH1106 SPI → Display API: extends renderer API (evidence: `src/SH1106Spi.h`)
- SSD1306 Selector → SSD1306 Wire: selects adapter (evidence: `src/SSD1306.h`)
- SH1106 Selector → SH1106 Wire: selects adapter (evidence: `src/SH1106.h`)
- Display Renderer → OLED Display: renders through adapter
- SSD1306 Wire → OLED Display: transfers over I2C (evidence: `src/SSD1306Wire.h`)
- SH1106 Wire → OLED Display: transfers over I2C (evidence: `src/SH1106Wire.h`)
- SSD1306 Brzo → OLED Display: transfers over Brzo (evidence: `src/SSD1306Brzo.h`)
- SH1106 Brzo → OLED Display: transfers over Brzo
- SSD1306 SPI → OLED Display: transfers over SPI (evidence: `src/SSD1306Spi.h`)
- SH1106 SPI → OLED Display: transfers over SPI (evidence: `src/SH1106Spi.h`)
- SSD1306 mbed I2C → OLED Display: transfers over I2C
