CH32V003 - getting started inklusive eines Selbstbauprogrammer DIY

        16.06.2025     R. Seelig





Zu allererst: Diese Seite behandelt eine Toolchain-Kette, Funktionen für den CH32V003 und den Aufbau eines DIY Selbstbauprogrammers unter Linux (auch wenn die Programmerhardware unter Windows lauffähig ist, benötigt der Programmer und die Toolchain-Kette eine komplett andere Installation)

Die hier beschriebenen Programme und Sourcedateien sowie alle Bilder und Pläne sind - exklusive des Compilers - in einer Archivdatei zusammengefasst, die hier gedownloaded werden kann:



Aller Anfang ist schwierig und möchte man mit einem unbekanntem Mikrocontroller starten kommt es unweigerlich zu unterschiedlichen Einstiegshürden.

Heutzutage gibt es für Bastler (heißt mittlerweile ja neudeutsch "Maker") jedoch viele Produkte die diesen Einstieg erleichtern und so erklärt sich auch der große Erfolg von Arduino: Einstecken, Programm aufspielen, geht.

Für diese Gruppe ist der Selbstbauprogrammer nicht gedacht. Für den, der sich den Einstieg leichter machen und mit einem CH32V003 anfangen möchte gibt es vom Hersteller des Chips ein Entwicklungspaket namens MounRiver Studio welches hier gedownloadet werden kann:



Hinweis: Der hier vorgestellte Selbstbauprogrammer ist mit der IDE MounRiver Studio NICHT kompatibel, bzw. kann von dieser IDE heraus nicht gestartet werden. Hier müßte auf Konsolenebene eine erstellte Binary- oder Hexdatei manuell in den Controller übertragen werden. Des weiteren benötigt es zum Programmieren der Firmware des Programmers einen Ardudino UNO / nano oder eines AVR-Systems mit zugänglichen GPIO-Pins und einer USB2UART Bridge. ATmega328, ATmega168, ATmega8 und ATtiny2313 sind in der Lage, die Firmware in den Programmer zu flashen.


    Übersicht der Schritte zum Aufbau des Selbstbauprogrammers und "erste Schritte" bei der Programmierung eines CH32V003   

  • Hardwareaufbau des Programmers

  • Installieren des RISCV-Compilers (wird für die Compilierung der Programmerfirmware und der späteren Programmierung von CH32V003 Mikrocontrollern benötigt)

  • Installieren des zu diesem Text gehörenden Archivs (alle zum Aufbau des Programmers und späteren Umgang mit CH32V003 benötigten Dateien sind hierin enthalten, exclusive des Compilers)

  • flashen der Firmware ARDULINK auf einen Arduino um hieraus einen (sehr langsamen) Programmer zu machen (wird nur einmal benötigt um die Firmware des Selbstbauprogrammers zu flashen)

  • flashen der Firmware des Selbstbauprogrammers über ARDULINK

  • Compilieren des Hostprogramms minichlink über den der Selbstbauprogrammer angesprochen wird

  • evtl. installieren eines Texteditors (vorzugsweise hier: Geany) mit dem ein Programm für den CH32V003 bearbeitet oder erstellt werden kann

  • Demoprogramme des Archivs testen


    Programmer    


Grundsätzlich gibt es vom Hersteller des Chips auch einen sehr günstigen Programmer / Debuger für den CH32V003 zu kaufen, aber hier gibt es schon den allerersten Fallstrick, auf den man hereinfallen kann (und auf den auch der Autor hereingefallen ist):

Im Internet werden unterschiedliche Programmer angeboten, die auf den ersten Blick identisch aussehen, es jedoch nicht sind:

Hier ist zwischen einem Programmer WCH-LinkE (mit einem großem "E" am Ende) und einem WCH-Link (OHNE einem "E" am Ende) zu unterscheiden.

Wichtig: Der WCH-Link ohne "E" ist NICHT in der Lage einen CH32V003 zu programmieren und ist wohl ein älterer Adapter, der gerne als WCH-LinkE verkauft wird. Dem Autor wurden insgesamt 3 Stück WCH-LinkE verkauft, die jedoch Programmer ohne "E" waren. Das ist dann auch der Grund, warum der Selbstbauprogrammer aufgebaut worden ist. Unterscheiden kann man die Versionen vordergründig dadurch, dass der Programmer ohne "E" mit einem 16 pol. IC (CH549), der mit "E" mit einem 20 pol. IC (CH32V305) realisiert ist.

Dieser Programmer ist natürlich mit dem herstellereigenen MounRiver Studio kompatibel, jedoch auch mit dem hier später vorgestellten Framework CH32FUN auf Kommandozeilenebene.


    Der Selbstbauprogrammer DIY    



Um es hier deutlich zu machen: Der Selbstbauprogrammer sowie das CH32FUN Framework sind nicht vom Autor dieses Textes. Das Programm des Programmers sowie das Framework selbst sind auf zwei github- Seiten von Christian Lohr zu finden. Für das Arbeiten mit diesem Text ist ein Download von diesen Seiten nicht notwendig, weil bis auf den Compiler selbst alle benötigten Dateien im Archiv zu diesem Text enhalten sind. Die Linkadressen zu Christian Lohr's Seiten wird hier für denjenigen aufgeführt, der sich evtl. aus den dort erhältlichen Programmen und Dateien sein eigenes Setup "zusammenbasteln" oder sich über weitreichende Beispiele informieren mag: Dass der Autor den Programmer aufgebaut hat, ist zum Einem dem Umstand geschuldet, dass er "verärgert" war über die Nichtlieferung eines geeigneten Programmers sowie die sehr lange Wartezeit bis ein solchiger geliefert wurde. Zum anderen arbeitet er gerne mit eigenen Tools, damit er im Falle eines Defektes sich selbst schnell behelfen kann. Ist man zudem unschlüssig, ob man mit dem CH32V003 etwas anfangen mag bedarf es außer dem Zeitaufwand wirklich nur sehr wenig finanziellen Mitteln um diesen Chip zu erkunden. Bestellt man bspw. bei AliExpress oder bei www.lcsc.com sowieso irgendwelche Bauteile, so kann man sich ein paar der Chips gleich mitbestellen, was angesichts von 0,25 Eur per Chip verschmerzbar ist. Außer PCB-Adaptern für den Chip selbst, der Mini-USB Buchse sowie für einen AMS1117 3.3V Spannungsreglers bedarf es nur absolut üblichen Elektronikbauteilen um mit dem CH32V003 zu starten.



    Schaltplan    


Um mit dem Programmer Zielsysteme sowohl für 3,3V und 5V unterstützen zu können, wurde der Schaltung ein 3,3V Spannungsregler hinzugefügt, die mittels eines Jumpers (voltage selector) oder eines Schiebeschalters umschaltbar ist. Da ein USB-Pegel nur 3,3V Pegel annehmen darf, sind in die D- und D+ Leitungen des USB in allerbester (okay, eher "dirty") V-USB Manier im Stile von bspw. eines USBasp 3,3V Zenerdioden eingefügt worden. Hier sind kleine 1/4W Z-Dioden zu verwenden. Bei leistungsstärkeren ZDioden kann es vorkommen, dass die Kennlinie im Sperrbereich die Spannung nicht steil genug begrenzt und höhere Pegel (bis hinauf zu 3,9V) auf den Leitungen des USB auftreten. Hier arbeitet dann der Programmer nicht richtig, bzw. wird der Programmer vom PC nicht als solcher erkannt und arbeitet demzufolge dann mit diesem auch nicht zusammen.

Die Connector-Reihe J3 beherbergt alle Anschlüsse die für den Umgang mit einem Zielsystem benötigt werden:
  • swclk / swdio ist an die Pins des Zielsystems anzuschließen, wobei für das Programmieren eines CH32V003 nur swdio benötigt wird, da dieser über ein SingleWire Protokoll verfügt.

  • self wird benötigt, um die Firmware in den Programmer zu flashen (wie dieses ohne einen vorhandenen Programmers erfolgen kann wird später erklärt)

  • GND / 5V / 3,3V sind Versorgungsanschlüsse für das Zielsystem

Der Programmer selbst kann sogar auf einem Steckbrett aufgebaut werden (für einen ersten Versuch), nur leider sind Steckbretter bezüglich der Steckverbindungen nicht sonderlich zuverlässig. Aus diesem Grund heraus hat der Autor (seit Jahren das erste mal wieder) einen Aufbau auf Lochrasterkarte vorgenommen. Dieses ist dann immer noch schneller, als auf die Lieferung eines korrekten WCH-LinkE oder einer entworfenen Platine zu warten. Für denjenigen, der das auf Lochrasterkarte aufbauen mag, wurde ein Layout für Lochrasterkarte und Silberdraht erstellt.


    Layout Lochrasterkarte    



Hinweis: Der CH32V003 im TSSOP-20 Gehäuse, die Mini-USB Buchse sowie der Spannungsregler AMS1117 3.3 sind auf PCB-Adaptern zu verlöten und diese Adapter dann auf der Lochrasterkarte zu verbauen. Beim Aufbau darauf achten, von den niedrigen Bauteilen zu den höhreren Bauteilen zu Bestücken. Am Besten wird mit den Lötbrücken angefangen.

Die Lötseite ist so dargestellt, wie die Verdrahtung aussehen muß, wenn die Platine umgedreht wird.


    Inbetriebnahme    



Vorraussetzungen, um den Programmer und ein späteres Arbeiten mit CH32V003 zu ermöglichen: Die Reihenfolge für die Inbetriebnahme des Selbstbauprogrammers und der Toolchain für den CH32V003 ist:

  • installieren des Compilers

  • installieren des zu diesem Text gehörenden Archivs

  • compilieren des Hostprogramms minichlink

  • flashen eines AVR-Controllers um aus diesem einen ARDULINK zu machen, der dann seinerseits die Firmware für den Selbstbauprogrammer flashen kann

  • flashen des Selbstbauprogrammers

  • mit den Demoprogrammen aus dem Archiv, einem CH32V003 und dem Selbstbauprogrammer experimentieren => getting started


    Installieren des Compilers    



Als erstes muß der Compiler aus den oben genannten Quellen gedownloaded und ausgepackt werden. Dieses kann entweder aus dem Desktop heraus mit dem Programm Engrampa, in der Konsole mit dem Midnight Commander oder manuell mittels Befehlseingabe erfolgen.

Grundsätzlich kann für den Speicherort des Compilers jedes Verzeichnis gewählt werden, da alle vom Compiler benötigten Dateien relativ zu seiner Verzeichnisstruktur vorhanden sind. Der Autor hat als Speicherort /usr/local gewählt, damit der Compiler für alle Benutzer verfügbar gemacht werden kann. Da mit Emgrampa und dem Midnight Commander das Entpacken menügesteuert ist bedarf es für diese Variante keine weitere Erklärung. Exemplarisch hier also nur das Entpacken in der Kommandozeile:

In den Ordner wechseln, in den das Compilerarchiv gedownloaded wurde, sich dort als Superuser anmelden:

      su
      Passwort:

und in der nachfolgenden Zeile das Passwort hierfür eingeben. Anschließend das Archiv auspacken mit:

      tar -xvf xpack-riscv-none-elf-gcc-14.2.0-3-linux-x64.tar.gz -C /usr/local

Das Archiv wird jetzt ausgepackt und im Ordner /usr/local gibt es einen neuen Unterordner mit dem Namen: 
      xpack-riscv-none-elf-gcc-14.2.0-3-linux-x64
Innerhalb dieses Ordners ist ein weiterer Ordner namens bin enthalten. Dort sind alle Programmteile des Compilers gespeichert und der vollständige Pfad zu diesen Programmen lautet dann: 
      /usr/local/xpack-riscv-none-elf-gcc-14.2.0-3-linux-x64/bin/
Dieser Pfad ist wichtig, weil er in den Suchpfad eingetragen werden muß, in dem Linux aufgerufene ausführbare Dateien sucht.

Für die Aufnahme des Compilerpfades in den Suchpfad gibt es 2 Möglichkeiten. Zum einen ist es möglich, den Suchpfad so zu erweitern, dass alle Benutzer des Linuxsystem diesen Compiler nutzen können. Zum anderen kann der Suchpfad nur für den aktuellen Benutzer erweitert werden.

In beiden Fällen sind ist jeweils eine Textdatei zu editieren und um einen Eintrag zu erweitern.

Für die Erweiterung des Suchpfades für alle Benutzer ist die Datei /etc/profile als root zu bearbeiten. Ist das Programm Midnight Commander mc und der dazugehörende Editor mcedit auf dem System installiert (auf den meisten System ist das der Fall) kann dieses nach Anmelden auf der Konsole als root mit folgendem Aufruf erfolgen:

      mcedit /etc/profile

Dort muss am Ende der Datei der Eintrag:

      PATH="$PATH:/usr/local/xpack-riscv-none-elf-gcc-14.2.0-3-linux-x64/bin/"

gemacht werden. Hat man den Editor mcedit verwendet, ist der Eintrag mittels der F2 Taste zu speichern und der Editor selbst kann mit F10 beendet werden.

Für die Erweiterung des Suchpfades für den aktuellen Benutzer ist die Hidden-Datei /home/benutzername.bashrc zu bearbeiten. Wäre der angemeldete Benutzer bspw. mcu, würde der Aufruf lauten:

      mcedit /home/mcu/.bashrc

Dort muss am Ende der Datei der Eintrag:

      export PATH="$PATH:/usr/local/xpack-riscv-none-elf-gcc-14.2.0-3-linux-x64/bin/"

gemacht werden.

Hat man den Editor mcedit verwendet, ist der Eintrag mittels der F2 Taste zu speichern und der Editor selbst kann mit F10 beendet werden.

Es ist sinnvoll, zu überprüfen, ob der Compiler richtig arbeitet. Das kann jetzt oder zu einem späteren Zeitpunkt erfolgen, aber es ist empfehlenswert es gleich nach dieser Installation zu erledigen, damit bei einem späteren eventuellen Fehlverhalten gut ausgeschlossen werden kann, dass der Fehler nicht an einem nicht arbeitenden / auffindbaren Compilerprogramm liegt. Zu diesem Zweck startet man den Rechner am besten neu, damit die gemachten Änderungen aktiv sind.

Nach dem Neustart des Rechners sollte jetzt der Compiler von jedem Verzeichnisort aufgerufen werden können. Hierzu lässt man sich die Ausgabe der Versionsnummer des Compilers geben und damit ist dann geklärt, dass die Suchpfade richtig gesetzt sind:

      riscv-none-elf-gcc --version

Der Compiler antwortet mit:

      riscv-none-elf-gcc (xPack GNU RISC-V Embedded GCC x86_64) 14.2.0
      Copyright (C) 2024 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.



    Installieren des Archivs    



Das Archiv hat den Dateinamen ch32v003_gettingstarted.tar.gz und enthält alle benötigten Dateien und kann in ein (fast) beliebiges Verzeichnis entpackt werden.

Auch hier kann das Entpacken mittels Engrampa, dem Midnight Comander oder per Befehlseingabe erfolgen.

Nachfolgende Angaben in Bezug auf ein Verzeichnis beziehen sich im Text hier immer auf einen Benutzer mcu. Bei Befehlseingaben ist der entsprechende Benutzername anstelle von mcu einzugeben!

Beim Entpacken des Archivs wird ein Ordner ch32v003 in dem Verzeichnis angelegt, in den das Archiv ausgepackt wird. Im Beispiel hier ist es das Homeverzeichnis des Benutzers mcu:

      tar -xvf ch32v003_gettingstarted.tar.gz -C /home/mcu/

Das Archiv ist somit entpackt. Alle benötigten Dateien liegen jetzt auf dem Computer vor, inklusive der Toolchain-Kette (mit Beispielprogrammen), die auch zum späteren Programmieren des CH32V003 benötigt werden.


    Compilieren des Hostprogramms minichlink    



minichlink ist das Programm, mit dem der PC über einen Programmer (ARDULINK, der Selbstbauprogrammer oder auch ein Debuger/Programmer von WCH) den Mikrocontroller anspricht und flasht. Dieses Programm liegt im Sourcecode vor und muß compiliert werden.

Hierfür wechselt man in das Verzeichnis /home/mcu/ch32v003/minichlink und startet dort make:

      cd /home/mcu/ch32v003/minichlink
      make


Rules:

minichlink spricht die Hardware an (USB) und damit ein normaler Benutzer diese Verwenden kann, muß dem Linux gesagt werden, dass ein Benutzer dieses tun darf (nur ein Admin, root oder superuser kann ohne Einschränkung alle Hardware des PC's benutzen). Linux verwendet hierfür sogenannte "Regeln" die im zentralen Konfigurationsverzeichnis /etc/udev/rules.d abgelegt werden. In diesen Regeldateien wird vereinbart, welche Benutzergruppen welche Hardware verwenden dürfen. Im Ordner minichlink ist hierfür die Regeldatei 99-minichlink.rules enthalten, die Hardware für den Selbstbauprogrammer, einen USB-Bootloader für CH32V003 und die originalen Debuger / Programmer von WCH für die Benutzer in den Gruppen "plugdev" und "dialout" freigibt. Diese Regeldatei muß als root nach /etc/udev/rules.d kopiert werden:

      su
      Passwort:
      cp 99-minichlink.rules /etc/udev/rules.d
      exit


Beim nächsten Reboot des PC hat der Benutzer nun die Rechte, Programmer für den Mikrocontroller zu benutzen.

Hinweis: Jedes USB-Gerät besitzt eine Produktidentifikationsnumer, PID oder auch idProduct und eine Herstelleridentifikationsnummer, VID oder auch idVendor. Die Regeldatei beinhaltet eine Auflistung genau dieser Identifikationsnummern zum Zugriff auf die Hardware.


    Arduino ARDULINK erstellen    



Um die Firmware in den Selbstbauprogrammer zu flashen benötigt es einen Programmer, den wir (noch) nicht haben. Hierfür kann man sich mit einem Arduino UNO/nano oder eines AVR-Systems behelfen, welches über einen der Controller ATmega328p / 168 / 88 oder ATtiny2313 sowie einer USB2UART-Bridge verfügt.

Hierfür gibt es das AVR-Programm ARDULINK. Dieses Programm ist bereits compiliert und kann mittels eines Scripts in den AVR-Controller geflasht werden. Hierzu wechselt man in das Verzeichnis ardulink und startet dort das Script. Im Script selbst sind Angaben über den zu verwendeten Programmer des AVR, den Anschlußport des Controllers und den zu angeschlossenen Controller selbst zu tätigen. Jede der Eingaben im Script ist mit der Return-Taste zu bestätigen.

Hinweis: Originale Arduino's verwenden den Port ttyACM0, die China-Clones haben in aller Regel einen CH340G Chip als USB2UART-Bridge verbaut und verwenden den Port ttyUSB0. Desweiteren werden originale Arduino nano mit einer Baudrate von 57600 Baud, manche Clones mit 115200 Baud betrieben.


      cd /home/mcu/ch32v003/ardulink
      ./flash_ardulink exit


Der Arduino ist jetzt ein Programmer für einen CH32V003, der SWIO-Anschluss ist hier PD6 Arduino Pin 6.

Mit diesem könnte man jetzt schon arbeiten und grundsätzlich Programme für den CH32V003 flashen (wie es der Autor des Textes zu Beginn mit dem CH32V003 auch getan hat). Allerdings hat der ARDULINK-Programmer einen entscheidenden Haken: er ist schier unerträglich langsam. Für das Flashen eines Programms in der max. Größe von 16 kByte benötigt ARDULINK ca. 80 Sekunden , bis das Programm geflasht ist. Für ein flüssiges Arbeiten ist dieses viel zu langsam und aus diesem Grunde wurde der Selbstbauprogrammer aufgebaut.


    Firmware des Selbstbauprogrammers flashen    





Um die Firmware zu flashen verbindet man Pin 6 / PD6 des Arduino's über einen 2,2k Serienwiderstand mit dem self-Anschluß des Selbstbauprogrammers. Der 5V und Masseanschluß GND des Arduinos ist ebenfalls mit dem Selbstbauprogrammer zu verbinden.



Um die Firmware für den Programmer zu flashen wechselt man in das Verzeichnis /home/mcu/ch32v003/rvswdio_programmer und startet dort erst make und anschließend make flash:

      cd /home/mcu/ch32v003/rvswdio_programmer
      make

      riscv-none-elf-gcc -E -P -x c -DTARGET_MCU=CH32V003 -DMCU_PACKAGE=1 -DTARGET_MCU_LD=0 -DTARGET_MCU_MEMORY_SPLIT= ../ch32fun//ch32fun.ld > ../ch32fun//generated__.ld
      riscv-none-elf-gcc -o rvswdio_programmer.elf ../ch32fun/ch32fun.c rvswdio_programmer.c ./src/rv003usb.S ./src/rv003usb.c -g -Os -flto -ffunction-sections -fdata-sections -fmessage-length=0 -msmall-data-limit=8 -march=rv32ec -mabi=ilp32e -DCH32V003 -static-libgcc -I/usr/include/newlib -I../ch32fun//../extralibs -I../ch32fun/ -nostdlib -I. -Wall -I ./ -I ./include -Wl,--print-memory-usage -Wl,-Map=rvswdio_programmer.map -L../ch32fun//../misc -lgcc -lgcc -T ../ch32fun//generated__.ld -Wl,--gc-sections 1>&2
      Memory region Used Size Region Size %age Used
          FLASH: 8944 B 16 KB 54.59%
            RAM: 416 B 2 KB 20.31%
      riscv-none-elf-objdump -S rvswdio_programmer.elf > rvswdio_programmer.lst
      riscv-none-elf-objcopy -O binary rvswdio_programmer.elf rvswdio_programmer.bin
      riscv-none-elf-objcopy -O ihex rvswdio_programmer.elf rvswdio_programmer.hex

      make flash


Da der Arduinoprogrammer sehr sehr langsam ist, wird der Flashvorgang ca. 40 Sekunden dauern. Während dieser Zeit werden (leider) keine Bildschirmausgaben gemacht und es muß einfach auf das Ende des Flashvorgangs gewartet werden.

Nach Beendigung des Flashvorgangs ist es geschafft und der Programmer ist betriebsbereit, sofern keine Fehler aufgetreten sind und der Hardwareaufbau ebenso fehlerfrei ist.

Nach dem Anschließen des Programmers an einen USB-Port kann überprüft werden, ob der Programmer sich auch am USB anmeldet. Hierfür gibt man in der Konsole ein:

      lsusb


Der PC listet nun alle am Computer angeschlossenen USB Devices auf. Je nach Version von lsusb werden zu den PID und VID Adressen auch Klartextnamen mit angezeigt. Wichtig hier ist jedoch nur, dass die Adressen des Programmers (ID 1206:5D10) auch aufgelistet sind.



        Der Programmer ist einsatzbereit :-)