{"id":20536669,"url":"https://github.com/islandcontroller/hello-ch32v003","last_synced_at":"2025-10-26T01:36:45.651Z","repository":{"id":153360549,"uuid":"617178773","full_name":"islandcontroller/hello-ch32v003","owner":"islandcontroller","description":"A simple \"Hello World\"-like project for the ultra low-cost WCH CH32V003 RISC-V MCU ","archived":false,"fork":false,"pushed_at":"2025-07-27T01:17:03.000Z","size":372,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-25T15:43:02.270Z","etag":null,"topics":["ch32v003","hello-world","openwch","risc-v"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/islandcontroller.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-03-21T21:12:46.000Z","updated_at":"2025-07-27T01:17:06.000Z","dependencies_parsed_at":"2023-11-12T16:24:58.017Z","dependency_job_id":"fc4f0660-3a7e-469e-942c-76b664066d80","html_url":"https://github.com/islandcontroller/hello-ch32v003","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/islandcontroller/hello-ch32v003","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/islandcontroller%2Fhello-ch32v003","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/islandcontroller%2Fhello-ch32v003/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/islandcontroller%2Fhello-ch32v003/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/islandcontroller%2Fhello-ch32v003/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/islandcontroller","download_url":"https://codeload.github.com/islandcontroller/hello-ch32v003/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/islandcontroller%2Fhello-ch32v003/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281047794,"owners_count":26435124,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-25T02:00:06.499Z","response_time":81,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ch32v003","hello-world","openwch","risc-v"],"created_at":"2024-11-16T00:37:28.000Z","updated_at":"2025-10-26T01:36:45.629Z","avatar_url":"https://github.com/islandcontroller.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hello-ch32v003 [![GitHub license](https://img.shields.io/github/license/islandcontroller/hello-ch32v003?style=flat-square)](LICENSE) [![Discord server link](https://img.shields.io/badge/discord-WCH%20Community-white?style=flat-square\u0026logo=discord)](https://t.co/Qbblvmfbae) [![Discord server link](https://img.shields.io/badge/GitHub-template--ch32v003-white?style=flat-square\u0026logo=github)](https://github.com/islandcontroller/template-ch32v003)\n\nA simple \"Hello World\"-like project for the ultra low-cost WCH CH32V003 RISC-V MCU.\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"scr.png\" /\u003e\u003c/p\u003e\n\nThis project contains a simple set of modules to get the MCU running in a minimal configuration:\n  - Serial I/O on USART1 (connected to WCH-LinkE USART)\n  - TIM1 Channel 3 configured for PWM output to LED\n  - SysTick enabled and using auto-reload feature\n  - I2C1 interface with 24C64 EEPROM read and write access\n\n**Project template available here: [`template-ch32v003`](https://github.com/islandcontroller/template-ch32v003)**\n\n## Requirements\n\n* Hardware\n  * WCH CH32V003F4P6-EVT+WCH-LinkE Starter Kit (available from LCSC, [PartNr `C5236707`](https://www.lcsc.com/product-detail/Microcontroller-Units-MCUs-MPUs-SOCs_WCH-Jiangsu-Qin-Heng-CH32V003F4P6-EVT-WCH-LinkE_C5236707.html))\n    * Starter Kit includes WCH-LinkE Debugger\n  * 6 pcs. female-female jumper wires\n  * (optional) additional 1 pc. female-female jumper wire for LED demo\n  * (optional) AT24C64 EEPROM IC + Solderless breadboard + 2x 10k Resistors\n* Software\n  * Linux OS or WSL installation\n  * [Docker Engine](https://docs.docker.com/engine/install/debian/) (running within WSL if applicable)\n  * VSCode [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension\n  * (WSL only) [usbipd-win](https://learn.microsoft.com/en-us/windows/wsl/connect-usb)\n\n### Hardware Setup\n\n* (optional) Connect the `LED1` and `PC3` pins on header `P2` using a female-female jumper wire\n* Follow instructions from the [WCH-LinkE User Manual](http://www.wch-ic.com/downloads/WCH-LinkUserManual_PDF.html) for connecting the debugger to your EVT board.\n\n| WCH-LinkE Pin | EVT Board Pin |\n|---------------|---------------|\n| `RST`         | `NRST / PD7`  |\n| `3V3`         | `VCC` (*)     |\n| `GND`         | `GND`         |\n| `SWDIO/TMS`   | `PD1`         |\n| `TX`          | `PD6`         |\n| `RX`          | `PD5`         |\n\n*) For powering the target from your WCH-LinkE debugger. Omit this if you want to power the EVT board via its own USB port.\n\n## EEPROM Hardware Setup (optional)\n\n* Connect the `LED1` and `PA6` pins on header `J3` using a female-female jumper wire\n* Connect the 24C64 EEPROM to `PB10` and `PB11` and add 10k pull-up resistors to SDA and SCL:\n  ```\n       .___________.  VCC   VCC VCC       VCC  .________________\n      1|    |_|    |8  |     |   |         |   |\n   +---| A0    VCC |---+    .|. .|.        +---| VCC (3V3)\n   |  2|           |7       | | | | R1,R2      |\n   o---| A1     WP |---+    |_| |_| 10k    +---| GND\n   |  3|           |6  |     |   |         |   |\n   o---| A2    SCL |---(-----o---(---------(---| PC2 (I2C1_SCL)\n   |  4|           |5  |         |         |   |\n   o---| GND   SDA |---(---------o---------(---| PC1 (I2C1_SDA)\n   |   |___________|   |                   |   |________________\n  GND  U2             GND                 GND  U1\n       AT24C64 (DIP8)                          CH32V003\n  ```\n\n### **Note**\n\nIf you want to use the EEPROM demo, remove the comment at the start of the `#define USE_EEPROM_DEMO` line at the top of `main.c`. The demo is disabled by default.\n\n## Usage\n\n* Clone this repository using the following command. Note the use of the `--recursive` tag.\n  ```\n  git clone --recursive https://github.com/islandcontroller/hello-ch32v003\n  ```\n* Open the folder in VSCode\n* Connect WCH-Link debug probe\n  * (WSL only) attach to WSL using `usbipd attach --wsl --busid \u003c...\u003e`. **This needs to be completed before starting the Dev Container.**\n* Run the command \"**Dev Containers: Reopen in Container**\"\n  * On first launch, you may need to install some udev rules on your host machine. Copy the files to your workspace by running `setup-devcontainer` inside the container.\n  * Re-open the workspace on your host and run the `install-rules` script inside the `.vscode/setup` folder.\n\n        cd .vscode/setup\n        sudo ./install-rules\n\n  * Afterwards, restart the devcontainer.\n* Upon prompt, select the \"`WCH RISC-V Toolchain x.x`\" CMake Kit. \n* Run \"**CMake: Configure**\"\n* Build using \"**CMake: Build [F7]**\"\n\n* Split the terminal tab using the `[|]`-Button or press `Ctrl + Shift + 5`. Then launch the serial monitor:\n\n      cu -l /dev/ttyACM0 -s 115200\n\n  **To close the connection later on, press ESC/ENTER, type `~.` (tilde, dot) and wait for 3 seconds.**\n\n* Start debugging using \"**Debug: Start Debugging [F5]**\"\n* Continue execution once the breakpoint in `main()` is reached.\n* Type `?` in the serial monitor Terminal tab to show available commands.\n\n## WCH-LinkE Firmware Update\nA firmware update of the WCH-LinkE debug probe to version `v31` or newer may be necessary. Use the [WCH-LinkUtility](https://www.wch.cn/downloads/WCH-LinkUtility_ZIP.html) to perform an online update of the programmer, as described in section 6.2 \"*WCH-LinkUtility Online Update*\" of the [WCH-Link User Manual](https://www.wch.cn/downloads/WCH-LinkUserManual_PDF.html).\n\n* Pry open the clear case of the WCH-LinkE using a small flat-head screwdriver\n* Push and hold the \"IAP\" button and insert the debugger into a USB port\n* Start the `WCH-LinkUtility.exe`\n* Confirm installation of the required drivers\n* Click the \"Query Read-Write-Protect Status\" button (Alt + F5)\n\nIf a firmware update is available, a pop-up window will appear, asking you to confirm the update.\n\n## SOIC8 Pin Mapping and \"un-bricking\"\nOn the SOIC8 package `CH32V003J4M6`, the debug interface is multiplexed with USART1 data lines. In the default configuration, enabling the UART transmitter will block debugger access. To use both USART1 and the debug port, **un-comment the `USE_SOIC8_UART_REMAP`** macro definition in `hw_layer/hw_iodefs.h`. Use the following table for connecting the debug probe to the SOIC8 part:\n\n|WCH-LinkE Pin|SOIC8 Pin|\n|-|-|\n|`3V3`|4 `VDD`|\n|`GND`|2 `VSS`|\n|`SWDIO`|8 `PD1/PD5/PD4` (*)|\n|`TX`|8 `PD1/PD5/PD4` (*)|\n|`RX`|1 `PD6`|\n\n*) **Note:** *WCH-LinkE `TX` and `SWDIO` lines are connected to the same pin at the SOIC8 part!*\n\nIn order to use the USART pin, close the debug connection (OpenOCD) in software. This releases the SWDIO line to a high-impedance state.\n\n### Un-bricking an SOIC8 part\nIf an SOIC8 part has been programmed without swapping the RX/TX lines, debugger access is no longer possible. A full chip reset is required. Use the included `wlink` utility to perform the reset:\n\n    wlink erase --method power-off --chip ch32v003\n\n#### WCH-LinkUtility\nOn a Windows system, you can use the [WCH-LinkUtility](https://www.wch.cn/downloads/WCH-LinkUtility_ZIP.html) to perform a full chip reset:\n\n* MCU Core: `RISC-V`\n* Series: `CH32V00x`\n* Target -\u003e \"Clear All Code-Flash-By Power Off\"\n\n## Licensing\n\nIf not stated otherwise in the specific file, the contents of this project are licensed under the MIT License. The full license text is provided in the [`LICENSE`](LICENSE) file.\n\n    SPDX-License-Identifier: MIT\n\n## Help and References\n\n* [openwch/ch32v003](https://github.com/openwch/ch32v003) Manufacturer EVT demos and documentation\n* [WCH-IC: CH32V003DS0.pdf](http://www.wch-ic.com/downloads/CH32V003DS0_PDF.html) MCU Datasheet\n* [WCH-IC: CH32V003RM.pdf](http://www.wch-ic.com/downloads/CH32V003RM_PDF.html) MCU Reference Manual\n* [WCH-IC: QingKeV2_Processor_Manual.pdf](http://www.wch-ic.com/downloads/QingKeV2_Processor_Manual_PDF.html) Processor Core Manual\n\nIf you're looking for further information about WCH products, check out their community Discord server: \n[![Discord server link](https://img.shields.io/badge/discord-WCH%20Community-white?style=flat-square\u0026logo=discord)](https://t.co/Qbblvmfbae)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fislandcontroller%2Fhello-ch32v003","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fislandcontroller%2Fhello-ch32v003","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fislandcontroller%2Fhello-ch32v003/lists"}