LED API
Overview
The LED system in MatrixOS provides control over the 8x8 LED matrix with layer support, real-time updates, and cross-fade animations. The LED API is available as MatrixOS.LED and is imported by default.
For some LED functions, you can specify a layer ID. If you don't specify a layer ID, the API will use layer 255 (the topmost layer). Changes only take effect when you call Update().
For immediate updates, write to layer 0 (the active buffer). Changes render immediately unless paused with PauseUpdate(True). This is ideal for real-time effects but may cause flickering.
The Python LED API is implemented in Applications/Python/PikaPython/MatrixOS_LED.py with type hints in Applications/Python/PikaPython/_MatrixOS_LED.pyi.
Constants
The LED API uses the following predefined constants:
CURRENT_LAYER = 255- Refers to the current active layer when no layer is specifiedCROSSFADE_DURATION = 200- Default crossfade duration in milliseconds
MatrixOS.LED.NextBrightness
def NextBrightness() -> None
Cycles to the next predefined brightness level for the LEDs.
Example:
MatrixOS.LED.NextBrightness()
MatrixOS.LED.SetBrightness
def SetBrightness(brightness: int) -> None
Sets the brightness level of the LEDs.
Parameters:
brightness(int): Brightness level (0-255)
Example:
MatrixOS.LED.SetBrightness(128) # Set to 50% brightness
MatrixOS.LED.SetBrightnessMultiplier
def SetBrightnessMultiplier(partition_name: str, multiplier: float) -> bool
Applies a brightness multiplier to a specific LED partition.
Parameters:
partition_name(str): Name of the partition to modifymultiplier(float): Brightness multiplier
Returns:
bool: True if successful
Example:
MatrixOS.LED.SetBrightnessMultiplier("keypad", 0.8) # Set keypad brightness to 0.8x
MatrixOS.LED.SetColor
def SetColor(xy: Point, color: Color, layer: int = CURRENT_LAYER) -> None
Sets the color of a specific LED at coordinates (x, y).
Parameters:
xy(Point): LED coordinates (0-7 for both x and y)color(Color): Color to setlayer(int, optional): Layer ID to write to (defaults to CURRENT_LAYER)
Example:
point = Point(2, 3)
red = Color(255, 0, 0)
MatrixOS.LED.SetColor(point, red) # Set LED at (2,3) to red
MatrixOS.LED.SetColorByID
def SetColorByID(id: int, color: Color, layer: int = CURRENT_LAYER) -> None
Sets the color of an LED by its ID (0-63 for 8x8 matrix).
Parameters:
id(int): LED ID (0-63)color(Color): Color to setlayer(int, optional): Layer ID to write to (defaults to CURRENT_LAYER)
Example:
MatrixOS.LED.SetColorByID(0, Color(0, 255, 0)) # Set first LED to green
MatrixOS.LED.Fill
def Fill(color: Color, layer: int = CURRENT_LAYER) -> None
Fills all LEDs with the specified color.
Parameters:
color(Color): Color to fill withlayer(int, optional): Layer ID to write to (defaults to CURRENT_LAYER)
Example:
MatrixOS.LED.Fill(Color(0, 0, 255)) # Fill all LEDs with blue
MatrixOS.LED.FillPartition
def FillPartition(partition: str, color: Color, layer: int = CURRENT_LAYER) -> bool
Fills a specific LED partition with the specified color.
Parameters:
partition(str): Partition name (e.g., "keypad", "function")color(Color): Color to fill withlayer(int, optional): Layer ID to write to (defaults to CURRENT_LAYER)
Returns:
bool: True if successful
Example:
MatrixOS.LED.FillPartition("keypad", Color(255, 255, 0)) # Fill keypad with yellow
MatrixOS.LED.Update
def Update(layer: int = CURRENT_LAYER) -> None
Updates the specified layer, making changes visible on the device.
Parameters:
layer(int, optional): Layer ID to update (defaults to CURRENT_LAYER)
Example:
MatrixOS.LED.Update() # Update the top layer
MatrixOS.LED.CurrentLayer
def CurrentLayer() -> int
Returns the current active layer ID.
Returns:
int: Current layer ID
MatrixOS.LED.CreateLayer
def CreateLayer(crossfade: int = CROSSFADE_DURATION) -> int
Creates a new LED layer with optional crossfade animation.
Parameters:
crossfade(int, optional): Crossfade duration in milliseconds (defaults to CROSSFADE_DURATION)
Returns:
int: New layer ID
Example:
new_layer = MatrixOS.LED.CreateLayer(500) # Create layer with 500ms crossfade
MatrixOS.LED.CopyLayer
def CopyLayer(dest: int, src: int) -> None
Copies the contents of one layer to another.
Parameters:
dest(int): Destination layer IDsrc(int): Source layer ID
MatrixOS.LED.DestroyLayer
def DestroyLayer(crossfade: int = CROSSFADE_DURATION) -> bool
Destroys the current layer with optional crossfade animation.
Parameters:
crossfade(int, optional): Crossfade duration in milliseconds (defaults to CROSSFADE_DURATION)
Returns:
bool: True if successful
MatrixOS.LED.Fade
def Fade(crossfade: int = CROSSFADE_DURATION) -> None
Applies a fade effect with specified duration.
Parameters:
crossfade(int, optional): Fade duration in milliseconds (defaults to CROSSFADE_DURATION)
MatrixOS.LED.PauseUpdate
def PauseUpdate(pause: bool = True) -> None
Pauses or resumes LED updates.
Parameters:
pause(bool, optional): True to pause, False to resume (defaults to True)
Example:
MatrixOS.LED.PauseUpdate(True) # Pause updates
# Make multiple changes...
MatrixOS.LED.PauseUpdate(False) # Resume updates
MatrixOS.LED.GetLEDCount
def GetLEDCount() -> int
Returns the total number of LEDs on the device.
Returns:
int: Number of LEDs (typically 64 for 8x8 matrix)
Layer Management
Real-time Effects
For real-time effects like visualizers, write directly to layer 0:
# Real-time audio visualizer
for i in range(64):
MatrixOS.LED.SetColorByID(i, Color(intensity, 0, 0))
# No need to call Update() - changes are immediate
Smooth Transitions
For smooth transitions between states, use layers with crossfade:
# Create new layer with fade
new_layer = MatrixOS.LED.CreateLayer(1000) # 1 second crossfade
# Draw new content
MatrixOS.LED.Fill(Color(0, 255, 0))
MatrixOS.LED.Update()
Batch Updates
For multiple changes, update them then update:
MatrixOS.LED.PauseUpdate(True)
# Make multiple changes
for x in range(8):
for y in range(8):
MatrixOS.LED.SetColor(Point(x, y), Color(x*32, y*32, 0))
MatrixOS.LED.Update()
Comments