0
# APA102 DotStar LEDs
1

2
APA102/DotStar LED driver supporting SPI and bitbang interfaces with individual brightness control via alpha channel. APA102 LEDs offer higher refresh rates and more precise color control compared to WS281x chips.
3

4
## Capabilities
5

6
### Device Initialization
7

8
Creates an APA102 device instance with configurable dimensions, interface selection, and pixel mapping.
9

10
```python { .api }
11
class apa102:
12
    def __init__(
13
        self,
14
        serial_interface=None,
15
        width=8,
16
        height=1,
17
        cascaded=None,
18
        rotate=0,
19
        mapping=None
20
    ):
21
        """
22
        Initialize APA102 DotStar LED device.
23
        
24
        Parameters:
25
        - serial_interface: Serial interface (SPI or bitbang), optional (defaults to bitbang)
26
        - width: Number of pixels horizontally (default: 8)
27
        - height: Number of pixels vertically (default: 1)
28
        - cascaded: Total number of pixels in strip (overrides width/height if specified)
29
        - rotate: Rotation angle (0, 1, 2, 3 for 0°, 90°, 180°, 270°)
30
        - mapping: Array of pixel-to-physical offset mappings for non-standard layouts
31
        """
32
```
33

34
### Display Control
35

36
Controls the RGB LED output with support for individual pixel brightness control through the alpha channel.
37

38
```python { .api }
39
def display(self, image):
40
    """
41
    Display a 32-bit RGBA PIL image on the APA102 LEDs.
42
    The alpha channel controls individual pixel brightness.
43
    
44
    Parameters:
45
    - image: PIL Image object in mode 'RGBA' (32-bit color with alpha)
46
             Alpha values: 0 = off, 255 = full brightness
47
             RGB values: Standard 0-255 color channels
48
    """
49

50
def contrast(self, value):
51
    """
52
    Set global LED intensity/brightness multiplier.
53
    
54
    Parameters:
55
    - value: Global brightness level (0-255)
56
             Applied as multiplier to individual pixel alpha values
57
    """
58

59
def show(self):
60
    """
61
    Not supported operation (no-op).
62
    APA102 LEDs update immediately on display() calls.
63
    """
64

65
def hide(self):
66
    """
67
    Not supported operation (no-op).
68
    Use contrast(0) or display black image to turn off LEDs.
69
    """
70
```
71

72
## Usage Examples
73

74
### Basic LED Strip
75
```python
76
from luma.led_matrix.device import apa102
77
from luma.core.render import canvas
78
from PIL import Image
79

80
# Create 30-pixel APA102 strip with default bitbang interface
81
device = apa102(cascaded=30)
82

83
# Create RGBA image for brightness control
84
img = Image.new('RGBA', (30, 1))
85
pixels = img.load()
86

87
# Set colors with individual brightness
88
pixels[0, 0] = (255, 0, 0, 255)    # Red at full brightness
89
pixels[1, 0] = (0, 255, 0, 128)    # Green at 50% brightness
90
pixels[2, 0] = (0, 0, 255, 64)     # Blue at 25% brightness
91

92
device.display(img)
93
```
94

95
### Using SPI Interface
96
```python
97
from luma.core.interface.serial import spi, noop
98
from luma.led_matrix.device import apa102
99
from luma.core.render import canvas
100

101
# Create SPI interface for faster communication
102
serial = spi(port=0, device=0, gpio=noop())
103
device = apa102(serial_interface=serial, cascaded=50)
104

105
# Draw with canvas (auto-converts to RGBA)
106
with canvas(device) as draw:
107
    # Canvas drawing automatically sets full alpha
108
    draw.point((0, 0), fill="red")
109
    draw.point((1, 0), fill="green")
110
    draw.point((2, 0), fill="blue")
111
```
112

113
### LED Matrix with Brightness Control
114
```python
115
from luma.led_matrix.device import apa102
116
from PIL import Image
117
import numpy as np
118

119
# Create 8x8 LED matrix
120
device = apa102(width=8, height=8)
121

122
# Create gradient brightness pattern
123
img = Image.new('RGBA', (8, 8))
124
pixels = img.load()
125

126
for x in range(8):
127
    for y in range(8):
128
        # Distance-based brightness
129
        distance = ((x - 3.5) ** 2 + (y - 3.5) ** 2) ** 0.5
130
        brightness = max(0, int(255 - distance * 30))
131
        pixels[x, y] = (255, 255, 255, brightness)  # White with varying brightness
132

133
device.display(img)
134
```
135

136
### Animated Effects with Brightness
137
```python
138
import time
139
import math
140
from luma.led_matrix.device import apa102
141
from PIL import Image
142

143
device = apa102(width=16, height=1)
144

145
# Breathing effect with individual pixel brightness
146
for step in range(100):
147
    img = Image.new('RGBA', (16, 1))
148
    pixels = img.load()
149
    
150
    for i in range(16):
151
        # Sine wave brightness pattern
152
        brightness = int(128 + 127 * math.sin(step * 0.2 + i * 0.5))
153
        hue = (i + step * 0.1) % 1.0
154
        
155
        # Convert HSV to RGB
156
        import colorsys
157
        rgb = colorsys.hsv_to_rgb(hue, 1.0, 1.0)
158
        color = tuple(int(c * 255) for c in rgb)
159
        
160
        pixels[i, 0] = (*color, brightness)
161
    
162
    device.display(img)
163
    time.sleep(0.05)
164
```
165

166
### Global Brightness Control
167
```python
168
from luma.led_matrix.device import apa102
169
from luma.core.render import canvas
170

171
device = apa102(cascaded=20)
172

173
# Set global brightness to 25%
174
device.contrast(64)
175

176
# Draw normally - global brightness will be applied
177
with canvas(device) as draw:
178
    for i in range(20):
179
        draw.point((i, 0), fill="white")
180

181
# Fade out gradually
182
for brightness in range(64, -1, -2):
183
    device.contrast(brightness)
184
    time.sleep(0.1)
185
```
186

187
## Hardware Requirements
188

189
- **Platform**: Raspberry Pi or compatible Linux SBC
190
- **Interface Options**:
191
  - **SPI**: Hardware SPI for faster communication (recommended for many LEDs)
192
  - **Bitbang**: GPIO bit-banging (default, works with any GPIO pins)
193
- **Connections**:
194
  - **SPI Mode**: 
195
    - Data: SPI MOSI (GPIO 10)
196
    - Clock: SPI SCLK (GPIO 11)
197
  - **Bitbang Mode**:
198
    - Data: Any GPIO pin (configurable)
199
    - Clock: Any GPIO pin (configurable)
200
  - **Power**: 5V supply with adequate current capacity
201
  - **Ground**: Common ground connection
202

203
## Performance Advantages
204

205
- **Higher Refresh Rates**: Up to 20kHz vs ~800Hz for WS281x
206
- **Individual Brightness**: Each pixel has independent brightness control
207
- **Clock Signal**: Separate clock allows more reliable timing
208
- **SPI Compatible**: Can use hardware SPI for maximum speed
209
- **No Timing Critical**: Less sensitive to timing variations than WS281x
210

211
## Error Handling
212

213
The device may raise the following exceptions:
214

215
- `luma.core.error.DeviceDisplayModeError`: Invalid display dimensions or unsupported image mode
216
- `AssertionError`: Invalid parameter values (brightness out of range, invalid dimensions)
217
- `RuntimeError`: SPI interface initialization failures or communication errors
218
- `OverflowError`: Too many pixels specified for available memory limits
219

220
## Alpha Channel Usage
221

222
APA102 LEDs support 5-bit brightness control (32 levels) per pixel through the alpha channel:
223

224
- **Alpha 0**: LED off
225
- **Alpha 1-7**: Very dim (mapped to hardware brightness 1)
226
- **Alpha 8-15**: Dim (mapped to hardware brightness 2)
227
- **...continuing pattern...**
228
- **Alpha 248-255**: Full brightness (mapped to hardware brightness 31)
229

230
The library automatically handles the conversion from 8-bit alpha values to 5-bit hardware brightness levels.