hello-ch32v003

A simple "Hello World"-like project for the ultra low-cost WCH CH32V003 RISC-V MCU.

This project contains a simple set of modules to get the MCU running in a minimal configuration:

• Serial I/O on USART1 (connected to WCH-LinkE USART)
• TIM1 Channel 3 configured for PWM output to LED
• SysTick enabled and using auto-reload feature
• I2C1 interface with 24C64 EEPROM read and write access

ℹ️ See README.vscode.md for VSCode setup information! ℹ️

Requirements

• Hardware
  • WCH CH32V003F4P6-EVT+WCH-LinkE Starter Kit (available from LCSC, PartNr C5236707)
    • Starter Kit includes WCH-LinkE Debugger
  • 6 pcs. female-female jumper wires
  • (optional) additional 1 pc. female-female jumper wire for LED demo
  • (optional) AT24C64 EEPROM IC + Solderless breadboard + 2x 10k Resistors
• Software
  • MounRiver Studio Community (as of March 2023, a manual OpenOCD update is needed)
  • Serial terminal program, e.g. PuTTy or minicom

Manual OpenOCD Update for MounRiver V1.30 or earlier

MounRiver Studio Community V1.30 does not include the updated OpenOCD build required for WCH-LinkE support. In order to update the debugger, perform the following steps:

• Download the MounRiver Studio V1.84 Update package
• Extract the package into a temporary folder
• Copy the contained toolchain folder to your local MounRiver Studio Community installation
• Confirm overwrite of all files in the toolchain folder

Hardware Setup

• (optional) Connect the LED1 and PC3 pins on header P2 using a female-female jumper wire
• Follow instructions from the WCH-LinkE User Manual for connecting the debugger to your EVT board.

WCH-LinkE Pin	EVT Board Pin
RST	NRST / PD7
3V3	VCC (*)
GND	GND
SWDIO/TMS	PD1
TX	PD6
RX	PD5

*) For powering the target from your WCH-LinkE debugger. Omit this if you want to power the EVT board via its own USB port.

EEPROM Hardware Setup (optional)

• Connect the LED1 and PA6 pins on header J3 using a female-female jumper wire
• Connect the 24C64 EEPROM to PB10 and PB11 and add 10k pull-up resistors to SDA and SCL:

       .___________.  VCC   VCC VCC       VCC  .________________
      1|    |_|    |8  |     |   |         |   |
   +---| A0    VCC |---+    .|. .|.        +---| VCC (3V3)
   |  2|           |7       | | | | R1,R2      |
   o---| A1     WP |---+    |_| |_| 10k    +---| GND
   |  3|           |6  |     |   |         |   |
   o---| A2    SCL |---(-----o---(---------(---| PC2 (I2C1_SCL)
   |  4|           |5  |         |         |   |
   o---| GND   SDA |---(---------o---------(---| PC1 (I2C1_SDA)
   |   |___________|   |                   |   |________________
  GND  U2             GND                 GND  U1
       AT24C64 (DIP8)                          CH32V003
  

Note

If you want to use the EEPROM demo, remove the comment at the start of the #define USE_EEPROM_DEMO line at the top of main.c. The demo is disabled by default.

Usage

• Clone this repository using the following command. Note the use of the --recursive tag.

  git clone --recursive https://github.com/islandcontroller/hello-ch32v003
  

• Load this project in MounRiver Studio Community and build the executable
• Open a serial terminal on the WCH-LinkE programmer's VCP (115200 Baud, 8N1)
• Flash the firmware to the MCU using the provided .launch script
• Resume execution once breakpoint in main() is reached
• Press ? in the serial terminal to show available commands

SOIC8 Pin Mapping and "un-bricking"

On the SOIC8 package CH32V003J4M6, the debug interface is multiplexed with USART1 data lines. In the default configuration, enabling the UART transmitter will block debugger access. To use both USART1 and the debug port, un-comment the USE_SOIC8_UART_REMAP macro definition in hw_layer/hw_iodefs.h. Use the following table for connecting the debug probe to the SOIC8 part:

WCH-LinkE Pin	SOIC8 Pin
3V3	4 VDD
GND	2 VSS
SWDIO	8 PD1/PD5/PD4 (*)
TX	8 PD1/PD5/PD4(*)
RX	1 PD6

*) Note: WCH-LinkE TX and SWDIO lines are connected to the same pin at the SOIC8 part!

In order to use the USART pin, close the debug connection (OpenOCD) in software. This releases the SWDIO line to a high-impedance state.

Un-bricking an SOIC8 part

If an SOIC8 part has been programmed without swapping the RX/TX lines, debugger access is no longer possible. A full chip reset is required.

Use the WCH-LinkUtility to perform a full chip reset:

• MCU Core: RISC-V
• Series: CH32V00x
• Target -> "Clear All Code-Flash-By Power Off"

Licensing

If not stated otherwise in the specific file, the contents of this project are licensed under the MIT License. The full license text is provided in the LICENSE file.

SPDX-License-Identifier: MIT

Help and References

• openwch/ch32v003 Manufacturer EVT demos and documentation
• WCH-IC: CH32V003DS0.pdf MCU Datasheet
• WCH-IC: CH32V003RM.pdf MCU Reference Manual
• WCH-IC: QingKeV2_Processor_Manual.pdf Processor Core Manual

If you're looking for further information about WCH products, check out their community Discord server: