Flipdot-display/docs/home-assistant.md

Home Assistant

← Back to the README

The ESP32 connects to Home Assistant in two ways:

• MQTT (with discovery): the display's own switches, dropdowns, sensors and buttons. Broker, user and password are in the web UI, Home Assistant tab (an empty broker uses secrets.h). Changing them restarts the ESP32.
• REST API: values of any entity for the dynamic pages and the trigger rules. Set the URL (empty: http://<broker>:8123, plain http only, use the IP address) and a long-lived access token (Home Assistant, your profile, Security tab) in the same tab.

Entities

• FlipDot Display Power switch: off clears the display and cuts power through the relay.
• FlipDot Display Mode dropdown: what is shown during the day, a dynamic page ("Clock" first) or one of the bitmaps (the same choice as in the web UI).
• FlipDot Display Off image dropdown: what is left on the dots when the display switches off (at night or with the Power switch): blank or one of the bitmaps.
• FlipDot Display IP sensor: the ESP32's IP address.
• FlipDot Display Stopwatch switch and FlipDot Display Stopwatch reset button: the stopwatch of the dynamic pages.
• FlipDot Display Shown page sensor: what the display shows now (schedule, rule or chosen page). FlipDot Display Back to schedule button: ends a page chosen by hand.
• FlipDot Display Firmware sensor: version and health, e.g. 2.7.2, ok, 0 crashes, recovery ok.
• FlipDot Display Recovery button: restarts into the recovery app for 10 minutes.

The unique ids of these entities never change, so automations and dashboards keep working after firmware updates.

Values on dynamic pages

A Home Assistant value element on a page shows an entity's state or one of its attributes, as a number (multiplier, decimals, auto unit, without minus sign), a duration, a time from a timestamp, or with own texts per state (see the web UI).

Home Assistant values on the shown page are read every minute, one entity at a time, by a task of their own (on the ESP32's other core), so a slow or unreachable Home Assistant never holds up the display or the web UI. An unknown or unreachable value shows --. The display only changes when the shown text changes, so round values with the decimals setting.

Rules

The schedule can bring a page to the front from a Home Assistant state, e.g. the 3D printer page while sensor.mainsailos_current_print_state is printing. Each rule is read at its own interval; when Home Assistant can't be reached it is read once a minute at most, so the display keeps running.

Weather forecast

Weather entities have no forecast attribute anymore (since Home Assistant 2024.3); the forecast comes from the weather.get_forecasts action. The Verwachting page reads it from a template sensor that keeps the next days as an attribute. Add to configuration.yaml (and restart Home Assistant, or reload the template entities):

template:
  - trigger:
      - trigger: time_pattern
        minutes: /30
      - trigger: homeassistant
        event: start
    action:
      - action: weather.get_forecasts
        data: { type: daily }
        target: { entity_id: weather.knmi_home }
        response_variable: f
    sensor:
      - name: Weer verwachting
        unique_id: weer_verwachting
        state: "{{ f['weather.knmi_home'].forecast[0].condition }}"
        attributes:
          forecast: "{{ f['weather.knmi_home'].forecast[:4] }}"

The page then reads sensor.weer_verwachting with attribute paths: forecast.0 is today, forecast.1 tomorrow, forecast.2 the day after, e.g. forecast.1.condition (chooses the icon weer7 <condition>, 7 x 7 dots), forecast.1.temperature (max) and forecast.1.templow (min). The weekdays are Date elements with a day offset. Use another weather entity by replacing weather.knmi_home in the YAML (and on the page, for today's icon and temperature).

Plex and Tautulli

The Plex page (in examples/home-pages.json) uses Home Assistant's Plex and Tautulli integrations, no extra firmware:

• sensor.plex_server (Plex, named after your server): how many are watching.
• sensor.{plex_user}_state (Tautulli, per user): playing, paused, ... chooses the icon (icons plex playing, plex paused, plex buffering).
• sensor.{plex_user}_full_title and sensor.{plex_user}_progress (Tautulli, per user): the title and the progress bar. Home Assistant creates these disabled: enable them on the Tautulli user's device in Home Assistant.

{plex_user} is the Plex user set in the web UI (Home Assistant tab), written the way Home Assistant puts it in entity ids (MangaValk -> mangavalk). A rule (Schedule tab) adds the page to the rotation while sensor.plex_server is above 0.