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.
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.
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. |
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.
The following figure shows the location of the 40-pin header. The VisionFive board is taken as an example:
Figure - 40-Pin Definition
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 |
Before configuring and debugging the GPIOs, you need to prepare the follows:
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)
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:
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) | - |
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.
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_defconfig
andvisionfive_defconfig
are 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 |
The SD card used to flash the images identifies the following directories:
Figure -Identified Directories
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
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>/__boot
Information:
<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.
This section provides commands to configure 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 > value
Information:
You can use an oscilloscope to check the voltage level.
Configure the voltage level of GPIO0 as low:
echo 0 > value
Information:
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
This chapter describes how to configure and debug I2C GPIO.
4 channels of I2C bus are supported: i2c0, i2c1, i2c2, and i2c3.
Perform the following to configure I2C:
Connect the Sense Hat (B) to the header as the following:
Figure - Connect the Sense Hat (B) to the header
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)
Perform the following steps to debug I2C:
Steps:
Execute the following command to scan the bus:
i2cdetect -l
Result:
Figure - Example Output
Execute the following command to detect the device:
i2cdetect -y -r 1
Information:
1 is the I2C bus number.
Result:
Figure - Example Output
In this figure, the detected devices are 0x29
, 0x48
, 0x5c
, 0x68
, and 0x70
.
Execute the following command to read register content:
i2cget -f -y 1 0x5c 0x0f
Information:
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 0x10
Information:
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 0x5c
Information:
1
: I2C bus number0x5c
: I2C device address
Result:
Figure - Example Output
This chapter describes how to configure and debug 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.
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
This section provides steps for loopback test and testing SPI with ADXL345 module.
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=riscv
Result:
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.0
is the device name.
Execute the following command to perform the test:
./spidev_test -D /dev/spidev0.0 -v -p string_to_send
Information:
spidev0.0
is the device name got from the previous step.
Result:
Figure - Example Output
In this figure, the highlighted part indicates the test is successful.
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=riscv
Result:
The output file is spidev_test in the same directory.
Upload spidev_tes
t 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
This chapter describes how to configure and debug 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.
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.
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 |
This section describes how to debug PWM GPIO:
cd /sys/class/pwm/pwmchip0
echo 0 > export
cd pwm0
echo 5000000 > period
echo 1000000 > duty_cycle
This chapter describes how to configure and debug 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:
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.
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
The following table describes the UART and DEV mapping:
Table - UART and DEV Mapping
UART | DEV |
UART1 | /dev/ttyS2 |
UART2 | /dev/ttyS3 |
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).
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/ttyS2
Result:
Figure - Example Output
Configure Ubuntu minicom by typing the following:
sudo minicom -s
Select Serial port setup, and configure minicom as follows:
Figure -Example Configuration
Information:
Serial Device can be detected by commanddmesg | grep tty
on 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
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.
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
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-gnu
Information:
This step can be skipped if the tool has been installed.
Execute the following to compile:
riscv64-linux-gnu-gcc SHTC3_dev.c -o shtc3
Result:
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:
./shtc3
Result:
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
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.
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
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 2
Result:
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