https://github.com/styropyr0/ssd1306_rp2350
https://github.com/styropyr0/ssd1306_rp2350
Last synced: 11 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/styropyr0/ssd1306_rp2350
- Owner: styropyr0
- License: mit
- Created: 2025-08-15T21:18:59.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-08-15T21:56:36.000Z (11 months ago)
- Last Synced: 2025-08-15T23:38:32.534Z (11 months ago)
- Language: C++
- Size: 24.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
- License: LICENSE
Awesome Lists containing this project
README
# SSD1306 OLED Display Driver for Raspberry Pi Microcontrollers
**(Works with Clang/LLVM and ARM Embedded Toolchain)**
A lightweight, fast driver library to control SSD1306-based OLED displays with Raspberry Pi, using C++ and standard Linux I2C APIs. This library offers versatile features comparable to the Arduino version, but does **not** include advanced scene-management (Fragments) or Drawable objects. Use direct method calls for all graphics, text, and data plotting.
This driver is based on the [SSD1306 OLED Display Driver for Arduino](https://github.com/styropyr0/oled.h)
| Power Mode | Frame Rate (fps) |
|--------------------|------------------------|
| Low Power Mode | ≤5 |
| Balanced Mode | 8–10 |
| Performance Mode | 16–19 |
| Turbo Mode | 40–43 |
***
### Key Features
- **Text Output**: Print static and animated text in various fonts and highlight styles.
- **Custom Fonts Support**: Render text using custom font arrays; switch between multiple font styles.
- **Progress Bars**: Visual progress/status bars, multiple styles.
- **Bitmap Rendering**: Draw icons or full images from arrays (converted using the companion Python tool).
- **Geometric Primitives**: Draw rectangles (with optional rounded corners), circles, lines.
- **Display Inversion**: Invert entire display or pixel states for different visual styles.
- **Brightness & Power Management**: Software brightness control, I2C speed modes for power optimization.
- **I2C Communication**: Direct communication with SSD1306 via `/dev/i2c-X`. Default address: `0x3C` (changeable).
- **Data Visualization**: Static plots—pulse/waveform, bar, scatter, histogram, bit plots—for real-time sensor and analytics display.
- **Python Bitmap Generator**: Tool to convert images (PNG/JPG) to C array bitmaps for easy display integration.
***
### Installation / Building
**1. Clone the Repository**
```bash
git clone https://github.com/styropyr0/oled.h.git
cd oled.h
```
**2. Build (CMake + Ninja)**
```bash
mkdir build
cd build
cmake -G "Ninja" ..
ninja
```
**3. Dependencies**
- Standard C++17+
- Linux I2C headers (e.g., ``)
- CMake (≥3.10) and Ninja build system
***
### Hardware & Connection
- **Display**: SSD1306 OLED (128x64 or 128x32), I2C interface.
- **Board**: Raspberry Pi (any model; tests on Pi 3/4/5).
- **I2C Bus**: Typically `/dev/i2c-1`
- SDA/SCL pins: Default Pi bus pins (see Pi docs).
**Check your hardware address using:**
```bash
i2cdetect -y 1
```
***
### C++ Library Usage
#### 1. Basic Initialization
```cpp
#include "SSD1306.h"
int main() {
SSD1306 oled(128, 64); // width, height, address, bus
oled.begin(); // Initialize hardware
oled.clearScr(); // Clear display buffer
oled.print("Hello, Raspberry Pi!", 0, 0); // Text at (0,0)
oled.inflate(); // Render changes to screen
}
```
#### 2. Print Highlighted/Animated Text
```cpp
oled.printHighlighted("Warning!", 0, 0);
oled.printAnimated("Loading...", 10, 20, 40 /* ms delay */, true /* highlight */);
```
#### 3. Progress Bar Example
```cpp
oled.progressBar(75, 10, 40, 2); // 75% at (10,40), style 2
```
#### 4. Bitmap Rendering
- Convert your image:
```bash
python bitmap_generator.py logo.png logo.h 24x24
```
- In C++:
```cpp
#include "logo.h" // bitmap array generated by script
oled.draw(logo_bitmap, 30, 20, 24, 24);
```
#### 5. Shapes
```cpp
oled.rectangle(5, 5, 40, 20, 3, 1, false); // Rectangle w/rounded corners
oled.circle(75, 32, 12, 2); // Circle center (75,32), radius 12
oled.line(0, 0, 127, 63, 1); // Line across screen
```
#### 6. Display Inversion & Power Modes
```cpp
oled.invertDisplay(); // Invert colors
oled.setBrightness(80); // 80% brightness
oled.setPowerMode(PERFORMANCE_MODE); // Fastest I2C speed
```
***
### Data Visualization (Plots)
Plots data arrays for instant graphics:
```cpp
int signal[] = {2, 4, 3, 1, 0, 2, 5, 3};
oled.pulsePlot(0,0,128,32, signal, 8, 5);
// More plots:
oled.barPlot(0,34,128,16, signal, 8, 5);
oled.scatterPlot(0,52,128,12, signal, 8, 5, 2);
int histogramData[] = {2,4,1,3,5};
oled.histogramPlot(0,60,128,16, histogramData, 5, 5);
```
***
### API Reference (Selected Methods)
| Method | Description |
|------------------------------|----------------------------------------------|
| `SSD1306(uint8_t w, h)` | Constructor: width, height |
| `begin()` | Initialize hardware & display |
| `clearScr()` | Clear display RAM |
| `inflate()` | Push buffer to the OLED screen |
| `print(text, x, y)` | Draw text at position |
| `printHighlighted(text,x,y)` | Highlighted text at [x,y] |
| `printAnimated(text,x,y,delay,highlight)` | Typewriter effect |
| `setFont(fontArray)` | Use a custom font |
| `clearCustomFont()` | Reset to default font |
| `progressBar(pct,x,y,style)` | Render progress bar |
| `draw(data,x,y,w,h)` | Draw a bitmap array |
| `rectangle(x,y,w,h,radius,thickness,fill)` | Rectangle |
| `circle(cx,cy,radius,thickness)` | Circle |
| `line(x0,y0,x1,y1,thickness)`| Line |
| `setBrightness(value)` | LED brightness 0–100 |
| `setPowerMode(mode)` | I2C speed |
| `invertDisplay()` | Invert all pixels |
| `scatterPlot(...)` | Render scatter plot |
| `barPlot(...)` | Render bar plot |
| `pulsePlot(...)` | Render pulse waveform |
| `histogramPlot(...)` | Histogram |
***
### Constants Quick Reference
| Constant | Value | Description |
|-------------------|--------|--------------------------------------------|
| `ADDR` | 0x3C | Default I2C address |
| `WIDTH_128` | 128 | 128 px width |
| `HEIGHT_64` | 64 | 64 px height |
| `LOW_POWER_MODE` | 0x01 | 100kHz I2C |
| `BALANCED_MODE` | 0x02 | 200kHz I2C |
| `PERFORMANCE_MODE`| 0x03 | 400kHz I2C |
| `TURBO_MODE` | 0x04 | 1MHz I2C (auto fallback) |
***
### Bitmap Generator Tool (Python)
Convert PNG/JPG to C arrays for direct rendering on the OLED display.
```bash
python bitmap_generator.py "logo.png" logo.h 32x32
# Output: logo.h — contains logo_bitmap[] array
```
Include the `.h` file in your project and use `oled.draw` to render.
***
### Usage Pattern Comparison
| Capability | Arduino/ESP32 Version | Raspberry Pi Version (C++) |
|-----------------------------|-----------------------------------|-----------------------------------|
| Fragments/Drawables | Scene batching, reusable UI | NOT INCLUDED |
| Direct Methods | Available | Available |
| Bitmaps, Fonts, Plots | Yes | Yes |
| Build/Deploy | Arduino IDE | CMake + Ninja |
| I2C | Wire library | Linux i2c-dev (C++ binding) |
***
### Example: Full Demo Program
```cpp
#include "SSD1306.h"
#include "logo.h" // Generated by bitmap_generator.py
int main() {
SSD1306 oled(128, 64, 0x3C, "/dev/i2c-1");
oled.begin();
oled.clearScr();
oled.print("Raspberry Pi OLED!", 0, 0);
oled.progressBar(80, 5, 20, 2);
oled.rectangle(10, 30, 50, 20, 2, 1, false);
oled.draw(logo_bitmap, 70, 32, 24, 24);
int data[] = {3, 5, 2, 4, 1};
oled.barPlot(0, 54, 128, 10, data, 5, 5);
oled.setBrightness(100);
oled.inflate();
}
```
***
## Conclusion
This C++ library for SSD1306 displays on Raspberry Pi gives you robust text, graphics, and data plotting—ideal for sensor dashboards, status screens, or mini GUIs. Build, run, and update displays using standard Linux tools and C++. All methods are streamlined for direct calls - no scene batching, but everything else is there for rich, flexible UI.