# 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

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

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

```python
# 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:**

```bash
# 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)

```python
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`):
   ```bash
   tail -f ~/infoscreen-dev/logs/simclient.log
   ```
   
   Look for:
   ```
   Event page_progress = 0
   Event auto_progress = true
   ```

2. **Inspect current_event.json directly**:
   ```bash
   cat ~/infoscreen-dev/src/current_event.json | jq
   ```
   
   All scheduler fields should be present in the output.

3. **Test with MQTT message**:
   ```bash
   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