Wall Display Mode
Relevant source files
The following files were used as context for generating this wiki page:
Wall Display Mode identifies a device switched into an always-on dashboard configuration. This mode enables specific kiosk-style behaviors, such as automatic screensaver activation, Night mode, and hardware-specific triggers like camera-based wake.
Unlike standard devices that browse the application as a typical website, a Wall Display operates as a dedicated home interface. It returns to a configured Default View when idle or upon waking.
Sources: GLOSSARY.md:104-107, README.md:46-49
Core Features and Behaviors
A Wall Display implements specialized states and hardware integrations to function as a persistent home appliance.
| Feature | Action |
|---|---|
| Always-on | Maintains the dashboard UI without the device entering system sleep. |
| Screensaver | Displays photos from Immich or a fallback folder when the device is idle. |
| Night Mode | Transitions to a black screen or dim clock during specific household hours. |
| Wake Triggers | Uses camera motion-wake or Screen Wake Lock to activate the display. |
| Default View | Automatically returns to a specific page (e.g., Today view) upon wake. |
Sources: GLOSSARY.md:104-118, README.md:46-49
Device State Transitions
The following diagram illustrates how a Wall Display moves between active, idle, and scheduled sleep states.
The diagram shows the transition from active dashboard viewing to automated idle states like Screensaver and Night Mode.
Sources: GLOSSARY.md:104-115
Default View Mechanics
Each device designated as a Wall Display can define its own starting point, known as the Default View. If a device-specific view is not set, it inherits the Household's global Default View.
- Today View: The primary dashboard page showing events for today/tomorrow, chores, and weather.
- Automatic Return: The system forces the Wall Display back to this view whenever it wakes from sleep or screensaver mode.
Sources: GLOSSARY.md:98-102, GLOSSARY.md:104-107
Real-time Updates
To remain accurate without manual refreshing, Wall Display interfaces utilize a Server-Sent Events (SSE) stream.
The sequence diagram details how the liveUpdates script maintains UI freshness via the /events/stream endpoint.
Sources: internal/web/calendar_templ.go:217-243, internal/app/app.go:103
Implementation Details
The client-side logic for real-time updates resides in the liveUpdates component. It uses the native EventSource API to listen for messages on /events/stream. When a message or a reconnect event occurs, the client fetches the current page via fetch() and replaces the #live DOM element with the new content.
Sources: internal/web/calendar_templ.go:217-243
Technical Requirements and Limitations
Specific Wall Display features depend on the presence of a secure context (HTTPS).
- HTTPS Requirement: Browsers only allow "Screen Wake Lock" and "Camera motion-wake" over HTTPS.
- Plain HTTP: If served over plain HTTP, the Wall Display functions only for browsing; hardware-level wake and lock features are disabled.
- Configuration: The
BASE_URLenvironment variable must be set to anhttps://address to enable these capabilities.
Sources: README.md:46-55
Screensaver and Night Mode
The Wall Display manages its visual state based on both activity and time of day.
- Screensaver Sources: The system prioritizes photos from an Immich integration. If Immich is unavailable or empty, it uses the "Fallback folder" located within the
DATA_DIR. - Night Mode Execution: During user-defined "Night mode" hours, the display switches from the screensaver to a black screen or a dim clock to minimize light pollution.
Sources: GLOSSARY.md:110-118