In a recently arrived package from Seeed Studio there was a Wio Lite RISC-V WiFi module. This board uses the same 32-bit GD32VF103CBT6 core as used on the Longan Nano by Sipeed. There is an additional ESP8266 Wio Core for Wi-Fi connectivity.
Table of Contents
- Wio Lite RISC-V WiFi
- PlatformIO Only
- Compiling Blink
- Installing the Latest
- Uploading With USB (DFU)
- Adding Serial Output
- Downloading the Example Blink Projects
The Wio Lite RISC-V is a development board based on a 32-bit GD32VF103CBT6 core by GigaDevice and a ESP8266 Wio core. It resembles a wasp with the ESP8266 being the thorax and a Feather form-factor abdomen carrying the RISC-V processor. Through holes for standard 0.1" headers along the long edges of the abdomen are connected to the RISC-V core. The distance between the headers is breadboard compatible. In keeping with the Feather standard, there is a JST2.0 Lipo battery port on the top side. Its presence means that header pins should be soldered on the bottom side of the board as done with other Feather boards. Hopefully the micro SD slot on the bottom side will not be in the way. There is a provision for a JTAG connector on the abdomen near the waist and through holes for a Wio Core I/O header are situated above the waist. Since the latter are not breadboard compatible, any installed connector or header should be soldered on the top side. The USB-C connector is used to power the device and to upload new firmware.
The 108 MHz, 32 bit, GD32VF103CBT6 has impressive capabilities.
- 128 K bytes of Flash memory
- 32 K bytes of RAM
- 2 ADC (12 bit, 10 channels)
- 2 DAC (12 bit)
- 7 timers (16 bit) of varying capabilities
- a watchdog, a real-time counter/clock (??)
- 3 USART
- 2 I2C
- 3 SPI
- 2 I2S
- 2 CAN
- 1 USB OTG
The Wio Core "can be considered equivalent to [the] ESP-WROOM-02 except that the original firmware is replaced with [Wio platform] firmware."
So far, I have not seen an official pinout. Here is my poor attempt at documenting the connections on the board based on the schematic and the GD32VF103 Datasheet (rev 1.1). Imagine that the board is in the narrow white column in the centre, with the USB-C connector visible and at the bottom (as shown in the left photograph above). The header numbers correspond to the numbering on the schematic and follow the convention of assigning the number 1 to the pin with the square solder mask. The labels with the green background next to the pin numbers are those printed on the board. Basically they are the pin name and default function of the corresponding core pins as described in section 2.6.3 GD32VF103Cx pin definitions of the data sheet. The labels with the white background are those found on the schematic. The Function column gives the alternate function description of the pin, any function after a ";" is a remap function (whatever that means, I obviously have a lot to learn).
|Wio Lite RISC-V WiFi|
|Function (alternate; remap)||Schematic||Headers||Schematic||Function (alternate; remap)|
|I2C1_SDA, USART2_RX; TIMER1_CH3||PB11_SDA||PB11||12||1||RST||MCU_NRST||Reset|
|I2C1_SCL, USART2_TX; TIMER1_CH2||PB10_SCL||PB10||11||2||3V3||3.3 volt|
|I2C0_SDA, TIMER3_CH1; USART0_RX||PB7_D5||PB7||10||3||VDDA||VDDA|
|USART0_CK, TIMER0_CH0, CK_OUT0, USBFS_SOF||PB8_D6||PB8||9||4||GND||Ground|
|I2C0_SMBA, SPI2_MOSI, I2S2_SD; TIMER2_CH1, SPI0_MOSI, CAN1_RX||PB5_D9||PB5||8||5||PA0||PA0_A0||WKUP, USART1_CTS, ADC0_IN0; TIMER1_CH0_ETI, TIMER4_CH0|
|ADC01_IN9, TIMER2_CH2; TIMER0_CH1_ON||PB0_D10||PB0||7||6||PA1||PA1_A1||USART1_RTS, ADC01_IN1, TIMER4_CH1, TIMER1_CH1|
|SPI1_NSS, I2S_WS, I2C1_SMBA, USART2_CK, TIMER0_BRKIN, CAN1_RX||PB12_D11||PB12||6||7||PA4||PA4_A4||SPI0_NSS, USART1_CK, ADC01_IN4; SPI2_NSS, I2S2_WS|
|I2C0_SCL, TIMER3_CH0; USART0_TX, CAN1_TX||PB6_D12||PB6||5||8||PA5||PA5_A5||SPI0_SCK, ADC01_IN5, DAC_OUT1|
|TIMER3_CH3; I2C0_SDA, CAN0_TX||PB9_D13||PB9||4||9||PA6||PA6_A6||SPI0_MISO, ADC01_IN6, TIMER2_CH0; TIMER0_BRKIN|
|5 volt||5V||3||10||PA7||PA7_A7||SPI0_MOSI, ADC01_IN7, TIMER2_CH1; TIMER0_CH0_ON|
|Ground||GND||2||11||PB13||PB13_SPI1_SCK||SPI1_SCK, I2S1_CK, USART2_CTS, TIMER0_CH0_ON, CAN1_TX|
|MCU_VBAT||VBAT||1||12||PB15||PB15_SPI1_MOSI||SPI1_MOSI, TIMER0_CH2_ON, I2S1_SD|
|13||PB14||PB14_SPI1_MISO||USART0_CK, TIMER0_CH0, CK_OUT0, SPI1_MOSI, TIMER0_CH2_ON, I2S1_SD|
|14||PA10||PA10_UART0_RX_D0||USART0_RX, TIMER0_CH2, USBFS_ID|
|15||PA9||PA9_UART0_TX_D1||USART0_TX, TIMER0_CH1, USBFS_VBUS|
The blue LED beside the USB-C connector and below the reset push button switch is connected to pin PA8 and is active high. Pins PA11 and PA12 are connected to the D- and D+ USB data lines. The SD-card slot is connected with SPI bus 1. As far as I can determine, the only connection between the RISC-V core and the ESP core is through a two wire serial connection, USART1 (RX = PA3, Tx = PA2) on the RISC-V side.
The Wio Lite RISC-V WiFi is quite new. There is no support for the board in the Arduino IDE. Indeed, I have yet to get the GD32V board cannot get the board. Furthermore, I cannot find much information about it on the Web, and the vendor does make it clear that the PlatformIO environment is the only currently available playground.
Since it uses the same microprocessor as the Sipeed Longan Nano, I assumed that programming it would be relatively similar. Indeed, I managed to upload a blink firmware to the device. The sketch was written for the Arduino framework in PlatformIO on a Linux desktop. In the following discussion on how to proceed, it will be assumed that PlatformIO (PIO for short) is installed and working properly on the desktop, but if not, here are the installation instructions.
Just started a new project
- If PIO Home is not open, click on the PIO icon on the left edge,
QUICK ACCESS/PIO Home/Openin the
PLATFORMIO LISTin the left panel.
- Click on
+ New Projectin the PIO Home page.
Project Wizard window will pop up.
- Set the project name. I chose
- Select the board. I entered "Wio" in the box and then scrolled down the list of boards with "Wio" somewhere in their name.
Wio Lite RISC-V (SeeedStudio).
- Change the framework from
GigaDevice GD32V SDKto
- Click on the button.
PIO will obtain the platform toolchain and set up the project as a directory with assorted subdirectories all shown in the EXPLORER panel on the left.
- Click on the
srcdirectory and then on the
main.cppfile name in the EXPLORER panel.
- The typical bare source template will be displayed in the
main.cpptab. Replace the bare
loop()functions with those in the standard Arduino Blink sketch. Do not remove the
#include <Arduino.h>directive at the top of the file; it is necessary in PlatformIO when using the Arduino platform, it is implicit in the Arduino IDE. Note that I shortened the LED on time by an order of magnitude for a reason to be explored below.
- Click on the
PlatformIO: Buildicon. It is the check mark on the tool bar along the bottom of the application window.
If everything worked, then success should be reported as shown below.
However at the time of writing this post, the build fails because of a missing variant
I have found two ways to solve this problem which hopefully will be resolved quickly.
- Click on
EXPLORERpanel. (If the panel is not visible, click on the "sheets of paper" icon below
Fileor use the CtrlShiftE keyboard shortcut).
- Change the board definition to
board = gd32vf103v-eval.
main.cppadd the following line above the
#define LED_BUILTIN PA8
- Compile the project and this time it should work.
sipeed-longan-nano board definition, the I/O pin names such as PA9 will work correctly because all three boards use the same GD32VF103 chip. However the on board LEDs are connected to different I/O pins. That is why it was necessary to redefine LED_BUILTIN in
main.cpp. The compiler will complain, but it will work.
I will not go into the details.
- If it does not exist, create a subdirectory named
~/.platformio/packages/framework-arduino-gd32v/variants/.; PlatformIO Project Configuration File ; ; Build options: build flags, source filter ; Upload options: custom upload port, speed and extra flags ; Library options: dependencies, extra library storages ; Advanced options: extra scripting ; ; Please visit documentation for the other options and examples ; https://docs.platformio.org/page/projectconf.html [env:wio_lite_risc-v] platform = gd32v ;board = wio_lite_risc-v board = gd32vf103v-eval framework = arduino
- Copy the missing files
pins_arduino.cwhich can be found in Longuino GitHub repository into
- Compile the project and this time it should work.
Presumably, the missing variant files will be added in the repository. I have attempted to use the upstream development platform with no success. PlatformIO documentation on the Wio Litd RISC-V board says "Please use wio_lite_risc-v ID for [the] board option", which is why this solution may be better in the long run. However, I hope that meddling in the gd32v package will not be the cause of problems when it is updated.
Now there remained the task of uploading the binary to the Wio.
If you have already uploaded firmware to a GD32VF103 based board such as the Sipeed Longan Nano, then you can skip this section.
As far as I can ascertain, it is not possible to upload with a serial connection. Instead the DFU (Device Firmware Upgrade) protocol will be used to upload the firmware over the USB connection. As far as I know, dfu-util is the only way to support this mechanism on a desktop running Linux. Unfortunately, the version of the utility that is installed with GD32V package in PIO is not up to date and it will not work. I tried installing the package available in the Ubuntu repository
It certainly looked recent enough, but it would not work. It is necessary to build
dfu-utils from the source. Again following advice found on the Web, I tried the gd32-dfu-utils which is supposed to be a fork of
dfu-utils that added GD32VF103 support without success. The same type of error occured when trying with a more recent fork of the fork. In the end what worked was the latest version of
dfu-utils on SourceForge. I followed the instructions by dr-br to download and compile the latest version of
configure command given had been ./configure --prefix=$HOME as suggested by dr-br, the utilities would have ended up in a
~/bin which is not in the search path on my system. I checked that the utility was installed in my
I copied those three
dfu-* files in
/.local/bin/ on top of the files in
The project configuration file
platformio.ini should have the following content.
In other words, add
upload_protocol = dfu to the configuration file. Note that I am using the "better fix" for the missing variant files.
Connect the USB-C cable to the desktop and the Wio, slide the
BOOT0 switch towards the battery connector and press the reset button across from the connector. The board is now in download mode. Before uploading the firmware, it is not a bad idea to check that the Wio now shows up as an anonymous USB device with ID 28e9:0189 and to check that there is a
UDEV rule for the device. You can even check that the installed
dfu utility recognizes the Wio.
Click on the
PlatformIO: Upload icon on the tool bar along the bottom of the application window. You will probably see something contradictory like this.
PIO gave an even scarier FAILED message, but the new firmware was uploaded to the Wio. Change the LED frequency, press on the reset and upload the firmware to the Wio again just to confirm that the new firmware was installed.
Do not forget to slide the
BOOT0 switch back up towards the
BOOT0 label. Otherwise when the board is powered up in the future, it will appear to be defective while it is merely waiting for new firmware as it will be in download mode.
It is not too difficult to output text to the terminal, but the
Serial class used in Arduino to do this is not available. Instead, USART0 will be initialized explicitly and output to the terminal will be through
printf which by default sends its ouyput to the UART. The source for this is a Sipeed documentation page entitled UART. The document is not available in English, so thank you Google translate.
platformio.ini configuration file by adding the baud of the serial connection.
Upload the firmware to the Wio as describe above. Do not forget to return the
BOOT0 switch away from the battery connector.
To see the output it will be necessary to connect a USB to TTY (3.3 volt) converter to the Wio. Do this with the USB-C cable disconnected, and the USB - TTY converter not connected to the desktop. USB to TTY converters that support both 3.3 and 5 volts, select 3.3 volts. Do not use a 5 volt converter. Make sure your converter will output 3.3 volt signals otherwise the Nano will be damaged. Finally, connect the converter Rx pin to the USART0_TX pin of the Wio which is pin PA9 (physical pin 15). The next pin (physical pin 16, the last pin beside the reset button) is the ground pin which has to be connected to the ground pin of the converter. Connect the USB-C cable and the USB end of the USB - TTY converter to the desktop.
The output will be sent to the serial port just as soon as power is the firmware is uploaded. If the terminal is not visible then click on the PlatformIO: Serial Monitor icon, which looks like a 2 prong plug facing up on the bottom tool bar. To view the beginning of the output, press on the RESET button on the Wio.
Three Blink projects can be downloaded with the following links.
- nanoblink.zip: simple LED blink.
- nanoblink2.zip: LED blink with serial output.
- nanoblink3.zip: LED blink with Serial object.
Just extract the content of the archive somewhere in the PlatformIO projects directory. Here is one way to do it in Linux.
Note that I decided to put the
wioblink example project in a subdirectory, called
wio_risc-v, of the PlatformIO project directory. The
-p option of the
mkdir command creates all needed directories along the specified path. In other words, it created directory
wio_risc-v before creating
blink1 inside of it.
To start using a downloaded project
- Click on the Open Project button in the PIO Home page
- Click on the
Projectsfolder in the Places section of the Favorites panel
- Navigate to the desired project directory such as
- Click on the button.
The project can now be compiled.
There will not be a next step until work on the Wio platform is updated. Right now, the example code showing how to communicate with the ESP8266 does not compile. Now that's ok, because the same package that brought me this module included a Longan Nano, which I have already written about and a Seeeduino XIAO about which a post will be available shortly.