Overview
The oled_ssd1306 node drives SSD1306-based OLED displays via I2C for rendering
text, graphics, charts, and icons. Unlike character LCDs, the SSD1306 is a pixel-addressable display capable of
rendering custom fonts, shapes, and images. These compact, high-contrast OLED panels are widely used in embedded
systems, wearables, and IoT dashboards.
Properties
| Property | Type | Default | Options | Description |
|---|---|---|---|---|
| i2cBus | select | "/dev/i2c-1" | /dev/i2c-0, /dev/i2c-1 | I2C bus device path |
| address | select | "0x3c" | 0x3c, 0x3d | I2C device address |
| width | select | "128" | 128, 64 | Display width in pixels |
| height | select | "64" | 32, 64 | Display height in pixels |
| rotation | select | "0" | 0, 90, 180, 270 | Display rotation in degrees |
| contrast | number | 255 | 0-255 | Display contrast/brightness level |
| externalVcc | boolean | false | - | Set true if display uses external VCC supply |
Input
// Simple text
msg.payload = "Hello OLED!";
// Structured content
msg.payload = {
"text": "Temperature",
"value": "23.5C",
"x": 0,
"y": 0,
"fontSize": 16,
"clear": true
};
// Draw commands
msg.payload = {
"commands": [
{ "type": "clear" },
{ "type": "text", "x": 0, "y": 0,
"content": "EdgeFlow", "size": 2 },
{ "type": "line", "x0": 0, "y0": 20,
"x1": 127, "y1": 20 },
{ "type": "text", "x": 0, "y": 28,
"content": "CPU: 45C", "size": 1 },
{ "type": "display" }
]
};Output
{
"payload": true,
"topic": "oled/status",
"_oled": {
"address": "0x3c",
"width": 128,
"height": 64,
"rotation": 0,
"contrast": 255
}
}Wiring / Connection Diagram
Raspberry Pi SSD1306 OLED
+-----------+ +-------------+
| | | |
| 3.3V (1) +------------+ VCC |
| | | |
| SDA (3) +------------+ SDA |
| | | |
| SCL (5) +------------+ SCL |
| | | |
| GND (6) +------------+ GND |
| | | |
+-----------+ +------+------+
| +---------+ |
| | 128x64 | |
| | OLED | |
| | display | |
| +---------+ |
+-------------+
Common module variants:
- 0.96" 128x64 (most common)
- 0.91" 128x32 (compact)
- Available in white, blue, or yellow/blue
Note: Some SSD1306 modules have a fixed address resistor. If you need two OLEDs on the same I2C bus, ensure one is set to 0x3C and the other to 0x3D by modifying the address resistor on the PCB.
Example Use Cases
Mini Sensor Dashboard
Display multiple sensor readings with labels on a 128x64 OLED.
// Function node: build OLED dashboard layout
var temp = msg.payload.temperature.toFixed(1);
var humid = msg.payload.humidity.toFixed(0);
var press = msg.payload.pressure.toFixed(0);
msg.payload = {
"commands": [
{ "type": "clear" },
{ "type": "text", "x": 0, "y": 0,
"content": "EdgeFlow Sensor", "size": 1 },
{ "type": "line", "x0": 0, "y0": 12,
"x1": 127, "y1": 12 },
{ "type": "text", "x": 0, "y": 18,
"content": "Temp: " + temp + " C", "size": 1 },
{ "type": "text", "x": 0, "y": 32,
"content": "Humid: " + humid + " %", "size": 1 },
{ "type": "text", "x": 0, "y": 46,
"content": "Press: " + press + " hPa", "size": 1 },
{ "type": "display" }
]
};
return msg;Network Status Display
Show Wi-Fi connection status, IP address, and signal strength on the OLED.
// Function node: format network info for OLED
var net = msg.payload;
msg.payload = {
"commands": [
{ "type": "clear" },
{ "type": "text", "x": 0, "y": 0,
"content": "WiFi: " + (net.connected ? "OK" : "--"),
"size": 1 },
{ "type": "text", "x": 0, "y": 16,
"content": net.ssid || "Not Connected",
"size": 1 },
{ "type": "text", "x": 0, "y": 32,
"content": "IP: " + (net.ip || "N/A"),
"size": 1 },
{ "type": "text", "x": 0, "y": 48,
"content": "RSSI: " + (net.rssi || "--") + " dBm",
"size": 1 },
{ "type": "display" }
]
};
return msg;Progress Bar with Percentage
Draw a graphical progress bar showing task completion.
// Function node: draw progress bar on OLED
var percent = msg.payload; // 0-100
var barWidth = Math.round((percent / 100) * 120);
msg.payload = {
"commands": [
{ "type": "clear" },
{ "type": "text", "x": 20, "y": 5,
"content": "Progress", "size": 2 },
{ "type": "rect", "x": 4, "y": 30,
"w": 120, "h": 16, "fill": false },
{ "type": "rect", "x": 4, "y": 30,
"w": barWidth, "h": 16, "fill": true },
{ "type": "text", "x": 45, "y": 52,
"content": percent + "%", "size": 1 },
{ "type": "display" }
]
};
return msg;Common Use Cases
Real-Time Graphs
Draw live line graphs and bar charts for sensor data visualization
Compact Dashboards
Multi-value status screens with icons and formatted layouts
Custom Icons and Bitmaps
Display logos, icons, and pixel art using bitmap rendering
3D Printer Displays
Progress bars, temperature readouts, and status indicators for printers