Complete guide to all available configuration options for your screens.
🎯 Basic Configuration
"id" Required
Type: Integer
Description: Unique identifier for your screen. Used in URLs and file naming.
💡 Tip: Use numbers 2000+ for custom screens. Numbers 1000-1999 were reserved for legacy widgets.
"name" Required
Type: String
Description: Human-readable name displayed in the builder and logs.
Example:
"name": "Living Room Dashboard"
"template" Required
Type: String
Description: Path to the HTML template file, relative to app/templates/
Example:
"template": "screens/my_dashboard.html"
📝 Use Case: For multi-page screens, this is the default template. Individual pages override this with their own templates.
"stylesheet" Optional
Type: String
Description: Path to external CSS file, relative to app/templates/
Example:
"stylesheet": "screens/my_dashboard.css"
💡 Tip: CSS must be inlined in templates using {% include 'path.css' %} for Playwright to see it.
🖥️ Display Settings
"base_resolution" Required
Type: Array [width, height]
Description: The design resolution of your screen. Templates are designed for this size.
Examples:
"base_resolution": [320, 240] // Small e-ink display
"base_resolution": [800, 480] // Raspberry Pi touchscreen
"base_resolution": [640, 400] // Inky Frame 7-color
📝 Use Case: Design your HTML at this resolution, then devices can request any size - the screen will scale automatically.
"background_color" Optional
Type: Array [R, G, B]
Default: [255, 255, 255] (white)
Description: Background color for transparent areas of the rendered image.
Examples:
"background_color": [255, 255, 255] // White
"background_color": [0, 0, 0] // Black
"background_color": [240, 240, 240] // Light gray
💡 Tip: Set this to match your CSS body background to avoid color mismatches.
📄 Multi-Page Screens
"pages" Optional
Type: Object
Description: Defines multiple pages within a single screen. Each page has its own HTML template.
Structure:
"pages": {
"1": {
"name": "Welcome",
"template": "screens/screen_2002_page_1.html",
"description": "Welcome and overview page"
},
"2": {
"name": "Dashboard",
"template": "screens/screen_2002_page_2.html",
"description": "Main dashboard view"
}
}
📝 Use Cases:
- 📱 Multi-screen dashboards with navigation
- 🎮 Button-controlled interfaces (page 1 = button A, page 2 = button B)
- 📊 Different views of the same data (overview → details)
- ⏰ Time-based rotation (show different pages at different times)
💡 File Naming: Use predictable names like screen_{id}_page_{num}.html for easy management.
"navigation" Optional
Type: Object
Description: Controls how multi-page navigation works.
Structure:
"navigation": {
"default_page": "1",
"param_name": "page",
"show_nav_bar": true
}
Fields:
default_page - Which page to show when no page parameter is providedparam_name - URL parameter name for page selection (usually "page")show_nav_bar - Whether to display navigation UI (used by templates)
💡 URL Format: /screen/2002?page=2 shows page 2
🔤 Variables & Data
"variables" Optional
Type: Object
Description: Default values for template variables. Devices can override these via URL parameters.
Example:
"variables": {
"temperature": "22°C",
"humidity": "45%",
"location": "Living Room",
"sensor_value": 450,
"last_update": "10:30 AM"
}
In Templates:
<div>Temperature: {{ temperature|default('--') }}</div>
<div>Humidity: {{ humidity }}</div>
📝 Use Cases:
- 🌡️ Sensor data (temperature, humidity, CO2)
- 📊 Metrics and statistics
- 📍 Location or room names
- ⏰ Timestamps and status messages
- 🎨 Customization (colors, text, titles)
💡 Device Override: A device can send /screen/2002?temperature=25°C to override the default value.
Built-in Functions
Description: Special functions available in all templates.
Available Functions:
<!-- Current date/time -->
{{ now().strftime('%I:%M %p') }} → "02:30 PM"
{{ now().strftime('%B %d, %Y') }} → "February 10, 2026"
{{ now().strftime('%A') }} → "Monday"
<!-- Date formatting -->
{{ now().strftime('%Y-%m-%d') }} → "2026-02-10"
{{ now().strftime('%H:%M:%S') }} → "14:30:45"
📝 Use Cases: Clocks, timestamps, date displays, time-based greetings
📋 Complete Examples
Simple Single-Page Screen
{
"id": 2000,
"name": "Temperature Monitor",
"template": "screens/temp_monitor.html",
"stylesheet": "screens/temp_monitor.css",
"base_resolution": [320, 240],
"background_color": [255, 255, 255],
"variables": {
"temperature": "22°C",
"location": "Living Room"
}
}
📝 Best For: Simple displays, sensor dashboards, status screens
Multi-Page Dashboard
{
"id": 2002,
"name": "Multi-Page Dashboard",
"template": "screens/screen_2002_page_1.html",
"stylesheet": "screens/screen_2002.css",
"base_resolution": [800, 480],
"background_color": [255, 255, 255],
"pages": {
"1": {
"name": "Welcome",
"template": "screens/screen_2002_page_1.html",
"description": "Welcome and overview"
},
"2": {
"name": "System Monitor",
"template": "screens/screen_2002_page_2.html",
"description": "Live system stats"
},
"3": {
"name": "Statistics",
"template": "screens/screen_2002_page_3.html",
"description": "Charts and metrics"
}
},
"navigation": {
"default_page": "1",
"param_name": "page",
"show_nav_bar": true
},
"variables": {
"page1_title": "Welcome Dashboard",
"page2_title": "System Status",
"page3_title": "Analytics"
}
}
📝 Best For: Complex dashboards, button-controlled devices, tabbed interfaces
E-Ink Weather Display
{
"id": 2010,
"name": "Weather Station",
"template": "screens/weather.html",
"stylesheet": "screens/weather.css",
"base_resolution": [640, 400],
"background_color": [255, 255, 255],
"variables": {
"location": "San Francisco",
"temperature": "18°C",
"condition": "Partly Cloudy",
"humidity": "65%",
"wind": "12 km/h",
"forecast": ["☀️ 20°", "🌤️ 19°", "🌧️ 16°"]
}
}
📝 Best For: Weather displays, outdoor monitors, e-ink devices
💡 Device Request: /screen/2010?device_template=inky_frame_7&location=Seattle&temperature=15°C