olafn/infoscreen-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
82f43f75ba5c56c3a90fbd154d9fe8e4b9c52efd
infoscreen-dev/README.md
RobbStarkAustria 82f43f75ba docs: refactor docs structure and tighten assistant instruction policy 
shrink root README into a landing page with a docs map and focused contributor guidance
add TV_POWER_RUNBOOK as the canonical TV power rollout and canary runbook
add CHANGELOG and move project history out of README-style docs
refactor src README into a developer-focused guide (architecture, runtime files, MQTT, debugging)
prune redundant older HDMI docs and keep a canonical HDMI_CEC_SETUP path
update copilot instructions to a high-signal policy format with strict anti-shadow-README design rules
align references across docs to current files, scripts, and TV power behavior
2026-04-01 10:01:58 +02:00

236 lines
7.1 KiB
Markdown
Raw Blame History

# Infoscreen Client
Digital signage client for Raspberry Pi that displays presentations, videos, and web content in kiosk mode. It is managed centrally via MQTT and includes HDMI-CEC TV control, screenshot-based dashboard monitoring, and process health reporting.
Dashboard screenshots can contain visible on-screen content. Keep that in mind when enabling or documenting remote monitoring.
## Key Features
- Server-side PPTX to PDF rendering; client displays PDFs with Impressive.
- Presentation auto-advance, loop mode, and progress indicators.
- Video playback with `python-vlc` when available and external VLC fallback.
- Web and WebUntis display in kiosk mode.
- HDMI-CEC TV power control with local fallback and MQTT-coordinated power intent.
- MQTT discovery, heartbeat, group assignment, and event delivery.
- Screenshot dashboard with Wayland/X11 capture tool fallbacks.
- Process health bridge between `display_manager.py` and `simclient.py`.
## Quick Start
### 1. Install Dependencies
```bash
cd ~/
git clone <repository-url> infoscreen-dev
cd infoscreen-dev
sudo apt-get update
sudo apt-get install -y \
python3 python3-pip python3-venv \
impressive \
chromium-browser vlc \
cec-utils \
scrot imagemagick
# For Wayland systems:
# sudo apt-get install grim gnome-screenshot
python3 -m venv venv
source venv/bin/activate
pip install -r src/requirements.txt
```
### 2. Configure `.env`
Copy `.env.template` to `.env` and set at least:
```bash
ENV=production
DEBUG_MODE=0
LOG_LEVEL=INFO
MQTT_BROKER=192.168.1.100
MQTT_PORT=1883
HEARTBEAT_INTERVAL=60
SCREENSHOT_INTERVAL=180
SCREENSHOT_CAPTURE_INTERVAL=180
DISPLAY_CHECK_INTERVAL=15
FILE_SERVER_HOST=
FILE_SERVER_PORT=8000
FILE_SERVER_SCHEME=http
CEC_ENABLED=true
CEC_DEVICE=0
CEC_TURN_OFF_DELAY=30
CEC_POWER_ON_WAIT=5
CEC_POWER_OFF_WAIT=5
POWER_CONTROL_MODE=local
```
Mode summary:
- `POWER_CONTROL_MODE=local`: local event-time CEC only.
- `POWER_CONTROL_MODE=hybrid`: prefer fresh MQTT intent, fallback to local timing.
- `POWER_CONTROL_MODE=mqtt`: MQTT intent authoritative, with safe fallback behavior.
### 3. Start Services
```bash
cd ~/infoscreen-dev/src
python3 simclient.py
```
In a second terminal:
```bash
cd ~/infoscreen-dev/src
python3 display_manager.py
```
Or use the helper script:
```bash
./scripts/start-display-manager.sh
```
## Runtime Model
The client runs as two cooperating processes:
- `src/simclient.py`: MQTT communication, discovery, heartbeats, event ingestion, dashboard publishing, power intent intake.
- `src/display_manager.py`: display orchestration, HDMI-CEC, screenshots, local runtime health state.
Important runtime files:
- `src/current_event.json`: active event from scheduler.
- `src/current_process_health.json`: process health bridge for dashboard and monitoring.
- `src/power_intent_state.json`: latest validated MQTT power intent.
- `src/power_state.json`: last applied power action telemetry.
- `src/screenshots/`: shared screenshot directory.
## Content Types
### Presentations
Presentations are rendered server-side to PDF and displayed with Impressive. Auto-advance, loop, page progress, and auto-progress are supported.
See [IMPRESSIVE_INTEGRATION.md](IMPRESSIVE_INTEGRATION.md) for full behavior, event examples, and troubleshooting.
### Videos
Video events support:
- `url`
- `autoplay`
- `loop`
- `volume`
The Display Manager prefers `python-vlc`; if unavailable it falls back to the external VLC binary.
### Web Pages
Web and WebUntis events are displayed in Chromium kiosk mode.
## TV Power Intent
Phase 1 TV power coordination uses the group topic:
- `infoscreen/groups/{group_id}/power/intent`
Key references:
- Frozen contract: [TV_POWER_INTENT_SERVER_CONTRACT_V1.md](TV_POWER_INTENT_SERVER_CONTRACT_V1.md)
- Rollout and canary testing: [TV_POWER_RUNBOOK.md](TV_POWER_RUNBOOK.md)
- Client implementation handoff: [TV_POWER_HANDOFF_CLIENT.md](TV_POWER_HANDOFF_CLIENT.md)
## Testing
Use the helper scripts in `scripts/` for focused tests:
- `./scripts/test-display-manager.sh`: event and process testing.
- `./scripts/test-impressive.sh`: single-play presentation.
- `./scripts/test-impressive-loop.sh`: looping presentation.
- `./scripts/test-mqtt.sh`: MQTT broker connectivity.
- `./scripts/test-screenshot.sh`: screenshot capture.
- `./scripts/test-hdmi-cec.sh`: HDMI-CEC diagnostics and runtime state inspection.
- `./scripts/test-power-intent.sh`: MQTT power intent publishing, rejection tests, and telemetry checks.
## Troubleshooting
Use the specialist docs instead of treating this file as the full troubleshooting manual:
- Presentation and Impressive issues: [IMPRESSIVE_INTEGRATION.md](IMPRESSIVE_INTEGRATION.md)
- HDMI-CEC setup and TV control: [HDMI_CEC_SETUP.md](HDMI_CEC_SETUP.md)
- Screenshot race condition and metadata sync: [SCREENSHOT_MQTT_FIX.md](SCREENSHOT_MQTT_FIX.md)
- Monitoring and dashboard behavior: [CLIENT_MONITORING_SETUP.md](CLIENT_MONITORING_SETUP.md)
- Developer-oriented MQTT/event details: [src/README.md](src/README.md)
Quick checks:
- Follow logs: `tail -f logs/display_manager.log src/simclient.log`
- Inspect screenshots: `ls -lh src/screenshots/`
- Inspect power state: `cat src/power_intent_state.json` and `cat src/power_state.json`
- Restart both services: `./scripts/restart-all.sh`
## Deployment
For production you typically run both `simclient.py` and `display_manager.py` via systemd or Docker.
- Container setup: [src/CONTAINER_TRANSITION.md](src/CONTAINER_TRANSITION.md)
- Production compose file: [src/docker-compose.production.yml](src/docker-compose.production.yml)
- Display manager architecture: [src/DISPLAY_MANAGER.md](src/DISPLAY_MANAGER.md)
If running directly on the host, ensure:
- the display session is available (`DISPLAY` / `XAUTHORITY` for X11),
- the screenshot tools for your session type are installed,
- `ENV=production` is set when you want HDMI-CEC active.
## Documentation Map
### Operator / Deployment
- [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
- [HDMI_CEC_SETUP.md](HDMI_CEC_SETUP.md)
- [TV_POWER_RUNBOOK.md](TV_POWER_RUNBOOK.md)
- [CLIENT_MONITORING_SETUP.md](CLIENT_MONITORING_SETUP.md)
- [CHANGELOG.md](CHANGELOG.md)
### Feature-Specific
- [IMPRESSIVE_INTEGRATION.md](IMPRESSIVE_INTEGRATION.md)
- [SCREENSHOT_MQTT_FIX.md](SCREENSHOT_MQTT_FIX.md)
- [SCHEDULER_FIELDS_SUPPORT.md](SCHEDULER_FIELDS_SUPPORT.md)
- [SERVER_VOLUME_CONTROL_SETUP.md](SERVER_VOLUME_CONTROL_SETUP.md)
### Development / Internal
- [src/README.md](src/README.md)
- [src/DISPLAY_MANAGER.md](src/DISPLAY_MANAGER.md)
- [src/IMPLEMENTATION_SUMMARY.md](src/IMPLEMENTATION_SUMMARY.md)
- [TV_POWER_COORDINATION_TASKLIST.md](TV_POWER_COORDINATION_TASKLIST.md)
- [TV_POWER_HANDOFF_SERVER.md](TV_POWER_HANDOFF_SERVER.md)
## Contributing
Before changing runtime behavior:
- test with the relevant helper scripts,
- verify logs stay clean,
- update the specialist doc for the feature you changed.
When editing AI assistant guidance files:
- keep `.github/copilot-instructions.md` policy-focused,
- follow its "Instruction File Design Rules" section,
- avoid turning it into a shadow README.
Recent project history is tracked in [CHANGELOG.md](CHANGELOG.md).
## License
[Add your license here]
Reference in New Issue View Git Blame Copy Permalink