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 Slow mode switch and FlipDot Display Slow mode interval dropdown (1 minute ... 60 minutes): the display only changes at those times, on the clock, and is switched off in between (less noise, e.g. in the evening with an automation). Rules with "show at once in slow mode" still show their page right away.
• 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.