¶ PROPRIETARY NOTICE
Copyright © Shanghai StarFive Technology Co., Ltd., 2021-2022. All rights reserved.
Information in this document is provided "as is," with all faults. Contents may be periodically updated or revised due to the product development. Shanghai StarFive Technology Co., Ltd. (hereinafter “StarFive”) reserves the right to make changes without further notice to any products herein.
StarFive expressly disclaims all warranties, representations, and conditions of any kind, whether express or implied, including, but not limited to, the implied warranties or conditions of merchantability, fitness for a particular purpose and non-infringement.
StarFive does not assume any liability rising out of the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation indirect, incidental, special, exemplary, or consequential damages.
All material appearing in this document is protected by copyright and is the property of StarFive. You may use this document or any part of the document for internal or educational purposes only, provided you do not modify, edit or take out of context the information in this document in any manner. Information contained in this document may be used, at your sole risk, for any purposes. StarFive authorizes you to copy this document, provided that you retain all copyright and other proprietary notices contained in the original materials on any copies of the materials and that you comply strictly with these terms. This copyright permission does not constitute an endorsement of the products or services.
¶ About This Manual
¶ Introduction
This document is intended to:
-
introduce the 40-pin header.
-
provide instructions to configure and debug GPIO, I2C, SPI, PWM, and UART.
-
provide peripheral examples to use 40-pin header.
¶ Revision History
| Version | Released | Revision |
|---|---|---|
| V1 | 2021-12-08 | The first official release. |
| V1.1 | 2021-12-27 | - Updated the command and improved description in the Generating dtb section. - Added a note in the GitHub Repository section |
| V1.2 | 2022-05-05 | - Updated the download link for 2inch LCD Module Example. |
¶ Overview
The 40-pin header allows StarFive single board computers, including both StarLight and VisionFive, to interface with a variety of external components, which enables developers to create their projects. This document is intended to:
-
introduce the 40-pin header as described in this chapter.
-
provide instructions to configure and debug GPIO, I2C, SPI, PWM, and UART, as described in Preparation, GPIO Operations, I2C Operations, SPI Operations, PWM Operations, and UART Operations chapters.
-
provide peripheral examples to use 40-pin header, as described in Peripheral Examples chapter.
¶ 40-Pin Header Definition
The following figure shows the location of the 40-pin header. The VisionFive board is taken as an example:
Figure - 40-Pin Definition
¶ GPIO Pinout
The following table describes the GPIO pinout, the map and explanation of what each pin can do:
Table - GPIO Pinout
| dts | sys | Pin Name | Num | Num | Pin Name | sys | dts |
|---|---|---|---|---|---|---|---|
| 3.3V Power | 1 | 2 | 5V Power | ||||
| i2c1 | i2c-1 | GPIO48 (I2C SDA) | 3 | 4 | 5V Power | ||
| i2c1 | i2c-1 | GPIO47 (I2C SCL) | 5 | 6 | GND | ||
| 494 | GPIO46 | 7 | 8 | GPIO14 (UART TX) | ttyS0 | uart3 | |
| GND | 9 | 10 | GPIO13 (UART RX) | ttyS0 | uart3 | ||
| 492 | GPIO44 | 11 | 12 | GPIO45 | PWM2 | ||
| 470 | GPIO22 | 13 | 14 | GND | |||
| 468 | GPIO20 | 15 | 16 | GPIO21 | 469 | ||
| 3.3V Power | 17 | 18 | GPIO19 | 467 | |||
| spi2 | spidev0.0 | GPIO18 (SPI MOSI) | 19 | 20 | GND | ||
| spi2 | spidev0.0 | GPIO16 (SPI MISO) | 21 | 22 | GPIO17 | 465 | |
| spi2 | spidev0.0 | GPIO12 (SPI SCLK) | 23 | 24 | GPIO15 (SPI CE0) | spidev0.0 | spi2 |
| GND | 25 | 26 | GPIO11 (SPI CE1) | spidev0.0 | spi2 | ||
| 457 | GPIO9 | 27 | 28 | GPIO10 | 458 | ||
| 456 | GPIO8 | 29 | 30 | GND | |||
| 454 | GPIO6 | 31 | 32 | GPIO7 (PWM0) | PWM0 | ||
| PWM1 | GPIO5 (PWM1) | 33 | 34 | GND | |||
| 451 | GPIO3 | 35 | 36 | GPIO4 | 452 | ||
| 449 | GPIO1 | 37 | 38 | GPIO2 | 450 | ||
| GND | 39 | 40 | GPIO0 | 448 |
¶ Preparation
Before configuring and debugging the GPIOs, you need to prepare the follows:
¶ Preparing Hardware
The following table describes hardware items to be prepared if you want to configure, debug, and test this 40-pin header by following this guide:
Table - Hardware Preparation
| Type | M/O* | Item | Notes |
| General | M | StarFive single board computer | The following boards are applicable: - StarLight - VisionFive |
| General | M | - 16GB (or more) micro-SD card - micro-SD card reader - Computer (PC/Mac/Linux) - USB to serial converter (3.3 V I/O) - Ethernet cable - Power adapter (5 V / 3 A) - USB Type-C Cable | These items are used for flashing Fedora OS into a micro-SD card. |
| GPIO | O | An oscilloscope | The oscilloscope is used to verify the GPIO voltage. |
| I2C | O | - Sense Hat (B) - Dupont Line | - |
| SPI | O | - ADXL345 Module - Dupont Line | - |
| PWM | O | An oscilloscope | The oscilloscope is used to measure the corresponding pin and check the PWM period and duty cycle. |
| Peripheral Example | O | - 2inch LCD Module - Dupont Line | - |
* M/O: M (Mandatory)/ O (Optional)
¶ Preparing Software
Before configuring the 40-pin header, the Fedora OS needs to be flashed into the Micro-SD card, and the dtb files need to be compiled and replaced. The following procedures are provided:
¶ GitHub Repository
The following table describes the GitHub Repository addresses:
Note:
Make sure you have swtiched to the corresponding branch.
Table - GitHub Repository Addresses
| Type | Repository | Branch |
| Linux | visionfive | |
| dts File under Linux Repo | - | |
| Uboot | JH7100_upstream | |
| OpenSBI | master | |
| Fedora image (Alpha version) | - |
¶ Flashing Fedora OS to a Micro-SD Card
Two methods are provided to flash images. One is for Mac/Linux, the other is for Windows. For detailed instructions, refer to Flashing Fedora OS to a Micro-SD Card section in VisionFive Single Board Computer Quick Start Guide.
¶ Generating dtb
To compile the device tree sources (.dtsi files) into device tree blobs (.dtb files) using device tree compiler (DTC), execute the following command under the root directory of Linux:
make <Configuration_File> ARCH=riscv CROSS_COMPILE=riscv64-linux-gnu-
make CROSS_COMPILE=riscv64-linux-gnu- ARCH=riscv dtbs
Information:
<Configuration_File>:
Bothstarfive_jh7100_fedora_defconfigandvisionfive_defconfigare applicable.
The following is the example command:
make starfive_jh7100_fedora_defconfig ARCH=riscv CROSS_COMPILE=riscv64-linux-gnu-
make CROSS_COMPILE=riscv64-linux-gnu- ARCH=riscv dtbs
Different boards use different dtb files. The following table describes the relationship:
Table - dtb Files
| Board | File |
| StarLight | /linux/arch/riscv/boot/dts/starfive/jh7100-beaglev-starlight.dtb |
| VisionFive | /linux/arch/riscv/boot/dts/starfive/jh7100-starfive-visionfive-v1.dtb |
¶ Replacing dtb
The SD card used to flash the images identifies the following directories:
Figure -Identified Directories
¶ Method 1: Directly Replacing dtb File
Execute the following command under the root directory of Linux to replace the dtb file:
sudo cp arch/riscv/boot/dts/starfive/<dtb_file> <Mount_Directory>/__boot/dtbs/<Kernel_Version>/starfive
Information:
<dtb_file>refers to the dtb file name. Different boards use different dtb files. For more information, see dtb Files table in this document.
<Mount_Directory>refers to the actual mount directory. For example,/media/jianlong.
<Kernel_Version>refers to the kernel version number. For example,5.14.0+.
Example Command:
sudo cp arch/riscv/boot/dts/starfive/jh7100-starfive-visionfive-v1.dtb /media/jianlong/__boot/dtbs/5.14.0+/starfive
¶ Method 2: Adding Startup Item
To replace dtb file by adding a startup item, perform the following:
Steps:
-
Execute the following commands under the root directory of Linux:
sudo cp arch/riscv/boot/dts/starfive/<dtb_file> <Mount_Direcotry>/boot/dtbs/Information:
-
<dtb_file>refers to the dtb file name. Different boards use different dtb files. For more information, see dtb Files table in this document. -
<Mount_Directory>refers to the actual mount directory. For example,/media/jianlong.
Example Command:
sudo cp arch/riscv/boot/dts/starfive/jh7100-starfive-visionfive-v1.dtb /media/jianlong/__boot/dtbs/ -
-
Enter SD card mount directory:
cd <Mount_Direcotry>/__bootInformation:
<Mount_Directory>refers to the actual mount directory. For example,/media/jianlong. -
Update
grub.cfg:sudo gedit grub.cfg -
Add the following command lines, save and exit:
menuentry 'MY Fedora vmlinux-5.14.0+' { linux /vmlinuz-5.14.0+ ro root=UUID=f852f7f6-aa4e-4404-8ea9-439568b767a1 rhgb console=tty0 console=ttyS0,115200 earlycon rootwait stmmaceth=chain_mode:1 selinux=0 LANG=en_US.UTF-8 devicetree /dtbs/<dtb_File> initrd /initramfs-<Kernel_Version>.img }Information:
In these command lines：<dtb_File >: the name of dtb file used by the board. For example,jh7100-starfive-visionfive-v1.dtb. Different boards use different dtb files. For more information, see dtb Files table in this document.<Kernel_Version>: the kernel version number. For example,5.14.0+.MY Fedora vmlinux-5.14.0: Configurable menu item name.
-
When the grub menu occurs, select the menu item set in the previous step, for example, MY Fedora vmlinux-5.14.0+, during startup.
Notes:
Multiple startup items can be added according to the actual number of dtb files.
¶ GPIO Operations
This section provides commands to configure GPIO:
¶ Configuring GPIO
To configure GPIO, perform the following:
Steps:
-
Execute the following command to configure GPIO0:
cd /sys/class/gpio echo 448 > export -
Locate to the GPIO0 directory:
cd gpio448 -
Configure the direction of GPIO0 as in:
echo in > direction -
Alternatively, configure the direction of GPIO0 as out:
echo out > direction -
Configure the voltage level of GPIO0 as high:
echo 1 > valueInformation:
You can use an oscilloscope to check the voltage level. -
Configure the voltage level of GPIO0 as low:
echo 0 > valueInformation:
You can use an oscilloscope to check the voltage level. -
Connect the 3.3V Power pin with the GPIO0, and check the voltage level of GPIO0:
cat value -
Connect the GND pin with the GPIO0, and check the voltage level of GPIO0:
cat value
¶ I2C Operations
This chapter describes how to configure and debug I2C GPIO.
¶ Configuring I2C GPIO
4 channels of I2C bus are supported: i2c0, i2c1, i2c2, and i2c3.
Perform the following to configure I2C:
¶ Hardware Setup
Connect the Sense Hat (B) to the header as the following:
.svg)
Figure - Connect the Sense Hat (B) to the header
¶ Configuring dts File
Modify the file content of jh7100-common.dtsi under /linux/arch/riscv/boot/dts/starfive. The following is the default setting. You can configure the unoccupied GPIOs as required.
Figure - Example File Content
Information:
The I2C GPIO pin number is the number indicated in the Pin Name. For more details about the GPIO Pin Name, see the GPIO Pinout section in this document. The pin names of the I2C GPIO are listed as follows:
- GPIO48 (I2C SDA)
- GPIO47 (I2C SCL)
¶ Debugging I2C GPIO
Perform the following steps to debug I2C:
Steps:
-
Execute the following command to scan the bus:
i2cdetect -lResult:
Figure - Example Output -
Execute the following command to detect the device:
i2cdetect -y -r 1Information:
1 is the I2C bus number.Result:
Figure - Example Output
In this figure, the detected devices are0x29,0x48,0x5c,0x68, and0x70. -
Execute the following command to read register content:
i2cget -f -y 1 0x5c 0x0fInformation:
1: I2C bus number0x5c: I2C device address0x0f: Memory address
Result:
The register content is 0xb1 in this output. -
Execute the following command to write register data:
i2cset -y 1 0x5c 0x11 0x10Information:
1: I2C bus number.0x5c: I2C device address.0x11: Memory address.0x10: The content to be written in the register.
-
Execute the following to read all register values:
i2cdump -y 1 0x5cInformation:
1: I2C bus number0x5c: I2C device address
Result:
Figure - Example Output
¶ SPI Operations
This chapter describes how to configure and debug SPI GPIO.
¶ Configuring SPI GPIO
The configuration file, jh7100-common.dtsi, is under /linux/arch/riscv/boot/dts/starfive.
2 channels of SPI bus are supported: spi2 and spi3.
¶ Modify Pins
The configured SPI GPIO number is the number indicated in the Pin Name. For more details about the GPIO Pin Name, see the GPIO Pinout section in this document. You can configure the unoccupied pins. The following is the default settings in the jh7100-common.dtsi:
Figure - Modify Pins
¶ Debugging SPI GPIO
This section provides steps for loopback test and testing SPI with ADXL345 module.
¶ Loopback Test
The following steps are provided for loopback test:
-
Wiring: Connect GPIO18 with GPIO16 as the following:
Figure - Connect Pin 18 with 16 -
Locate to the following path for the test tool, spidev_test.c:
cd /linux/tools/spi -
Execute the following command under the test tool directory:
make CROSS_COMPILE=riscv64-linux-gnu- ARCH=riscvResult:
The output file is spidev_test in the same directory.
-
Upload spidev_test to the board, for example, Starlight, and change the execution permission by executing the following:
chmod +x spidev_test -
Confirm the SPI device.
ls /dev/spidev*Result:
Figure - Example Output
In this output,spidev0.0is the device name. -
Execute the following command to perform the test:
./spidev_test -D /dev/spidev0.0 -v -p string_to_sendInformation:
spidev0.0is the device name got from the previous step.Result:
Figure - Example Output
In this figure, the highlighted part indicates the test is successful.
¶ Testing SPI with ADXL345 Module
Perform the following steps to test SPI with ADXL345 module:
-
Connect the ADXL345 module to the 40-pin header as the following:
Figure - Connect ADXL345 Module to the Header -
Locate to the following path for test tool,
spidev_test.c:cd /linux/tools/spi -
Execute the following command under the test tool directory:
make CROSS_COMPILE=riscv64-linux-gnu- ARCH=riscvResult:
The output file is spidev_test in the same directory. -
Upload
spidev_test to the board, for example, StarLight, and change the execution permission by executing the following:chmod +x spidev_test -
Confirm the SPI device.
ls /dev/spidev*Example:
Figure - Example Output
In this output, spidev0.0 is the device name. -
Execute the following to read the device ID:
./spidev_test -H -O -D /dev/spidev0.0 -v -p \\x80\\x00 -
Execute the following to read the value for multiple registers:
./spidev_test -H -O -D /dev/spidev0.0 -v -p \\xec\\x00\\x00\\x00\\x00\\x00\\x00 -
Execute the following to read:
./spidev_test -H -O -D /dev/spidev0.0 -v -p \\x9e\\x00 -
Execute the following to write:
./spidev_test -H -O -D /dev/spidev0.0 -v -p \\x1e\\xaa -
Execute the following to read the verification:
./spidev_test -H -O -D /dev/spidev0.0 -v -p \\x9e\\x00
¶ PWM Operations
This chapter describes how to configure and debug PWM GPIO:
¶ Configuring PWM GPIO
The configuration file, jh7100-common.dtsi, is located under /linux/arch/riscv/boot/dts/starfive
8 channels of PWM are supported at the most.
¶ Modify Pin
The following figure shows the example file content to modify pin:
Figure - Example File Content
The configured PWM GPIO number is the number contained in the Pin Name. For more details about the GPIO Pin Name, see the GPIO Pinout section in this document.
¶ PWM and Pin Name Mapping
The following table describes the PWM and pin name mapping:
Table - PWM and Pin Name Mapping
| PWM | GPIO (Pin Name) |
| PWM0 | GPIO7 |
| PWM1 | GPIO5 |
| PWM2 | GPIO45 |
¶ Debugging PWM GPIO
This section describes how to debug PWM GPIO:
- Execute the following to configure PWM channel:
cd /sys/class/pwm/pwmchip0 echo 0 > export - Execute the following to configure PWM period:
cd pwm0 echo 5000000 > period - Execute the following to configure PWM duty cycle:
echo 1000000 > duty_cycle - Use an oscilloscope to measure the corresponding pin and check the PWM period and duty cycle.
¶ UART Operations
This chapter describes how to configure and debug UART GPIO:
¶ Configuring UART GPIO
The configuration file, jh7100-common.dtsi, is located under:
/linux/arch/riscv/boot/dts/starfive
4 channels of UART are supported at the most:
- Uart3 is for Debug.
- Uart0 is for Bluetooth.
- Uart1 and Uart2 can be used.
The configured UART GPIO number is the number contained in the Pin Name. For more details about the GPIO Pin Name, see the GPIO Pinout section in this document.
¶ Modifying dts
To modify dts file, perform the following steps:
-
Add aliases of uart1 or uart2 on the aliases node. The following is an example:
Figure - Example Configuration -
Add uart1 or uart2 node on the dts. The following is an example:
Figure - Example Configuration -
Add uart1_pins or uart2_pins node on the &gpio node
The configured UART GPIO number is the number contained in the Pin Name. You can configure the unoccupied pins. For more details about the GPIO Pin Name, see the GPIO Pinout section in this document.
Figure - Example Configuration
¶ UART and DEV Mapping
The following table describes the UART and DEV mapping:
Table - UART and DEV Mapping
| UART | DEV |
| UART1 | /dev/ttyS2 |
| UART2 | /dev/ttyS3 |
¶ Debugging UART GPIO
¶ Hardware Setup
To set up the hardware, perform the following steps:
Steps:
-
Connect the jumper wires from the USB-to-Serial Converter to the 40-Pin GPIO header of the VisionFive as follows.
Figure - Connect the Converter to the Header
-
Connect the other end of the USB-to-Serial Converter to your device (PC/Ubuntu).
¶ Debugging UART Send and Receive Functions
-
Configure Visionfive minicom
sudo minicom -s -
Select Serial port setup, and configure minicom as follows:
Figure - Example Configuration -
Start Visionfive minicom by typing the following command:
minicom -o -D /dev/ttyS2Result:
Figure - Example Output -
Configure Ubuntu minicom by typing the following:
sudo minicom -s -
Select Serial port setup, and configure minicom as follows:
Figure -Example ConfigurationInformation:
Serial Device can be detected by commanddmesg | grep ttyon Ubuntu
-
Start Ubuntu minicom, you can see as follows:
Figure - Example Output
Test UART Send:
To test UART send function, you can input characters, such as hello ubuntu, on the VisionFive minicom. Then you wil see the character are outputted on the Ubuntu minicom as the following:
-
Figure on the Left: Ubuntu minicom interface
-
Figure on the Right: VisionFive minicom interface
Test UART Receive:
To test UART receive, you can input characters, such as hello visionfive on the Ubuntu minicom. Then you will see the characters are outputted on the Visionfive minicom:
-
Figure on the Left: Ubuntu minicom interface
-
Figure on the Right: VisionFive minicom interface
¶ Peripheral Examples
In this demo, Sense Hat (B) is used. For the detailed specifications, refer to https://www.waveshare.com/wiki/Sense_HAT_(B) .
Notes:
The official libraries of BCM2835, Python, and wiringPi are not supported, and we use the system call instead. The examples are required to be modified.
¶ Sense Hat (B) Example
¶ Hardware Setup
The following table and figure describe how to connect Sense HAT to the 40-pin header:
Table - Connect Sense Hat (B) to the 40-Pin Header
| Sense HAT (B) | Pin Number |
| 3V3 | 1 |
| GND | 9 |
| SDA | 3 |
| SCL | 5 |
Figure - Connect Sense Hat (B) to the 40-Pin Header
Figure - Connect Sense Hat (B) to the 40-Pin Header
¶ Examples
Take SHTC3 sensor as an example:
-
Download the source code from: SHTC3_dev.c
-
(Optional) Install the tool to compile. The following is an example to install:
sudo apt-get install gcc-riscv64-linux-gnuInformation:
This step can be skipped if the tool has been installed. -
Execute the following to compile:
riscv64-linux-gnu-gcc SHTC3_dev.c -o shtc3Result:
The output file is shtc3 in the same directory.
-
Copy the executable codes from the shtc3 file to the board, and change the execution permission by executing the following command:
chmod +x shtc3 -
Execute the following command to run:
./shtc3Result:
The following output indicates the execution is successful: [root@fedora-starfive riscv]# ./shtc3 SHTC3 Sensor Test Program ... Fopen : /dev/i2c-1 Temperature = 75.61°C , Humidity = 68.55 Temperature = 27.40°C , Humidity = 68.54 Temperature = 27.40°C , Humidity = 68.55 Temperature = 27.40°C , Humidity = 68.54 Temperature = 27.39°C , Humidity = 68.54
¶ 2inch LCD Module Example
A 2inch LCD Module is used in this example. For the detailed specifications, refer to the following: https://www.waveshare.com/wiki/2inch_LCD_Module.
Notes:
The official examples are required to be modified for this demo.
¶ Hardware Setup
The following table and figure describe how to connect the 2inch LCD module with the 40-pin header:
Table - Connect 2inch LCD with 40-pin Header
| 2inch LCD Module | Pin Number |
| VCC | 17 |
| GND | 39 |
| DIN | 19 |
| CLK | 23 |
| CS | 28 |
| DC | 22 |
| RST | 13 |
| BL | 18 |
Figure - Connect 2inch LCD with 40-Pin Header
Figure - Connect 2inch LCD with 40-Pin Header
¶ Executing Example
Perform the following steps to execute the example:
Steps:
-
Download the source code from visionfive.tar.gz.
-
Execute the following command to copy the codes to the board. For example, VisionFive.
tar -xvf visionfive.tar.gz cd visionfive/ ./main 2Result:
The following two figures will be displayed in turn. One is the photo of VisionFive, the other is the offical example figure.
Figure - Example Output