← Back to Garden
evergreen ·
troubleshooting esp32 mqtt wifi debugging

Troubleshooting Guide

Common issues encountered during TSI-Telemetry development and their solutions.

Compilation Issues

Sketch Too Large (132% of space)

Error:

Sketch uses 1733367 bytes (132%) of program storage space. Maximum is 1310720 bytes.

Cause: WiFi + BLE together use a lot of flash space.

Solution: Use the "huge_app" partition scheme:

FQBN = esp32:esp32:esp32:PartitionScheme=huge_app

Or in arduino-cli:

arduino-cli compile --fqbn esp32:esp32:esp32:PartitionScheme=huge_app firmware/tsi

This increases app space from 1.3MB to 3MB by removing OTA support.

PubSubClient.h Not Found

Error:

fatal error: PubSubClient.h: No such file or directory

Solution:

arduino-cli lib install "PubSubClient"
arduino-cli lib list  # Verify it's installed

WiFi Issues

WiFi Status Code 1 (WL_NO_SSID_AVAIL)

Error:

WiFi connection timeout!
WiFi status code: 1

Cause: ESP32 can't find the network. Most common reason: Phone hotspot is on 5GHz.

Solution: ESP32 only supports 2.4GHz WiFi!

  • iPhone: Settings → Personal Hotspot → Enable "Maximize Compatibility"
  • Android: Settings → Hotspot → Band → Select "2.4 GHz"

WiFi Status Code 4 (WL_CONNECT_FAILED)

Cause: Wrong password.

Solution: Double-check password in Config.h. Watch for:

  • Special characters that need escaping
  • Trailing spaces
  • Case sensitivity

WiFi Status Code 6 (WL_DISCONNECTED)

Cause: Network found but connection dropped.

Solution: Usually transient. Code should auto-reconnect.

"wifi:sta is connecting, cannot set config"

Cause: Trying to reconnect while already connecting.

Solution: Add disconnect before reconnect:

WiFi.disconnect(true);
delay(100);
WiFi.begin(ssid, password);

MQTT Issues

MQTT rc=-2 (MQTT_CONNECT_FAILED)

Causes:

  1. Empty or wrong MQTT_SERVER
  2. Can't resolve DNS
  3. TLS handshake failing
  4. Port 8883 blocked

Debug steps:

  1. Check Config.h has the full server URL:
#define MQTT_SERVER "xxxxx.s1.eu.hivemq.cloud"  // Not empty!
  1. Test from computer first:
mosquitto_pub -h xxxxx.s1.eu.hivemq.cloud -p 8883 \
  -u esp32 -P 'password' --capath /etc/ssl/certs/ \
  -t "test" -m "hello"
  1. If that works but ESP32 doesn't, try adding DNS:
WiFi.config(INADDR_NONE, INADDR_NONE, INADDR_NONE, IPAddress(8,8,8,8));

MQTT rc=-4 (MQTT_CONNECTION_TIMEOUT)

Cause: Server not responding in time.

Solution: Increase timeout:

espClient.setTimeout(15000);  // 15 seconds

MQTT rc=4 (MQTT_CONNECT_BAD_CREDENTIALS)

Cause: Wrong username or password.

Solution: Verify in HiveMQ Cloud → Access Management.

MQTT rc=5 (MQTT_CONNECT_UNAUTHORIZED)

Cause: User doesn't have permission.

Solution: Check HiveMQ Cloud permissions for the user.

BLE Issues

BLE Connection Fails

Symptoms: "Connection failed!" after "Connecting to OBD2 adapter..."

Causes:

  1. Wrong MAC address in Config.h
  2. OBD adapter not powered/plugged in
  3. Another device connected to adapter

Solutions:

  1. Verify MAC address matches your adapter
  2. Make sure car ignition is ON (OBD port needs power)
  3. Disconnect phone BLE apps (Torque, OBD2 apps)

ELM327 Init Fails

Symptoms: "ELM327 init failed!"

Cause: Adapter not responding to AT commands.

Solutions:

  1. Try reset: Unplug adapter, wait 10 seconds, replug
  2. Check BLE UUIDs match your adapter (some clones differ)

Serial Monitor Issues

Garbage Output

Cause: Baud rate mismatch.

Solution: Make sure monitor uses 115200:

arduino-cli monitor -p /dev/cu.usbserial-* -c baudrate=115200

No Output

Causes:

  1. Wrong port
  2. ESP32 in boot loop (crash)

Solutions:

  1. Check port: ls /dev/cu.usb*
  2. Watch for repeated reboots (indicates crash)

Grafana Issues

"No Data" in Panels

Causes:

  1. Time range too narrow
  2. Query syntax error
  3. No data in database

Debug:

-- Check if data exists
SELECT COUNT(*) FROM car_metrics;

-- Check recent data
SELECT * FROM car_metrics ORDER BY time DESC LIMIT 5;

Can't Access Grafana Remotely

Cause: Grafana only listening on localhost.

Solution: Edit /opt/homebrew/etc/grafana/grafana.ini:

[server]
http_addr = 0.0.0.0

Then restart: brew services restart grafana

Database Issues

TimescaleDB Container Not Running

Check:

docker ps | grep timescaledb

Start:

docker start timescaledb

Can't Connect to TimescaleDB

Check port:

psql -h localhost -p 5433 -U postgres -d telemetry

Password: telemetry123

Bridge Issues

Bridge Not Receiving Messages

Check:

  1. Is bridge running? ps aux | grep mqtt_to_timescale
  2. Is HiveMQ receiving? Check HiveMQ Cloud web console
  3. Topic match? Must be exactly car/telemetry

Bridge Crashes on Insert

Cause: Missing column in database.

Solution: Add missing column:

ALTER TABLE car_metrics ADD COLUMN battery_voltage DECIMAL(4,2);

Quick Diagnostic Commands

# Check all services
docker ps                          # TimescaleDB running?
brew services list                 # Grafana running?
ps aux | grep mqtt_to_timescale    # Bridge running?

# Test MQTT
mosquitto_pub -h YOUR_SERVER -p 8883 -u USER -P PASS \
  --capath /etc/ssl/certs/ -t "car/telemetry" -m '{"rpm":1234}'

# Check database
psql -h localhost -p 5433 -U postgres -d telemetry \
  -c "SELECT * FROM car_metrics ORDER BY time DESC LIMIT 1;"

# Check ESP32 serial
arduino-cli monitor -p /dev/cu.usbserial-* -c baudrate=115200