troubleshooting

Home Assistant isn't discovering my Display Screen

If your ROAMiQ Display Screen connects to MQTT but never shows up in Home Assistant, the cause is almost always the discovery prefix in your Home Assistant MQTT settings.

Before you start

  • Home Assistant with the MQTT integration installed
  • ROAMiQ Display Screen on the same network as your MQTT broker
  • MQTT Explorer (or any MQTT client) for the quick check below

Quick check (90 seconds)

Open MQTT Explorer and subscribe to:

homeassistant/#

You should see a cluster of retained messages like:

  • homeassistant/light/roamiq_<id>_led/config
  • homeassistant/switch/roamiq_<id>_relay1/config
  • homeassistant/sensor/roamiq_<id>_temperature/config
  • …and several more

If those messages are there, the panel has done its job. The problem is in Home Assistant.

Fix it in Home Assistant

1

Open the MQTT integration

In Home Assistant, go to Settings → Devices & Services, click the MQTT integration, then Configure.

2

Check Enable discovery

Make sure Enable discovery is turned on.

3

Fix the Discovery prefix

Set the Discovery prefix to exactly homeassistant — no trailing slash, no extra characters, lowercase. A trailing slash is the #1 cause of silent discovery failures.

4

Reload the integration

Open the 3-dot menu on the MQTT integration and choose Reload.

If the messages aren't on the broker at all

That's rare, but if homeassistant/# is empty in MQTT Explorer, force the panel to republish:

  1. On the tablet, open Settings → Wi-Fi, toggle Wi-Fi off and then on. The panel will reconnect to MQTT and re-publish every discovery config.
  2. Alternatively, reboot the tablet. Same effect.

Once the retained messages are on the broker, follow the steps above in Home Assistant.

Still stuck?

If you've confirmed the discovery prefix is homeassistant, reloaded the integration, and the messages are visible on the broker but the device still isn't appearing, open a support ticket with the following:

  • A screenshot of your Settings → Devices & Services → MQTT → Configure page
  • A screenshot of the homeassistant/# tree in MQTT Explorer
  • Your Home Assistant logs filtered for mqtt (Settings → System → Logs)

We'll take it from there.