0
# MAX7219 LED Matrix
1

2
LED matrix display driver for MAX7219 chips supporting cascaded displays, rotation, block orientation, and brightness control. The MAX7219 is a popular SPI-driven LED matrix controller that can drive 8x8 LED matrices.
3

4
## Capabilities
5

6
### Device Initialization
7

8
Creates a MAX7219 device instance with configurable display size, cascading, rotation, and layout options.
9

10
```python { .api }
11
class max7219:
12
    def __init__(
13
        self,
14
        serial_interface=None,
15
        width=8,
16
        height=8, 
17
        cascaded=None,
18
        rotate=0,
19
        block_orientation=0,
20
        blocks_arranged_in_reverse_order=False,
21
        contrast=0x70,
22
        **kwargs
23
    ):
24
        """
25
        Initialize MAX7219 LED matrix device.
26
        
27
        Parameters:
28
        - serial_interface: Serial interface object (from luma.core.interface.serial), optional
29
        - width: Display width in pixels (default: 8)
30
        - height: Display height in pixels (default: 8)
31
        - cascaded: Number of cascaded devices (overrides width/height if specified)
32
        - rotate: Rotation angle in degrees (0, 90, 180, 270)
33
        - block_orientation: Block rotation angle (0, 90, -90, 180)
34
        - blocks_arranged_in_reverse_order: Boolean for reverse order (default: False)
35
        - contrast: Initial contrast/brightness value (0-255, default: 0x70)
36
        - **kwargs: Additional parameters passed to parent device class
37
        """
38
```
39

40
### Display Control
41

42
Controls the display output including showing images, brightness adjustment, and power management.
43

44
```python { .api }
45
def display(self, image):
46
    """
47
    Display a 1-bit PIL image on the LED matrix.
48
    
49
    Parameters:
50
    - image: PIL Image object in mode '1' (1-bit monochrome)
51
    """
52

53
def contrast(self, value):
54
    """
55
    Set LED intensity/brightness.
56
    
57
    Parameters:
58
    - value: Brightness level (0-255, where 0 is dimmest and 255 is brightest)
59
    """
60

61
def show(self):
62
    """
63
    Wake the device from low-power sleep mode.
64
    Restores the device to normal operation.
65
    """
66

67
def hide(self):
68
    """
69
    Put the device in low-power sleep mode.
70
    Turns off all LEDs to save power.
71
    """
72
```
73

74
### Image Preprocessing
75

76
Handles image transformations for proper display on the LED matrix hardware.
77

78
```python { .api }
79
def preprocess(self, image):
80
    """
81
    Preprocess image with rotation and reverse order corrections.
82
    
83
    Parameters:
84
    - image: PIL Image object
85
    
86
    Returns:
87
    - PIL Image object with transformations applied
88
    """
89
```
90

91
## Usage Examples
92

93
### Basic 8x8 Matrix
94
```python
95
from luma.core.interface.serial import spi, noop
96
from luma.led_matrix.device import max7219
97
from luma.core.render import canvas
98

99
# Create SPI interface
100
serial = spi(port=0, device=0, gpio=noop())
101
device = max7219(serial, width=8, height=8)
102

103
# Draw a simple pattern
104
with canvas(device) as draw:
105
    draw.rectangle((0, 0, 7, 7), outline="white")
106
    draw.point((4, 4), fill="white")
107
```
108

109
### Cascaded Multiple Matrices
110
```python
111
from luma.core.interface.serial import spi, noop
112
from luma.led_matrix.device import max7219
113
from luma.core.render import canvas
114

115
# Create interface for 4 cascaded 8x8 matrices (32x8 total)
116
serial = spi(port=0, device=0, gpio=noop())
117
device = max7219(serial, cascaded=4)
118

119
# Draw across all matrices
120
with canvas(device) as draw:
121
    draw.text((0, 0), "Hello World", fill="white")
122
```
123

124
### Rotated Display
125
```python
126
from luma.core.interface.serial import spi, noop
127
from luma.led_matrix.device import max7219
128

129
# Create rotated 90-degree display
130
serial = spi(port=0, device=0, gpio=noop())
131
device = max7219(serial, width=8, height=8, rotate=90)
132

133
# Brightness control
134
device.contrast(128)  # Medium brightness
135

136
# Power management
137
device.hide()  # Sleep mode
138
device.show()  # Wake up
139
```
140

141
### Custom Block Arrangement
142
```python
143
from luma.core.interface.serial import spi, noop
144
from luma.led_matrix.device import max7219
145

146
# Create display with blocks in reverse order and rotated blocks
147
serial = spi(port=0, device=0, gpio=noop())
148
device = max7219(
149
    serial, 
150
    cascaded=4,
151
    block_orientation=90,
152
    blocks_arranged_in_reverse_order=True
153
)
154
```
155

156
## Hardware Requirements
157

158
- **Platform**: Raspberry Pi or compatible Linux SBC
159
- **Interface**: SPI (Serial Peripheral Interface)
160
- **Connections**: 
161
  - VCC: 5V power supply
162
  - GND: Ground
163
  - DIN: SPI MOSI (GPIO 10)
164
  - CS: SPI CE0 (GPIO 8) 
165
  - CLK: SPI SCLK (GPIO 11)
166

167
## Error Handling
168

169
The device may raise the following exceptions:
170

171
- `luma.core.error.DeviceDisplayModeError`: Invalid display dimensions or unsupported image mode
172
- `AssertionError`: Invalid parameter values (contrast out of range, invalid rotation, etc.)
173
- `RuntimeError`: SPI interface initialization or communication failures