Introduction

MCUViewer is a non-intrusive GUI debugging tool for microcontrollers that allows quick visualization of variable values in real-time.

Downloads¶

MCUViewer can be downloaded from the MCUViewer website.

Supported Probes and MCUs¶

MCUViewer natively supports the following interfaces:

• ST-Link

• J-Link

• OpenOCD-compatible probes (via GDB server; not all are fully tested)

If your probe is not natively supported by MCUViewer (for example, TI C2000 probes), you can use the Serial Driver solution instead. This allows MCUViewer to communicate with any target device that provides a serial interface, making it a universal fallback option.

Installation¶

Windows¶

On Windows MCUViewer can be either installed or unpacked (portable version). Unpacking might be preferable in some cases as it does not require admin rights.

• Installing - download the *.zip file, unpack it, and double click the installer. Follow the instructions.

• Unpacking - download the *.zip file, unpack it, and unpack the *.exe installer once again. Copy the unpacked folders to a preferred location. Run by double clicking the MCUViewer.exe file from bin directory.

Linux¶

Download the *.deb package and install it using: sudo apt install ./MCUViewer-x.y.z-Linux.deb

On Linux MCUViewer requires a valid gdb. Please install it if not already present. You can check if it works by typing gdb --version in your terminal window.

MacOS¶

Download the *.dmg package. Open it and drag and drop the MCUViewer app to Applications folder. If you’re on ARM, you’ll be propmted to install Rosetta when running the app. If the application does not run due to unverified source, make sure to allow it in the security preferences (Privacy & Security -> Security -> “Open Anyway”).

Quick Start - Variable Viewer¶

The Variable Viewer module samples the addresses of selected variables at regular time intervals. It is generally well-suited for medium-frequency signals, as the sampling rate is limited by the SWD speed and the type of probe used. If high-speed readout is required, please refer to the Recorder section or try the SWO-based Trace Viewer.

Your target should be connected to the debug probe using SWDIO, SWCLK, and GND pins.

1. Select the *.elf file of your project in Options->Acquisition.

2. Choose the debug probe.

3. Close the Options->Acquisition window and click the Import Variables button.

4. Select the variables you want to visualize and click Import.

5. Drag and drop the selected variables onto the plot canvas.

6. Click the large STOPPED button to start data acquisition.

In case of any errors make sure to visit Variable Viewer and FAQ

Quick Start - Trace Viewer¶

The Trace Viewer module parses SWO trace data and displays the results in the form of plots. It enables visualization of high-speed signals with minimal overhead, as well as digital plots for visualizing and profiling interrupt execution.

Your target should be connected to the debug probe using the SWDIO, SWCLK, SWO, and GND pins.

1. Switch to the Trace Viewer tab.

2. Select the debug probe in Options → Acquisition, then close the window.

3. Enter your core frequency in kHz in the main window.

4. Select a trace prescaler - start with a relatively high value (e.g., ~20), as this depends heavily on your debug probe and SWD setup.

5. In your code, place special markers:

Example for digital data:

ITM->PORT[x].u8 = 0xaa; //enter tag 0xaa - plot state high
foo();
ITM->PORT[x].u8 = 0xbb; //exit tag 0xbb - plot state low

And for tracing “analog” signals you can use:

float a = sin(10.0f * i);          // some high frequency signal to trace
ITM->PORT[x].u32 = *(uint32_t*)&a; // type-punn to desired size: sizeof(float) = sizeof(uint32_t)

or

uint16_t a = getAdcSample();       // some high frequency signal to trace
ITM->PORT[x].u16 = a;              

where x is the channel number in MCUViewer. Moreover you need to configure the SWO pin of your microcontroller.

6. Click the large STOPPED button to begin acquisition

In case of any errors please visit Trace Viewer and FAQ

License¶

MCUViewer is distributed under the EULA License. The license is available online and after installation in:

• Windows: C:\Program Files\MCUViewer\bin

• Linux: /usr/local/MCUViewer

• MacOS: Applications/MCUViewer/Contents/Resources

For questions regarding licensing, contact contact@mcuviewer.com.

Reporting bugs or improvements¶

To report an issue or a feature request please contact us at contact@mcuviewer.com or start a new issue on the MCUViewer GitHub repository.

In case of a bug, please provide the following information to make it easier to reproduce and fix:

1. MCUViewer version

2. Operating system and version

3. Debug probe and target type

4. Log file (log directory can be found in Settings->General window)

5. Steps to reproduce, screenshots or videos of the issue