This article has been accepted for publication in a future issue of this journal, but has not been
fully edited. Content may change prior to final publication. Citation information: DOI 10.1109/LES.2016.2619692, IEEE
IEEE-ESL-Aug-16-0113
Arduino Debugger
Jan Dolinay, Petr Dostálek, and Vladimír Vašek
Abstract—This letter describes our source-level debugger for
Arduino which can be used to debug the code in Arduino using
GNU debugger (GDB). The presented solution uses Eclipse as the
visual front-end. It does not require any modification of the
Arduino board or additional hardware; debug functionality is
achieved by adding a program library to the user application.
Standard functionality expected from a debugger is available,
such as setting breakpoints while debugging, stepping through
the code and viewing variables. This allows developing projects
with Arduino more efficiently and also using the Arduino for
teaching embedded programming at a more advanced level,
including debugging the program.
Index Terms—Arduino, Engineering
Microcontrollers, Software debugging.
INTRODUCTION
S INCEits introduction in 2003, the Arduino platform
became a very popular tool for hobby projects with
microcontrollers. But its usage is not limited to the “Maker”
world. It can be found in research laboratories as an affordable
and easy-to-use platform for controlling various apparatus or
performing experiments in many areas. For example, [1]
describes control of microfluidic devices and the authors of [2]
used Arduino in psychological and neurophysiological
experiments. The Arduino is also often used in education [4],
[5]. It is possible that it will soon become de facto standard
platform for teaching embedded systems and similar subjects.
Arduino is a microcontroller-based prototyping platform
which consists of a board with microcontroller (MCU),
software framework for this MCU and integrated development
environment (IDE) [3]. There are several boards available
ranging from very small, such as Arduino Nano, to powerful
boards with 32-bit MCU, such as Arduino Due. In this letter
we will be discussing the design of a debugger for probably
the most used board, Arduino Uno. This board is equipped
“This work was supported by the Ministry of Education, Youth and Sports
of the Czech Republic within the National Sustainability Programme project
No. LO1303 (MSMT-7778/2014) and also by the European Regional
Development Fund under the project CEBIA-Tech No. CZ.1.05/2.1.00/03”.
J. Dolinay, is with the Department of Automation and Control
Engineering, Faculty of Applied Informatics, of Tomas Bata University in
Zlín, nám. T. G. Masaryka 5555, 760 01 Zlín, Czech Republic (e-mail:
dolinay@fai.utb.cz).
P. Dostálek, is with the Department of Automation and Control
Engineering, Faculty of Applied Informatics, of Tomas Bata University in
Zlín, nám. T. G. Masaryka 5555, 760 01 Zlín, Czech Republic (e-mail:
dostalek@fai.utb.cz).
V. Vašek, is with the Department of Automation and Control Engineering,
Faculty of Applied Informatics, of Tomas Bata University in Zlín, nám. T. G.
Masaryka 5555, 760 01 Zlín, Czech Republic (e-mail: vasek@fai.utb.cz).
1943-0663 (c) 2016 IEEE. Personal use is permitted, but republication/redistribution requires IEEE permission. See http://www.ieee.org/publications_standards/publications/rights/index.html for more information.
Embedded Systems Letters
1
with Atmel 8-bit MCU ATmega328.
Arguably one of the main limitations of Arduino is its poor
debugging support. Being able to debug the program is very
desirable for any larger software project and also learning
about debugging is an important topic in embedded
programming courses.
The solution presented in this article makes it possible to
debug programs in Arduino without any extra hardware or
modification of the board. It only requires adding a program
library (driver) into the user application. The solution is based
on the widely-used GNU debugger GDB.
education, BACKGROUND AND RELATED WORK
A common way of debugging Arduino programs is sending
text messages to the host computer and using the on-board
LED. These two options are easily available with just a few
lines of code, but much better debugging support is available
and common in the MCU-based systems nowadays. A typical
MCU, including the ATmega328 used in Arduino Uno, has an
on-chip debug module which allows setting breakpoints,
stepping through the code, displaying variables, etc.
Unfortunately, the Arduino Uno board does not support this.
If an Arduino user desires more advanced debugging than
the above mentioned text messages and LED, they can use
Visual Micro debugger. This software tool allows developing
Arduino projects in Microsoft Visual Studio or Atmel Studio
[7]. Unlike the Arduino platform, which is an open source, this
tool is not free. Moreover, it does not allow inserting
breakpoints on the fly or stepping through the code.
Another option is connecting to the on-chip debugWire
interface available in the ATmega328 MCU. However, a
special device (debug adapter) is needed. An example of such
a device is AVR Dragon, which is probably the most
affordable tool for this purpose ($50). The Arduino board
requires a minor modification to allow using the debugWire
interface - there is a place on the board which needs to be cut.
Our debugger represents a third option based on the GNU
Project debugger (GDB) and the so called GDB stub. The
GDB stub (or GDB server) is a piece of code which runs in the
debugged MCU and executes commands from the GDB. We
have decided to use this approach because it requires no
modification of the hardware, it is free and GDB is accepted
as a standard for debugging in the industry.
The principle of GDB stub is commonly used on various
platforms [8], [9], [10]. However, to the best of the authors’
knowledge, it has not been implemented for the Arduino. We
have found three projects [11], [12], [13] which implement
such a stub code for the Atmel AVR family of
This article has been accepted for publication in a future issue of this journal, but has not been fully edited. Content may change prior to final publication. Citation information: DOI 10.1109/LES.2016.2619692, IEEE
Embedded Systems Letters
IEEE-ESL-Aug-16-0113
microcontrollers (the ATmega328 MCU used in the Arduino
Uno board belongs to this family), but none of them usable for
Arduino. Project [11] relies on modifying the flash memory of
the MCU to support breakpoints, which is hard to implement
on Arduino as explained in the next section.
Project [12] seems to be an unfinished experiment, last
updated in 2008 and project [13] is not designed to
communicate with GDB directly. So although each of these
projects provided valuable information for our work, it took
combining all three of them to obtain a working solution.
IMPLEMENTATION OF THE GDB STUB FOR ARDUINO
Our GDB stub is in principle a program library for the
ATmega328 MCU used in the Arduino Uno board. This
library acts as the GDB representative on the target machine.
It sends and receives any information which GDB needs. The
communication with GDB is carried on via the USB interface
available on the Arduino board, using the same virtual serial
port which is used to upload user programs. However, we
found the serial connection very unstable with GDB on host
computers with Windows operating systems, probably due to
non-standard implementation of the virtual serial port driver.
Therefore we use a proxy server running on the host system
which communicates with GDB via TCP socket on one side
and with the Arduino board via serial port on the other side.
For Linux hosts no such proxy is needed. The components and
communication interfaces of the debug system are shown in
Fig. 1. The dashed line represents the direct connection via
serial port which is usable on Linux systems.
Fig. 1. Configuration of the debug system with our GDB stub.
A. Communication Protocol
Our GDB stub communicates with the debugger using
standard GDB communication protocol called Remote Serial
Protocol (RSP). This protocol defines many commands but
only a few are required to make the stub work [9]. The
following commands are implemented in our stub:
• Last signal (?)
• Set thread (H) and is thread alive (T)
• Read registers (g) and write registers (G)
• Read memory (m) and write memory (M)
• Detach the debugger (D) and kill request (k)
• Continue (c) and step (s)
• Insert (Z) and remove (z) breakpoint
• Basic query requests (qSupported, qC, thread info)
1943-0663 (c) 2016 IEEE. Personal use is permitted, but republication/redistribution requires IEEE permission. See http://www.ieee.org/publications_standards/publications/rights/index.html for more information.
2
B. Breakpoint Implementation
Breakpoints are the most important functionality of the
GDB stub. Breakpoints are used not only to stop the program
at a user-selected point but are also internally used by GDB
when the user single-steps through the code.
In a GDB stub for the ATmega328 MCU a breakpoint can
be implemented either by inserting a call to the GDB stub at
the point at which the user requests the program to stop or by
comparing current position in the program (the program
counter register PC) with a list of requested breakpoint
addresses. The former method requires erasing and rewriting
parts of the flash memory upon any breakpoint insertion. This
leads to increased wear of the memory and also requires that
the flash-modification routines of the GDB stub are placed in
a special section of the MCU memory which is already
occupied by the Arduino bootloader. Although we believe it is
possible to somehow combine or link the GDB stub with the
Arduino bootloader and implement this method we have
decided to use the latter option, which is easier to implement
and does not affect the life of the program memory. Our GDB
stub keeps an array of breakpoint addresses in RAM memory
and compares these addresses with the current position in the
program after each machine instruction. If there is a match, the
user program is stopped and a message is sent to the debugger
on the host system, see Fig. 2. To let the GDB stub do the
comparison an interrupt must be triggered after the execution
of every instruction of the user program to give control to the
stub code. This method is based on the feature of the
ATmega328 MCU that one instruction of the main program is
always executed after returning from an interrupt service
routine (ISR) even if another interrupt request is already
pending. We use the external interrupt, configured to trigger
when the associated pin is low, for this purpose. The GDB
stub makes sure that there is continuous request for the
interrupt by configuring the pin as output and driving it low.
The obvious drawback of this method is that it considerably
reduces the execution speed of the program when any
breakpoint is set.
Fig. 2. Code of the GDB stub for handling breakpoints.
ANALYSIS AND DISCUSSION
The GDB stub was tested on computers with Windows 7,
Windows 10 and Linux Mint 17 operating systems in the
Eclipse IDE versions Luna (4.4.2) and Mars (4.5.0) with build
tools and GDB obtained from Arduino IDE version 1.6.8. It
should be possible to use the stub with any other IDE which
allows configuring GDB for debugging. It is not possible to
use the Arduino IDE, because it does not have any support for
debugging. Testing environment with Windows 7 laptop
computer can be seen in Fig. 3.
This article has been accepted for publication in a future issue of this journal, but has not been fully edited. Content may change prior to final publication. Citation information: DOI 10.1109/LES.2016.2619692, IEEE
Embedded Systems Letters
IEEE-ESL-Aug-16-0113
A. Usage of the Debugger
To explain the usage of the debugger we will describe
simple use case with the traditional Arduino sample program
which blinks the on-board LED connected to pin 13.
Fig. 3. Testing environment with Windows 7 computer running the Eclipse
IDE with GDB. Arduino Uno is connected via USB cable.
To use the proposed debugger the user first needs to add the
code of the GDB stub into their project. The code is located in
two files, avr8-stub.c and avr8-stub.h.
Then a call to debug_init function must be placed in the
initialization part of the user code. In a typical Arduino
program this will be in the setup function, which is executed
once upon power up or reset, see Fig. 5.
Once the program is built and uploaded to the board a
debug session can be configured and started. The Eclipse IDE
acts as a visual front-end to the GDB debugger which
connects to the GDB stub code running in the target MCU.
The connection with the debug target can use the Arduino
virtual serial port directly on Linux hosts, for example,
/dev/ttyS0. On Windows hosts the connection is established
via free TCP-to-serial proxy server hub4com.
Unless a breakpoint has been pre-set in the code the
program in the target MCU is now freely running and the on-
board LED is blinking. The program can be stopped using the
Suspend button in the IDE. It will be stopped at arbitrary
position, most likely inside the delay function, as can be seen
in Fig. 4.
Fig. 4. The call stack of the test program after it has been stopped by the
debugger.
1943-0663 (c) 2016 IEEE. Personal use is permitted, but republication/redistribution requires IEEE permission. See http://www.ieee.org/publications_standards/publications/rights/index.html for more information.
3
Fig. 4 shows the call stack which indicates that the program
is stopped in micros function which was called from the delay
function which was itself called from the loop function (see
also Fig. 5 with the loop function code).
Fig. 5. Sample program with two breakpoints inserted. The program is
stopped at the first one.
The user can, for example, insert breakpoints into the loop
function or step through the code using the Step into or Step
over buttons in the IDE. Fig. 5 shows the code with two
breakpoints inserted and the program stopped at the first one.
B. Use Cases
To illustrate the benefits of using the debugger let us take
the same sample program as earlier but this time with an error
– a misspelled call to the delay function with the argument
missing. The code can be seen in Fig. 6.
The compiler will issue a warning but if the user ignores it,
it is possible to upload and run the program. But instead of
blinking, the LED will be continuously on. With a debugger at
hand the user can connect to the program and suspend it. Then
they can step through the program line by line and see that
stepping over the first call to delay function takes a noticeable
amount of time but the second call to delay is skipped
immediately. This indicates that the problem is on this line of
the program and the user is now likely to notice the missing
argument.
As another use case let us consider similar program with
busy loop delay instead of the Arduino delay function. There
is a hard-to-find error in the for loop – the variable “i” used as
the loop counter is too short (16 bits) to ever reach the value
against which it is compared (100,000). As a result the loop
never finishes. The visible result is that the LED is always on
because the program never returns from the first call to the
delay function.
This article has been accepted for publication in a future issue of this journal, but has not been fully edited. Content may change prior to final publication. Citation information: DOI 10.1109/LES.2016.2619692, IEEE
Embedded Systems Letters
IEEE-ESL-Aug-16-0113
Fig. 6. Sample program with the argument missing in the second call to delay
function.
Fig. 7. Delay function with busy loop. The for loop will never end because
the 16-bit variable i can never reach value 100,000.
If the user connects to the program with the debugger and
suspends it, the program will be stopped inside the mydelay
function. The user can hoover the mouse over the “i” variable
to see its value. This may be some arbitrary number, e.g. 8466,
as shown in Fig. 8. Resuming the program for a while and
suspending it again it is possible to observe the changes of the
value. Yet a better approach will be to place a breakpoint at
the last line of the mydelay function, i.e. at the closing brace.
The program should stop at this breakpoint after the loop
finishes. Since it never stops, it is clear that the loop never
finishes. Finding the reason why it never finishes may take
some time still, but at least the location and reason of the
incorrect program behavior were quickly identified.
Fig. 8. Inspecting the value of the variable i.
C. Memory Utilization and Performance
Our debugger stub requires approximately 5 kB of program
memory (flash) out of the 32 kB available in the MCU, and
255 Bytes of RAM (out of 2 kB available). We consider this to
be acceptable for most Arduino projects. Someone developing
a cutting-edge application will probably use a hardware
debugger rather than our software solution.
As already mentioned, when breakpoints are set, the
debugged program runs at a significantly reduced speed. The
overall effect depends on the design of the debugged program.
For example, the Arduino delay function, which is internally
implemented by polling hardware timer, is slowed down by a
factor of 4 - a one second delay takes four seconds to execute.
If a simple busy loop is used to generate a delay, the delay will
be stretched approximately by a factor of 350 - a busy loop
which normally takes 100 milliseconds will take about 35
seconds to execute. In such a case it will be necessary to
1943-0663 (c) 2016 IEEE. Personal use is permitted, but republication/redistribution requires IEEE permission. See http://www.ieee.org/publications_standards/publications/rights/index.html for more information.
4
modify the delay function for debugging purposes. In our
experience it is possible to cope with this limitation, for
example, by inserting and removing breakpoints as needed
(this is fast operation with no side effects such as rewriting the
program memory in our solution). There is also a breakpoint
function available in our stub which can be used to insert
breakpoints at compile time which do not affect the execution
speed of the program. The source code of our stub and
detailed instructions for use can be found at
(http://www.codeproject.com/Articles/1037057/Debugger-for-
Arduino).
CONCLUSION
In this letter we presented a source-level debugger for
Arduino. It offers a unique option for debugging Arduino
programs with the standard GNU debugger GDB. Together
with Eclipse IDE this allows building a complete development
environment for micro-controller applications based on free
software and hardware. Having a debugger allows developing
programs for Arduino more efficiently and also using the
Arduino for teaching embedded programming on a more
advanced level, including debugging the program.
Our solution is implemented as the so called GBD stub,
which is a code running on the debugged micro-controller. It
provides common functionality expected from a debugger,
such as setting and removing breakpoints while debugging,
stepping through the code and inspecting variables.
REFERENCES
[1] E. T. da Costa, M. F. Mora, P. A.Willis, C. L. do Lago, H. Jiao, and C. D.
Garcia, “Getting started with openhardware: Development and control of
microfluidic devices,” Electrophorensis, vol. 35, pp. 2370–2377, Aug.
2014.
[2] A. D’Ausillio, “Arduino: A low-cost multipurpose lab equipment,”
Behavior Research Methods, vol. 44, no. 2, pp. 305-313, Jun. 2012.
[3] Anon. (2015, May). Arduino Home Page. [online]. Available:
http://arduino.cc
[4] P. Bender, K. Kussmann, “Arduino based projects in the computer
science capstone course,” Journal of Computing Sciences in Colleges,
vol. 27, no. 5, pp. 152-157, May 2012.
[5] P. Jamieson. (2012, April). Arduino for Teaching Embedded Systems.
Are Computer Scientists and Engineering Educators Missing the Boat?
[online]. Available
www.users.muohio.edu/jamiespa/html_papers/fecs_11.pdf
[6] Anon. (2015, February). Why Arduino is not the right educational tool.
[online]. Available: http://www.hackvandedam.nl/blog/?p=762
[7] Anon.(2015, February). Arduino IDE for Microsoft Visual Studio and
Atmel Studio. [online]. Available: http://www.visualmicro.com
[8] H. Li, Y. Xu, F. Wu, C. Yin, "Research of “Stub” remote debugging
technique," Proceedings of 2009 4th International Conference on
Computer Science & Education, Nanning, China, 2009, pp. 990-993.
[9] J. Bennett. (2015, February). Howto: GDB Remote Serial Protocol,
Writing a RSP Server. [online]. Available:
http://www.embecosm.com/appnotes/ean4/embecosm-howto-rsp-server-
ean4-issue-2.html
[10] M. Tan (2015, February) A minimal GDB stub for embedded remote
debugging. [online]. Available:
http://www.cs.columbia.edu/~sedwards/classes/2002/w4995-02/tan-
final.pdf
[11] R. Pen. (2015, May). AVR-GDB Server. [online]. Available:
https://github.com/rouming/AVR-GDBServer
[12] I. Doornekamp (2015, May). AVR gdbstub. [online]. Available:
http://zevv.nl/play/code/avr-gdbstub.
[13] S. Vakulenko. (2013, June). uOS - embedded operating system. [online].
Available: https://code.google.com/p/uos-embedded.