LEDMatrix/docs/PLUGIN_CONFIGURATION_GUIDE.md

Plugin Configuration Guide

Overview

The LEDMatrix system uses a plugin-based architecture where each plugin manages its own configuration. This guide explains the configuration structure, how to configure plugins via the web interface, and advanced configuration options.

Quick Start

1. Install a plugin from the Plugin Store in the web interface
2. Navigate to the plugin's configuration tab (automatically created when installed)
3. Configure settings using the auto-generated form
4. Save configuration; the running display applies it without a restart

For detailed information, see the sections below.

Configuration Structure

Core System Configuration

The main configuration file (config/config.json) now contains only essential system settings:

{
    "web_display_autostart": true,
    "schedule": {
        "enabled": true,
        "start_time": "07:00",
        "end_time": "23:00"
    },
    "timezone": "America/Chicago",
    "location": {
        "city": "Dallas",
        "state": "Texas",
        "country": "US"
    },
    "display": {
        "hardware": {
            "rows": 32,
            "cols": 64,
            "chain_length": 2,
            "parallel": 1,
            "brightness": 90,
            "hardware_mapping": "adafruit-hat",
            "scan_mode": 0,
            "pwm_bits": 9,
            "pwm_dither_bits": 1,
            "pwm_lsb_nanoseconds": 130,
            "disable_hardware_pulsing": false,
            "inverse_colors": false,
            "show_refresh_rate": false,
            "limit_refresh_rate_hz": 100
        },
        "runtime": {
            "gpio_slowdown": 3
        },
        "display_durations": {
            "calendar": 30
        },
        "use_short_date_format": true
    },
    "calendar": {
        "enabled": false,
        "update_interval": 3600,
        "max_events": 5,
        "show_all_day": true,
        "date_format": "%m/%d",
        "time_format": "%I:%M %p"
    },
    "plugin_system": {
        "plugins_directory": "plugin-repos"
    }
}

Configuration Sections

1. System Settings

• web_display_autostart: Enable web interface auto-start
• schedule: Display schedule settings
• timezone: System timezone
• location: Default location for location-based plugins

2. Display Hardware

• hardware: LED matrix hardware configuration
• runtime: Runtime display settings
• display_durations: How long each display mode shows (in seconds)
• use_short_date_format: Use short date format

3. Core Components

• calendar: Calendar manager settings (core system component)

4. Plugin System

• plugin_system: Plugin system configuration
  • plugins_directory: Directory where plugins are stored (the only one the loader scans)
  • auto_discover, auto_load_enabled, development_mode may still appear in older configs; nothing reads them (see CONFIG_REFERENCE.md)

Plugin Configuration

Plugin Discovery

Plugins are automatically discovered from the plugin-repos directory. Each plugin should have:

• manifest.json: Plugin metadata and configuration schema
• manager.py: Plugin implementation
• requirements.txt: Plugin dependencies

Plugin Configuration in config.json

Plugins are configured by adding their plugin ID as a top-level key in the config:

{
    "weather": {
        "enabled": true,
        "api_key": "your_api_key",
        "update_interval": 1800,
        "units": "imperial"
    },
    "stocks": {
        "enabled": true,
        "symbols": ["AAPL", "GOOGL", "MSFT"],
        "update_interval": 600
    }
}

How often the core calls a plugin's update(): the plugin's get_update_interval() if it returns a number, else update_interval in the plugin's manifest.json, else update_interval in its config.json section as above, else 60 seconds. A config update_interval therefore only sets the scheduler's cadence for a plugin whose manifest does not; plugins that expose it in their config schema typically also honour it themselves inside update(). See PLUGIN_API_REFERENCE.md.

Plugin Display Durations

Add plugin display modes to the display_durations section:

{
    "display": {
        "display_durations": {
            "calendar": 30,
            "weather": 30,
            "weather_forecast": 30,
            "stocks": 30,
            "stock_news": 20
        }
    }
}

Migration from Old Configuration

Removed Sections

The following configuration sections have been removed as they are now handled by plugins:

• All sports manager configurations (NHL, NBA, NFL, etc.)
• Weather manager configuration
• Stock manager configuration
• News manager configuration
• Music manager configuration
• All other content manager configurations

What Remains

Only core system components remain in the main configuration:

• Display hardware settings
• Schedule settings
• Calendar manager (core component)
• Plugin system settings

Plugin Development

Plugin Structure

Each plugin should follow this structure:

plugin-repos/
└── my-plugin/
    ├── manifest.json
    ├── manager.py
    ├── requirements.txt
    └── README.md

Plugin Manifest

{
    "id": "my-plugin",
    "name": "My Plugin",
    "version": "1.0.0",
    "description": "Plugin description",
    "author": "Your Name",
    "entry_point": "manager.py",
    "class_name": "MyPlugin",
    "display_modes": ["my_plugin"]
}

The Plugin Store refuses a manifest that lacks any of id, name, class_name or display_modes (store_manager.py); the loader itself needs class_name. version is not required, but the store compares it with the registry's latest_version to offer updates, so set it. entry_point defaults to manager.py if omitted. The config schema is not named in the manifest: it is always the file config_schema.json in the plugin directory. The class_name value must match the actual class defined in the entry point file exactly (case-sensitive, no spaces); otherwise the loader fails with a PluginError ("Class ... not found in module") at load time.

Plugin Manager Class

from src.plugin_system.base_plugin import BasePlugin

class MyPlugin(BasePlugin):
    def __init__(self, plugin_id, config, display_manager, cache_manager, plugin_manager):
        super().__init__(plugin_id, config, display_manager, cache_manager, plugin_manager)
        # self.config, self.display_manager, self.cache_manager,
        # self.plugin_manager, self.logger, and self.enabled are
        # all set up by BasePlugin.__init__.

    def update(self):
        """Fetch/update data. Called based on update_interval."""
        pass

    def display(self, force_clear=False):
        """Render plugin content to the LED matrix."""
        pass
    
    # BasePlugin.get_display_duration() already returns
    # self.config['display_duration'] (default 15s); override it only to
    # vary the duration with the content.
    def get_display_duration(self):
        return self.config.get('display_duration', 30)

Dynamic Duration Configuration

Plugins that render multi-step content (scrolling leaderboards, tickers, etc.) can opt-in to dynamic durations so the display controller waits for a full cycle.

{
    "football-scoreboard": {
        "enabled": true,
        "dynamic_duration": {
            "enabled": true,
            "max_duration_seconds": 240
        }
    },
    "display": {
        "dynamic_duration": {
            "max_duration_seconds": 180
        }
    }
}

• Set dynamic_duration.enabled per plugin to toggle the behaviour.
• Optional dynamic_duration.max_duration_seconds on the plugin overrides the global cap (defined under display.dynamic_duration.max_duration_seconds, default 180s).
• Plugins should override supports_dynamic_duration(), is_cycle_complete(), and reset_cycle_state() (see BasePlugin) to control when a cycle completes.

Configuration Tabs

Each installed plugin automatically gets its own dedicated configuration tab in the web interface. This provides a clean, organized way to configure plugins.

Accessing Plugin Configuration

1. Navigate to the Plugin Manager tab to see all installed plugins
2. Click the Configure button on any plugin card, or
3. Click directly on the plugin's tab button in the navigation bar

Auto-Generated Forms

Configuration forms are automatically generated from each plugin's config_schema.json:

• Boolean → Toggle switch
• Number/Integer → Number input with min/max validation
• String → Text input with length constraints
• Array → Comma-separated input
• Enum → Dropdown menu

Configuration Features

• Type-safe inputs: Form inputs match JSON Schema types
• Default values: Fields show current values or schema defaults
• Real-time validation: Input constraints enforced (min, max, maxLength, etc.)
• Help text: Each field shows description from schema

For more details, see Plugin Configuration Tabs.

For information about how core properties (enabled, display_duration, live_priority) are handled, see Core Plugin Properties.

Schema Validation

The configuration system uses JSON Schema Draft-07 for validation:

• Pre-save validation: Invalid configurations are rejected before saving
• Automatic defaults: Default values extracted from schemas
• Error messages: Clear error messages show exactly what's wrong
• Reliable loading: Schema loading with caching and fallback paths
• Core properties handling: System-managed properties (enabled, display_duration, live_priority) are automatically handled - they don't need to be in plugin schemas and aren't validated as required fields

Schema Structure

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "default": true,
      "description": "Enable or disable this plugin"
    },
    "update_interval": {
      "type": "integer",
      "default": 3600,
      "minimum": 60,
      "maximum": 86400,
      "description": "Update interval in seconds"
    }
  }
}

Best Practices

1. Keep main config minimal: Only include core system settings
2. Use plugin-specific configs: Each plugin manages its own configuration
3. Document plugin requirements: Include clear documentation for each plugin
4. Version control: Keep plugin configurations in version control
5. Testing: Test plugins in emulator mode before hardware deployment
6. Use schemas: Always provide config_schema.json for your plugins
7. Sensible defaults: Ensure defaults work without additional configuration
8. Add descriptions: Help users understand each setting

Troubleshooting

Common Issues

1. Plugin not loading: Check plugin manifest and directory structure
2. Configuration errors: Validate plugin configuration against schema
3. Display issues: Check display durations and plugin display methods
4. Performance: Monitor plugin update intervals and resource usage
5. Form missing or wrong: Verify config_schema.json exists in the plugin directory and is valid JSON Schema
6. Settings not saving: Check validation errors and ensure all required fields are filled

Debug Mode

There is no config key for debug logging. Run the display with debug logging instead:

python3 run.py -d            # or: LEDMATRIX_DEBUG=true python3 run.py

See Also

• Plugin Development Guide - Complete development guide
• Plugin Configuration Tabs - Configuration tabs feature
• Plugin API Reference - API documentation
• Main README - Project overview