0
# Utility Functions
1
2
Additional utility functions for color generation and MicroPython compatibility that enhance the CircuitPython API emulation.
3
4
## Capabilities
5
6
### Color Utilities (rainbowio)
7
8
Rainbow color generation utility for creating smooth color transitions, commonly used with NeoPixel LED strips and other RGB applications.
9
10
```python { .api }
11
def colorwheel(color_value: int) -> int:
12
"""
13
Generate rainbow colors from input value.
14
15
Creates a smooth color wheel where:
16
- 0 and 255 are red
17
- 85 is green
18
- 170 is blue
19
- Values between create smooth rainbow transitions
20
21
Parameters:
22
- color_value: Integer from 0-255 representing position on color wheel
23
24
Returns:
25
32-bit RGB color value in format 0xRRGGBB
26
27
Note: Values outside 0-255 range return black (0x000000)
28
"""
29
```
30
31
### MicroPython Compatibility (micropython)
32
33
Decorator functions that provide MicroPython compatibility for code that needs to run on both CircuitPython and MicroPython platforms.
34
35
```python { .api }
36
def const(x):
37
"""
38
Emulate MicroPython const decorator.
39
40
In MicroPython, this decorator optimizes constants at compile time.
41
In CPython/Blinka, this is a no-op that returns the value unchanged.
42
43
Parameters:
44
- x: Value to mark as constant
45
46
Returns:
47
The input value unchanged
48
"""
49
50
def native(f):
51
"""
52
Emulate MicroPython native decorator.
53
54
In MicroPython, this compiles functions to native code for performance.
55
In CPython/Blinka, this is a no-op that returns the function unchanged.
56
57
Parameters:
58
- f: Function to mark as native
59
60
Returns:
61
The input function unchanged
62
"""
63
64
def viper(f):
65
"""
66
MicroPython viper decorator - not supported.
67
68
Raises:
69
- SyntaxError: Always raised as viper code emitter is not supported
70
"""
71
72
def asm_thumb(f):
73
"""
74
MicroPython inline assembler decorator - not supported.
75
76
Raises:
77
- SyntaxError: Always raised as inline assembly is not supported
78
"""
79
```
80
81
## Usage Examples
82
83
### Rainbow Color Generation
84
85
```python
86
import rainbowio
87
88
# Generate rainbow colors for a color cycle
89
colors = []
90
for i in range(256):
91
color = rainbowio.colorwheel(i)
92
# Extract RGB components
93
red = (color >> 16) & 0xFF
94
green = (color >> 8) & 0xFF
95
blue = color & 0xFF
96
colors.append((red, green, blue))
97
98
# Use with NeoPixels
99
import neopixel_write
100
import board
101
102
# Create rainbow effect
103
pixels = bytearray(3 * 10) # 10 RGB pixels
104
for i in range(10):
105
color = rainbowio.colorwheel(i * 25) # Spread across color wheel
106
pixels[i*3] = (color >> 8) & 0xFF # Green
107
pixels[i*3+1] = (color >> 16) & 0xFF # Red
108
pixels[i*3+2] = color & 0xFF # Blue
109
110
neopixel_write.neopixel_write(board.D18, pixels)
111
```
112
113
### MicroPython Compatibility
114
115
```python
116
import micropython
117
118
# Define constants (optimized on MicroPython, no-op on CPython)
119
LED_PIN = micropython.const(18)
120
BLINK_DELAY = micropython.const(500)
121
122
# Native compilation hint (optimized on MicroPython, no-op on CPython)
123
@micropython.native
124
def fast_calculation(data):
125
result = 0
126
for value in data:
127
result += value * 2
128
return result
129
130
# Use in portable code
131
import board
132
import digitalio
133
import time
134
135
led = digitalio.DigitalInOut(getattr(board, f'D{LED_PIN}'))
136
led.direction = digitalio.Direction.OUTPUT
137
138
while True:
139
led.value = True
140
time.sleep(BLINK_DELAY / 1000)
141
led.value = False
142
time.sleep(BLINK_DELAY / 1000)
143
```
144
145
### Color Wheel Animation
146
147
```python
148
import rainbowio
149
import time
150
151
def rainbow_cycle(strip_length, delay=0.1):
152
"""Create a rainbow cycle animation."""
153
for offset in range(256):
154
colors = []
155
for i in range(strip_length):
156
# Calculate color for this pixel
157
color_pos = (i * 256 // strip_length + offset) % 256
158
color = rainbowio.colorwheel(color_pos)
159
colors.append(color)
160
161
# Here you would send colors to your LED strip
162
yield colors
163
time.sleep(delay)
164
165
# Use the animation
166
for frame in rainbow_cycle(30, 0.05):
167
# Send frame to LED strip
168
print(f"Frame: {[hex(c) for c in frame[:5]]}...") # Show first 5 colors
169
```
170
171
## Import Patterns
172
173
```python
174
# Import color utilities
175
import rainbowio
176
color = rainbowio.colorwheel(128)
177
178
# Import MicroPython compatibility
179
import micropython
180
CONSTANT_VALUE = micropython.const(42)
181
182
# Or import specific functions
183
from rainbowio import colorwheel
184
from micropython import const, native
185
186
@native
187
def optimized_function():
188
THRESHOLD = const(100)
189
return THRESHOLD * 2
190
```
191
192
## Platform Notes
193
194
### rainbowio
195
- Available on all platforms where Blinka is installed
196
- Returns 24-bit RGB values in 0xRRGGBB format
197
- Commonly used with NeoPixel strips and RGB LEDs
198
199
### micropython
200
- Decorator functions are no-ops on CPython but maintain compatibility
201
- `viper` and `asm_thumb` decorators raise SyntaxError as they're not supported
202
- Useful for writing code that works on both CircuitPython and MicroPython