Skip to content

INTEGRATIONS

Jump to bottom
github-actions[bot] edited this page Mar 30, 2026 · 1 revision

Integrations

Connect FreeKiosk to your automation stack

Docs Home • REST API • MQTT

Important

REST API and MQTT can run simultaneously on the same device.

Table of Contents

Integration Channels

FreeKiosk offers two main integration methods:

Channel Best For Documentation
REST API On-demand control via HTTP REST API Docs
MQTT Real-time telemetry + Home Assistant MQTT Docs

Feature Comparison

Feature REST API MQTT
Control Method Request/response Push commands
Telemetry Polling Real-time
HA Discovery Manual Auto
Availability HTTP status LWT
Security API key Username/password

REST API

HTTP-based control for on-demand device management.

Key Features

  • 40+ Endpoints - Complete device control
  • Device Status - Real-time sensor data
  • Navigation Control - URL and app switching
  • Media Capture - Screenshot & camera access
  • API Security - Optional API key authentication

Best For

  • Home Assistant HTTP integration
  • Mobile app control
  • Shell scripts (curl/wget)
  • Web dashboards (JavaScript)

Quick Start

# Get device status
curl -H "X-Api-Key: your-key" http://tablet-ip:8080/api/status

# Navigate to new URL
curl -X POST -H "X-Api-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://new-dashboard.com"}' \
  http://tablet-ip:8080/api/url

# Take screenshot
curl -H "X-Api-Key: your-key" http://tablet-ip:8080/api/screenshot -o screenshot.png

Tip

See the complete REST API Reference for all endpoints.

MQTT

Real-time telemetry and Home Assistant auto-discovery.

Key Features

  • MQTT Protocol - v5 / v3.1.1 support
  • HA Discovery - Auto-configuration in Home Assistant
  • Availability - LWT (Last Will Testament) status
  • Telemetry - Real-time sensor publishing
  • Remote Control - Command subscription topics

Best For

  • Home Assistant integration (auto-discovery)
  • Continuous monitoring
  • Event-based automation
  • Multi-device management

Quick Start

Home Assistant configuration:

mqtt:
  broker: your-broker-ip
  port: 1883
  discovery: true
  discovery_prefix: homeassistant

Topic structure:

freekiosk/lobby/availability         # Device online/offline
freekiosk/lobby/state                # All sensor data (JSON)
freekiosk/lobby/set/brightness       # Set brightness command
freekiosk/lobby/set/url              # Navigate to URL

Tip

See the complete MQTT Reference for topics and commands.

Headless Setup

Configure integrations via ADB for mass deployment.

Configuration Parameters

REST API:

  • rest_api_enabled - Enable REST API ("true")
  • rest_api_port - API port ("8080")
  • rest_api_key - API authentication key

MQTT:

  • mqtt_enabled - Enable MQTT ("true")
  • mqtt_broker_url - Broker IP/hostname
  • mqtt_port - Broker port ("1883")
  • mqtt_username - MQTT username
  • mqtt_password - MQTT password
  • mqtt_discovery_prefix - HA discovery prefix ("homeassistant")

Example Commands

REST API only:

adb shell am start -n com.freekiosk/.MainActivity \
    --es rest_api_enabled "true" \
    --es rest_api_port "8080" \
    --es rest_api_key "my-secret-key" \
    --es pin "1234"

MQTT only:

adb shell am start -n com.freekiosk/.MainActivity \
    --es mqtt_enabled "true" \
    --es mqtt_broker_url "192.168.1.100" \
    --es mqtt_username "homeassistant" \
    --es mqtt_password "mqtt-password" \
    --es pin "1234"

Both together:

adb shell am start -n com.freekiosk/.MainActivity \
    --es rest_api_enabled "true" \
    --es rest_api_port "8080" \
    --es rest_api_key "my-secret-key" \
    --es mqtt_enabled "true" \
    --es mqtt_broker_url "192.168.1.100" \
    --es mqtt_username "homeassistant" \
    --es mqtt_password "mqtt-password" \
    --es pin "1234"

Note

See the complete ADB Configuration Guide for all parameters.

Choosing Your Integration

Decision Guide

Use Case Recommended Why
Home Assistant MQTT Auto-discovery + real-time
Mobile App REST API Simple HTTP requests
Monitoring REST API Polling for status
Event Automation MQTT Push-based notifications
Web Integration REST API JavaScript friendly
Multi-Device Fleet MQTT Central broker
Scripts REST API Easy curl commands
Real-time Control Both Best of both worlds

Hybrid Approach

Use both for maximum flexibility:

  • MQTT - Continuous telemetry and HA discovery
  • REST API - On-demand commands and media capture
  • ADB - Initial provisioning and bulk configuration

Related Documentation

Clone this wiki locally