Debugging Arduino Sketches

Analogy categoryAnalogies

The Debugging Challenge on Embedded Hardware

Debugging an Arduino is harder than debugging a desktop program because there is no screen, no operating system, and traditionally no breakpoints — the code runs on a bare microcontroller you cannot easily pause. Bugs fall into three broad classes: logic errors where the code compiles but behaves wrong, hardware errors where wiring or a faulty component defeats correct code, and resource errors where limited RAM or timing overruns quietly corrupt behavior. Effective debugging is a disciplined process of making the invisible visible: instrumenting the code to report its own state, then narrowing the search space until the fault reveals itself.

🏏

Cricket analogy: Like diagnosing a batting slump — is it a technical flaw in the trigger movement (logic), a bad pitch (hardware), or fatigue late in a long innings (resources)? You isolate one variable at a time before changing anything.

Serial Print Debugging and the Plotter

The most-used debugging tool is Serial.print(). By printing variable values, sensor readings, and 'reached here' markers at key points, you build a running trace of what the program actually did versus what you assumed. A useful discipline is to wrap debug output in a DEBUG macro so you can compile it out for production, and to print variable names alongside values so the log is self-describing. For numeric data that changes over time — a filtered accelerometer axis, a PID error term — the built-in Serial Plotter graphs comma- or space-separated values in real time, turning a wall of numbers into a curve where oscillation, drift, or saturation is obvious at a glance.

🏏

Cricket analogy: Like Hawk-Eye overlaying the ball's trajectory instead of arguing from memory — the Serial Plotter turns a stream of raw numbers into a visible curve so an lbw-style close call becomes plain.

cpp

// Toggle all debug output from one line
#define DEBUG 1

#if DEBUG
  #define DPRINT(x)    Serial.print(x)
  #define DPRINTLN(x)  Serial.println(x)
#else
  #define DPRINT(x)
  #define DPRINTLN(x)
#endif

int readSensor(int pin) {
  int raw = analogRead(pin);
  DPRINT(F("sensor["));    // F() keeps the string in flash, not RAM
  DPRINT(pin);
  DPRINT(F("] = "));
  DPRINTLN(raw);
  return raw;
}

void loop() {
  int a = readSensor(A0);
  int b = readSensor(A1);
  // For the Serial Plotter: two comma-separated series
  Serial.print(a); Serial.print(',');
  Serial.println(b);
  delay(50);
}

Wrap string literals in the F() macro (e.g., Serial.print(F("value = "))) to store them in flash program memory instead of precious SRAM. On an Uno with only 2 KB of RAM, dozens of unwrapped debug strings can silently exhaust memory and cause crashes.

Diagnosing Memory Corruption

The most baffling Arduino bugs are RAM exhaustion bugs: the sketch works for a while then resets, freezes, or produces garbage, with no compiler warning. The ATmega328P has just 2 KB of SRAM shared between global variables, the heap, and the stack. When large String objects fragment the heap or deep function calls grow the stack downward, the two collide and memory corrupts. Diagnose it by measuring free RAM at runtime with a freeMemory() helper that compares the stack pointer to the heap boundary; if the number trends toward zero, you have a leak or oversized buffers. The cures are using the F() macro for strings, preferring fixed char arrays over the dynamic String class, and sizing arrays realistically.

🏏

Cricket analogy: Like a run chase where the required rate creeps up unnoticed until wickets and overs collide — free RAM shrinking toward zero is that silent pressure that suddenly collapses the innings.

Heavy use of the String class is a leading cause of hard-to-find crashes on 8-bit Arduinos. Repeated concatenation fragments the tiny heap until an allocation fails and behavior turns erratic. For anything running long-term, prefer fixed-size char[] buffers with snprintf() and treat the String class as a convenience for short-lived, low-stakes code only.

Classify bugs first: logic, hardware, or resource — the fix and the tools differ for each.
Serial.print tracing with labeled values is the workhorse; wrap it in a DEBUG macro to compile out for production.
The Serial Plotter graphs comma/space-separated numbers live, exposing oscillation, drift, and saturation instantly.
Use the F() macro to keep literal strings in flash and protect the ATmega328P's 2 KB of SRAM.
Memory exhaustion causes silent resets and garbage; measure free RAM at runtime and watch for a downward trend.
Prefer fixed char arrays and snprintf over the String class in long-running sketches to avoid heap fragmentation.
Isolate hardware faults by testing components independently and checking wiring before blaming the code.