# MQTT Connection Troubleshooting

### Step 1: Credential format

* **Username/password** must be **alphanumeric only** (A–Z, a–z, 0–9), with no spaces or special characters.
* If special characters were used before, update **both** the broker and the device to a new alphanumeric pair.

### Step 2: Confirm the MQTT broker

1. In HA: **Settings → Devices & Services → Add Integration → search “MQTT” → Configure**.<br>

   <figure><img src="/files/wU97Hhg6z7yNZWSJVcJT" alt=""><figcaption></figcaption></figure>

   <figure><img src="/files/D2JY3PJG65ootxc2IhJO" alt=""><figcaption></figcaption></figure>
2. Success indicates the **Broker IP, port, and credentials** are correct.<br>

   <figure><img src="/files/jcazAMlJoN3uiONmxata" alt=""><figcaption></figcaption></figure>
3. On failure:
   * **HA OS**: install and enable **Mosquitto broker** from the **Add-on Store**;
   * Other setups: ensure Mosquitto is running and listening on **1883** (when TLS is off).

### Step 3: Verify network connectivity (device ↔ HA)

1. Add the **Ping (ICMP)** integration in HA and enter the **LinknLink device IP**;<br>

   <figure><img src="/files/KMxFV0iJysI21C96YSzE" alt=""><figcaption></figcaption></figure>

   <figure><img src="/files/AH7etgnEuFNmaJehPNwj" alt=""><figcaption></figcaption></figure>
2. **connected** means same LAN/reachable;<br>

   <figure><img src="/files/kUPfaH0LEvMR7uoKdVGS" alt=""><figcaption></figcaption></figure>
3. If it fails: check different subnets/VLANs, **AP isolation/guest network**, or router/firewall rules blocking internal traffic.

### Step 4: Enter MQTT settings on the LinknLink device by using LinknLink App

* **Broker IP**, **port (1883 by default)**, **username/password**;
* Save and Check HA MQTT integration device list

### Step 5: Confirm HA receives messages

1. Open **Developer Tools → MQTT** (or the MQTT integration’s **Listen to a topic**);<br>

   <figure><img src="/files/5xbuVWpEMB91k1wrpEea" alt=""><figcaption></figcaption></figure>
2. In **Topic**, enter **`home/#`** → **Start listening**;<br>

   <figure><img src="/files/Aj4535VktqXCliCVQCT2" alt=""><figcaption></figcaption></figure>
3. If you see topics/payloads from the device, the connection and messaging are good.

### Step 6: Deep-dive with MQTT Explorer (optional)

1. Download **MQTT Explorer** from [**https://mqtt-explorer.com/**](https://mqtt-explorer.com/);
2. In **Connections**, add a profile with name, **Host** (broker IP), **Port** (usually **1883**), and credentials;<br>

   <figure><img src="/files/HtCA1iMy5I9SVp2Hb1ot" alt=""><figcaption></figcaption></figure>
3. **Save → Connect** to browse the full topic tree for easier troubleshooting.<br>

   <figure><img src="/files/wuioCjBIarK2Hl3Jt6Ci" alt=""><figcaption></figcaption></figure>

> Once these checks pass, the LinknLink device should connect to MQTT without issues.


---

# Agent Instructions: 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:

```
GET https://kb.linknlink.com/kb/smart-home-devices/emotion-series/mqtt-connection-troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.