This project provides a virtual development environment for STM32 microcontrollers running MicroPython, using QEMU for hardware emulation. It allows developers to build and test IoT applications without physical hardware.
Current Release: v2025.03.04.17 (v1.1.0-beta.5)
Current Milestone: v1.1.0 - Debugging and QEMU Integration (In Progress, ~99% complete)
Roadmap Progress: View detailed status
We are currently focusing on improving debugging capabilities and QEMU integration. Recent progress includes:
- Added comprehensive GDB integration with MicroPython debugging support
- Implemented Python-level debugging with stack trace, variable inspection, and exception handling
- Enhanced breakpoint support with Python function name resolution and memory inspection
- Added comprehensive exception handling capabilities with type filtering and state inspection
- Enhanced exception visualization with color-coded output and interactive navigation
- Created comprehensive documentation for exception handling commands and workflows
- Completed implementation of custom UART driver for QEMU with simulation features
- Enhanced network simulation with robust device-to-device communication
- Added comprehensive debugging guide and documentation
See our Version History for more details on releases.
- QEMU-based emulation of STM32F4 microcontrollers
- MicroPython firmware with STM32 support
- Sensor simulation and peripheral emulation
- IoT connectivity for device telemetry
- Development workflow from virtual testing to physical deployment
qemu-micropython/
├── bin/ # Compiled binaries and firmware
├── config/ # QEMU and environment configurations
│ ├── boards/ # Board-specific configurations
│ ├── micropython/ # MicroPython build configuration
│ └── qemu/ # QEMU machine definitions
├── docs/ # Documentation
├── firmware/ # MicroPython firmware builds
├── scripts/ # Utility scripts for the environment
│ ├── build.sh # Build the firmware
│ ├── run_qemu.sh # Start QEMU with proper parameters
│ └── flash.sh # Flash firmware to QEMU or physical device
├── src/ # Project source code
│ ├── lib/ # Libraries and modules
│ └── main.py # Main application code
├── tests/ # Test suite
└── tools/ # Additional development tools
- Git
- Python 3.x
- ARM GCC Toolchain (arm-none-eabi-gcc)
- Make
Note: QEMU will be automatically downloaded and built by the setup script.
-
Clone this repository:
git clone https://github.com/yourusername/qemu-micropython.git cd qemu-micropython -
Run the environment setup script:
chmod +x scripts/setup_env.sh ./scripts/setup_env.sh
This will:
- Install required dependencies
- Clone and build QEMU with STM32 support
- Clone and prepare MicroPython for STM32
- Set up board configurations
To build the MicroPython firmware with your application:
./scripts/build.shThe script is currently configured to build for the STM32F4DISC board. The build process creates firmware files (which may include firmware0.bin and firmware1.bin for split firmware boards).
To run your application in the QEMU emulator:
./scripts/run_qemu.shThis will:
- Check for firmware files in the build directory
- Handle split firmware files if necessary (combining them for QEMU)
- Start QEMU with the appropriate configuration for the target board
- Load your firmware and start execution
Note: We're currently using the olimex-stm32-h405 machine type in QEMU as it has a Cortex-M4 processor similar to the STM32F4 Discovery board.
When you're ready to deploy to a physical STM32 device:
./scripts/flash.sh /dev/ttyACM0Replace /dev/ttyACM0 with the appropriate device path for your board.
- Write your MicroPython application in
src/main.py - Add supporting modules in
src/lib/ - Build the firmware with
./scripts/build.sh - Test in QEMU with
./scripts/run_qemu.sh - Debug and refine your code
- Deploy to physical hardware with
./scripts/flash.sh
The repository includes a sample IoT application that demonstrates:
- GPIO control (LED blinking)
- I2C sensor reading (temperature, humidity)
- MQTT-based IoT connectivity
When running in QEMU, you can use our enhanced debugging capabilities:
# Start a debugging session with full MicroPython support
./scripts/debug_micropython.shThis will:
- Launch QEMU with the firmware in debug mode
- Start GDB with MicroPython helper scripts
- Set up common breakpoints and configurations
- Enable Python-level debugging
Our debugging environment provides:
- Python stack tracing and inspection
- Variable and object examination
- Exception analysis
- Custom MicroPython GDB commands
See our GDB Debugging Guide for detailed instructions.
-
QEMU machine type errors: If you encounter errors about unsupported machine types, check the
config/qemu/stm32f4.cfgfile. You may need to modify it to use a different machine type supported by your QEMU build. -
Firmware not found: The build process generates different firmware files depending on the board. For STM32F4DISC, it creates split firmware files (firmware0.bin and firmware1.bin). The run script automatically handles this.
-
Build failures: Ensure you have the ARM toolchain (arm-none-eabi-gcc) installed and in your PATH.
- Not all STM32 peripherals are fully emulated in QEMU
- We're using olimex-stm32-h405 as a substitute for STM32F4-Discovery in QEMU
- Timing may differ between emulated and physical environments
- Some hardware-specific features may require adjustment for accurate simulation
The project is organized into several milestone releases:
- GDB integration for step-by-step debugging (99% complete)
- Custom UART driver optimized for QEMU (100% complete)
- Better semihosting integration for reliable output (50% complete)
- Exploration of alternative QEMU machine types for STM32F4 (40% complete)
- Comprehensive unit testing framework (97% complete)
Target completion: Q2 2025
- Network simulation for IoT connectivity testing
- Virtual sensors simulation (temperature, humidity, motion)
- State snapshots for efficient scenario testing
- Over-the-air update mechanisms for firmware deployment
Target completion: Q4 2025
- Continuous integration and deployment pipeline (30% complete)
- Automated testing in virtual environments
- Documentation improvements (35% complete)
Target completion: Q1 2026
You can track the detailed progress of these features in our Roadmap Status document, GitHub Project and Milestones.
We use a dual versioning system:
- Date-based versions (vYYYY.MM.DD.build) for automated builds and incremental releases
- Semantic versions (v1.x.y) for major milestone completions
For mapping between version types, see our Version Mapping Guide.
- v1.0.0 (March 1, 2025): Initial release with documentation and testing tools
- v1.1.0-alpha (March 1, 2025): Early work on debugging and QEMU integration
- v1.1.0-beta.1 (March 2, 2025): Continued improvements to debugging capabilities
- v1.1.0-beta.2 (March 3, 2025): Completed implementation of custom UART driver for QEMU with simulation features
- v1.1.0-beta.4 (March 4, 2025): Comprehensive GDB integration with MicroPython debugging support
- v1.1.0-beta.5 (March 5, 2025): Enhanced exception visualization with color-coded output and interactive navigation
For full release details, visit our Releases Page.
Contributions are welcome! Please feel free to submit a Pull Request. For release notes, please follow our Release Notes Template.
This project is licensed under the MIT License - see the LICENSE file for details.
- MicroPython project: https://micropython.org/
- QEMU project: https://www.qemu.org/
- STM32 community: https://www.st.com/