Control and Debug Zigbee2MQTT from iOS

Why a Mobile MQTT Client Helps with Zigbee2MQTT

Most Zigbee2MQTT setups live on a headless Raspberry Pi or a home server tucked in a closet. The web frontend is great when you are at a desk, but the moment you need to pair a new sensor while standing in the attic, or restart the bridge because something went silent, reaching for a laptop is the last thing you want.

A native iOS MQTT client gives you the broker connection directly in your pocket. MQTT Commander for iPhone and iPad connects over TCP, TLS, WebSocket, or WSS using MQTT 3.1.1 or 5.0, supports QoS 0, 1, and 2, and stores broker credentials in the iOS Keychain so nothing sensitive lands in a config file. It ships with a built-in preset for zigbee2mqtt/# so your first connection takes about thirty seconds.

This guide walks through the practical workflows: reading device state, pairing new devices, sending bridge commands, and avoiding accidental retained writes.

Subscribing to zigbee2mqtt/#

When you create a new connection in MQTT Commander, tap the Zigbee2MQTT preset. It pre-fills the wildcard subscription zigbee2mqtt/#, which matches every topic the bridge publishes—device state, bridge status, log output, and event notifications.

Once connected you will see a live stream of messages. Each row shows the topic, the first line of the payload, and the timestamp. Tap any message to open the payload inspector, which renders JSON with syntax highlighting, lets you diff two consecutive messages side-by-side, and can decode Base64 blobs or display image payloads inline. For numeric payloads you can run a JSONPath expression directly in the inspector to pull out a single field without scrolling through a large object.

If the stream is too noisy, narrow the subscription. Replace zigbee2mqtt/# with zigbee2mqtt/bridge/# to watch only bridge traffic, or zigbee2mqtt/FRIENDLY_NAME to focus on one device.

Reading Device State and Last Seen

Every device Zigbee2MQTT manages publishes its state to zigbee2mqtt/FRIENDLY_NAME. A typical motion sensor payload looks like this:

{
  "battery": 87,
  "linkquality": 204,
  "occupancy": false,
  "last_seen": "2026-05-30T08:14:22Z"
}

The last_seen field is the fastest way to spot a dead or unreachable device without opening the web frontend. Subscribe to the device topic, pull down to refresh retained messages, and check the timestamp. A device that went silent hours ago but shows a recent last_seen is probably just quiet; one with a stale timestamp needs attention.

MQTT Commander stores retained messages locally. The payload inspector shows a retained badge on any message the broker delivered with the retained flag set, so you always know whether you are looking at a live event or a cached last-known state.

Sending Bridge Commands

Permit Join

To pair a new Zigbee device, publish to zigbee2mqtt/bridge/request/permit_join. MQTT Commander includes a safe command template for this:

{"value": true}

Open the publish composer, select the permit_join template, review the payload, and tap Publish. The bridge opens the network for 254 seconds by default. When you are done pairing, publish the same topic with {"value": false} to close the network immediately.

Restarting the Bridge

If the bridge stops responding or you have just changed a configuration option that requires a restart, publish to zigbee2mqtt/bridge/request/restart:

{}

An empty object is a valid payload here. The bridge will restart and reconnect to the broker within a few seconds. Watch the zigbee2mqtt/bridge/state topic to confirm the transition from offline to online.

Other Bridge Requests

The same pattern applies to other bridge request topics: zigbee2mqtt/bridge/request/backup, zigbee2mqtt/bridge/request/coordinator_check, and zigbee2mqtt/bridge/request/touchlink/identify. Each one accepts a JSON payload and responds on the corresponding zigbee2mqtt/bridge/response/... topic, which you will see appear in your subscription stream within seconds.

Controlling Devices with .../set

To change device state—turn a light on, set a color temperature, or lock a door—publish to zigbee2mqtt/FRIENDLY_NAME/set. For a dimmable bulb named living_room_lamp:

{"state": "ON", "brightness": 180, "color_temp": 370}

For a smart plug you only need:

{"state": "OFF"}

MQTT Commander’s publish composer lets you save these as reusable templates with a name and description. Build your device command once, name it something like “Living room lamp—evening”, and it appears in your template list for every future session.

Publish Templates and Avoiding Accidental Retained Writes

The publish composer is intentionally draft-first. You fill in the topic and payload, choose a QoS level, and toggle the retain flag before anything leaves the device. A yellow Retain warning banner appears whenever the retain flag is enabled, and if you publish a retained message MQTT Commander will ask for a second confirmation before sending.

Deleting a retained message is equally deliberate. Select a retained message in the topic list, tap Delete Retained, and confirm the prompt. This publishes a zero-byte retained message to clear the broker’s cache without leaving stale state behind.

If you are experimenting with zigbee2mqtt/FRIENDLY_NAME/set commands, leave the retain flag off. Device command topics are not meant to be retained, and a stale retained command can cause unexpected behavior after a bridge restart.

Troubleshooting Connection Issues

If MQTT Commander cannot reach your broker, open Connection Doctor. It runs a staged diagnostic: DNS resolution, TCP handshake, TLS certificate validation (if applicable), MQTT CONNECT packet, and finally a subscribe/publish round-trip. Each stage reports pass or fail with a plain-language explanation, so you know immediately whether the problem is a firewall rule, a wrong port, or an expired certificate.

For TLS connections, the built-in Certificate Wizard walks through importing a CA certificate, client certificate, and private key for mTLS authentication. Credentials are stored in the iOS Keychain and never written to disk in plaintext.

If your Zigbee2MQTT broker is on the same local network but you are away from home, check that your MQTT broker is reachable over your VPN or via an MQTTS port exposed through your router. Connection Doctor will tell you exactly which step fails.

Going Further

Once you are comfortable watching zigbee2mqtt/# and sending bridge commands, explore what else you can do from iOS:

• Pair new devices by using permit_join from the publish template without touching a keyboard.
• Monitor device link quality across your mesh by comparing linkquality values in the payload inspector.
• Catch firmware update events on zigbee2mqtt/bridge/event before they complete.
• Combine MQTT Commander with Home Assistant for a deeper view—see debugging Home Assistant MQTT from iPhone and getting started with MQTT on iPhone.

MQTT Commander is a $2.99 one-time purchase for iOS 15 and iPadOS 15 and later, with no subscription. Broker data stays on your device; the only outbound telemetry is anonymous crash reporting through Sentry and anonymous usage counts through Aptabase, both of which you can opt out of in Settings.