Learn / Microcontrollers / Firmware and debugging

Firmware Build, Logs & Fault Isolation

ReviewedIntermediate MakerAbout 5 min
ESP32
In short

Firmware Build, Logs & Fault Isolation: the short answer

When a project does not work, find which stage fails instead of changing everything at once. The stages are: it compiles, it uploads, it starts, it talks to the parts, it reads sensible values, it reacts correctly.

Level
Intermediate
Time
About 5 min
Topic
Microcontrollers
You will learn to

Find a firmware fault stage by stage using serial logs and an I²C scan.

Before this: Arduino and ESP32 Basics

When a project does not work, find which stage fails instead of changing everything at once. The stages are: it compiles, it uploads, it starts, it talks to the parts, it reads sensible values, it reacts correctly.

The serial monitor is your main tool. Print a line at start-up with the sketch name and version, print each step of setup, and print raw readings next to the converted values. Make sure the monitor's baud rate matches Serial.begin().

Common signatures: garbage characters means wrong baud rate; nothing at all means wrong port or a crash before Serial.begin; 'sensor not found' means wiring, address or power; NaN or -999 means the read failed and you should not show it as a real value.

For I²C parts, run an I²C scanner sketch first. If the address appears, the wiring and power are fine and the problem is in your code or library settings.

Reproduce first, then narrow

A bug you can trigger on demand is half fixed. Write down the exact steps and inputs that cause it. Then cut the program in half: disable one part and see if the fault remains. Repeat until a small area is left.

Change one thing at a time. Two changes at once and a fix tells you nothing about which one worked.

Make the program talk

Serial prints are the first tool. Print values at decision points, with a label, for example 'adc=512 state=2'. Remember that printing is slow and can hide timing bugs, and that printing inside an interrupt routine is risky. Set a flag in the interrupt and print from the main loop.

A spare pin toggled at the start and end of a routine, watched on an oscilloscope or logic analyser, measures how long it really takes without disturbing it much.

Common causes worth checking early

Variables shared with an interrupt need the volatile keyword. A 16-bit value read while an interrupt changes it can be torn on an 8-bit chip. Integer overflow, such as a counter of milliseconds in a 16-bit variable wrapping at 65 seconds, makes bugs that appear only after a while. Running out of RAM from large strings or arrays shows up as odd resets or garbage values.

Check the hardware before blaming the code: supply voltage under load, a shared ground, and loose jumper wires cause many 'software' faults.

Common mistakes
  • Changing several things at once, then not knowing what fixed it.
  • Printing from inside an interrupt routine and breaking the timing.
  • Blaming the code before measuring the supply voltage.
Intermediate lesson · Maker plan

Practise this lesson with Maker

The explanation above is free for everyone. The practice for Intermediate lessons in every domain are part of the Maker plan at ₹499 a month, and Pro includes them too.

With Maker you also get: a worked example, a hands-on task, a 3-question check.

Common questions

What will I learn in "Firmware Build, Logs & Fault Isolation"?

Find a firmware fault stage by stage using serial logs and an I²C scan.