Skip to content
Quick start Product guide

Troubleshooting

WizDash connection and widget troubleshooting checklist covering BLE and local WiFi scans, MQTT topic segments, case-sensitive JSON keys, and plan limits
Quick checklist for diagnosing BLE/WiFi discovery, MQTT topic mismatches, JSON key case sensitivity, and plan limits.

Confirm that the board is running a sketch generated for BLE. Turn on Bluetooth. On Android 11 and earlier, allow location permission as well. Bring the phone close to the board, and make sure another phone is not already connected to it.

Confirm that the phone and the ESP32 are joined to the same WiFi network. A classic ESP32 uses 2.4 GHz WiFi only. A guest network, or a router that isolates its clients, can prevent the two from seeing each other. You can also read the board’s IP address in the Serial Monitor and enter it by hand.

WizDash Bluetooth Devices scan screen listing nearby advertising ESP32 boards
BLE scan check: confirm the board is advertising and not already connected to another phone.
WizDash WiFi Connection screen showing Auto Scan results and Manual IP input
WiFi scan check: if router settings block mDNS/UDP discovery, enter the board’s IP and port 81 under Manual IP.

The MQTT test succeeds, but no data arrives

Section titled “The MQTT test succeeds, but no data arrives”

The test only shows that the phone can reach the broker. Confirm that the board can reach it too. The device ID, username, TLS setting, and port must match the values flashed to the board. When a username is set, the topic includes it. When no username is set, that part of the topic is left out. A single difference on either side prevents the two from meeting.

WizDash MQTT Connection Settings lower section showing port 8883, TLS toggle, and Connection succeeded message
Check broker settings: “Connection succeeded” confirms the phone reached the broker; verify the board uses the exact same username, port, and TLS setting.
WizDash Device Info sheet showing the bound Device ID and broker address
Check Device Info: confirm the bound Device ID matches the ID printed by your board in the Serial Monitor.

The JSON key must match the firmware exactly, including case. The board must send one complete JSON object. A display such as a gauge expects a number, so a text value will not move it.

The free version allows 10 functional widgets in a project. Each widget type holds at most 20.

WizDash widget settings dialog showing the case-sensitive JSON key field
Check JSON Key: double-tap the widget to confirm its JSON key matches your firmware character for character, including case.
WizDash Add Widget picker sheet showing the 8 / 10 free functional widget counter
Check widget quota: the top-right badge of the Add Widget sheet shows how many functional widgets are used in the project.

The file must be within 2 MB and must be a layout exported by WizDash. A layout with more than 10 functional widgets requires the full version.

Paste firmware URL is on the menu of an MQTT project, including before the phone has connected. Sending the update requires the phone to be connected to that project’s broker. The board must be running the sketch variant generated with OTA included.