WCH RISC-V Microcontroller Web Serial ISP

How do I get my device to run the bootloader?

Methods vary between device families. Bootloader entry at reset is typically controlled by the state of one or more pins. Consult table below, or see your device's documentation.

1. '0' indicates logic-low voltage level, '1' indicates logic-high voltage level.
2. 'TX' is transmit output from the device, 'RX' is receive input to the device.

For devices with BOOT0 and BOOT1 control pins, some package variants may have BOOT1 internally tied to GND, with only BOOT0 exposed. Other packages may not have either pin exposed, with BOOT0 tied internally to GND, effectively rendering the bootloader unusable.

What does the DTR/RTS reset sequence option do?

For devices equipped with a DTR/RTS "auto-download" reset circuit that controls NRST and BOOT0/1 pins, when this option is enabled it will, each time the serial connection is opened, give a special sequence of signals on the serial DTR and RTS lines to cause the device to be automatically reset into the bootloader.

The exact construction of such a circuit will not be covered here, but the output NRST and BOOT0/1 signal states of any circuit used, given the input DTR/RTS signals shown, should match that depicted in the diagram below.

Note that this is not compatible with the "Serial Port One-Click Download" CH340X circuit that is recommended by WCH for use with its WCHISPStudio software.

Why is my loaded firmware larger than it should be?

When a firmware file is loaded it is padded to the next 1,024 byte boundary. For example, a 4,835 byte firmware will be padded to 5,120 bytes.

Due to the nature of flash memory, before it can be written, an area corresponding to the size of data to be written must first be erased. However, the WCH factory bootloader only performs erasure on sizes that are multiples of 1,024 bytes. Therefore, the firmware is padded to meet the bounds of the erased area.

Padding is done with 0xFF bytes.

Why are the listed flash sizes for CH32V20x and CH32V30x larger than specified in the datasheet?

These families actually use a dual-die configuration inside the package: one for the microcontroller only, and a second for the flash memory. The MCU also features a large amount of RAM, greater than what is available to the user. At start-up, they automatically copy a certain portion of this 'external' flash into a reserved area of RAM, and code is executed from there, as if it were flash. This caching permits higher microcontroller speed than would otherwise be possible with such an 'external' flash.

For some devices in these families, the relative proportion of code flash to RAM can be configured in the option bytes (see reference manual for details). For example, less flash but more RAM, or more flash but less RAM. The datasheet specification tables list the default size allocated to the flash RAM cache, not the physical flash capacity.

The larger, actual flash capacity is utilised by this tool so that the entire capacity of flash is capable of being written to, regardless of configured flash-RAM split.

I tried to load a firmware file, but I get a maximum size exceeded error.

You may have loaded an Intel Hex or S-Record file that specifies the firmware image to be loaded at an address of 0x8000000 and onwards. Because this tool expects addressing to be relative, not absolute, such a file will cause it to first try and fill the range from 0x0 to 0x7FFFFFF with blank data before processing the file's data. Because that amount of data is larger than the maximum allowed, an error occurs.

Your firmware image should instead be based at 0x0, using relative addressing, not absolute.

Why do I get a warning in the log about the reported device variant not matching the selected device?

The specific device you have selected does not exactly match the one you are talking to.

Ensure you have selected the correct package variant for the device in question. For example, if you are using an 8-pin CH32V003J4M6, but have 20-pin CH32V003F4P6 selected, you will get this warning.

Ignoring this warning may be detrimental, due to some device families not having identical flash sizes for all their variants.

I loaded a firmware file, but the button to write to flash is disabled.

The size of the firmware is too large for the currently selected device. You will have been warned about this when loading the firmware file.

Make sure you select the correct device variant. Some families do not have an identical flash size for all their devices.

A warning is also issued if you subsequently change device to one too small after having loaded a firmware file.

I disabled read-protection by changing RDPR to 0xA5 and then writing the new config. Why does my microcontroller now no longer work?

Because your flash memory got erased!

When the RDPR option byte is changed to un-protected (value 0xA5) from previously protected (any other value), the microcontroller will automatically perform a full erasure of the user application flash memory.

Why is there no option to read flash?

The WCH bootloader does not support reading out the contents of flash — there is no command in the protocol to accomplish that.

Does my firmware data get uploaded to or saved on the server?

No. Although it is hosted on a web server, this tool runs locally in your web browser, and any firmware file you load never leaves your computer, nor is it retained anywhere.

Can I create a link to here which auto-selects a device and/or auto-loads a firmware URL?

Yes. A query string can be added to this page's URL to auto-select a device, auto-load a firmware file from an external URL, or both. Append a question-mark character (?) and then one or both of the following parameters:

• dev=device — replace 'device' with the full number of the desired part (e.g. dev=CH32X035C8T6). Device names specified this way are not case-sensitive.
• fw=url — replace 'url' with the full entity-encoded URL of the firmware file (e.g. fw=http%3A%2F%2Fexample.com%2Ffirmware.hex).

Both parameters may be combined by separating them with an ampersand character (&).

The device I want to program is not listed.

If your device's factory bootloader supports serial UART communication, then you can request it to be added by opening a new Issue on the GitHub repository.