TRMNL Home Assistant Integration

This integration provides a native way to send data from Home Assistant to your TRMNL e-ink display using TRMNL's Webhook Plugin feature.

It works natively without requiring external Python scripts or a middleman server.

Prerequisites

A working Home Assistant setup
A TRMNL device
A TRMNL Webhook Plugin URL (see Step 0 below)

Step 0: Get your TRMNL Webhook URL

Before configuring Home Assistant, you must create a slot on your TRMNL device to receive the data.

Go to your TRMNL Dashboard at usetrmnl.com.
Navigate to Plugins -> Private Plugins.
Click Add New or Create New Plugin.
Choose Webhook for the data strategy.
In the Code/Markup editor, write the desired layout. Variables sent from Home Assistant will be available here (e.g., {{ temperature }}).
Save the plugin. A Webhook URL will be provided, formatted like: https://usetrmnl.com/api/custom_plugins/xyz123abc. Save this URL.
Assign the new Private Plugin to your device's playlist.

Step 1: Install the Custom Component

You can install this via HACS (recommended) or manually.

Option A: HACS (Recommended)

Open HACS in Home Assistant.
Click the three dots in the top right and select Custom repositories.
Add the URL of this repository https://github.com/Jobey99/useTRMNL-Home-Assistant and select Integration as the category.
Click Install.
Restart Home Assistant.

Option B: Manual Installation

Copy the custom_components/trmnl folder from this repository.
Paste it into your Home Assistant's config/custom_components/ directory.
Restart Home Assistant.

Step 2: Configure the Integration

Go to Settings -> Devices & Services in Home Assistant.
Click Add Integration in the bottom right corner.
Search for TRMNL.
Enter your TRMNL Webhook URL.
Click Submit.

Step 3: Send Data to TRMNL via Automations

Use the trmnl.update_plugin service to send customized merge_variables to the TRMNL screen.

Using Developer Tools to Test

Go to Developer Tools -> Services.
Select TRMNL: Update TRMNL Plugin.
In the variables key, define the data your TRMNL plugin expects.

Example YAML payload:

service: trmnl.update_plugin
data:
  variables:
    temperature: 22.5
    pm25: 12.7

Full Example: Sensor Dashboard

To display a dashboard with multiple sensors, you must configure both the TRMNL display markup and the Home Assistant automation.

1. TRMNL Plugin Markup

In your TRMNL Private Plugin settings at usetrmnl.com, paste the following into the Code/Markup editor:

<div class="layout layout--col gap--space-between">
  <div class="grid grid--cols-1 gap--xlarge" style="max-width: 85%;">
    <div class="grid grid--cols-2">
      <div class="item">
        <div class="content">
          <span class="value value--large">{{ temperature }}°C</span>
          <span class="label label--large">Temperature</span>
        </div>
      </div>
      <div class="item">
        <div class="content">
          <span class="value value--large">{{ pm25 }} µg/m³</span>
          <span class="label label--large">PM2.5 Level</span>
        </div>
      </div>
    </div>
  </div>
</div>

2. Home Assistant Automation

Create an automation in Home Assistant to periodically push the sensor data to the variables temperature and pm25 defined in the markup above.

Go to Settings -> Automations.
Create a new Automation.
Switch to YAML editing mode and use the following template (replace the sensor entities with your own):

alias: Update TRMNL Sensor Dashboard
trigger:
  - platform: time_pattern
    minutes: /5
action:
  - service: trmnl.update_plugin
    data:
      variables:
        temperature: "{{ states('sensor.air_sensor_temperature') | float(default=0) }}"
        pm25: "{{ states('sensor.air_sensor_current_pm2_5') | float(default=0) }}"

Passing Raw HTML

If the TRMNL markup utilizes an injected HTML variable (like {{ content }}), raw HTML can be sent from Home Assistant.

service: trmnl.update_plugin
data:
  variables:
    content: >
      <h2>Temp: {{ states('sensor.air_sensor_temperature') }}°C</h2>
      <h2>PM2.5: {{ states('sensor.air_sensor_current_pm2_5') }} µg/m³</h2>

Jobey99/useTRMNL-Home-Assistant