I am working on a few Arduino-based projects and am tired of debugging using print statements.
I have been researching various toolchains to add debugging ability to my embedded control developments.
I am interested in anyone’s experience with setting up such a toolchain for debugging code on various Arduino boards.
My typical boards are Uno, Nano, NODEMCU, WEMOS D1, and other ESP variations.
Please share what are you using for debugging Arduino boards:
IDE:
External debugging hardware:
Target Processors:
Other stuff:
Surprisingly I found a number of tutorials on debugging Arduino with gdb. Visual Micro is a GUI IDE which lets you debug in the GUI and another tutorial I just saw(dated 2017) is for the ESP and it said it was commandline only and uses GDBStub.h to get you debugging over serial port. That’s 5 years old so hopefully something has changed.
I’m very interested in this too as for way too long I just hated debugging with Serial.print and over the years have usually coded in #define DEBUG in my apps to include and exclude debug statements. I’m hoping the newer Arduino IDEs have some improvements in this area.
Sounds like I am not the only one wandering around on this.
My debugging needs include these functions;
Variables
Watch window
Call Stack
Breakpoint
The questions I am researching are:
What debug functions can I get without a dongle? Not sure how you get debug functions without ICE. However, I could swear that I previously used Visual Micro without a dongle to get some debug functions.
What dongles fit the budget for hobby work?
Do I need a hardware dongle to get to the above debug functions?
If so what debugging functions can I get to with what hardware configuration?
IntelliSense; A language service that provides intelligent code completions based on language semantics and an analysis of your source code.
Do I need a different toolchain for each Arduino processor type?
My research [II also watched lots of videos] so far:
Visual Studio:
Visual Studio Community & Visual Studio Code, [that naming convention isn’t too confusing said no one]:
There are actually two versions of Visual Studio. The larger Visual Studio in itself has multiple versions. The free is Visual Studio Community. The other lighter version is Visual Studio Code.
I got Visual Studio Code installed:
MS Arduino extension
MS C++, Intellisense extension.
Most of the IDE is working
Could not get the debug to work. Throws various errors when I try to debug. Seems that I have a debug config file set up wrong [launch.json] or do I need a dongle? Haven’t found a doc on setting up a debug config specific for Arduino.
Serial port output window is not displaying anything. Problem with config wrong?
Unclear if and what I need for hardware to debug and how to set it up.
Platform I/O
There is an extension for Visual Studio: Did not install it yet but watched lots of videos.
Seems like this is the most popular toolchain.
Not sure what if any hardware is needed for basic debugging.
Arduino IDE:
The new Arduino IDE supports debugging for only SAMD devices but needs a dongle
I forget what I was debugging a few years ago but when I was looking for a JTAG dongle I ran across the Blackmagic Probe and found I could flash a ST32 JLINK dongle( < $10) with the firmware and make it into a JTAG interface with BlackMagic Probe(BMP) using openOCD.
Or you can purchase the real thing for $75: 1BitSquared - Black Magic Probe V2.3
Here’s more info on BlackMagic Probe: https://black-magic.org/
But I don’t think BMP will help on the small 8bit AVR Arduinos. I know I have another JTAG dongle which was ~$7x years ago but again, those were for ARM based stuff already having JTAG onboard IIRC.
Yes, Serial.print debugging has been driving me nuts for years. I’m looking to port a tide chart project which is using an Arduino Nano, BT board and RTC over to an ESP32 so this debugging venture should be helpful.
Looks promising. I’ve used Eclipse for lots of different projects(recently STM32CubeIDE) and it can be a mouthful. Scrolling through that blog I see those magic step-into, step-over, and Watch icons so that could be your solution.
One thing I should make clear first – this article is about debugging Arduino Uno, Nano, Mega (and possibly other boards based on the AVR microcontrollers).
There is a ‘Debugging Arduino Code’ chapter in the documentation for the VS Code Arduino extensions which can be a bit misleading. The debugging they are talking about is only available to a few boards (e.g., Arduino M0 Pro) which include hardware debugger interface on the board. There is no support for debugging the popular AVR-based boards like Uno, Nano or Mega in the [MS] Arduino extensions.
Limitations of this Debugger Solution
There are 4 important limitations of using this debugger:
Serial communication (hardware serial) cannot be used together with the debugger – no Serial.something functions in your program.
One pin must be reserved for the debugger – this is pin 2 on Uno by default, can be changed to pin 3 in the avr8-stub.h file. You cannot use this pin in your program.
The program runs at slow speed when any breakpoint is enabled (and there is always at least one enabled in VS Code, see Common problems below). Some time-sensitive operations may not work correctly when debugging the program.
It is not possible to stop the program in interrupt service routines, or in general, it is not possible to step through the program when interrupts are disabled – as it happens in the Arduino micros() function. If you find yourself stepping over cli(); command in the code, expect that something unexpected may happen.
Having read the details 2 or 3 times AND comments it became obvious this uses the serial port for the GDB communications AND relies on interrupts which the 328s have few off. Not even SoftSerial can be used since it relies on another interrupt to work.
It was a flag which stood out for me as I have a Tide Chart project I was thinking of testing this on but I use the serial port for the Bluetooth interface and I2C for the RTC interface.
There’s also a new bootloader which when used greatly helps improve speed of the processing while debugging. And probably once done a few times the extra steps needed to get this level of debugging available won’t feel like it’s really a bunch of extra steps.
It just kills me that MS is behind VS Code and they play games with telemetry and proprietary modules and hooks. I was using Atom for a few years but couldn’t figure out why there was a push to stop using it and to use MS-VS Code and then MS bought github and it became obvious. It’s good to have competition and lots of OSS devs keep hounding MS for games played while claiming to be OSS friendly.
I have to get some Ardu projects completed so I am moving on, at least for a while.
My interim plan:
Use the Arduino for debugging
Use Notepad ++ with Arduino language add-in to edit as it has some auto-complete functionality. I used this before.
The Run function in Notepad++ can launch the Arduino IDE for compilation and debugging.
Try using VS Code just for editing so I have access to IntelliSense. Not sure it is worth the overhead.
I may buy 1 and/or 2 Arduino Zeros to get the real-time debug capability of the newest Arduino IDE.
Employ this setup for more complex hardware projects like my project that uses radio (HC12) nodes.
The challenge with this is I have to port/translate the project over to the final board type and if it has problems in that config I am back to square one.
------ Not giving up …
I think I have narrowed my choices down to Visual Micro extension for Visual Studio Community as the full debug solution but I need more research.
I get that alot from people used to setup.exe and then their clicking buttons and “doing stuff”. It can be nice when that happens but more and more things are a cluster of tools working together and things get muddy at that point. Eclipse was designed to pull that type of stuff together and vendors like STM have created packages which have things setup already. When not, ya it can be lots of ‘what does THAT mean’ moments.
I have the STM32CubeIDE installed and an STM32 board so I will check and see how well it does debugging. Then I’ll see if I can bring in the one Arduino Zero I have and debug that too. I’ll also try the Arduino IDE v2.x with the Zero and see how debugging goes.
The ease of use and plethora of Arduino libraries has made it an easy platform to use but when stuff goes wrong, digging into libraries with print statements, etc bites.
I’m running the Arduino IDE v2.0.3 via AppImage and for an STM32 board I have been messing with for the JL1 and JL2 lasers it was surprisingly easy to get it working for compiling and uploading.
Just added the cores to the board preferences so I could select the STM32F1 boards then the STM32F103CBTX board number: https://github.com/stm32duino/BoardManagerFiles/raw/main/package_stmicroelectronics_index.json
and had to add where my STM32CubeIDE programmer script location to the path variable prior to running the IDE:
PATH=/home/maker/Projects/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin:$PATH ./
arduino-ide_2.0.3_Linux_64bit.AppImage
I’m using a ST-Link v2 programmer like this( $10 ):
Getting debugging to work has been 30 minutes of me trying to figure it out instead of reading some Arduino docs on setting it up… That’s kinda how I roll sometime and thought I could figure it out.
I think I should pull out the Zero board… while I can upload to the STM32F103 it says the debugger doesn’t support the STM32F1 boards but after a bunch of changes to platform.txt and boards.txt one user was able to get the Arduino IDE 2.0.3 debugger working with the STM32F103. https://www.stm32duino.com/viewtopic.php?f=18&p=10740
But I just want to see it working so I’ll bookmark that thread and try the Zero later.
UPDATE( it’s later ):
The Arduino IDE v2.0.3 worked fine debugging a Zero device once I updated the bootloader. My Zero board is about 10 years old… And no extra hardware is needed, just plugged USB cable into the Programmer port, set a couple of things in the IDE like Board and Port which were almost automatic and then Programmer to “Atmel EDBG”. I set breakpoints, did step into, outof, over etc and watched local variables changing and it all worked out of the box as they say. Console output shows it’s using the gdb debug server.
UPDATE( latest ):
You’ve got me on a mission now that I’ve seen the Arduino IDE v2.0.3(latest) running in-circuit gdb debugging with the Arduino Zero. I will be doing the modifications to the properties.txt and boards.txt file for enabling the Arduino IDE to do debugging with the STM32 via the OpenOCD/ST-Link method.
Then I’m going to see if I can get OpenOCD/esp-prog to work with the Arduino IDE.
The esp-prog is ~$20 but the magic is really the FT232H interface so even just a breakout board with that should work.
UPDATE( later than latest ):
The stm32 modifications listed in that linked topic on stm32duino.com site do work with the Arduino IDE v2.0.3 so that’s good news. I have since learned how to add compiler options to the Arduino IDE menus and added Compiler optimizations and also debugging settings for the ESP32 since they are missing from that. I used the stm32 boards.txt and platform.txt files as examples. I’ve installed the esp-idf tool, set it’s openocd up in the platform.txt file since it’s version 0.11 and has support for esp32 while the Arduino default is 0.10 and doesn’t support esp32.
But so far the openocd debugger does not want to debug in the IDE and complains about missing memory map information. So I’m getting very close!
UPDATE( last until someone else actually posts something ).
The ESP-IDF team updated the ESP32 Core last week(v2.0.6) and included JTAG debugging fixes for the Arduino v2.0.3 IDE. I tested it with my FTDI FT232H board and an ESP-WROOM-32 board and it does work. So now we have Arduino SAMD based ARM boards, STM32/JLink boards and ESP boards with either FT232H or ESP-Prog JTAG interfaces(both under $20).
@dougl
I finally got around to plugging in my Zero board and trying to debug a simple set of code for an I2C current sensor I am planning on a project.
It seemed to work but was flakey, keep in mind since I just started using this it could be me that is flakey.
Sometimes it locked up and the only way I could get it to work again was to reload the IDE
Breakpoints wouldn’t clear even though it said they were.
Many of the drop downs in the debig window did not populate. Perhaps there is nothting to populate with this specific code?
Stepping through the code stopped at breakpoints even when I previously cleared them.
I blame my struggles on my newbie status but:
The big disappointment is that there does not seem to be adequate user documentation for the debug UI. I found one post on setting up the ZERO for debugging and used that to get started.
I have not found a single document that defines what each of the functions of the debug interface does and how to use it. I am surprised because this is kind of a big deal for Arduino to have a built-in debug ability.
BTW I did find the new “IntelliSense” function very useful when editing and didn’t see any further need for Notepad++
@donkjr I had seen that problem too, ie breakpoints not being released but I thought it was related to the esp32 libraries which had just included the openocd/debugging capabilities. When I tested the Zero it was just a quick test where I set a couple of breakpoints, started the debugger and saw it stop at breakpoing #1 then I hit Continue button and saw it stopped at breakpoint #2, followed by looking at a local variable.
There’s a discussion on this here about both documentation AND the breakpoint issue.
It also points to documentation on VSCode debugging which this IDE shares code with.
I’ve used GDB debugging for a few years back about 20 years ago and it was both commandline and in a GUI wrapping the GDB server(Presentation Manager PMGDB ) so I knew what was expected of the Arduino IDE buttons. I will look for documentation.
Wow thanks for that… those problems are identical to what I experienced.
Not sure this debugger is ready for prime time yet?
I will also search the VS docs for help but until the problems cited in these posts are cleared I don’t think I will spend much time hacking on this thing…
while searching I found this which is supposedly their debugging doc and was updated Jan 19, 2023.
I’m also going to zing them a bit for promoting this feature of the v2 IDE and leaving these bugs in the software even after official release of the IDE. the v2 IDE is what they are putting all new development into. BTW, I also found it a PIA to have to start and stop the debugger a bunch to clear breakpoints. But, I was troubleshooting a crashing issue on my ESP32 and it was really nice to be able to step through the code and get to the cause of the crash instead of using println statements.
@donkjr I just pulled out my Zero board and debugged a little blink app.
void setup() {
// put your setup code here, to run once:
pinMode( LED_BUILTIN ,OUTPUT);
}
void loop() {
int rVal=0;
// put your main code here, to run repeatedly:
digitalWrite(LED_BUILTIN,HIGH);
rVal=mydelay(200);
digitalWrite(LED_BUILTIN,LOW);
rVal=mydelay(2000);
}
int mydelay(int mSec ) {
if(mSec > 1000){
delay(mSec);
return(mSec);
}
else {
delay(1000);
return(1000);
}
}
I didn’t have any problems debugging with breakpoints as long as I stopped the debugger(the square icon) before changing the breakpoints and then starting the debugger(triangle icon) to start debugging again. It’s a minor inconvenience and does mean that if you find you want to add a breakpoint while debugging you then have to stop and restart the debugger and get back to where you left off.
I’ve brought this up in the Arduino IDE v2 forum.
@donkjr I am running the nightly update version just to be sure we’re on the same page.
arduino-ide_nightly-20230119_Linux_64bit
And I just tried debugging with the Zero doing dynamic breakpoint insert and removal without stopping the debugger and it worked for me. BUT, if I don’t use Continue to get around the loop() the debugger seems to get stuck in the infinite loop code. So try not to use the Jump Into or Jump Over options at the end of your loop() function code.
