LEDMatrix/docs/PLUGIN_API_REFERENCE.md

Plugin API Reference

Complete API reference for plugin developers. This document describes all methods and properties available to plugins through the Display Manager, Cache Manager, and Plugin Manager.

Table of Contents

• BasePlugin
• Display Manager
• Cache Manager
• Plugin Manager

---

BasePlugin

All plugins must inherit from BasePlugin and implement the required methods. The base class provides access to managers and common functionality.

Available Properties

self.plugin_id          # Plugin identifier (string)
self.config             # Plugin configuration dictionary
self.display_manager    # DisplayManager instance
self.cache_manager      # CacheManager instance
self.plugin_manager     # PluginManager instance
self.logger             # Plugin-specific logger
self.enabled            # Boolean enabled status

Required Methods

update() -> None

Fetch/update data for this plugin. Called based on update_interval specified in the plugin's manifest.

Example:

def update(self):
    cache_key = f"{self.plugin_id}_data"
    cached = self.cache_manager.get(cache_key, max_age=3600)
    if cached:
        self.data = cached
        return
    
    self.data = self._fetch_from_api()
    self.cache_manager.set(cache_key, self.data)

display(force_clear: bool = False) -> None

Render this plugin's display. Called during display rotation or when explicitly requested.

Parameters:

• force_clear (bool): If True, clear display before rendering

Example:

def display(self, force_clear=False):
    if force_clear:
        self.display_manager.clear()
    
    self.display_manager.draw_text(
        "Hello, World!",
        x=5, y=15,
        color=(255, 255, 255)
    )
    
    self.display_manager.update_display()

Optional Methods

validate_config() -> bool

Validate plugin configuration. Override to implement custom validation.

Returns: True if config is valid, False otherwise

has_live_content() -> bool

Check if plugin currently has live content. Override for live priority plugins.

Returns: True if plugin has live content

get_live_modes() -> List[str]

Get list of display modes to show during live priority takeover.

Returns: List of mode names

cleanup() -> None

Clean up resources when plugin is unloaded. Override to close connections, stop threads, etc.

on_config_change(new_config: Dict[str, Any]) -> None

Called after plugin configuration is updated via web API.

on_enable() -> None

Called when plugin is enabled.

on_disable() -> None

Called when plugin is disabled.

get_display_duration() -> float

Get display duration for this plugin. Can be overridden for dynamic durations.

Returns: Duration in seconds

get_info() -> Dict[str, Any]

Return plugin info for display in web UI. Override to provide additional state information.

Dynamic-duration hooks

Plugins that render multi-step content (e.g. cycling through several games) can extend their display time until they've shown everything. To opt in, either set dynamic_duration.enabled: true in the plugin's config or override supports_dynamic_duration().

supports_dynamic_duration() -> bool

Return True if this plugin should use dynamic durations. Default reads config["dynamic_duration"]["enabled"].

get_dynamic_duration_cap() -> Optional[float]

Maximum number of seconds the controller will keep this plugin on screen in dynamic mode. Default reads config["dynamic_duration"]["max_duration_seconds"].

is_cycle_complete() -> bool

Override this to return True only after the plugin has rendered all of its content for the current rotation. Default returns True immediately, which means a single display() call counts as a full cycle.

reset_cycle_state() -> None

Called by the controller before each new dynamic-duration session. Reset internal counters/iterators here.

Live priority hooks

Live priority lets a plugin temporarily take over the rotation when it has urgent content (live games, breaking news). Enable by setting live_priority: true in the plugin's config and overriding has_live_content().

has_live_priority() -> bool

Whether live priority is enabled in config (default reads config["live_priority"]).

has_live_content() -> bool

Override to return True when the plugin currently has urgent content. Default returns False.

get_live_modes() -> List[str]

List of display modes to show during a live takeover. Default returns the plugin's display_modes from its manifest.

Vegas scroll hooks

Vegas mode shows multiple plugins as a single continuous scroll instead of rotating one at a time. Plugins control how their content appears via these hooks. See ADVANCED_FEATURES.md for the user side of Vegas mode.

get_vegas_content() -> Optional[PIL.Image | List[PIL.Image] | None]

Return content to inject into the scroll. Multi-item plugins (sports, odds, news) should return a list of PIL Images so each item scrolls independently. Static plugins (clock, weather) can return a single image. Returning None falls back to capturing whatever display() produces.

get_vegas_content_type() -> str

'multi', 'static', or 'none'. Affects how Vegas mode treats the plugin. Default 'static'.

get_vegas_display_mode() -> VegasDisplayMode

Returns one of VegasDisplayMode.SCROLL, FIXED_SEGMENT, or STATIC. Read from config["vegas_mode"] or override directly.

get_supported_vegas_modes() -> List[VegasDisplayMode]

The set of Vegas modes this plugin can render. Used by the UI to populate the mode selector for this plugin.

get_vegas_segment_width() -> Optional[int]

For FIXED_SEGMENT plugins, the width in pixels of the segment they occupy in the scroll. None lets the controller pick a default.

The full source for BasePlugin lives in src/plugin_system/base_plugin.py. If a method here disagrees with the source, the source wins — please open an issue or PR to fix the doc.

---

Display Manager

The Display Manager handles all rendering operations on the LED matrix. Available as self.display_manager in plugins.

Properties

display_manager.width    # Display width in pixels (int)
display_manager.height    # Display height in pixels (int)

Core Methods

clear() -> None

Clear the display completely. Creates a new black image.

Note: Does not call update_display() automatically. Call update_display() after drawing new content.

Example:

self.display_manager.clear()
# Draw new content...
self.display_manager.update_display()

update_display() -> None

Update the physical display using double buffering. Call this after drawing all content.

Example:

self.display_manager.draw_text("Hello", x=10, y=10)
self.display_manager.update_display()  # Actually show on display

Text Rendering

draw_text(text: str, x: int = None, y: int = None, color: tuple = (255, 255, 255), small_font: bool = False, font: ImageFont = None, centered: bool = False) -> None

Draw text on the canvas.

Parameters:

• text (str): Text to display
• x (int, optional): X position. If None, text is centered horizontally. If centered=True, x is treated as center point.
• y (int, optional): Y position (default: 0, top of display)
• color (tuple): RGB color tuple (default: white)
• small_font (bool): Use small font if True
• font (ImageFont, optional): Custom font object (overrides small_font)
• centered (bool): If True, x is treated as center point; if False, x is left edge

Example:

# Centered text
self.display_manager.draw_text("Hello", color=(255, 255, 0))

# Left-aligned at specific position
self.display_manager.draw_text("World", x=10, y=20, color=(0, 255, 0))

# Centered at specific x position
self.display_manager.draw_text("Center", x=64, y=16, centered=True)

get_text_width(text: str, font) -> int

Get the width of text when rendered with the given font.

Parameters:

• text (str): Text to measure
• font: Font object (ImageFont or freetype.Face)

Returns: Width in pixels

Example:

width = self.display_manager.get_text_width("Hello", self.display_manager.regular_font)
x = (self.display_manager.width - width) // 2  # Center text

get_font_height(font) -> int

Get the height of the given font for line spacing purposes.

Parameters:

• font: Font object (ImageFont or freetype.Face)

Returns: Height in pixels

Example:

font_height = self.display_manager.get_font_height(self.display_manager.regular_font)
y = 10 + font_height  # Position next line

format_date_with_ordinal(dt: datetime) -> str

Format a datetime object into 'Mon Aug 30th' style with ordinal suffix.

Parameters:

• dt: datetime object

Returns: Formatted date string

Example:

from datetime import datetime
date_str = self.display_manager.format_date_with_ordinal(datetime.now())
# Returns: "Jan 15th"

Image Rendering

The display manager doesn't provide a dedicated draw_image() method. Instead, plugins paste directly onto the underlying PIL Image (display_manager.image), then call update_display() to push the buffer to the matrix.

from PIL import Image

logo = Image.open("assets/logo.png").convert("RGB")
self.display_manager.image.paste(logo, (10, 10))
self.display_manager.update_display()

For transparency support, paste using a mask:

icon = Image.open("assets/icon.png").convert("RGBA")
self.display_manager.image.paste(icon, (5, 5), icon)
self.display_manager.update_display()

This is the same pattern the bundled scoreboard base classes (src/base_classes/baseball.py, basketball.py, football.py, hockey.py) use, so it's the canonical way to render arbitrary images.

Weather Icons

draw_weather_icon(condition: str, x: int, y: int, size: int = 16) -> None

Draw a weather icon based on the condition string.

Parameters:

• condition (str): Weather condition (e.g., "clear", "cloudy", "rain", "snow", "storm")
• x (int): X position
• y (int): Y position
• size (int): Icon size in pixels (default: 16)

Supported Conditions:

• "clear", "sunny" → Sun icon
• "clouds", "cloudy", "partly cloudy" → Cloud icon
• "rain", "drizzle", "shower" → Rain icon
• "snow", "sleet", "hail" → Snow icon
• "thunderstorm", "storm" → Storm icon

Example:

self.display_manager.draw_weather_icon("rain", x=10, y=10, size=16)

draw_sun(x: int, y: int, size: int = 16) -> None

Draw a sun icon with rays.

Parameters:

• x (int): X position
• y (int): Y position
• size (int): Icon size (default: 16)

draw_cloud(x: int, y: int, size: int = 16, color: tuple = (200, 200, 200)) -> None

Draw a cloud icon.

Parameters:

• x (int): X position
• y (int): Y position
• size (int): Icon size (default: 16)
• color (tuple): RGB color (default: light gray)

draw_rain(x: int, y: int, size: int = 16) -> None

Draw rain icon with cloud and droplets.

draw_snow(x: int, y: int, size: int = 16) -> None

Draw snow icon with cloud and snowflakes.

draw_text_with_icons(text: str, icons: List[tuple] = None, x: int = None, y: int = None, color: tuple = (255, 255, 255)) -> None

Draw text with weather icons at specified positions.

Parameters:

• text (str): Text to display
• icons (List[tuple], optional): List of (icon_type, x, y) tuples
• x (int, optional): X position for text
• y (int, optional): Y position for text
• color (tuple): Text color

Note: Automatically calls update_display() after drawing.

Example:

icons = [
    ("sun", 5, 5),
    ("cloud", 100, 5)
]
self.display_manager.draw_text_with_icons(
    "Weather: Sunny, Cloudy",
    icons=icons,
    x=10, y=20
)

Scrolling State Management

For plugins that implement scrolling content, use these methods to coordinate with the display system.

set_scrolling_state(is_scrolling: bool) -> None

Mark the display as scrolling or not scrolling. Call when scrolling starts/stops.

Parameters:

• is_scrolling (bool): True if currently scrolling, False otherwise

Example:

def display(self, force_clear=False):
    self.display_manager.set_scrolling_state(True)
    # Scroll content...
    self.display_manager.set_scrolling_state(False)

is_currently_scrolling() -> bool

Check if the display is currently in a scrolling state.

Returns: True if scrolling, False otherwise

defer_update(update_func: Callable, priority: int = 0) -> None

Defer an update function to be called when not scrolling. Useful for non-critical updates that should wait until scrolling completes.

Parameters:

• update_func: Function to call when not scrolling
• priority (int): Priority level (lower numbers = higher priority, default: 0)

Example:

def update(self):
    # Critical update - do immediately
    self.fetch_data()
    
    # Non-critical update - defer until not scrolling
    self.display_manager.defer_update(
        lambda: self.update_cache_metadata(),
        priority=1
    )

process_deferred_updates() -> None

Process any deferred updates if not currently scrolling. Called automatically by the display controller, but can be called manually if needed.

Note: Plugins typically don't need to call this directly.

get_scrolling_stats() -> dict

Get current scrolling statistics for debugging.

Returns: Dictionary with scrolling state information

Example:

stats = self.display_manager.get_scrolling_stats()
self.logger.debug(f"Scrolling: {stats['is_scrolling']}, Deferred: {stats['deferred_count']}")

Available Fonts

The Display Manager provides several pre-loaded fonts:

display_manager.regular_font      # Press Start 2P, size 8
display_manager.small_font        # Press Start 2P, size 8
display_manager.calendar_font     # 5x7 BDF font
display_manager.extra_small_font  # 4x6 TTF font, size 6
display_manager.bdf_5x7_font     # Alias for calendar_font

---

Cache Manager

The Cache Manager handles data caching to reduce API calls and improve performance. Available as self.cache_manager in plugins.

Basic Methods

get(key: str, max_age: int = 300) -> Optional[Dict[str, Any]]

Get data from cache if it exists and is not stale.

Parameters:

• key (str): Cache key
• max_age (int): Maximum age in seconds (default: 300)

Returns: Cached data dictionary, or None if not found or stale

Example:

cached = self.cache_manager.get("weather_data", max_age=600)
if cached:
    return cached

set(key: str, data: Dict[str, Any], ttl: Optional[int] = None) -> None

Store data in cache with current timestamp.

Parameters:

• key (str): Cache key
• data (Dict): Data to cache
• ttl (int, optional): Time-to-live in seconds (for compatibility)

Example:

self.cache_manager.set("weather_data", {
    "temp": 72,
    "condition": "sunny"
})

clear_cache(key: Optional[str] = None) -> None

Remove a specific cache entry, or all cache entries when called without arguments.

Parameters:

• key (str, optional): Cache key to delete. If omitted, every cached entry (memory + disk) is cleared.

Example:

# Drop one stale entry
self.cache_manager.clear_cache("weather_data")

# Nuke everything (rare — typically only used by maintenance tooling)
self.cache_manager.clear_cache()

Advanced Methods

get_cached_data(key: str, max_age: int = 300, memory_ttl: Optional[int] = None) -> Optional[Dict[str, Any]]

Get data from cache with separate memory and disk TTLs.

Parameters:

• key (str): Cache key
• max_age (int): TTL for persisted (on-disk) entry
• memory_ttl (int, optional): TTL for in-memory entry (defaults to max_age)

Returns: Cached data, or None if not found or stale

Example:

# Use memory cache for 60 seconds, disk cache for 1 hour
data = self.cache_manager.get_cached_data(
    "api_response",
    max_age=3600,
    memory_ttl=60
)

get_cached_data_with_strategy(key: str, data_type: str = 'default') -> Optional[Dict[str, Any]]

Get data using data-type-specific cache strategy. Automatically selects appropriate TTL based on data type.

Parameters:

• key (str): Cache key
• data_type (str): Data type for strategy selection (e.g., 'weather', 'sports_live', 'stocks')

Returns: Cached data, or None if not found or stale

Example:

# Automatically uses appropriate cache duration for weather data
weather = self.cache_manager.get_cached_data_with_strategy(
    "weather_current",
    data_type="weather"
)

get_with_auto_strategy(key: str) -> Optional[Dict[str, Any]]

Get data with automatic strategy detection from cache key.

Parameters:

• key (str): Cache key (strategy inferred from key name)

Returns: Cached data, or None if not found or stale

Example:

# Strategy automatically detected from key name
data = self.cache_manager.get_with_auto_strategy("nhl_live_scores")

get_background_cached_data(key: str, sport_key: Optional[str] = None) -> Optional[Dict[str, Any]]

Get background service cached data with sport-specific intervals.

Parameters:

• key (str): Cache key
• sport_key (str, optional): Sport identifier (e.g., 'nhl', 'nba') for live interval lookup

Returns: Cached data, or None if not found or stale

Example:

# Uses sport-specific live_update_interval from config
games = self.cache_manager.get_background_cached_data(
    "nhl_games",
    sport_key="nhl"
)

Strategy Methods

get_cache_strategy(data_type: str, sport_key: Optional[str] = None) -> Dict[str, Any]

Get cache strategy configuration for a data type.

Parameters:

• data_type (str): Data type (e.g., 'weather', 'sports_live', 'stocks')
• sport_key (str, optional): Sport identifier for sport-specific strategies

Returns: Dictionary with strategy configuration (max_age, memory_ttl, etc.)

Example:

strategy = self.cache_manager.get_cache_strategy("sports_live", sport_key="nhl")
max_age = strategy['max_age']  # Get configured max age

get_sport_live_interval(sport_key: str) -> int

Get the live_update_interval for a specific sport from config.

Parameters:

• sport_key (str): Sport identifier (e.g., 'nhl', 'nba')

Returns: Live update interval in seconds

Example:

interval = self.cache_manager.get_sport_live_interval("nhl")
# Returns configured live_update_interval for NHL

get_data_type_from_key(key: str) -> str

Extract data type from cache key to determine appropriate cache strategy.

Parameters:

• key (str): Cache key

Returns: Inferred data type string

get_sport_key_from_cache_key(key: str) -> Optional[str]

Extract sport key from cache key for sport-specific strategies.

Parameters:

• key (str): Cache key

Returns: Sport identifier, or None if not found

Utility Methods

clear_cache(key: Optional[str] = None) -> None

Clear cache for a specific key or all keys.

Parameters:

• key (str, optional): Specific key to clear. If None, clears all cache.

Example:

# Clear specific key
self.cache_manager.clear_cache("weather_data")

# Clear all cache
self.cache_manager.clear_cache()

get_cache_dir() -> Optional[str]

Get the cache directory path.

Returns: Cache directory path string, or None if not available

list_cache_files() -> List[Dict[str, Any]]

List all cache files with metadata.

Returns: List of dictionaries with cache file information (key, age, size, path, etc.)

Example:

files = self.cache_manager.list_cache_files()
for file_info in files:
    self.logger.info(f"Cache: {file_info['key']}, Age: {file_info['age_display']}")

Metrics Methods

get_cache_metrics() -> Dict[str, Any]

Get cache performance metrics.

Returns: Dictionary with cache statistics (hits, misses, hit rate, etc.)

Example:

metrics = self.cache_manager.get_cache_metrics()
self.logger.info(f"Cache hit rate: {metrics['hit_rate']:.2%}")

get_memory_cache_stats() -> Dict[str, Any]

Get memory cache statistics.

Returns: Dictionary with memory cache stats (size, max_size, etc.)

---

Plugin Manager

The Plugin Manager provides access to other plugins and plugin system information. Available as self.plugin_manager in plugins.

Methods

get_plugin(plugin_id: str) -> Optional[Any]

Get a plugin instance by ID.

Parameters:

• plugin_id (str): Plugin identifier

Returns: Plugin instance, or None if not found

Example:

weather_plugin = self.plugin_manager.get_plugin("weather")
if weather_plugin:
    # Access weather plugin data
    pass

get_all_plugins() -> Dict[str, Any]

Get all loaded plugin instances.

Returns: Dictionary mapping plugin_id to plugin instance

Example:

all_plugins = self.plugin_manager.get_all_plugins()
for plugin_id, plugin in all_plugins.items():
    self.logger.info(f"Plugin {plugin_id} is loaded")

get_enabled_plugins() -> List[str]

Get list of enabled plugin IDs.

Returns: List of plugin identifier strings

get_plugin_info(plugin_id: str) -> Optional[Dict[str, Any]]

Get plugin information including manifest and runtime info.

Parameters:

• plugin_id (str): Plugin identifier

Returns: Dictionary with plugin information, or None if not found

Example:

info = self.plugin_manager.get_plugin_info("weather")
if info:
    self.logger.info(f"Plugin: {info['name']}, Version: {info.get('version')}")

get_all_plugin_info() -> List[Dict[str, Any]]

Get information for all plugins.

Returns: List of plugin information dictionaries

get_plugin_directory(plugin_id: str) -> Optional[str]

Get the directory path for a plugin.

Parameters:

• plugin_id (str): Plugin identifier

Returns: Directory path string, or None if not found

get_plugin_display_modes(plugin_id: str) -> List[str]

Get list of display modes for a plugin.

Parameters:

• plugin_id (str): Plugin identifier

Returns: List of display mode names

Example:

modes = self.plugin_manager.get_plugin_display_modes("football-scoreboard")
# Returns: ['nfl_live', 'nfl_recent', 'nfl_upcoming', ...]

Plugin Manifests

Access plugin manifests through self.plugin_manager.plugin_manifests:

# Get manifest for a plugin
manifest = self.plugin_manager.plugin_manifests.get(self.plugin_id, {})

# Access manifest fields
display_modes = manifest.get('display_modes', [])
version = manifest.get('version')

Inter-Plugin Communication

Plugins can communicate with each other through the Plugin Manager:

Example - Getting data from another plugin:

def update(self):
    # Get weather plugin
    weather_plugin = self.plugin_manager.get_plugin("weather")
    if weather_plugin and hasattr(weather_plugin, 'current_temp'):
        self.temp = weather_plugin.current_temp

Example - Checking if another plugin is enabled:

enabled_plugins = self.plugin_manager.get_enabled_plugins()
if "weather" in enabled_plugins:
    # Weather plugin is enabled
    pass

---

Best Practices

Caching

1. Use appropriate cache keys: Include plugin ID and data type in keys

   cache_key = f"{self.plugin_id}_weather_current"
   

2. Use cache strategies: Prefer get_cached_data_with_strategy() for automatic TTL selection

   data = self.cache_manager.get_cached_data_with_strategy(
       f"{self.plugin_id}_data",
       data_type="weather"
   )
   

3. Handle cache misses: Always check for None return values

   cached = self.cache_manager.get(key, max_age=3600)
   if not cached:
       cached = self._fetch_from_api()
       self.cache_manager.set(key, cached)
   

Display Rendering

1. Always call update_display(): After drawing content, call update_display()

   self.display_manager.draw_text("Hello", x=10, y=10)
   self.display_manager.update_display()  # Required!
   

2. Use clear() appropriately: Only clear when necessary (e.g., force_clear=True)

   def display(self, force_clear=False):
       if force_clear:
           self.display_manager.clear()
       # Draw content...
       self.display_manager.update_display()
   

3. Handle scrolling state: If your plugin scrolls, use scrolling state methods

   self.display_manager.set_scrolling_state(True)
   # Scroll content...
   self.display_manager.set_scrolling_state(False)
   

Error Handling

1. Log errors appropriately: Use self.logger for plugin-specific logging

   try:
       data = self._fetch_data()
   except Exception as e:
       self.logger.error(f"Failed to fetch data: {e}")
       return
   

2. Handle missing data gracefully: Provide fallback displays when data is unavailable

   if not self.data:
       self.display_manager.draw_text("No data available", x=10, y=16)
       self.display_manager.update_display()
       return
   

---

See Also

• BasePlugin Source - Base plugin implementation
• Display Manager Source - Display manager implementation
• Cache Manager Source - Cache manager implementation
• Plugin Manager Source - Plugin manager implementation
• Plugin Development Guide - Complete development guide
• Advanced Plugin Development - Advanced patterns and examples