# chfly2024/esp-idf-ssd1306 architecture

> Architecture diagram of the GitHub repository chfly2024/esp-idf-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/chfly2024/esp-idf-ssd1306
- Repository: https://github.com/chfly2024/esp-idf-ssd1306

## Overview

This repository is an ESP-IDF SSD1306/SH1106 display driver with many firmware demos. The usual workflow is an ESP32 demo initializes a configured I2C or SPI interface and panel, then draws text, images, animation, or scrolling content through the driver to an OLED. The driver also provides a framebuffer and drawing operations, with a bundled basic font; BDF fonts and richer graphics are demonstrated separately. Demo-to-driver links are supported by the source index’s include references. Transport implementation details are unsampled, so their dispatch links are shown as unverified.

Main entry points: [`components/ssd1306/ssd1306.h`](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/ssd1306.h) (Display API), [`components/ssd1306/ssd1306.c`](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/ssd1306.c) (Drawing and framebuffer), [`BdfFontDemo/main/main.c`](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/BdfFontDemo/main/main.c) (BDF fonts), [`ImageDemo/main/main.c`](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/ImageDemo/main/main.c) (Image drawing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_examples["Display demos"]
  node_text_demo["Text and layout<br/>[main.c]"]
  node_font_demo["BDF fonts<br/>[main.c]"]
  node_freetype_demo["FreeType rendering<br/>[main.c]"]
  node_image_demo["Image drawing<br/>[main.c]"]
  node_image_motion["Image motion<br/>[main.c]"]
  node_image_rotation["Image rotation<br/>[main.c]"]
  node_image_scroll["Image scrolling<br/>[main.c]"]
  node_animation_demo["Animation<br/>[main.c]"]
  node_race_demo["Game graphics<br/>[main.c]"]
  node_highway_demo["Highway graphics<br/>[main.c]"]
  node_encoder_demo["Rotary input demo<br/>[main.c]"]
  node_mouse_demo["Mouse interaction<br/>[main.c]"]
  node_scroll_counter["Scrolling counters<br/>[main.c]"]
end

subgraph group_driver["Driver core"]
  node_driver_api["Display API<br/>[ssd1306.h]"]
  node_driver_core["Drawing and framebuffer<br/>[ssd1306.c]"]
end

subgraph group_transport["Bus transports"]
  node_i2c_legacy["Legacy I2C"]
  node_i2c_new["New I2C<br/>[ssd1306_i2c_new.c]"]
  node_spi["SPI transport<br/>[ssd1306_spi.c]"]
end

subgraph group_assets["Fonts and assets"]
  node_basic_font["Basic 8x8 font<br/>[font8x8_basic.h]"]
  node_bdf_assets["BDF font assets<br/>[ncenR12.h]"]
  node_sprite_assets["Sprite assets<br/>[Scroll-o-Sprites.h]"]
end

node_esp(("ESP32 firmware"))
node_oled["SSD1306 / SH1106"]

node_esp -->|"runs example"| node_text_demo
node_text_demo -->|"uses API"| node_driver_api
node_font_demo -->|"uses API"| node_driver_api
node_freetype_demo -->|"uses API"| node_driver_api
node_image_demo -->|"uses API"| node_driver_api
node_image_motion -->|"uses API"| node_driver_api
node_image_rotation -->|"uses API"| node_driver_api
node_image_scroll -->|"uses API"| node_driver_api
node_animation_demo -->|"uses API"| node_driver_api
node_race_demo -->|"uses API"| node_driver_api
node_highway_demo -->|"uses API"| node_driver_api
node_encoder_demo -->|"uses API"| node_driver_api
node_mouse_demo -->|"uses API"| node_driver_api
node_scroll_counter -->|"uses API"| node_driver_api
node_driver_api -.->|"exposes operations"| node_driver_core
node_driver_core -->|"uses font data"| node_basic_font
node_driver_core -.->|"updates display"| node_oled
node_driver_core -.->|"dispatches I2C"| node_i2c_legacy
node_driver_core -.->|"dispatches I2C"| node_i2c_new
node_driver_core -.->|"dispatches SPI"| node_spi
node_font_demo -->|"loads font data"| node_bdf_assets
node_font_demo -->|"uses sprites"| node_sprite_assets
node_image_demo -->|"uses font data"| node_basic_font

click node_driver_api "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/ssd1306.h"
click node_driver_core "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/ssd1306.c"
click node_i2c_legacy "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/ssd1306_i2c_legacy.c"
click node_i2c_new "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/ssd1306_i2c_new.c"
click node_spi "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/ssd1306_spi.c"
click node_text_demo "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/TextDemo/main/main.c"
click node_font_demo "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/BdfFontDemo/main/main.c"
click node_freetype_demo "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/FreeTypeDemo/main/main.c"
click node_image_demo "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/ImageDemo/main/main.c"
click node_image_motion "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/ImageMoveDemo/main/main.c"
click node_image_rotation "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/ImageRotationDemo/main/main.c"
click node_image_scroll "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/ImageScrollDemo/main/main.c"
click node_animation_demo "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/AnimationDemo/main/main.c"
click node_race_demo "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/CarRaceDemo/main/main.c"
click node_highway_demo "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/HighwayDemo/main/main.c"
click node_encoder_demo "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/RotaryEncoderDemo2/main/main.c"
click node_mouse_demo "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/MouseIconDemo/main/main.c"
click node_scroll_counter "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/ScrollCounterDemo/main/main.c"
click node_basic_font "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/font8x8_basic.h"
click node_bdf_assets "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/BdfFontDemo/main/ncenR12.h"
click node_sprite_assets "https://github.com/chfly2024/esp-idf-ssd1306/blob/master/BdfFontDemo/main/Scroll-o-Sprites.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_text_demo,node_font_demo,node_freetype_demo,node_image_demo,node_image_motion,node_image_rotation,node_image_scroll,node_animation_demo,node_race_demo,node_highway_demo,node_encoder_demo,node_mouse_demo,node_scroll_counter toneBlue
class node_driver_api,node_driver_core toneAmber
class node_i2c_legacy,node_i2c_new,node_spi toneMint
class node_basic_font,node_bdf_assets,node_sprite_assets toneRose
class node_esp,node_oled toneIndigo
```

## Components

### Display demos

- [Text and layout](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/TextDemo/main/main.c): `TextDemo/main/main.c`
- [BDF fonts](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/BdfFontDemo/main/main.c): `BdfFontDemo/main/main.c`
- [FreeType rendering](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/FreeTypeDemo/main/main.c): `FreeTypeDemo/main/main.c`
- [Image drawing](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/ImageDemo/main/main.c): `ImageDemo/main/main.c`
- [Image motion](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/ImageMoveDemo/main/main.c): `ImageMoveDemo/main/main.c`
- [Image rotation](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/ImageRotationDemo/main/main.c): `ImageRotationDemo/main/main.c`
- [Image scrolling](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/ImageScrollDemo/main/main.c): `ImageScrollDemo/main/main.c`
- [Animation](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/AnimationDemo/main/main.c): `AnimationDemo/main/main.c`
- [Game graphics](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/CarRaceDemo/main/main.c): `CarRaceDemo/main/main.c`
- [Highway graphics](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/HighwayDemo/main/main.c): `HighwayDemo/main/main.c`
- [Rotary input demo](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/RotaryEncoderDemo2/main/main.c): `RotaryEncoderDemo2/main/main.c`
- [Mouse interaction](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/MouseIconDemo/main/main.c): `MouseIconDemo/main/main.c`
- [Scrolling counters](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/ScrollCounterDemo/main/main.c): `ScrollCounterDemo/main/main.c`

### Driver core

- [Display API](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/ssd1306.h): `components/ssd1306/ssd1306.h`
- [Drawing and framebuffer](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/ssd1306.c): `components/ssd1306/ssd1306.c`

### Bus transports

- [Legacy I2C](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/ssd1306_i2c_legacy.c): `components/ssd1306/ssd1306_i2c_legacy.c`
- [New I2C](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/ssd1306_i2c_new.c): `components/ssd1306/ssd1306_i2c_new.c`
- [SPI transport](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/ssd1306_spi.c): `components/ssd1306/ssd1306_spi.c`

### Fonts and assets

- [Basic 8x8 font](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/components/ssd1306/font8x8_basic.h): `components/ssd1306/font8x8_basic.h`
- [BDF font assets](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/BdfFontDemo/main/ncenR12.h): `BdfFontDemo/main/ncenR12.h`
- [Sprite assets](https://github.com/chfly2024/esp-idf-ssd1306/blob/master/BdfFontDemo/main/Scroll-o-Sprites.h): `BdfFontDemo/main/Scroll-o-Sprites.h`

### Other components

- **ESP32 firmware**
- **SSD1306 / SH1106**

## Connections

- ESP32 firmware → Text and layout: runs example
- Text and layout → Display API: uses API (evidence: `TextDemo/main/main.c`)
- BDF fonts → Display API: uses API (evidence: `BdfFontDemo/main/main.c`)
- FreeType rendering → Display API: uses API (evidence: `FreeTypeDemo/main/main.c`)
- Image drawing → Display API: uses API (evidence: `ImageDemo/main/main.c`)
- Image motion → Display API: uses API (evidence: `ImageMoveDemo/main/main.c`)
- Image rotation → Display API: uses API (evidence: `ImageRotationDemo/main/main.c`)
- Image scrolling → Display API: uses API (evidence: `ImageScrollDemo/main/main.c`)
- Animation → Display API: uses API (evidence: `AnimationDemo/main/main.c`)
- Game graphics → Display API: uses API (evidence: `CarRaceDemo/main/main.c`)
- Highway graphics → Display API: uses API (evidence: `HighwayDemo/main/main.c`)
- Rotary input demo → Display API: uses API (evidence: `RotaryEncoderDemo2/main/main.c`)
- Mouse interaction → Display API: uses API (evidence: `MouseIconDemo/main/main.c`)
- Scrolling counters → Display API: uses API (evidence: `ScrollCounterDemo/main/main.c`)
- Display API → Drawing and framebuffer: exposes operations (evidence: `components/ssd1306/ssd1306.c`)
- Drawing and framebuffer → Basic 8x8 font: uses font data (evidence: `components/ssd1306/ssd1306.c`)
- Drawing and framebuffer → SSD1306 / SH1106: updates display
- Drawing and framebuffer → Legacy I2C: dispatches I2C
- Drawing and framebuffer → New I2C: dispatches I2C
- Drawing and framebuffer → SPI transport: dispatches SPI
- BDF fonts → BDF font assets: loads font data (evidence: `BdfFontDemo/main/main.c`)
- BDF fonts → Sprite assets: uses sprites (evidence: `BdfFontDemo/main/main.c`)
- Image drawing → Basic 8x8 font: uses font data (evidence: `ImageDemo/main/main.c`)
