OLED Display (SSD1306)

> [!NOTE] > Real HD44780/PCF8574/MAX7219/ST7735 hardware also ships in SH1106 (a very similar OLED controller) variants — OMS's simulated component and code generator target SSD1306 specifically.

Displays15 blocksMicroPythonC++
OLED Display

At a glance

Pins and properties exactly as the circuit editor and simulator define this part. The text below explains how to use them.

Pinout

Pinout of the OLED Display, drawn as in the circuit editor. Select a label to see that pin in the table below.

Properties

What you can change in the Property Inspector.

Properties of this part
PropertyRange or choicesDefault
I2C Address0x3C, 0x3D0x3C

1. Overview

The SSD1306 OLED is the smallest and most common display in this chapter — a 0.96" monochrome panel that needs only 4 wires (power + I2C). It's also the only display in this entire chapter with genuine, pixel-accurate bus simulation — see Section 6 below.

[!NOTE] Real HD44780/PCF8574/MAX7219/ST7735 hardware also ships in SH1106 (a very similar OLED controller) variants — OMS's simulated component and code generator target SSD1306 specifically.


2. Pinout

Verified against simulator/components/oled.ts (4-pin header):

Pins of this part
PinLabelTypeNotes
GNDGNDGroundGround
VCCVCCPower in+3.3V/5V supply
SCLSCLI2CI2C clock
SDASDAI2CI2C data

3. Key Specifications

SpecValue
ControllerSSD1306
Resolution128 × 64 px
ColorMonochrome (1-bit)
InterfaceI2C
Default address0x3C — 0x3D also supported

4. Libraries Used

  • C++ (Arduino): Adafruit_GFX + Adafruit_SSD1306.
  • MicroPython: no external import — OMS's code generator writes a complete, self-contained SSD1306_I2C driver class directly into your generated code (a compact reimplementation of the standard ssd1306.py driver's API: fill, pixel, text, line, rect/fill_rect, blit, contrast, invert, poweron/poweroff, show).

5. Component Properties

From the real props: [...]:

  • i2cAddress (select) — 0x3C (default) or 0x3D.

Powered detection works differently here than every other display in this chapter: instead of a simple voltage threshold, OMS places a real current-sense element on VCC and considers the module powered once sensed current exceeds 5mA — closer to how a real bench multimeter would confirm the module is actually drawing power, not just that a voltage is present. There is no modeled undervoltage fault for this component (fault is always false), unlike the LCD/MAX7219/TFT displays, which all raise a LOW V(D)D/CC fault below a set threshold.


6. Simulator Behavior — Real Bus-Level Simulation

Unlike every other display in this chapter, the OLED's on-canvas image is not driven by a static prop. OMS's simulator engine genuinely intercepts your compiled program's real I2C writes to this display's address, decodes the actual SSD1306 command/data protocol, and renders the real resulting 128×64 pixel buffer — pixel-for-pixel identical to what a physical panel would show. This works across all three simulation engines: AVR (C++), RP2040 (C++), and the MicroPython WASM VM (any board) — confirmed in GoldSimEngine.ts's onOledFrame/oledFrame handlers, which inject the captured frame directly into the component's render state, overriding anything its own state() function would otherwise show.

Before your program has sent its first real frame (or in idle canvas view), the part shows a placeholder — "OLED ON" plus the configured I2C address once powered, or a dim label when off.

[!NOTE] This is the standard this chapter's other four displays (LCD Parallel/I2C, MAX7219, TFT ST7735) don't yet meet — those show a manually-set prop or preset, not your real code's actual output. MAX7219 gained real bus capture on 2 of the 3 engine families (AVR, RP2040) as part of this same review (see 10.4); the LCD and TFT displays have no bus decoder on any engine family yet.


7. Supported Blockly Blocks (13 Blocks)

Drawing the blocks…

OLED Display (SSD1306) — OMS Parts