131 lines
3.3 KiB
Markdown
131 lines
3.3 KiB
Markdown
# 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
|
|
``` |