Initial import: clean snapshot from /home/olafn/infoscreen-dev (2025-10-25)
This commit is contained in:
RobbStarkAustria
202
SCHEDULER_FIELDS_SUPPORT.md
Normal file
202
SCHEDULER_FIELDS_SUPPORT.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user