0
# Monochrome Displays
1

2
Single-color OLED displays that support 1-bit monochrome rendering. These displays typically show white, blue, or yellow pixels on a black background, providing crisp text and graphics with high contrast.
3

4
## Capabilities
5

6
### SSD1306 Display
7

8
Serial interface to a monochrome SSD1306 OLED display, one of the most common OLED controllers supporting multiple resolution configurations.
9

10
```python { .api }
11
class ssd1306:
12
    def __init__(self, serial_interface=None, width=128, height=64, rotate=0, **kwargs):
13
        """
14
        Initialize SSD1306 OLED display.
15

16
        Parameters:
17
        - serial_interface: Serial interface (usually luma.core.interface.serial.i2c)
18
        - width: Number of horizontal pixels (default: 128)
19
        - height: Number of vertical pixels (default: 64)
20
        - rotate: Rotation value 0-3 (0°, 90°, 180°, 270°) (default: 0)
21
        """
22

23
    def display(self, image):
24
        """
25
        Display a 1-bit PIL Image on the OLED.
26

27
        Parameters:
28
        - image: PIL.Image in mode "1" (1-bit monochrome)
29
        
30
        The image size must exactly match the display dimensions.
31
        """
32
```
33

34
**Supported Resolutions**: (128,64), (128,32), (96,16), (64,48), (64,32)
35

36
Usage example:
37

38
```python
39
from luma.core.interface.serial import i2c
40
from luma.oled.device import ssd1306
41
from luma.core.render import canvas
42

43
# Initialize device
44
serial = i2c(port=1, address=0x3C)
45
device = ssd1306(serial, width=128, height=64)
46

47
# Draw content
48
with canvas(device) as draw:
49
    draw.text((0, 0), "SSD1306 Display", fill="white")
50
    draw.rectangle((10, 20, 50, 40), outline="white")
51
```
52

53
### SSD1309 Display
54

55
Serial interface to a monochrome SSD1309 OLED display, compatible with SSD1306 but optimized for SPI communication.
56

57
```python { .api }
58
class ssd1309(ssd1306):
59
    """
60
    Inherits all functionality from ssd1306.
61
    
62
    Optimized for SPI communication but maintains full API compatibility.
63
    Constructor parameters and methods identical to ssd1306.
64
    """
65
```
66

67
**Supported Resolutions**: Same as SSD1306
68

69
Usage example:
70

71
```python
72
from luma.core.interface.serial import spi
73
from luma.oled.device import ssd1309
74

75
# Initialize with SPI interface
76
serial = spi(port=0, device=0, bus_speed_hz=8000000)
77
device = ssd1309(serial, width=128, height=64)
78
```
79

80
### SH1106 Display
81

82
Serial interface to a monochrome SH1106 OLED display with different memory organization than SSD1306, requiring specialized display logic.
83

84
```python { .api }
85
class sh1106:
86
    def __init__(self, serial_interface=None, width=128, height=64, rotate=0, **kwargs):
87
        """
88
        Initialize SH1106 OLED display.
89

90
        Parameters:
91
        - serial_interface: Serial interface (usually luma.core.interface.serial.i2c)
92
        - width: Number of horizontal pixels (default: 128)
93
        - height: Number of vertical pixels (default: 64)
94
        - rotate: Rotation value 0-3 (0°, 90°, 180°, 270°) (default: 0)
95
        """
96

97
    def display(self, image):
98
        """
99
        Display a 1-bit PIL Image on the SH1106 OLED.
100

101
        Parameters:
102
        - image: PIL.Image in mode "1" (1-bit monochrome)
103
        """
104
```
105

106
**Supported Resolutions**: (128,128), (128,64), (128,32)
107

108
Usage example:
109

110
```python
111
from luma.core.interface.serial import i2c
112
from luma.oled.device import sh1106
113

114
# Initialize device - note different default resolution
115
serial = i2c(port=1, address=0x3C)
116
device = sh1106(serial, width=128, height=128)
117

118
with canvas(device) as draw:
119
    draw.ellipse((10, 10, 118, 118), outline="white")
120
```
121

122
### SH1107 Display
123

124
Serial interface to a monochrome SH1107 OLED display with portrait orientation as default and specialized memory mapping.
125

126
```python { .api }
127
class sh1107:
128
    def __init__(self, serial_interface=None, width=64, height=128, rotate=0, **kwargs):
129
        """
130
        Initialize SH1107 OLED display.
131

132
        Parameters:
133
        - serial_interface: Serial interface (usually luma.core.interface.serial.i2c)
134
        - width: Number of horizontal pixels (default: 64)
135
        - height: Number of vertical pixels (default: 128)
136
        - rotate: Rotation value 0-3 (0°, 90°, 180°, 270°) (default: 0)
137
        
138
        Note: Default orientation is portrait (64x128)
139
        """
140

141
    def display(self, image):
142
        """
143
        Display a 1-bit PIL Image on the SH1107 OLED.
144

145
        Parameters:
146
        - image: PIL.Image in mode "1" (1-bit monochrome)
147
        """
148
```
149

150
**Supported Resolutions**: (64,128), (80,128), (128,128)
151

152
Usage example:
153

154
```python
155
from luma.core.interface.serial import i2c
156
from luma.oled.device import sh1107
157

158
# Initialize with portrait orientation
159
serial = i2c(port=1, address=0x3C)
160
device = sh1107(serial)  # Uses default 64x128
161

162
with canvas(device) as draw:
163
    # Portrait-oriented content
164
    draw.text((5, 10), "Portrait", fill="white")
165
    draw.text((5, 30), "Display", fill="white")
166
    draw.rectangle((5, 50, 59, 100), outline="white")
167
```
168

169
## Common Patterns
170

171
### Error Handling
172

173
All monochrome displays will raise `luma.core.error.DeviceDisplayModeError` if an unsupported resolution is specified:
174

175
```python
176
from luma.oled.device import ssd1306
177
import luma.core.error
178

179
try:
180
    device = ssd1306(serial, width=200, height=200)  # Unsupported
181
except luma.core.error.DeviceDisplayModeError as e:
182
    print(f"Unsupported display mode: {e}")
183
```
184

185
### Image Requirements
186

187
All monochrome displays require 1-bit PIL Images:
188

189
```python
190
from PIL import Image
191

192
# Create compatible image
193
img = Image.new("1", (128, 64), color=0)  # Black background
194
# Draw to image...
195
device.display(img)
196
```
197

198
### Memory and Performance
199

200
- Use `luma.core.framebuffer.diff_to_previous()` (default) for efficient updates
201
- Use `luma.core.framebuffer.full_frame()` for guaranteed complete refreshes
202
- Canvas context manager automatically handles framebuffer optimization