> For the complete documentation index, see [llms.txt](https://kb.linknlink.com/kb/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kb.linknlink.com/kb/smart-home-devices/emotion-series/mqtt-connection-troubleshooting.md).

# 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.