0
# Unicorn HAT HD
1

2
Specialized driver for Pimoroni's Unicorn HAT HD, a 16x16 RGB LED matrix (256 LEDs total) that connects via SPI interface. This device provides high-resolution RGB display capabilities for Raspberry Pi projects.
3

4
## Capabilities
5

6
### Device Initialization
7

8
Creates a Unicorn HAT HD device instance with configurable rotation.
9

10
```python { .api }
11
class unicornhathd:
12
    def __init__(
13
        self,
14
        serial_interface=None,
15
        rotate=0,
16
        **kwargs
17
    ):
18
        """
19
        Initialize Unicorn HAT HD device.
20
        
21
        Parameters:
22
        - serial_interface: Serial SPI interface object (optional, defaults to None)
23
        - rotate: Rotation angle (0, 1, 2, 3 for 0°, 90°, 180°, 270°)
24
        - **kwargs: Additional parameters passed to parent device class
25
        """
26
```
27

28
### Display Control
29

30
Controls the RGB LED matrix output with brightness and power management features.
31

32
```python { .api }
33
def display(self, image):
34
    """
35
    Display a 32-bit RGBA PIL image on the 16x16 LED matrix.
36
    Alpha channel controls individual pixel brightness.
37
    
38
    Parameters:
39
    - image: PIL Image object in mode 'RGBA' (32-bit color with alpha)
40
             Must be 16x16 pixels to match hardware dimensions
41
    """
42

43
def contrast(self, value):
44
    """
45
    Set LED intensity/brightness for all pixels.
46
    
47
    Parameters:
48
    - value: Brightness level (0-255, where 0 is off and 255 is full brightness)
49
    """
50

51
def show(self):
52
    """
53
    Restore contrast to previous level.
54
    Brings LEDs back to normal brightness after hide().
55
    """
56

57
def hide(self):
58
    """
59
    Set contrast to zero (all LEDs appear off).
60
    LEDs are turned off but device remains active for quick restore.
61
    """
62
```
63

64
## Usage Examples
65

66
### Basic Setup
67
```python
68
from luma.core.interface.serial import spi, noop
69
from luma.led_matrix.device import unicornhathd
70
from luma.core.render import canvas
71

72
# Create SPI interface 
73
serial = spi(port=0, device=0, gpio=noop())
74
device = unicornhathd(serial_interface=serial)
75

76
# Draw simple pattern
77
with canvas(device) as draw:
78
    draw.rectangle((0, 0, 15, 15), outline="white")
79
    draw.point((8, 8), fill="red")
80
```
81

82
### Rainbow Pattern
83
```python
84
import colorsys
85
from luma.core.interface.serial import spi, noop
86
from luma.led_matrix.device import unicornhathd
87
from luma.core.render import canvas
88

89
serial = spi(port=0, device=0, gpio=noop())
90
device = unicornhathd(serial_interface=serial)
91

92
# Create rainbow gradient
93
with canvas(device) as draw:
94
    for x in range(16):
95
        for y in range(16):
96
            # Calculate hue based on position
97
            hue = (x + y) / 32.0
98
            rgb = colorsys.hsv_to_rgb(hue, 1.0, 1.0)
99
            color = tuple(int(c * 255) for c in rgb)
100
            draw.point((x, y), fill=color)
101
```
102

103
### Animated Plasma Effect
104
```python
105
import time
106
import math
107
from luma.core.interface.serial import spi, noop
108
from luma.led_matrix.device import unicornhathd
109
from luma.core.render import canvas
110

111
serial = spi(port=0, device=0, gpio=noop())
112
device = unicornhathd(serial_interface=serial)
113

114
# Plasma animation
115
for step in range(1000):
116
    with canvas(device) as draw:
117
        for x in range(16):
118
            for y in range(16):
119
                # Plasma calculation
120
                v = math.sin((x + step) * 0.2) * 0.5
121
                v += math.sin((y + step) * 0.15) * 0.5
122
                v += math.sin((x + y + step) * 0.1) * 0.5
123
                v += math.sin(math.sqrt((x - 8) ** 2 + (y - 8) ** 2) + step * 0.3) * 0.5
124
                
125
                # Convert to color
126
                hue = (v + 4) / 8.0
127
                import colorsys
128
                rgb = colorsys.hsv_to_rgb(hue, 1.0, 1.0)
129
                color = tuple(int(c * 255) for c in rgb)
130
                draw.point((x, y), fill=color)
131
    
132
    time.sleep(0.05)
133
```
134

135
### Image Display with Brightness Control
136
```python
137
from PIL import Image
138
from luma.core.interface.serial import spi, noop
139
from luma.led_matrix.device import unicornhathd
140

141
serial = spi(port=0, device=0, gpio=noop())
142
device = unicornhathd(serial_interface=serial)
143

144
# Load and resize image to 16x16
145
image = Image.open("photo.jpg")
146
image = image.resize((16, 16), Image.LANCZOS)
147
image = image.convert("RGBA")
148

149
# Display with varying brightness
150
for brightness in range(0, 256, 5):
151
    device.contrast(brightness)
152
    device.display(image)
153
    time.sleep(0.1)
154
```
155

156
### Rotated Display
157
```python
158
from luma.core.interface.serial import spi, noop
159
from luma.led_matrix.device import unicornhathd
160
from luma.core.render import canvas
161

162
# Create device rotated 90 degrees
163
serial = spi(port=0, device=0, gpio=noop())
164
device = unicornhathd(serial_interface=serial, rotate=1)
165

166
# Draw text that will appear rotated
167
with canvas(device) as draw:
168
    draw.text((2, 5), "HI", fill="green")
169
```
170

171
### Scrolling Text
172
```python
173
import time
174
from luma.core.interface.serial import spi, noop
175
from luma.led_matrix.device import unicornhathd
176
from luma.core.render import canvas
177
from luma.core.virtual import viewport
178
from luma.core.legacy import text
179
from luma.core.legacy.font import proportional, CP437_FONT
180

181
serial = spi(port=0, device=0, gpio=noop())
182
device = unicornhathd(serial_interface=serial)
183

184
# Create scrolling text
185
virtual = viewport(device, width=200, height=16)
186
text(virtual, (0, 0), "Scrolling message on Unicorn HAT HD!", 
187
     fill="white", font=proportional(CP437_FONT))
188

189
# Scroll the text
190
for offset in range(200 - 16):
191
    virtual.set_position((offset, 0))
192
    time.sleep(0.1)
193
```
194

195
### Power Management
196
```python
197
import time
198
from luma.core.interface.serial import spi, noop
199
from luma.led_matrix.device import unicornhathd
200
from luma.core.render import canvas
201

202
serial = spi(port=0, device=0, gpio=noop())
203
device = unicornhathd(serial_interface=serial)
204

205
# Draw pattern
206
with canvas(device) as draw:
207
    draw.ellipse((4, 4, 12, 12), fill="blue")
208

209
# Flash on and off
210
for _ in range(10):
211
    device.hide()   # Turn off
212
    time.sleep(0.5)
213
    device.show()   # Turn on
214
    time.sleep(0.5)
215
```
216

217
## Hardware Specifications
218

219
- **Resolution**: 16×16 RGB LEDs (256 total)
220
- **Color Depth**: 24-bit RGB (16.7 million colors)
221
- **Brightness Control**: 8-bit per pixel via alpha channel
222
- **Interface**: SPI communication
223
- **Dimensions**: 62mm × 62mm HAT form factor
224
- **Power**: 5V via GPIO header (external supply recommended for full brightness)
225
- **Current Draw**: Up to 2A at full white brightness
226

227
## Hardware Requirements
228

229
- **Platform**: Raspberry Pi with 40-pin GPIO header
230
- **Interface**: Hardware SPI (faster performance than bitbang)
231
- **Connections**: 
232
  - SPI MOSI (GPIO 10)
233
  - SPI SCLK (GPIO 11)
234
  - SPI CE0 (GPIO 8)
235
  - 5V power supply
236
  - Ground connection
237
- **Power Supply**: External 5V power supply recommended for full brightness operation
238

239
## Performance Characteristics
240

241
- **Refresh Rate**: High refresh rate via SPI interface
242
- **Update Speed**: Can handle real-time animations and video
243
- **Memory Usage**: Efficient buffering for 16×16 pixel array
244
- **Heat Generation**: Minimal heat at moderate brightness levels
245

246
## Error Handling
247

248
The device may raise the following exceptions:
249

250
- `luma.core.error.DeviceDisplayModeError`: Invalid image dimensions (must be 16×16) or unsupported mode
251
- `RuntimeError`: SPI interface initialization failures or communication errors
252
- `AssertionError`: Invalid parameter values (brightness out of range, invalid rotation)
253
- `OSError`: Hardware access issues or permissions problems
254

255
## Compatibility Notes
256

257
- **HAT Compatibility**: Designed specifically for Raspberry Pi HAT interface
258
- **Pin Usage**: Uses SPI pins, may conflict with other SPI devices
259
- **Power Requirements**: May require external power supply for full brightness
260
- **Case Compatibility**: Standard HAT form factor fits most Pi cases with cutouts