Introduction
The serial monitor is one of the most important debugging tools for ESP32 development. Before you learn advanced debugging methods, it is worth becoming comfortable with serial output because it solves a large number of real problems quickly.
If your ESP32 is not connecting to Wi-Fi, not reading a sensor correctly, restarting unexpectedly, freezing during startup, or behaving differently than expected, the serial monitor is often the first place you should look.
A serial monitor is useful because it lets your ESP32 send messages to your computer while the program is running. Those messages can show you what the program is doing, what values it is reading, whether a connection succeeded or failed, and where things started to go wrong. That makes the serial monitor much more than a simple text window. It becomes a live view into the behavior of your code.
For beginners, this is often the first real step into debugging. Instead of guessing why the code failed, you begin printing useful information and reading it as the program runs. That habit alone can make ESP32 programming much less frustrating.
This article explains how to use the serial monitor for ESP32 debugging, why it matters, what kinds of messages you should print, and how to use it effectively in real projects.
What the serial monitor does
The serial monitor displays text sent from the ESP32 to the computer over a serial connection, usually through USB. When the ESP32 is connected to your computer and your code uses serial output commands, those messages appear in the monitor window.
In simple terms, the board talks back to you while it runs.
That matters because microcontrollers do not have a built-in screen for showing status information in most projects. If a variable has the wrong value, if a loop is stuck, or if a sensor is returning something unexpected, the serial monitor gives you a place to see that information.
Without serial output, debugging becomes much harder. You may only know that something failed, not where or why. With serial output, you can trace the path of the program and observe its state while it runs.
Why serial debugging is so useful on ESP32
The ESP32 is powerful and flexible, but it is still a microcontroller platform where many things can go wrong during development. Wireless connections can fail. Sensors may return unexpected values. Timing issues can affect behavior. Reset loops and crashes can happen. Program flow may not reach the part of the code you think it reaches.
The serial monitor helps because it gives immediate feedback. You can add a message before and after an important action, then see whether the action was reached and what happened next. This is often enough to narrow a problem down very quickly.
Imagine that your ESP32 is supposed to connect to Wi-Fi and then send data to a server. If it fails, the serial monitor can show whether the code reached the Wi-Fi section, whether the connection started, whether it timed out, whether an IP address was received, or whether the failure happened later during the server request.
That kind of visibility turns debugging from guesswork into investigation.
Serial monitor basics
To use the serial monitor, you usually do three things. First, initialize serial communication in your program. Second, print messages from your code. Third, open the serial monitor in your development environment and view the output.
A very basic Arduino-style ESP32 example looks like this:
void setup() {
Serial.begin(115200);
Serial.println("ESP32 starting...");
}
void loop() {
Serial.println("Running loop");
delay(1000);
}
In this example, Serial.begin(115200); starts serial communication at a baud rate of 115200. Then the code prints one message during startup and another repeatedly in the loop.
When you open the serial monitor with the same baud rate, you will see the messages appear.
This is the foundation of serial debugging. Once that works, you can start printing meaningful information rather than only simple test text.
Why baud rate matters
The baud rate is the communication speed used by the ESP32 and the serial monitor. Both sides must match. If your code uses Serial.begin(115200); but the serial monitor is set to a different speed, the output may look unreadable or corrupted.
That is one of the most common beginner problems. If the text looks like nonsense, check the baud rate first.
A rate of 115200 is very common for ESP32 work, but the important thing is consistency. Whatever you set in code should match what you select in the monitor.
The best way to use serial output
Many beginners print too little or too much. Both can make debugging harder.
If you print too little, the output may not tell you enough to locate the problem. If you print too much, the log becomes noisy and difficult to read. Good serial debugging means printing the most useful information at the most useful points in the program.
A good approach is to print messages around important events. For example, print when setup starts, when Wi-Fi connection begins, when a sensor is initialized, when data is read, and when an error occurs. That gives you a clear trail through the logic.
This works especially well when debugging startup problems. If the program restarts or freezes, the last visible message often tells you roughly where it happened.
For example:
void setup() {
Serial.begin(115200);
Serial.println("Setup started");
Serial.println("Initializing sensor");
// sensor setup code here
Serial.println("Connecting to Wi-Fi");
// Wi-Fi code here
Serial.println("Setup finished");
}
If the last visible line is Initializing sensor, then the problem likely happened during or immediately after sensor setup. That is already a very useful clue.
Printing variable values
One of the strongest uses of the serial monitor is printing variable values. This helps confirm whether the program is reading, calculating, or storing the right data.
For example:
int temperature = 27;
Serial.print("Temperature: ");
Serial.println(temperature);
This lets you see the actual value rather than assume it is correct.
You can do the same with floats, strings, counters, pin states, Wi-Fi status codes, sensor results, and almost anything else that matters to the program. When something behaves strangely, variable printing is often the fastest way to check your assumptions.
Suppose a sensor reading appears wrong in your final output. Print the raw reading first. Then print the converted value. Then print the value being sent to the display or network. By comparing those steps, you can find out where the incorrect value first appears.
That is real debugging in practice.
Using the serial monitor to trace program flow
Another important technique is tracing the path of execution. This means printing messages that show which parts of the code are being reached.
For example:
void loop() {
Serial.println("Loop started");
if (digitalRead(12) == HIGH) {
Serial.println("Button detected");
}
Serial.println("Loop finished");
delay(500);
}
If you expect the button section to run but never see Button detected, that tells you the condition is not becoming true. The issue may be the wiring, the pin configuration, or the logic itself.
Tracing program flow is especially useful when working with conditions, loops, tasks, state machines, or error-prone hardware initialization. It helps answer a very basic but powerful question: where is the code actually going?
Debugging Wi-Fi problems with serial output
Wi-Fi is one of the most common areas where ESP32 developers need debugging help. A project may fail because it never connects, connects too slowly, gets disconnected, or reaches the network but fails to complete the next step.
Serial output makes this much easier to diagnose.
For example:
#include <WiFi.h>
const char* ssid = "YourNetwork";
const char* password = "YourPassword";
void setup() {
Serial.begin(115200);
Serial.println("Starting Wi-Fi connection");
WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED) {
Serial.println("Connecting...");
delay(1000);
}
Serial.println("Wi-Fi connected");
Serial.print("IP address: ");
Serial.println(WiFi.localIP());
}
void loop() {
}
This example shows the connection attempt progressing in the serial monitor. If it never gets past Connecting..., the problem may be with credentials, signal strength, configuration, or network compatibility. If it reaches the connected message, then the failure is somewhere later in the project.
That kind of step-by-step visibility is exactly why serial debugging is so effective.
Debugging sensor readings
Sensor projects often fail in ways that are difficult to understand without serial output. The code may compile and run, but the readings may always be zero, always be the same value, or jump unpredictably.
The serial monitor helps you inspect what the ESP32 is actually reading.
For example:
int sensorValue = analogRead(34);
Serial.print("Sensor value: ");
Serial.println(sensorValue);
That one line can immediately tell you whether the sensor is responding at all.
If you are converting the raw reading into another unit, such as voltage or temperature, it helps to print both the raw and converted values. That way you can tell whether the problem lies in the sensor input or in the conversion formula.
For example:
int rawValue = analogRead(34);
float voltage = rawValue * (3.3 / 4095.0);
Serial.print("Raw: ");
Serial.print(rawValue);
Serial.print(" Voltage: ");
Serial.println(voltage);
This kind of output is much more informative than only printing the final result.
Debugging button and GPIO input issues
Buttons, switches, and GPIO signals are another common source of confusion. A button may appear not to work when the real issue is incorrect wiring, missing pull-up or pull-down configuration, or the logic being inverted.
The serial monitor helps by letting you print the input state repeatedly.
Example:
void loop() {
int buttonState = digitalRead(12);
Serial.print("Button state: ");
Serial.println(buttonState);
delay(200);
}
If the value never changes, then the problem may be electrical rather than logical. If it changes but the rest of the program does not respond, then the logic after the read may need attention.
This approach is simple, but it is one of the fastest ways to separate hardware problems from software problems.
Finding crashes and reset loops
Serial output is also very useful when the ESP32 crashes, resets, or gets stuck in a boot loop. In many cases, the final message printed before the crash tells you approximately where the program failed.
For example, if your setup code prints these messages:
Serial.println("Starting setup");
Serial.println("Starting display");
Serial.println("Starting Wi-Fi");
Serial.println("Starting web server");
and the output stops after Starting Wi-Fi, then the issue is likely happening during Wi-Fi setup or immediately afterward.
This method is not as deep as advanced debugging tools, but it is often enough to narrow the problem significantly.
It is also common for the ESP32 to print its own boot or crash information to the serial monitor. Even if you do not fully understand every line at first, that output can still tell you whether the board is restarting repeatedly or hitting a panic condition.
Using labels to make logs easier to read
As your program grows, plain messages like Here or Value become less useful. It is better to label output clearly so you know what each line means without guessing.
For example:
Serial.println("[SETUP] Starting Wi-Fi");
Serial.println("[WIFI] Connected");
Serial.println("[SENSOR] Reading temperature");
Serial.println("[ERROR] Sensor not detected");
This makes the log easier to scan, especially in larger projects.
You can also include variable names directly in the output:
Serial.print("[SENSOR] temperatureC = ");
Serial.println(temperatureC);
A readable log is much easier to debug than a messy stream of unlabeled values.
Avoiding too much serial output
Although serial debugging is extremely useful, too much output can become a problem. If the ESP32 prints messages too often, especially inside a very fast loop, the monitor can become flooded with text. That makes important messages harder to find and can even affect timing in some programs.
For example, printing inside a loop that runs thousands of times per second is usually not helpful. It is often better to print only at intervals, or only when something changes, or only when an error occurs.
A more controlled version might look like this:
void loop() {
static unsigned long lastPrint = 0;
if (millis() - lastPrint > 1000) {
lastPrint = millis();
Serial.println("Still running");
}
}
This gives you regular status updates without overwhelming the monitor.
Good debugging output should be informative, not noisy.
Using serial messages for error handling
The serial monitor becomes even more powerful when paired with simple error checks. Instead of only printing normal progress messages, also print clear error messages when something fails.
For example:
if (!sensor.begin()) {
Serial.println("[ERROR] Sensor initialization failed");
}
Or:
if (WiFi.status() != WL_CONNECTED) {
Serial.println("[ERROR] Wi-Fi not connected");
}
This makes failures easier to spot immediately. Instead of wondering whether the code silently skipped an important step, you see an explicit warning in the log.
In larger projects, this habit can save a great deal of time.
Comparing expected output with actual output
One of the best debugging habits is to think in terms of expected behavior. Before running the code, ask yourself what the serial monitor should show if everything is working correctly.
Then compare that expectation with what actually appears.
For example, if setup should initialize three devices, connect to Wi-Fi, and then begin reading data, your expected log might look something like this:
Setup started
Sensor initialized
Display initialized
Wi-Fi connected
Reading data
If the real output stops after Display initialized, that immediately narrows the problem. Debugging becomes much easier when you compare the real sequence against the intended sequence.
Using serial output during development and reducing it later
During development, it is normal to use a lot of serial output. It helps you understand the system and catch mistakes quickly. But once the code becomes stable, you may want to reduce or tidy the messages.
This is especially useful in larger projects. Too many leftover debug prints can make logs harder to read later. Some developers keep only the most important startup, status, and error messages once the project is working well.
That is a good long-term habit. Use detailed serial output when exploring a problem, then keep the final logging focused and meaningful.
Common beginner mistakes
One common mistake is forgetting to start serial communication with Serial.begin(...). If that line is missing, you may open the monitor and see nothing.
Another common mistake is using the wrong baud rate. If the monitor shows unreadable text, check that the baud setting matches the one in your code.
A third common mistake is opening the serial monitor too late. If your board prints important startup messages immediately after reset, you may miss them if the monitor opens after the board has already started. In some cases, restarting the board while the monitor is already open helps.
Another mistake is printing vague messages that do not explain anything useful. A line like Value: is not very helpful unless you know what value it refers to. Clear labels are better.
Finally, some beginners print so much information that they bury the real problem. Good debugging means printing what matters most.
A practical debugging example
Imagine you are building an ESP32 project that reads a temperature sensor and sends the value over Wi-Fi every few seconds. The project is not working. Sometimes it seems to hang, and sometimes the value never reaches the server.
A useful serial debugging approach would be to print messages like these:
Serial.println("[SETUP] Program started");
Serial.println("[SETUP] Initializing sensor");
Serial.println("[SETUP] Sensor ready");
Serial.println("[WIFI] Connecting");
Serial.println("[WIFI] Connected");
Serial.print("[SENSOR] Temperature = ");
Serial.println(tempValue);
Serial.println("[NETWORK] Sending data");
Serial.println("[NETWORK] Send complete");
If the monitor stops at [WIFI] Connecting, the issue is likely with Wi-Fi. If it reaches [SENSOR] Temperature = ... but never shows [NETWORK] Send complete, then the problem is likely in the send step. If the printed temperature is clearly wrong, then the sensor handling needs attention.
This is exactly how the serial monitor helps in real situations. It breaks the mystery into smaller visible steps.
Conclusion
The serial monitor is one of the simplest and most effective tools for ESP32 debugging. It helps you see what the program is doing, trace the flow of execution, inspect variable values, watch connection attempts, verify sensor readings, and narrow down crashes or startup failures.
For beginners, it is often the first tool that makes debugging feel manageable. For experienced developers, it remains useful because fast, clear text output is often enough to solve many problems without needing heavier tools.
