7 When You’re Stuck
When You're Stuck
Fast, symptom-based triage: an interactive decision tree for the five most common IoT failures, a diagnostic command cheat-sheet, and an error-code reference — so you spend your time testing, not guessing.
Sammy your guide, not a professor
“My instinct used to be to change three things at once and hope. The tree on this page is the opposite habit: change one thing, run one check, and actually believe the result.”
Find Your Symptom
Pick the category closest to your problem, then answer yes or no at each step. Every branch ends in either a fix with the exact solutions to try, or confirmation that this layer is fine and the problem is somewhere else.
Sammy says: if you already know the symptom, skip straight to the closest matching first question instead of starting from step one every category — the tree is a shortcut, not a ritual.
Diagnostic Command Cheat-Sheet
WiFi.status()Expected: 3 = ConnectedWiFi.localIP()Expected: e.g. 192.168.1.100WiFi.RSSI()Expected: -30 (excellent) to -90 (poor)ESP.getFreeHeap()Expected: >20000 bytes healthymqtt.state()Expected: 0 = ConnectedI2C scanner sketchExpected: device addresses listedCommon Error Codes
| Wi-Fi status | Meaning | MQTT state | Meaning |
|---|---|---|---|
0 |
WL_IDLE_STATUS | -4 |
Connection timeout |
1 |
WL_NO_SSID_AVAIL | -3 |
Connection lost |
3 |
WL_CONNECTED | -2 |
Connect failed |
4 |
WL_CONNECT_FAILED | 0 |
Connected |
6 |
WL_DISCONNECTED | 4 |
Bad credentials |
When the Fix Isn't Here
Not every problem is a live bug the tree can catch. If a module's own chapters cover a worked failure in that specific technology — Wi-Fi warehouse congestion, a LoRaWAN link budget miscalculation, a battery-life shortfall — the module that owns the technology is the right next stop, not this page. Nine full deployment post-mortems live in IoT Deployment Failure Case Studies. And if nothing here is actually broken but a concept still isn't clicking, that's not a debugging problem: it belongs on Quizzes & Checking Yourself, which walks through closing a conceptual gap instead of chasing a symptom.