Home Assistant integration (MQTT publisher)

MyAstroBoard can publish its state to an MQTT broker, with Home Assistant MQTT Discovery: enable the connector, point it at the broker Home Assistant already uses, and a “MyAstroBoard” device appears in Home Assistant together with one device per location - sky period, night score, sun and moon times, tonight’s best window and top target, current weather-for-astro, upcoming events - and, for users who opted in, one device per user with their Astrodex counters, tonight’s plan and its equipment, observation log totals and the latest Astrodex picture.

It is publish-only: MyAstroBoard never reads commands from the broker. The only thing it subscribes to is Home Assistant’s own birth message, so entities come back by themselves after a Home Assistant restart.

Ready-made Lovelace cards live in a separate repository: lovelace-myastroboard-card.

MyAstroBoard itself can also run inside Home Assistant OS, as an app - see Installation, option 2. The MQTT integration below works the same whichever way MyAstroBoard is installed (broker host core-mosquitto when both run in Home Assistant).

Requirements

Setup

1. Broker. Create a user for MyAstroBoard on the broker (Mosquitto add-on: Settings -> Add-ons -> Mosquitto -> Configuration, or a Home Assistant user - the add-on accepts those). Note the broker’s IP address and port (1883, or 8883 for TLS).
2. MQTT connection. App settings -> Configuration -> MQTT connections -> Add a connection (see MQTT connections):
   • Display name: any name, shown in the connector’s picker.
   • Broker URL: mqtt://192.168.1.10:1883 (or mqtts://host:8883 for TLS). Use the IP address rather than a .local name - mDNS does not resolve inside the container.
   • Username / Password: the broker user. Leave both blank for an anonymous broker.
   • Press the test button (wifi icon): it opens one real connection to the broker with the settings as typed and reports Reachable or the reason it is not (refused, timeout, not authorized, TLS…). Save.
3. Connector. App settings -> Connectors -> MQTT / Home Assistant -> Configure:
   • MQTT connection: pick the connection created above (the wifi button tests it).
   • Tick the modules you want (see Modules), switch Enable connector on, Save.
4. Home Assistant. Settings -> Devices & services -> MQTT: within a minute a MyAstroBoard device and one MyAstroBoard - <location> device per location preset appear. The card’s status line shows Connected, the last publish time and the number of devices and entities.

Nothing has to be added to configuration.yaml.

Per-user activity

Location and board data are install-level and published as soon as the connector is on. A user’s data (Astrodex, plan, observation log, pictures) is private, so it is published only when that user asks for it: My settings -> Customize -> Publish my activity to Home Assistant (MQTT). The switch only shows once an admin has enabled the connector, and it only ever covers the user’s own data - an admin cannot publish another user’s activity. The admin-side User activity and Latest Astrodex picture modules must be on as well.

Modules

Every location the cache scheduler keeps warm gets a device (in practice every preset). Disable the entities you do not need from the device page in Home Assistant.

Settings

MQTT connections

A broker is declared once, in App settings -> Configuration -> MQTT connections, and each MQTT connector picks one. Several connectors can share a connection: each one opens its own client, which is why two connectors on one connection cannot be saved with the same client ID (a broker keeps one session per client ID and would disconnect them in turn).

The list shows, for each connection, whether the broker answers (checked when the page opens and with the wifi button) and which connectors use it. A connection still picked by a connector cannot be deleted: pick another one in that connector first. Editing a connection makes every connector using it reconnect.

Upgrading from 1.7.1 or earlier: a configured connector’s broker becomes a connection named Home Assistant, already picked by the connector, with its password - nothing to re-enter.

Buttons

• Publish now - full republish of discovery and every state on the next tick (a few seconds).
• Remove from Home Assistant - switches the connector off and deletes every retained MyAstroBoard topic from the broker; Home Assistant drops the devices (their history is lost). Broker settings and modules are kept, so enabling the connector again recreates everything. Simply switching the connector off, by contrast, leaves the devices in place as unavailable. See Long-term statistics for the one thing a removal leaves behind.

Long-term statistics

Home Assistant records long-term statistics for every sensor that declares a state_class, and keeps them after the entity disappears. Only the six counters that track your own progress declare one (state_class: total): Astrodex objects, objects with pictures, pictures, constellations, observation sessions and total integration - the numbers a Statistics graph card can show growing month after month. Everything else (sky, Moon, best window, weather, aurora, plan progress) is an ephemeris or a forecast that MyAstroBoard recomputes at any time, so it deliberately records no long-term statistics; the recorder’s short-term history (10 days by default) still draws them in a history graph.

After Remove from Home Assistant (or a user opting out), those six series per user stay in the recorder as orphans. Home Assistant lists them under Developer tools -> Statistics with a Fix issue action that deletes them; Spook reports the same list. Nothing else is left behind.

Automation ideas

# Red observatory light at astronomical dusk
trigger:
  - platform: state
    entity_id: sensor.myastroboard_backyard_sky_period
    to: astronomical_night
action:
  - service: light.turn_on
    target: { entity_id: light.observatory }
    data: { rgb_color: [255, 0, 0], brightness: 40 }

# Tonight looks good
trigger:
  - platform: numeric_state
    entity_id: sensor.myastroboard_backyard_observation_score
    above: 7
condition:
  - condition: state
    entity_id: binary_sensor.myastroboard_backyard_astronomical_night
    state: "on"
action:
  - service: notify.mobile_app_phone
    data:
      message: "Night score {{ states('sensor.myastroboard_backyard_observation_score') }} - top target {{ states('sensor.myastroboard_backyard_top_target_tonight') }}"

Privacy and security

• Outbound only. No command topic exists; nothing Home Assistant publishes is acted upon.
• The password lives in the connector secrets store, never in the configuration, backups, the config export or any API response (the connection list only sees a mask).
• The connection test never pairs the stored password with a URL that differs from the saved one, and the MQTT and MQTT connection routes are admin-only.
• mqtts:// gives TLS; Accept self-signed certificates is meant for a LAN broker with its own CA, nothing else.
• A user’s data is published only while that user’s own switch is on. Location devices carry the preset name and timezone, not its coordinates; pictures are published without location data.

Troubleshooting

Log lines are prefixed MQTT publisher: in data/myastroboard.log.

Tested against Home Assistant 2024.11+ discovery format; re-check the release notes of the Home Assistant version you run if entities fail to appear.

Entities

Home Assistant builds each entity id from the device name and the entity name (never from the JSON key): the Top target tonight sensor of the “MyAstroBoard - Backyard” device is sensor.myastroboard_backyard_top_target_tonight, the Astronomical night binary sensor is binary_sensor.myastroboard_backyard_astronomical_night, the picture is image.myastroboard_alice_latest_astrodex_picture. unique_id is <base>_loc_<location_id>_<key>, so renaming a preset later keeps the entity history. The tables below are generated from backend/connectors/mqtt_payloads.py.

Board device (Board diagnostics)

Location device - Sky conditions

Location device - Weather now

Nearest hourly forecast row plus the astro analysis.

Location device - Upcoming events

User device - User activity

User device - Latest Astrodex picture

Topics

<base> is the base topic (myastroboard by default), <prefix> the discovery prefix.

Every timestamp is ISO 8601 with a UTC offset; an unknown value is JSON null (the entity shows unknown). A location device carries location_id, location_name and timezone next to the entity keys; a user device carries user_id and username.

The MQTT integration’s own homeassistant/status topic is the connector’s only subscription: online triggers a full republish.

Last updated 2026-11-13