Flow_Controller/firmware/Readme.md

CH32V003 Firmware & Linux Development Setup

This folder contains the firmware source code for the CNC Water Flow Controller, built using the ch32fun framework.

Below is the guide to set up the build environment, compile, and flash the CH32V003 series on Linux using CLI tools.

Tested on: Ubuntu Linux, CH32V003J4M6 (8-pin)

---

1. Install toolchain

1.1. Download xPack RISC-V GCC:

https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases

Choose linux-x64 for X86-64 or linux-arm64 for ARM64.

Extract it:

cd ~/Downloads
mkdir -p ~/toolchains
tar -xzf xpack-riscv-none-elf-gcc-15.2.0-1-linux-x64.tar.gz -C ~/toolchains # Update e.g.: to your version

Activate it (add this to your ~/.bashrc for permanence):

export TOOLCHAIN=$HOME/toolchains/xpack-riscv-none-elf-gcc-15.2.0-1 # Update e.g.: to your version
export PATH=$TOOLCHAIN/bin:$PATH

Verify the installation:

riscv-none-elf-gcc --version

It should print:

riscv-none-elf-gcc (xPack GNU RISC-V Embedded GCC x86_64) 15.2.0
Copyright (C) 2025 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

1.2. Install dependencies

sudo apt update
sudo apt install libusb-1.0-0-dev libudev-dev

1.3. Fix the USB permissions issue

Add a udev rule for WCH-Link / minichlink.

Before creating the rule, verify the USB vendor and product IDs match your device:

lsusb

Example output:

Bus 001 Device 005: ID 1a86:8010 QinHeng Electronics WCH-Link

Make sure:

• 1a86 matches idVendor
• 8010 matches idProduct

If your device reports different IDs, use those values in the rule below.

Create:

sudo nano /etc/udev/rules.d/99-wch.rules

Add:

SUBSYSTEM=="usb", ATTR{idVendor}=="1a86", ATTR{idProduct}=="8010", MODE="0666"

Then reload:

sudo udevadm control --reload-rules
sudo udevadm trigger

Unplug/replug the programmer.

2. Install Flashing Tool (minichlink)

Clone the ch32fun repository and build minichlink:

cd ~/
git clone https://github.com/cnlohr/ch32fun ~/ch32fun
cd ~/ch32fun/minichlink
make
sudo mv minichlink /usr/local/bin/

3. Build the Firmware

Navigate to this firmware directory where the Makefile and main.c are located. Make sure the ch32fun path in the Makefile points to where you cloned ch32fun.

cd ~/proj/Flow_Controller/firmware
make clean
make

This will generate main.bin and main.elf.

4. Flash Firmware

Connect your WCH-LinkE programmer to the board's J1 header:

Signal	Programmer	MCU Header (J1)
SWIO	SWDIO	Pin 3 (SWIO)
GND	GND	Pin 2 (GND)
5V	3.3V	Pin 1 (+3.3V)
Flash the compiled binary:

make flash

or manually:

minichlink -w main.bin flash

5. Logs

See logs on the SWIO pin:

minichlink -T

6. Unbricking

If you accidentally misconfigure the SWIO pin and lock yourself out, you can use the CH32V003 Unbrick CLI tool:

git clone https://github.com/shakir-abdo/ch32v003-unbrick.git
cd ch32v003-unbrick
npm install
./unbrick.js