PaperPanel

Lightweight Home Assistant dashboard for old and low-power devices (for example Kindle browsers).

The project is intentionally simple:

• PHP renders the dashboard widgets on the server.
• Plain JavaScript updates the page.
• No frontend framework, no build step, no npm required.

Why This Project

This dashboard is optimized for legacy browser engines where modern SPAs are often slow or broken.

Key goals:

• High compatibility with old devices
• Low CPU and memory usage
• Easy deployment on standard web servers
• Easy widget customization via config.json

Features

• Legacy-friendly JavaScript (no framework)
• E-Ink friendly high-contrast UI
• Config-driven main page widgets
• Device control for Home Assistant entities
• Weather widget and local date widget support
• Auto-refresh plus immediate refresh after user actions

Requirements

• Home Assistant instance reachable from the web server
• Home Assistant Long-Lived Access Token
• PHP-enabled web server (Apache, nginx + php-fpm, lighttpd, HA Apache addon)
• PHP cURL extension enabled
• Write access for the cache directory

Quick Start

1. Copy this project to your web server document root (or subfolder).
2. Edit config.json and set:
   • address to your Home Assistant URL
   • token or environment variable HA_TOKEN
3. Ensure the cache folder is writable by the web server user.
4. Open index.php in your browser.

Installation (Detailed)

1. Deploy Files

Copy all project files to your server, for example:

/var/www/html/htdocs/
	index.php
	api.php
	helper.php
	main.js
	style.css
	config.json
	pages/
	icons/
	cache/

2. Configure Home Assistant Access

Edit config.json:

{
	"address": "http://YOUR_HOME_ASSISTANT_IP:8123",
	"token": "",
	"devices": {
		"main": [
			{ "id": "widget.date", "type": "date", "width": 2, "options": { "weekday": true, "time": true } },
			{ "id": "weather.forecast_home", "type": "weather", "width": 4 }
		],
		"switches": true,
		"lights": true,
		"automations": true,
		"players": true
	}
}

Notes:

• address should be the internal URL of Home Assistant.
• Plain HTTP is usually easiest for old Kindle browsers on local networks.

3. Configure Token (Recommended Secure Option)

Preferred:

• keep token empty in config.json
• provide token through environment variable HA_TOKEN

Example:

export HA_TOKEN="YOUR_LONG_LIVED_ACCESS_TOKEN"

The application automatically uses HA_TOKEN when config.json has no token value.

4. Set Cache Permissions

The app caches Home Assistant states in cache/devices.json.

Make sure the web server user can write to cache/.

Example (Linux):

chown -R www-data:www-data cache
chmod -R 775 cache

5. Open Dashboard

Open in browser:

http://YOUR_SERVER/htdocs/index.php

For Kindle, use the experimental browser URL directly.

Device and Widget Configuration

The main page is configured in config.json under devices.main.

Examples:

• Home Assistant entity widget:

{ "id": "light.living_room", "type": "light", "width": 2 }

• Local date widget (no HA entity needed):

{
	"id": "widget.date",
	"type": "date",
	"width": 2,
	"options": {
		"weekday": true,
		"time": true,
		"format": "d.m.Y",
		"timeFormat": "H:i",
		"timezone": "Europe/Berlin"
	}
}

Date widget options:

• weekday (true/false)
• time (true/false)
• format (PHP date format)
• timeFormat (PHP time format)
• timezone (optional, for example Europe/Berlin)

Theme Configuration

Set the UI theme in config.json:

"ui": {
	"theme": "dark"
}

Available values:

• dark (default)
• light

Example for light mode:

"ui": {
	"theme": "light"
}

Performance Notes for Old Devices

• Keep widget count low on one page.
• Use mostly static icons and simple layouts.
• Prefer local network hosting for lower latency.
• Avoid heavy background images and custom webfonts.

Troubleshooting

Empty dashboard or no updates

• Check config.json address/token values.
• Verify the server can reach Home Assistant.
• Verify cache/ is writable.

Button click does nothing

• Open browser dev console and inspect request errors.
• Check Home Assistant token permissions.
• Check domain/service validity for the entity.

403 from Home Assistant

• Token invalid or expired.
• Home Assistant network/security settings block the request.

Security Notes

• Do not expose this dashboard directly to the public internet.
• Recommended: run it only in your local network.
• Treat your Home Assistant token like a password.
• Prefer HA_TOKEN over storing secrets in config.json.

Inspiration

This project is inspired by KFloorP and similar Kindle/Home Assistant dashboard projects.