0
# Greyscale Displays
1

2
4-bit greyscale OLED displays supporting 16 levels of grey intensity. These displays can render both monochrome and greyscale content with automatic RGB to greyscale conversion using luma calculation.
3

4
## Capabilities
5

6
### SSD1322 Display
7

8
Serial interface to a 4-bit greyscale SSD1322 OLED display with flexible resolution support and dual rendering modes.
9

10
```python { .api }
11
class ssd1322:
12
    def __init__(self, serial_interface=None, width=256, height=64, rotate=0, mode="RGB", framebuffer=None, **kwargs):
13
        """
14
        Initialize SSD1322 greyscale OLED display.
15

16
        Parameters:
17
        - serial_interface: Serial interface (usually luma.core.interface.serial.spi)
18
        - width: Number of horizontal pixels (default: 256)
19
        - height: Number of vertical pixels (default: 64)
20
        - rotate: Rotation value 0-3 (0°, 90°, 180°, 270°) (default: 0)
21
        - mode: Rendering mode "1" (monochrome) or "RGB" (greyscale) (default: "RGB")
22
        - framebuffer: Framebuffering strategy (diff_to_previous or full_frame)
23
        """
24

25
    def command(self, cmd, *args):
26
        """
27
        Send command and optional arguments to the display.
28

29
        Parameters:
30
        - cmd: Command byte
31
        - args: Optional command arguments passed as data
32
        """
33
```
34

35
**Supported Resolutions**: (256,64), (256,48), (256,32), (128,64), (128,48), (128,32), (64,64), (64,48), (64,32)
36

37
Usage example:
38

39
```python
40
from luma.core.interface.serial import spi
41
from luma.oled.device import ssd1322
42
from luma.core.render import canvas
43

44
# Initialize large greyscale display
45
serial = spi(port=0, device=0, bus_speed_hz=8000000)
46
device = ssd1322(serial, width=256, height=64, mode="RGB")
47

48
# Draw greyscale content
49
with canvas(device) as draw:
50
    # RGB colors automatically converted to greyscale
51
    draw.rectangle((0, 0, 256, 64), fill=(128, 128, 128))  # Grey background
52
    draw.text((10, 10), "Greyscale Text", fill=(255, 255, 255))  # White text
53
    draw.ellipse((50, 20, 100, 50), fill=(64, 64, 64))     # Dark grey circle
54
```
55

56
### SSD1322 NHD Variant
57

58
Specialized version of SSD1322 for Newhaven Display (NHD) modules with fixed configuration.
59

60
```python { .api }
61
class ssd1322_nhd:
62
    def __init__(self, serial_interface=None, width=128, height=64, rotate=0, mode="RGB", framebuffer=full_frame(), **kwargs):
63
        """
64
        Initialize SSD1322 NHD greyscale OLED display.
65

66
        Parameters:
67
        - serial_interface: Serial interface (usually luma.core.interface.serial.spi)
68
        - width: Fixed at 128 pixels
69
        - height: Fixed at 64 pixels
70
        - rotate: Rotation value 0-3 (0°, 90°, 180°, 270°) (default: 0)
71
        - mode: Rendering mode "1" (monochrome) or "RGB" (greyscale) (default: "RGB")
72
        - framebuffer: Fixed to full_frame() strategy
73
        """
74

75
    def display(self, image):
76
        """
77
        Display 1-bit monochrome or 24-bit RGB image as greyscale.
78

79
        Parameters:
80
        - image: PIL.Image in mode "1" or "RGB"
81
        """
82

83
    def command(self, cmd, *args):
84
        """
85
        Send command and optional arguments to the display.
86
        """
87
```
88

89
**Supported Resolutions**: (128,64) only
90

91
### SSD1325 Display
92

93
Serial interface to a 4-bit greyscale SSD1325 OLED display with specialized greyscale table support.
94

95
```python { .api }
96
class ssd1325:
97
    def __init__(self, serial_interface=None, width=128, height=64, rotate=0, mode="RGB", framebuffer=None, **kwargs):
98
        """
99
        Initialize SSD1325 greyscale OLED display.
100

101
        Parameters:
102
        - serial_interface: Serial interface (usually luma.core.interface.serial.spi)
103
        - width: Number of horizontal pixels (default: 128)
104
        - height: Number of vertical pixels (default: 64)
105
        - rotate: Rotation value 0-3 (0°, 90°, 180°, 270°) (default: 0)
106
        - mode: Rendering mode "1" (monochrome) or "RGB" (greyscale) (default: "RGB")
107
        - framebuffer: Framebuffering strategy (diff_to_previous or full_frame)
108
        """
109
```
110

111
**Supported Resolutions**: (128,64)
112

113
### SSD1327 Display
114

115
Serial interface to a 4-bit greyscale SSD1327 OLED display with square format and enhanced greyscale support.
116

117
```python { .api }
118
class ssd1327:
119
    def __init__(self, serial_interface=None, width=128, height=128, rotate=0, mode="RGB", framebuffer=None, **kwargs):
120
        """
121
        Initialize SSD1327 greyscale OLED display.
122

123
        Parameters:
124
        - serial_interface: Serial interface (usually luma.core.interface.serial.spi)
125
        - width: Number of horizontal pixels (default: 128)
126
        - height: Number of vertical pixels (default: 128)
127
        - rotate: Rotation value 0-3 (0°, 90°, 180°, 270°) (default: 0)
128
        - mode: Rendering mode "1" (monochrome) or "RGB" (greyscale) (default: "RGB")
129
        - framebuffer: Framebuffering strategy (diff_to_previous or full_frame)
130
        """
131
```
132

133
**Supported Resolutions**: (128,128)
134

135
### SSD1362 Display
136

137
Serial interface to a 4-bit greyscale SSD1362 OLED display with wide format support.
138

139
```python { .api }
140
class ssd1362:
141
    def __init__(self, serial_interface=None, width=256, height=64, rotate=0, mode="RGB", framebuffer=None, **kwargs):
142
        """
143
        Initialize SSD1362 greyscale OLED display.
144

145
        Parameters:
146
        - serial_interface: Serial interface (usually luma.core.interface.serial.spi)
147
        - width: Number of horizontal pixels (default: 256)
148
        - height: Number of vertical pixels (default: 64)
149
        - rotate: Rotation value 0-3 (0°, 90°, 180°, 270°) (default: 0)
150
        - mode: Rendering mode "1" (monochrome) or "RGB" (greyscale) (default: "RGB")
151
        - framebuffer: Framebuffering strategy (diff_to_previous or full_frame)
152
        """
153
```
154

155
**Supported Resolutions**: (256,64)
156

157
## Rendering Modes
158

159
### RGB Mode (Greyscale)
160

161
In RGB mode, color images are converted to 4-bit greyscale using luma calculation:
162

163
```python
164
# RGB mode for greyscale rendering (default)
165
device = ssd1322(serial, mode="RGB")
166

167
with canvas(device) as draw:
168
    # Colors converted using Y' = 0.299R' + 0.587G' + 0.114B'
169
    draw.rectangle((0, 0, 100, 50), fill=(255, 0, 0))    # Red -> Dark grey
170
    draw.rectangle((100, 0, 200, 50), fill=(0, 255, 0))  # Green -> Light grey
171
    draw.rectangle((0, 50, 100, 64), fill=(0, 0, 255))   # Blue -> Very dark grey
172
```
173

174
### Monochrome Mode
175

176
In monochrome mode, displays render as 1-bit black and white:
177

178
```python
179
# Monochrome mode
180
device = ssd1322(serial, mode="1")
181

182
with canvas(device) as draw:
183
    # Only black (0) and white (255) pixels
184
    draw.rectangle((0, 0, 256, 64), fill=0)    # Black
185
    draw.text((10, 10), "Mono Text", fill=255) # White
186
```
187

188
## Advanced Usage
189

190
### Custom Greyscale Levels
191

192
Work directly with greyscale values (0-15 for 4-bit):
193

194
```python
195
from PIL import Image
196

197
# Create greyscale image with specific levels
198
img = Image.new("L", (128, 64))  # "L" mode for greyscale
199
pixels = img.load()
200

201
for x in range(128):
202
    for y in range(64):
203
        # Create gradient (values 0-255 mapped to 0-15 internally)
204
        pixels[x, y] = int((x / 128) * 255)
205

206
device.display(img)
207
```
208

209
### Performance Considerations
210

211
Greyscale displays use nibble packing (2 pixels per byte):
212

213
```python
214
# Efficient for even-width displays
215
device = ssd1322(serial, width=256, height=64)  # 256 is divisible by 4
216

217
# Less efficient for odd-width displays  
218
device = ssd1325(serial, width=128, height=64)  # Requires pixel alignment
219
```
220

221
## Common Patterns
222

223
### Error Handling
224

225
```python
226
import luma.core.error
227

228
try:
229
    device = ssd1327(serial, width=200, height=100)
230
except luma.core.error.DeviceDisplayModeError as e:
231
    print(f"Unsupported display mode: {e}")
232
```
233

234
### Image Mode Compatibility
235

236
```python
237
from PIL import Image
238

239
# Compatible image modes
240
mono_img = Image.new("1", (128, 64))        # 1-bit monochrome
241
grey_img = Image.new("L", (128, 64))        # 8-bit greyscale
242
rgb_img = Image.new("RGB", (128, 64))       # 24-bit RGB
243

244
# All can be displayed on greyscale devices
245
device.display(mono_img)  # Direct display
246
device.display(grey_img)  # Direct display
247
device.display(rgb_img)   # Converted to greyscale
248
```
249

250
### Framebuffer Optimization
251

252
```python
253
from luma.core.framebuffer import diff_to_previous, full_frame
254

255
# Recommended for animations and frequent updates
256
device = ssd1322(serial, framebuffer=diff_to_previous())
257

258
# Use for static content or troubleshooting
259
device = ssd1322(serial, framebuffer=full_frame())
260
```