> For the complete documentation index, see [llms.txt](https://docs.chirpwireless.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chirpwireless.io/connectors/mqtt-connector/cloud-mqtt.md). # Cloud MQTT Cloud MQTT is the simpler of the two MQTT paths into Chirp. You don't run a broker yourself — Chirp provisions a managed MQTT broker for the connector, gives you the endpoint and credentials, and you point your devices (or Zigbee2MQTT) at it. That's the whole architecture. For most homes this is the right choice. You're not running a server in the basement, you're not exposing a port on your router, and you're not managing TLS certificates. You install Zigbee2MQTT on the machine that owns your USB Zigbee dongle, paste in four credentials, and the data starts flowing. ## When to choose Cloud MQTT * You don't already have an MQTT broker. * Your devices live on a home network behind NAT, and you'd rather not poke a hole through your router or rent a VPS. * You want the simplest possible setup that works. If you already operate your own broker — Mosquitto on a home server, a HiveMQ Cloud account, an MQTT broker on a Raspberry Pi sitting alongside Home Assistant — see [External MQTT](/connectors/mqtt-connector/external-mqtt.md). Both paths produce the same end result inside Chirp; the difference is who owns the broker. ## Creating the connector 1. Open **Connectors** in Chirp's sidebar. 2. Tap **Add connector**. 3. Pick **Cloud MQTT** from the connector type list. 4. Give it a **Name** — something memorable like `Home Zigbee Hub` or `Garden Sensors`. 5. Tap **Add**. Chirp provisions a broker endpoint and shows four values: | Field | What it is | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Broker URL** | The complete address of Chirp's broker for this connector. Uses TLS on port 1884 (not the default 1883). Copy it as-is — including the `mqtts://` scheme. | | **Topic prefix** | Every message published through this connector must start with this path. It's how the broker keeps your data separate from everyone else's. Looks like `iot/{org}/{connection}` — two unique segments identifying your organization and this connector. | | **Username** | Generated by Chirp. Copy it exactly — case and characters matter. | | **Password** | A long random secret. **Shown once.** Copy it immediately and save it somewhere you can find later. If you close the dialog without saving the password, you'll need to rotate the credentials and reconfigure your devices. | There's no recovering the original password later — Chirp doesn't keep it readable. Rotation is the only path back if you've lost it. ## Connecting Zigbee2MQTT to a Cloud MQTT connector In Zigbee2MQTT's `configuration.yaml`, the four credentials map to: ```yaml mqtt: base_topic: iot/{your-org-segment}/{your-connection-segment}/zigbee2mqtt server: mqtts://mqtt-iot.chirpwireless.io:1884 user: {username from Chirp} password: {password from Chirp} ``` A few things to notice: * **`base_topic` adds `/zigbee2mqtt` to the Topic prefix.** Z2M automatically appends `/{friendlyName}` for each device, so your living-room sensor ends up publishing to `iot/{org}/{connection}/zigbee2mqtt/LivingRoomSensor`. Chirp strips the prefix internally, leaving the device-level topic as `zigbee2mqtt/LivingRoomSensor` — which is what you'll match in the Device ID Topic field when registering the device. * **`server` uses `mqtts://` and port 1884.** The `mqtts://` scheme tells Z2M to use TLS automatically. You don't need to provide a CA certificate — the broker uses a publicly-trusted certificate. * **The username and password are the ones from Chirp**, not anything Z2M generates. For the full Zigbee2MQTT setup including the Docker Compose template and `configuration.yaml` example, see [Setting up Zigbee2MQTT](/connectors/mqtt-connector/zigbee2mqtt.md). ## Connecting other MQTT devices Anything that publishes MQTT can use the same credentials — an ESP32 you wrote firmware for, a Tasmota smart plug, an MQTT-publishing weather station. Configure the device's MQTT settings: * **Broker / server URL:** the Broker URL value from Chirp, including the `mqtts://` scheme and port 1884. * **Username / Password:** the credentials Chirp generated. * **Topic to publish to:** must start with the Topic prefix. So if you'd normally publish to `weather/outside`, with Chirp you publish to `{Topic prefix}/weather/outside`. When you register the device in Chirp, the Device ID Topic field uses the device-level portion only — Chirp strips the prefix automatically. ## Verifying the connection After Z2M (or your device) starts up: 1. Open the connector's detail page in Chirp. 2. Look at **Last data received**. Within a few seconds of Z2M connecting, this field updates with a timestamp. The first message Z2M publishes is its own bridge status (`{base_topic}/bridge/state`) — it's how you know the broker accepted the connection, even before any sensor has reported. If **Last data received** stays empty for more than a minute, see [Troubleshooting](/connectors/mqtt-connector/troubleshooting.md). ## Rotating credentials If the password is compromised or you've lost it: 1. Open the connector in Chirp. 2. In edit mode, use the regenerate option for the password. 3. Update the password in your device or Z2M `configuration.yaml`. 4. Restart the device or Z2M. The username and Topic prefix don't change on rotation — only the password. ## Limits Cloud MQTT connectors are unlimited per home. If you want separate connectors for different device groups (one for the indoor Zigbee mesh, one for the garden sensors, one for the workshop), create as many as you need — each gets its own credentials and topic prefix. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.chirpwireless.io/connectors/mqtt-connector/cloud-mqtt.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.