Sipeed Longan Nano using Visual Studio Code and PlatformIO and upload to development board.
Information
none
Operating system used
Windows 10 Pro
Procedure
- Sipeed Longan GD32VF103CBT6 MCU Nano RISC-V Development Board (LCD screen is optional)
- USB A - USB C cable
- Install Visual Studio Code.
https://code.visualstudio.com/
Download and install VSCodeUserSetup-x64-1.59.1.exe
- Change Color Theme (Optional)
Select in left menu: Manage (Cog wheel)
Color Theme: Monokai
- Select in left menu: Extensions
- Install several extensions:
Note: Search the extensions by entering its name in the Search box.
- C/C++ (C/C++ IntelliSense, debugging, and code browsing.)
- vscode-icons (Icons for Visual Studio Code)
- vscode-pdf (Display pdf file in VSCode.)
- PlatformIO IDE (Professional development environment for Embedded, IoT, Arduino, CMSIS, ESP-)
- Restart Visual Studio Code.
- Start PIO Home:
- Select in left menu PlatformIO (Ant/Alien icon)
- Select: New Terminal
- In the terminal window type: pio platform install gd32v
The release version (stable version) will be installed.
If you want to install the development version (latest version), type: pio platform install https://github.com/sipeed/platform-gd32v
- Select menu: PIO Home | Open
Select: Project Examples
- Import project example:Arduino blink
- Modify platformio.ini
[env:sipeed-longan-nano]
;Platform, choose gd32v
platform = gd32v
;Optional gd32vf103-sdk or arduino
framework = arduino
;Development board
board = sipeed-longan-nano
;Serial monitor baudrate
monitor_speed = 115200
;Download tool Default serial port, optional jlink, gd-link, dfu, etc.
upload_protocol = serial
- Build code.
Terminal output: build_serial_sipeed_longan_arduino_blink.txt
- There are several methods to upload the compiled Blink program to the Sipeed Longan Nano Development Board.
I will demonstrate 4 methods A, B, C and D.
- Method A: Using a USB-A - Mini USB-B cable (upload_protocol = serial), a FTDI FT232RL adapter and PlatformIO to upload the firmware.
- Method B: Using a USB-A - USB-C cable (upload_protocol not used), and "GD32 Dfu Tool" to upload the firmware.
- Method C: Using a USB-A - USB-C cable (upload_protocol = sipeed-rv-debugger), the Sipeed RV Debugger Plus and PlatformIO to upload the firmware.
- Method D: Using a USB-A - USB-C cable (upload_protocol = dfu) and PlatformIO to upload the firmware.
Method A: Using a USB-A - Mini USB-B cable (upload_protocol = serial), a FTDI FT232RL adapter and PlatformIO to upload the firmware.
Top view
The VCC pin can output 3.3V or 5.0V depending on how you set the jumper.
Set the jumper to 3.3V.
The FTDI adapter itself is powered (5V) by the USB-A -> mini USB-B cable.
Bottom view
- Jumper wires 15 cm long (4x female-female), the photo shows 6 wires!
I only need 4 jumper wires to connect the FTDI adapter to the Sipeed Longan Nano Development Board.
Connect the FTDI FT232RL (on the left) to the Sipeed Longan Nano Development Board (on the right) using jumper wires.
FTDI FT232RL adapter (Only pins RX, TX, VCC and GND are used)
Sipeed Longan Nano Development Board (Only pins TO, RO, 3V3 and GND are used)
| DTR (Not connected) |
- |
| RX |
TO |
| TX |
RO |
| VCC |
3V3 |
| CTS (Not connected) |
- |
| GND |
GND |
- Connect the FTDI FT232RL adapter to the computer using an USB 2.0 cable, USB-A > Mini USB-B (length: 80 cm)
Another photo. The Sipeed Longan Nano with the TFT display connected to the FTDI FT232RL adapter.
- When the FTDI FT232RL adapter is plugged into the computer, Windows 10 pro does not detects the FTDI FT232RL adapter.
You need to install a Virtual COM port (VCP) driver.
Virtual COM port (VCP) drivers cause the USB device to appear as an additional COM port available to the PC. Application software can access the USB device in the same way as it would access a standard COM port.
The VCP Drivers, can be found at:
https://ftdichip.com/drivers/vcp-drivers/
I downloaded the setup_executable file (CDM212364_Setup.zip) and executed CDM212364_Setup.exe to install the Virtual COM port (VCP) driver.
- Install FTDI CDM drivers.
- The Windows Device Manager (devmgmt.msc) automatically detects which COM port is being used when the FTDI FT232RL adapter is plugged in.
- When using the FTDI FT232RL adapter, the platformio.ini file will look like:
[env:sipeed-longan-nano]
platform = gd32v
framework = arduino
board = sipeed-longan-nano
monitor_speed = 115200
upload_protocol = serial
Note 1: The USB-C connector on the Sipeed Longan Nano Development Board is not connected to anything.
The FTDI FT232RL adapter provides power (3.3V) to the Sipeed Longan Nano Development Board.
Note 2: There is no need to specify the port by adding the following line in platformio.ini:
upload_port = COM4 (Depends which COM port the FTDI FT232RL adapter is connected to).
The COM port is auto detected.
- Set the Sipeed Longan Nano Development Board into download mode:
- Press BOOT key and keep it pressed.
- Shortly press and immediately release the RESET button.
- Then release the BOOT button.
The Sipeed Longan Nano Development Board is now set into download mode.
The preloaded Red-Green-Blue Led stopped blinking and only the power LED is on.
- Upload the Blink program to the development board.
Terminal output: upload_serial_sipeed_longan_arduino_blink.txt
- The Blink program is now running on the development board.
- When the upload_protocol = serial, the stm32flash.exe program is used to upload the firmware to the device.
A few examples how to use the stm32flash.exe program:
- Attach the Sipeed Longan Nano < - > FTDI FT232RL using the USB-A - Mini USB-B cable to computer.
- Set the Sipeed Longan Nano Development Board into download mode:
- Press BOOT key and keep it pressed.
- Shortly press and immediately release the RESET button.
- Then release the BOOT button.
- The stm32flash.exe is located at:
C:\Users\<user>\.platformio\packages\tool-gd32vflash
- The generated firmware.hex and firmware.bin are located at:
C:\Users\<user>\Documents\PlatformIO\Projects\<project>\.pio\build\sipeed-longan-nano
- To get device information:
Type: cd C:\Users\<user>\.platformio\packages\tool-gd32vflash
Type: .\stm32flash COM4
- To upload the firmware.bin to Sipeed Longan Nano device:
Type: .\stm32flash
-g 0x08000000
-b 115200
-w C:\Users\<user>\Documents\PlatformIO\Projects\<project>\
.pio\build\sipeed-longan-nano\firmware.bin COM4
Note: Instead of firmware.bin you can upload the firmware.hex with the same command as mentioned above.
More information about stm32flash.exe can be found at:
PlatformIO 2: Under the hood
Method B: Using a USB-A - USB-C cable (upload_protocol not used), and "GD32 Dfu Tool" to upload the firmware.
First connect the Sipeed Longan Nano Development Board to computer using the USB cable.
When the Sipeed Longan Nano Development Board is plugged into the computer using the USB-A - USB-C cable, Windows 10 pro does not detects the development board.
You need to install an driver.
- It is important to follow this procedure in the correct order:
- Goto http://www.gd32mcu.com/en/download/ (GigaDevice download section), and select GD32VF1 MCU.
Select Tab "Tool & Software".
Download "GD32 Dfu Drivers". I have downloaded GD32_Dfu_Tool_V3.8.2.9056.rar
Download "GD32 MCU Dfu Tool". I have downloaded GD32DfuDrivers_V3.6.6.6167.rar
- Unpack both rar files.
- Install the GD32DfuDriver (Please note: My computer has a 64-bit processor x64):
- Goto folder GD32DfuDrivers_V3.6.6.6167\x64
- Execute file GD32DfuDrivers.exe as Administrator.
- Start Windows Device Manager (devmgmt.msc) and check if the device is detected.
If the device is not detected:
- Press BOOT key and keep it pressed.
- Shortly press and immediately release the RESET button.
- Then release the BOOT button.
- The GD32DfuDriver is now installed and the Sipeed Longan Nano Development Board can now be detected.
The platformio.ini will look like this:
[env:sipeed-longan-nano]
platform = gd32v
framework = arduino
board = sipeed-longan-nano
monitor_speed = 115200
There is NO need to add the following line:
upload_protocol = dfu
in platformio.ini, because PlatformIO will not be used to upload the firmware.
- Start the GD32 MCU Dfu Tool.exe, the other rar was which unpacked.
If the pull down menu "DFU Device" is empty, set the Sipeed Longan Nano Development Board into download mode:
- Press BOOT key and keep it pressed.
- Shortly press and immediately release the RESET button.
- Then release the BOOT button.
... and restart GD32 MCU Dfu Tool.exe
- Build the Blink.cpp program.
The firmware file (firmware.hex) which will be uploaded to the development board is located at:
C:\Users\robertlie\Documents\PlatformIO\Projects\xxxxx-arduino-blink\.pio\build-sipeed-longan-nano
- In the GD32 MCU Dfu Tool, select the firmware.hex file and press the OK button to upload the firmware to the development board.
- Press the Reset button on the development board if the LED does not blink.
Method C: Using a USB-A - USB-C cable (upload_protocol = sipeed-rv-debugger), the Sipeed RV Debugger Plus and PlatformIO to upload the firmware.
I have written a separate tutorial, see:
Using Sipeed RV Debugger Plus to upload firmware and to debug code
Method D: Using a USB-A - USB-C cable (upload_protocol = dfu) and PlatformIO to upload the firmware.
First connect the Sipeed Longan Nano Development Board to computer using the USB cable.
When the Sipeed Longan Nano Development Board is plugged into the computer using the USB-A - USB-C cable, Windows 10 pro does not detects the development board.
You need to install a generic WinUSB driver using the Zadig program.
- Goto https://zadig.akeo.ie, download and install Zadig.
Zadig is a Windows application that installs generic USB drivers, such as WinUSB, libusb-win32/libus0_sys or libusbK.
I downloaded Zadig 2.5 (zadig-2.5.exe) but not started it yet!
- The Sipeed Longan Nano Development Board is connected to computer using the USB-A - USB-C cable.
Set the Sipeed Longan Nano Development Board into download mode.
- Press BOOT key and keep it pressed.
- Shortly press and immediately release the RESET button.
- Then release the BOOT button.
- Start Windows Device Manager (devmgmt.msc).
This is not required but it is useful to see what is happening.
You will see "Unknown device".
You may close or leave the Device Manager open.
- Start the Zadig executable. Select in the Zadig toolbar: Options | List All Devices
In the bottom left corner you will see how many USB devices it has found.
In this example there are 4 devices found.
- Select the EMPTY line. This represents the "Unknown Device".
Make sure USB ID = 28E9 0189 otherwise it is not the correct USB device.
Hardware ID USB\VID_28E9&PID_0189 is recognized as GD32 DFU Bootloader (Longan Nano).
Vendor Id = 28e9 (GDMicroelectronics)
Product Id = 0189 (GD32 DFU Bootloader, Longan Nano)
USB Vendor/Device IDs Database: http://www.linux-usb.org/usb.ids
- Make the following changes:
- Select WinUSB (vx.x.xxxx.xxxxx)
- Enable the Edit checkbox and enter an arbritrary name, for example: Sipeed Longan Nano
- Press Install Driver button.
- After the driver is installed, close the Zadig application. This application is not needed anymore.
Lets verify if the WinUSB driver is installed.
Start Windows Device Manager (devmgmt.msc)
You will see it has detected an USB device but it is an "Unknown device".
- Double click "Unknown device" and select tab Driver.
You will see Driver Provider: libwdi
- Press button Driver details. WinUSB is installed.
- Select tab Details, you will see the name you have entered: Sipeed Longan Nano.
- The WinUSB driver is now installed and the Sipeed Longan Nano Development Board can now be detected.
The platformio.ini will look like this:
[env:sipeed-longan-nano]
platform = gd32v
framework = arduino
board = sipeed-longan-nano
monitor_speed = 115200
upload_protocol = dfu
Set the Sipeed Longan Nano Development Board into download mode:
- Press BOOT key and keep it pressed.
- Shortly press and immediately release the RESET button.
- Then release the BOOT button.
- In file C:\Users\<user>\.platformio\platforms\gd32v\builder\main.py, dfu-util is mentioned.
elif upload_protocol == "dfu":
hwids = board.get("build.hwids", [["0x0483", "0xDF11"]])
vid = hwids[0][0]
pid = hwids[0][1]
_upload_tool = join(platform.get_package_dir(
"tool-dfuutil") or "", "bin", "dfu-util")
_upload_flags = [
"-d", "%s:%s" % (vid.split('x')[1], pid.split('x')[1]),
"-a", "0", "--dfuse-address",
"%s:leave" % board.get("upload.offset_address", "0x08000000"), "-D"
]
See also:
https://github.com/sipeed/platform-gd32v/tree/master/builder
The Vendor ID (vid) = 0x0483 and Product ID (pid) = 0xDF11 are both wrong.
You must change these to values in the main.py:
hwids = board.get("build.hwids", [["0x28E9", "0x0189"]])
The Vendor ID (VID) = 0x28E9 (GDMicroelectronics)
The Product ID (PID) = 0x0189 (GD32 DFU Bootloader, Longan Nano)
The combination vendor id and product id determines the device used.
A list of all USB Vendor/Product IDs:
http://www.linux-usb.org/usb.ids
- Build and upload the Blink program to the development board.
Terminal output (build): build_dfu_sipeed_longan_arduino_blink.txt
Terminal output (upload): upload_dfu_sipeed_longan_arduino_blink.txt
- The firmware is uploaded and the Blink program works correctly.
However I got a "bad page size" message and one error message during the upload:
Found GD32VF103, which reports a bad page size and count for its internal memory.
.. and ..
Error during upload get_status
*** [upload] Error 74
You can ignore both messages.
- In case you are curious, only for the "bad page size" I have found a quick and dirty solution.
It is caused by the dfu-util.exe program.
In PlatformIO, using the project wizard, the following choices were made:
Board: Sipeed Longan Nano
Framework: Arduino
The packages tool-dfuutil and tool-gd32vflash were installed and both packages contains the dfu-util.exe program.
But the package tool-gd32vflash contains a dfu-util.exe program modified specific for the GD32 microcontrollers.
By the way, for all projects, PlatformIO installs all frameworks and packages at Windows location:
C:\Users\<user>\.platformio\packages
To fix the "bad page size" message I replaced the tool-dfuutil\bin\dfu-util.exe with the tool-gd32vflash\dfu-util.exe.
*** WARNING ***
If your PlatformIO uses other devices which depends on the tool-dfuutil package it will of course generate errors after implementing this quick and dirty solution.
- The dfu-util (Device Firmware Update Utility) program is intended to download and upload firmware to/from devices connected over USB.
A few examples how to use the dfu-util.exe program:
- Attach the Sipeed Longan Nano using the USB-C cable to computer.
- Set the Sipeed Longan Nano Development Board into download mode:
- Press BOOT key and keep it pressed.
- Shortly press and immediately release the RESET button.
- Then release the BOOT button.
- The dfu-util.exe is located at:
C:\Users\<user>\.platformio\packages\tool-gd32vflash
- The generated firmware.hex and firmware.bin are located at:
C:\Users\<user>\Documents\PlatformIO\Projects\<project>\.pio\build\sipeed-longan-nano
- To check if the dfu-util.exe program can detect the Sipeed Longan Nano device:
Type: cd C:\Users\<user>\.platformio\packages\tool-gd32vflash
Type: .\dfu-util -l
- To upload the firmware.bin to Sipeed Longan Nano device:
Type: .\dfu-util
-d 28e9:0189
-a 0 --dfuse-address 0x08000000:leave
-D C:\Users\<user>\Documents\PlatformIO\Projects\<project>\
.pio\build\sipeed-longan-nano\firmware.bin
Note: Instead of firmware.bin you can upload the firmware.hex with the same command as mentioned above.
More information about dfu-util.exe can be found at:
PlatformIO 2: Under the hood
|
