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
```