LEDMatrix/docs/archive/ON_DEMAND_DISPLAY_API.md

On-Demand Display API

Overview

The On-Demand Display API allows manual control of what's shown on the LED matrix. Unlike the automatic rotation or live priority system, on-demand display is user-triggered - typically from the web interface with a "Show Now" button.

Use Cases

• 📺 "Show Weather Now" button in web UI
• 🏒 "Show Live Game" button for specific sports
• 📰 "Show Breaking News" button
• 🎵 "Show Currently Playing" button for music
• 🎮 Quick preview of any plugin without waiting for rotation

Priority Hierarchy

The display controller processes requests in this order:

1. On-Demand Display (HIGHEST) ← User explicitly requested
2. Live Priority (plugins with live content)
3. Normal Rotation (automatic cycling)

On-demand overrides everything, including live priority.

API Reference

DisplayController Methods

show_on_demand(mode, duration=None, pinned=False) -> bool

Display a specific mode immediately, interrupting normal rotation.

Parameters:

• mode (str): The display mode to show (e.g., 'weather', 'hockey_live')
• duration (float, optional): How long to show in seconds
  • None: Use mode's default display_duration from config
  • 0: Show indefinitely (until cleared)
  • > 0: Show for exactly this many seconds
• pinned (bool): If True, stays on this mode until manually cleared

Returns:

• True: Mode was found and activated
• False: Mode doesn't exist

Example:

# Show weather for 30 seconds then return to rotation
controller.show_on_demand('weather', duration=30)

# Show weather indefinitely
controller.show_on_demand('weather', duration=0)

# Pin to hockey live (stays until unpinned)
controller.show_on_demand('hockey_live', pinned=True)

# Use plugin's default duration
controller.show_on_demand('weather')  # Uses display_duration from config

clear_on_demand() -> None

Clear on-demand display and return to normal rotation.

Example:

controller.clear_on_demand()

is_on_demand_active() -> bool

Check if on-demand display is currently active.

Returns:

• True: On-demand mode is active
• False: Normal rotation or live priority

Example:

if controller.is_on_demand_active():
    print("User is viewing on-demand content")

get_on_demand_info() -> dict

Get detailed information about current on-demand display.

Returns:

{
    'active': True,              # Whether on-demand is active
    'mode': 'weather',           # Current mode being displayed
    'duration': 30.0,            # Total duration (None if indefinite)
    'elapsed': 12.5,             # Seconds elapsed
    'remaining': 17.5,           # Seconds remaining (None if indefinite)
    'pinned': False              # Whether pinned
}

# Or if not active:
{
    'active': False
}

Example:

info = controller.get_on_demand_info()
if info['active']:
    print(f"Showing {info['mode']}, {info['remaining']}s remaining")

Web Interface Integration

API Endpoint Example

# In web_interface/blueprints/api_v3.py

from flask import jsonify, request

@api_v3.route('/display/show', methods=['POST'])
def show_on_demand():
    """Show a specific plugin on-demand"""
    data = request.json
    mode = data.get('mode')
    duration = data.get('duration')  # Optional
    pinned = data.get('pinned', False)  # Optional
    
    # Get display controller instance
    controller = get_display_controller()
    
    success = controller.show_on_demand(mode, duration, pinned)
    
    if success:
        return jsonify({
            'success': True,
            'message': f'Showing {mode}',
            'info': controller.get_on_demand_info()
        })
    else:
        return jsonify({
            'success': False,
            'error': f'Mode {mode} not found'
        }), 404

@api_v3.route('/display/clear', methods=['POST'])
def clear_on_demand():
    """Clear on-demand display"""
    controller = get_display_controller()
    controller.clear_on_demand()
    
    return jsonify({
        'success': True,
        'message': 'On-demand display cleared'
    })

@api_v3.route('/display/on-demand-info', methods=['GET'])
def get_on_demand_info():
    """Get on-demand display status"""
    controller = get_display_controller()
    info = controller.get_on_demand_info()
    
    return jsonify(info)

Frontend Example (JavaScript)

// Show weather for 30 seconds
async function showWeather() {
    const response = await fetch('/api/v3/display/show', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            mode: 'weather',
            duration: 30
        })
    });
    
    const data = await response.json();
    if (data.success) {
        updateStatus(`Showing weather for ${data.info.duration}s`);
    }
}

// Pin to live hockey game
async function pinHockeyLive() {
    const response = await fetch('/api/v3/display/show', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            mode: 'hockey_live',
            pinned: true
        })
    });
    
    const data = await response.json();
    if (data.success) {
        updateStatus('Pinned to hockey live');
    }
}

// Clear on-demand
async function clearOnDemand() {
    const response = await fetch('/api/v3/display/clear', {
        method: 'POST'
    });
    
    const data = await response.json();
    if (data.success) {
        updateStatus('Returned to normal rotation');
    }
}

// Check status
async function checkOnDemandStatus() {
    const response = await fetch('/api/v3/display/on-demand-info');
    const info = await response.json();
    
    if (info.active) {
        updateStatus(`On-demand: ${info.mode} (${info.remaining}s remaining)`);
    } else {
        updateStatus('Normal rotation');
    }
}

UI Example (HTML)

<!-- Plugin controls -->
<div class="plugin-card">
    <h3>Weather</h3>
    <button onclick="showWeather()">Show Now (30s)</button>
    <button onclick="showWeatherIndefinite()">Show Until Cleared</button>
    <button onclick="pinWeather()">Pin Weather</button>
</div>

<!-- On-demand status display -->
<div id="on-demand-status" class="status-bar">
    <span id="status-text">Normal rotation</span>
    <button id="clear-btn" onclick="clearOnDemand()" style="display: none;">
        Clear On-Demand
    </button>
</div>

<script>
// Poll for status updates
setInterval(async () => {
    const info = await fetch('/api/v3/display/on-demand-info').then(r => r.json());
    
    const statusText = document.getElementById('status-text');
    const clearBtn = document.getElementById('clear-btn');
    
    if (info.active) {
        let text = `On-demand: ${info.mode}`;
        if (info.remaining) {
            text += ` (${Math.ceil(info.remaining)}s)`;
        } else if (info.pinned) {
            text += ' (pinned)';
        }
        statusText.textContent = text;
        clearBtn.style.display = 'inline-block';
    } else {
        statusText.textContent = 'Normal rotation';
        clearBtn.style.display = 'none';
    }
}, 1000);  // Update every second
</script>

Behavior Details

Duration Modes

Duration Value	Behavior	Use Case
None	Use plugin's display_duration from config	Default behavior
0	Show indefinitely until cleared	Quick preview
> 0	Show for exactly N seconds	Timed preview
pinned=True	Stay on mode until unpinned	Extended viewing

Auto-Clear Behavior

On-demand display automatically clears when:

• Duration expires (if set and > 0)
• User manually clears it
• System restarts

On-demand does NOT clear when:

• duration=0 (indefinite)
• pinned=True
• Live priority content appears (on-demand still has priority)

Interaction with Live Priority

# Scenario 1: On-demand overrides live priority
controller.show_on_demand('weather', duration=30)
# → Shows weather even if live game is happening

# Scenario 2: After on-demand expires, live priority takes over
controller.show_on_demand('weather', duration=10)
# → Shows weather for 10s
# → If live game exists, switches to live game
# → Otherwise returns to normal rotation

Use Case Examples

Example 1: Quick Weather Check

# User clicks "Show Weather" button
controller.show_on_demand('weather', duration=30)
# Shows weather for 30 seconds, then returns to rotation

Example 2: Monitor Live Game

# User clicks "Watch Live Game" button
controller.show_on_demand('hockey_live', pinned=True)
# Stays on live game until user clicks "Back to Rotation"

Example 3: Preview Plugin

# User clicks "Preview" in plugin settings
controller.show_on_demand('my-plugin', duration=15)
# Shows plugin for 15 seconds to test configuration

Example 4: Emergency Override

# Admin needs to show important message
controller.show_on_demand('text-display', pinned=True)
# Display stays on message until admin clears it

Testing

Manual Test from Python

# Access display controller
from src.display_controller import DisplayController
controller = DisplayController()  # Or get existing instance

# Test show on-demand
controller.show_on_demand('weather', duration=20)
print(controller.get_on_demand_info())

# Test clear
time.sleep(5)
controller.clear_on_demand()
print(controller.get_on_demand_info())

Test with Web API

# Show weather for 30 seconds
curl -X POST http://pi-ip:5001/api/v3/display/show \
  -H "Content-Type: application/json" \
  -d '{"mode": "weather", "duration": 30}'

# Check status
curl http://pi-ip:5001/api/v3/display/on-demand-info

# Clear on-demand
curl -X POST http://pi-ip:5001/api/v3/display/clear

Monitor Logs

sudo journalctl -u ledmatrix -f | grep -i "on-demand"

Expected output:

On-demand display activated: weather (duration: 30s, pinned: False)
On-demand display expired after 30.1s
Clearing on-demand display: weather

Best Practices

1. Provide Visual Feedback

Always show users when on-demand is active:

// Update UI to show on-demand status
function updateOnDemandUI(info) {
    const banner = document.getElementById('on-demand-banner');
    if (info.active) {
        banner.style.display = 'block';
        banner.textContent = `Showing: ${info.mode}`;
        if (info.remaining) {
            banner.textContent += ` (${Math.ceil(info.remaining)}s)`;
        }
    } else {
        banner.style.display = 'none';
    }
}

2. Default to Timed Display

Unless explicitly requested, use a duration:

# Good: Auto-clears after 30 seconds
controller.show_on_demand('weather', duration=30)

# Risky: Stays indefinitely
controller.show_on_demand('weather', duration=0)

3. Validate Modes

Check if mode exists before showing:

# Get available modes
available_modes = controller.available_modes + list(controller.plugin_modes.keys())

if mode in available_modes:
    controller.show_on_demand(mode, duration=30)
else:
    return jsonify({'error': 'Mode not found'}), 404

4. Handle Concurrent Requests

Last request wins:

# Request 1: Show weather
controller.show_on_demand('weather', duration=30)

# Request 2: Show hockey (overrides weather)
controller.show_on_demand('hockey_live', duration=20)
# Hockey now shows for 20s, weather request is forgotten

Troubleshooting

On-Demand Not Working

Check 1: Verify mode exists

info = controller.get_on_demand_info()
print(f"Active: {info['active']}, Mode: {info.get('mode')}")
print(f"Available modes: {controller.available_modes}")

Check 2: Check logs

sudo journalctl -u ledmatrix -f | grep "on-demand\|available modes"

On-Demand Not Clearing

Check if pinned:

info = controller.get_on_demand_info()
if info['pinned']:
    print("Mode is pinned - must clear manually")
    controller.clear_on_demand()

Check duration:

if info['duration'] == 0:
    print("Duration is indefinite - must clear manually")

Mode Shows But Looks Wrong

This is a display issue, not an on-demand issue. Check:

• Plugin's update() method is fetching data
• Plugin's display() method is rendering correctly
• Cache is not stale

Security Considerations

1. Authentication Required

Always require authentication for on-demand control:

@api_v3.route('/display/show', methods=['POST'])
@login_required  # Add authentication
def show_on_demand():
    # ... implementation

2. Rate Limiting

Prevent spam:

from flask_limiter import Limiter

limiter = Limiter(app, key_func=get_remote_address)

@api_v3.route('/display/show', methods=['POST'])
@limiter.limit("10 per minute")  # Max 10 requests per minute
def show_on_demand():
    # ... implementation

3. Input Validation

Sanitize mode names:

import re

def validate_mode(mode):
    # Only allow alphanumeric, underscore, hyphen
    if not re.match(r'^[a-zA-Z0-9_-]+$', mode):
        raise ValueError("Invalid mode name")
    return mode

Implementation Checklist

• Add API endpoint to web interface
• Add "Show Now" buttons to plugin UI
• Add on-demand status indicator
• Add "Clear" button when on-demand active
• Add authentication/authorization
• Add rate limiting
• Test with multiple plugins
• Test duration expiration
• Test pinned mode
• Document for end users

Future Enhancements

Consider adding:

1. Queue system - Queue multiple on-demand requests
2. Scheduled on-demand - Show mode at specific time
3. Recurring on-demand - Show every N minutes
4. Permission levels - Different users can show different modes
5. History tracking - Log who triggered what and when