infoscreen-dev/SCHEDULER_FIELDS_SUPPORT.md

Scheduler Fields Support

Overview

The infoscreen client automatically preserves all fields sent by the scheduler in the event database, including scheduler-specific metadata fields like page_progress and auto_progress.

How It Works

Event Storage (simclient.py)

When an event is received via MQTT on the infoscreen/events/{group_id} topic:

1. Full Preservation: The save_event_to_json() function stores the complete event data using json.dump() without filtering

2. No Data Loss: All fields from the scheduler are preserved, including:

   • page_progress - Current page/slide progress tracking
   • auto_progress - Auto-progression state
   • occurrence_of_id - Original event ID for recurring events
   • recurrence_rule - iCal recurrence rule (RRULE format)
   • recurrence_end - End date for recurring events
   • Any other scheduler-specific fields

3. Debug Logging: When LOG_LEVEL=DEBUG, the system logs the presence of page_progress and auto_progress fields

Event Processing (display_manager.py)

The Display Manager:

• Uses scheduler-specific fields to control presentation behavior:
  • page_progress: Controls Impressive's --page-progress option (overall progress bar)
  • auto_progress: Controls Impressive's --auto-progress option (per-page countdown)
• Other scheduler-specific fields are preserved but not actively used by display logic

Example Event with Scheduler Fields

{
  "id": 57,
  "occurrence_of_id": 57,
  "group_id": 2,
  "title": "2. Wiederholung",
  "start": "2025-10-19T05:00:00+00:00",
  "end": "2025-10-19T05:30:00+00:00",
  "recurrence_rule": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR,SA,SU;UNTIL=20251101T225959Z",
  "recurrence_end": "2025-11-01T22:59:59",
  "page_progress": true,
  "auto_progress": true,
  "presentation": {
    "type": "slideshow",
    "auto_advance": true,
    "slide_interval": 10,
    "files": [
      {
        "name": "slides.pdf",
        "url": "http://server:8000/api/files/slides.pdf",
        "checksum": null,
        "size": null
      }
    ]
  }
}

Implementation Details

Storage Function (simclient.py)

def save_event_to_json(event_data):
    """Speichert eine Event-Nachricht in der Datei current_event.json
    
    This function preserves ALL fields from the incoming event data,
    including scheduler-specific fields like:
    - page_progress: Current page/slide progress tracking
    - auto_progress: Auto-progression state
    - And any other fields sent by the scheduler
    """

Display Manager Implementation (display_manager.py)

The Display Manager reads page_progress and auto_progress fields and translates them to Impressive command-line options:

# In start_presentation() method:

# Get scheduler-specific progress display settings
page_progress = event.get('page_progress', False)  # Show overall progress bar
auto_progress = event.get('auto_progress', False)  # Show per-page auto-advance progress

# Later, when building Impressive command:
if page_progress:
  cmd.append('--page-progress')
  logging.info("Page progress bar enabled (shows overall position in presentation)")

if auto_progress:
  cmd.append('--auto-progress')
  logging.info("Auto-progress bar enabled (shows per-page countdown during auto-advance)")

Impressive Command Line Options

Event Field	Impressive Option	Short Form	Description
page_progress: true	--page-progress	-q	Shows a progress bar at the bottom indicating position in presentation
auto_progress: true	--auto-progress	-k	Shows a countdown progress bar for each page during auto-advance

Example Commands:

# With page progress only
impressive --fullscreen --auto 10 --wrap --page-progress presentation.pdf

# With auto progress only
impressive --fullscreen --auto 10 --wrap --auto-progress presentation.pdf

# With both progress bars
impressive --fullscreen --auto 10 --wrap --page-progress --auto-progress presentation.pdf

Storage Function (simclient.py)

def save_event_to_json(event_data):
  """Speichert eine Event-Nachricht in der Datei current_event.json
    
  This function preserves ALL fields from the incoming event data,
  including scheduler-specific fields like:
  - page_progress: Show overall progress bar in presentation
  - auto_progress: Show per-page auto-advance countdown
  - And any other fields sent by the scheduler
  """
    try:
        json_path = os.path.join(os.path.dirname(__file__), "current_event.json")
        with open(json_path, "w", encoding="utf-8") as f:
            json.dump(event_data, f, ensure_ascii=False, indent=2)
        logging.info(f"Event-Nachricht in {json_path} gespeichert")
        
        # Log if scheduler-specific fields are present (DEBUG level)
        if isinstance(event_data, list):
            for idx, event in enumerate(event_data):
                if isinstance(event, dict):
                    if 'page_progress' in event:
                        logging.debug(f"Event {idx}: page_progress = {event['page_progress']}")
                    if 'auto_progress' in event:
                        logging.debug(f"Event {idx}: auto_progress = {event['auto_progress']}")
        elif isinstance(event_data, dict):
            if 'page_progress' in event_data:
                logging.debug(f"Event page_progress = {event_data['page_progress']}")
            if 'auto_progress' in event_data:
                logging.debug(f"Event auto_progress = {event_data['auto_progress']}")
    except Exception as e:
        logging.error(f"Fehler beim Speichern der Event-Nachricht: {e}")

Verification

To verify that scheduler fields are being stored correctly:

1. Check the log file (with LOG_LEVEL=DEBUG):

   tail -f ~/infoscreen-dev/logs/simclient.log
   

   Look for:

   Event page_progress = 0
   Event auto_progress = true
   

2. Inspect current_event.json directly:

   cat ~/infoscreen-dev/src/current_event.json | jq
   

   All scheduler fields should be present in the output.

3. Test with MQTT message:

   mosquitto_pub -h localhost -t "infoscreen/events/2" -m '{
     "id": 99,
     "page_progress": 5,
     "auto_progress": true,
     "presentation": {
       "files": [{"name": "test.pdf"}],
       "auto_advance": true,
       "slide_interval": 10
     }
   }'
   

   Then check that page_progress and auto_progress appear in current_event.json.

Future Use

If the Display Manager needs to use these scheduler fields in the future (e.g., to resume presentations at a specific page), the fields are already available in the event data without any code changes needed in simclient.py.

Summary

✅ No changes required - The current implementation already preserves all scheduler fields
✅ Automatic preservation - Uses json.dump() which saves complete data structure
✅ Debug logging added - Logs presence of page_progress and auto_progress fields
✅ Documentation updated - README now documents scheduler-specific fields
✅ Future-proof - Any new scheduler fields will be automatically preserved