Feature: Kiosk Mode (1/7) - Foundation: Settings Model & Utilities #4197

nstefanelli · 2026-01-09T18:33:10Z

Summary

Part 1 of 7 in the Kiosk Mode implementation series.

This PR adds the foundation types and utilities that subsequent Kiosk Mode PRs will build upon. No functional changes to the app yet - this just adds the building blocks.

Related Discussion: https://github.com/orgs/home-assistant/discussions/2403

What's Included

KioskSettings.swift (~750 lines)

Complete settings model for kiosk mode configuration:

Core settings (PIN, biometric auth, navigation lockdown)
Dashboard configuration (primary URL, rotation settings)
Screensaver options (modes, timeout, brightness)
Clock display options (style, date, 24-hour format)
Photo screensaver settings (source, interval, transitions)
Wake/sleep triggers (entities, schedules)
Camera popup settings
Audio/TTS settings
Status overlay configuration

All types are Codable for persistence and Equatable for change detection.

KioskConstants.swift (~200 lines)

Centralized constants:

Animation durations and curves
Notification names for kiosk events
Default values and limits

Utilities (~400 lines)

IconMapper: Converts MDI icons (e.g., mdi:thermometer) to SF Symbols
TouchFeedbackManager: Haptic and audio feedback for touch interactions
AnimationUtilities: Shared animation helpers

Changes

File	Lines	Description
KioskSettings.swift	+750	Settings model and enums
KioskConstants.swift	+200	Constants and notifications
IconMapper.swift	+165	MDI to SF Symbol mapping
TouchFeedbackManager.swift	+200	Haptic/audio feedback
AnimationUtilities.swift	+230	Animation helpers
project.pbxproj	modified	Added new files

Total: ~1,600 lines added

Test Plan

Project builds successfully
No compiler warnings in new files
Types are accessible from other modules

PR Series

Foundation (this PR) - Settings model, constants, utilities
Core Manager - KioskModeManager, WebViewController integration
Screensaver - Clock, photo, and custom URL screensavers
Navigation Lockdown - Edge protection, secret exit gesture
Security - PIN/FaceID, tamper detection
Commands - Notification command handlers
Camera & Settings UI - Camera popup, settings views

Part 1 of Kiosk Mode implementation. This PR adds the foundation for Kiosk Mode: ## KioskSettings.swift - Complete settings model with all configuration options - Codable for persistence - Includes enums for screensaver modes, clock styles, photo sources, etc. - Entity trigger configurations - Dashboard rotation settings ## KioskConstants.swift - Centralized constants for animations, timing, notifications - Notification names for kiosk events ## Utilities - IconMapper: Converts MDI icons to SF Symbols - TouchFeedbackManager: Haptic and audio feedback - AnimationUtilities: Shared animation helpers These types form the foundation that subsequent PRs will build upon.

Part 2 of Kiosk Mode implementation. Depends on PR home-assistant#4197. ## KioskModeManager (~970 lines) Central coordinator for all kiosk functionality: - Enable/disable kiosk mode - Screen state management (on, dimmed, screensaver) - Brightness control with day/night scheduling - Idle timer and activity tracking - Dashboard navigation - Entity trigger subscriptions - HA WebSocket integration ## Security (~760 lines) - SecurityManager: PIN and biometric authentication - SettingsManager: Settings persistence ## Dashboard (~360 lines) - DashboardManager: Dashboard rotation and scheduling ## Camera Detection (~320 lines) - CameraDetectionManager: Motion and presence detection using front camera ## App Launcher (~360 lines) - AppLauncherManager: Launch external apps, return handling ## WebViewController Integration (~565 lines) - WebViewController+Kiosk: Kiosk overlay management - Modified WebViewController: Made properties internal for kiosk access

Part 3 of Kiosk Mode implementation. Depends on PRs home-assistant#4197 and home-assistant#4198. Adds screensaver functionality with multiple display modes: Files added (~52K): - ClockScreensaverView.swift: Clock display with multiple styles (large, minimal, digital, analog) - CustomURLScreensaverView.swift: Display custom HA dashboard as screensaver - EntityStateProvider.swift: Fetches and formats entity states for display - PhotoManager.swift: Manages photo loading from device, iCloud, and HA media - PhotoScreensaverView.swift: Photo slideshow with transitions - ScreensaverViewController.swift: UIKit controller coordinating screensaver presentation Features: - Multiple screensaver modes: clock, photos, dim, blank, custom URL - Clock styles: large, minimal, digital, analog with entity display - Photo sources: device albums, iCloud, Home Assistant media - Pixel shift for burn-in prevention - Day/night brightness scheduling

Part 4 of Kiosk Mode implementation. Depends on PRs home-assistant#4197, home-assistant#4198, home-assistant#4199. Adds navigation lockdown and overlay UI components: Files added (~39K): - EdgeProtectionView.swift: Invisible edge barriers preventing swipe gestures - QuickActionsView.swift: Quick launch panel for third-party apps - SecretExitGestureView.swift: Hidden gesture sequence to exit kiosk mode - StatusOverlayView.swift: Connection status, battery, and time display Features: - Edge protection blocks iOS system gestures (Control Center, notifications) - Configurable secret tap pattern for secure kiosk exit - Quick actions panel with app shortcuts - Status bar overlay with connection indicator

Part 5 of Kiosk Mode implementation. Depends on PRs home-assistant#4197-home-assistant#4200. Files added (~51K): Security: - BatteryManager.swift: Battery monitoring, low battery alerts - CrashRecoveryManager.swift: Automatic crash recovery and restart - GuidedAccessManager.swift: iOS Guided Access integration - TamperDetectionManager.swift: Motion-based tamper detection Audio: - AmbientAudioDetector.swift: Ambient sound level monitoring for wake triggers - AudioManager.swift: Audio playback and TTS support Features: - Battery level monitoring with critical level alerts - Automatic crash recovery to restore kiosk state - Guided Access API integration for enterprise deployments - Motion-based tamper detection (device moved while in kiosk) - Ambient audio detection for sound-triggered wake - Text-to-speech announcements via notification commands

Part 6 of Kiosk Mode implementation. Depends on PRs home-assistant#4197-home-assistant#4201. Files added: - KioskCommandHandlers.swift (~500 lines): Handlers for all kiosk notification commands Supported commands (14 total): - command_screen_on: Wake screen - command_screen_off: Start screensaver - command_brightness: Set screen brightness - command_screensaver: Control screensaver mode - command_navigate: Navigate to URL/path - command_refresh: Reload current page - command_kiosk_mode: Enable/disable kiosk mode - command_volume: Set device volume - command_tts: Text-to-speech announcement - command_play_audio: Play audio file - command_launch_app: Launch third-party app - command_return: Return to HA app - command_show_camera: Show camera popup - command_dismiss_camera: Dismiss camera popup

Part 7 of Kiosk Mode implementation. Final PR. Depends on PRs home-assistant#4197-home-assistant#4202. Camera files added: - CameraMotionDetector.swift: Frame-by-frame motion detection - CameraOverlayView.swift: Camera popup UI with actions - CameraStreamViewController.swift: HLS stream player - PresenceDetector.swift: Vision framework person detection Settings UI files added: - KioskSettingsView.swift: Main kiosk settings page - ScreensaverConfigView.swift: Screensaver mode configuration - DashboardConfigurationView.swift: Dashboard selection - EntityTriggersView.swift: Wake trigger entity configuration - PhotoAlbumPickerView.swift: Album selection for photo screensaver AppLauncher files added: - QuickLaunchPanelView.swift: Quick launch panel UI Features: - Camera popup with doorbell integration - Action buttons (unlock door, dismiss, etc.) - Auto-dismiss after configurable timeout - Motion detection via frame differencing - Person/face detection via Vision framework - Complete kiosk settings UI

Copilot

Pull request overview

This PR establishes the foundation for Kiosk Mode functionality by introducing core data models, constants, and utility classes. It's the first of seven PRs that will implement a comprehensive kiosk mode feature for the Home Assistant iOS app.

Key Changes:

Comprehensive settings model with ~380 lines of configuration properties covering all kiosk mode aspects
Centralized constants for animations, timing, UI dimensions, and thresholds
Utility classes for icon mapping, touch feedback, and animations

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
KioskSettings.swift	Complete settings model with 50+ configuration properties, supporting types, and enums for kiosk mode configuration
KioskConstants.swift	Centralized constants for animations, timing, UI dimensions, motion detection, and accessibility labels
IconMapper.swift	Material Design Icons to SF Symbols mapping utility with 100+ icon conversions
TouchFeedbackManager.swift	Singleton manager for haptic and audio feedback with SwiftUI/UIKit integration
AnimationUtilities.swift	Pre-defined animations, transitions, view modifiers, and button styles for consistent UX
project.pbxproj	Xcode project configuration updates to include new Kiosk module files

Sources/App/Kiosk/KioskSettings.swift

Sources/App/Kiosk/Utilities/TouchFeedbackManager.swift

Sources/App/Kiosk/KioskSettings.swift

Sources/App/Kiosk/Utilities/TouchFeedbackManager.swift

Sources/App/Kiosk/KioskSettings.swift

Sources/App/Kiosk/Utilities/AnimationUtilities.swift

Sources/App/Kiosk/KioskSettings.swift

- Rename isEnabled to isKioskModeEnabled for clarity - Add documentation to TriggerAction and QuickActionType enums - Replace magic system sound IDs with documented SystemSound enum - Remove unused Shared import from TouchFeedbackManager

Simplify security by using only device-based authentication (Face ID, Touch ID, device passcode) to exit kiosk mode. This avoids storing sensitive PIN data in app settings. Custom PIN support can be added later with proper Keychain storage.

nstefanelli · 2026-01-09T19:54:19Z

All review feedback has been addressed:

Renamed isEnabled to isKioskModeEnabled for clarity
Removed PIN-based authentication in favor of device-level authentication (Face ID/Touch ID/Device Passcode)
Fixed iOS 15+ compatibility (replaced NavigationStack, ContentUnavailableView, etc.)
Added kiosk_mode/set WebSocket command support for HA 2026.1+
All Copilot review threads resolved

Ready for re-review. 🙏

bgoncal

This PR does not add functionality alone by itself, merging it and not merging the following PRs would mean code with no purpose is left behind. Please organize the PRs to add small pieces of the full functionlity starting with something that adds value alone first.

Also, when I tried to open in Xcode it mentioned wrong file references, I assumt the AI modified pxbproj manually but not correctly

home-assistant · 2026-01-12T09:17:00Z

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

home-assistant bot added the cla-signed label Jan 9, 2026

nstefanelli mentioned this pull request Jan 9, 2026

Feature: Kiosk Mode (2/7) - Core Manager & Integration #4198

Open

7 tasks

nstefanelli mentioned this pull request Jan 9, 2026

Feature: Kiosk Mode (3/7) - Screensaver Views #4199

Open

7 tasks

nstefanelli mentioned this pull request Jan 9, 2026

Feature: Kiosk Mode (4/7) - Navigation Lockdown & Overlays #4200

Open

7 tasks

nstefanelli mentioned this pull request Jan 9, 2026

Feature: Kiosk Mode (5/7) - Security Managers & Audio Detection #4201

Open

7 tasks

nstefanelli mentioned this pull request Jan 9, 2026

Feature: Kiosk Mode (6/7) - Notification Command Handlers #4202

Draft

6 tasks

nstefanelli mentioned this pull request Jan 9, 2026

Feature: Kiosk Mode (7/7) - Camera Popup & Settings UI #4203

Draft

8 tasks

bgoncal requested a review from Copilot January 9, 2026 18:52

Copilot started reviewing on behalf of bgoncal January 9, 2026 18:52 View session

Copilot AI reviewed Jan 9, 2026

View reviewed changes

nstefanelli added 2 commits January 9, 2026 14:09

Address Copilot review feedback

7577f0d

- Rename isEnabled to isKioskModeEnabled for clarity - Add documentation to TriggerAction and QuickActionType enums - Replace magic system sound IDs with documented SystemSound enum - Remove unused Shared import from TouchFeedbackManager

bgoncal requested changes Jan 12, 2026

View reviewed changes

home-assistant bot marked this pull request as draft January 12, 2026 09:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Feature: Kiosk Mode (1/7) - Foundation: Settings Model & Utilities #4197

Feature: Kiosk Mode (1/7) - Foundation: Settings Model & Utilities #4197

nstefanelli commented Jan 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nstefanelli commented Jan 9, 2026

Uh oh!

bgoncal left a comment

Uh oh!

home-assistant bot commented Jan 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Feature: Kiosk Mode (1/7) - Foundation: Settings Model & Utilities #4197

Are you sure you want to change the base?

Feature: Kiosk Mode (1/7) - Foundation: Settings Model & Utilities #4197

Conversation

nstefanelli commented Jan 9, 2026

Summary

What's Included

KioskSettings.swift (~750 lines)

KioskConstants.swift (~200 lines)

Utilities (~400 lines)

Changes

Test Plan

PR Series

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nstefanelli commented Jan 9, 2026

Uh oh!

bgoncal left a comment

Choose a reason for hiding this comment

Uh oh!

home-assistant bot commented Jan 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants