This repository contains a collection of example projects to be used with the newly developed CH32V PlatformIO integration.

The examples range from using the NoneOS SDK over to FreeRTOS and TencentOS projects and more.

As these are PlatformIO projects, the PlatformIO documentation at https://docs.platformio.org/ always applies. Especially useful are the Getting started with VSCode + PlatformIO, CLI reference and platformio.ini options pages.

It is assumed that you have either installed VSCode + PlatformIO or PlatformIO on the CLI following the documentation above.

Open VSCode, expand the PlatformIO sidebar (ant icon) and click "PIO Home".

In the resulting PIO Home window, click on the "Platforms" sidebar and chose "Advanced Installation"

You will be asked for a repistory. Enter the URL and press "Install".

The platform should now be successfully installed.

Experienced PlatformIO CLI users can also use the short-hand command

Inevitibly, the platform version you installed at one point will become outdated.

There are two ways to update:

The PIO Home -> Platforms screen lists all installed platforms. This can be filtered by CH32. If a (git) update is available, there will be an "Update" button available.

In the PlatformIO CLI, execute

Clone this repository in an arbitrary folder.

When using VSCode, open the PIO Home screen, e.g. via the toolbar. Use the "Open Project" open to navigate to one of the projects in the repository that you just cloned, e.g., blinky-none-os.

After opening the project, trust the VSCode workspace in the popup dialog. Your workspace should now contain the new project.

The available boards for an example are listed in the platformio.ini file of the project. For each board, there is an [env:board] section describing the build parameters. Refer to the documentation linked above for detailed information.

For example, the blinky-none-os project contains

Thus all these chips / development boards are available.

The available board values are the boards available in the platform. Note that not every board supports every framework. The CH32V003 series does not support frameworks other than noneos-sdk due its small RAM and Flash sizes.

In VSCode, to select a certain board environment (and project), you must use the project environment switcher in the bottom blue taskbar. Make sure your wanted board and project are selected before continuing. After selecting a new environment, the IntelliSense will be reloaded, which might take a bit.

For CLI users, the target environment is given as the -e switch in the pio run command, see documentation.

In VSCode, use the project tasks list in the left PIO sidebar as normal to trigger the "Build" action, or a different action, for a certain environment. The environment you have previously selected as your default will be the expanded one.

For CLI users, executue the pio run -e command, as documentend above.

Compilation should result in a success, e.g.:

Note that the default upload method and available upload method is listed in the board manifest, e.g. for the GD32F303CC board, stlink is the default, attempting to upload via a ST-Link probe connected to the chip via SWD, using OpenOCD as tool. JLink, CMSIS-DAP, BMP, serial and USB-DFU (experimental) upload methods are available as well. To change the upload method, change upload_protocol accordingly. SWD based upload methods can also be used as debug_tool for live-debugging.

For VSCode users, use the project task "Upload".

For CLI users, use pio run -t upload -e as documented above.

Example of upload:

For examples using serial output, you need to connect your WCH-Link(E)'s UART signals, or a USB-UART converter, to the target's UART pins to be able to observe it. For all chip series, when the debug.h code is used, this is by default UART1 on TX = PD5, RX = PD6. Note that the UART adapter and the target board should also share a common GND connection.

To access the serial montior in VSCode, execute the "Monitor" project task, as shown above.

To access it from the CLI, execute pio device monitor.

The monitor is aborted by pressing the standard Ctrl+C combination.

Settings like the baud rate or adapter to use (if not auto-detected) are to be found in the monitor section of the platformio.ini.

Example:

If a SWD capable debug probe is connected to the target, and configured via debug_tool, you can open the "Debug" sidebar in VSCode. In the upper left, the configuration "PIO Debug (your-project-name)" should be selected. By pressing the the "Play" button then, PlatformIO will start compiling the project in debug mode, start the debug server (e.g., OpenOCD) and connect to it with the appropriate GDB client.

Note: Currently, only the WCH-Link(E) is supported as debugging adapter.

It should hit a breakpoint in the main() function of the project (which can e.g. be in the Arduino core). From there, use the regular Step Over, Step Into, Step Out of, etc. buttons for debug control.

VSCode also shows the state of all peripheral registers (such as USART1, ADC0, etc.) and decodes them. The RISC-V core's internal registers are shown in the expandable "Registers" panel.

Note all the other possible debug configuration options.

The same can be achieved from the CLI, as documented. This launches the user into a GDB session.