ha-addon

Timeframe

An e-paper calendar, weather, and smart home family dashboard

Supported displays

• Visionect Place & Play 13 / Joan 13 Pro - designed for 10m update interval
• Boox Mira Pro 25.3" - Real-time updates via WebSocket
• Boox Mira 13.3" - Real-time updates via WebSocket
• TRMNL (OG)
• TRMNL (X)
• reTerminal E1001 7.5"
• reTerminal E1003 10.3"

Installation

1. In Home Assistant, go to Settings → Add-ons → Add-on Store
2. Click the three-dot menu (⋮) → Repositories
3. Add this repository URL: https://github.com/timeframe/ha-addon
4. Find Timeframe in the add-on store and click Install
5. Click Start
6. Access the app at port 8099 (e.g. http://homeassistant.local:8099)

Run as a standalone Docker container

Timeframe can also run as a regular Docker container, independent of the Home Assistant add-on system. All configuration comes from environment variables, and it can point at any reachable Home Assistant instance — local or remote.

You'll need a Home Assistant long-lived access token: in HA, open your profile → Security → Long-Lived Access Tokens → Create Token.

Using Docker Compose

A ready-to-edit docker-compose.yml is included. Set TIMEFRAME_HOME_ASSISTANT_URL and TIMEFRAME_HOME_ASSISTANT_TOKEN, then:

docker compose up -d --build

Open the dashboard at http://localhost:8099.

Using docker run

docker build -t timeframe .

docker run -d \
  --name timeframe \
  -p 8099:8099 \
  -v timeframe-data:/data \
  -e TIMEFRAME_HOME_ASSISTANT_URL="http://192.168.1.50:8123" \
  -e TIMEFRAME_HOME_ASSISTANT_TOKEN="your_long_lived_access_token" \
  timeframe

Environment variables

Keep the /data volume across restarts — it holds the bundled Postgres database and the generated secret key.

When installed as a Home Assistant add-on, Timeframe instead authenticates automatically via the Supervisor and reads unit options from the add-on configuration UI, so no environment variables are required in that mode.

Configuration

The following entities can be created in Home Assistant to customize behavior. Icon names are from Material Design Icons (without the mdi- prefix).

Template helper examples

Here are some example template sensors:

sensor.timeframe_top_left_status

{% if is_state('input_boolean.check_mailbox', 'on') %}
mailbox,Check mail
{% endif %}

sensor.timeframe_top_left_unavailable_entities

…

sensor.timeframe_top_left_low_batteries

{% for state in states.sensor
|selectattr('attributes.device_class', '==', 'battery')
|selectattr('entity_id', 'search', 'battery_level') -%}
{% if states(state.entity_id) |int(100)  0 %} ({% if days %}{{ days }}d{% endif %}{% if hours %}{{ hours }}h{% endif %}{% if minutes %}{{ minutes }}m{% endif %}){% endif %}
{% endif %}

sensor.timeframe_top_left_door_locks

…

sensor.timeframe_top_left_backup_battery_status

{% if is_state('sensor.solaredge_grid_power', 'unknown') %}
battery,Backup {{ states('sensor.solaredge_storage_level') }}%
{% endif %}

sensor.timeframe_top_left_dishwasher_needs_attention

{% set power = states('sensor.kitchen_dishwasher_switched_outlet_power') %}
{% if is_number(power) and power | float  19 %}
dishwasher,Run the dishwasher!
{% endif %}

sensor.timeframe_top_left_heat_pump_status

{% if not is_state('select.main_heat_source', 'heat pump only') %}
heat,Main HVAC {{ states("select.main_heat_source") }}
{% endif %}
{% if not is_state('select.upstairs_heat_source', 'heat pump only') %}
heat,Upstairs HVAC {{ states("select.upstairs_heat_source") }}
{% endif %}

sensor.timeframe_weather_status_uv

{% set uv = states('sensor.weather_station_uv_index') | float(-1) %}
{% if uv > 3 %}
weather-sunny-alert,{{ uv | int }}
{% endif %}

sensor.timeframe_weather_status_wind_gust

{% if states('sensor.weather_station_wind_gust') | int > 10 %}
arrow-up,{{states('sensor.weather_station_wind_gust') | int}},{{states('sensor.weather_station_wind_direction_average') | int - 45 }}
{% endif %}

sensor.timeframe_top_right_bird

bird,{{ states('sensor.least_recently_seen_bird') }}

sensor.timeframe_weather_status_lightning

…

sensor.timeframe_weather_feels_like_entity_id

sensor.weather_station_feels_like

sensor.timeframe_media_player_entity_id

media_player.sonos_amp_2

sensor.timeframe_weather_status_open_windows

{% set temp = states('sensor.weather_station_feels_like') | int %}
{% set aqi = states('sensor.airnow_air_quality_index') | int %}
{% set now = now().time() %}
{% set start = strptime('06:00', '%H:%M').time() %}
{% set end = strptime('20:00', '%H:%M').time() %}
{% if aqi  63 and temp  0 %}
email-outline, SoloFolio message
{% endif %}

sensor.timeframe_top_left_dryer_status

{% if is_state('input_boolean.laundry_dryer_needs_changed', 'on') %}
  {% set elapsed = as_timestamp(now()) - as_timestamp(states.input_boolean.laundry_dryer_needs_changed.last_changed) %}
  {% set total_minutes = ((elapsed + 150) // 300 * 5) | int %}
  {% set days = total_minutes // 1440 %}
  {% set hours = total_minutes % 1440 // 60 %}
  {% set minutes = total_minutes % 60 %}
tumble-dryer,Dryer{% if total_minutes > 0 %} ({% if days %}{{ days }}d{% endif %}{% if hours %}{{ hours }}h{% endif %}{% if minutes %}{{ minutes }}m{% endif %}){% endif %}
{% endif %}

sensor.timeframe_top_left_dog_bowl_status

{% if is_state('binary_sensor.dog_bowl_water_detected', 'off') %}
paw,Water low
{% endif %}

sensor.timeframe_top_left_rav4_status

{% if is_state('device_tracker.garage_rav4_beacon', 'home') and is_state('sensor.garage_ev_charger_west_status', 'not_connected') %}
charging-station,RAV4 unplugged
{% endif %}

sensor.timeframe_top_left_groceries_status

{% if is_state('input_boolean.bring_in_groceries', 'on') %}
basket,Bring in groceries
{% endif %}

sensor.timeframe_top_left_printer_status

{% set toner = states('sensor.away_room_printer_black_toner_remaining') %}
{% if is_number(toner) and toner | float  19 %}
door-closed,Open Door for robot
{% endif %}

sensor.timeframe_weather_status_air_quality_warning

{% set aqi = states('sensor.honeysuckle_air_quality_aqi_us_aqi') | int %}
{% if aqi > 100 %}
face-mask-outline,{{ aqi }}
{% elif aqi > 50 %}
air-filter,{{ aqi }}
{% endif %}

sensor.timeframe_top_left_solar_power_warning

{% set uv = states('sensor.weather_station_uv_index') %}
{% set solar_kw = states('sensor.solaredge_solar_power') %}
{% if is_number(uv) and is_number(solar_kw) and uv | float >= 4 and solar_kw | float 4 but low solar output!
{% endif %}

Calendar events

Event description tokens

You can customize how an individual calendar event renders by adding one or more tokens to its description. Tokens are usually placed on their own line and are stripped from any text shown on the display. Icon names come from Material Design Icons (without the mdi- prefix).

A recurring event whose title ends with a four-digit year in parentheses, e.g. Ada (1990), renders that year as an elapsed count (Ada (35)) — this is how birthdays and anniversaries show an age.

Banner mode

To display a full-width banner at the bottom of the screen, include timeframe-banner or #banner in a calendar event's description. The banner appears while the event is active (between its start and end times).

• The event title becomes the banner heading.
• The rest of the description (after removing the tag) becomes the banner body. Basic HTML formatting (, , , ) is supported; plain-text newlines are converted to line breaks.

Example: Create a calendar event titled "School Closed Today" with the description:

#banner
Due to inclement weather, all schools will be closed today. Stay safe!

Local development

Configuration:

Create config/timeframe.yml from config/timeframe.yml.example with your settings.

Environment variables

Setup

1. bundle install
2. bin/rails s
3. Visit http://localhost:3000