fix README.md
This commit is contained in:
181
README.md
Normal file
181
README.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# STM8 Bootloader Template Project
|
||||
|
||||
## Overview
|
||||
|
||||
This project provides a flexible bootloader implementation for STM8 microcontrollers using the SDCC compiler. The bootloader resides in the option bytes reserved area and enables in-application programming (IAP) capabilities via UART communication.
|
||||
|
||||
Note: The bootloader implementation is based on and inspired by the [STM8uLoader](https://github.com/ovsp/STM8uLoader) project, with significant modifications and enhancements for integration into this template structure.
|
||||
|
||||
## Features
|
||||
|
||||
- **Three-stage Bootloader**:
|
||||
- Boot0: TRAP isr for load boot1
|
||||
- Boot1: Minimal bootloader stored in *reserved* option bytes
|
||||
- Boot2: Full-featured bootloader loaded via serial communication
|
||||
|
||||
- **Flexible Configuration**:
|
||||
- Enable/disable bootloader via `ENABLE_OPTION_BOOTLOADER` Makefile macro
|
||||
|
||||
- **Complete Toolchain**:
|
||||
- PC-side programming utility for firmware updates
|
||||
- Support for read, write, go and exec operations
|
||||
|
||||
- **Safe Operation**:
|
||||
- Bootloader integrity protected in option bytes
|
||||
- Fallback to application on timeout or communication failure
|
||||
|
||||
## Bootloader Reference
|
||||
|
||||
This project's bootloader implementation is derived from the excellent STM8uLoader project by ovsp. Key adaptations include:
|
||||
|
||||
- Integration into a modular template project structure
|
||||
- Three-stage bootloader approach (Boot1 in option bytes, Boot2 loaded dynamically)
|
||||
- Enhanced Makefile system with configuration macros
|
||||
- Extended command set and error handling
|
||||
|
||||
## Bootloader Operation Flow
|
||||
|
||||
1. **Power-on/Reset**:
|
||||
- MCU starts execution at reset vector(0x8000)
|
||||
- Control transfers to `bootloader_enter()` in `bsp/init0.c`
|
||||
|
||||
2. **Stage 1 (Boot1)**:
|
||||
- Copies Boot1 from option bytes (0x480E-0x483F) to RAM and Run
|
||||
- Sends synchronization sequence `0x00 0x0D` via UART
|
||||
- Waits for PC to send Boot2 code
|
||||
|
||||
3. **Stage 2 (Boot2)**:
|
||||
- Receives and validates Boot2 code from PC
|
||||
- Executes Boot2 which provides full command interface
|
||||
- Processes PC commands for programming, reading, and device control
|
||||
|
||||
4. **Application Start**:
|
||||
- On successful programming or timeout, jumps to main application(0x8004)
|
||||
- Option to stay in bootloader mode for debugging
|
||||
|
||||
## Building the Project
|
||||
|
||||
### Prerequisites
|
||||
- SDCC (Small Device C Compiler) installed
|
||||
- stm8flash or similar programming tool
|
||||
- Python 3.x (for PC tools)
|
||||
|
||||
### Compilation Options
|
||||
|
||||
Enable bootloader support:
|
||||
```bash
|
||||
make ENABLE_OPTION_BOOTLOADER=1
|
||||
```
|
||||
|
||||
Disable bootloader (direct application execution):
|
||||
```bash
|
||||
make ENABLE_OPTION_BOOTLOADER=0
|
||||
```
|
||||
|
||||
### Build Targets
|
||||
```bash
|
||||
# Build both application and bootloader option
|
||||
make all
|
||||
|
||||
# Program device (requires stm8flash)
|
||||
make flash
|
||||
```
|
||||
|
||||
## Bootloader Integration
|
||||
|
||||
1. The main application includes `bootloader.h`, which redirects the TRAP interrupt vector to `bootloader_enter()` in `bsp/boot0.c`.
|
||||
|
||||
2. During the build process, the Makefile swaps the reset vector (0x8000) and trap vector (0x8004) positions. This ensures that upon startup, the bootloader entry routine executes first.
|
||||
|
||||
3. It sends a handshake signal (`0x00 0x0D`) via UART1 and waits approximately 200ms for a response.
|
||||
|
||||
4. If no response is received within the timeout period, execution proceeds to the main application (reset vector).
|
||||
|
||||
## Option Bytes Configuration
|
||||
|
||||
The bootloader uses the reserved option byte area for storage:
|
||||
|
||||
| Address Range | Content | Size |
|
||||
|---------------|--------------------------|-------|
|
||||
| 0x4800-0x480A | Device option bytes | 11 bytes |
|
||||
| 0x480D-0x483F | Boot1 code | 51 bytes |
|
||||
|
||||
**Important**: These addresses are specific to STM8S103/003. Adjust for other STM8 variants.
|
||||
|
||||
## PC Communication Protocol
|
||||
|
||||
### Connection Parameters
|
||||
- **Baud Rate**: 128000 bps
|
||||
- **Data Bits**: 8
|
||||
- **Parity**: None
|
||||
- **Stop Bits**: 1
|
||||
|
||||
### Command Set
|
||||
| Command | Opcode | Description |
|
||||
|-----------|--------|--------------------------------------|
|
||||
| CMD_READ | 0xF1 | Read memory from device |
|
||||
| CMD_WRITE | 0xF2 | Write memory to device |
|
||||
| CMD_GO | 0xF3 | Jump address for execution |
|
||||
| CMD_EXEC | 0xF4 | Execute Machine-Code |
|
||||
|
||||
### Communication Sequence
|
||||
1. Boot1 sends sync bytes: `0x00 0x0D`
|
||||
2. PC responds with Boot2 reversed bytes
|
||||
3. Boot1 receves Boot2 and checksum
|
||||
4. Boot2 executes and prepare to receive cmd
|
||||
5. PC sends commands with appropriate parameters
|
||||
|
||||
## Usage Example
|
||||
|
||||
### Programming New Firmware
|
||||
```bash
|
||||
# 1. Build the application
|
||||
make flash
|
||||
|
||||
# 2. Enter interactive mode
|
||||
python scripts/stm8loader.py /dev/ttyUSB0
|
||||
|
||||
# 3. Use command line:
|
||||
python scripts/stm8loader.py /dev/ttyUSB0 --write 0x8000 firmware.bin
|
||||
```
|
||||
|
||||
## Supported Devices
|
||||
|
||||
Currently tested with:
|
||||
- STM8S103/003 (default configuration)
|
||||
|
||||
**Important**: To port to other STM8 variants need verify peripheral register definitions
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **No response from device**:
|
||||
- Verify baud rate settings
|
||||
- Check UART pin connections (TX/RX swapped?)
|
||||
- Ensure option bytes are correctly programmed
|
||||
|
||||
2. **Bootloader not starting**:
|
||||
- Verify `ENABLE_OPTION_BOOTLOADER` is set during compilation
|
||||
- Check main.c include `bootloader.h`
|
||||
- Check `bsp/boot0.c`
|
||||
- Confirm option bytes
|
||||
|
||||
## Safety Considerations
|
||||
|
||||
1. **Power Stability**: Ensure stable power supply during programming
|
||||
2. **Watchdog Timer**: Disable or properly handle watchdog in bootloader
|
||||
3. **Interrupts**: Save/restore interrupt context during bootloader operations
|
||||
4. **Memory Protection**: Never overwrite bootloader area in option bytes
|
||||
|
||||
## References
|
||||
|
||||
- [STM8uLoader](https://github.com/ovsp/STM8uLoader)
|
||||
- [STM8S Reference Manual](https://www.st.com/resource/en/reference_manual/cd00190271-stm8s-series-and-stm8af-series-8bit-microcontrollers-stmicroelectronics.pdf)
|
||||
- [SDCC User Guide](http://sdcc.sourceforge.net/doc/sdccman.pdf)
|
||||
- [STM8 Bootloader AN2659](https://www.st.com/resource/en/application_note/cd00173937-stm8-swim-communication-protocol-and-debug-module-stmicroelectronics.pdf)
|
||||
- [STM8 CPU programming manual](https://www.st.com/resource/en/programming_manual/cd00161709-stm8-cpu-programming-manual-stmicroelectronics.pdf)
|
||||
|
||||
---
|
||||
|
||||
**Note**: This implementation is for educational and development purposes. Always verify bootloader behavior in your specific application context before deployment.
|
||||
Reference in New Issue
Block a user