wagiminator / mcu-flash-tools

Simple ISP Flash Tools for various Microcontrollers

MCU ISP Flash Tools

This is a compilation of straightforward In-System Programming (ISP) flash tools for different microcontrollers, all written as individual Python scripts. Their single-script format makes them incredibly easy to integrate into any toolchain.

• chprog.py - Flashing CH5xx, CH32Fxxx, CH32Vxxx, CH32Xxxx via embedded USB bootloader
• rvprog.py - Flashing CH32Vxxx with WCH-LinkE via serial debug interface
• puyaisp.py - Flashing PY32F0xx with USB-to-serial converter via embedded UART bootloader
• stc8isp.py - Flashing STC8G/8H with USB-to-serial converter via embedded UART bootloader
• stc8usb.py - Flashing STC8H8KxxU via embedded USB bootloader
• stm32isp.py - Flashing entry-level STM32 with USB-to-serial converter via embedded UART bootloader
• tinyupdi.py - Flashing tinyAVR with USB-to-serial converter via UPDI

In order for these tools to work, Python3 must be installed on your system. To do this, follow these instructions. In addition PyUSB, PySerial and pyhidapi must be installed. On Linux (Debian-based), all of this can be done with the following commands:

sudo apt install python3 python3-pip
python3 -m pip install pyusb pyserial hid

Windows users in particular may also need to install libusb.

chprog

Description

With this tool, almost all WCH microcontrollers (CH5xx, CH32Fxxx, CH32Vxxx, CH32Xxxx, and CH32Lxxx) which have a factory-builtin bootloader (v2.x.x) can be flashed via USB.

Preparations

On Linux you do not need to install a driver for the USB bootloader. However, by default Linux will not expose enough permission to upload your code. In order to fix this, open a terminal and run the following commands:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="4348", ATTR{idProduct}=="55e0", MODE="666"' | sudo tee /etc/udev/rules.d/99-ch55x.rules
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="1a86", ATTR{idProduct}=="55e0", MODE="666"' | sudo tee -a /etc/udev/rules.d/99-ch55x.rules
sudo udevadm control --reload-rules

For Windows, you need the CH372 driver. Alternatively, you can also use the Zadig Tool to install the correct driver. Here, click "Options" -> "List All Devices" and select the USB module. Then install the libusb-win32 driver. To do this, the board must be connected and the microcontroller must be in bootloader mode.

Usage

The bootloader must be started manually for new uploads. To do this, the board must first be disconnected from the USB port and all voltage sources. Now press the BOOT button and keep it pressed while reconnecting the board to the USB port of your PC. The chip now starts in bootloader mode, the BOOT button can be released and new firmware can be uploaded via USB. Alternatively, you can leave the board connected to the USB port, press and hold the BOOT button, press and release the RESET button and then release the BOOT button to enter the bootloader mode. If there is no BOOT button on the board, look at the datasheet to find out which pin needs to be pulled to which voltage level for the microcontroller to go into boot mode.

Now run the following command (example):

python3 chprog.py firmware.bin

rvprog

Description

With this tool, the WCH RISC-V microcontrollers CH32Vxxx and CH32Xxxx can be programmed with the WCH-LinkE (pay attention to the "E" in the name) via its serial debug interface.

Preparations

To use the WCH-Link on Linux, you need to grant access permissions beforehand by executing the following commands:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="1a86", ATTR{idProduct}=="8010", MODE="666"' | sudo tee /etc/udev/rules.d/99-WCH-LinkE.rules
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="1a86", ATTR{idProduct}=="8012", MODE="666"' | sudo tee -a /etc/udev/rules.d/99-WCH-LinkE.rules
sudo udevadm control --reload-rules

On Windows, if you need to you can install the WinUSB driver over the WCH interface 1.

Usage

To upload firmware, you should make the following connections to the WCH-LinkE (SWCLK is not present on the CH32V003 and therefore does not need to be connected):

WCH-LinkE       CH32V/X
+-------+      +-------+
|  SWCLK| ---> |SWCLK  |
|  SWDIO| <--> |SWDIO  |
|    GND| ---> |GND    |
|    3V3| ---> |VDD    |
+-------+      +-------+

If the blue LED on the WCH-LinkE remains illuminated once it is connected to the USB port, it means that the device is currently in ARM mode and must be switched to RISC-V mode initially. There are a few ways to accomplish this:

• You can utilize the rvprog tool with the -v option (see below).
• Alternatively, you can select "WCH-LinkRV" in the software provided by WCH, such as MounRiver Studio or WCH-LinkUtility.
• Another option is to hold down the ModeS button on the device while plugging it into the USB port.

More information can be found in the WCH-Link User Manual.

Usage: rvprog.py [-h] [-a] [-v] [-b] [-u] [-l] [-e] [-G] [-R] [-f FLASH]

Optional arguments:
  -h, --help                show help message and exit
  -a, --armmode             switch WCH-Link to ARM mode
  -v, --rvmode              switch WCH-Link to RISC-V mode
  -b, --unbrick             unbrick chip (CH32V003 only)
  -u, --unlock              unlock chip (remove read protection)
  -l, --lock                lock chip (set read protection)
  -e, --erase               perform a whole chip erase
  -G, --pingpio             make nRST pin a GPIO pin (CH32V003 only)
  -R, --pinreset            make nRST pin a reset pin (CH32V003 only)
  -f FLASH, --flash FLASH   write BIN file to flash

Example:
python3 rvprog.py -f firmware.bin

puyaisp

Description

With this tool, PUYA microcontrollers of the series PY32F0xx (and maybe other PY32) can be flashed via a simple USB-to-serial converter by utilizing the factory built-in embedded bootloader.

Preparations

If necessary, a driver for the USB-to-serial converter used must be installed.

Usage

Connect your USB-to-serial converter to your PY32F0xx MCU as follows:

USB2SERIAL            PY32F0xx
+--------+      +-------------------+
|     RXD| <--- |PA2 or PA9  or PA14|
|     TXD| ---> |PA3 or PA10 or PA15|
|     VDD| ---> |VDD                |
|     GND| ---> |GND                |
+--------+      +-------------------+

Set your MCU to bootloader mode by using ONE of the following methods:

• Disconnect your USB-to-serial converter, pull BOOT0 pin (PF4) to VCC (or press and hold the BOOT button, if your board has one), then connect the converter to your USB port. BOOT0 pin (or BOOT button) can be released now.
• Connect your USB-to-serial converter to your USB port. Pull BOOT0 pin (PF4) to VCC, then pull nRST (PF2) shortly to GND (or press and hold the BOOT button, then press and release the RESET button and then release the BOOT button, if your board has them).

Usage: puyaisp.py [-h] [-u] [-l] [-e] [-o] [-G] [-R] [-f FLASH]

Optional arguments:
  -h, --help                show this help message and exit
  -u, --unlock              unlock chip (remove read protection)
  -l, --lock                lock chip (set read protection)
  -e, --erase               perform chip erase (implied with -f)
  -o, --rstoption           reset option bytes
  -G, --nrstgpio            make nRST pin a GPIO pin
  -R, --nrstreset           make nRST pin a RESET pin
  -f FLASH, --flash FLASH   write BIN file to flash and verify

Example:
python3 puyaisp.py -f firmware.bin

stc8isp

Description

With this tool, STC8G/8H microcontrollers can be flashed via a simple USB-to-serial converter by utilizing the factory built-in embedded bootloader.

Preparations

If necessary, a driver for the USB-to-serial converter used must be installed.

Usage

• Connect your USB-to-serial converter to your MCU as shown below.
• Run stc8isp.py (see below for arguments).
• Perform a power cycle of your MCU (reconnect to power) when prompted.

USB2SERIAL         STC8G/8H
+--------+         +------+
|     VCC| --/ --> |VCC   |    interruptible (for power cycle)
|     RXD| --|R|-- |P3.1  |    resistor (100R - 1000R)
|     TXD| --|<|-- |P3.0  |    diode (e.g. 1N5819)
|     GND| ------- |GND   |    common ground
+--------+         +------+

Usage: stc8isp.py [-h] [-p PORT] [-t TRIM] [-e] [-f FLASH]

Optional arguments:
  -h,       --help          show this help message and exit
  -p PORT,  --port PORT     set COM port (default: /dev/ttyUSB0)
  -t TRIM,  --trim TRIM     trim IRC to frequency in Hz (128000 - 36000000)
  -e,       --erase         perform chip erase (implied with -f)
  -f FLASH, --flash FLASH   write BIN file to flash

Example:
python3 stc8isp.py -p /dev/ttyUSB0 -t 24000000 -f firmware.bin

stc8usb

Description

This tool allows you to flash STC8H8KxxU microcontrollers through their USB interface, using the pre-installed embedded USB bootloader.

Preparations

Because the USB bootloader functions as a Human Interface Device (HID), there's no need to install drivers. However, Linux doesn't initially grant sufficient permissions to access the bootloader. To resolve this issue, open a terminal and execute the following commands:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="34bf", ATTR{idProduct}=="1001", MODE="666"' | sudo tee /etc/udev/rules.d/99-STC-ISP.rules
sudo udevadm control --reload-rules

Usage

To initiate new uploads, the bootloader needs to be manually started. Begin by unplugging the board from the USB port and disconnecting all power sources. Then, press and hold the BOOT button while reconnecting the board to your PC's USB port. This action triggers the chip to enter bootloader mode. Once in this mode, you can release the BOOT button and proceed to upload new firmware via USB.

If your board doesn't have a BOOT button, you'll need to short pin P3.2 to ground while connecting to achieve the same effect.

Usage: stc8usb.py [-h] [-t TRIM] [-e] [-f FLASH]

Optional arguments:
  -h,       --help          show this help message and exit
  -t TRIM,  --trim TRIM     set MCU system frequency
  -e,       --erase         perform chip erase (implied with -f)
  -f FLASH, --flash FLASH   write BIN file to flash

Example:
python3 stc8usb.py -t 24000000 -f firmware.bin

stm32isp

Description

With this tool, some entry-level STM32 microcontrollers can be flashed via a simple USB-to-serial converter by utilizing the factory built-in UART bootloader. It currently supports the following devices:

• STM32C011/031
• STM32F03xx4/6
• STM32G03x/04x
• STM32L01x/02x

Preparations

If necessary, a driver for the USB-to-serial converter used must be installed.

Usage

Connect your USB-to-serial converter to your STM32 MCU as follows:

USB2SERIAL      STM32C011/031
+--------+      +------------+
|     RXD| <--- |PA9  (PA11) |
|     TXD| ---> |PA10 (PA12) |
|     3V3| ---> |VDD (3V3)   |
|     GND| ---> |GND         |
+--------+      +------------+

USB2SERIAL      STM32F03xx4/6
+--------+      +------------+
|     RXD| <--- |PA9  or PA14|
|     TXD| ---> |PA10 or PA15|
|     3V3| ---> |VDD (3V3)   |
|     GND| ---> |GND         |
+--------+      +------------+

USB2SERIAL      STM32G03x/04x
+--------+      +------------+
|     RXD| <--- |PA2 or PA9  |
|     TXD| ---> |PA3 or PA10 |
|     3V3| ---> |VDD (3V3)   |
|     GND| ---> |GND         |
+--------+      +------------+

USB2SERIAL      STM32L01x/02x
+--------+      +------------+
|     RXD| <--- |PA2 or PA9  |
|     TXD| ---> |PA3 or PA10 |
|     3V3| ---> |VDD (3V3)   |
|     GND| ---> |GND         |
+--------+      +------------+

Set your MCU to boot mode by using ONE of the following method:

• Disconnect your board from all power supplies, pull BOOT0 pin to VCC (or press and hold the BOOT button if your board has one), then connect the board to your USB port. The BOOT button can be released now.
• Connect your USB-to-serial converter to your USB port. Pull BOOT0 pin to VCC, then pull nRST shortly to GND (or press and hold the BOOT button, then press and release the RESET button and then release the BOOT button, if your board has them).

On STM32G03x/04x microcontrollers, the BOOT0 pin is initially disabled. When the chip is brand new or the main flash memory is erased, this isn't an issue as the embedded bootloader automatically kicks in. By using the stm32isp tool, the BOOT0 pin will be activated for subsequent use. However, if the chip has been previously programmed using a different software tool, the bootloader might not be accessible through the BOOT0 pin anymore. In such cases, the nBOOT_SEL bit in the User Option Bytes must be cleared (set to 0) using an SWD programmer like ST-Link and the appropriate software.

Usage: stm32isp.py [-h] [-u] [-l] [-e] [-f FLASH]

Optional arguments:
  -h, --help                show this help message and exit
  -u, --unlock              unlock chip (remove read protection)
  -l, --lock                lock chip (set read protection)
  -e, --erase               perform chip erase (implied with -f)
  -f FLASH, --flash FLASH   write BIN file to flash and verify

Example:
python3 stm32isp.py -f firmware.bin

tinyupdi

Description

This tool allows tinyAVR series 0, 1, and 2 microcontrollers to be programmed using a USB-to-serial converter connected in a special way to the UPDI pin (also called SerialUPDI). More information can be found here.

Preparations

If necessary, a driver for the USB-to-serial converter used must be installed.

Usage

Connect the USB-to-serial converter via USB to the PC and via the circuit described below to the UPDI pin of the microcontroller.

USB2SERIAL                       tinyAVR
+--------+                    +-----------+
|     RXD| <------------+---> |UPDI (PA0) |
|        |              |     |           |
|     TXD| ---|1kOhm|---+     |           |
|        |                    |           |
|     VDD| -----------------> |VDD        |
|     GND| -----------------> |GND        |
+--------+                    +-----------+

Alternatively, a pre-assembled SerialUPDI programmer can be used.

Usage: tinyupdi.py [-h] [-d DEVICE] [-e] [-f FLASH] [-fs [FUSES [FUSES ...]]]

Optional arguments:
  -h, --help                show help message and exit
  -d, --device              set target device (if not set, it will be auto-detected)
  -e, --erase               perform a chip erase (implied with --flash)
  -f FLASH, --flash FLASH   BIN file to flash
  -fs [FUSES [FUSES ...]], --fuses [FUSES [FUSES ...]]
                            fuses to set (syntax: fuse_nr:0xvalue)
  -t TRIM, --trim TRIM      configure oscillator for given frequency (set fuse 2)
Example:
python3 tinyupdi.py -f firmware.bin -fs 6:0x04 7:0x00 8:0x00 -t 8000000

Links

1. MCU Templates
2. MCU Development Boards
3. AVR Development Boards
4. SerialUPDI Programmers

mcu-flash-tools's Issues

RTS DTR auto boot enter?

Hello again.
It is possible to implement this type of schema for the boot-loader in the code?

I'm designing a new board for the PY32F002A micro-controller, wondering about using the CH340X as a USB-Serial communication IC for the board. If this could be implemented, I think is a no brainer to choose that IC instead of the CH340N (That doesn't have DTR or RTS)

py32f0 series?

Hello first of all TKS a lot for this repo.
I'm wondering if it would be a pain to add PY32F0 series tool (Cortex m0+) with SWD interface?
I want a small tool to program this MCU to add this tool to the arduino IDE.

I'm trying to do this using the hidapi an libusb libraries on linux and my knowledge is not enough.

My cpp program scan the usb devices based on one txt file that contains all the vid/pid values, then connect to one of them and then it start reading and writing to one endpoint. But i dont know how to talk to the SWD HID device...

Here is the TXT file for the CMSIS/DAP device list:

# This file is a list of VID / PID of the devices that the py32flasher will search
# to flash the PY32F Microcontrollers.
# You can find the VID / PID values using in linux the command "lsusb" on the terminal
# In Windows you can find this values following the next steps:
# * Go to Control Panel > Device Manager and find your USB device
# * Double click the device or right click and select Properties.
# * Go to the Details tab and select Hardware ID to view its PID and VID.
#
# You should add the VID and PID following the next examples: 


# STM32 nucleo boards, with onboard st/linkv2-1
0483 374b
0483 3752

# STM32 discovery boards, with onboard st/linkv2
0483 3748

# STLINK-V3 boards (standalone and embedded) in usbloader mode and standard (debug) mode
0483 374d
0483 374e
0483 374f
0483 3753
0483 3754
0483 3755
0483 3757

# Essemi ESLinkII
30cc 9527

# WCH-Link
1a86 8011

# # WCH-Link clone
2a86 8011

# Wagiminator picoDAP
1209 C55D

# CMSIS-DAP Cat Programmer
4348 55E0

# Cypress KitProg1/KitProg2 
04b4 f138
04b4 f148

# Cypress MiniProg4
04b4 f151
04b4 f152

# Cypress KitProg3
04b4 f154
04b4 f155
04b4 f166

# DAPLink
0d28 0204

# Keil ULINKplus
c251 2750

# NXP LPC-LinkII
1fc9 0090

# NXP MCU-Link
1fc9 0143

# Microchip EDBG CMSIS-DAP
03eb 2111

# Microchip JTAGICE3 CMSIS-DAP
03eb 2140

# Microchip Atmel-ICE CMSIS-DAP
03eb 2141

# Microchip Power Debugger CMSIS-DAP
03eb 2144

# Microchip mEDBG CMSIS-DAP
03eb 2145

# Microchip EDBGC CMSIS-DAP
03eb 216c

# Microchip nEDBG CMSIS-DAP
03eb 2175

# RadioOperator STM32F103C8T6_CMSIS-DAP_SWO probe firmware
# Note, this firmware uses STMicroelectronic's USB VID.
0483 572a

chprog.py - "Configuration not set" Error

Dear Stefan,

Thanks a lot for all your wonderful sharing.

I was using the "chprog.py" script for programming CH32X033 chip on a M1 MacOS and bump into the following error.
"Configuration not set", it could very well be a local issue on my setup, so might not be something of a concern.

I manage to get the programer to work for me by adding the following
"self.dev.set_configuration()" to line 89. (Sorry not a Python programmer myself)

Hope it would come in handy for anyone facing the same issue.