0
# Luma LED Matrix
1
2
A Python library for interfacing with LED matrix displays, specifically targeting MAX7219 driver-based LED matrices, WS2812 NeoPixels, and APA102 DotStar LEDs on Raspberry Pi and other Linux-based single board computers. The library provides a Pillow-compatible drawing canvas with support for multiple cascaded devices, various display types, and advanced features like scrolling and terminal-style printing.
3
4
## Package Information
5
6
- **Package Name**: luma.led_matrix
7
- **Language**: Python
8
- **Installation**: `pip install luma.led_matrix`
9
- **Dependencies**: `luma.core`, `rpi_ws281x` (for NeoPixel support)
10
11
## Core Imports
12
13
```python
14
from luma.led_matrix.device import max7219, neopixel, ws2812, apa102, neosegment, unicornhathd
15
```
16
17
Device constants:
18
```python
19
from luma.led_matrix.const import max7219 as max7219_const
20
```
21
22
Segment mapping functions:
23
```python
24
from luma.led_matrix.segment_mapper import regular, dot_muncher
25
```
26
27
Required core imports for basic usage:
28
```python
29
from luma.core.interface.serial import spi, noop
30
from luma.core.render import canvas
31
```
32
33
## Basic Usage
34
35
### MAX7219 LED Matrix
36
```python
37
from luma.core.interface.serial import spi, noop
38
from luma.led_matrix.device import max7219
39
from luma.core.render import canvas
40
41
# Create serial interface and device
42
serial = spi(port=0, device=0, gpio=noop())
43
device = max7219(serial, width=8, height=8)
44
45
# Draw on the device
46
with canvas(device) as draw:
47
draw.rectangle(device.bounding_box, outline="white", fill="black")
48
draw.text((1, 1), "Hi", fill="white")
49
```
50
51
### NeoPixel (WS2812) LEDs
52
```python
53
from luma.led_matrix.device import neopixel
54
from luma.core.render import canvas
55
56
# Create device (auto-detects interface)
57
device = neopixel(width=8, height=4)
58
59
# Draw colorful patterns
60
with canvas(device) as draw:
61
draw.point((0, 0), fill="red")
62
draw.point((1, 0), fill="green")
63
draw.point((2, 0), fill="blue")
64
```
65
66
### Seven-Segment Display
67
```python
68
from luma.led_matrix.device import neosegment
69
70
# Create 4-digit seven-segment display
71
device = neosegment(width=4)
72
device.text = "1234"
73
```
74
75
## Architecture
76
77
The library follows the luma.core architecture pattern:
78
79
- **Device Classes**: Hardware-specific display drivers (max7219, ws2812, apa102, etc.)
80
- **Serial Interfaces**: Communication protocols (SPI, bitbang, DMA) from luma.core
81
- **Canvas Rendering**: Pillow-compatible drawing context for cross-device compatibility
82
- **Virtual Devices**: Higher-level abstractions like seven-segment displays built on top of basic devices
83
84
Each device inherits from `luma.core.device.device` and implements the standard display interface, allowing consistent usage patterns across different hardware types.
85
86
## Capabilities
87
88
### MAX7219 LED Matrix Driver
89
90
LED matrix display driver for MAX7219 chips supporting cascaded displays, rotation, block orientation, and brightness control.
91
92
```python { .api }
93
class max7219:
94
def __init__(
95
self,
96
serial_interface=None,
97
width=8,
98
height=8,
99
cascaded=None,
100
rotate=0,
101
block_orientation=0,
102
blocks_arranged_in_reverse_order=False,
103
contrast=0x70
104
): ...
105
106
def display(self, image): ...
107
def contrast(self, value): ...
108
def show(self): ...
109
def hide(self): ...
110
def clear(self): ...
111
def data(self, values): ...
112
def preprocess(self, image): ...
113
```
114
115
[MAX7219 LED Matrix](./max7219.md)
116
117
### NeoPixel (WS2812) RGB LEDs
118
119
RGB LED strip and matrix driver supporting WS281x chips with DMA interface for smooth animations and color control.
120
121
```python { .api }
122
class neopixel:
123
def __init__(
124
self,
125
dma_interface=None,
126
width=8,
127
height=4,
128
cascaded=None,
129
rotate=0,
130
mapping=None
131
): ...
132
133
def display(self, image): ...
134
def contrast(self, value): ...
135
def show(self): ...
136
def hide(self): ...
137
def clear(self): ...
138
def cleanup(self): ...
139
```
140
141
```python { .api }
142
# ws2812 is the same as neopixel
143
ws2812 = neopixel
144
```
145
146
[NeoPixel RGB LEDs](./neopixel.md)
147
148
### APA102 DotStar LEDs
149
150
APA102/DotStar LED driver supporting SPI and bitbang interfaces with individual brightness control via alpha channel.
151
152
```python { .api }
153
class apa102:
154
def __init__(
155
self,
156
serial_interface=None,
157
width=8,
158
height=1,
159
cascaded=None,
160
rotate=0,
161
mapping=None
162
): ...
163
164
def display(self, image): ...
165
def contrast(self, value): ...
166
def show(self): ...
167
def hide(self): ...
168
def clear(self): ...
169
```
170
171
[APA102 DotStar LEDs](./apa102.md)
172
173
### Seven-Segment Display
174
175
Virtual seven-segment display device built on top of NeoPixel hardware for displaying text and numbers.
176
177
```python { .api }
178
class neosegment:
179
def __init__(
180
self,
181
width,
182
undefined="_",
183
device=None
184
): ...
185
186
@property
187
def text(self): ...
188
189
@text.setter
190
def text(self, value): ...
191
192
@property
193
def color(self): ...
194
195
@color.setter
196
def color(self, value): ...
197
198
def segment_mapper(self, text, notfound): ...
199
```
200
201
[Seven-Segment Display](./sevensegment.md)
202
203
### Unicorn HAT HD
204
205
Specialized driver for Pimoroni's Unicorn HAT HD (16x16 RGB LED matrix) with SPI interface.
206
207
```python { .api }
208
class unicornhathd:
209
def __init__(
210
self,
211
serial_interface,
212
rotate=0
213
): ...
214
215
def display(self, image): ...
216
def contrast(self, value): ...
217
def show(self): ...
218
def hide(self): ...
219
```
220
221
[Unicorn HAT HD](./unicornhathd.md)
222
223
### Hardware Constants and Segment Mapping
224
225
Hardware register constants for MAX7219 and character-to-segment mapping utilities for seven-segment displays.
226
227
```python { .api }
228
class max7219:
229
NOOP = 0x00
230
DIGIT_0 = 0x01
231
DECODEMODE = 0x09
232
INTENSITY = 0x0A
233
SCANLIMIT = 0x0B
234
SHUTDOWN = 0x0C
235
DISPLAYTEST = 0x0F
236
```
237
238
```python { .api }
239
def regular(text, notfound="_"): ...
240
def dot_muncher(text, notfound="_"): ...
241
```
242
243
[Constants and Utilities](./constants.md)
244
245
## Types
246
247
```python { .api }
248
# Pixel mapping type for non-standard layouts
249
PixelMapping = list[int]
250
251
# Color specification (RGB tuple or color name)
252
Color = tuple[int, int, int] | str
253
254
# Device rotation angles
255
Rotation = 0 | 1 | 2 | 3 # 0°, 90°, 180°, 270°
256
257
# Block orientation for MAX7219
258
BlockOrientation = 0 | 90 | -90 | 180
259
260
# Image modes supported by different devices
261
ImageMode = "1" | "RGB" | "RGBA" # 1-bit monochrome, 24-bit RGB, 32-bit RGBA
262
263
# Serial interface types (from luma.core)
264
SerialInterface = object # SPI, bitbang, or noop interface objects
265
266
# DMA interface for WS281x devices
267
DMAInterface = object # WS281x DMA interface object
268
269
# Exception types that can be raised
270
DeviceDisplayModeError = Exception # Invalid display dimensions or mode
271
```