0
# NeoPixel RGB LEDs
1

2
RGB LED strip and matrix driver supporting WS281x chips (WS2812, WS2812B, WS2811, etc.) with DMA interface for smooth animations and full-color control. NeoPixels are individually addressable RGB LEDs that can display millions of colors.
3

4
## Capabilities
5

6
### Device Initialization
7

8
Creates a NeoPixel device instance with configurable dimensions, rotation, and pixel mapping for various LED arrangements.
9

10
```python { .api }
11
class neopixel:
12
    def __init__(
13
        self,
14
        dma_interface=None,
15
        width=8,
16
        height=4,
17
        cascaded=None,
18
        rotate=0,
19
        mapping=None
20
    ):
21
        """
22
        Initialize NeoPixel (WS281x) RGB LED device.
23
        
24
        Parameters:
25
        - dma_interface: WS2812 DMA interface (optional, auto-detected if not specified)
26
        - width: Number of pixels horizontally (default: 8)
27
        - height: Number of pixels vertically (default: 4)
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
# ws2812 is an alias for neopixel
34
ws2812 = neopixel
35
```
36

37
### Display Control
38

39
Controls the RGB LED output including color display, brightness adjustment, and cleanup operations.
40

41
```python { .api }
42
def display(self, image):
43
    """
44
    Display a 24-bit RGB PIL image on the NeoPixel LEDs.
45
    
46
    Parameters:
47
    - image: PIL Image object in mode 'RGB' (24-bit color)
48
    """
49

50
def contrast(self, value):
51
    """
52
    Set LED intensity/brightness for all pixels.
53
    
54
    Parameters:
55
    - value: Brightness level (0-255, where 0 is off and 255 is full brightness)
56
    """
57

58
def show(self):
59
    """
60
    Restore contrast to previous level.
61
    Used after hide() to bring LEDs back to normal brightness.
62
    """
63

64
def hide(self):
65
    """
66
    Set contrast to zero (simulated off state).
67
    LEDs appear off but device remains active.
68
    """
69

70
def cleanup(self):
71
    """
72
    Reset device and free hardware resources.
73
    Should be called when finished using the device.
74
    """
75
```
76

77
## Usage Examples
78

79
### Basic LED Strip
80
```python
81
from luma.led_matrix.device import neopixel
82
from luma.core.render import canvas
83

84
# Create 30-pixel LED strip
85
device = neopixel(cascaded=30)
86

87
# Set individual pixel colors
88
with canvas(device) as draw:
89
    draw.point((0, 0), fill="red")
90
    draw.point((1, 0), fill="green") 
91
    draw.point((2, 0), fill="blue")
92
    draw.point((3, 0), fill=(255, 128, 0))  # Orange
93
```
94

95
### 8x8 LED Matrix
96
```python
97
from luma.led_matrix.device import neopixel
98
from luma.core.render import canvas
99

100
# Create 8x8 NeoPixel matrix
101
device = neopixel(width=8, height=8)
102

103
# Draw colorful patterns
104
with canvas(device) as draw:
105
    # Rainbow diagonal
106
    for i in range(8):
107
        hue = i / 8.0
108
        import colorsys
109
        rgb = colorsys.hsv_to_rgb(hue, 1.0, 1.0)
110
        color = tuple(int(c * 255) for c in rgb)
111
        draw.point((i, i), fill=color)
112
```
113

114
### Unicorn HAT Layout
115
```python
116
from luma.led_matrix.device import neopixel, UNICORN_HAT
117
from luma.core.render import canvas
118

119
# Create 8x8 matrix with Unicorn HAT snake-like mapping
120
device = neopixel(width=8, height=8, mapping=UNICORN_HAT)
121

122
# Draw normally - mapping handles physical layout
123
with canvas(device) as draw:
124
    draw.rectangle((0, 0, 7, 7), outline="white")
125
```
126

127
### Animated Effects
128
```python
129
import time
130
import math
131
from luma.led_matrix.device import neopixel
132
from luma.core.render import canvas
133

134
device = neopixel(width=8, height=4)
135

136
# Brightness control
137
device.contrast(128)  # 50% brightness
138

139
# Animated rainbow wave
140
for step in range(100):
141
    with canvas(device) as draw:
142
        for x in range(device.width):
143
            for y in range(device.height):
144
                hue = (x + y + step * 0.1) % 1.0
145
                import colorsys
146
                rgb = colorsys.hsv_to_rgb(hue, 1.0, 1.0)
147
                color = tuple(int(c * 255) for c in rgb)
148
                draw.point((x, y), fill=color)
149
    time.sleep(0.05)
150

151
# Cleanup when done
152
device.cleanup()
153
```
154

155
### Custom Pixel Mapping
156
```python
157
from luma.led_matrix.device import neopixel
158

159
# Custom mapping for non-standard LED arrangements
160
# Maps logical positions to physical LED indices
161
custom_mapping = [
162
    15, 14, 13, 12,  # Top row (right to left)
163
    8,  9,  10, 11,  # Second row (left to right)
164
    7,  6,  5,  4,   # Third row (right to left)
165
    0,  1,  2,  3    # Bottom row (left to right)
166
]
167

168
device = neopixel(width=4, height=4, mapping=custom_mapping)
169
```
170

171
## Hardware Constants
172

173
### Unicorn HAT Mapping
174
```python { .api }
175
UNICORN_HAT: list[int]
176
```
177
Translation mapping for 8x8 Unicorn HAT converting snake-like physical layout to scan-like logical layout. This 64-element list maps logical pixel positions to physical LED indices.
178

179
```python { .api }
180
UNICORN_HAT = [
181
    7,  6,  5,  4,  3,  2,  1,  0,
182
    8,  9,  10, 11, 12, 13, 14, 15,
183
    23, 22, 21, 20, 19, 18, 17, 16,
184
    24, 25, 26, 27, 28, 29, 30, 31,
185
    39, 38, 37, 36, 35, 34, 33, 32,
186
    40, 41, 42, 43, 44, 45, 46, 47,
187
    55, 54, 53, 52, 51, 50, 49, 48,
188
    56, 57, 58, 59, 60, 61, 62, 63
189
]
190
```
191

192
## Hardware Requirements
193

194
- **Platform**: Raspberry Pi or compatible Linux SBC with PWM/DMA support
195
- **Interface**: PWM + DMA (via rpi_ws281x library)
196
- **Connections**:
197
  - Data: GPIO 18 (PWM0) or GPIO 12 (PWM0 Alt) or GPIO 13 (PWM1)
198
  - Power: 5V supply (adequate current capacity required)
199
  - Ground: Common ground connection
200
- **Power**: External 5V supply recommended for multiple LEDs
201
- **Current**: ~60mA per LED at full white brightness
202

203
## Error Handling
204

205
The device may raise the following exceptions:
206

207
- `RuntimeError`: WS281x initialization failures, DMA setup issues, or hardware communication errors
208
- `luma.core.error.DeviceDisplayModeError`: Invalid display dimensions or unsupported image mode
209
- `AssertionError`: Invalid parameter values (brightness out of range, invalid dimensions)
210
- `OverflowError`: Too many pixels specified for available memory/hardware limits
211

212
## Performance Notes
213

214
- Uses DMA for efficient data transfer without CPU blocking
215
- Supports up to 1000+ LEDs depending on available memory
216
- Update rates of 60+ FPS possible for smooth animations
217
- Color depth: 24-bit RGB (16.7 million colors) with 8-bit brightness control