# STM32Bridge - STM32CubeMX to PlatformIO Migration Tool
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://platformio.org/)
A comprehensive CLI utility to automate the migration of STM32CubeMX projects to PlatformIO with full FreeRTOS support.
## 📦 Installation
### From PyPI (Recommended)
```bash
pip install stm32bridge
```
### Development Installation
```bash
git clone https://github.com/jobenas/stm32bridge.git
cd stm32bridge
pip install -e .
# For testing and development
pip install -r requirements-dev.txt
# Or install specific dependency groups
pip install -e .[test] # Testing dependencies
pip install -e .[dev] # Development tools
pip install -e .[pdf] # PDF processing (optional)
pip install -e .[build] # Build tools
```
### From Local Wheel
```bash
# Build and install from source
git clone https://github.com/jobenas/stm32bridge.git
cd stm32bridge
pip install build
python -m build
pip install dist/stm32bridge-1.0.0-py3-none-any.whl
```
### Prerequisites
- Python 3.8 or higher
- PlatformIO Core (automatically checked and installed if needed)
- Git (for some FreeRTOS library dependencies)
## 🚀 Features
- **Complete Project Migration**: Analyzes STM32CubeMX projects and creates fully configured PlatformIO projects
- **FreeRTOS Support**: Automatic FreeRTOS library integration with CMSIS-OS v2 compatibility
- **Build Verification**: Integrated build testing with automatic dependency resolution
- **Editor Integration**: Open migrated projects directly in your favorite code editor
- **Board Detection**: Automatic MCU and board detection with extensive board mapping
- **Flexible Configuration**: Support for custom boards, FreeRTOS configurations, and build options
## 📁 Project Structure
```
stm32bridge/
├── main.py # CLI entry point
├── stm32bridge/
│ ├── __init__.py # Package initialization
│ ├── constants.py # MCU families and board mappings
│ ├── exceptions.py # Custom exceptions
│ ├── core/ # Core migration logic
│ │ ├── analyzer.py # STM32CubeMX project analysis
│ │ ├── generator.py # PlatformIO project generation
│ │ └── migrator.py # File migration and adaptation
│ ├── utils/ # Utility modules
│ │ ├── build.py # Build verification and dependency management
│ │ ├── editor.py # Code editor integration
│ │ ├── platformio.py # PlatformIO command execution
│ │ └── boards.py # Board detection utilities
│ └── cli/ # CLI command implementations
│ ├── migrate.py # Migration command
│ ├── analyze.py # Analysis command
│ └── list_boards.py # Board listing command
└── stm32bridge.py # Legacy monolithic version (for reference)
```
## 🛠️ Installation
### Prerequisites
- Python 3.8+
- PlatformIO Core (installed via pip or standalone)
### Install STM32Bridge
```bash
# Clone the repository
git clone <repository-url>
cd stm32bridge
# Install in development mode
pip install -e .
# For development with all dependencies
pip install -r requirements-dev.txt
# Or install specific dependency groups
pip install -e .[test] # Testing dependencies
pip install -e .[dev] # Development tools
pip install -e .[pdf] # PDF processing (optional)
```
## 📖 Usage
### Basic Migration
```bash
# Migrate a project with automatic board detection
stm32bridge migrate my_stm32_project my_platformio_project
# Specify a specific board
stm32bridge migrate my_stm32_project my_platformio_project --board nucleo_l432kc
# Windows example
stm32bridge migrate C:\Projects\MySTM32Project C:\Projects\MyPlatformIOProject --board nucleo_f401re
# Linux/Mac example
stm32bridge migrate ~/projects/my_stm32_project ~/projects/my_platformio_project --board disco_f407vg
```
### Advanced Options
```bash
# Migrate with build verification
stm32bridge migrate my_stm32_project my_platformio_project --board nucleo_l432kc --build
# Migrate and open in VS Code
stm32bridge migrate my_stm32_project my_platformio_project --board nucleo_l432kc --open
# Use different editor
stm32bridge migrate my_stm32_project my_platformio_project --board nucleo_l432kc --open --editor code
# Force overwrite existing directory
stm32bridge migrate my_stm32_project my_platformio_project --force
```
### FreeRTOS Options
```bash
# Use framework FreeRTOS instead of external library
stm32bridge migrate my_stm32_project my_platformio_project --no-freertos
# Completely disable FreeRTOS migration
stm32bridge migrate my_stm32_project my_platformio_project --disable-freertos
# Use PlatformIO framework's built-in FreeRTOS
stm32bridge migrate my_stm32_project my_platformio_project --framework-freertos
```
### Analysis and Information
```bash
# Analyze project without migration
stm32bridge analyze my_stm32_project
# List supported boards
stm32bridge list-boards
# Get help
stm32bridge --help
stm32bridge migrate --help
```
## 🔧 Supported Features
### MCU Families
- STM32F0, F1, F2, F3, F4, F7
- STM32G0, G4
- STM32H7
- STM32L0, L1, L4, L5
- STM32U5
- STM32WB
### FreeRTOS Integration
- Automatic FreeRTOS library detection and integration
- CMSIS-OS v2 compatibility layer
- Custom FreeRTOS configuration preservation
- Support for timers, event groups, and other FreeRTOS features
### Build System
- Complete PlatformIO configuration generation
- Automatic dependency resolution
- Build verification with memory usage reporting
- Support for custom build flags and configurations
### Development Tools
- VS Code, VSCodium, Sublime Text, Atom, Vim support
- STLink upload and debug configuration
- Serial monitor setup
- Custom board definitions
## 🎯 Example Workflow
1. **Generate STM32CubeMX Project**: Create your project with Makefile toolchain
2. **Analyze**: `python main.py analyze /path/to/project` to verify compatibility
3. **Migrate**: `python main.py migrate /path/to/project /path/to/output --board nucleo_l432kc --build --open`
4. **Develop**: Your PlatformIO project is ready with full build and debug support!
## 🐛 Troubleshooting
### Common Issues
- **Build Failures**: Use `--build` flag to get detailed error analysis and automatic fixes
- **Missing Dependencies**: Tool automatically installs required Python packages (GitPython, etc.)
- **FreeRTOS Issues**: Try `--no-freertos` or `--framework-freertos` flags
- **Board Detection**: Use `python main.py list-boards` to find the correct board name
### Debug Options
- Use `python main.py analyze` to validate project structure
- Check PlatformIO installation: `pio --version`
- Verify board support: `pio boards | grep <your-mcu>`
## 🤝 Contributing
The codebase is now well-organized and modular:
- **Core Logic**: Add new features in `stm32bridge/core/`
- **Utilities**: Add helper functions in `stm32bridge/utils/`
- **CLI Commands**: Add new commands in `stm32bridge/cli/`
- **Configuration**: Update constants in `stm32bridge/constants.py`
## 📄 License
MIT License - see LICENSE file for details.
## 🙏 Acknowledgments
- PlatformIO team for the excellent embedded development platform
- STMicroelectronics for STM32CubeMX
- FreeRTOS community for real-time OS support
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/stm32bridge",
"name": "stm32bridge",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "stm32, cubemx, platformio, embedded, migration, freertos, arm, cortex, microcontroller, iot",
"author": "STM32Bridge Team",
"author_email": "STM32Bridge Team <dev@stm32bridge.com>",
"download_url": "https://files.pythonhosted.org/packages/df/f9/79c7fc9b153b3c20d4fabf3bcc096a700b82f61fca17f612f8f1ac8b5203/stm32bridge-1.3.3.tar.gz",
"platform": null,
"description": "# STM32Bridge - STM32CubeMX to PlatformIO Migration Tool\r\n\r\n[](https://www.python.org/downloads/)\r\n[](LICENSE)\r\n[](https://platformio.org/)\r\n\r\nA comprehensive CLI utility to automate the migration of STM32CubeMX projects to PlatformIO with full FreeRTOS support.\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n### From PyPI (Recommended)\r\n```bash\r\npip install stm32bridge\r\n```\r\n\r\n### Development Installation\r\n```bash\r\ngit clone https://github.com/jobenas/stm32bridge.git\r\ncd stm32bridge\r\npip install -e .\r\n\r\n# For testing and development\r\npip install -r requirements-dev.txt\r\n\r\n# Or install specific dependency groups\r\npip install -e .[test] # Testing dependencies\r\npip install -e .[dev] # Development tools \r\npip install -e .[pdf] # PDF processing (optional)\r\npip install -e .[build] # Build tools\r\n```\r\n\r\n### From Local Wheel\r\n```bash\r\n# Build and install from source\r\ngit clone https://github.com/jobenas/stm32bridge.git\r\ncd stm32bridge\r\npip install build\r\npython -m build\r\npip install dist/stm32bridge-1.0.0-py3-none-any.whl\r\n```\r\n\r\n### Prerequisites\r\n- Python 3.8 or higher\r\n- PlatformIO Core (automatically checked and installed if needed)\r\n- Git (for some FreeRTOS library dependencies)\r\n\r\n## \ud83d\ude80 Features\r\n\r\n- **Complete Project Migration**: Analyzes STM32CubeMX projects and creates fully configured PlatformIO projects\r\n- **FreeRTOS Support**: Automatic FreeRTOS library integration with CMSIS-OS v2 compatibility\r\n- **Build Verification**: Integrated build testing with automatic dependency resolution\r\n- **Editor Integration**: Open migrated projects directly in your favorite code editor\r\n- **Board Detection**: Automatic MCU and board detection with extensive board mapping\r\n- **Flexible Configuration**: Support for custom boards, FreeRTOS configurations, and build options\r\n\r\n## \ud83d\udcc1 Project Structure\r\n\r\n```\r\nstm32bridge/\r\n\u251c\u2500\u2500 main.py # CLI entry point\r\n\u251c\u2500\u2500 stm32bridge/\r\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\r\n\u2502 \u251c\u2500\u2500 constants.py # MCU families and board mappings\r\n\u2502 \u251c\u2500\u2500 exceptions.py # Custom exceptions\r\n\u2502 \u251c\u2500\u2500 core/ # Core migration logic\r\n\u2502 \u2502 \u251c\u2500\u2500 analyzer.py # STM32CubeMX project analysis\r\n\u2502 \u2502 \u251c\u2500\u2500 generator.py # PlatformIO project generation\r\n\u2502 \u2502 \u2514\u2500\u2500 migrator.py # File migration and adaptation\r\n\u2502 \u251c\u2500\u2500 utils/ # Utility modules\r\n\u2502 \u2502 \u251c\u2500\u2500 build.py # Build verification and dependency management\r\n\u2502 \u2502 \u251c\u2500\u2500 editor.py # Code editor integration\r\n\u2502 \u2502 \u251c\u2500\u2500 platformio.py # PlatformIO command execution\r\n\u2502 \u2502 \u2514\u2500\u2500 boards.py # Board detection utilities\r\n\u2502 \u2514\u2500\u2500 cli/ # CLI command implementations\r\n\u2502 \u251c\u2500\u2500 migrate.py # Migration command\r\n\u2502 \u251c\u2500\u2500 analyze.py # Analysis command\r\n\u2502 \u2514\u2500\u2500 list_boards.py # Board listing command\r\n\u2514\u2500\u2500 stm32bridge.py # Legacy monolithic version (for reference)\r\n```\r\n\r\n## \ud83d\udee0\ufe0f Installation\r\n\r\n### Prerequisites\r\n\r\n- Python 3.8+\r\n- PlatformIO Core (installed via pip or standalone)\r\n\r\n### Install STM32Bridge\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone <repository-url>\r\ncd stm32bridge\r\n\r\n# Install in development mode\r\npip install -e .\r\n\r\n# For development with all dependencies\r\npip install -r requirements-dev.txt\r\n\r\n# Or install specific dependency groups \r\npip install -e .[test] # Testing dependencies\r\npip install -e .[dev] # Development tools\r\npip install -e .[pdf] # PDF processing (optional)\r\n```\r\n\r\n## \ud83d\udcd6 Usage\r\n\r\n### Basic Migration\r\n\r\n```bash\r\n# Migrate a project with automatic board detection\r\nstm32bridge migrate my_stm32_project my_platformio_project\r\n\r\n# Specify a specific board\r\nstm32bridge migrate my_stm32_project my_platformio_project --board nucleo_l432kc\r\n\r\n# Windows example\r\nstm32bridge migrate C:\\Projects\\MySTM32Project C:\\Projects\\MyPlatformIOProject --board nucleo_f401re\r\n\r\n# Linux/Mac example \r\nstm32bridge migrate ~/projects/my_stm32_project ~/projects/my_platformio_project --board disco_f407vg\r\n```\r\n\r\n### Advanced Options\r\n\r\n```bash\r\n# Migrate with build verification\r\nstm32bridge migrate my_stm32_project my_platformio_project --board nucleo_l432kc --build\r\n\r\n# Migrate and open in VS Code\r\nstm32bridge migrate my_stm32_project my_platformio_project --board nucleo_l432kc --open\r\n\r\n# Use different editor\r\nstm32bridge migrate my_stm32_project my_platformio_project --board nucleo_l432kc --open --editor code\r\n\r\n# Force overwrite existing directory\r\nstm32bridge migrate my_stm32_project my_platformio_project --force\r\n```\r\n\r\n### FreeRTOS Options\r\n\r\n```bash\r\n# Use framework FreeRTOS instead of external library\r\nstm32bridge migrate my_stm32_project my_platformio_project --no-freertos\r\n\r\n# Completely disable FreeRTOS migration\r\nstm32bridge migrate my_stm32_project my_platformio_project --disable-freertos\r\n\r\n# Use PlatformIO framework's built-in FreeRTOS\r\nstm32bridge migrate my_stm32_project my_platformio_project --framework-freertos\r\n```\r\n\r\n### Analysis and Information\r\n\r\n```bash\r\n# Analyze project without migration\r\nstm32bridge analyze my_stm32_project\r\n\r\n# List supported boards\r\nstm32bridge list-boards\r\n\r\n# Get help\r\nstm32bridge --help\r\nstm32bridge migrate --help\r\n```\r\n\r\n## \ud83d\udd27 Supported Features\r\n\r\n### MCU Families\r\n- STM32F0, F1, F2, F3, F4, F7\r\n- STM32G0, G4\r\n- STM32H7\r\n- STM32L0, L1, L4, L5\r\n- STM32U5\r\n- STM32WB\r\n\r\n### FreeRTOS Integration\r\n- Automatic FreeRTOS library detection and integration\r\n- CMSIS-OS v2 compatibility layer\r\n- Custom FreeRTOS configuration preservation\r\n- Support for timers, event groups, and other FreeRTOS features\r\n\r\n### Build System\r\n- Complete PlatformIO configuration generation\r\n- Automatic dependency resolution\r\n- Build verification with memory usage reporting\r\n- Support for custom build flags and configurations\r\n\r\n### Development Tools\r\n- VS Code, VSCodium, Sublime Text, Atom, Vim support\r\n- STLink upload and debug configuration\r\n- Serial monitor setup\r\n- Custom board definitions\r\n\r\n## \ud83c\udfaf Example Workflow\r\n\r\n1. **Generate STM32CubeMX Project**: Create your project with Makefile toolchain\r\n2. **Analyze**: `python main.py analyze /path/to/project` to verify compatibility\r\n3. **Migrate**: `python main.py migrate /path/to/project /path/to/output --board nucleo_l432kc --build --open`\r\n4. **Develop**: Your PlatformIO project is ready with full build and debug support!\r\n\r\n## \ud83d\udc1b Troubleshooting\r\n\r\n### Common Issues\r\n\r\n- **Build Failures**: Use `--build` flag to get detailed error analysis and automatic fixes\r\n- **Missing Dependencies**: Tool automatically installs required Python packages (GitPython, etc.)\r\n- **FreeRTOS Issues**: Try `--no-freertos` or `--framework-freertos` flags\r\n- **Board Detection**: Use `python main.py list-boards` to find the correct board name\r\n\r\n### Debug Options\r\n\r\n- Use `python main.py analyze` to validate project structure\r\n- Check PlatformIO installation: `pio --version`\r\n- Verify board support: `pio boards | grep <your-mcu>`\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nThe codebase is now well-organized and modular:\r\n\r\n- **Core Logic**: Add new features in `stm32bridge/core/`\r\n- **Utilities**: Add helper functions in `stm32bridge/utils/`\r\n- **CLI Commands**: Add new commands in `stm32bridge/cli/`\r\n- **Configuration**: Update constants in `stm32bridge/constants.py`\r\n\r\n## \ud83d\udcc4 License\r\n\r\nMIT License - see LICENSE file for details.\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- PlatformIO team for the excellent embedded development platform\r\n- STMicroelectronics for STM32CubeMX\r\n- FreeRTOS community for real-time OS support\r\n",
"bugtrack_url": null,
"license": null,
"summary": "STM32CubeMX to PlatformIO Migration Tool",
"version": "1.3.3",
"project_urls": {
"Bug Reports": "https://github.com/yourusername/stm32bridge/issues",
"Documentation": "https://github.com/yourusername/stm32bridge/blob/main/README.md",
"Homepage": "https://github.com/yourusername/stm32bridge",
"Source Code": "https://github.com/yourusername/stm32bridge"
},
"split_keywords": [
"stm32",
" cubemx",
" platformio",
" embedded",
" migration",
" freertos",
" arm",
" cortex",
" microcontroller",
" iot"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a8b6f3a2b76e51a375750a89b7bb510a828b1c498b635a926316ca90ec68b19f",
"md5": "26723e60788c21203438d2b3ae29cb28",
"sha256": "98c23b5c87cdcc0f21f9b5e605e826c604aa431177a0194e9d11a05499b6b85f"
},
"downloads": -1,
"filename": "stm32bridge-1.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "26723e60788c21203438d2b3ae29cb28",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 45661,
"upload_time": "2025-10-15T03:23:28",
"upload_time_iso_8601": "2025-10-15T03:23:28.383041Z",
"url": "https://files.pythonhosted.org/packages/a8/b6/f3a2b76e51a375750a89b7bb510a828b1c498b635a926316ca90ec68b19f/stm32bridge-1.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dff979c7fc9b153b3c20d4fabf3bcc096a700b82f61fca17f612f8f1ac8b5203",
"md5": "24d0738fc17c1247b862e749d09b10d1",
"sha256": "e02b357a87656e530af4bcb95425addb3f2a2307e0a38d5ae2071b9bc81e72c4"
},
"downloads": -1,
"filename": "stm32bridge-1.3.3.tar.gz",
"has_sig": false,
"md5_digest": "24d0738fc17c1247b862e749d09b10d1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 42574,
"upload_time": "2025-10-15T03:23:30",
"upload_time_iso_8601": "2025-10-15T03:23:30.412255Z",
"url": "https://files.pythonhosted.org/packages/df/f9/79c7fc9b153b3c20d4fabf3bcc096a700b82f61fca17f612f8f1ac8b5203/stm32bridge-1.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-15 03:23:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "stm32bridge",
"github_not_found": true,
"lcname": "stm32bridge"
}
JSON
