Ikraam Ghoor
4d2d05a0fb
Necessary to support self-hosted TRMNL displays using the BYOS Hanami API. Users can now select between raw image uploads and JSON-wrapped base64 payloads compatible with the /api/screens endpoint. Implements: - Strategy pattern for webhook payload transformation (raw vs. byos-hanami) - JWT authentication flow with token refresh (credentials never stored) - 422 error handling with automatic screen deletion and retry - UI for BYOS configuration including login and manual token entry
TRMNL HA
Send Home Assistant dashboard screenshots to your TRMNL e-ink display with advanced dithering optimized for e-paper screens.
Note: This add-on can capture screenshots from any website, not just Home Assistant dashboards. See Standalone Mode for detailed setup.
Features
- E-ink optimized dithering - Floyd-Steinberg and Ordered algorithms for crisp e-paper rendering
- TRMNL webhook integration - Automatic dashboard uploads to TRMNL devices
- Scheduled captures - Cron-based automation with Web UI management
- Device presets - Pre-configured settings for 24+ popular e-ink displays
- Crash recovery - Automatic browser recovery and process supervision
- High performance - Powered by Bun runtime for fast startup and low memory
Installation
Home Assistant OS (Recommended)
-
Add this repository to Home Assistant:
- Go to Settings → Add-ons → Add-on Store → ⋮ → Repositories
- Add:
https://github.com/usetrmnl/trmnl-home-assistant
-
Install the TRMNL HA add-on
-
Configure your access token:
- In Home Assistant: Profile → Long-Lived Access Tokens → Create Token
- Add to the add-on configuration
-
Start the add-on and open the Web UI
Home Assistant Container (Docker)
Running HA as a Docker container? No problem! Just one command:
docker run -d --name trmnl-ha \
--restart unless-stopped \
-e HOME_ASSISTANT_URL=http://YOUR_HOST_IP:8123 \
-e ACCESS_TOKEN=your_token_here \
-p 10000:10000 \
-v ./trmnl-data:/data \
ghcr.io/usetrmnl/trmnl-ha-amd64:latest # ARM64 (Pi 4/5, Apple Silicon): ghcr.io/usetrmnl/trmnl-ha-aarch64:latest
Note: Replace
YOUR_HOST_IPwith your machine's IP (e.g.,192.168.1.100). Container names likehomeassistantwon't work since HA uses host networking.
Then open http://localhost:10000 - that's it!
See full Docker setup for Docker Compose and timezone configuration.
Proxmox Users
If running Home Assistant OS in Proxmox, set the VM host type to host for Chromium to work properly.
Security
Important: This add-on is designed for trusted home networks.
- The Web UI (port 10000) has no built-in authentication
- Always use Ingress (sidebar integration) instead of direct port access
- Never expose port 10000 directly to the internet
- Access tokens are stored securely in Home Assistant's add-on configuration
Documentation
| Topic | Description |
|---|---|
| Configuration | Required and optional settings |
| Web UI | Using the web interface |
| API Reference | Screenshot endpoint parameters |
| Device Presets | Supported e-ink displays |
| Scheduled Captures | Cron-based automation |
| Troubleshooting | Common issues and fixes |
| Local Development | Development setup |
Attribution
This project is based on the puppet Home Assistant add-on by Paulus Schoutsen.
See the NOTICE file for complete attribution and modification details.
License
Copyright (c) Paulus Schoutsen (original work) Copyright (c) 2024-2025 TRMNL (enhancements and modifications)
Licensed under the Apache License 2.0