# CH32V003 Firmware & Linux Development Setup

This folder contains the firmware source code for the CNC Water Flow Controller, built using the [ch32fun](https://github.com/cnlohr/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](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:
```bash
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):
```Bash
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:
```Bash
riscv-none-elf-gcc --version
```

It should print:
```Bash
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
```bash
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:
```Bash
lsusb
```
Example output:
```Bash
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:
```Bash
sudo nano /etc/udev/rules.d/99-wch.rules
```
Add:
```Bash
SUBSYSTEM=="usb", ATTR{idVendor}=="1a86", ATTR{idProduct}=="8010", MODE="0666"
```
Then reload:
```Bash
sudo udevadm control --reload-rules
sudo udevadm trigger
```
Unplug/replug the programmer.

## 2. Install Flashing Tool (minichlink)
Clone the ch32fun repository and build minichlink:
```Bash
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`.
```Bash
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:
```Bash
make flash
```
or manually: 
```bash
minichlink -w main.bin flash
```

## 5. Logs
See logs on the SWIO pin:
```Bash
minichlink -T
```

## 6. Unbricking
If you accidentally misconfigure the SWIO pin and lock yourself out, you can use the CH32V003 Unbrick CLI tool:
```Bash
git clone https://github.com/shakir-abdo/ch32v003-unbrick.git
cd ch32v003-unbrick
npm install
./unbrick.js
```