olafn/infoscreen-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

align .env.template with .env

Browse Source 
stragety for client monitoring setup
This commit is contained in:
RobbStarkAustria
2026-03-11 11:40:45 +01:00
parent 2340e698a4
commit 1c445f4ba7
3 changed files with 856 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

162
README.md
View File

@@ -63,45 +63,40 @@ pip install -r src/requirements.txt
### 2. Configuration
Create `.env` file in project root:
Create `.env` file in project root (or copy from `.env.template`):
```bash
# Screenshot capture behavior
SCREENSHOT_ALWAYS=0 # Set to 1 for testing (forces capture even without active display)
# Environment
ENV=production
LOG_LEVEL=INFO
ENV=production # development | production (CEC disabled in development)
DEBUG_MODE=0 # 1 to enable debug mode
LOG_LEVEL=INFO # DEBUG | INFO | WARNING | ERROR
# MQTT Configuration
# Timing (seconds)
HEARTBEAT_INTERVAL=30
SCREENSHOT_INTERVAL=60 # How often simclient transmits screenshots
SCREENSHOT_CAPTURE_INTERVAL=60 # How often display_manager captures screenshots
DISPLAY_CHECK_INTERVAL=5
MQTT_BROKER=192.168.1.100 # Your MQTT broker IP/hostname
MQTT_PORT=1883
# Screenshot Configuration
SCREENSHOT_MAX_WIDTH=800 # Downscale to this width (preserves aspect)
SCREENSHOT_JPEG_QUALITY=70 # JPEG quality 1-95 (lower = smaller files)
SCREENSHOT_MAX_FILES=20 # Keep this many screenshots (rotation)
SCREENSHOT_ALWAYS=0 # Set to 1 to force capture even when no event active
# Timing (seconds)
HEARTBEAT_INTERVAL=30
SCREENSHOT_INTERVAL=60
DISPLAY_CHECK_INTERVAL=5
HEARTBEAT_INTERVAL=60 # How often client sends status updates
SCREENSHOT_INTERVAL=180 # How often simclient transmits screenshots
SCREENSHOT_CAPTURE_INTERVAL=180 # How often display_manager captures screenshots
DISPLAY_CHECK_INTERVAL=15 # How often display_manager checks for new events
# File/API Server (used to download presentation files)
# Defaults to the same host as MQTT_BROKER, port 8000, scheme http.
# If incoming event URLs use host 'server' (or are host-less), simclient rewrites them to this server.
FILE_SERVER_HOST= # optional; if empty, defaults to MQTT_BROKER
FILE_SERVER_PORT=8000 # default API port
# http or https
FILE_SERVER_SCHEME=http
# FILE_SERVER_BASE_URL= # optional full override, e.g., http://192.168.1.100:8000
# Defaults to MQTT_BROKER host with port 8000 and http scheme
FILE_SERVER_HOST= # Optional; if empty, defaults to MQTT_BROKER
FILE_SERVER_PORT=8000 # Default API port
FILE_SERVER_SCHEME=http # http or https
# FILE_SERVER_BASE_URL= # Optional full override, e.g., http://192.168.1.100:8000
# HDMI-CEC TV Control (optional)
CEC_ENABLED=true # Enable automatic TV power control (auto-disabled in development)
CEC_ENABLED=true # Enable automatic TV power control
CEC_DEVICE=0 # Target device (0 recommended for TV)
CEC_TURN_OFF_DELAY=30 # Seconds to wait before turning off TV
CEC_POWER_ON_WAIT=5 # Seconds to wait after power ON (for TV boot)
CEC_POWER_OFF_WAIT=5 # Seconds to wait after power OFF (increase for slower TVs)
CEC_POWER_OFF_WAIT=5 # Seconds to wait after power OFF
```
### 3. Start Services
@@ -321,35 +316,63 @@ Captures test screenshot for dashboard monitoring.
### Environment Variables
All configuration is done via `.env` file in the project root. Copy `.env.template` to `.env` and adjust values for your environment.
#### Environment
- `ENV` - `development` or `production`
- `DEBUG_MODE` - Enable debug output (1=on, 0=off)
- `LOG_LEVEL` - `DEBUG`, `INFO`, `WARNING`, `ERROR`
- `ENV` - Environment mode: `development` or `production`
- **Important:** CEC TV control is automatically disabled in `development` mode
- `DEBUG_MODE` - Enable debug output: `1` (on) or `0` (off)
- `LOG_LEVEL` - Logging verbosity: `DEBUG`, `INFO`, `WARNING`, or `ERROR`
#### MQTT
- `MQTT_BROKER` - Primary MQTT broker IP/hostname
- `MQTT_PORT` - MQTT port (default: 1883)
- `MQTT_BROKER_FALLBACKS` - Comma-separated fallback brokers
- `MQTT_USERNAME` - Optional authentication
- `MQTT_PASSWORD` - Optional authentication
#### MQTT Configuration
- `MQTT_BROKER` - **Required.** MQTT broker IP address or hostname
- `MQTT_PORT` - MQTT broker port (default: `1883`)
- `MQTT_USERNAME` - Optional. MQTT authentication username (if broker requires it)
- `MQTT_PASSWORD` - Optional. MQTT authentication password (if broker requires it)
#### Timing
- `HEARTBEAT_INTERVAL` - Status update frequency (seconds)
- `SCREENSHOT_INTERVAL` - Dashboard screenshot frequency (seconds)
- `DISPLAY_CHECK_INTERVAL` - Event check frequency (seconds)
#### Timing Configuration (seconds)
- `HEARTBEAT_INTERVAL` - How often client sends status updates to server (default: `60`)
- `SCREENSHOT_INTERVAL` - How often simclient transmits screenshots via MQTT (default: `180`)
- `SCREENSHOT_CAPTURE_INTERVAL` - How often display_manager captures screenshots (default: `180`)
- `DISPLAY_CHECK_INTERVAL` - How often display_manager checks for new events (default: `15`)
#### File/API Server
- `FILE_SERVER_HOST` - Host/IP of the file server; defaults to `MQTT_BROKER` when empty
- `FILE_SERVER_PORT` - Port of the file server (default: 8000)
- `FILE_SERVER_SCHEME` - `http` or `https` (default: http)
- `FILE_SERVER_BASE_URL` - Optional full override, e.g., `https://api.example.com:443`
#### Screenshot Configuration
- `SCREENSHOT_ALWAYS` - Force screenshot capture even when no display is active
- `0` - Only capture when presentation/video/web is active (recommended for production)
- `1` - Always capture screenshots (useful for testing)
#### File/API Server Configuration
These settings control how the client downloads presentation files and other content.
- `FILE_SERVER_HOST` - Optional. File server hostname/IP. Defaults to `MQTT_BROKER` if empty
- `FILE_SERVER_PORT` - File server port (default: `8000`)
- `FILE_SERVER_SCHEME` - Protocol: `http` or `https` (default: `http`)
- `FILE_SERVER_BASE_URL` - Optional. Full base URL override (e.g., `http://192.168.1.100:8000`)
- When set, this takes precedence over HOST/PORT/SCHEME settings
#### HDMI-CEC TV Control (Optional)
Automatic TV power management based on event scheduling.
- `CEC_ENABLED` - Enable automatic TV control: `true` or `false`
- **Note:** Automatically disabled when `ENV=development` to avoid TV cycling during testing
- `CEC_DEVICE` - Target CEC device address (recommended: `0` for TV)
- `CEC_TURN_OFF_DELAY` - Seconds to wait before turning off TV after last event ends (default: `30`)
- `CEC_POWER_ON_WAIT` - Seconds to wait after power ON command for TV to boot (default: `5`)
- `CEC_POWER_OFF_WAIT` - Seconds to wait after power OFF command (default: `5`, increase for slower TVs)
### File Server URL Resolution
- The MQTT client (`src/simclient.py`) downloads presentation files listed in events.
- If an event contains URLs with host `server` (e.g., `http://server:8000/...`) or a missing host, the client rewrites them to the configured file server.
- By default, the file server host is the same as `MQTT_BROKER`, with port `8000` and scheme `http`.
- You can override this behavior using the `.env` variables above; `FILE_SERVER_BASE_URL` takes precedence over the individual host/port/scheme.
- Tip: When editing `.env`, keep comments after a space and `#` so values stay clean.
The MQTT client ([src/simclient.py](src/simclient.py)) downloads presentation files and videos from the configured file server.
**URL Rewriting:**
- Event URLs using placeholder host `server` (e.g., `http://server:8000/...`) are automatically rewritten to the configured file server
- By default, file server = `MQTT_BROKER` host with port `8000` and `http` scheme
- Use `FILE_SERVER_BASE_URL` for complete override, or set individual HOST/PORT/SCHEME variables
**Best practices:**
- Keep inline comments in `.env` after a space and `#` to avoid parsing issues
- Match the scheme (`http`/`https`) to your actual server configuration
- For HTTPS or non-standard ports, explicitly set `FILE_SERVER_SCHEME` and `FILE_SERVER_PORT`
### MQTT Topics
@@ -677,11 +700,10 @@ The following notable changes were added after the previous release and are incl
- **Session detection**: Automatic Wayland vs X11 detection with appropriate tool selection
- **Wayland support**: `grim`, `gnome-screenshot`, `spectacle` (in order)
- **X11 support**: `scrot`, `import` (ImageMagick), `xwd`+`convert` (in order)
- **Image processing**: Client-side downscaling and JPEG compression for bandwidth optimization
- **File management**: Timestamped screenshots plus `latest.jpg` symlink, automatic rotation
- **Transmission**: Enhanced `simclient.py` to prefer `latest.jpg`, added detailed logging
- **Dashboard topic**: Structured JSON payload with screenshot, system info, and client status
- **Configuration**: New environment variables for capture interval, quality, max width, file rotation
- **Configuration**: New environment variables `SCREENSHOT_CAPTURE_INTERVAL`, `SCREENSHOT_INTERVAL`, `SCREENSHOT_ALWAYS`
- **Testing mode**: `SCREENSHOT_ALWAYS=1` forces capture even without active display
### Previous Changes (Oct 2025)
@@ -690,16 +712,15 @@ The following notable changes were added after the previous release and are incl
**Processing pipeline:**
1. Capture full-resolution screenshot to PNG
2. Downscale to configured max width (default 800px, preserves aspect ratio)
3. Convert to JPEG with configured quality (default 70)
4. Save timestamped file: `screenshot_YYYYMMDD_HHMMSS.jpg`
5. Create/update `latest.jpg` symlink for easy access
6. Rotate old screenshots (keeps max 20 by default)
2. Downscale and compress to JPEG (hardcoded settings in display_manager.py)
3. Save timestamped file: `screenshot_YYYYMMDD_HHMMSS.jpg`
4. Create/update `latest.jpg` symlink for easy access
5. Rotate old screenshots (automatic cleanup)
**Capture timing:**
- Only captures when a display process is active (presentation/video/web)
- Can be forced with `SCREENSHOT_ALWAYS=1` for testing
- Default interval: 60 seconds
- Interval configured via `SCREENSHOT_CAPTURE_INTERVAL` (default: 180 seconds)
### Screenshot Transmission (simclient.py)
@@ -734,38 +755,35 @@ infoscreen/{client_id}/dashboard
### Configuration
```bash
# Capture settings (display_manager.py)
SCREENSHOT_CAPTURE_INTERVAL=60 # Seconds between captures
SCREENSHOT_MAX_WIDTH=800 # Downscale width (0 = no downscaling)
SCREENSHOT_JPEG_QUALITY=70 # JPEG quality 1-95
SCREENSHOT_MAX_FILES=20 # Number to keep before rotation
SCREENSHOT_ALWAYS=0 # Force capture even without active event
Configuration is done via environment variables in `.env` file. See the "Environment Variables" section above for complete documentation.
# Transmission settings (simclient.py)
SCREENSHOT_INTERVAL=60 # Seconds between MQTT publishes
```
Key settings:
- `SCREENSHOT_CAPTURE_INTERVAL` - How often display_manager.py captures screenshots (default: 180 seconds)
- `SCREENSHOT_INTERVAL` - How often simclient.py transmits screenshots via MQTT (default: 180 seconds)
- `SCREENSHOT_ALWAYS` - Force capture even when no display is active (useful for testing, default: 0)
### Scalability Recommendations
**Small deployments (<10 clients):**
- Default settings work well
- `SCREENSHOT_CAPTURE_INTERVAL=30`, `SCREENSHOT_MAX_WIDTH=800`, `SCREENSHOT_JPEG_QUALITY=70`
- `SCREENSHOT_CAPTURE_INTERVAL=30-60`, `SCREENSHOT_INTERVAL=60`
**Medium deployments (10-50 clients):**
- Reduce capture frequency: `SCREENSHOT_CAPTURE_INTERVAL=60`
- Lower quality: `SCREENSHOT_JPEG_QUALITY=60-65`
- Reduce capture frequency: `SCREENSHOT_CAPTURE_INTERVAL=60-120`
- Reduce transmission frequency: `SCREENSHOT_INTERVAL=120-180`
- Ensure broker has adequate bandwidth
**Large deployments (50+ clients):**
- Further reduce frequency: `SCREENSHOT_CAPTURE_INTERVAL=120`
- Aggressive compression: `SCREENSHOT_JPEG_QUALITY=50-60`, `SCREENSHOT_MAX_WIDTH=640`
- Consider implementing hash-based deduplication (skip if unchanged)
- Further reduce frequency: `SCREENSHOT_CAPTURE_INTERVAL=180`, `SCREENSHOT_INTERVAL=180-300`
- Monitor MQTT broker load and consider retained message limits
- Consider staggering screenshot intervals across clients
**Very large deployments (200+ clients):**
- Consider HTTP storage + MQTT metadata pattern instead of base64-over-MQTT
- Implement screenshot upload to file server, publish only URL via MQTT
- Implement hash-based deduplication to skip identical screenshots
**Note:** Screenshot image processing (resize, compression quality) is currently hardcoded in [src/display_manager.py](src/display_manager.py). Future versions may expose these as environment variables.
### Troubleshooting