20  Troubleshooting Hub

Interactive Diagnostic Tools for IoT Problems

20.1 Troubleshooting Hub

TipSystematic Debugging

This hub provides interactive decision trees to diagnose common IoT problems. Follow the flowcharts to identify root causes and find solutions faster.

---

20.2 Quick Diagnostic Tools

Select your problem category to start troubleshooting:

problemCategories = [
  {id: "connectivity", name: "Connectivity Issues", icon: "wifi", description: "Device can't connect or drops connection"},
  {id: "sensor", name: "Sensor Problems", icon: "thermometer", description: "Readings are wrong, missing, or erratic"},
  {id: "power", name: "Power Issues", icon: "battery", description: "Device dies too fast or won't power on"},
  {id: "data", name: "Data Problems", icon: "database", description: "Data not reaching cloud or corrupted"},
  {id: "performance", name: "Performance Issues", icon: "speedometer", description: "System is slow or unresponsive"}
]

viewof selectedCategory = Inputs.radio(
  problemCategories.map(c => c.name),
  {label: "What type of problem are you experiencing?", value: "Connectivity Issues"}
)

currentCategory = problemCategories.find(c => c.name === selectedCategory)

---

20.3 Connectivity Troubleshooter

connectivityTree = {
  return {
    start: {
      question: "Can the device power on and show any LED activity?",
      yes: "network_check",
      no: "power_issue"
    },
    power_issue: {
      diagnosis: "Power Supply Problem",
      solutions: [
        "Check battery charge level or replace batteries",
        "Verify USB/power cable is properly connected",
        "Test with a different power supply",
        "Check for physical damage to power connector"
      ],
      severity: "critical"
    },
    network_check: {
      question: "Is the device within range of the gateway/router?",
      yes: "signal_quality",
      no: "range_issue"
    },
    range_issue: {
      diagnosis: "Out of Range",
      solutions: [
        "Move device closer to gateway/router",
        "Add a range extender or mesh node",
        "Check for obstacles (metal, concrete, water)",
        "Consider using a protocol with longer range (LoRa, cellular)"
      ],
      severity: "medium"
    },
    signal_quality: {
      question: "Can you see the device's network (Wi-Fi SSID, BLE advertisement)?",
      yes: "auth_check",
      no: "radio_issue"
    },
    radio_issue: {
      diagnosis: "Radio/Antenna Problem",
      solutions: [
        "Check if antenna is properly connected",
        "Verify radio is enabled in firmware",
        "Check for interference from other 2.4GHz devices",
        "Reset network settings on device"
      ],
      severity: "high"
    },
    auth_check: {
      question: "Does the device successfully authenticate/connect?",
      yes: "data_flow",
      no: "auth_issue"
    },
    auth_issue: {
      diagnosis: "Authentication Failure",
      solutions: [
        "Verify credentials (password, API key, certificates)",
        "Check if device is registered/provisioned correctly",
        "Ensure time is synchronized (for certificate validation)",
        "Re-provision the device from scratch"
      ],
      severity: "high"
    },
    data_flow: {
      question: "Is data reaching the server/cloud?",
      yes: "intermittent",
      no: "firewall_issue"
    },
    firewall_issue: {
      diagnosis: "Firewall/NAT Blocking",
      solutions: [
        "Check firewall rules allow outbound MQTT/CoAP ports",
        "Verify NAT traversal is working",
        "Test with a different network (mobile hotspot)",
        "Check if corporate network blocks IoT protocols"
      ],
      severity: "medium"
    },
    intermittent: {
      diagnosis: "Connection is Working",
      solutions: [
        "If intermittent: check for channel congestion",
        "Monitor RSSI over time for signal variations",
        "Check for periodic interference sources",
        "Consider implementing connection keepalive"
      ],
      severity: "low"
    }
  };
}

// State machine for troubleshooting
viewof troubleshootingState = {
  const tree = connectivityTree;
  let currentNode = "start";
  let history = [];

  const container = document.createElement("div");
  container.style.cssText = "background: #f8f9fa; padding: 20px; border-radius: 12px; margin: 20px 0;";

  function render() {
    const node = tree[currentNode];

    if (node.diagnosis) {
      // Terminal node - show diagnosis
      const severityColors = {critical: "#E74C3C", high: "#E67E22", medium: "#F39C12", low: "#27AE60"};
      container.innerHTML = `
        <div style="background: ${severityColors[node.severity]}20; padding: 20px; border-radius: 8px; border-left: 4px solid ${severityColors[node.severity]};">
          <h4 style="color: ${severityColors[node.severity]}; margin-top: 0;">Diagnosis: ${node.diagnosis}</h4>
          <p style="color: #666;">Severity: <strong style="color: ${severityColors[node.severity]};">${node.severity.toUpperCase()}</strong></p>
          <h5 style="margin-bottom: 10px;">Recommended Solutions:</h5>
          <ol style="margin: 0; padding-left: 20px;">
            ${node.solutions.map(s => `<li style="margin-bottom: 8px;">${s}</li>`).join("")}
          </ol>
        </div>
        <button onclick="this.parentElement.__reset()" style="margin-top: 15px; background: #2C3E50; color: white; border: none; padding: 10px 20px; border-radius: 6px; cursor: pointer;">
          Start Over
        </button>
      `;
    } else {
      // Question node
      container.innerHTML = `
        <div style="background: white; padding: 20px; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1);">
          <h4 style="margin-top: 0; color: #2C3E50;">${node.question}</h4>
          <div style="display: flex; gap: 15px; margin-top: 15px;">
            <button onclick="this.parentElement.parentElement.parentElement.__answer('yes')"
                    style="flex: 1; background: #27AE60; color: white; border: none; padding: 12px 20px; border-radius: 6px; cursor: pointer; font-size: 16px;">
              Yes
            </button>
            <button onclick="this.parentElement.parentElement.parentElement.__answer('no')"
                    style="flex: 1; background: #E74C3C; color: white; border: none; padding: 12px 20px; border-radius: 6px; cursor: pointer; font-size: 16px;">
              No
            </button>
          </div>
        </div>
        ${history.length > 0 ? `
          <button onclick="this.parentElement.__back()" style="margin-top: 10px; background: #7F8C8D; color: white; border: none; padding: 8px 15px; border-radius: 4px; cursor: pointer;">
            Back
          </button>
        ` : ""}
      `;
    }
  }

  container.__answer = (answer) => {
    history.push(currentNode);
    currentNode = tree[currentNode][answer];
    render();
  };

  container.__back = () => {
    if (history.length > 0) {
      currentNode = history.pop();
      render();
    }
  };

  container.__reset = () => {
    currentNode = "start";
    history = [];
    render();
  };

  render();
  return container;
}

troubleshootingState

---

20.4 Sensor Troubleshooter

sensorProblems = [
  {
    symptom: "Reading is always zero",
    causes: [
      {cause: "Wiring disconnected", check: "Verify all connections, especially ground", likelihood: "High"},
      {cause: "Wrong pin configuration", check: "Check GPIO pin numbers in code match physical wiring", likelihood: "High"},
      {cause: "Sensor damaged", check: "Test with multimeter or replacement sensor", likelihood: "Medium"},
      {cause: "Pull-up/down resistor missing", check: "Add appropriate resistor if required by sensor", likelihood: "Medium"}
    ]
  },
  {
    symptom: "Reading is constant (non-zero)",
    causes: [
      {cause: "Sensor saturated", check: "Check if measurement is at sensor's max/min range", likelihood: "High"},
      {cause: "ADC not configured", check: "Verify ADC resolution and reference voltage settings", likelihood: "Medium"},
      {cause: "Floating input", check: "Add pull-up/down resistor to prevent floating", likelihood: "Medium"},
      {cause: "Power supply noise", check: "Add decoupling capacitor near sensor", likelihood: "Low"}
    ]
  },
  {
    symptom: "Reading fluctuates wildly",
    causes: [
      {cause: "Electrical noise", check: "Add filtering capacitor, use shielded cables", likelihood: "High"},
      {cause: "Poor connection", check: "Check for loose wires or cold solder joints", likelihood: "High"},
      {cause: "Sampling too fast", check: "Add delay between readings, use averaging", likelihood: "Medium"},
      {cause: "Ground loop", check: "Use single ground point, star topology", likelihood: "Medium"}
    ]
  },
  {
    symptom: "Reading drifts over time",
    causes: [
      {cause: "Temperature effect", check: "Compensate for ambient temperature changes", likelihood: "High"},
      {cause: "Sensor aging", check: "Recalibrate sensor with known reference", likelihood: "Medium"},
      {cause: "Self-heating", check: "Reduce sampling rate or add thermal isolation", likelihood: "Medium"},
      {cause: "Humidity effect", check: "Use conformal coating or sealed enclosure", likelihood: "Low"}
    ]
  },
  {
    symptom: "Reading is offset (wrong by fixed amount)",
    causes: [
      {cause: "Calibration needed", check: "Perform two-point calibration with known values", likelihood: "High"},
      {cause: "Reference voltage wrong", check: "Measure actual Vref and adjust calculations", likelihood: "Medium"},
      {cause: "Unit conversion error", check: "Verify formula converts raw ADC to engineering units", likelihood: "Medium"},
      {cause: "Sensor placement", check: "Ensure sensor is measuring intended quantity", likelihood: "Low"}
    ]
  }
]

viewof selectedSymptom = Inputs.select(
  sensorProblems.map(p => p.symptom),
  {label: "What symptom are you seeing?", value: "Reading fluctuates wildly"}
)

selectedProblem = sensorProblems.find(p => p.symptom === selectedSymptom)

html`
<div style="background: #E8F4FD; padding: 20px; border-radius: 12px; margin: 20px 0;">
  <h4 style="margin-top: 0; color: #2C3E50;">Symptom: ${selectedSymptom}</h4>

  <h5 style="margin-bottom: 15px;">Possible Causes (ordered by likelihood):</h5>

  ${selectedProblem.causes.map((c, i) => html`
    <div style="background: white; padding: 15px; border-radius: 8px; margin-bottom: 10px;
                border-left: 4px solid ${c.likelihood === 'High' ? '#E74C3C' : c.likelihood === 'Medium' ? '#F39C12' : '#27AE60'};">
      <div style="display: flex; justify-content: space-between; align-items: center;">
        <strong style="color: #2C3E50;">${i + 1}. ${c.cause}</strong>
        <span style="background: ${c.likelihood === 'High' ? '#E74C3C' : c.likelihood === 'Medium' ? '#F39C12' : '#27AE60'};
                     color: white; padding: 2px 8px; border-radius: 10px; font-size: 12px;">
          ${c.likelihood}
        </span>
      </div>
      <p style="margin: 8px 0 0 0; color: #666; font-size: 14px;">
        <strong>Check:</strong> ${c.check}
      </p>
    </div>
  `)}
</div>
`

---

20.5 Power Troubleshooter

powerIssues = [
  {
    symptom: "Battery drains too fast",
    quickChecks: [
      "Is the device actually sleeping? Check current with multimeter during sleep mode",
      "Are all peripherals powered down during sleep?",
      "Is the radio transmitting more than necessary?",
      "Are you using the most efficient sleep mode available?"
    ],
    commonFixes: [
      "Increase sleep duration between readings",
      "Use interrupt-based wake instead of polling",
      "Reduce transmission power if range allows",
      "Disable unused peripherals (LEDs, sensors when not in use)"
    ],
    deeperDiagnosis: "Use [Power Budget Calculator](../design-strategies-and-prototyping/animations/power-budget.qmd) to model expected vs actual consumption"
  },
  {
    symptom: "Device won't power on",
    quickChecks: [
      "Is the battery charged / power supply connected?",
      "Is the power switch in the ON position?",
      "Is there visible damage to the power connector?",
      "Does the voltage regulator get warm when powered?"
    ],
    commonFixes: [
      "Try a different/known-good power source",
      "Check for short circuits with multimeter",
      "Inspect solder joints around power circuit",
      "Measure voltage at various test points"
    ],
    deeperDiagnosis: "Check if over-current protection triggered; inspect for damaged components"
  },
  {
    symptom: "Brownouts / random resets",
    quickChecks: [
      "Does reset happen during high-current operations (radio TX)?",
      "Is the power supply rated for peak current?",
      "Are there sufficient bulk capacitors?",
      "Is the voltage stable under load?"
    ],
    commonFixes: [
      "Add larger decoupling capacitors (100-1000uF)",
      "Use power supply with higher current rating",
      "Stagger high-power operations",
      "Lower transmission power"
    ],
    deeperDiagnosis: "Use oscilloscope to capture voltage during operation"
  }
]

viewof selectedPowerIssue = Inputs.select(
  powerIssues.map(p => p.symptom),
  {label: "What power issue are you experiencing?", value: "Battery drains too fast"}
)

currentPowerIssue = powerIssues.find(p => p.symptom === selectedPowerIssue)

html`
<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 20px; margin: 20px 0;">
  <div style="background: #FEF5E7; padding: 20px; border-radius: 12px;">
    <h4 style="margin-top: 0; color: #E67E22;">Quick Checks</h4>
    <ul style="margin: 0; padding-left: 20px;">
      ${currentPowerIssue.quickChecks.map(c => html`<li style="margin-bottom: 8px;">${c}</li>`)}
    </ul>
  </div>

  <div style="background: #D5F4E6; padding: 20px; border-radius: 12px;">
    <h4 style="margin-top: 0; color: #27AE60;">Common Fixes</h4>
    <ul style="margin: 0; padding-left: 20px;">
      ${currentPowerIssue.commonFixes.map(f => html`<li style="margin-bottom: 8px;">${f}</li>`)}
    </ul>
  </div>
</div>

<div style="background: #E8F4FD; padding: 15px; border-radius: 8px; margin-top: 10px;">
  <strong>For deeper diagnosis:</strong> ${currentPowerIssue.deeperDiagnosis}
</div>
`

---

20.6 Quick Reference: Error Codes

Protocol	Error	Meaning	Quick Fix
MQTT	Connection refused (1)	Unacceptable protocol version	Update client library
MQTT	Connection refused (4)	Bad username/password	Check credentials
MQTT	Connection refused (5)	Not authorized	Check ACL permissions
CoAP	4.01 Unauthorized	Missing or invalid token	Add authentication
CoAP	4.04 Not Found	Resource doesn’t exist	Check endpoint path
LoRaWAN	Join failed	Keys mismatch	Verify AppKey/DevEUI
BLE	Pairing failed	Wrong PIN or timeout	Re-initiate pairing
Wi-Fi	Auth failed	Wrong password	Re-enter credentials

---

20.7 Related Resources

Diagnostic Tools:

• Troubleshooting Simulator - Practice debugging scenarios
• Power Budget Calculator - Analyze power consumption
• Sensor Calibration Tool - Fix sensor accuracy issues
• ADC Resolution Visualizer - Debug sensor reading issues

Understanding Fundamentals:

• Binary & Hex Converter - Decode raw sensor data
• Wireless Range Calculator - Diagnose connectivity range issues
• Sampling Visualizer - Understand aliasing problems

Practice & Learning:

• Hands-On Labs Hub - Practice with guided exercises
• Failure Case Studies - Learn from real-world failures
• Tool Discovery Hub - Find more diagnostic tools