Skip to main content
Version: Latest 🚧

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 specified
  • CROSSFADE_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 modify
  • multiplier (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 set
  • layer (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 set
  • layer (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 with
  • layer (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 with
  • layer (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 ID
  • src (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