### Complete OLED Display UI Example

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplayui.md

This example demonstrates the full setup for an OLED display using OLEDDisplayUi, including initializing the display, defining frames and overlays, and configuring automatic transitions.

```cpp
#include <Wire.h>
#include "SSD1306Wire.h"
#include "OLEDDisplayUi.h"

SSD1306Wire display(0x3c, SDA, SCL);
OLEDDisplayUi ui(&display);

void frame1(OLEDDisplay *display, OLEDDisplayUiState* state, int16_t x, int16_t y) {
  display->setFont(ArialMT_Plain_16);
  display->setTextAlignment(TEXT_ALIGN_CENTER);
  display->drawString(x + 64, y + 32, "Frame 1");
}

void frame2(OLEDDisplay *display, OLEDDisplayUiState* state, int16_t x, int16_t y) {
  display->setFont(ArialMT_Plain_16);
  display->setTextAlignment(TEXT_ALIGN_CENTER);
  display->drawString(x + 64, y + 32, "Frame 2");
}

void overlayStatus(OLEDDisplay *display, OLEDDisplayUiState* state) {
  display->setFont(ArialMT_Plain_10);
  display->setTextAlignment(TEXT_ALIGN_RIGHT);
  display->drawString(128, 0, "OK");
}

void setup() {
  display.init();
  ui.init();
  
  FrameCallback frames[] = { frame1, frame2 };
  ui.setFrames(frames, 2);
  
  OverlayCallback overlays[] = { overlayStatus };
  ui.setOverlays(overlays, 1);
  
  ui.setTimePerFrame(5000);
  ui.setTimePerTransition(300);
  ui.enableAutoTransition();
}

void loop() {
  ui.update();
}

```

--------------------------------

### SH1106Wire Usage Example

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Basic setup and display initialization for the SH1106Wire driver. Ensure Wire.h and SH1106Wire.h are included.

```cpp
#include <Wire.h>
#include "SH1106Wire.h"

SH1106Wire display(0x3c, SDA, SCL);

void setup() {
  display.init();
  display.drawString(0, 0, "SH1106");
  display.display();
}
```

--------------------------------

### Install Library via PlatformIO

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/README.md

Use this command to install the library into a PlatformIO project.

```bash
platformio lib install 2978
```

--------------------------------

### Non-Blocking Loading Process

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/errors.md

Use `ui.runLoadingProcess()` within `setup()` to avoid blocking the main loop. Calling it in `loop()` will freeze the application.

```cpp
// CORRECT: runLoadingProcess() in setup()
void setup() {
  display.init();
  ui.init();
  
  LoadingStage stages[] = {
    { "Connecting WiFi...", connectWiFi },
    { "Loading data...", loadData },
  };
  
  ui.setLoadingDrawFunction(loadingAnimation);
  ui.runLoadingProcess(stages, 2);
  
  // Control continues here after loading complete
}

void loop() {
  // Normal operation
  ui.update();
}

// AVOID: Calling in loop()
void loop() {
  // DON'T DO THIS:
  // ui.runLoadingProcess(stages, 1);  // Blocks loop!
}
```

--------------------------------

### Usage Example for LoadingStage

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/types.md

Demonstrates how to define and use an array of LoadingStage structures to manage a multi-stage loading process.

```cpp
void initWiFi() {
  WiFi.begin("SSID", "password");
  while (WiFi.status() != WL_CONNECTED) {
    delay(100);
  }
}

void initFS() {
  SPIFFS.begin();
}

LoadingStage stages[] = {
  { "Connecting WiFi...", initWiFi },
  { "Mounting Storage...", initFS },
};

void setup() {
  ui.setLoadingDrawFunction(loadingDrawer);
  ui.runLoadingProcess(stages, 2);
  // Boot continues here
}
```

--------------------------------

### OLEDDisplayUi Constructor and Initialization

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/INDEX.md

Initializes the Multi-Frame UI Framework and sets up the display. This is the starting point for using the UI framework.

```APIDOC
## OLEDDisplayUi Constructor and Initialization

### Description
Initializes the Multi-Frame UI Framework and sets up the display. This is the starting point for using the UI framework.

### Method
Constructor and `init()` method

### Endpoint
`api-reference-oleddisplayui.md`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Example: SSD1306Demo - Frame 1

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/README.md

Details and description of the first frame in the SSD1306Demo example, showcasing XBM image, static text, and indicators.

```APIDOC
## Example: SSD1306Demo

### Frame 1

![DemoFrame1](https://github.com/squix78/esp8266-oled-ssd1306/raw/master/resources/DemoFrame1.jpg)

This frame demonstrates:
- How to draw an XBM image.
- How to draw static text that is not affected by frame transitions.
- The active/inactive frame indicators.
```

--------------------------------

### SSD1306Spi Usage Examples

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/configuration.md

Examples of instantiating the SSD1306Spi display driver with different chip select configurations and for ESP32 with custom GPIO pins.

```cpp
// Standard with discrete CS
SSD1306Spi display(D0, D2, D8);  // RES=D0, DC=D2, CS=D8
```

```cpp
// CS hardwired to ground
SSD1306Spi display(D0, D2, -1);
```

```cpp
// ESP32 with custom pins
SSD1306Spi display(GPIO_NUM_4, GPIO_NUM_2, GPIO_NUM_15);
```

--------------------------------

### Example Loading Animation Function

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/types.md

An example implementation of a LoadingDrawFunction to display the current stage's process text and a progress bar.

```cpp
void loadingAnimation(OLEDDisplay *display, LoadingStage* stage, uint8_t progress) {
  display->setFont(ArialMT_Plain_10);
  display->drawString(0, 0, stage->process);
  display->drawProgressBar(10, 20, 100, 10, progress);
}
```

--------------------------------

### Example Overlay Drawing Function

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/types.md

An example implementation of an OverlayCallback function to draw an overlay, such as a clock, on the display.

```cpp
void clockOverlay(OLEDDisplay *display, OLEDDisplayUiState* state) {
  display->setTextAlignment(TEXT_ALIGN_RIGHT);
  display->drawString(128, 0, "12:34");  // No x,y offset
}
```

--------------------------------

### Initialize OLED Display

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplay.md

Initializes the display buffer and hardware. Call this in setup() before any drawing operations. Ensure sufficient memory is available.

```cpp
#include "SSD1306Wire.h"
SSD1306Wire display(0x3c, SDA, SCL);

void setup() {
  if (!display.init()) {
    Serial.println("Display initialization failed");
    return;
  }
  display.clear();
  display.display();
}
```

--------------------------------

### SSD1306Wire Usage Examples

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/configuration.md

Demonstrates various ways to instantiate the SSD1306Wire display object, including standard initialization, custom frequency, skipping I2C initialization, and configuring multiple displays on ESP32.

```cpp
// Standard with auto-detected pins
SSD1306Wire display(0x3c, SDA, SCL);
```

```cpp
// Custom frequency (400 kHz for long wires)
SSD1306Wire display(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, 400000);
```

```cpp
// Skip I2C initialization (manage externally)
SSD1306Wire display(0x3c, -1, -1);
```

```cpp
// ESP32 with two displays on different buses
SSD1306Wire display1(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE);
SSD1306Wire display2(0x3d, 21, 22, GEOMETRY_128_64, I2C_TWO);
```

--------------------------------

### Example Frame Drawing Function

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/types.md

An example implementation of a FrameCallback function to draw content on the display with specified offsets.

```cpp
void myFrame(OLEDDisplay *display, OLEDDisplayUiState* state, int16_t x, int16_t y) {
  display->setFont(ArialMT_Plain_10);
  display->drawString(x, y, "Frame content");
}
```

--------------------------------

### Multi-Frame UI with Auto-Transition

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/README.md

Example of creating a multi-frame user interface with automatic transitions between frames. Set the time per frame and enable auto-transition for a slideshow-like effect.

```cpp
#include "OLEDDisplayUi.h"

SSD1306Wire display(0x3c, SDA, SCL);
OLEDDisplayUi ui(&display);

void frame1(OLEDDisplay *d, OLEDDisplayUiState* s, int16_t x, int16_t y) {
  d->drawString(x, y, "Page 1");
}

void frame2(OLEDDisplay *d, OLEDDisplayUiState* s, int16_t x, int16_t y) {
  d->drawString(x, y, "Page 2");
}

void setup() {
  display.init();
  ui.init();
  
  FrameCallback frames[] = { frame1, frame2 };
  ui.setFrames(frames, 2);
  ui.setTimePerFrame(5000);
  ui.enableAutoTransition();
}

void loop() {
  ui.update();
}
```

--------------------------------

### Initialize Simple I2C Display

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/configuration.md

Basic setup for an I2C OLED display. Ensure the Wire library is included and the display object is initialized with the correct I2C address.

```cpp
#include <Wire.h>
#include "SSD1306Wire.h"

SSD1306Wire display(0x3c, SDA, SCL);

void setup() {
  if (!display.init()) {
    Serial.println("Init failed");
    return;
  }
  
  display.clear();
  display.setFont(ArialMT_Plain_10);
  display.setTextAlignment(TEXT_ALIGN_CENTER);
  display.drawString(64, 32, "Ready");
  display.display();
}
```

--------------------------------

### Initialize File Input Listener

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/resources/glyphEditor.html

Event listener setup for handling file uploads within the editor interface.

```javascript
document.getElementById('fileinput').addEventListener('change', function(e) { let f = e.targ
```

--------------------------------

### Initialize SSD1306 mbed-OS I2C Display

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Example of initializing an SSD1306 display using the SSD1306I2C driver for mbed-OS environments. This driver utilizes the mbed I2C API.

```cpp
#include "SSD1306I2C.h"

// STM32L4 example
SSD1306I2C display(0x3c, I2C_SDA, I2C_SCL);

void setup() {
  display.init();
  display.drawString(0, 0, "mbed-OS");
  display.display();
}
```

--------------------------------

### Initialize I2C Display

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/README.md

Basic setup for an I2C SSD1306 display. Ensure the display is connected correctly and the address (0x3c) is appropriate. Handles initialization failure.

```cpp
#include <Wire.h>
#include "SSD1306Wire.h"

SSD1306Wire display(0x3c, SDA, SCL);  // Address 0x3c, auto-detect pins

void setup() {
  if (!display.init()) {
    // Handle init failure
    return;
  }
  
  display.clear();
  display.setFont(ArialMT_Plain_10);
  display.drawString(0, 0, "Hello World");
  display.display();
}

void loop() {
  // Update display
}
```

--------------------------------

### Check Frame State Example

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/types.md

Demonstrates how to check the current frame state using the `FrameState` enum. Use this to determine if the UI is animating or static.

```cpp
OLEDDisplayUiState* state = ui.getUiState();
if (state->frameState == IN_TRANSITION) {
  Serial.println("Animating...");
} else {
  Serial.println("Static frame");
}
```

--------------------------------

### Initialize SH1106 SPI Display

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Example of initializing an SH1106 display using the SH1106Spi driver over SPI protocol for ESP8266, ESP32, and Arduino platforms.

```cpp
#include <SPI.h>
#include "SH1106Spi.h"

SH1106Spi display(D0, D2, D8);

void setup() {
  display.init();
  display.display();
}
```

--------------------------------

### SSD1306Spi Constructor and Usage

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Instantiates an SSD1306 display using the SPI protocol. Requires Reset, Data/Command, and Chip Select pins. Two examples show standard SPI with a separate CS pin and with CS hardwired to ground. The display is initialized and a string is drawn and shown.

```cpp
SSD1306Spi(uint8_t rst, uint8_t dc, uint8_t cs, 
           OLEDDISPLAY_GEOMETRY g = GEOMETRY_128_64)
```

```cpp
#include <SPI.h>
#include "SSD1306Spi.h"

// Standard SPI with separate CS
SSD1306Spi display(D0, D2, D8);  // RES=D0, DC=D2, CS=D8

// CS hardwired to ground
SSD1306Spi display(D0, D2, -1);

void setup() {
  display.init();
  display.drawString(0, 0, "SPI Fast");
  display.display();
}
```

--------------------------------

### Set Text Alignment Example

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/types.md

Illustrates setting text alignment using OLEDDISPLAY_TEXT_ALIGNMENT. The alignment affects how the text is positioned relative to the given coordinates.

```cpp
display.setTextAlignment(TEXT_ALIGN_LEFT);
display.drawString(0, 0, "Left");    // Starts at (0,0)

display.setTextAlignment(TEXT_ALIGN_RIGHT);
display.drawString(128, 0, "Right"); // Ends at (128,0)

display.setTextAlignment(TEXT_ALIGN_CENTER);
display.drawString(64, 0, "Center"); // Centered at x=64

display.setTextAlignment(TEXT_ALIGN_CENTER_BOTH);
display.drawString(64, 32, "Both");  // Centered at (64,32)
```

--------------------------------

### Set Indicator Direction Example

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/types.md

Shows how to set the indicator direction using the `IndicatorDirection` enum. Options are LEFT_RIGHT (normal) and RIGHT_LEFT (reversed).

```cpp
ui.setIndicatorPosition(BOTTOM);
ui.setIndicatorDirection(LEFT_RIGHT);  // Normal order
// vs
ui.setIndicatorDirection(RIGHT_LEFT);  // Reversed order
```

--------------------------------

### Set Indicator Position Example

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/types.md

Demonstrates how to set the indicator bar position using the `IndicatorPosition` enum. Options include TOP, RIGHT, BOTTOM, and LEFT.

```cpp
ui.setIndicatorPosition(BOTTOM);  // Dots at bottom
ui.setIndicatorPosition(RIGHT);   // Dots on right side
```

--------------------------------

### Initialize High-Speed SPI Display

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/configuration.md

Setup for an SPI OLED display, optimized for high-speed updates. Ensure the SPI library is included and the display object is initialized with the correct pin assignments.

```cpp
#include <SPI.h>
#include "SSD1306Spi.h"

// RES=D0, DC=D2, CS=D8
SSD1306Spi display(D0, D2, D8);

void setup() {
  display.init();
  
  // SPI is very fast, many updates per second
  for (int i = 0; i < 100; i++) {
    display.drawPixel(random(128), random(64));
    display.display();
  }
}
```

--------------------------------

### Initialize SSD1306Wire with Different Geometries

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/types.md

Demonstrates how to initialize SSD1306Wire objects with various display geometries and print their dimensions. Ensure the correct geometry is selected for your display.

```cpp
// 128x64 (standard, default)
SSD1306Wire display1(0x3c, SDA, SCL, GEOMETRY_128_64);

// 128x32 (wide, short)
SSD1306Wire display2(0x3c, SDA, SCL, GEOMETRY_128_32);

// 64x48 (small)
SSD1306Wire display3(0x3c, SDA, SCL, GEOMETRY_64_48);

// 64x32 (very small)
SSD1306Wire display4(0x3c, SDA, SCL, GEOMETRY_64_32);

void setup() {
  display1.init();
  Serial.println(display1.width());   // 128
  Serial.println(display1.height());  // 64
  
  display2.init();
  Serial.println(display2.width());   // 128
  Serial.println(display2.height());  // 32
}
```

--------------------------------

### getHeight()

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplay.md

An alternative, non-const method to get the display height in pixels.

```APIDOC
## getHeight()

### Description
Alternative method to get display height (non-const).

### Returns
`uint16_t` — Display height in pixels.
```

--------------------------------

### init()

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplayui.md

Initializes the UI system. This method must be called after creating the UI object and after the display object has been initialized.

```APIDOC
## init()

### Description
Initializes the UI system. This method must be called after creating the UI object and after the display object has been initialized.

### Signature
```cpp
void init()
```

### Returns
void

### Usage Example
```cpp
display.init();
ui.init();
ui.setTargetFPS(30);
```
```

--------------------------------

### Basic UI Initialization and Timing

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/configuration.md

Initializes the OLED display and the UI, then sets the target frames per second, time per frame, and time per transition for animations.

```cpp
OLEDDisplayUi ui(&display);

void setup() {
  display.init();
  ui.init();
  
  ui.setTargetFPS(30);          // 30 FPS animation
  ui.setTimePerFrame(5000);     // 5 seconds per frame
  ui.setTimePerTransition(300); // 300ms slide animation
}
```

--------------------------------

### getWidth()

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplay.md

An alternative, non-const method to get the display width in pixels.

```APIDOC
## getWidth()

### Description
Alternative method to get display width (non-const).

### Returns
`uint16_t` — Display width in pixels.
```

--------------------------------

### Enable All Frame Indicators

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplayui.md

Enables indicators for all frames. This is typically called once during setup.

```cpp
void enableAllIndicators()

```

```cpp
ui.enableAllIndicators();

```

--------------------------------

### init()

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplay.md

Allocates the pixel buffer, initializes the display hardware, and resets the display to a known state. It internally calls allocateBuffer() and sends initialization commands to the display.

```APIDOC
## init()

### Description
Allocates the pixel buffer, initializes the display hardware, and resets the display to a known state. Calls `allocateBuffer()` internally and sends initialization commands to the display.

### Method
bool

### Parameters
No parameters

### Returns
`bool` — True if initialization succeeded (buffer allocated and hardware ready), false otherwise (typically due to insufficient memory).

### Usage Example
```cpp
#include "SSD1306Wire.h"
SSD1306Wire display(0x3c, SDA, SCL);

void setup() {
  if (!display.init()) {
    Serial.println("Display initialization failed");
    return;
  }
  display.clear();
  display.display();
}
```
```

--------------------------------

### Get Display Height

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplay.md

Retrieves the display height in pixels. Useful for layout calculations.

```cpp
uint16_t h = display.height();  // 64 for 128x64
```

--------------------------------

### Get Display Width

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplay.md

Retrieves the display width in pixels. Useful for layout calculations.

```cpp
uint16_t w = display.width();  // 128 for 128x64
```

--------------------------------

### Initialize Display

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/configuration.md

Initializes the display and allocates necessary buffers. Returns true on success, false if buffer allocation fails.

```cpp
bool init()
```

```cpp
void setup() {
  if (!display.init()) {
    Serial.println("Display init failed");
    return;
  }
}
```

--------------------------------

### Get Current Drawing Color

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplay.md

Retrieves the current global drawing color set for the display.

```cpp
auto currentColor = display.getColor();
```

--------------------------------

### Initialize SSD1306 with Wire.h (64x48)

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/README_GEOMETRY_64_48.md

Use this initialization for the SSD1306 display with 64x48 geometry when using the Wire.h library. Ensure the correct I2C address and pins are specified.

```cpp
#include <Wire.h>
#include <SSD1306Wire.h>
SSD1306Wire display(0x3c, D2, D1, GEOMETRY_64_48 ); // WEMOS OLED shield
```

--------------------------------

### SSD1306Brzo connect() and display() Methods

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Methods for initializing the I2C connection and sending display data using the SSD1306Brzo driver.

```APIDOC
## SSD1306Brzo connect()

```cpp
bool connect()
```

### Description
Initializes the brzo_i2c library.

## SSD1306Brzo display()

```cpp
void display(void)
```

### Description
Sends the pixel buffer using brzo_i2c transactions. Typically faster than Wire.
```

--------------------------------

### Initialize SSD1306 with BRZO i2c (64x48)

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/README_GEOMETRY_64_48.md

This snippet shows how to initialize the SSD1306 display with 64x48 geometry using the BRZO i2c library. Verify the I2C address and pin connections.

```cpp
#include <SSD1306Brzo.h>
SSD1306Brzo display(0x3c, D2, D1, GEOMETRY_64_48 ); // WEMOS OLED Shield
```

--------------------------------

### Get String Width

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplay.md

Calculates the pixel width of a string using the current font. Can optionally interpret text as UTF-8.

```cpp
uint16_t getStringWidth(const char* text, uint16_t length, bool utf8 = false)
uint16_t getStringWidth(const String &text)
```

```cpp
display.setFont(ArialMT_Plain_10);
uint16_t width = display.getStringWidth("Hello");
// Use width to center text: drawString(64 - width/2, 0, "Hello");
```

--------------------------------

### Initialize and Configure UI Library

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/README.md

Initializes the display and configures UI library settings such as target FPS, auto-transition, frame timing, and indicator visibility.

```C++
/**
 * Initialise the display
 */
void init();

/**
 * Configure the internal used target FPS
 */
void setTargetFPS(uint8_t fps);

/**
 * Enable automatic transition to next frame after the some time can be configured with
 * `setTimePerFrame` and `setTimePerTransition`.
 */
void enableAutoTransition();

/**
 * Disable automatic transition to next frame.
 */
void disableAutoTransition();

/**
 * Set the direction if the automatic transitioning
 */
void setAutoTransitionForwards();
void setAutoTransitionBackwards();

/**
 *  Set the approx. time a frame is displayed
 */
void setTimePerFrame(uint16_t time);

/**
 * Set the approx. time a transition will take
 */
void setTimePerTransition(uint16_t time);
```

--------------------------------

### Example Custom Font Table Lookup

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/types.md

Demonstrates a custom FontTableLookupFunction to map specific character ranges to font table indices.

```cpp
char myFontLookup(const uint8_t ch) {
  if (ch >= 'A' && ch <= 'Z') return ch - 'A' + 1;
  if (ch >= '0' && ch <= '9') return ch - '0' + 27;
  return 0;  // Unknown
}

display.setFontTableLookupFunction(myFontLookup);
```

--------------------------------

### Get Most Significant Byte (MSB) as Hex

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/resources/glyphEditor.html

Extracts the most significant byte (MSB) from an integer and returns it as a hexadecimal string, prefixed with '0x'.

```javascript
static getMsB(anInt) {
  return Font.toHexString(anInt>>>8);
}
```

--------------------------------

### SSD1306Spi connect() and display() Methods

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Methods for initializing the SPI connection and sending display data using the SSD1306Spi driver.

```APIDOC
## SSD1306Spi connect()

```cpp
bool connect()
```

### Description
Initializes GPIO pins and SPI bus, performs reset sequence (RES pulse).

### Sequence:
1. Set RES/DC/CS as outputs
2. Call SPI.begin() and SPI.setClockDivider(SPI_CLOCK_DIV2)
3. Pulse RES high -> low (1ms) -> high (10ms)

### Returns:
`bool` — True after reset completes

## SSD1306Spi display()

```cpp
void display(void)
```

### Description
Sends the pixel buffer via SPI. Uses double-buffering to send only changed regions.

### Characteristics:
- Very fast (SPI speeds ~40 MHz possible)
- Requires 3+ pins vs. 2 for I2C
- No bus arbitration (fully controlled)
```

--------------------------------

### Initializing SSD1306 Displays with Different Geometries

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Demonstrates initializing SSD1306 displays with various predefined geometries like 128x32, 64x48, and 64x32.

```cpp
// 128x32 small display
SSD1306Wire display_small(0x3c, SDA, SCL, GEOMETRY_128_32);

// 64x48 tiny display
SSD1306Wire display_tiny(0x3c, SDA, SCL, GEOMETRY_64_48);

// 64x32 minimal
SSD1306Wire display_mini(0x3c, SDA, SCL, GEOMETRY_64_32);
```

--------------------------------

### Creating and Using XBM Bitmaps

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/README.md

Instructions on how to convert images into XBM format for display on the OLED screen using the library.

```APIDOC
## Creating and using XBM bitmaps

### Description
This section explains how to convert images into a compatible XBM bitmap format for display with the library.

### Conversion Methods

1.  **Using Gimp:**
    Export the image in a 1-bit XBM format.

2.  **Using a converter website (e.g., https://javl.github.io/image2cpp/):**
    - Upload the image.
    - Ensure the image dimensions match the screen (e.g., 128x64).
    - Set Draw Mode to "Horizontal - 1 bit per pixel".
    - Check the "Swap bits in byte" option.

### Usage

1.  **Store the bitmap in a header file:**
    ```C++
    const unsigned char epd_example [] PROGMEM = {
        0x00, 0x00, 0x00, 0x00, 0x00, 0x00, ... 
    };
    ```

2.  **Draw the bitmap using `display.drawXbm()`:**
    ```C++
    display.clear();
    display.drawXbm(0, 0, 128, 64, epd_example); // Assuming a 128x64 bitmap
    display.display();
    ```
```

--------------------------------

### connect()

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Initializes the I2C bus and sets the clock frequency if not -1. Returns true on success.

```APIDOC
## connect()

### Description
Initializes the I2C bus and sets the clock frequency if not -1. On ESP8266/ESP32, it calls `Wire.begin(sda, scl)` if sda is not -1. It also sets the I2C frequency if the provided frequency is not -1.

### Method
```cpp
bool connect()
```

### Parameters
None

### Returns
`bool` — True if I2C initialization succeeded
```

--------------------------------

### Draw Vertical Line on OLED Display

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplay.md

Optimized function for drawing vertical lines. Specify the X-coordinate, starting Y-coordinate, and the desired length.

```cpp
void drawVerticalLine(int16_t x, int16_t y, int16_t length)
```

```cpp
display.drawVerticalLine(10, 20, 50);
```

--------------------------------

### Draw Horizontal Line on OLED Display

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplay.md

Optimized function for drawing horizontal lines. Specify the starting X-coordinate, Y-coordinate, and the desired length.

```cpp
void drawHorizontalLine(int16_t x, int16_t y, int16_t length)
```

```cpp
display.drawHorizontalLine(10, 20, 50);
```

--------------------------------

### Handle OLED Display Initialization Failure

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/errors.md

Check if display.init() returns false, indicating potential heap memory issues. Provides fallback options and restarts the ESP if initialization fails.

```cpp
void setup() {
  Serial.begin(115200);
  
  // Check available memory first (ESP8266/ESP32)
  #ifdef ESP8266
  Serial.print("Free heap: ");
  Serial.println(ESP.getFreeHeap());
  #endif
  
  if (!display.init()) {
    Serial.println("FATAL: Display initialization failed!");
    Serial.println("Possible causes:");
    Serial.println("1. Insufficient heap memory");
    Serial.println("2. Heap fragmentation");
    Serial.println("3. Other libraries consuming RAM");
    
    // Fallback options:
    // Option A: Reduce geometry
    // display.geometry = GEOMETRY_64_32;  // Not a real method, demo
    
    // Option B: Reduce other allocations (disable WiFi, SPIFFS, etc)
    
    // Option C: Restart
    ESP.restart();
    return;
  }
  
  display.drawString(0, 0, "Init OK");
  display.display();
}
```

--------------------------------

### Check Free Heap Before and After Display Initialization

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/errors.md

Check the available heap memory before and after initializing the display. If initialization fails and heap is low, consider disabling features like WiFi or SPIFFS.

```cpp
void setup() {
  #ifdef ESP8266
  Serial.println(ESP.getFreeHeap());  // Check before display
  #endif
  
  // Initialize display early
  if (!display.init()) {
    #ifdef ESP8266
    Serial.println(ESP.getFreeHeap());  // Check after failed init
    #endif
    
    // If init fails and heap is low, try disabling features
    // WiFi.off() or SPIFFS.end() then retry
    return;
  }
}
```

--------------------------------

### SSD1306Wire Constructor Overloads

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Creates an SSD1306 display instance using the Wire (I2C) library. Supports various configurations for I2C address, pins, geometry, I2C bus, and frequency. Use -1 for SDA/SCL to skip Wire.begin.

```cpp
#include <Wire.h>
#include "SSD1306Wire.h"

// Standard initialization (SDA/SCL auto-detected)
SSD1306Wire display(0x3c, SDA, SCL);

// 128x32 display
SSD1306Wire display(0x3c, SDA, SCL, GEOMETRY_128_32);

// Custom frequency
SSD1306Wire display(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, 400000);

// Skip Wire.begin (external I2C management)
SSD1306Wire display(0x3c, -1, -1);

void setup() {
  display.init();
  display.drawString(0, 0, "Hello");
  display.display();
}
```

--------------------------------

### Get Least Significant Byte (LSB) as Hex

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/resources/glyphEditor.html

Extracts the least significant byte (LSB) from an integer and returns it as a hexadecimal string, prefixed with '0x'.

```javascript
static getLsB(anInt) {
  return Font.toHexString(anInt & 0xFF);
}
```

--------------------------------

### Set Display Color Example

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/types.md

Demonstrates how to set the drawing color using the OLEDDISPLAY_COLOR enum. The color affects subsequent drawing operations like lines.

```cpp
display.setColor(WHITE);
display.drawLine(0, 0, 10, 10);  // White line

display.setColor(BLACK);
display.drawLine(0, 0, 10, 10);  // Erase (black line)

display.setColor(INVERSE);
display.drawLine(0, 0, 10, 10);  // Toggle pixels (inverse)
```

--------------------------------

### Hardware Abstraction - I2C with Wire.h

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/README.md

Includes for the SSD1306 and SH1106 libraries using the standard Wire.h library for I2C communication. Demonstrates initialization with different display geometries and I2C frequencies.

```APIDOC
## I2C with Wire.h

```C++
#include <Wire.h>
#include "SSD1306Wire.h"

// for 128x64 displays:
SSD1306Wire display(0x3c, SDA, SCL);  // ADDRESS, SDA, SCL
// for 128x32 displays:
// SSD1306Wire display(0x3c, SDA, SCL, GEOMETRY_128_32);  // ADDRESS, SDA, SCL, GEOMETRY_128_32 (or 128_64)
// for using 2nd Hardware I2C (if available)
// SSD1306Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_TWO); //default value is I2C_ONE if not mentioned
// By default SD1306Wire set I2C frequency to 700000, you can use set either another frequency or skip setting the frequency by providing -1 value
// SSD1306Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, 400000); //set I2C frequency to 400kHz
// SSD1306Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, -1); //skip setting the I2C bus frequency
```

for a SH1106:
```C++
#include <Wire.h>
#include "SH1106Wire.h"

SH1106Wire display(0x3c, SDA, SCL);  // ADDRESS, SDA, SCL
// By default SH1106Wire set I2C frequency to 700000, you can use set either another frequency or skip setting the frequency by providing -1 value
// SH1106Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, 400000); //set I2C frequency to 400kHz
// SH1106Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, -1); //skip setting the I2C bus frequency
```
```

--------------------------------

### I2C Display Initialization and Usage

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Initializes an SSD1306 display using the I2C interface and displays "Ready". Requires Wire library.

```cpp
#include <Wire.h>
#include "SSD1306Wire.h"

SSD1306Wire display(0x3c, SDA, SCL);

void setup() {
  if (!display.init()) {
    Serial.println("Init failed");
    return;
  }
  display.drawString(0, 0, "Ready");
  display.display();
}
```

--------------------------------

### Turn Display On

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplay.md

Turns the physical display on, making the buffered content visible. This is used to re-enable the display after it has been turned off.

```cpp
display.displayOn();
```

--------------------------------

### SSD1306Brzo Constructor

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/configuration.md

Initializes the SSD1306 display using the brzo_i2c optimized I2C library (ESP8266 only). Requires I2C address, SDA, SCL pins, and display geometry.

```APIDOC
## SSD1306Brzo Constructor

### Description
Initializes the SSD1306 display using the brzo_i2c optimized I2C library (ESP8266 only). Requires I2C address, SDA, SCL pins, and display geometry.

### Parameters
#### Path Parameters
- **address** (uint8_t) - Required - I2C address (typically 0x3C)
- **sda** (uint8_t) - Required - SDA pin number
- **scl** (uint8_t) - Required - SCL pin number
- **g** (OLEDDISPLAY_GEOMETRY) - Optional - Display geometry, Default: GEOMETRY_128_64

### Key Differences from SSD1306Wire
- Requires `brzo_i2c` library separately
- Pins are uint8_t (not int)
- Speed: 1000 kHz (160 MHz ESP8266), 800 kHz (80 MHz)
- Frequency not configurable (optimized by hardware speed)
```

--------------------------------

### SSD1306Brzo Constructor and Usage

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Instantiates an SSD1306 display using the brzo_i2c library. Requires the I2C address, SDA, and SCL pins. The display is initialized and a string is drawn and shown.

```cpp
SSD1306Brzo(uint8_t address, uint8_t sda, uint8_t scl, 
            OLEDDISPLAY_GEOMETRY g = GEOMETRY_128_64)
```

```cpp
#include <brzo_i2c.h>
#include "SSD1306Brzo.h"

SSD1306Brzo display(0x3c, D3, D5);  // SDA=D3, SCL=D5

void setup() {
  display.init();
  display.drawString(0, 0, "Fast I2C");
  display.display();
}
```

--------------------------------

### Get UI State Pointer

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplayui.md

Retrieve a pointer to the current UI state structure. This allows you to inspect or modify properties like the current frame, timing, and custom user data.

```cpp
OLEDDisplayUiState* state = ui.getUiState();
Serial.print("Current frame: ");
Serial.println(state->currentFrame);

// Store custom data
state->userData = (void*)myData;
```

--------------------------------

### SH1106Wire setI2cAutoInit() Method

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Configures whether the I2C bus should be automatically initialized by the driver. This function behaves identically to the one in the SSD1306Wire class.

```cpp
void setI2cAutoInit(bool doI2cAutoInit)
```

--------------------------------

### SSD1306 I2C Initialization with brzo_i2c

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/README.md

Initialize an SSD1306 display using the faster brzo_i2c library for I2C communication.

```C++
#include <brzo_i2c.h>
#include "SSD1306Brzo.h"

SSD1306Brzo display(0x3c, SDA, SCL);  // ADDRESS, SDA, SCL
```

--------------------------------

### Get UI State and Update Display

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/README.md

Retrieves the current state of the UI and updates the display. The `update()` function must be called in the main loop and returns the remaining time for drawing.

```C++
// State Info
OLEDDisplayUiState* getUiState();

// This needs to be called in the main loop
// the returned value is the remaining time (in ms)
// you have to draw after drawing to keep the frame budget.
int8_t update();
```

--------------------------------

### Initialize OLEDDisplayUi and Set Target FPS

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplayui.md

Initializes the UI system and sets the target frames per second. Must be called after creating the UI object and after display.init().

```cpp
#include "SSD1306Wire.h"
#include "OLEDDisplayUi.h"

SSD1306Wire display(0x3c, SDA, SCL);
OLEDDisplayUi ui(&display);

void setup() {
  display.init();
  ui.init();
  ui.setTargetFPS(30);
}
```

--------------------------------

### Prevent Initialization Failures by Initializing Early

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/errors.md

Initialize the OLED display before other memory-intensive allocations like WiFi or SPIFFS to prevent heap fragmentation and ensure successful initialization.

```cpp
// For ESP8266/ESP32, initialize display early before other allocations
void setup() {
  // Initialize display FIRST
  if (!display.init()) {
    // Handle failure
    return;
  }
  
  // Then initialize WiFi, SPIFFS, etc.
  WiFi.begin("SSID", "password");
}
```

--------------------------------

### SSD1306Wire Constructor

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/configuration.md

Initializes the SSD1306 display using the Wire (I2C) library. Allows configuration of I2C address, pins, geometry, I2C bus, and frequency.

```APIDOC
## SSD1306Wire Constructor

### Description
Initializes the SSD1306 display using the Wire (I2C) library. Allows configuration of I2C address, pins, geometry, I2C bus, and frequency.

### Parameters
#### Path Parameters
- **address** (uint8_t) - Required - I2C slave address (typically 0x3C)
- **sda** (int) - Optional - SDA pin (-1 skips Wire.begin), Default: -1
- **scl** (int) - Optional - SCL pin (-1 skips Wire.begin), Default: -1
- **g** (OLEDDISPLAY_GEOMETRY) - Optional - Display size, Default: GEOMETRY_128_64
- **i2cBus** (HW_I2C) - Optional - I2C bus (ESP32 only), Default: I2C_ONE
- **frequency** (long) - Optional - I2C frequency Hz (-1 to skip), Default: 700000

### Usage Examples
```cpp
// Standard with auto-detected pins
SSD1306Wire display(0x3c, SDA, SCL);

// Custom frequency (400 kHz for long wires)
SSD1306Wire display(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, 400000);

// Skip I2C initialization (manage externally)
SSD1306Wire display(0x3c, -1, -1);

// ESP32 with two displays on different buses
SSD1306Wire display1(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE);
SSD1306Wire display2(0x3d, 21, 22, GEOMETRY_128_64, I2C_TWO);
```
```

--------------------------------

### SH1106Wire Constructor

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/configuration.md

Initializes the SH1106 display using the Wire (I2C) library. Parameters are identical to SSD1306Wire, but it's used for SH1106 displays due to a different internal addressing scheme.

```APIDOC
## SH1106Wire Constructor

### Description
Initializes the SH1106 display using the Wire (I2C) library. Parameters are identical to SSD1306Wire, but it's used for SH1106 displays due to a different internal addressing scheme.

### Parameters
#### Path Parameters
- **address** (uint8_t) - Required - I2C slave address (typically 0x3C)
- **sda** (int) - Optional - SDA pin (-1 skips Wire.begin), Default: -1
- **scl** (int) - Optional - SCL pin (-1 skips Wire.begin), Default: -1
- **g** (OLEDDISPLAY_GEOMETRY) - Optional - Display size, Default: GEOMETRY_128_64
- **i2cBus** (HW_I2C) - Optional - I2C bus (ESP32 only), Default: I2C_ONE
- **frequency** (long) - Optional - I2C frequency Hz (-1 to skip), Default: 700000

### Key Difference
- Different internal page addressing scheme (SH1106 vs SSD1306).
```

--------------------------------

### SSD1306I2C connect()

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Establishes the I2C connection for the SSD1306I2C driver, setting the frequency based on the platform.

```APIDOC
## connect()

### Description
Creates the mbed I2C object and sets the I2C frequency. The frequency is 1000 kHz for STM32L4 and 400 kHz for other platforms.

### Signature
```cpp
bool connect()
```

### Returns
- **bool** - True if the I2C creation succeeded.
```

--------------------------------

### OLEDDisplayUi Constructor

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-oleddisplayui.md

Creates a UI manager for the specified display. Requires an initialized display object.

```cpp
OLEDDisplayUi(OLEDDisplay *display)
```

--------------------------------

### setI2cAutoInit()

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Enables automatic I2C initialization before each display() call. Useful when multiple I2C devices share the bus.

```APIDOC
## setI2cAutoInit()

### Description
Enables or disables automatic I2C initialization before each `display()` call. This is particularly useful when multiple I2C devices share the same bus, ensuring the bus is correctly initialized before each display update.

### Method
```void
setI2cAutoInit(bool doI2cAutoInit)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **doI2cAutoInit** (bool) - Required - True to auto-initialize I2C before `display()`, false to rely on external initialization.

### Usage Example
```cpp
display.setI2cAutoInit(true);
// Now each display() call re-initializes I2C
```
```

--------------------------------

### SSD1306Spi Constructor and Usage

Source: https://github.com/thingpulse/esp8266-oled-ssd1306/blob/master/_autodocs/api-reference-display-drivers.md

Initializes an SSD1306 display using the SPI protocol. It requires the Reset, Data/Command, and Chip Select pins.

```APIDOC
## SSD1306Spi Constructor

```cpp
SSD1306Spi(uint8_t rst, uint8_t dc, uint8_t cs, 
           OLEDDISPLAY_GEOMETRY g = GEOMETRY_128_64)
```

### Description
Creates an SSD1306 SPI display.

### Parameters
#### Path Parameters
- **rst** (uint8_t) - Required - Reset pin (RES)
- **dc** (uint8_t) - Required - Data/Command pin (DC)
- **cs** (uint8_t) - Required - Chip Select pin (CS), or -1 if hardwired low
#### Query Parameters
- **g** (OLEDDISPLAY_GEOMETRY) - Optional - Display geometry (default: GEOMETRY_128_64)

### Pin Requirements:
- RES (Reset): digital output, pulses low 10ms at initialization
- DC (Data/Command): digital output, high for data, low for commands
- CS (Chip Select): digital output, or -1 if not used
- MOSI, SCK: SPI bus (set via SPI.begin())

### Usage Example:
```cpp
#include <SPI.h>
#include "SSD1306Spi.h"

// Standard SPI with separate CS
SSD1306Spi display(D0, D2, D8);  // RES=D0, DC=D2, CS=D8

// CS hardwired to ground
SSD1306Spi display(D0, D2, -1);

void setup() {
  display.init();
  display.drawString(0, 0, "SPI Fast");
  display.display();
}
```
```