21  Interactive Troubleshooting Flowchart

Step-by-Step Debugging for Common IoT Issues

21.1 IoT Troubleshooting Guide

TipSystematic Debugging

Select your problem category and follow the interactive flowchart. Each step includes diagnostic commands and solutions.

---

21.2 Select Problem Category

viewof problemCategory = Inputs.radio(
  ["Wi-Fi/Network", "MQTT/Messaging", "Sensor Issues", "Power/Battery", "Serial/Debug"],
  {label: "What's the problem?", value: "Wi-Fi/Network"}
)

---

21.3 Troubleshooting Flowchart

troubleshootingTrees = {
  return {
    "Wi-Fi/Network": {
      title: "Wi-Fi & Network Troubleshooting",
      color: "#3498DB",
      steps: [
        {
          id: "wifi-1",
          question: "Does the device power on and boot?",
          yes: "wifi-2",
          no: "wifi-power-fix",
          diagnostic: "Check LED indicators or serial output",
          code: "// Check boot - open Serial Monitor at 115200 baud"
        },
        {
          id: "wifi-power-fix",
          type: "solution",
          title: "Power Issue",
          solutions: [
            "Check USB cable - use data cable, not charge-only",
            "Try different USB port or power supply",
            "Verify voltage: ESP32 needs 3.3V, NodeMCU needs 5V via USB",
            "Check for short circuits on the board"
          ],
          code: "// Measure voltage at VIN and 3.3V pins with multimeter"
        },
        {
          id: "wifi-2",
          question: "Does Wi-Fi.begin() return without hanging?",
          yes: "wifi-3",
          no: "wifi-begin-fix",
          diagnostic: "Add timeout to Wi-Fi connection",
          code: `Wi-Fi.begin(ssid, password);
int timeout = 0;
while (Wi-Fi.status() != WL_CONNECTED && timeout < 20) {
  delay(500);
  Serial.print(".");
  timeout++;
}
Serial.println(Wi-Fi.status() == WL_CONNECTED ? "Connected!" : "Failed");`
        },
        {
          id: "wifi-begin-fix",
          type: "solution",
          title: "Wi-Fi.begin() Hanging",
          solutions: [
            "Check SSID and password for typos (case-sensitive!)",
            "Ensure 2.4GHz network (ESP32/8266 don't support 5GHz)",
            "Try Wi-Fi.mode(WIFI_STA) before begin()",
            "Add Wi-Fi.disconnect() before begin() to clear old state",
            "Check if router has MAC filtering enabled"
          ],
          code: `Wi-Fi.mode(WIFI_STA);
Wi-Fi.disconnect();
delay(100);
Wi-Fi.begin(ssid, password);`
        },
        {
          id: "wifi-3",
          question: "Does Wi-Fi.status() return WL_CONNECTED?",
          yes: "wifi-4",
          no: "wifi-status-fix",
          diagnostic: "Print Wi-Fi status code",
          code: `Serial.print("Wi-Fi Status: ");
Serial.println(Wi-Fi.status());
// 0=IDLE, 1=NO_SSID_AVAIL, 3=CONNECTED, 4=CONNECT_FAILED, 6=DISCONNECTED`
        },
        {
          id: "wifi-status-fix",
          type: "solution",
          title: "Wi-Fi Not Connecting",
          solutions: [
            "Status 1 (NO_SSID_AVAIL): SSID not found - check spelling, range",
            "Status 4 (CONNECT_FAILED): Wrong password or auth issue",
            "Status 6 (DISCONNECTED): Weak signal - move closer to router",
            "Try static IP if DHCP is slow",
            "Check router logs for connection attempts"
          ],
          code: `// Try static IP
IPAddress ip(192, 168, 1, 100);
IPAddress gateway(192, 168, 1, 1);
IPAddress subnet(255, 255, 255, 0);
Wi-Fi.config(ip, gateway, subnet);
Wi-Fi.begin(ssid, password);`
        },
        {
          id: "wifi-4",
          question: "Can you ping the device from your computer?",
          yes: "wifi-5",
          no: "wifi-ping-fix",
          diagnostic: "Get IP and try ping",
          code: `Serial.print("IP Address: ");
Serial.println(Wi-Fi.localIP());
// Then run: ping <ip-address> from terminal`
        },
        {
          id: "wifi-ping-fix",
          type: "solution",
          title: "Device Not Responding to Ping",
          solutions: [
            "Ensure computer is on same network/subnet",
            "Check if router has AP isolation enabled (disable it)",
            "Firewall on computer might block ICMP",
            "Try from another device on the network"
          ],
          code: "// Check subnet - both devices should be 192.168.x.x"
        },
        {
          id: "wifi-5",
          question: "Can the device reach the internet?",
          yes: "wifi-success",
          no: "wifi-internet-fix",
          diagnostic: "Try HTTP request to known server",
          code: `HTTPClient http;
http.begin("http://httpbin.org/ip");
int code = http.GET();
Serial.printf("HTTP Response: %d\\n", code);
if (code > 0) Serial.println(http.getString());
http.end();`
        },
        {
          id: "wifi-internet-fix",
          type: "solution",
          title: "No Internet Access",
          solutions: [
            "Check DNS - try IP address instead of hostname",
            "Verify gateway is correct (usually .1 or .254)",
            "Check if router has internet access",
            "Some networks require captive portal login"
          ],
          code: `// Test with IP instead of hostname
http.begin("http://142.250.185.238");  // Google IP`
        },
        {
          id: "wifi-success",
          type: "success",
          title: "Network is Working!",
          message: "Your Wi-Fi connection is functioning correctly. If you're still having issues, they may be application-level (MQTT, HTTP, etc.)"
        }
      ]
    },

    "MQTT/Messaging": {
      title: "MQTT Troubleshooting",
      color: "#9B59B6",
      steps: [
        {
          id: "mqtt-1",
          question: "Is Wi-Fi connected first?",
          yes: "mqtt-2",
          no: "mqtt-wifi-fix",
          diagnostic: "Check Wi-Fi status before MQTT",
          code: `if (Wi-Fi.status() != WL_CONNECTED) {
  Serial.println("Wi-Fi not connected!");
  return;
}`
        },
        {
          id: "mqtt-wifi-fix",
          type: "solution",
          title: "Wi-Fi Required First",
          solutions: [
            "MQTT requires network connectivity",
            "Ensure Wi-Fi is connected before mqtt.connect()",
            "See Wi-Fi troubleshooting flowchart"
          ],
          code: "// Connect Wi-Fi first, then MQTT"
        },
        {
          id: "mqtt-2",
          question: "Does mqtt.connect() return true?",
          yes: "mqtt-3",
          no: "mqtt-connect-fix",
          diagnostic: "Check connection result and state",
          code: `if (mqtt.connect("client-id")) {
  Serial.println("Connected!");
} else {
  Serial.print("Failed, rc=");
  Serial.println(mqtt.state());
}`
        },
        {
          id: "mqtt-connect-fix",
          type: "solution",
          title: "MQTT Connection Failed",
          solutions: [
            "State -4: Connection timeout - check broker address/port",
            "State -3: Connection lost - network issue",
            "State -2: Connect failed - wrong broker/port",
            "State -1: Disconnected - call connect() again",
            "State 4: Bad credentials - check username/password",
            "State 5: Unauthorized - check ACL permissions"
          ],
          code: `// Common broker settings
mqtt.setServer("broker.hivemq.com", 1883);  // Public broker
// OR
mqtt.setServer("test.mosquitto.org", 1883);
// For auth:
mqtt.connect("client-id", "username", "password");`
        },
        {
          id: "mqtt-3",
          question: "Does mqtt.loop() get called regularly?",
          yes: "mqtt-4",
          no: "mqtt-loop-fix",
          diagnostic: "mqtt.loop() must be in main loop",
          code: `void loop() {
  if (!mqtt.connected()) {
    reconnect();
  }
  mqtt.loop();  // MUST be called!
  // ... rest of code
}`
        },
        {
          id: "mqtt-loop-fix",
          type: "solution",
          title: "Missing mqtt.loop()",
          solutions: [
            "mqtt.loop() processes incoming messages and keepalives",
            "Must be called frequently (every loop iteration)",
            "Without it, connection will timeout after ~15 seconds",
            "Don't use long delay() calls that block the loop"
          ],
          code: `// Use non-blocking timing instead of delay()
unsigned long lastPublish = 0;
void loop() {
  mqtt.loop();
  if (millis() - lastPublish > 5000) {
    mqtt.publish("topic", "message");
    lastPublish = millis();
  }
}`
        },
        {
          id: "mqtt-4",
          question: "Does mqtt.publish() return true?",
          yes: "mqtt-5",
          no: "mqtt-publish-fix",
          diagnostic: "Check publish return value",
          code: `if (mqtt.publish("test/topic", "hello")) {
  Serial.println("Published!");
} else {
  Serial.println("Publish failed!");
}`
        },
        {
          id: "mqtt-publish-fix",
          type: "solution",
          title: "Publish Failed",
          solutions: [
            "Check if still connected: mqtt.connected()",
            "Topic might be too long (max ~128 chars safe)",
            "Payload might be too large (default 256 bytes)",
            "Increase buffer: mqtt.setBufferSize(512)"
          ],
          code: `mqtt.setBufferSize(1024);  // Increase buffer
// Check connection before publish
if (!mqtt.connected()) {
  Serial.println("Reconnecting...");
  mqtt.connect("client-id");
}`
        },
        {
          id: "mqtt-5",
          question: "Are subscribed messages being received?",
          yes: "mqtt-success",
          no: "mqtt-subscribe-fix",
          diagnostic: "Check callback and subscription",
          code: `void callback(char* topic, byte* payload, unsigned int length) {
  Serial.print("Message on ");
  Serial.println(topic);
}
// In setup:
mqtt.setCallback(callback);
mqtt.subscribe("test/topic");`
        },
        {
          id: "mqtt-subscribe-fix",
          type: "solution",
          title: "Not Receiving Messages",
          solutions: [
            "setCallback() must be called before connect()",
            "subscribe() must be called after successful connect()",
            "Re-subscribe after reconnection",
            "Check topic matches exactly (case-sensitive)",
            "Use # wildcard to debug: mqtt.subscribe('test/#')"
          ],
          code: `void reconnect() {
  while (!mqtt.connected()) {
    if (mqtt.connect("client-id")) {
      mqtt.subscribe("my/topic");  // Re-subscribe!
    } else {
      delay(5000);
    }
  }
}`
        },
        {
          id: "mqtt-success",
          type: "success",
          title: "MQTT is Working!",
          message: "Your MQTT connection is functioning correctly. Messages are being published and received."
        }
      ]
    },

    "Sensor Issues": {
      title: "Sensor Troubleshooting",
      color: "#E67E22",
      steps: [
        {
          id: "sensor-1",
          question: "Is the sensor powered correctly?",
          yes: "sensor-2",
          no: "sensor-power-fix",
          diagnostic: "Check VCC and GND connections",
          code: "// Measure voltage at sensor VCC pin - should match sensor spec"
        },
        {
          id: "sensor-power-fix",
          type: "solution",
          title: "Sensor Power Issue",
          solutions: [
            "Check sensor voltage requirement (3.3V vs 5V)",
            "ESP32 3.3V pin max ~500mA total",
            "Use external power for high-current sensors",
            "Add decoupling capacitor (100nF) near VCC",
            "Check for loose connections"
          ],
          code: "// Most sensors work at 3.3V, check datasheet"
        },
        {
          id: "sensor-2",
          question: "For I2C: Does I2C scanner find the device?",
          yes: "sensor-3",
          no: "sensor-i2c-fix",
          diagnostic: "Run I2C scanner",
          code: `#include <Wire.h>
void setup() {
  Serial.begin(115200);
  Wire.begin();
  for (byte addr = 1; addr < 127; addr++) {
    Wire.beginTransmission(addr);
    if (Wire.endTransmission() == 0) {
      Serial.printf("Found at 0x%02X\\n", addr);
    }
  }
}`
        },
        {
          id: "sensor-i2c-fix",
          type: "solution",
          title: "I2C Device Not Found",
          solutions: [
            "Check SDA/SCL connections (ESP32: SDA=21, SCL=22)",
            "Add pull-up resistors (4.7k-10k to 3.3V)",
            "Check address - some sensors have configurable addresses",
            "Reduce I2C speed: Wire.setClock(100000)",
            "Check for address conflicts"
          ],
          code: `// Try different pins
Wire.begin(SDA_PIN, SCL_PIN);
// Slow down I2C
Wire.setClock(100000);`
        },
        {
          id: "sensor-3",
          question: "Does the sensor library initialize?",
          yes: "sensor-4",
          no: "sensor-init-fix",
          diagnostic: "Check begin() return value",
          code: `if (!sensor.begin()) {
  Serial.println("Sensor init failed!");
  while(1);
}`
        },
        {
          id: "sensor-init-fix",
          type: "solution",
          title: "Sensor Init Failed",
          solutions: [
            "Check if correct library is installed",
            "Verify sensor I2C address matches library default",
            "Try specifying address: sensor.begin(0x76)",
            "Check for library version compatibility",
            "Reset sensor power (turn off, wait 1s, turn on)"
          ],
          code: `// Specify address explicitly
if (!bme.begin(0x76)) {  // or 0x77
  Serial.println("Could not find BME280");
}`
        },
        {
          id: "sensor-4",
          question: "Are readings reasonable (not NaN or extreme)?",
          yes: "sensor-success",
          no: "sensor-reading-fix",
          diagnostic: "Print raw values",
          code: `float value = sensor.readValue();
Serial.printf("Raw: %.2f\\n", value);
if (isnan(value)) Serial.println("NaN detected!");`
        },
        {
          id: "sensor-reading-fix",
          type: "solution",
          title: "Bad Sensor Readings",
          solutions: [
            "NaN: Communication issue or sensor not ready",
            "All zeros: Check power and connections",
            "Extreme values: Check units and scaling",
            "Noisy readings: Add averaging or filtering",
            "Stuck values: Sensor might need calibration or reset"
          ],
          code: `// Add averaging
float readAveraged(int samples) {
  float sum = 0;
  for (int i = 0; i < samples; i++) {
    sum += analogRead(SENSOR_PIN);
    delay(10);
  }
  return sum / samples;
}`
        },
        {
          id: "sensor-success",
          type: "success",
          title: "Sensor is Working!",
          message: "Your sensor is functioning correctly and returning valid readings."
        }
      ]
    },

    "Power/Battery": {
      title: "Power & Battery Troubleshooting",
      color: "#27AE60",
      steps: [
        {
          id: "power-1",
          question: "Does the device work when USB-powered?",
          yes: "power-2",
          no: "power-usb-fix",
          diagnostic: "Test with USB first",
          code: "// Connect to computer USB and check serial output"
        },
        {
          id: "power-usb-fix",
          type: "solution",
          title: "USB Power Issue",
          solutions: [
            "Try different USB cable (data cable, not charge-only)",
            "Try different USB port or computer",
            "Check for short circuits on the board",
            "Measure current draw - might exceed USB limit (500mA)"
          ],
          code: "// USB typically provides 500mA max"
        },
        {
          id: "power-2",
          question: "Is battery voltage in correct range?",
          yes: "power-3",
          no: "power-battery-fix",
          diagnostic: "Measure battery with multimeter",
          code: "// LiPo: 3.0V (empty) to 4.2V (full)"
        },
        {
          id: "power-battery-fix",
          type: "solution",
          title: "Battery Voltage Issue",
          solutions: [
            "Below 3.0V: Battery is dead/damaged - replace",
            "Above 4.2V: Overcharged - dangerous, stop using",
            "Check polarity - reversed will damage board",
            "Use battery with protection circuit (BMS)"
          ],
          code: "// Safe LiPo range: 3.0V - 4.2V"
        },
        {
          id: "power-3",
          question: "Does voltage drop significantly under load?",
          yes: "power-load-fix",
          no: "power-4",
          diagnostic: "Measure voltage while device runs",
          code: "// Measure at VIN while Wi-Fi is active"
        },
        {
          id: "power-load-fix",
          type: "solution",
          title: "Voltage Drop Under Load",
          solutions: [
            "Battery can't supply enough current",
            "Add larger capacitor (100-1000uF) near VIN",
            "Use battery with higher discharge rate (C rating)",
            "Reduce peak current: stagger operations",
            "Check for high resistance in connections"
          ],
          code: `// Stagger high-power operations
Wi-Fi.begin(ssid, pass);
delay(100);  // Let Wi-Fi stabilize
// Then start sensors...`
        },
        {
          id: "power-4",
          question: "Is deep sleep working correctly?",
          yes: "power-5",
          no: "power-sleep-fix",
          diagnostic: "Check sleep current",
          code: `esp_sleep_enable_timer_wakeup(10 * 1000000);  // 10 seconds
esp_deep_sleep_start();
// Measure current during sleep - should be ~10uA`
        },
        {
          id: "power-sleep-fix",
          type: "solution",
          title: "Deep Sleep Not Working",
          solutions: [
            "Disable Wi-Fi/BT before sleep: Wi-Fi.mode(WIFI_OFF)",
            "Some pins prevent sleep - check GPIO states",
            "External components may draw power",
            "Use esp_wifi_stop() for lowest power",
            "Check for LED or other always-on components"
          ],
          code: `// Proper deep sleep sequence
Wi-Fi.disconnect(true);
Wi-Fi.mode(WIFI_OFF);
btStop();
esp_deep_sleep_start();`
        },
        {
          id: "power-5",
          question: "Is battery life meeting expectations?",
          yes: "power-success",
          no: "power-life-fix",
          diagnostic: "Calculate expected vs actual",
          code: "// Expected hours = mAh / avg_mA"
        },
        {
          id: "power-life-fix",
          type: "solution",
          title: "Battery Life Too Short",
          solutions: [
            "Measure actual current consumption",
            "Increase sleep time, decrease active time",
            "Reduce Wi-Fi usage - it's the biggest drain",
            "Lower CPU frequency: setCpuFrequencyMhz(80)",
            "Use RTC memory to avoid full boot"
          ],
          code: `// Reduce power
setCpuFrequencyMhz(80);  // Instead of 240
// Store data in RTC memory
RTC_DATA_ATTR int bootCount = 0;`
        },
        {
          id: "power-success",
          type: "success",
          title: "Power System is Working!",
          message: "Your power system is functioning correctly with expected battery life."
        }
      ]
    },

    "Serial/Debug": {
      title: "Serial & Debug Troubleshooting",
      color: "#E74C3C",
      steps: [
        {
          id: "serial-1",
          question: "Is the correct COM port selected?",
          yes: "serial-2",
          no: "serial-port-fix",
          diagnostic: "Check Device Manager/System Info",
          code: "// Windows: Device Manager > Ports\n// Mac: ls /dev/cu.*\n// Linux: ls /dev/ttyUSB* /dev/ttyACM*"
        },
        {
          id: "serial-port-fix",
          type: "solution",
          title: "COM Port Not Found",
          solutions: [
            "Install USB-to-Serial driver (CP210x or CH340)",
            "Try different USB port",
            "Check cable is data-capable",
            "On Mac, look for /dev/cu.* devices",
            "On Linux, add user to dialout group"
          ],
          code: "// Linux: sudo usermod -a -G dialout $USER"
        },
        {
          id: "serial-2",
          question: "Is baud rate correct (usually 115200)?",
          yes: "serial-3",
          no: "serial-baud-fix",
          diagnostic: "Match code and monitor baud rate",
          code: "Serial.begin(115200);  // Must match monitor setting"
        },
        {
          id: "serial-baud-fix",
          type: "solution",
          title: "Baud Rate Mismatch",
          solutions: [
            "Code and monitor must use same baud rate",
            "Common rates: 9600, 115200, 921600",
            "Garbage characters = wrong baud rate",
            "Boot messages at 74880 baud (ESP8266)"
          ],
          code: "Serial.begin(115200);  // Standard for ESP32"
        },
        {
          id: "serial-3",
          question: "Do you see any output at all?",
          yes: "serial-4",
          no: "serial-output-fix",
          diagnostic: "Add early serial output",
          code: `void setup() {
  Serial.begin(115200);
  delay(100);  // Wait for serial
  Serial.println("Boot!");
}`
        },
        {
          id: "serial-output-fix",
          type: "solution",
          title: "No Serial Output",
          solutions: [
            "Add delay after Serial.begin()",
            "Check TX pin not used for something else",
            "Try different terminal program",
            "Reset board with monitor already open",
            "Check if boot mode is correct"
          ],
          code: `void setup() {
  Serial.begin(115200);
  while(!Serial) { delay(10); }  // Wait for serial
  Serial.println("Ready!");
}`
        },
        {
          id: "serial-4",
          question: "Is output readable (not garbage)?",
          yes: "serial-success",
          no: "serial-garbage-fix",
          diagnostic: "Check for clear text",
          code: "// Readable: 'Hello World'\n// Garbage: '?x???~'"
        },
        {
          id: "serial-garbage-fix",
          type: "solution",
          title: "Garbage Characters",
          solutions: [
            "Baud rate mismatch - most common cause",
            "Wrong serial mode (8N1 is default)",
            "EMI interference on serial lines",
            "Power supply noise",
            "Try different baud rate: 9600, 74880, 115200"
          ],
          code: "// Try 74880 for ESP8266 boot messages"
        },
        {
          id: "serial-success",
          type: "success",
          title: "Serial is Working!",
          message: "Your serial connection is functioning correctly. You can now debug your code."
        }
      ]
    }
  };
}

// Get current tree
currentTree = troubleshootingTrees[problemCategory]

// State management using viewof for reactivity
viewof troubleshootState = {
  const initialState = {
    currentStep: currentTree.steps[0].id,
    history: [],
    tree: currentTree
  };

  const container = document.createElement('div');
  container.style.display = 'none';
  container.value = initialState;

  // Expose state management functions globally
  window.troubleshootNav = {
    goToStep: (stepId) => {
      container.value = {
        ...container.value,
        history: [...container.value.history, container.value.currentStep],
        currentStep: stepId
      };
      container.dispatchEvent(new Event('input', { bubbles: true }));
    },
    goBack: () => {
      if (container.value.history.length > 0) {
        const newHistory = [...container.value.history];
        const prevStep = newHistory.pop();
        container.value = {
          ...container.value,
          history: newHistory,
          currentStep: prevStep
        };
        container.dispatchEvent(new Event('input', { bubbles: true }));
      }
    },
    reset: () => {
      container.value = {
        ...container.value,
        currentStep: container.value.tree.steps[0].id,
        history: []
      };
      container.dispatchEvent(new Event('input', { bubbles: true }));
    }
  };

  return container;
}

// Find step by ID
findStep = (id) => currentTree.steps.find(s => s.id === id)

// Current step from state
currentStep = troubleshootState.currentStep
history = troubleshootState.history

// Render current step
html`
<style>
.troubleshoot-container {
  max-width: 800px;
  margin: 0 auto;
}
.troubleshoot-header {
  background: ${currentTree.color};
  color: white;
  padding: 20px;
  border-radius: 12px 12px 0 0;
  text-align: center;
}
.troubleshoot-content {
  background: white;
  border: 2px solid ${currentTree.color};
  border-top: none;
  border-radius: 0 0 12px 12px;
  padding: 25px;
}
.question-box {
  background: #f8f9fa;
  padding: 20px;
  border-radius: 10px;
  margin-bottom: 20px;
  border-left: 4px solid ${currentTree.color};
}
.question-text {
  font-size: 18px;
  font-weight: bold;
  color: #2C3E50;
  margin-bottom: 15px;
}
.diagnostic-tip {
  background: #E8F6F3;
  padding: 10px 15px;
  border-radius: 6px;
  font-size: 14px;
  color: #16A085;
  margin-bottom: 15px;
}
.code-block {
  background: #1e1e1e;
  color: #d4d4d4;
  padding: 15px;
  border-radius: 8px;
  font-family: 'Fira Code', monospace;
  font-size: 13px;
  overflow-x: auto;
  white-space: pre-wrap;
  margin-bottom: 20px;
}
.answer-buttons {
  display: flex;
  gap: 15px;
  justify-content: center;
}
.answer-btn {
  padding: 12px 40px;
  border: none;
  border-radius: 8px;
  font-size: 16px;
  font-weight: bold;
  cursor: pointer;
  transition: transform 0.2s, box-shadow 0.2s;
}
.answer-btn:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(0,0,0,0.2);
}
.btn-yes {
  background: #27AE60;
  color: white;
}
.btn-no {
  background: #E74C3C;
  color: white;
}
.solution-box {
  background: #FEF9E7;
  border: 2px solid #F39C12;
  border-radius: 12px;
  padding: 20px;
}
.solution-title {
  color: #E67E22;
  font-size: 20px;
  font-weight: bold;
  margin-bottom: 15px;
}
.solution-list {
  margin: 0;
  padding-left: 20px;
}
.solution-list li {
  margin-bottom: 10px;
  color: #2C3E50;
}
.success-box {
  background: #D5F4E6;
  border: 2px solid #27AE60;
  border-radius: 12px;
  padding: 25px;
  text-align: center;
}
.success-icon {
  font-size: 48px;
  margin-bottom: 15px;
}
.success-title {
  color: #27AE60;
  font-size: 24px;
  font-weight: bold;
  margin-bottom: 10px;
}
.nav-buttons {
  display: flex;
  justify-content: space-between;
  margin-top: 20px;
  padding-top: 20px;
  border-top: 1px solid #eee;
}
.nav-btn {
  padding: 10px 20px;
  border: 1px solid #ccc;
  background: white;
  border-radius: 6px;
  cursor: pointer;
}
.nav-btn:hover {
  background: #f0f0f0;
}
.progress-dots {
  display: flex;
  justify-content: center;
  gap: 8px;
  margin-top: 15px;
}
.progress-dot {
  width: 10px;
  height: 10px;
  border-radius: 50%;
  background: #ddd;
}
.progress-dot.active {
  background: ${currentTree.color};
}
.progress-dot.completed {
  background: #27AE60;
}
</style>

<div class="troubleshoot-container">
  <div class="troubleshoot-header">
    <h3 style="margin: 0;">${currentTree.title}</h3>
  </div>

  <div class="troubleshoot-content">
    ${(() => {
      const step = findStep(currentStep);
      if (!step) return html`<p>Step not found</p>`;

      if (step.type === "solution") {
        return html`
          <div class="solution-box">
            <div class="solution-title">${step.title}</div>
            <ul class="solution-list">
              ${step.solutions.map(s => html`<li>${s}</li>`)}
            </ul>
            ${step.code ? html`<div class="code-block">${step.code}</div>` : ''}
          </div>
          <div class="nav-buttons">
            <button class="nav-btn" onclick="window.troubleshootNav?.goBack()">Back</button>
            <button class="nav-btn" onclick="window.troubleshootNav?.reset()">Start Over</button>
          </div>
        `;
      }

      if (step.type === "success") {
        return html`
          <div class="success-box">
            <div class="success-icon">&#10004;</div>
            <div class="success-title">${step.title}</div>
            <p>${step.message}</p>
          </div>
          <div class="nav-buttons">
            <button class="nav-btn" onclick="window.troubleshootNav?.goBack()">Back</button>
            <button class="nav-btn" onclick="window.troubleshootNav?.reset()">Start Over</button>
          </div>
        `;
      }

      // Question step
      return html`
        <div class="question-box">
          <div class="question-text">${step.question}</div>
          ${step.diagnostic ? html`<div class="diagnostic-tip"><strong>Tip:</strong> ${step.diagnostic}</div>` : ''}
        </div>

        ${step.code ? html`<div class="code-block">${step.code}</div>` : ''}

        <div class="answer-buttons">
          <button class="answer-btn btn-yes" onclick="window.troubleshootNav?.goToStep('${step.yes}')">Yes</button>
          <button class="answer-btn btn-no" onclick="window.troubleshootNav?.goToStep('${step.no}')">No</button>
        </div>

        <div class="nav-buttons">
          <button class="nav-btn" onclick="window.troubleshootNav?.goBack()" ${history.length === 0 ? 'disabled' : ''}>Back</button>
          <button class="nav-btn" onclick="window.troubleshootNav?.reset()">Start Over</button>
        </div>
      `;
    })()}
  </div>
</div>
`

---

21.4 Quick Diagnostic Commands

21.4.1 Essential Debug Commands

Issue	Command	Expected Output
Wi-Fi status	Wi-Fi.status()	3 = Connected
IP address	Wi-Fi.localIP()	e.g., 192.168.1.100
Signal strength	Wi-Fi.RSSI()	-30 (excellent) to -90 (poor)
Free memory	ESP.getFreeHeap()	>20000 bytes healthy
MQTT state	mqtt.state()	0 = Connected
I2C scan	See code above	Device addresses

21.4.2 Common Error Codes

Wi-Fi Status	Meaning
0	WL_IDLE_STATUS
1	WL_NO_SSID_AVAIL
3	WL_CONNECTED
4	WL_CONNECT_FAILED
6	WL_DISCONNECTED

MQTT State	Meaning
-4	Connection timeout
-3	Connection lost
-2	Connect failed
0	Connected
4	Bad credentials

---

21.5 Related Resources

• Troubleshooting Hub - More debugging guides
• Failure Case Studies - Learn from real failures
• Code Snippet Library - Working code examples
• MQTT Message Flow - MQTT visualization

NoteCan’t Find Your Issue?

If your problem isn’t covered here, check the Discussion Prompts Hub to ask peers, or search the code snippets for working examples.