Complete guide for step-by-step debugging of an Arduino code

I own a lot of robots! And most of them are under the control of Arduino boards.

While the development on the Arduino platform is exciting, it does come with its set of challenges. The Arduino 1.x IDE isn't exceptional, the 2.x feels somewhat like a budget version of VSCode. In both versions, one of their many issues lies in the absence of a proper debugger. Throughout the programming of a project, especially as it becomes more intricate, errors can crop up at any moment. Effectively identifying these errors is a crucial skill for any Arduino developer. The conventional and simplest method involves sending textual information over the serial port and using the monitor as a debugging screen. However, monitoring the execution of a loop or complex code quickly becomes challenging as it is not possible to pause the program at the right moment to study its internal state.

Serial.println("so far, so good!");

Here's another approach I suggest in this article: step-by-step debugging..

The method I'm going to show you is compatible with many programmable boards. I personally use it with all types of Arduino boards (nano, uno, mega, etc.), but with a bit of adaptation, it would also work with ESP boards or others. We will, as much as possible, use free tools (or for a few euros at the end of the article) so that the method is suitable for hobbyists.

Regardless of your programming software, whether it's Arduino IDE, CLion, VSCode, etc., it inevitably comes with debugging tools. These tools can vary in capabilities, complexity of usage, or hardware requirements.

The method I'm suggesting uses the free PlatformIO IDE. The tool is free and open-source. It's cross-platform (Windows, Linux, Mac, etc.), supports multiple architectures (x32, x64, ARM, etc.), works with multiple frameworks (Arduino, ESP, Simba, etc.), and is built on the foundation of VSCode. In short, it's the perfect IDE for embedded system programming in C/C++... or if close to perfect.

Its installation is straightforward: go to the link https://platformio.org/platformio-ide and follow the instructions.

Take a few minutes to install the IDE, and I'll meet you as soon as it's done! ☕︎

The usual "old-fashioned" method that most people use to debug the previous code involves using the serial port and the serial monitor to transfer and display debug information. Here in particular, we would like to know the value of the counter variable. That old-school method involves initializing the serial port in the setup() method and then sending the value of counter in the loop() method, as shown in the code below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#include <Arduino.h>
 
uint8_t counter = 0;
 
void setup() {
  Serial.begin(9600);
  pinMode(LED_BUILTIN, OUTPUT);
}
 
void blink() {
  digitalWrite(LED_BUILTIN, HIGH);
  delay(100);
  digitalWrite(LED_BUILTIN, LOW);
  delay(100);
}
 
void loop() {
  if (counter < 300) {
    blink();
  }
  counter++;
  Serial.println(counter);
}

Have a try by deploying the code using the previous method (Ctrl+F5), and then opening the serial monitor:

1. Click on the PlatformIO icon: Serial monitor in the shape of a power plug, in the icon bar at the bottom of the screen.
2. Click on the Serial Monitor tab in the window that opens.
3. Finally, click on the Start monitoring button.

I know I talk (or write) a lot, but finally, here we are: let's explore a more suitable method.

The first thing to do is to configure our software for debugging:

• Open the platformio.ini file located at the project's root.
• Modify the file so that its content is as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[env:default]
platform = atmelavr
framework = arduino
 
; Compatible boards with the debugger:
;  https://docs.platformio.org/en/stable/plus/debug-tools/avr-stub.html#boards
board = nanoatmega328
; board = uno
; board = megaatmega2560
 
; Configure debugger tool
debug_tool = avr-stub
debug_port = COM3
 
; GDB stub implementation
lib_deps = 
  jdolinay/avr-debugger

This file configures the behavior of PlatformIO for our project.

1. The first line indicates the start of a section. Here, we configure the default environment, meaning that our project behaves the same under all conditions. However, it is possible to configure different behavior or settings based on whether we want to debug or compile for release, as well as the specific board we want to work with. It is possible to make these configurations more complex, for example, to test our code simultaneously on two different boards connected to different ports of the computer.
   More information: https://docs.platformio.org/en/latest/projectconf/sections/env/index.html
2. The next two lines define the platform and framework, i.e., the compilation toolchain used. In simple terms, compilation transforms our C++ code into code specific to the target microcontroller. Here, that is Arduino boards with AVR family processors.
3. Next, we define the board that will be used. Again, because each board has a different processor and hardware specifications, we need to be precise. Our compiler supports a large number of boards, but the debugger supports a bit less. (see point 4)
4. Now is the time to configure the debugger. Here, we will use avr-stub, which is specific to AVR family processors. This debugger supports a limited number of architectures, frameworks, and boards (actually, all Arduino-type boards).
   More information: https://docs.platformio.org/en/stable/plus/debug-tools/avr-stub.html
5. Then, we specify the debug port. Note that this line is optional if only one Arduino board is connected to the computer: PlatformIO will detect it automatically.
6. Finally, we include a dependency on the jdolinay/avr-debugger library. Here, you see the magic of PlatformIO, which will automatically find, download, compile, and link this library to the project! This library contains the Arduino code allowing our board to communicate with the debugger via the serial port.

Once done, we need to make a few changes to our code. We will start from our initial version without the Serial debug. It will be necessary to add:

• Two #include statements at the beginning of the file (but after the <arduino.h> one) to use the debug library in our code.
• A call to the debug_init() method at the beginning of the setup() function.

Here is the resulting code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#include <Arduino.h>
#include "avr8-stub.h"
#include "app_api.h"
 
uint8_t counter = 0;
 
void setup() {
  debug_init();
  pinMode(LED_BUILTIN, OUTPUT);
}
 
void blink() {
  digitalWrite(LED_BUILTIN, HIGH);
  delay(100);
  digitalWrite(LED_BUILTIN, LOW);
  delay(100);
}
 
void loop() {
  if (counter < 300) {
    blink();
  }
  counter++;
}

Everything is ready for the big moment: the one that usually blows our minds the first time we discover step-by-step debugging 🤯.

Rewind: in the section Attempt at old-fashioned debugging I listed several drawbacks related to using the serial port for debugging. I hope you are now convinced of the benefits of a "real" step-by-step debugger. However, we have not yet addressed the last point in this drawbacks list: how to use the serial connection while debugging our program simultaneously? Yes, it is indeed possible! 🤯

I am sorry to say, but to understand properly the next bit, we will have to get a few word on some technical topics.

In practice, to communicate with the outside world, Arduino boards have various communication protocols available. Perhaps these names will sound familiar to you: SPI, I2C, UART, etc...

Let's focus more specifically on the UART protocol. It is a serial communication protocol requiring two cables, called RX and TX. RX receives information, while the TX cable transmits it. By connecting the RX cable of a UART-compatible device to the TX cable of another and vice-versa, these two devices can exchange information in both directions.

To upload your program to the Arduino board, you probably connected it to the USB port of your computer. In term of hardware, your Arduino board has a built-in UART-USB converter plug to its pins 0 and 1. Those pins (0 and 1) are also used by the Serial library and are initialized for communication when you write Serial.begin(). You don't need to give them as parameters, that is built-in. Just as per the avr-debugger, at least by default here. Since it is not possible to simultaneously use this UART0 connection (pins 0 and 1) for two different and simultaneous usage, we can't use both the Serial library and avr-debugger. The trick is therefore to find another pair of pins that would allows a UART connection. Several possibilities are available to us:

1. Use other pins for uploading Arduino code. This is theoretically possible but complicated. Indeed, the use of pins 0 and 1 for code upload UART transfer is deeply rooted into the Arduino bootloader. It would be need to hack it (modify it) and then flash it back to the board according to a specific procedure. This is a path that I do not recommend.
2. Use another pair of pins for data transfer via Serial. This is entirely possible.
   1. Some boards - like the Arduino Mega - have multiple hardware UART connections. For instance pins 14 to 18 can be used under the name UART1, UART2, and UART3. These pairs are standard on the board and both the Serial library and the avr-debugger library can use them.
   2. It is also possible to software simulate a serial connection via the SoftwareSerial library.
3. In all cases, an additional UART-USB converter will be necessary to connect this second serial connection to the computer. This can be done in two ways:
   1. By purchasing an external UART-USB converter. Any brand, even the cheapest ones for 1.10€ on AliExpress is suitable.
   2. By using a second Arduino board (any model) for which we will use its built-in converter on pins 0 and 1.
4. Debugging can also be entrusted to a dedicated and specialized JTAG-type card - compatible with your Arduino board. However, those tools are expensive and specific to each type of board. That is a solution to be left to professionals and not something that hobbyists would really need I suppose.

Simulating a Serial Port

To free up the USB port (UART0) for the exclusive use of the debugger, it is possible to simulate the serial connection using the SoftwareSerial library. I won't go into details here because this goes beyond the scope of this article, but you can refer to the documentation for help.

Using UART1 for Serial Communication

Alternatively to the previous solution - and assuming you are using an Arduino with multiple UART - you can simply replace the classic code for your serial communication (meaning keyword Serial) with Serial1 for using UART1 (pins 18 and 19), Serial2 (pins 16 and 17), or Serial3 (pins 14 and 15). Again, this is beyond the scope of this article, and I recommend consulting the documentation for more details.

Using avr-debugger on UARTx

Let's focus now on an Arduino Mega board, which has the advantage of having multiple pins natively compatible with UART. To use the UARTx for debug (UART1, 2 or 3), we will need to modify our platformio.ini file as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[env:default]
platform = atmelavr
board = megaatmega2560
framework = arduino
 
; Configure upload tool
upload_port = COM3
 
; Configure debugger tool
; TX(uart)<->RX(arduino) and RX(uart)<->TX(arduino)
; PIN depends on the UART number used
debug_tool = avr-stub
debug_port = COM4
build_flags = -DAVR8_UART_NUMBER=1
 
; GDB stub implementation
lib_deps =
  jdolinay/avr-debugger

The differences with the previous file are:

• Changing the board type to an Arduino Mega.
• The introduction of the upload_port configuration, which defines the serial port used for code upload.
• A new build_flags configuration allowing the addition of flags during compilation. Here, we use -DAVR8_UART_NUMBER with a value of 1, allowing avr-debugger to use UART1 (pins 18 and 19) on our board.
• Mind how the debug_port is different from upload_port. We now need to use an UART-USB converter - here from UART1 (pins 18-19) to USB COM4.

Using an UART-USB Converter

Now that our configuration is ready, we can reuse the code from the section Attempt at old-fashioned debugging above to use both the step-by-step debugger and our serial port with the monitor. We just need to figure out how to connect pins 18 and 19 (UART1 on the Arduino Mega) to the computer. For this, we need an UART-USB converter. These usually come in the form of a cable (TTL-USB) or a board (UART-USB) with a male USB port on one side and pins or Dupont cables on the other side.

Connection goes like this:

• RX of the board to TX (pin 18) of the Arduino.
• TX of the board to RX (pin 19) of the Arduino.
• GND of the board to GND of the Arduino.
• Leave the +5V of the board unconnected; in our example, the Arduino is already powered through the standard serial port.

Using an Arduino as a UART-USB Converter

Suppose you want to use an Arduino Nano as an UART-USB converter. In that case, you should connect the UART pins of the debugged Arduino Mega to the UART0 pins (pins 0 and 1) of the Arduino Nano. Then, connect that nano to the computer. To avoid actually boot and use the arduino nano processor - we only use the built-in UART-USB converter - you must shortcut connect the RESET pin to the GND.

To summarize:

• Connect RX of the debugged Arduino to pin 1 of the converter Arduino.
• Connect TX of the debugged Arduino to pin 0 of the converter Arduino.
• Connect RESET and GND of the converter Arduino together.
• (optional) I tend to recommand connecting the GNDs of both boards together as well.

Once these adjustments are made, the rest of the debugging process unfolds as before: use the F5 shortcut, and you're good to go!