Skip to content

README.md

Latest commit

 

History

History
182 lines (129 loc) · 5.42 KB

README.md

File metadata and controls

182 lines (129 loc) · 5.42 KB
Raw

STM32F407 Bootloader Host (Python 3)

Python 3 command‑line utility to talk to the STM32 bootloader running on your board. It supports version/help/cid/rdp, flash erase/write, memory read, sector protection, jump to address, and a test for unsupported commands.

This README covers setup and usage on Windows (PowerShell).

Prerequisites

  • Python 3.8+ on PATH (python --version)
  • PySerial

Install PySerial:

python -m pip install --upgrade pip
python -m pip install pyserial

Script location

  • Host script: bootloader_stm32f407xx_host.py
  • Folder: host/

Run it from that folder or give the full path.

Quick start

  1. List available serial ports:
python .\bootloader_stm32f407xx_host.py ports
  1. Get bootloader version (replace COM3 with your port):
python .\bootloader_stm32f407xx_host.py --port COM3 get-ver
  1. Show supported commands reported by the device:
python .\bootloader_stm32f407xx_host.py --port COM3 get-help

Common commands

  • Chip ID:
python .\bootloader_stm32f407xx_host.py --port COM3 get-cid
  • RDP status:
python .\bootloader_stm32f407xx_host.py --port COM3 get-rdp
  • Mass erase (user sectors, bootloader sectors are protected by target code):
python .\bootloader_stm32f407xx_host.py --port COM3 erase --mass
  • Sector erase (e.g., sector 3, count 2):
python .\bootloader_stm32f407xx_host.py --port COM3 erase --sector 3 --count 2
  • Write a binary to Flash (128‑byte chunks by default):
# Flags (recommended)
python .\bootloader_stm32f407xx_host.py --port COM3 write --addr 0x0800C000 --file .\user_app.bin --chunk 128
# Or positional
python .\bootloader_stm32f407xx_host.py --port COM3 write 0x0800C000 .\user_app.bin --chunk 128
  • Read memory (e.g., 64 bytes from 0x0800C000):
# Flags
python .\bootloader_stm32f407xx_host.py --port COM3 mem-read --addr 0x0800C000 --length 64
# Or positional
python .\bootloader_stm32f407xx_host.py --port COM3 mem-read 0x0800C000 64

  • Enable/disable write protection using a 12-bit mask (bit N = sector N).

    Semantics: In STM32 HAL WRPSector, bit=1 means NOT protected, bit=0 means PROTECTED. The host’s --mask follows the same convention.

    Examples:

    • All sectors NOT protected (sectors 0..11):

      python .\bootloader_stm32f407xx_host.py --port COM3 prot-enable --mask 0x0FFF --mode 1

    • Normal bootloader state (protect bootloader sectors 0 and 1, others not):

      python .\bootloader_stm32f407xx_host.py --port COM3 prot-enable --mask 0x0FFC --mode 1

    • Protect only sectors 2 and 3 (mask clears bits 2 and 3):

      python .\bootloader_stm32f407xx_host.py --port COM3 prot-enable --mask 0x0FF3 --mode 1

    • Protect only sectors 3, 5, 7:

      # 0x0FFF - (0x008 + 0x020 + 0x080) = 0x0F57
python .\bootloader_stm32f407xx_host.py --port COM3 prot-enable --mask 0x0F57 --mode 1

  • Read sector protection status:

python .\bootloader_stm32f407xx_host.py --port COM3 prot-status
  • Jump to address (Thumb mode handled by target):
# Positional
python .\bootloader_stm32f407xx_host.py --port COM3 go 0x08008000
# Or with flags
python .\bootloader_stm32f407xx_host.py --port COM3 go --address 0x08008000
  • Send an intentionally unsupported command (expect NACK):
python .\bootloader_stm32f407xx_host.py --port COM3 send-unsupported
  • Reduce logs:
python .\bootloader_stm32f407xx_host.py --port COM3 --quiet get-ver

Notes

  • CRC is CRC‑32/MPEG‑2 (poly 0x04C11DB7) to match STM32 HAL CRC default; CRC bytes are sent little‑endian as in the original script.
  • Write chunk size can be adjusted with --chunk (1..255). The target typically supports up to 128 bytes.
  • Option Bytes (write protection) changes require a reset to take effect. The firmware triggers an automatic reset using HAL_FLASH_OB_Launch() after applying protection. If your terminal shows a timeout on the protection command, it can be due to the immediate reset—just reconnect and check prot-status.
  • MEM_READ returns exactly the requested number of bytes when ACKed.

For detailed packet formats and examples, see PROTOCOL.md in this folder.

Troubleshooting

  • Timeout / no response:

    • Confirm the board is in bootloader mode (user button state as per your firmware) and the correct COM port is used.
    • Try power cycling or resetting the board.
    • Close other tools (serial monitors, IDE) that may lock the port.

  • NACK received:

    • Indicates CRC mismatch or unsupported command/parameters.
    • Check address ranges and payload sizes.

  • Erase/Write fails:

    • Ensure you’re not writing to protected bootloader sectors (0–1) — target code blocks it.
    • Verify sector ranges are valid for your device.

Mapping to device commands

  • get-ver → BL_GET_VER (0x51)
  • get-help → BL_GET_HELP (0x52)
  • get-cid → BL_GET_CID (0x53)
  • get-rdp → BL_GET_RDP_STATUS (0x54)
  • go → BL_GO_TO_ADDR (0x55)
  • erase → BL_FLASH_ERASE (0x56)
  • write → BL_MEM_WRITE (0x57)
  • prot-enable → BL_EN_R_W_PROTECT (0x58)
  • mem-read → BL_MEM_READ (0x59)
  • prot-status → BL_READ_SECTOR_P_STATUS (0x5A)
  • otp-read → BL_OTP_READ (0x5B) (likely unsupported)
  • prot-disable → BL_DIS_R_W_PROTECT (0x5C) (may be unsupported)
  • send-unsupported → 0x5D (intentionally unsupported)