0
# Constants and Utilities
1

2
Hardware register constants for MAX7219 chips and character-to-segment mapping utilities for seven-segment displays. These low-level components support the device implementations and text rendering capabilities.
3

4
## Capabilities
5

6
### MAX7219 Hardware Constants
7

8
Register address constants for direct MAX7219 chip communication and configuration.
9

10
```python { .api }
11
class max7219:
12
    """
13
    MAX7219 LED driver register addresses and constants.
14
    Used internally by the max7219 device class for hardware communication.
15
    """
16
    
17
    NOOP = 0x00         # No operation register
18
    DIGIT_0 = 0x01      # First digit register (digits 0-7: 0x01-0x08)
19
    DECODEMODE = 0x09   # Decode mode register (BCD decode control)
20
    INTENSITY = 0x0A    # Intensity register (LED brightness: 0x00-0x0F)
21
    SCANLIMIT = 0x0B    # Scan limit register (number of digits to display)
22
    SHUTDOWN = 0x0C     # Shutdown register (normal/shutdown mode)
23
    DISPLAYTEST = 0x0F  # Display test register (test mode on/off)
24
```
25

26
### Segment Mapping Functions
27

28
Character-to-segment pattern conversion functions for seven-segment displays.
29

30
```python { .api }
31
def regular(text, notfound="_"):
32
    """
33
    Map text characters to 7-segment display patterns using standard character set.
34
    
35
    Parameters:
36
    - text: String to convert to segment patterns
37
    - notfound: Character to use for unmappable characters (default: "_")
38
    
39
    Returns:
40
    - Generator yielding segment bit patterns as integers
41
    
42
    Yields:
43
    - int: 8-bit pattern where each bit represents a segment (MSB unused)
44
           Bit layout: 0GFEDCBA (A=top, B=top-right, C=bottom-right, 
45
           D=bottom, E=bottom-left, F=top-left, G=middle)
46
    """
47

48
def dot_muncher(text, notfound="_"):
49
    """
50
    Map text with decimal point handling for 7-segment displays.
51
    Combines dots with previous characters to save display positions.
52
    
53
    Parameters:
54
    - text: String to convert (dots after characters combine with previous char)
55
    - notfound: Character to use for unmappable characters (default: "_")
56
    
57
    Returns:
58
    - Generator yielding segment patterns with dot integration
59
    
60
    Yields:
61
    - int: 8-bit pattern with dot bit (MSB) for decimal point display
62
           Bit layout: DGFEDCBA (D=dot/decimal point, others same as regular)
63
    
64
    Example:
65
    - "12.34" becomes 3 patterns: "1", "2.", "3", "4" 
66
    - The "2." combines digit 2 with decimal point bit
67
    """
68
```
69

70
## Usage Examples
71

72
### Direct MAX7219 Register Access
73
```python
74
from luma.led_matrix.const import max7219 as max7219_const
75
from luma.core.interface.serial import spi, noop
76

77
# Low-level register access (normally handled by max7219 device class)
78
serial = spi(port=0, device=0, gpio=noop())
79

80
# Set intensity to maximum
81
serial.write([max7219_const.INTENSITY, 0x0F])
82

83
# Enable normal operation (exit shutdown)
84
serial.write([max7219_const.SHUTDOWN, 0x01])
85

86
# Set scan limit to display all 8 digits
87
serial.write([max7219_const.SCANLIMIT, 0x07])
88
```
89

90
### Character Mapping for Seven-Segment
91
```python
92
from luma.led_matrix.segment_mapper import regular, dot_muncher
93

94
# Basic character mapping
95
text = "HELLO"
96
patterns = list(regular(text))
97
print([f"0x{p:02X}" for p in patterns])
98
# Output: ['0x76', '0x79', '0x38', '0x38', '0x5C']
99

100
# Handle unmappable characters
101
text = "HI@"
102
patterns = list(regular(text, notfound="?"))
103
# @ maps to ?, which maps to 0x00 (no segments)
104

105
# Decimal point handling
106
text = "12.34"
107
regular_patterns = list(regular(text))
108
print(f"Regular: {len(regular_patterns)} patterns")  # 5 patterns
109

110
dot_patterns = list(dot_muncher(text))
111
print(f"Dot muncher: {len(dot_patterns)} patterns")  # 4 patterns
112
# Second pattern will have decimal point bit set
113
```
114

115
### Custom Seven-Segment Display
116
```python
117
from luma.led_matrix.segment_mapper import regular
118
from luma.led_matrix.device import neopixel
119
from luma.core.render import canvas
120

121
# Create custom segment display using mapping functions
122
def display_text_on_segments(device, text, color=(255, 255, 255)):
123
    """Display text using direct segment patterns."""
124
    patterns = list(regular(text))
125
    
126
    # Assume 7 LEDs per digit arranged as segments
127
    # This is a simplified example - real implementation would
128
    # need proper LED addressing for segment layout
129
    
130
    for digit_pos, pattern in enumerate(patterns):
131
        for segment in range(7):
132
            if pattern & (1 << segment):
133
                # Calculate LED position for this segment
134
                led_index = digit_pos * 7 + segment
135
                # Set LED color (implementation depends on device layout)
136
                # This would require custom canvas drawing or direct LED control
137

138
# Usage with neosegment device
139
device = neopixel(cascaded=28)  # 4 digits × 7 segments
140
display_text_on_segments(device, "TEST")
141
```
142

143
### Extending Character Set
144
```python
145
from luma.led_matrix.segment_mapper import _DIGITS
146

147
# View supported characters
148
print("Supported characters:")
149
for char, pattern in sorted(_DIGITS.items()):
150
    print(f"'{char}': 0x{pattern:02X}")
151

152
# The _DIGITS dictionary contains mappings like:
153
# '0': 0x3F, '1': 0x06, '2': 0x5B, '3': 0x4F, '4': 0x66
154
# 'A': 0x77, 'B': 0x7C, 'C': 0x39, 'D': 0x5E, 'E': 0x79, 'F': 0x71
155
# 'H': 0x76, 'L': 0x38, 'P': 0x73, 'U': 0x3E
156
# '-': 0x40, '_': 0x08, '"': 0x22, etc.
157
```
158

159
### Temperature Display with Decimal
160
```python
161
from luma.led_matrix.segment_mapper import dot_muncher
162
from luma.led_matrix.device import neosegment
163

164
display = neosegment(width=4)
165

166
# Display temperature like "72.5"
167
temp = 72.5
168
temp_text = f"{temp:.1f}"
169

170
# Use dot_muncher to handle decimal point efficiently
171
patterns = list(dot_muncher(temp_text))
172
print(f"Temperature '{temp_text}' uses {len(patterns)} digit positions")
173

174
# Display normally - neosegment handles the segment patterns internally
175
display.text = temp_text
176
```
177

178
## Character Set Reference
179

180
### Supported Characters
181

182
**Digits**: `0123456789`
183
**Letters**: `ABCDEFHLPU` (uppercase), `rnot` (lowercase representations)  
184
**Symbols**: `- _ " ' °` and various special characters
185

186
### Segment Bit Layout
187

188
Seven-segment displays use a 7-bit pattern (plus optional decimal point):
189

190
```
191
 AAA
192
F   B
193
F   B  
194
 GGG
195
E   C
196
E   C
197
 DDD   [DP]
198
```
199

200
Bit positions: `0GFEDCBA` (bit 7 unused in regular mapping, used for decimal in dot_muncher)
201

202
### Decimal Point Handling
203

204
- **regular()**: Treats '.' as separate character (uses one display position)
205
- **dot_muncher()**: Combines '.' with previous character (saves display positions)
206

207
Example with "12.34":
208
- **regular**: `['1', '2', '.', '3', '4']` → 5 positions
209
- **dot_muncher**: `['1', '2.', '3', '4']` → 4 positions
210

211
## Implementation Notes
212

213
- Constants are used internally by device classes for hardware communication
214
- Segment mappers support the neosegment virtual device
215
- Character set is optimized for readability on seven-segment displays
216
- Unmappable characters default to underscore ('_') pattern unless specified otherwise
217
- All functions return generators for memory efficiency with long text strings