MCUViewer: The “Eye” of Embedded Debugging for One-Click Visualization of Variables and Traces

What is MCUViewer?MCUViewer (formerly STMViewer) is a GUI debugging tool specifically designed for MCU developers, consisting of two core modules:

Module	Main Functionality	Applicable Scenarios
Variable Viewer	Real-time reading of variable values in RAM, supporting plotting, logging, and manual value modification	Monitoring global variables, debugging algorithm parameters
Trace Viewer	Parsing SWO traces, displaying high-frequency signals, function execution durations, etc.	Sampling high-speed interrupts, performance profiling, signal waveforms

The hardware requirements are minimal; just a single ST-Link or J-Link can present the internal state of the MCU on a computer like a monitoring dashboard.

What Pain Points Does MCUViewer Address?

1. 1. “Invisible Variables”— Traditional serial printing consumes a lot of CPU and can only be identified visually. The Variable Viewer reads directly from RAM, with zero intrusion and no additional instructions.
2. 2. Difficulty in Capturing High-Frequency Signals— UART-UART-UART rates cannot keep up with the internal clock of Cortex-M. The Trace Viewer relies on hardware ITM/SWO, allowing MHz-level waveforms to be captured with a single register write.
3. 3. Cross-Platform Debugging Limitations— STMStudio only runs on Windows and does not support J-Link. MCUViewer provides installation packages for both Linux and Windows, compatible with ST-Link and J-Link.
4. 4. Fragmented Debugging Information— Variables and traces are viewed with different tools, leading to high switching costs. MCUViewer combines both into one, unifying the UI, saving time and effort.

Installation & Usage Tips

Linux

1. 1. Ensure the system has gdb ≥ 12.1.
2. 2. Download <span>MCUViewer-x.y.z-Linux.deb</span>, execute <span>sudo apt install ./MCUViewer-*.deb</span>.
3. 3. If ST-Link is not recognized, copy the rules from <span>launch/install/Unix/udevrules/</span> to <span>/etc/udev/rules.d/</span>.

Windows

1. 1. Download the exe installer directly from the Release page.
2. 2. Set the ST-Link to “STM32 Debug + Mass Storage + VCP” mode, otherwise a libusb error will occur.
3. 3. If the graphics card performance is sufficient, you can assign the external GPU to MCUViewer in the settings to improve rendering smoothness.

Quick Start – Variable Viewer

1. 1. Open Options → Acquisition Settings, select the project’s <span>.elf</span> (must be compiled in Debug mode).
2. 2. “Import variables from *.elf”, select the global variables you want to observe. If not automatically recognized, click Add variable to manually enter the name.
3. 3. Click Update variable addresses, the address will change from “NOT FOUND!” to the actual RAM address.
4. 4. Drag the variables to the plotting area, connect the debugging probe, download the firmware, and click STOPPED to see the real-time curves.

Quick Start – Trace Viewer

1. 1. In CubeMX → System Core → SYS Mode & Configuration, enable Trace Asynchronous SWO.
2. 2. Insert ITM markers in the code, for example:

   ITM->PORT[0].u8 = 0xAA; // Enter
   foo();
   ITM->PORT[0].u8 = 0xBB; // Exit

   If you want to trace floating-point or ADC data, you can use <span>ITM->PORT[x].u32 = *(uint32_t*)&f;</span>.

3. 3. Compile and download, open Trace Viewer, fill in the System Core Clock (kHz) in Settings, and adjust the prescaler (the upper limit for ST-Link V2 is about 2 MHz).
4. 4. Press STOPPED to start recording; waveforms and timestamps will be displayed in real-time.

Pros and Cons Quick Review

Pros	Cons
✅ Zero-intrusion variable reading, almost no impact on MCU operation	⚠️ Can only monitor global (persistent) variables; local variables cannot be captured directly
✅ Supports SWO Trace, capturing MHz-level signals	⚠️ 64-bit (<span>uint64_t</span>, <span>double</span>) variables are currently not supported
✅ Cross-platform (Linux/Windows), compatible with ST-Link and J-Link	⚠️ High wiring requirements for SWO pins; long lines can cause erroneous frames
✅ UI based on ImGui, smooth interaction, customizable layout	⚠️ Requires manual configuration of <span>.elf</span> paths and clock parameters, which may pose a slight barrier for newcomers
✅ Open-source (up to version 1.1.0) for self-compilation and secondary development	⚠️ Subsequent versions have closed source; updates depend on the official release of binaries

ConclusionIf you are working on motor control, real-time DSP, or any embedded project sensitive to timing and variable changes, MCUViewer can bring the “invisible internal state” to the screen, saving you the hassle of printf and serial debugging. It combines variable monitoring and trace visualization into one, helping you quickly locate algorithm errors and perform performance profiling in release versions. The only thing to note is that variables must be global and have fixed addresses, and the wiring for SWO pins must be stable. Overall, this is a highly cost-effective “debugging Swiss Army knife.”

Project address: https://github.com/klonyyy/MCUViewer