Skip to main content
Version: Matrix OS 3.2

LED API

Preview notice​

The MatrixOS Python API is in preview and is subject to change; it may contain errors.

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.

MatrixOS.LED.SetBrightness​

def SetBrightness(brightness: int) -> None

Sets the brightness level of the LEDs.

Parameters:

  • brightness (int): Brightness level (0-255)

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

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)

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)

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)

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

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)

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

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)

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)

Comments