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:

```json
{
    "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](CONFIG_REFERENCE.md#plugin_system))

## 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:

```json
{
    "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_API_REFERENCE.md#get_update_interval---optionalfloat).

### Plugin Display Durations

Add plugin display modes to the `display_durations` section:

```json
{
    "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

```json
{
    "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_install.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

```python
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.

```json
{
    "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](PLUGIN_CONFIGURATION_TABS.md).

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

## 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

```json
{
  "$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:

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

## See Also

- [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md) - Complete development guide
- [Plugin Configuration Tabs](PLUGIN_CONFIGURATION_TABS.md) - Configuration tabs feature
- [Plugin API Reference](PLUGIN_API_REFERENCE.md) - API documentation
- [Main README](../README.md) - Project overview