# newbluepill

**Repository Path**: gerryqd/newbluepill

## Basic Information

- **Project Name**: newbluepill
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-11
- **Last Updated**: 2025-11-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# STM32F103 Dual Application Project (Bootloader + Application)

This project implements a dual-application architecture for STM32F103C8T6 microcontroller with a bootloader and main application.

## Project Architecture

### Memory Layout

| Address Range | Size | Description |
|---------------|------|-------------|
| 0x08000000    | 16KB | Bootloader |
| 0x08007000    | 40KB | Application |
| 0x20000000    | 20KB | RAM (shared) |

### Directory Structure

```
newbluepill/
├── CMakeLists.txt                 # Root CMake configuration
├── cmake/                         # CMake modules
│   ├── build-info.cmake          # Git build information
│   └── stm32f103-options.cmake   # STM32F103 specific options
├── libs/                          # Shared libraries
│   └── stm32cubefwf1/            # STM32Cube HAL library
├── src/                          # Source code
│   ├── common/                   # Shared code
│   │   ├── hal/                  # Hardware abstraction layer
│   │   │   ├── uart1.c/.h        # UART1 driver
│   │   │   └── led.c/.h          # LED control
│   │   ├── utils/                # Utility functions
│   │   │   └── printf.c/.h       # Simple printf implementation
│   │   ├── build_info/           # Build information
│   │   │   └── build_info.c/.h   # Git and build info
│   │   └── stm32f1xx_hal_conf.h  # HAL configuration
│   ├── bootloader/               # Bootloader source
│   │   ├── main.c                # Bootloader entry point
│   │   ├── bootloader.c/.h       # Core bootloader logic
│   │   └── CMakeLists.txt        # Bootloader build config
│   ├── application/              # Application source
│   │   ├── main.c                # Application entry point
│   │   ├── cli/                  # Command line interface
│   │   │   ├── cli.c/.h          # CLI core
│   │   │   ├── cli_cmds.c/.h     # CLI commands
│   │   │   └── cli_adapter.c/.h  # CLI adapter
│   │   ├── app_cli.c/.h          # Application-specific commands
│   │   └── CMakeLists.txt        # Application build config
│   └── ld/                       # Linker scripts
│       ├── bootloader_flash.ld   # Bootloader memory layout
│       └── application_flash.ld  # Application memory layout
└── README.md                     # This file
```

## Build System

### Prerequisites

- CMake 3.10 or higher
- ARM GCC toolchain (arm-none-eabi-gcc)
- pyocd (for flashing)

### Build Commands

#### Method 1: Standard CMake (Recommended)

```bash
# Configure project
rm -rf build
cmake -B build -DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi.cmake

# Build bootloader only
cmake --build build --target bootloader

# Build application only
cmake --build build --target application

# Build both
cmake --build build --target build-all

# Flash to device
cmake --build build --target flash-bootloader    # Flash bootloader only
cmake --build build --target flash-app          # Flash application only
cmake --build build --target flash-both         # Flash both (bootloader first, then app)

# Show build help
cmake --build build --target help-build

# Clean build
cmake --build build --target clean
```

#### Method 2: Using Build Script (Easiest)

```bash
# Build both bootloader and application
./build.sh

# Build bootloader only
./build.sh bootloader

# Build application only
./build.sh application

# Clean build directory
./build.sh clean

# Show help
./build.sh help
```

#### Method 3: Using Make (If Available)

```bash
# Configure and build
rm -rf build && mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-none-eabi.cmake ..
make bootloader
make application
make build-all
```

## Bootloader Features

- **Application Validation**: Verifies application integrity before jumping
- **Timeout Jump**: Automatically jumps to application after 3 seconds
- **Interactive Mode**: Enter bootloader mode by pressing any key during timeout
- **Firmware Update**: Basic command interface for firmware updates
- **Error Handling**: Comprehensive error detection and reporting

### Bootloader Commands

- `status` - Show bootloader status and application validity
- `erase` - Erase application flash area
- `jump` - Jump to application (if valid)
- `reset` - Reset the system

## Application Features

- **Command Line Interface**: Interactive CLI with command history
- **LED Control**: Onboard LED management
- **System Information**: Build time, clock speed, memory info
- **Application Commands**:
  - `info` - Show application information
  - `status` - Show runtime status
  - `led <on|off|toggle>` - Control LED
  - `memory` - Show memory layout
  - `test` - Test application features
  - `help` - Show available commands

## Memory Layout Details

### Bootloader (16KB)
- Flash: `0x08000000 - 0x8003FFF`
- Entry point: Reset_Handler at `0x08000000`
- Vector table at flash start

### Application (48KB)
- Flash: `0x08007000 - 0x0800FFFF`
- Entry point: Reset_Handler at `0x08007000`
- Vector table relocated to application start

### Vector Table Relocation

The application sets SCB->VTOR to `0x08007000` to redirect interrupts to its own vector table.

## Development Workflow

1. **Bootloader Development**:
   - Modify files in `src/bootloader/`
   - Build with `make bootloader`
   - Flash with `make flash-bootloader`

2. **Application Development**:
   - Modify files in `src/application/`
   - Build with `make application`
   - Flash with `make flash-app` (bootloader must be present)

3. **Full Build**:
   - `make build-all` to build both
   - `make flash-both` to flash both

## Troubleshooting

### Common Issues

1. **Application won't start**: Check if application is properly flashed and vector table is valid
2. **Bootloader loop**: Application validation failed - check application integrity
3. **Build errors**: Ensure all dependencies are installed and paths are correct

### Debugging

- Connect UART1 (PA9/PA10) at 115200 baud for console output
- Use LED status codes for visual debugging
- Check map files for memory layout verification

## Flash Layout Verification

```bash
# View bootloader map
objdump -h build/bootloader/bootloader.elf

# View application map
objdump -h build/application/application.elf

# Check flash usage
size build/bootloader/bootloader.elf
size build/application/application.elf
```

## Hardware Connection

- UART1: PA9 (TX), PA10 (RX) - 115200 8N1
- LED: PC13 (Blue Pill onboard LED)
- SWD: SWCLK, SWDIO for programming/debugging

## Future Enhancements

- USB CDC firmware update
- YModem protocol for file transfer
- Boot password protection
- Application rollback functionality
- OTA update support