0
# luma.oled
1

2
A Python library providing display drivers for OLED matrix displays with various controllers including SSD1306, SSD1309, SSD1322, SSD1325, SSD1327, SSD1331, SSD1351, SSD1362, SH1106, SH1107, and WS0010. The library supports I2C, SPI, and parallel communication protocols and provides a Pillow-compatible drawing canvas with advanced display capabilities.
3

4
## Package Information
5

6
- **Package Name**: luma.oled
7
- **Language**: Python
8
- **Installation**: `pip install luma.oled`
9
- **Dependencies**: `luma.core>=2.4.1` (automatically installs Pillow for image processing)
10

11
## Core Imports
12

13
```python
14
from luma.oled.device import ssd1306, ssd1331, ssd1322
15
from luma.core.interface.serial import i2c, spi
16
from luma.core.render import canvas
17
```
18

19
Version information:
20

21
```python
22
import luma.oled
23
print(luma.oled.__version__)  # "3.14.0"
24
```
25

26
For specific device types:
27

28
```python
29
# Monochrome devices
30
from luma.oled.device import ssd1306, ssd1309, sh1106, sh1107
31

32
# Color devices  
33
from luma.oled.device import ssd1331, ssd1351
34

35
# Greyscale devices
36
from luma.oled.device import ssd1322, ssd1325, ssd1327, ssd1362, ssd1322_nhd
37

38
# Character/text displays
39
from luma.oled.device import ws0010, winstar_weh
40
```
41

42
## Basic Usage
43

44
```python
45
from luma.core.interface.serial import i2c
46
from luma.core.render import canvas
47
from luma.oled.device import ssd1306
48
from PIL import ImageDraw
49

50
# Initialize I2C interface and device
51
serial = i2c(port=1, address=0x3C)
52
device = ssd1306(serial)
53

54
# Draw to the display using canvas context manager
55
with canvas(device) as draw:
56
    draw.rectangle(device.bounding_box, outline="white", fill="black")
57
    draw.text((30, 40), "Hello World", fill="white")
58

59
# Display will be automatically updated when canvas context exits
60
```
61

62
For persistent drawing:
63

64
```python
65
# Create reusable canvas
66
c = canvas(device)
67
for frame in range(100):
68
    with c as draw:
69
        draw.rectangle(device.bounding_box, outline="white", fill="black")
70
        draw.text((10, 10), f"Frame {frame}", fill="white")
71
```
72

73
## Architecture
74

75
The luma.oled library follows a layered architecture:
76

77
- **Device Layer**: Specific controller implementations (SSD1306, SH1106, etc.)
78
- **Base Classes**: Common functionality for color, greyscale, and character devices
79
- **Interface Layer**: Communication protocols (I2C, SPI, parallel) provided by luma.core
80
- **Rendering Layer**: Pillow-compatible drawing canvas and framebuffer management
81
- **Hardware Abstraction**: Consistent API across different chipsets and communication methods
82

83
The design enables developers to easily switch between different display types while maintaining the same drawing and rendering code.
84

85
## Capabilities
86

87
### Monochrome Displays
88

89
Single-color (usually white/blue) OLED displays supporting 1-bit monochrome rendering with full Pillow drawing capabilities.
90

91
```python { .api }
92
class ssd1306:
93
    def __init__(self, serial_interface=None, width=128, height=64, rotate=0, **kwargs): ...
94
    def display(self, image): ...
95
    def contrast(self, level): ...
96
    def show(self): ...
97
    def hide(self): ...
98
    def clear(self): ...
99
    @property
100
    def width(self) -> int: ...
101
    @property
102
    def height(self) -> int: ...
103
    @property
104
    def size(self) -> tuple[int, int]: ...
105
    @property
106
    def bounding_box(self) -> tuple[int, int, int, int]: ...
107

108
class ssd1309(ssd1306): ...
109

110
class sh1106:
111
    def __init__(self, serial_interface=None, width=128, height=64, rotate=0, **kwargs): ...
112
    def display(self, image): ...
113
    def contrast(self, level): ...
114
    def show(self): ...
115
    def hide(self): ...
116
    def clear(self): ...
117
    @property
118
    def width(self) -> int: ...
119
    @property
120
    def height(self) -> int: ...
121
    @property
122
    def size(self) -> tuple[int, int]: ...
123
    @property
124
    def bounding_box(self) -> tuple[int, int, int, int]: ...
125

126
class sh1107:
127
    def __init__(self, serial_interface=None, width=64, height=128, rotate=0, **kwargs): ...
128
    def display(self, image): ...
129
    def contrast(self, level): ...
130
    def show(self): ...
131
    def hide(self): ...
132
    def clear(self): ...
133
    @property
134
    def width(self) -> int: ...
135
    @property
136
    def height(self) -> int: ...
137
    @property
138
    def size(self) -> tuple[int, int]: ...
139
    @property
140
    def bounding_box(self) -> tuple[int, int, int, int]: ...
141
```
142

143
[Monochrome Displays](./monochrome-displays.md)
144

145
### Color Displays
146

147
16-bit color (5-6-5 RGB) OLED displays supporting full-color rendering with framebuffer optimization.
148

149
```python { .api }
150
class ssd1331:
151
    def __init__(self, serial_interface=None, width=96, height=64, rotate=0, framebuffer=None, **kwargs): ...
152
    def display(self, image): ...
153
    def contrast(self, level): ...
154
    def show(self): ...
155
    def hide(self): ...
156
    def clear(self): ...
157
    @property
158
    def width(self) -> int: ...
159
    @property
160
    def height(self) -> int: ...
161
    @property
162
    def size(self) -> tuple[int, int]: ...
163
    @property
164
    def bounding_box(self) -> tuple[int, int, int, int]: ...
165
    @property
166
    def framebuffer(self): ...
167

168
class ssd1351:
169
    def __init__(self, serial_interface=None, width=128, height=128, rotate=0, framebuffer=None, h_offset=0, v_offset=0, bgr=False, **kwargs): ...
170
    def display(self, image): ...
171
    def contrast(self, level): ...
172
    def command(self, cmd, *args): ...
173
    def show(self): ...
174
    def hide(self): ...
175
    def clear(self): ...
176
    @property
177
    def width(self) -> int: ...
178
    @property
179
    def height(self) -> int: ...
180
    @property
181
    def size(self) -> tuple[int, int]: ...
182
    @property
183
    def bounding_box(self) -> tuple[int, int, int, int]: ...
184
    @property
185
    def framebuffer(self): ...
186
```
187

188
[Color Displays](./color-displays.md)
189

190
### Greyscale Displays
191

192
4-bit greyscale OLED displays supporting both monochrome and greyscale rendering with automatic RGB to greyscale conversion.
193

194
```python { .api }
195
class ssd1322:
196
    def __init__(self, serial_interface=None, width=256, height=64, rotate=0, mode="RGB", framebuffer=None, **kwargs): ...
197
    def display(self, image): ...
198
    def command(self, cmd, *args): ...
199
    def contrast(self, level): ...
200
    def show(self): ...
201
    def hide(self): ...
202
    def clear(self): ...
203
    @property
204
    def width(self) -> int: ...
205
    @property
206
    def height(self) -> int: ...
207
    @property
208
    def size(self) -> tuple[int, int]: ...
209
    @property
210
    def bounding_box(self) -> tuple[int, int, int, int]: ...
211
    @property
212
    def framebuffer(self): ...
213

214
class ssd1325:
215
    def __init__(self, serial_interface=None, width=128, height=64, rotate=0, mode="RGB", framebuffer=None, **kwargs): ...
216
    def display(self, image): ...
217
    def contrast(self, level): ...
218
    def show(self): ...
219
    def hide(self): ...
220
    def clear(self): ...
221
    @property
222
    def width(self) -> int: ...
223
    @property
224
    def height(self) -> int: ...
225
    @property
226
    def size(self) -> tuple[int, int]: ...
227
    @property
228
    def bounding_box(self) -> tuple[int, int, int, int]: ...
229
    @property
230
    def framebuffer(self): ...
231

232
class ssd1327:
233
    def __init__(self, serial_interface=None, width=128, height=128, rotate=0, mode="RGB", framebuffer=None, **kwargs): ...
234
    def display(self, image): ...
235
    def contrast(self, level): ...
236
    def show(self): ...
237
    def hide(self): ...
238
    def clear(self): ...
239
    @property
240
    def width(self) -> int: ...
241
    @property
242
    def height(self) -> int: ...
243
    @property
244
    def size(self) -> tuple[int, int]: ...
245
    @property
246
    def bounding_box(self) -> tuple[int, int, int, int]: ...
247
    @property
248
    def framebuffer(self): ...
249

250
class ssd1362:
251
    def __init__(self, serial_interface=None, width=256, height=64, rotate=0, mode="RGB", framebuffer=None, **kwargs): ...
252
    def display(self, image): ...
253
    def contrast(self, level): ...
254
    def show(self): ...
255
    def hide(self): ...
256
    def clear(self): ...
257
    @property
258
    def width(self) -> int: ...
259
    @property
260
    def height(self) -> int: ...
261
    @property
262
    def size(self) -> tuple[int, int]: ...
263
    @property
264
    def bounding_box(self) -> tuple[int, int, int, int]: ...
265
    @property
266
    def framebuffer(self): ...
267

268
class ssd1322_nhd:
269
    def __init__(self, serial_interface=None, width=128, height=64, rotate=0, mode="RGB", framebuffer=full_frame(), **kwargs): ...
270
    def display(self, image): ...
271
    def contrast(self, level): ...
272
    def show(self): ...
273
    def hide(self): ...
274
    def clear(self): ...
275
    @property
276
    def width(self) -> int: ...
277
    @property
278
    def height(self) -> int: ...
279
    @property
280
    def size(self) -> tuple[int, int]: ...
281
    @property
282
    def bounding_box(self) -> tuple[int, int, int, int]: ...
283
    @property
284
    def framebuffer(self): ...
285
```
286

287
[Greyscale Displays](./greyscale-displays.md)
288

289
### Character/Text Displays
290

291
Text-oriented OLED displays with embedded fonts and character-based interface, supporting both graphical and text-based content.
292

293
```python { .api }
294
class ws0010:
295
    def __init__(self, serial_interface=None, width=100, height=16, undefined='_', font=None, selected_font=0, exec_time=1e-6 * 50, rotate=0, framebuffer=None, **kwargs): ...
296
    def display(self, image): ...
297
    def get_font(self, ft): ...
298
    def contrast(self, level): ...
299
    def show(self): ...
300
    def hide(self): ...
301
    def clear(self): ...
302
    @property
303
    def text(self) -> str: ...
304
    @text.setter
305
    def text(self, value: str): ...
306
    @property
307
    def width(self) -> int: ...
308
    @property
309
    def height(self) -> int: ...
310
    @property
311
    def size(self) -> tuple[int, int]: ...
312
    @property
313
    def bounding_box(self) -> tuple[int, int, int, int]: ...
314
    @property
315
    def framebuffer(self): ...
316

317
class winstar_weh(ws0010):
318
    def __init__(self, serial_interface=None, width=16, height=2, **kwargs): ...
319
```
320

321
[Character/Text Displays](./character-displays.md)
322

323
### Communication Interfaces
324

325
Serial communication interfaces provided by luma.core for connecting to OLED displays via different protocols.
326

327
```python { .api }
328
# From luma.core.interface.serial
329
class i2c:
330
    def __init__(self, port=1, address=0x3C, **kwargs): ...
331
    def command(self, cmd, *args): ...
332
    def data(self, values): ...
333

334
class spi:
335
    def __init__(self, port=0, device=0, bus_speed_hz=8000000, **kwargs): ...
336
    def command(self, cmd, *args): ...
337
    def data(self, values): ...
338

339
class parallel:
340
    def __init__(self, RS=7, E=8, PINS=[25,24,23,18], **kwargs): ...
341
    def command(self, cmd, *args): ...
342
    def data(self, values): ...
343
```
344

345
[Communication Interfaces](./interfaces.md)
346

347
## Common Types
348

349
```python { .api }
350
# Rotation values
351
Rotation = int  # 0, 1, 2, or 3 (0°, 90°, 180°, 270°)
352

353
# Display modes
354
DisplayMode = str  # "1" (monochrome), "RGB" (color/greyscale)
355

356
# Framebuffer strategies (from luma.core.framebuffer)
357
class diff_to_previous: ...
358
class full_frame: ...
359

360
# Bounding box
361
BoundingBox = tuple[int, int, int, int]  # (left, top, right, bottom)
362

363
# Image type (from PIL)
364
Image = PIL.Image.Image
365
```