MQTT Connection Troubleshooting

Verify credential format, broker health, and network reachability so your LinknLink device can reliably connect to Home Assistant (HA) via MQTT.

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.

   

   
2. Success indicates the Broker IP, port, and credentials are correct.

   
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;

   

   
2. connected means same LAN/reachable;

   
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);

   
2. In Topic, enter home/# → Start listening;

   
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/;

2. In Connections, add a profile with name, Host (broker IP), Port (usually 1883), and credentials;

   
3. Save → Connect to browse the full topic tree for easier troubleshooting.

   

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