General

The front-end of the development environment is Visual Studio Code (VSC). If you do not already have it installed on your computer, install it!

The development effort needs a so called cross compiler, that generates code for the target device instruction set architecture (isa) and not the host computers isa. The following steps is required to install the cross-compiler and configuration files that are needed for the gd32v MCU.

After the final step, you should be able to compile and download, the "Blinky" main.c application that is included in the template project. If the on board LEDs starts to blink after running a download cycle the development environment successfully installed.

For support, please e-mail Linus (remahl@kth.se)

Step #1: Download target cross-compiler and templates...

toolchain gd32v (232MB) (Links to an external site.) MacOS

toolchain gd32v (232MB) (Links to an external site.) Linux

toolchain gd32v (232MB) (Links to an external site.) Windows

Extract the package somewhere you can easily find it, for example in your documents folder.

Step #2: MacOS only; Install Command line tools and dfu-tool

Check if you have command line tools already installed: Open terminal and type;

gcc -v

If the command is not recognized, type:

xcode-select --install

Then install homebrew (if you do not have it already), type:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Finally install the dfu utility, type:

brew install dfu-util

Step #2: Windows only; Install Mingw make and USB driver

Step #2.1: Install Mingw make

Check if you have mingw-make already installed: If the file “mingw32-make” is present in directory “C:\mingw\bin” then skip the remaining part of 2.1 and go directly to step 2.2!

You can find the file “mingw32-make-3.80.0-3.exe” in the folder downloaded through step #1: double click on it and follow the instructions, and make a note on the path to the chosen installation directory (default is “C:\mingw\”)

Open the windows start menu and select: “Edit the system environment variables”/”Redigera Systemets Miljövariabler”.

Then select: “Environment variables...”/”Miljövariabler...”

In the upper region of the pop-up window, choose the "path" variable and click "Edit".

Then hit “New”/”Ny”, followed by “Browse” and navigate to the previous chosen installation folder! (default: "C:\mingw\bin")

Click on "ok", and check that the window now contains a new row with the path to the selected installation folder.

Step #2.2: Install USB driver, part 1.

Your computer also needs a USB-driver to be able to download software to the target MCU.

Download the following executable, double-click on it and select "Install"!

GD32DFUDrivers.exe (7.1MB) (Links to an external site.)

Step #2.3: Install USB driver, part II (you must have an mcu-card to do this!)

To complete the usb driver installation you will also need to download the following executable:

Zadig 2.5 (4.9MB)

Start the downloaded executable and select [options] -> [List all devices] from the drop down menu.

zadig1

Then connect the card while pressing the "BOOT"-button. Once the card is connected you can release the button.

In the drop down menu there should have appeared a new empty row. (In some cases it may also be named "GD32 Device in DFU Mode". Click on that row.

zadig2

If the row is empty press the "Edit"-checkbox (1) and paste in "GD32 Device In DFU Mode" (2).

Then carefully check that the values in the box marked 3 corresponds EXACTLY to the picture below, if the numbers aren't

USB ID: 28E9 0189 then start this step over from 2.3. If you cannot get the correct device to show up then it's best to message me for help with installing.

If (and only if) the numbers are all correct you can now press "Replace Driver". (4)

replace driver

Step #3: Create a new project

Use your computers file browser to move to the directory "projects" in the package you downloaded in step #1.

Each time you need to make a new project: Make a copy of the entire folder/directory "template" and rename it to something useful. The new directory should always be located in the projects directory, otherwise compilation will not work.

Next start VSCode and choose File→Open folder and navigate to .../projects/[your new projects name].

Step #4: Compile and download

To compile press in the top menu on: [Terminal]→ [New Task…] and select lio make [project name]

The MCU must be set in boot loader mode to accept a new program:

Press "boot", and while holding "boot" down press and release "reset", then finally release "boot"

To compile and download: [Terminal]→ [New Task…] and select lio make dfu [project name]

Step #5: MacOS only; Security issue.

Installing the compiler on macOS can be a bit tedious because the compiler runs a lot of different programs and each one needs to be allowed to run. This means that to enable the full toolchain you will need to run lio make multiple times, and on each new run allow a new part pf the toolchain.

The process is as follows:

Run "lio make"

A popup will appear asking "Move to recycling bin" or "Cancel" press cancel.

Go into settings->Security & Privacy->general and press the "Allow anyway" button in the lower right corner.

Repeat until no more popups appear.