0
# Seven-Segment Display
1

2
Virtual seven-segment display device built on top of NeoPixel hardware for displaying text and numbers. This creates a classic seven-segment display appearance using RGB LEDs arranged in the traditional segment pattern.
3

4
## Capabilities
5

6
### Device Initialization
7

8
Creates a virtual seven-segment display using NeoPixel LEDs as the underlying hardware.
9

10
```python { .api }
11
class neosegment:
12
    def __init__(
13
        self,
14
        width,
15
        undefined="_",
16
        device=None,
17
        **kwargs
18
    ):
19
        """
20
        Initialize NeoSegment seven-segment display.
21
        
22
        Parameters:
23
        - width: Number of 7-segment elements (digits) cascaded horizontally
24
        - undefined: Default character for unrenderable characters (default: "_")
25
        - device: Underlying device instance (optional, defaults to ws2812/neopixel)
26
        - **kwargs: Additional parameters passed to parent classes
27
        """
28
```
29

30
### Text Display and Color Control
31

32
Controls text display and individual character coloring on the seven-segment display.
33

34
```python { .api }
35
@property
36
def text(self):
37
    """
38
    Get the currently displayed text.
39
    
40
    Returns:
41
    - str: Current text content on the display
42
    """
43

44
@text.setter
45
def text(self, value):
46
    """
47
    Set text to display on the seven-segment display.
48
    
49
    Parameters:
50
    - value: Text string to display (characters not in mapping show as undefined char)
51
    """
52

53
@property
54
def color(self):
55
    """
56
    Get the color array for individual characters.
57
    
58
    Returns:
59
    - list: RGB color values for each character position
60
    """
61

62
@color.setter  
63
def color(self, value):
64
    """
65
    Set color for individual characters or all characters.
66
    
67
    Parameters:
68
    - value: Single RGB tuple for all chars, or list of RGB tuples for individual chars
69
             RGB values should be (red, green, blue) with 0-255 range
70
    """
71
```
72

73
### Segment Mapping
74

75
Handles character-to-segment pattern conversion for display rendering.
76

77
```python { .api }
78
def segment_mapper(self, text, notfound):
79
    """
80
    Map text characters to 7-segment display patterns.
81
    
82
    Parameters:
83
    - text: String to convert to segment patterns
84
    - notfound: Character to use for unmappable characters
85
    
86
    Returns:
87
    - Generator yielding segment bit patterns as integers
88
    """
89
```
90

91
## Usage Examples
92

93
### Basic Seven-Segment Display
94
```python
95
from luma.led_matrix.device import neosegment
96

97
# Create 4-digit seven-segment display
98
display = neosegment(width=4)
99

100
# Display numbers
101
display.text = "1234"
102

103
# Display text (limited character set)
104
display.text = "HELP"
105

106
# Handle overflow (raises OverflowError)
107
try:
108
    display.text = "TOOLONG"  # More than 4 characters
109
except OverflowError:
110
    display.text = "ERR"
111
```
112

113
### Colored Display
114
```python
115
from luma.led_matrix.device import neosegment
116

117
display = neosegment(width=4)
118

119
# Set all digits to red
120
display.text = "8888"
121
display.color = (255, 0, 0)
122

123
# Set individual digit colors
124
display.text = "1234"
125
display.color = [
126
    (255, 0, 0),    # Digit 1: Red
127
    (0, 255, 0),    # Digit 2: Green  
128
    (0, 0, 255),    # Digit 3: Blue
129
    (255, 255, 0)   # Digit 4: Yellow
130
]
131
```
132

133
### Custom Undefined Character
134
```python
135
from luma.led_matrix.device import neosegment
136

137
# Use different character for unmappable chars
138
display = neosegment(width=4, undefined="?")
139
display.text = "A@B#"  # @ and # will show as ?
140
```
141

142
### Clock Display
143
```python
144
import time
145
from luma.led_matrix.device import neosegment
146

147
# Create 4-digit display for time
148
clock = neosegment(width=4)
149

150
while True:
151
    # Get current time
152
    current_time = time.strftime("%H%M")
153
    clock.text = current_time
154
    
155
    # Alternate colors for hours and minutes
156
    clock.color = [
157
        (255, 0, 0),    # Hour tens: Red
158
        (255, 0, 0),    # Hour ones: Red
159
        (0, 255, 0),    # Minute tens: Green
160
        (0, 255, 0)     # Minute ones: Green
161
    ]
162
    
163
    time.sleep(1)
164
```
165

166
### Counter with Custom Device
167
```python
168
from luma.led_matrix.device import neosegment, neopixel
169

170
# Create custom underlying NeoPixel device
171
neopixel_device = neopixel(cascaded=28)  # 7 segments × 4 digits
172
display = neosegment(width=4, device=neopixel_device)
173

174
# Count from 0 to 9999
175
for i in range(10000):
176
    display.text = f"{i:04d}"  # Zero-padded 4 digits
177
    display.color = (0, 255, 255)  # Cyan
178
    time.sleep(0.1)
179
```
180

181
### Temperature Display
182
```python
183
import random
184
from luma.led_matrix.device import neosegment
185

186
temp_display = neosegment(width=4)
187

188
# Simulate temperature readings
189
for _ in range(100):
190
    # Generate temperature (e.g., 72.5°F)
191
    temp = random.uniform(65.0, 85.0)
192
    
193
    # Format for display (remove decimal point)
194
    temp_str = f"{temp:.1f}".replace(".", "")[:4]
195
    temp_display.text = temp_str.ljust(4)
196
    
197
    # Color based on temperature
198
    if temp < 70:
199
        color = (0, 0, 255)    # Blue for cold
200
    elif temp > 80:
201
        color = (255, 0, 0)    # Red for hot
202
    else:
203
        color = (0, 255, 0)    # Green for comfortable
204
    
205
    temp_display.color = color
206
    time.sleep(2)
207
```
208

209
## Supported Characters
210

211
The seven-segment display supports a limited character set including:
212

213
### Numbers
214
- `0-9`: Standard digits
215

216
### Letters  
217
- `A, B, C, D, E, F`: Hexadecimal letters
218
- `H, L, P, U`: Additional displayable letters
219
- `r, n, o`: Lowercase letters with reasonable representation
220

221
### Symbols
222
- `-`: Minus/dash (middle segment only)
223
- `_`: Underscore (bottom segment only)  
224
- `"`: Quotation marks (top segments)
225
- `'`: Apostrophe (single top segment)
226
- `°`: Degree symbol (top segments)
227

228
Characters not in the mapping will display as the `undefined` character (default: "_").
229

230
## Hardware Requirements
231

232
- **Underlying Device**: NeoPixel/WS2812 LEDs arranged in seven-segment pattern
233
- **LED Count**: 7 LEDs per digit × number of digits
234
- **Wiring**: LEDs must be wired in seven-segment pattern:
235
  ```
236
   AAA
237
  F   B
238
  F   B
239
   GGG
240
  E   C  
241
  E   C
242
   DDD
243
  ```
244
- **Power**: Same requirements as underlying NeoPixel device
245

246
## Error Handling
247

248
The device may raise the following exceptions:
249

250
- `OverflowError`: Text length exceeds display width (number of digits)
251
- `ValueError`: Invalid color specification (not RGB tuple or incorrect format)
252
- `RuntimeError`: Underlying NeoPixel device errors
253
- `AssertionError`: Invalid width or parameter values
254

255
## Integration with Segment Mappers
256

257
The neosegment device integrates with character mapping functions:
258

259
```python
260
from luma.led_matrix.segment_mapper import regular, dot_muncher
261

262
# The regular mapper is used by default
263
# dot_muncher handles decimal points by combining with previous character
264
```