DOCSEARCHbyAlgolia
Submit Docs

FreeKiosk Documentation

repository·main·Indexed 19 days ago

https://github.com/rushb-fr/freekiosk

An open-source kiosk mode platform for Android 8.0+ tablets, providing a free alternative to Fully Kiosk Browser. It allows locking devices to specific web URLs or external apps with support for WebView, External App, Dashboard, and Media Player modes. Features include a REST API with over 40 endpoints, MQTT integration with Home Assistant auto-discovery, and headless provisioning via ADB. Supports production-grade lockdown through Android Device Owner mode.

Tokens
31.3K
Snippets
92
Records
129
Agent score
66%

What's inside FreeKiosk

  1. Overview of FreeKiosk REST API capabilities

    main

    The FreeKiosk REST API is designed for integration with smart home platforms like Home Assistant.

    FeatureDetails
    Default Port8080
    ProtocolHTTP (HTTPS planned)
    AuthenticationOptional API Key via X-Api-Key header
    FormatJSON responses
    NOTE

    Some features (like true screen off or reboot) require Device Owner mode. The HTTP server remains accessible even when the screen is off (v1.2.4+).

  2. Overview of FreeKiosk capabilities and integrations

    main

    FreeKiosk is an open-source kiosk platform for Android tablets (Android 8.0+) that provides several modes of operation and integration points:

    Kiosk Modes

    • WebView: Displays a web URL.
    • External App: Locks the device to a specific installed application.
    • Dashboard/Media: Advanced modes for multi-app or media workflows.

    Integrations & Automation

    • REST API: Over 40+ endpoints for remote device control.
    • MQTT: Supports Home Assistant discovery for smart home integrations.
    • ADB Provisioning: Headless configuration and scripting for mass rollouts.

    Technical Specifications

    • Tech Stack: React Native, TypeScript, and Kotlin native modules.
    • License: MIT (Free and open-source).

  3. Understand FreeKiosk Display Modes

    main

    FreeKiosk offers four distinct operational modes depending on your use case:

    • WebView Mode: Displays any HTTPS/HTTP URL in a fullscreen immersive experience. Ideal for Home Assistant dashboards, digital signage, and web-based applications.
    • External App Mode: Locks the tablet to a specific installed Android application. It includes auto-relaunch on exit/crash and a 5-tap gesture + PIN to access settings. Best for cloud gaming (e.g., Steam Link) or custom Android apps.
    • Dashboard Mode: Provides a configurable tile grid of multiple URLs for quick navigation. It features one-tap navigation and an auto-return to the dashboard after inactivity. Best for multi-dashboard environments.
    • Media Mode: Focuses on enhanced media playback with native player integration, multi-app switching, and time-based content scheduling. Best for video/audio streaming and scheduled content rotation.

  4. Configure Motion Detection modes

    main

    FreeKiosk can detect motion using the device camera and report it as a motion_detected binary sensor in Home Assistant.

    Modes:

    • Default: Motion detection only runs during the screensaver (to wake the screen on movement). This has minimal battery impact.
    • Always-on: Continuous motion detection via an HA switch or MQTT setting. This uses the camera continuously and has a higher battery impact.

    To enable continuous detection, use the motion_always_on MQTT setting or the HA switch entity.

    Note: Camera permission must be granted for motion detection to work. FreeKiosk requests this automatically on first launch.

    # Toggle always-on motion detection
mosquitto_pub -h BROKER_IP -t "freekiosk/TOPIC_ID/set/motion_always_on" -m "ON"

  5. Configure Dashboard Mode

    main

    Dashboard Mode replaces the single-URL view with a grid of configurable URL tiles. Each tile has a name and a URL; tapping a tile opens that page.

    Setup

    1. Navigate to Settings → Dashboard tab.
    2. Toggle "Dashboard Mode" to ON.
    3. Add your tiles by providing a name and a URL for each.

    Related Features

    • Inactivity Return: When enabled in Settings → General, the app automatically returns to the dashboard grid after a configured period of touch inactivity.
    • URL Planner Integration: Scheduled planner events take priority. The app will switch from the dashboard grid to the scheduled URL, and automatically return to the grid once the event ends.

  6. Compare Basic Mode vs Device Owner Mode

    main

    Choose the mode based on your deployment needs:

    FeatureBasic ModeDevice Owner Mode
    Kiosk LockdownPartialComplete
    System NotificationsVisibleBlocked
    Status BarMay appearHidden
    Navigation ButtonsAccessibleDisabled
    Home ButtonMay workDisabled
    Recent AppsAccessibleDisabled
    Samsung PopupsCan appearBlocked
    Exit Without PINPossibleImpossible
    Auto-start on BootYesYes
    Recommended ForTesting, personalProduction, public

  7. How Wiki Sync works in FreeKiosk

    main

    FreeKiosk uses a GitHub Action to automatically publish documentation from the docs/ folder in the repository to the GitHub Wiki.

    Important: The docs/ folder is the single source of truth. This is a one-way sync. Any manual edits made directly to the GitHub Wiki will be overwritten during the next synchronization process.

    Sync Workflow

    1. Trigger: A push to the main branch or a manual workflow dispatch.
    2. Clone: The automation clones the wiki repository.
    3. Sync: Files are copied from docs/ to the wiki using rsync --delete to ensure the wiki matches the source exactly.
    4. Landing Page: The docs/README.md file is automatically copied to Home.md to serve as the wiki's landing page.
    5. Commit: Changes are pushed to the wiki repository.

  8. Configure Lockdown Levels for Security

    main

    FreeKiosk provides three levels of security and device control:

    LevelDescriptionUse Case
    BasicWebView kiosk with minimal restrictionsTesting, personal use
    StandardExternal app with navigation blockingSingle-app deployments
    EnterpriseDevice Owner full lockdownProduction, public kiosks

    Key Security Features:

    • Device Owner Mode: Complete device control.
    • Navigation Blocking: Disables home, recent apps, and settings.
    • Overlay Prevention: Blocks system dialogs and notifications.
    • Watchdog Service: Provides automatic recovery and monitoring.
    • PIN Protection: Secures settings access.
    • Lock Screen Controls: Optional PIN-protected controls for Wi-Fi, Bluetooth, audio, flashlight, brightness, emergency dialing, and rotation lock.
    • Screen Pinning: Task locking policies.

  9. Control screen power and lock state

    main

    Control the physical screen state. Note that full control (true screen off/lock) depends on the device's permission level.

    Screen Power

    • GET|POST /api/screen/on: Wake device / turn screen on.
    • GET|POST /api/screen/off: Turn screen off.

    Screen Lock

    • GET|POST /api/lock: Lock device screen. Requires Device Owner or AccessibilityService (API 28+). If neither is available, it falls back to dimming brightness to 0%.

    Permission Levels for Screen Control

    FeatureNo privilegesDevice AdminAccessibilityServiceDevice Owner
    screen/offDims to 0%lockNow()GLOBAL_ACTION_LOCK_SCREENlockNow()
    screen/onRestores brightnessWakes deviceWakes deviceWakes device
    lockErrorWorksWorksWorks
    rebootNot availableNot availableNot availableWorks
    Kiosk modeUser promptUser promptUser promptSilent

    Note on States: on refers to the physical screen state (PowerManager.isInteractive), while screensaverActive refers to the screensaver overlay. These are independent.

  10. FreeKiosk Integration and Automation Options

    main

    FreeKiosk provides several ways to integrate with external systems and automate device behavior:

    • REST API: Over 40 HTTP endpoints for remote device control.
    • MQTT: Supports real-time telemetry and features Home Assistant auto-discovery.
    • ADB Configuration: Allows for headless provisioning and scripting via Android Debug Bridge.
    • Modes: Supports WebView, External App, Dashboard, and Media Player modes.

  11. Understand FreeKiosk MQTT topic structure

    main

    FreeKiosk uses a hierarchical topic structure based on your Base Topic and Device Name (or deviceId).

    For a device with deviceName = lobby and Base Topic = freekiosk, the topics are:

    • Availability (LWT): freekiosk/lobby/availability (QoS 1, Retained)
    • State (all data): freekiosk/lobby/state (QoS 0, Retained)
    • Commands: freekiosk/lobby/set/{entity} (QoS 1, Not Retained)
    • Discovery: homeassistant/{component}/freekiosk_{deviceId}/{objectId}/config (QoS 1, Retained)

    Topic ID Logic

    The topic identifier is the sanitized Device Name (lowercased, spaces replaced with underscores). If no name is set, it falls back to the ANDROID_ID.

    freekiosk/lobby/state

  12. Compare REST API and MQTT integration channels

    main

    FreeKiosk provides two primary methods for connecting to your automation stack. You can run both simultaneously on the same device.

    REST API

    • Best For: On-demand control via HTTP, mobile app control, shell scripts (curl/wget), and web dashboards (JavaScript).
    • Control Method: Request/response.
    • Telemetry: Polling-based.
    • Security: Uses an API key.

    MQTT

    • Best For: Real-time telemetry, Home Assistant auto-discovery, event-based automation, and managing multi-device fleets.
    • Control Method: Push commands.
    • Telemetry: Real-time publishing.
    • Security: Uses username/password.
    • Availability: Uses LWT (Last Will Testament) to signal device status.