Debug Home Assistant MQTT from Your iPhone

Why Debug Home Assistant Over MQTT from Your Phone

Home Assistant’s MQTT integration does a lot, and it hides most of it. 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: which messages flow, what the payloads look like, and whether the broker delivers them at all.

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 in a home office. It works less well when your Zigbee coordinator sits in a closet, your broker runs on a Raspberry Pi in another room, or you want to check a topic from the couch.

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.

Finding Your Broker Address

Home Assistant users 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, then enter the same values.

If you’re not sure which port is open, the Connection Doctor runs staged diagnostics: it checks DNS resolution, TCP reachability, and the MQTT handshake as distinct stages, 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

The app stores credentials in the iOS Keychain, and they never leave your device. Broker data stays on-device: 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 Manager 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. Retained config messages start arriving:

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, which helps 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. A retained command payload can cause unexpected behavior on reconnect. Confirm and publish. If the light responds, the device and broker are healthy; if it doesn’t, the problem sits upstream in your automation or HA integration rather than 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, a badge in the topic list marks retained messages. 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 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 points to a hostname typo or split-horizon DNS. A TCP failure on port 1883 points to a firewall rule on the broker host or router. A failed MQTT handshake with an authentication error means the 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 Manager 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 free to download, with no subscription and an optional $4.99 one-time Pro unlock. It runs on iOS and iPadOS 17 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, visit the iOS app page.