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
• Fetch URL (pull mode) - Direct URL for on-demand screenshots, works with ESPHome and custom e-ink setups
• 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)

1. Add this repository to Home Assistant:

   • Go to Settings → Add-ons → Add-on Store → ⋮ → Repositories
   • Add: https://github.com/usetrmnl/trmnl-home-assistant

2. Install the TRMNL HA add-on

3. Configure your access token:

   • In Home Assistant: Profile → Long-Lived Access Tokens → Create Token
   • Add to the add-on configuration

4. 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_IP with your machine's IP (e.g., 192.168.1.100). Container names like homeassistant won't work since HA uses host networking.

Volume mount: -v ./trmnl-data:/data is recommended. -v ./trmnl-data:/app/data also works.

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
Fetch URL (Pull Mode)	On-demand screenshots via direct URL
Device Presets	Supported e-ink displays
Scheduled Captures	Cron-based automation
Webhook Formats	TRMNL, BYOS, and custom endpoints
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

Links

• TRMNL
• Documentation
• Changelog
• Upstream Project (puppet)