wch-isp(1)

💅 wch-isp — like, the manual page, bestie 🌸

okay so you found yourself at wch-isp(1) — welcome to the group chat 🫶 this is the firmware programmer for WCH microcontrollers, and by the end of this page you're gonna understand it so well. no cap.

---

✨ SYNOPSIS ✨

like, here's the whole vibe in code form (copy it exactly, don't @ me):

wch-isp [OPTIONS] COMMAND [ARG...]

wch-isp [-VDnpr] [-d UID] [flash|write|verify|reset] FILE

wch-isp [-VDnpr] [-d UID] [erase|config|remove-wp]

wch-isp [-VDnpr] [-d UID] config-set REG_NAME[:FIELD_SEL]=VALUE

wch-isp [-VDnpr] [-d UID] [list]

see how it's always OPTIONS first, then a COMMAND, then whatever args that command wants? that's the whole pattern, iykyk 💫

---

💖 DESCRIPTION 💖

wch-isp is an utility to write firmware into the flash of WCH microcontrollers, over USB. that's the main character energy right there 👑

and here's the little detail that's genuinely so thoughtful: by default the flash content is verified after writing. like, it double-checks its own work. we love a self-aware icon 💅

---

🎀 OPTIONS 🎀

every single flag, no skips, fr fr:

• -d UID — selects the USB device that matches the UID. and if nothing matches? then UID is used as an index to select a device from the list. cute little fallback, honestly 🌈
• -n — do not verify flash content after writing. heads up: verification is done by default, so this one turns it off 🙈
• -p — prints a progress bar during command operation. the little [####] bar. obsessed 🍓
• -r — reset the microcontroller after the command is completed 🔄
• -D — enable debug information, print raw isp commands sent over USB. for when you wanna see everything the chip is saying, lowkey nosy but valid 💀
• -V — prints version information to stdout, then exits. bye bestie 👋

---

👑 COMMANDS 👑

list

lists the currently detected compatible USB devices 📋✨

write FILE

writes FILE into flash — and it will automatically erase sufficient flash sectors before writing to it. yes queen, it handles the boring part for you 💖

flash FILE

writes FILE into flash, same as write. literally the same thing. twins 👯

verify FILE

verifies FILE content against the flash content. a lil vibe check for your firmware ⭐

reset

resets the microcontroller and jumps to code flash 🚀

erase

erases all the flash content. all of it. no survivors 💀 (ok but seriously, it's all of it)

config

prints a memory dump of the chip configuration. and when supported, the config is decoded to show registers name with it's fields value — so you get the pretty human-readable version, not just bytes 🌸

config-set REG_NAME[:FIELD_SEL]=VALUE

changes the value of a config field 🛠️

REG_NAME designates the name of the register to modify in the config (see config output, bestie — it's right there). FIELD_SEL is optional, and can be either:

• a number [0-9]+
• a range [0-9]+:[0-9]+
• or the name of a field

three whole options, we stay versatile 💅

remove-wp

disables flash write protection — heads up though, this modifies the chip configuration 🫶

---

🦋 EXAMPLES 🦋

list detected devices:

$ wch-isp list
0: BTVER v2.7 UID 8d-ff-ba-e4-c2-84-09-69 [0x1069] CH569
1: BTVER v2.5 UID f2-3e-88-26-3b-38-b5-9d [0x1980] CH32V208WBU6

look at those two icons sitting there being detected 😌✨

flash the firmware.bin file, -p enables the progress bar:

$ wch-isp -p flash firmware.bin
BTVER v2.5 UID f2-3e-88-26-3b-38-b5-9d [0x1980] CH32V208WBU6
[####################################################] write 35392/35392
[####################################################] verify 35392/35392
flash done

not the double progress bar 😭 write and verify, both ate 💯

erase the device's flash, select the device by it's UID (option -d):

$ wch-isp -d f2-3e-88-26-3b-38-b5-9d erase
BTVER v2.5 UID f2-3e-88-26-3b-38-b5-9d [0x1980] CH32V208WBU6
erase done

picking your device by UID is so much more precise than an index, ngl 🎯

change the config to disable the read protection RDPR and change the STOP_RST bit:

$ wch-isp config-set RDPR=0xa5 USER:STOP_RST=0
BTVER v2.6 UID cd-ab-bb-76-04-bc-8c-de [0x153f] CH32V103x6x6 (flash 32K)
writing new config
config-set done
$ wch-isp config
BTVER v2.6 UID cd-ab-bb-76-04-bc-8c-de [0x153f] CH32V103x6x6 (flash 32K)
raw: a5 5a ff 00 ff ff ff ff ff ff ff ff
00: RDPR: 0xa5
    [7:0]: 0xa5 (disabled)
02: USER: 0xff
      [5] PORCTR: 1 (0b1)
      [2] STANDBY_RST: 1 (disabled)
      [1] STOP_RST: 0 (enabled)
      [0] IWDG_SW: 1 (disabled)
04: DATA0: 0xff
06: DATA1: 0xff
08: WRPR0: 0xff
09: WRPR1: 0xff
0a: WRPR2: 0xff
0b: WRPR3: 0xff
config done

see how config-set takes REG_NAME:FIELD_SEL=VALUE and then config shows you the whole decoded dump after? the way that it just works 🔥 and yes, RDPR went to 0xa5 (disabled) and STOP_RST flipped to 0 (enabled). you did that 💅

lil reminder bestie: remove-wp and config-set both modify the chip configuration. like, actually change stuff on the chip. so know what you're doing before you type it, mwah 🫶

---

and that's the whole page!! version 0.5.0, dated 1980-01-01 — yes the date is iconic and weird, we stan an ageless legend 🎀✨ go flash something, you got this 💜