Debug Home Assistant MQTT from Your iPhone

Why Debug Home Assistant Over MQTT from Your Phone

Home Assistant’s MQTT integration is powerful, but it can be opaque. When a light doesn’t respond to an automation, or a new Zigbee device fails to appear in the dashboard, the fastest path to an answer is watching the raw MQTT traffic — seeing exactly what messages are flowing, what payloads look like, and whether the broker is delivering them at all.

The problem is that most MQTT debugging tools require a laptop. You open a terminal, fire up MQTT Explorer or mosquitto_sub, and stare at a desktop window. That works fine in a home office, but if your Zigbee coordinator is in a closet, your broker runs on a Raspberry Pi in another room, or you just want to check something quickly from the couch, a native iPhone app is a much better fit.

MQTT Commander for iOS connects to any MQTT broker, including the one running inside Home Assistant, and gives you a full inspection and publish workflow designed for a phone screen. Here’s how to use it to debug your Home Assistant setup.

Finding Your Broker Address

Home Assistant users typically run one of two broker configurations.

Mosquitto add-on: If you installed the official Mosquitto broker add-on from the Home Assistant add-on store, the broker is running on the same host as Home Assistant itself. Use your Home Assistant’s local IP address or hostname (e.g., homeassistant.local) and port 1883 for plain TCP, or 8883 if you’ve enabled TLS in the add-on configuration.

External broker: Some setups point Home Assistant at an external Mosquitto instance, a managed MQTT service, or a broker running on a separate machine. In that case, use that machine’s address and whatever port it’s configured on. Check Settings → Devices & Services → MQTT in Home Assistant to see the broker host and port that HA itself is using — that’s exactly what you want.

If you’re not sure which port is open, the Connection Doctor runs staged diagnostics: it checks DNS resolution, TCP reachability, and MQTT handshake separately, so you can pinpoint whether a failure is a network issue, a port mismatch, or a credentials problem.

Connecting from iPhone

Open MQTT Commander, tap the + button to create a new connection, and fill in:

• Host: your broker’s IP or hostname
• Port: 1883 (plain TCP) or 8883 (TLS)
• Username / Password: the MQTT credentials you set up in Home Assistant

Credentials are stored in the iOS Keychain and never leave your device. Broker data stays on-device entirely — MQTT Commander has no cloud backend and no telemetry tied to your traffic.

If your broker requires TLS, tap TLS and choose your certificate setup. The built-in Certificate Wizard handles .p12/.pfx bundles and PEM files, and supports ALPN and SNI for brokers behind reverse proxies. For most Mosquitto add-on users with a local network setup, plain TCP on port 1883 is fine.

Tap Connect. The status indicator turns green when the MQTT handshake completes.

Reading homeassistant/# Discovery Topics

Home Assistant’s MQTT discovery protocol publishes configuration payloads to topics under the homeassistant/ prefix. Every auto-discovered entity — lights, sensors, switches, climate devices — has a config topic that tells HA what the entity is and which state/command topics to use.

MQTT Commander ships with a built-in preset for homeassistant/#. Tap Subscribe, select the preset, and confirm. You’ll immediately start seeing retained config messages arrive:

homeassistant/light/bedroom_lamp/config
homeassistant/sensor/outdoor_temp/config
homeassistant/binary_sensor/front_door/config

Tap any topic to open the payload inspector. Config payloads are JSON, and the inspector renders them with syntax highlighting and lets you apply JSONPath expressions to extract specific fields — useful when a payload is large and you’re hunting for the command_topic or state_topic field.

{
  "name": "Bedroom Lamp",
  "command_topic": "zigbee2mqtt/bedroom_lamp/set",
  "state_topic": "zigbee2mqtt/bedroom_lamp",
  "brightness": true,
  "schema": "json"
}

Once you know the state topic, add it as a separate subscription to watch live state changes. When you toggle the light in Home Assistant, you’ll see the payload update in real time.

Publishing a Command to Test an Entity

After finding the command_topic for a device, you can publish directly to it to verify the device responds independently of any Home Assistant automation logic.

Tap Publish, paste the command topic (e.g., zigbee2mqtt/bedroom_lamp/set), and compose your payload in the draft editor:

{"state": "ON", "brightness": 128}

Before sending, MQTT Commander shows a retain warning if you’ve toggled the retained flag — useful because accidentally retaining a command payload can cause unexpected behavior on reconnect. Confirm and publish. If the light responds, you know the device and broker are healthy; if it doesn’t, the problem is upstream in your automation or HA integration, not in the MQTT layer.

Retained Messages and Stale Discovery

One common source of confusion in Home Assistant MQTT setups is stale retained messages. When you remove a device or rename an entity, the old config topic may still be sitting on the broker as a retained message, causing a ghost entity to keep reappearing in Home Assistant.

In MQTT Commander, retained messages are flagged with a badge in the topic list. To clear a stale config topic, tap it, then choose Delete retained message. The app asks for confirmation before publishing the empty-payload retained delete — a safeguard worth having when you’re operating on a live production broker.

Troubleshooting Common Issues

Can’t connect at all: Run the Connection Doctor and check which stage fails. A DNS failure usually means a hostname typo or split-horizon DNS issue. A TCP failure on port 1883 often means a firewall rule on the broker host or router. A failed MQTT handshake with an authentication error means credentials are wrong.

Connecting but seeing no messages on homeassistant/#: Check that MQTT discovery is enabled in Home Assistant (Settings → Devices & Services → MQTT → Configure → Enable discovery). Also confirm your MQTT user has permission to subscribe to homeassistant/# — Mosquitto’s ACL configuration can block wildcard subscriptions.

TLS handshake fails: Use the Certificate Wizard to import the broker’s CA certificate. If your broker is behind a reverse proxy with a Let’s Encrypt cert, you may not need a custom CA, but you do need to make sure the hostname matches the certificate’s CN or SAN.

Want to see Zigbee device traffic: Add a subscription for zigbee2mqtt/# alongside homeassistant/#. MQTT Commander has a built-in preset for this too. You’ll see device state updates, bridge logs, and OTA update progress all in one place. The Zigbee2MQTT guide covers that workflow in detail.

What You Get

MQTT Commander is a one-time $2.99 purchase with no subscription. It runs on iOS and iPadOS 15 and later, supports MQTT 3.1.1 and 5.0, and handles QoS 0, 1, and 2. Connections can be plain TCP, TLS, WebSocket, or WSS. Wildcard and shared subscriptions both work. The payload inspector handles JSON, hex, Base64, images, and JSONPath queries.

For a broader overview of using MQTT on iPhone, see the MQTT on iPhone guide. To get started immediately, visit the iOS app page.