Package: emdbg
Embedded Debug ToolsThe emdbg library connects several software and hardware debugging tools
together in a user friendly Python package to more easily enable advanced use
cases for ARM Cortex-M microcontrollers and related devices.The library orchestrates the launch and configuration of hardware debug and
trace probes, debuggers, logic analyzers, and waveform generators and provides
analysis tools, converters, and plugins to provide significant insight into the
software and hardware state during or after execution.The main focus of this project is the debugging of the PX4 Autopilot firmware
running the NuttX RTOS on STM32 microcontrollers on the FMUv5x and FMUv6x
hardware inside the Auterion Skynode. However, the library is modular and the
tools are generic so that it can also be used for other firmware either
out-of-box or with small adaptations.emdbg is maintained by@niklautfromAuterion.FeaturesDebug Probes: SWD and ITM/DWT over SWO.SEGGER J-Link: BASE Compact, EDU Mini.OpenOCD:STMicro STLinkv3.Coredump:CrashDebugwith support for PX4 Hardfault logs.Trace Probes: ITM/DWT/ETM over TRACE.Orbcode ORBTrace mini.SEGGER J-Trace(planned).GDB Debugger.Automatic management of debug probe drivers.Remote interfacing viaGDB/MIand RPyC.Plugins viaGDB Python API.User commands for PX4 and NuttX.Task information.Task switching to inspect call stack.Coredumping of memories and peripherals.GPIO state visualization.Backtrace generation.Register state visualization using SVD files.Register access watching and difference visualization.Hardfault trapping with immediate backtrace.Real-time instrumentation using ITM/DWT.Up to 2MB/s SWO capture via STLinkv3, 3MB/s via JLink.Visualization of task switching and interrupts viaperfetto.Latency measurement of scheduler and task priorities.Heap usage tracking via malloc, free, realloc, alignmem.Nanosecond resolution with very little runtime overhead.Patch Manager for out-of-tree modifications.Power Switch.Yocto USB Relay.Logic Analyzer and Waveform Generator.Digilent Analog Discovery 2via Python API.Sigrok(prototyped).Visualization viaperfetto(planned).Serial Protocols.NuttX NSH command prompt.Hardware configuration.FMUv5x and FMUv6x.A number of GDB and NSH scripting examples for test automation can be found in
thescriptsfolder.PresentationsDebugging MicrocontrollersPresented at Chaos Communication Camp by Niklas Hauser on 2023-08-18.Debugging and Profiling NuttX and PX4Presented at the NuttX International Workshop by Niklas Hauser on 2023-09-29.InstallationThe latest version is hosted on PyPi and can be installed via pip:pip3installemdbgYou also need to install other command line tools depending on what you use:Debugger:arm-none-eabi-gdb-py3.Debug probes:J-Link,OpenOCD,CrashDebug.Analysis:graphvizUsageMost modules have their own command-line interface. This library therefore has
many entry points which can be called usingpython3 -m emdbg.{module}.
The individual command line usage is documented in each module.
The most important modules areemdbg.debug.gdbandemdbg.bench.fmu:For example, launching GDB with TUI using a J-Link debug probe:python3-memdbg.debug.gdb--elfpath/to/firmware.elf--ui=tuijlink-deviceSTM32F765IIDocumentationMost important user guides are available as Markdown files in the repository.
You can browse the API documentation locally using thepdoclibrary:pdocemdbg# pdoc server ready at http://localhost:8080DevelopmentFor development, checkout the repository locally, then install with the-eflag, which symlinks the relevant files into the package path:cdembedded-debug-tools
pip3install-e".[all]"