Difference between revisions of "Matrix - 2'8 SPI Key TFT"

From FriendlyELEC WiKi
Jump to: navigation, search
(Connect to NanoPi 2)
(updated by API)
 
(56 intermediate revisions by 4 users not shown)
Line 3: Line 3:
 
==Introduction==
 
==Introduction==
 
[[File:Matrix-2'8_SPI_Key_TFT.png|thumb|]]
 
[[File:Matrix-2'8_SPI_Key_TFT.png|thumb|]]
*Matrix-2'8_SPI_Key_TFT模块是一款2.8英寸的TFT 触摸LCD,模块采用ST7789S驱动IC和XPT2046电阻式触摸IC,屏幕分辨率为320*240,采用SPI控制接口,模块还包含3个独立按键,可根据需要自定义功能。
+
* The Matrix-2.8_SPI_Key_TFT LCD is a FriendlyARM developed LCD module with resistive touch panel. Its resolution is 240 x 320. It uses the ST7789V IC and XPT2046 resistive touch IC. It has SPI interface and three configurable user keys.
*详细规格如下所示:
+
 
 +
* Specification
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
|LCD尺寸||2.8寸
+
|LCD Dimension||2.8"
 
|-
 
|-
|显示区域||57.6mm*43.2mm
+
|Display Area||57.6mm*43.2mm
 
|-
 
|-
|驱动IC||ST7789S
+
|Driver IC||ST7789V
 
|-
 
|-
|分辨率||320*240(RGB)
+
|Resolution||240 * 320(RGB)
 
|-
 
|-
|接口方式||SPI
+
|MCU Interface||SPI
 
|-
 
|-
|工作电压||5V
+
|Power Supply||5V
 
|-
 
|-
|背光电压||5V
+
|Backlight Voltage||5V
 
|-
 
|-
|触摸屏类型||电阻式,钢化玻璃触摸屏
+
|Touch||Resistive Touch, tempered glass touch panel
 
|-
 
|-
 
|}
 
|}
模块上电默认打开背光,可通过置低LED_EN引脚关闭背光。如果需要关闭上电打开背光,只需要拿到电路板上的R12电阻,再通过置高LED_EN引脚打开背光;
+
By default the module's backlight is turned on after the module is powered on. LED_EN can be set to turn off the backlight. If you don’t want the backlight to be turned on after the module is powered on you can take off R12 and in this case you can turn on the backlight by pulling up LED_EN.
  
 
==Features==
 
==Features==
Line 31: Line 32:
  
 
* Pin Description:
 
* Pin Description:
 +
FriendlyElec has released two versions. Here are the spec:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
|Pin || Description      ||Pin || Description
+
| style="background: PaleTurquoise; color: black" colspan="4"| '''Matrix-2'8_SPI_Key_TFT-1706'''
 +
|-
 +
|Pin# || Description      ||Pin# || Description
 
|-
 
|-
 
|1    || VDD_3.3V        ||2    || VDD_5V
 
|1    || VDD_3.3V        ||2    || VDD_5V
Line 45: Line 49:
 
|9    || GND              ||10  || NC  
 
|9    || GND              ||10  || NC  
 
|-
 
|-
|11  || LED_EN          ||12  || NC
+
|11  || LED_EN          ||12  || T_CS
 
|-
 
|-
 
|13  || KEY_1            ||14  || GND
 
|13  || KEY_1            ||14  || GND
Line 59: Line 63:
 
|23  || SPI_CLK          ||24  || LCD_CS
 
|23  || SPI_CLK          ||24  || LCD_CS
 
|-
 
|-
|25  || GND              ||26  || T_CS
+
|25  || GND              ||26  || NC
 
|-  
 
|-  
 
|}
 
|}
  
 +
{| class="wikitable"
 +
|-
 +
| style="background: PaleTurquoise; color: black" colspan="4"| '''Matrix-2'8_SPI_Key_TFT-1512'''
 +
|-
 +
|Pin# || Description      ||Pin# || Description
 +
|-
 +
|1    || VDD_3.3V  ||2    || VDD_5V
 +
|-
 +
|3    || NC        ||4    || VDD_5V
 +
|-
 +
|5    || NC        ||6    || GND
 +
|-
 +
|7    || LCD_RESET ||8    || NC
 +
|-
 +
|9    || GND      ||10  || NC
 +
|-
 +
|11  || LED_EN    ||12  || NC
 +
|-
 +
|13  || KEY_1    ||14  || GND
 +
|-
 +
|15  || KEY_2    ||16  || KEY_3
 +
|-
 +
|17  || VDD_3.3V  ||18  || T_IRQ
 +
|-
 +
|19  || SPI_MOSI  ||20  || GND
 +
|-
 +
|21  || SPI_MISO  ||22  || LCD_D/C
 +
|-
 +
|23  || SPI_CLK  ||24  || LCD_CS
 +
|-
 +
|25  || GND        ||26  || T_CS
 +
|-
 +
|}
 +
<span style="color:#ff0000"> <br>
 +
The Matrix-2'8_SPI_Key_TFT-1706 exposes T_CS from Pin26 to Pin12. And NEO/NEO2/NEO-Plus2 all of which have a 24Pin connector will be able to work with its touch.
 +
<br></span>
 +
 +
==Applicable Boards & OS==
 +
{| class="wikitable"
 +
|-
 +
|Index ||SoC Model|| Board Model || OS
 +
|-
 +
|1    ||H3||NanoPi NEO/NEO Air/NEO Core/M1/M1 Plus|| Allwinner's released Linux-3.4 kernel and Mainline Linux-4.x kernel
 +
|-
 +
|2    ||H5||NanoPi NEO2/NEO Plus2/NEO Core2 || Mainline Linux-4.x kernel
 +
|-
 +
|3    ||S5P4418||NanoPi2/NanoPi M2/NanoPi2 Fire    || Samsung's released Linux-3.4 kernel
 +
|-
 +
|}
 
<!---
 
<!---
 
==Basic Device Operation==
 
==Basic Device Operation==
Line 88: Line 141:
  
 
==Applications==
 
==Applications==
===Connect to NanoPi M1===
+
===H3 Based Boards===
Please refer to the following connection diagram to connect the module to the NanoPi M1:<br>
+
Connect to NanoPi M1:<br>
 +
Refer to the following hardware setup to connect the module to the NanoPi M1:<br>
 
[[File:Matrix-2'8_SPI_Key_TFT_nanopi_m1.jpg|frameless|600px|Matrix-2'8_SPI_Key_TFT_nanopi_m1]]
 
[[File:Matrix-2'8_SPI_Key_TFT_nanopi_m1.jpg|frameless|600px|Matrix-2'8_SPI_Key_TFT_nanopi_m1]]
  
===Connect to NanoPi 2===
+
Connect to NanoPi M1 Plus:<br>
Please refer to the following connection diagram to connect the module to the NanoPi 2:<br>
+
Refer to the following hardware setup to connect the module to the NanoPi M1 Plus:<br>
[[File:Matrix-2'8_SPI_Key_TFT_nanopi2.jpg|frameless|600px|Matrix-2'8_SPI_Key_TFT_nanopi2]]
+
[[File:Matrix-2'8_SPI_Key_TFT_nanopi_m1_plus.jpg|frameless|600px|Matrix-2'8_SPI_Key_TFT_nanopi_m1_plus]]
  
===Connect to NanoPi M2 / NanoPi 2 Fire===
+
Connect to NanoPi NEO:<br>
Please refer to the following connection diagram to connect the module to the NanoPi M2 / P2:<br>
+
Refer to the following hardware setup to connect the module to the NanoPi NEO:<br>
[[File:Matrix-2'8_SPI_Key_TFT_nanopi_m2.jpg|frameless|600px|Matrix-2'8_SPI_Key_TFT_nanopi_m2]]
+
[[File:Matrix-2'8_SPI_Key_TFT_nanopi_neo.jpg|frameless|600px|Matrix-2'8_SPI_Key_TFT_nanopi_neo]]
  
 +
Connect to NanoPi NEO Air:<br>
 +
Refer to the following hardware setup to connect the module to the NanoPi NEO Air:<br>
 +
[[File:Matrix-2'8_SPI_Key_TFT_nanopi_neo_air.jpg|frameless|600px|Matrix-2'8_SPI_Key_TFT_nanopi_neo_air]]
  
===Compile Test Program===
+
Connect to NanoPi NEO Core:<br>
Please login the matrix hub and enter the nanopi2 branch
+
Refer to the following hardware setup to connect the module to the NanoPi NEO Core:<br>
<syntaxhighlight lang="bash">
+
[[File:Matrix-2'8_SPI_Key_TFT_nanopi_neo_core.jpg|frameless|500px|Matrix-2'8_SPI_Key_TFT_nanopi_neo_core]]<br>
$ cd matrix
+
$ git checkout nanopi2
+
</syntaxhighlight>
+
  
Compile the Matrix code
+
===H5 Based Boards===
<syntaxhighlight lang="bash">
+
Connect to NanoPi NEO2:<br>
$ make CROSS_COMPILE=arm-linux- clean
+
[[File:Matrix-2'8_SPI_Key_TFT_nanopi_neo2.jpg|frameless|600px|Matrix-2'8_SPI_Key_TFT_nanopi_neo2]]<br>
$ make CROSS_COMPILE=arm-linux-
+
$ make CROSS_COMPILE=arm-linux- install
+
</syntaxhighlight>
+
Note: please make sure to install the cross compiler "arm-linux-gcc-4.9.3" on your PC, which is used to compile files for the NanoPi 2.<br>
+
Generated library files are under the "install/lib" directory. The test program is under the "install/usr/bin" directory.<br>
+
The modules are under the "modules" directory. The driver's source code is in github: https://github.com/friendlyarm/linux-3.4.y.git <br>
+
  
===Load Driver===
+
Connect to NanoPi NEOPlus2:<br>
Please insert a TF card which is flashed with Debian to a Linux host and mount its boot and rootfs sections.<br>
+
[[File:Matrix-2'8_SPI_Key_TFT_nanopi_neo_plus2.jpg|frameless|600px|Matrix-2'8_SPI_Key_TFT_nanopi_neo_plus2]]<br>
We assume the rootfs is mounted to /media/rootfs then please run the following commands to copy the driver, library and test program to the card.<br>
+
<syntaxhighlight lang="bash">
+
$ cp modules /media/rootfs/ -r
+
$ cp install/lib/* /media/rootfs/lib/ -d
+
$ cp install/usr/bin/* /media/rootfs/usr/bin/
+
</syntaxhighlight>
+
  
Insert this TF card to your NanoPi 2, power on and run the following commands to load the driver.<br>
+
Connect to NanoPi NEO Core2:<br>
<syntaxhighlight lang="bash">
+
Refer to the following hardware setup to connect the module to the NanoPi NEO Core:<br>
$ cd /modules
+
[[File:Matrix-2'8_SPI_Key_TFT_nanopi_neo_core2.jpg|frameless|500px|Matrix-2'8_SPI_Key_TFT_nanopi_neo_core2]]<br>
$ insmod fbtft_device.ko name=matrix-st7789s gpios=dc:97,reset:60,cs:94
+
$ insmod matrix_ads7846.ko
+
</syntaxhighlight>
+
"fbtft_device" is the LCD's driver. "matrix_ads7846" is the touch driver. If they are successfully loaded the LCD will be cleared and reset.<br>
+
  
===Test LCD Display===
+
===S5P4418 Based Boards===
Please run the following commands to set the display device to the Matrix-2'8_SPI_Key_TFT:
+
Connect to NanoPi 2:<br>
<syntaxhighlight lang="bash">
+
Refer to the following hardware setup to connect the module to the NanoPi 2:<br>
$ sudo FRAMEBUFFER=/dev/fb-st7789s startx &
+
[[File:Matrix-2'8_SPI_Key_TFT_nanopi2.jpg|frameless|600px|Matrix-2'8_SPI_Key_TFT_nanopi2]]
</syntaxhighlight>
+
"&" schedules the program to run background and you will see the following messages:<br>
+
<syntaxhighlight lang="bash">
+
Log file: "/var/log/Xorg.2.log"
+
</syntaxhighlight>
+
Here the message shows that the X window's DISPLAY value is 2<br>
+
  
===Calibrate Touch===
+
Connect to NanoPi M2 / NanoPi 2 Fire:<br>
Please run the following commands to calibrate touch:
+
Refer to the following hardware setup to connect the module to the NanoPi M2 / NanoPi 2 Fire:<br>
<syntaxhighlight lang="bash">
+
[[File:Matrix-2'8_SPI_Key_TFT_nanopi_m2.jpg|frameless|600px|Matrix-2'8_SPI_Key_TFT_nanopi_m2]]
$ DISPLAY=:2.0 xinput_calibrator
+
</syntaxhighlight>
+
After you click on the four points highlighted on the LCD you will get calibration done and observe the following messages:
+
<syntaxhighlight lang="bash">
+
Section "InputClass"
+
        Identifier      "calibration"
+
        MatchProduct    "ADS7846 Touchscreen"
+
        Option  "Calibration"  "196 3825 3887 358"
+
        Option  "SwapAxes"      "0"
+
EndSection
+
</syntaxhighlight>
+
Save these calibration data to the "/usr/share/X11/xorg.conf.d/99-calibration.conf" file and reboot the system your touch will be ready to go.
+
  
==Connect to NanoPi==
+
==Run pre-enabled Matrix-2'8_SPI_Key_TFT ROM==
===Preparations===
+
::{| class="wikitable"
Please install a Debian on a NanoPi and an appropriate cross compiler on a PC. Please refer to wiki:[[NanoPi/zh|NanoPi]] <br>
+
Compile a NanoPi kernel. Note: please use the kernel's source code from the nanopi-v4.1.y-matrix branch. <br>
+
<syntaxhighlight lang="bash">
+
$ git clone https://github.com/friendlyarm/linux-4.x.y.git
+
$ cd linux-4.x.y
+
$ git checkout nanopi-v4.1.y-matrix
+
$ make nanopi_defconfig
+
$ touch .scmversion
+
$ make
+
</syntaxhighlight>
+
 
+
===Hardware Connection===
+
Please refer to the following connection diagram to connect the Matrix-2'8 SPI_TFT to the NanoPi <br>
+
[[File:Matrix-2'8 SPI_TFT_nanopi.jpg|frameless|600px|Matrix-2'8 SPI_TFT_nanopi]]
+
 
+
Connection Details:
+
{| class="wikitable"
+
 
|-
 
|-
|Matrix-2'8 SPI_TFT || NanoPi
+
|Board Type||CPU Model||Download Link to Image File||Image File
 
|-
 
|-
| ||  
+
|NanoPi NEO|| H3 || [http://download.friendlyelec.com/nanopineo Download]|| official-ROMs/accessory-ROMs/nanopi-neo_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
 +
|-
 +
|NanoPi NEO Air|| H3 ||[http://download.friendlyelec.com/nanopineoair Download] || official-ROMs/accessory-ROMs/nanopi-neo-air_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
 +
|-
 +
|NanoPi M1|| H3 ||[http://download.friendlyelec.com/nanopim1 Download] || official-ROMs/accessory-ROMs/nanopi-m1_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
 +
|-
 +
|NanoPi M1 Plus|| H3 ||[http://download.friendlyelec.com/nanopim1plus Download] || official-ROMs/accessory-ROMs/nanopi-m1-plus_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
 +
|-
 +
|NanoPi NEO Core|| H3 ||[http://download.friendlyelec.com/nanopineocore Download] || official-ROMs/accessory-ROMs/nanopi-neo-core_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
 +
|-
 +
|NanoPi NEO2|| H5 ||[http://download.friendlyelec.com/nanopineo2 Download] || official-ROMs/accessory-ROMs/nanopi-neo2_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
 +
|-
 +
|NanoPi NEO Plus2|| H5 ||[http://download.friendlyelec.com/nanopineoplus2 Download] || official-ROMs/accessory-ROMs/nanopi-neo-plus2_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
 +
|-
 +
|NanoPi NEO Core2|| H5 ||[http://download.friendlyelec.com/nanopineocore2 Download] || official-ROMs/accessory-ROMs/nanopi-neo-core2_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
 +
|-
 +
|NanoPi K1 Plus|| H5 ||[http://download.friendlyelec.com/nanopik1plus Download] || official-ROMs/accessory-ROMs/nanopi-k1-plus_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
 
|-
 
|-
 
|}
 
|}
  
===Load Driver===
+
==Compile & Run Test Program Manually==
Power on the NanoPi and run the following command in Debian's terminal to load drivers:
+
===H3/H5===
 +
Note: the following method only applies for the Matrix-2'8_SPI_Key_TFT-1706 model. To test a Matrix-2'8_SPI_Key_TFT-1512(silkscreen T28-02 1512) refer to the last section and set Pin26 as the touch's enable/disable pin.<br><br>
 +
 
 +
====Linux-4.14====
 +
=====Use npi-config to enable 2.8"TFT=====
 +
If you use a FriendlyElec's H3/H5 board under Mainline Linux-4.14 kernel you need to enable the 2.8"TFT with npi-config.Start npi-config as root:
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
$ modprobe fbtft_device name=matrix-spi_tft gpios=dc:161,reset:162,cs:163
+
$ npi-config
$ modprobe matrix_ads7846
+
 
</syntaxhighlight>
 
</syntaxhighlight>
The "fbtft_device" module is the driver for the st7789s chip and the "matrix_ads7846" module is the driver for the xpt2046 chip.
+
Open the following menu:<br>
 +
[[File:tft-1.png|frameless|1000px|tft-1]]<br>
 +
Open SPI:<br>
 +
[[File:tft-2.png|frameless|1000px|tft-2]]<br>
 +
Enable/Disable SPI0:<br>
 +
[[File:tft-3.png|frameless|1000px|tft-3]]<br>
 +
Enable SPI0 and then select Matrix-2.8"_SPI_Key_TFT:<br>
 +
[[File:tft-4.png|frameless|1000px|tft-4]]<br>
 +
Return to the main menu and do <Finish>. Reboot your system and run the following command to check whether or not the Matrix-2.8"_SPI_Key_TFT is enabled:
 +
<syntaxhighlight lang="bash">
 +
$ ls /dev/fb-st7789s
 +
/dev/fb-st7789s
 +
</syntaxhighlight>
 +
/dev/fb-st7789s stands for a framebuffer device
 +
<syntaxhighlight lang="bash">
 +
$ ls /dev/input/ts-ads7846
 +
/dev/input/ts-ads7846
 +
</syntaxhighlight>
 +
/dev/input/ts-ads7846 stands for a touch device
 +
When you first start the system you will be prompted to click on five points to do calibration.<br>
 +
[[File:tslib.png|frameless|1000px|tft-tslib]]<br>
 +
Note: in the mainline Linux-4.x kernel Pin12 of Matrix-2'8_SPI_Key_TFT-1706 is by default set as touch device's enable/disable pin.<br>
 +
After you enable the Matrix-2'8_SPI_Key_TFT with npi-config your system will set it as your default display device. If you want to make Qt-demo auto-start on system boot you can follow the steps below:<br>
 +
[[File:tft-qt-demo-1.png|frameless|1000px|tft-qt-demo-1]]<br>
 +
Enter Autologin:<br>
 +
[[File:tft-qt-demo-2.png|frameless|1000px|tft-qt-demo-2]]<br>
 +
Enter Qt/Embedded:<br>
 +
[[File:tft-qt-demo-3.png|frameless|1000px|tft-qt-demo-3]]<br>
 +
Enable Qt/E Demo:<br>
 +
[[File:tft-qt-demo-4.png|frameless|1000px|tft-qt-demo-4]]<br>
 +
Return to the main menu and do <Finish>.Reboot your system and your Qt/E demo will be started automatically:<br>
 +
[[File:qt-demo-status.png|frameless|600px|qt-demo-status]]<br>
  
===Install Package===
+
=====Control backlight=====
Please run the following commands in Debian's terminal to install "qtembedded" and "matrix-tslib"
+
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
$ apt-get update
+
$ echo 1 >/sys/class/backlight/fb_st7789v/bl_power  # 关闭背光
$ apt-get install qtembedded
+
$ echo 0 >/sys/class/backlight/fb_st7789v/bl_power  # 打开背光
$ apt-get install matrix-tslib
+
 
</syntaxhighlight>
 
</syntaxhighlight>
The "qtembedded" library is what qt applications rely on and the "matrix-tslib" library is what screen calibration relies on.
 
  
===Run Test Program===
+
=====Extra setup for Matrix-2'8_SPI_Key_TFT-1512=====
Start Qt applications
+
If you connect a Matrix-2'8_SPI_Key_TFT-1512(silkscreen T28-02 1512) to a NanoPi M1/NanoPi M1 Plus you need to make changes in the kernel code to set Pin26 as touch's enable/disable pin.<br>
 +
Compile your kernel by following the steps in [[Mainline U-boot & Linux]] and make the following changes:
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
$ . /usr/bin/matrix-setqt4env
+
$ vi linux/arch/arm/boot/dts/sun8i-h3-nanopi
$ /usr/local/Trolltech/QtEmbedded-4.8.5-arm/examples/tetrix -qws
+
    ...
 +
    spi0_cs_pins: spi0_cs_pins {
 +
        pins = "PC3", "PA6";
 +
        function = "gpio_out";
 +
    };
 +
    ...
 +
&spi0 {
 +
    ...
 +
    cs-gpios = <&pio 2 3 GPIO_ACTIVE_HIGH>, <&pio 0 6 GPIO_ACTIVE_HIGH>;
 +
    ...
 
</syntaxhighlight>
 
</syntaxhighlight>
The matrix-setqt4env script sets the environmental variables which Qt and tslib rely on. If it is run on a platform for the first time a screen calibration GUI will be launched. Users need to go through a five-point calibration process to calibrate the screen.
+
<&pio 0 6 GPIO_ACTIVE_HIGH> means setting GPIOA6(Pin12) as touch's enable/disable pin. Change it to GPIOA17(Pin26):
The tetrix application is a game developed in Qt4.
+
<syntaxhighlight lang="bash">
 +
    ...
 +
    spi0_cs_pins: spi0_cs_pins {
 +
        pins = "PC3", "PA17";
 +
        function = "gpio_out";
 +
    };
 +
    ...
 +
&spi0 {
 +
    ...
 +
    cs-gpios = <&pio 2 3 GPIO_ACTIVE_HIGH>, <&pio 0 17 GPIO_ACTIVE_HIGH>;
 +
    ...
 +
</syntaxhighlight>
 +
Recompile the kernel code and copy the "sun8i-h3-nanopi-m1.dtb/sun8i-h3-nanopi-m1-plus.dtb" file under arch/arm/boot/dts/ to your TF card's boot section and reboot your board.
  
==Connect to Tiny4412==
+
{{S5Pxx18-SPI-2.8TFT}}
 
+
==Connect to RaspberryPi==
+
 
+
==Connect to Arduino==
+
  
 
==Resources==
 
==Resources==
Line 225: Line 294:
 
===Feb-24-2016===
 
===Feb-24-2016===
 
* Added the driver's source code location in Section 5.2
 
* Added the driver's source code location in Section 5.2
 +
 +
===June-17-2016===
 +
* Re-organized and simplified wiki
 +
 +
===March-5-2017===
 +
* Added sections 3.2, 3.3, 3.4 and 4.1
 +
 +
===July-5-2017===
 +
* Updated sections 4 and 5
 +
 +
===July-15-2017===
 +
* Updated section 5

Latest revision as of 07:17, 21 February 2022

查看中文

1 Introduction

Matrix-2'8 SPI Key TFT.png
  • The Matrix-2.8_SPI_Key_TFT LCD is a FriendlyARM developed LCD module with resistive touch panel. Its resolution is 240 x 320. It uses the ST7789V IC and XPT2046 resistive touch IC. It has SPI interface and three configurable user keys.
  • Specification
LCD Dimension 2.8"
Display Area 57.6mm*43.2mm
Driver IC ST7789V
Resolution 240 * 320(RGB)
MCU Interface SPI
Power Supply 5V
Backlight Voltage 5V
Touch Resistive Touch, tempered glass touch panel

By default the module's backlight is turned on after the module is powered on. LED_EN can be set to turn off the backlight. If you don’t want the backlight to be turned on after the module is powered on you can take off R12 and in this case you can turn on the backlight by pulling up LED_EN.

2 Features

  • PCB dimension(mm):

Matrix-2'8 SPI Key TFT PCB.png

  • Pin Description:

FriendlyElec has released two versions. Here are the spec:

Matrix-2'8_SPI_Key_TFT-1706
Pin# Description Pin# Description
1 VDD_3.3V 2 VDD_5V
3 NC 4 VDD_5V
5 NC 6 GND
7 LCD_RESET 8 NC
9 GND 10 NC
11 LED_EN 12 T_CS
13 KEY_1 14 GND
15 KEY_2 16 KEY_3
17 VDD_3.3V 18 T_IRQ
19 SPI_MOSI 20 GND
21 SPI_MISO 22 LCD_D/C
23 SPI_CLK 24 LCD_CS
25 GND 26 NC
Matrix-2'8_SPI_Key_TFT-1512
Pin# Description Pin# Description
1 VDD_3.3V 2 VDD_5V
3 NC 4 VDD_5V
5 NC 6 GND
7 LCD_RESET 8 NC
9 GND 10 NC
11 LED_EN 12 NC
13 KEY_1 14 GND
15 KEY_2 16 KEY_3
17 VDD_3.3V 18 T_IRQ
19 SPI_MOSI 20 GND
21 SPI_MISO 22 LCD_D/C
23 SPI_CLK 24 LCD_CS
25 GND 26 T_CS


The Matrix-2'8_SPI_Key_TFT-1706 exposes T_CS from Pin26 to Pin12. And NEO/NEO2/NEO-Plus2 all of which have a 24Pin connector will be able to work with its touch.

3 Applicable Boards & OS

Index SoC Model Board Model OS
1 H3 NanoPi NEO/NEO Air/NEO Core/M1/M1 Plus Allwinner's released Linux-3.4 kernel and Mainline Linux-4.x kernel
2 H5 NanoPi NEO2/NEO Plus2/NEO Core2 Mainline Linux-4.x kernel
3 S5P4418 NanoPi2/NanoPi M2/NanoPi2 Fire Samsung's released Linux-3.4 kernel

4 Applications

4.1 H3 Based Boards

Connect to NanoPi M1:
Refer to the following hardware setup to connect the module to the NanoPi M1:
Matrix-2'8_SPI_Key_TFT_nanopi_m1

Connect to NanoPi M1 Plus:
Refer to the following hardware setup to connect the module to the NanoPi M1 Plus:
Matrix-2'8_SPI_Key_TFT_nanopi_m1_plus

Connect to NanoPi NEO:
Refer to the following hardware setup to connect the module to the NanoPi NEO:
Matrix-2'8_SPI_Key_TFT_nanopi_neo

Connect to NanoPi NEO Air:
Refer to the following hardware setup to connect the module to the NanoPi NEO Air:
Matrix-2'8_SPI_Key_TFT_nanopi_neo_air

Connect to NanoPi NEO Core:
Refer to the following hardware setup to connect the module to the NanoPi NEO Core:
Matrix-2'8_SPI_Key_TFT_nanopi_neo_core

4.2 H5 Based Boards

Connect to NanoPi NEO2:
Matrix-2'8_SPI_Key_TFT_nanopi_neo2

Connect to NanoPi NEOPlus2:
Matrix-2'8_SPI_Key_TFT_nanopi_neo_plus2

Connect to NanoPi NEO Core2:
Refer to the following hardware setup to connect the module to the NanoPi NEO Core:
Matrix-2'8_SPI_Key_TFT_nanopi_neo_core2

4.3 S5P4418 Based Boards

Connect to NanoPi 2:
Refer to the following hardware setup to connect the module to the NanoPi 2:
Matrix-2'8_SPI_Key_TFT_nanopi2

Connect to NanoPi M2 / NanoPi 2 Fire:
Refer to the following hardware setup to connect the module to the NanoPi M2 / NanoPi 2 Fire:
Matrix-2'8_SPI_Key_TFT_nanopi_m2

5 Run pre-enabled Matrix-2'8_SPI_Key_TFT ROM

Board Type CPU Model Download Link to Image File Image File
NanoPi NEO H3 Download official-ROMs/accessory-ROMs/nanopi-neo_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
NanoPi NEO Air H3 Download official-ROMs/accessory-ROMs/nanopi-neo-air_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
NanoPi M1 H3 Download official-ROMs/accessory-ROMs/nanopi-m1_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
NanoPi M1 Plus H3 Download official-ROMs/accessory-ROMs/nanopi-m1-plus_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
NanoPi NEO Core H3 Download official-ROMs/accessory-ROMs/nanopi-neo-core_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
NanoPi NEO2 H5 Download official-ROMs/accessory-ROMs/nanopi-neo2_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
NanoPi NEO Plus2 H5 Download official-ROMs/accessory-ROMs/nanopi-neo-plus2_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
NanoPi NEO Core2 H5 Download official-ROMs/accessory-ROMs/nanopi-neo-core2_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip
NanoPi K1 Plus H5 Download official-ROMs/accessory-ROMs/nanopi-k1-plus_sd_ubuntu-tft_4.14_YYYYMMDD.img.zip

6 Compile & Run Test Program Manually

6.1 H3/H5

Note: the following method only applies for the Matrix-2'8_SPI_Key_TFT-1706 model. To test a Matrix-2'8_SPI_Key_TFT-1512(silkscreen T28-02 1512) refer to the last section and set Pin26 as the touch's enable/disable pin.

6.1.1 Linux-4.14

6.1.1.1 Use npi-config to enable 2.8"TFT

If you use a FriendlyElec's H3/H5 board under Mainline Linux-4.14 kernel you need to enable the 2.8"TFT with npi-config.Start npi-config as root:

$ npi-config

Open the following menu:
tft-1
Open SPI:
tft-2
Enable/Disable SPI0:
tft-3
Enable SPI0 and then select Matrix-2.8"_SPI_Key_TFT:
tft-4
Return to the main menu and do <Finish>. Reboot your system and run the following command to check whether or not the Matrix-2.8"_SPI_Key_TFT is enabled:

$ ls /dev/fb-st7789s 
/dev/fb-st7789s

/dev/fb-st7789s stands for a framebuffer device

$ ls /dev/input/ts-ads7846 
/dev/input/ts-ads7846

/dev/input/ts-ads7846 stands for a touch device When you first start the system you will be prompted to click on five points to do calibration.
tft-tslib
Note: in the mainline Linux-4.x kernel Pin12 of Matrix-2'8_SPI_Key_TFT-1706 is by default set as touch device's enable/disable pin.
After you enable the Matrix-2'8_SPI_Key_TFT with npi-config your system will set it as your default display device. If you want to make Qt-demo auto-start on system boot you can follow the steps below:
tft-qt-demo-1
Enter Autologin:
tft-qt-demo-2
Enter Qt/Embedded:
tft-qt-demo-3
Enable Qt/E Demo:
tft-qt-demo-4
Return to the main menu and do <Finish>.Reboot your system and your Qt/E demo will be started automatically:
qt-demo-status

6.1.1.2 Control backlight
$ echo 1 >/sys/class/backlight/fb_st7789v/bl_power   # 关闭背光
$ echo 0 >/sys/class/backlight/fb_st7789v/bl_power   # 打开背光
6.1.1.3 Extra setup for Matrix-2'8_SPI_Key_TFT-1512

If you connect a Matrix-2'8_SPI_Key_TFT-1512(silkscreen T28-02 1512) to a NanoPi M1/NanoPi M1 Plus you need to make changes in the kernel code to set Pin26 as touch's enable/disable pin.
Compile your kernel by following the steps in Mainline U-boot & Linux and make the following changes:

$ vi linux/arch/arm/boot/dts/sun8i-h3-nanopi
    ...
    spi0_cs_pins: spi0_cs_pins {
        pins = "PC3", "PA6";
        function = "gpio_out";
    };
    ...
&spi0 {
    ...
    cs-gpios = <&pio 2 3 GPIO_ACTIVE_HIGH>, <&pio 0 6 GPIO_ACTIVE_HIGH>;
    ...

<&pio 0 6 GPIO_ACTIVE_HIGH> means setting GPIOA6(Pin12) as touch's enable/disable pin. Change it to GPIOA17(Pin26):

    ...
    spi0_cs_pins: spi0_cs_pins {
        pins = "PC3", "PA17";
        function = "gpio_out";
    };
    ...
&spi0 {
    ...
    cs-gpios = <&pio 2 3 GPIO_ACTIVE_HIGH>, <&pio 0 17 GPIO_ACTIVE_HIGH>;
    ...

Recompile the kernel code and copy the "sun8i-h3-nanopi-m1.dtb/sun8i-h3-nanopi-m1-plus.dtb" file under arch/arm/boot/dts/ to your TF card's boot section and reboot your board.

6.2 S5P4418/S5P6818

The following steps only apply to Kernel Linux-4.4. We took the NanoPi Fire3 as an example. Run the following commands to initialize FriendlyElec's 2.8" SPI LCD. These commands need to be run only once.

sudo mount /dev/mmcblk0p1 /boot
sudo apt-get update
sudo apt-get install device-tree-compiler
sudo fdtput /boot/s5p6818-nanopi3-rev05.dtb spi0/spidev@0 status -t s "disabled"
sudo fdtget /boot/s5p6818-nanopi3-rev05.dtb spi0/spidev@0 status
sudo fdtput /boot/s5p6818-nanopi3-rev05.dtb spi0/fbtft@0 status -t s "okay"
sudo fdtget /boot/s5p6818-nanopi3-rev05.dtb spi0/fbtft@0 status
sudo reboot

Note: the "s5p6818-nanopi3-rev05.dtb" file is the kernel dtb file for the NanoPi Fire3. For another board you need to check its system's "/sys/devices/platform/board/info" file to figure out its dtb file.:

cat /sys/devices/platform/board/info

Here is the info file's content for the NanoPi Fire3:
Hardware  : NANOPI3
Revision  : 0005
Serial  : fa6818dba7110739
The "Hardware" here is "NANOPI3", "Revision" is "0005", "CPU" is "S5P6818", therefore the NanoPi Fire3's kernel dtb file name is "s5p6818-nanopi3-rev05.dtb".

After the dtb file is confirmed you can reboot your board and run the following command to check if the fb_st7789v module is loaded:

lsmod

Here is what you expect to see:
Module Size Used by
fb_st7789v 3315 0
fbtft 31881 1 fb_st7789v

Or you can run dmesg to check that. In our case after we ran dmesg we found that the SPI LCD was recognized as an "fb1" device:

dmesg | grep fb_st7789v

Here is what you expect to see:
[ 6.728000] fb_st7789v: module is from the staging directory, the quality is unknown, you have been warned.
[ 6.908000] graphics fb1: fb_st7789v frame buffer, 320x240, 150 KiB video memory, 4 KiB buffer memory, fps=35, spi0.0 at 50 MHz
Now as long as you set your system's framebuffer device to fb1 in either Qt or X-Windows you will see output in your LCD.

6.2.1 Launch Lubuntu Desktop on 2.8"LCD

On lubuntu desktop run the following commands:
Firstly remove the armsoc configuration file:

sudo rm -f /usr/share/X11/xorg.conf.d/20-armsoc.conf

Secondly create a new configuration file /etc/X11/xorg.conf:

sudo vi /etc/X11/xorg.conf

Here is its content:

Section "Monitor"
    Identifier          "Primary"
    VendorName          "FriendlyARM"
EndSection
 
Section "Device"
    Identifier          "Primary"
    Driver              "fbdev"
    Option              "fbdev" "/dev/fb1"
EndSection

After reboot you will see the following GUI:
s5pxx18-lubuntu-spi2.8tft.png
A touch panel is currently not supported yet. You need to use a mouse and keyboard to operate.

6.2.2 Run Qt Application on 2.8"LCD

Open a terminal in friendly-core and run the following commands to start a Qt demo:

. setqt5env
export QT_QPA_PLATFORM=linuxfb:fb=/dev/fb1
export QT_QPA_EGLFS_TSLIB=1
export QT_QPA_GENERIC_PLUGINS=tslib,evdevkeyboard
$QTDIR/examples/widgets/widgets/tetrix/tetrix

Here is a Qt demo:
s5pxx18-lubuntu-spi2.8tft.png
A touch panel is currently not supported yet. You need to use a mouse and keyboard to operate.

7 Update Log

7.1 Dec-15-2017

  • Released English version

8 Resources

9 Update Log

9.1 Feb-24-2016

  • Added the driver's source code location in Section 5.2

9.2 June-17-2016

  • Re-organized and simplified wiki

9.3 March-5-2017

  • Added sections 3.2, 3.3, 3.4 and 4.1

9.4 July-5-2017

  • Updated sections 4 and 5

9.5 July-15-2017

  • Updated section 5