Package: arduino-dbg
Arduino debuggerThis is a console debugger for use with sketches running on an embedded Arduino system.
After uploading your sketch to the Arduino, you can connect the serial port to your
computer and debug your running sketch with this application.You must include a small debugging library (dbg.cppandPyArduinoDebug.h) available athttps://github.com/kimballa/PyArduinoDebugin your application.Arduino IDE users can include thePyArduinoDebuglibrary in their sketch dependencies.If compiling with a Makefile, you should#include <PyArduinoDebug.h>and link withlibPyArduinoDebug.ato enable debugging your sketch.You will find instructions inPyArduinoDebug.hon the API for creating unconditional
and assertion-based breakpoints, and emitting debug and trace messages.SetupInstall this debugger and its dependencies with:pip install .If not already installed, installbinutilsthrough your OS package manager.Clone and build theArduino librarywithmake install.Follow instructions inPyArduinoDebug.hto include in your application.Runarduino-dbgto launch the debug console. Use-hto see CLI options.Set your Arduino platform: e.g.:set arduino.platform = unoUse thehelpcommand at the prompt to see available capabilities.UsageTypical usage is something like:arduino-dbg -f /path/to/sketch.elf -p /dev/ttyACM0(Assuming your Arduino's USB serial port connection is onttyACM0.)If you run thebreakcommand or press^Cwithin the debugger, it will pause the
running sketch so you can interrogate or set the values of variables (print someglobal),
see abacktrace, etc. Programmatic breakpoints can be selectively toggled on and off
withbreakpoint enableandbreakpoint disable. New breakpoints can be created from
the debugger at runtime only on platforms like the ARM Cortex-M4 which support
monitor-mode debugging. On AVR CPUs, you are restricted to breakpoints added statically
in the source code.Within the debugger, you can save a dump of the system registers and memory withdump <filename>. With this dump file and the compiled ELF file of your sketch, you can then
perform offline debugging later witharduino-dbg -d /path/to/filename.dump, or by
runningload /path/to/filename.dumpwithin the debugger.The dump file will retain the filename of your sketch's ELF file. If you move it to a
different location, you can open the ELF file withopen /path/to/my.elfwithin the
debugger after running theloadcommand.There are several additional commands. Typinghelpwill list available commands in the
debugger. Typehelp <command>to see usage information for each specific command.Typequit,exit, or\qto quit the debugger.Arduino platformsYou should specify what Arduino platform you are using with thesetcommand. e.g.:set arduino.platform = unoThe available platforms are:feather_m4leonardounoYou can see an up-to-date list of supported Arduino platforms with thelist platformscommand. Thelist architecturescommand will display supported CPU architectures.By default the platform isauto, and the debugger will attempt to auto-detect your CPU.
You can force auto-detection with:set arduino.platform = autoPlease open an issue if you are interested in support for additional platforms. At the
time of this writing, the debugger has the ability to support AVR- and ARM-based
platforms; each new cpu or platform in these families just requires a new configuration file
to be added and tested.Typesetto see more configuration variables you can modify. Once set, configuration is
saved to~/.arduino_dbg.confand reused in future sessions. You can delete this file and
restart the debugger to reinitialize the default configuration.CPU-assisted debugger supportThis debugger can perform useful functions on any Arduino with a USB-serial connection.
The debugger service can be activated by breakpoints introduced with theBREAK()macro
or by issuing thebreak(^C) command within the debugger prompt.Beyond that, for CPUs that support "monitor-mode debugging" (where debug events trigger an
IRQ which can be handled with onboard software, rather than requiring control by an
external JTAG debugger), such as the ARM SAMD51-based Cortex-M4, used in the Adafruit
Feather-M4 platform, this debugger can also take advantage of CPU-assisted debugging
features such as single-stepping with thestep(\s) command, or using the ability to
create new breakpoints or watchpoints dynamically at run-time.On such platforms, the ARMBKPTopcode will also properly enter the debugger service.LicenseThis project is licensed under the BSD 3-Clause license. See LICENSE.txt for complete details.