Overview

Feature

  • 2.8-inch IPS capacitive touch screen with a hardware resolution of 480×640.
  • Capacitive 5-point touch control.
  • Tempered glass capacitive touch panel, hardness up to 6H.
  • Drive LCD directly through Raspberry Pi's DSI interface with a refresh rate of up to 60Hz.
  • Working with Raspberry Pi, supports Raspberry Pi OS system.
  • Support Pi 4B/3B+/3A+, CM3+/4 must be used with adapter board.
  • Backlight brightness control by the software.

Working with Raspberry Pi

Hardware Connection

Use a 15PIN FPC cable to connect the 2.8inch DSI LCD to the DSI interface of the Raspberry Pi.
Fpc-pi001.jpg

Software Setting

  1. Download the image of the newest version Raspberry Pi, download the compressed file to the PC and extract the .img file
  2. Connect TF card to PC, use SDFormatter to format TF card
  3. Open Win32DiskImager software, select the system image prepared in step 1 and click write to burn the system image
  4. After the programming is completed, connect the TF card to the Raspberry Pi, start the Raspberry Pi, and log in to the terminal of the Raspberry Pi (you can connect the Raspberry Pi to an HDMI display or log in remotely with ssh)
git clone https://github.com/waveshare/2.8inch-DSI-LCD.git
cd 2.8inch-DSI-LCD
#To check the current system, if it is 32-bit system, you will enter 32-bit system. If it is 64-bit system, you will enter 64-bit system.
cd 32
#cd 64
#Enter uname -a to the terminal for checking the version of the kernel, and get the corresponding document content
cd 5.15.32
sudo ./WS_2_8inchDSI480x640_MAIN.sh
sudo reboot

Note: The above steps need to ensure that the Raspberry Pi can be connected to the Internet normally.

  1. Wait for the system to restart, it will be able to display and touch normally.

Rotation

Method 1

In the start menu, select: Preferences->Screen Configuration->Configure->Screens->DSI-1->Orientation, select the corresponding angle in it, click "√", select Yes, and restart.
4inch-DSI-LCD-Manual-02.jpg
2022/2/10 Note:

Known bugs in the current Bullseye branch:

1. If you use the above method to rotate after opening VNC, the rotation direction of the touch is wrong.

2. The above rotation method will also rotate abnormally on Pi3. These two bugs will be fixed in later versions.

If you need to open VNC and rotate at the same time, or use it on Pi3, you can use method two.

Method 2

Display rotation:

sudo nano /etc/xdg/lxsession/LXDE-pi/autostart
#Enter the command corresponding to the display rotation angle at the end of the autostart file, and it will take effect after restarting
#display rotated 90 degrees
xrandr --output DSI-1 --rotate right
#display rotated 180 degrees
xrandr --output DSI-1 --rotate inverted
#display rotated 270 degrees
xrandr --output DSI-1 --rotate left

Touch to rotate:

sudo nano /boot/config.txt
#Modify the instruction of the touch rotation angle at the end of the config.txt file, and it will take effect after restarting (there is a 0° touch direction instruction by default)
#90°:
dtoverlay=WS_2_8inchDSI480x640_Touch
#180°:
dtoverlay=WS_2_8inchDSI480x640_Touch,swappedxy,invertedx
#270°:
dtoverlay=WS_2_8inchDSI480x640_Touch,invertedx,invertedy
#0°:
dtoverlay=WS_2_8inchDSI480x640_Touch,invertedy,swappedxy

Backlight Control

Method 1

Using the application provided by Micro Snow (this program is only used for Raspberry Pi OS system), users can download, install and use in the following ways:

#Find the original driver directory
cd 2.8inch-DSI-LCD
#Determine the number of bits of the system currently in use, the 32-bit system enters 32 directory, the 64-bit system enters 64 directory
cd 32
#cd 64
cd Brightness
sudo ./install.sh

After the installation is complete, you can open the program in the Start menu - > Accessories - > Brightness, as shown below:
Top-2.png

Method 2

sudo nano /boot/config.txt
#In config.txt, change dtoverlay=WS_2_8inchDSI480x640_Screen to the following command, where x is 0-255, 0 is the darkest, 255 is the brightest, and the default is the brightest)
dtoverlay=WS_2_8inchDSI480x640_Screen,Backlight=x
#like:
dtoverlay=WS_2_8inchDSI480x640_Screen,Backlight=100
# Just restart
reboot

How to Use CSI Camera in Buster Branch

Note: If you don't know the difference between the two branches of Raspberry Pi OS, you can check the following introduction #Raspberry Pi OS branch introduction

  • illustrate

When the DSI LCD is used, the KMS display driver needs to be loaded, which will conflict with the default camera subsystem raspicam of the Buster branch.
The libcamera camera subsystem needs to be compiled and installed before the CSI camera related to the Raspberry Pi can be used normally.
If the user uses the Bullseye branch, then no action is required to use the Raspberry Pi related CSI camera.

  • Hardware connection

Turn off the Raspberry Pi first, connect the Raspberry Pi camera, and power on the Raspberry Pi.
Note: It is not allowed to plug and unplug the Raspberry Pi camera with power on, otherwise it may cause the related circuit to be burned out.

  • Update and open the camera interface

The libcamera-apps application supports Pi3 and Pi4. Before installing, you need to update your Raspberry Pi software:

sudo apt update

Set the correct dtoverlay in /boot/config.txt according to the actual camera

sudo nano /boot/config.txt

Add at the end of the document:

# Take RPi Camera V2 as an example, the photosensitive chip is Sony IMX219, then add the following code:
dtoverlay=imx219
#Similarly, OV5647 chip:
#dtoverlay=ov5647
#IMX477 chip:
#dtoverlay=imx477

Open the camera interface and execute the following commands:

sudo raspi-config

Select 3 Inteface Options -> P1 Camera -> Enter -> Yes -> Finish -> Yes, then the Raspberry Pi will restart.

Libcamera Installation Method 1

Note 1: It is recommended to use Pi4 to install and compile libcamera-apps instead of Pi3, because Pi4 has stronger performance and compilation is not prone to errors. The compiled image can also be used on Pi3.
Note 2: In the process of installing libcamera, there may be errors in some steps. If you are a novice, it is recommended to directly burn #Method 1: Use the image with the pre-installed driver, in which we have installed libcamera.
Install all required dependencies for libcamera:

sudo apt install libboost-dev -y
sudo apt install libgnutls28-dev openssl libtiff5-dev -y
sudo apt install qtbase5-dev libqt5core5a libqt5gui5 libqt5widgets5 -y
sudo apt install meson -y
sudo pip3 install pyyaml ply
sudo pip3 install --upgrade meson

Now we can download and build libcamera:

git clone git://linuxtv.org/libcamera.git
cd libcamera
meson build
cd build
meson configure -Dpipelines=raspberrypi -Dtest=false
cd ..
ninja -C build
sudo ninja -C build install
  • libepoxy

Libcamera-apps requires libepoxy to be installed. First install its prerequisites:

sudo apt install libegl1-mesa-dev

Then download and build libepoxy:

cd
git clone https://github.com/anholt
cd libepoxy
mkdir _build
cd _build
meson
ninja
sudo ninja install
  • libcamera-apps

Libcamera-apps further operates as follows:

sudo apt install cmake libboost-program-options-dev libdrm-dev libexif-dev

To build libcamera-apps, enter:

cd
git clone https://github.com/raspberrypi/libcamera-apps.git
cd libcamera-apps
mkdir build
cd build
cmake..
make -j4

Finally, use the libcamera-hello command to open a 5-second preview camera screen:

./libcamera-hello

Introduction to related instructions:

libcamera-still # can be used instead of raspistill. 
libcamera-vid # can be used instead of raspivid.
libcamera-raw A version of #libcamera-vid that saves uncompressed raw video files.
libcamera-hello #Startup command, run it to see the camera image on the display.
libcamera-jpeg # A stripped-down version of libcamera - can still run preview and capture JPEG, uninterrupted by other options.

Note: After installing libcamera-apps, the original DSI driver will be overwritten. In order to make the DSI LCD work normally, you need to reinstall the driver:

#For 7inch DSI LCD (C):
cd 7inch-DSI-LCD-C
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_7inchDSI1024x600_MAIN.sh
sudo reboot
#For 4inch DSI LCD:
cd 4inch-DSI-LCD
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_4inchDSI480x800_MAIN.sh
sudo reboot
#For 2.8inch DSI LCD:
cd 2.8inch-DSI-LCD
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_2_8inchDSI480x640_MAIN.sh
sudo reboot

Libcamera Installation Method 2

Since there are many steps to install libcamera, it takes a long time. We provide a script for direct installation.
The specific operation steps are as follows:
1. Update the list of available packages

sudo apt update

2. Download libcamera-install file and install

git clone https://github.com/waveshare/libcamera-install.git
cd libcamera-install
sudo chmod +x install_libcamera_all.sh
sudo ./install_libcamera_all.sh

3. The echo "install Succeed" appears to indicate successful installation. When echo "install Fail" appears, the installation failed.
After successful installation, three folders, libcamera, libcamera-apps and libepoxy will be generated in the libcamera-install directory. If you need to reinstall, you should delete these three folders first, and then reinstall.
Affected by the network, the installation may be unsuccessful if you run it once, and you can run it several times.
Note: After installing libcamera-apps, the original DSI driver will be overwritten. In order to make the DSI LCD work normally, you need to reinstall the driver:

#For 7inch DSI LCD (C):
cd 7inch-DSI-LCD-C
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_7inchDSI1024x600_MAIN.sh
sudo reboot
#For 4inch DSI LCD:
cd 4inch-DSI-LCD
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_4inchDSI480x800_MAIN.sh
sudo reboot
#For 2.8inch DSI LCD:
cd 2.8inch-DSI-LCD
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_2_8inchDSI480x640_MAIN.sh
sudo reboot

4. reboot

sudo reboot

5. Test, and display the camera image for 5 seconds

cd /home/pi/libcamera-install/libcamera-apps/build
./libcamera-hello
  • Advanced

For more instructions on using libcamera, please refer to:
https://www.raspberrypi.org/documentation/linux/software/libcamera/README.md
https://github.com/raspberrypi/libcamera-apps/blob/main/README.md
https://www.raspberrypi.org/documentation/linux/software/libcamera/rpi_SOFT_libcamera_1p2.pdf

Raspberry Pi OS

On December 2, 2021, the Raspberry Pi OS for Raspberry Pi split into two branches, the Buster branch and the Bullseye branch.

The Buster branch is a continuation of the old system, which is more stable and uses raspicam as the default camera subsystem.

The Bullseye branch adds some new features, including KMS as the default display driver and libcamera as the default camera subsystem.

For the project used with this display, we recommend users to use the Bullseye branch system, because on this system, it can be used normally with simple configuration, and the default I2C0 in the DSI interface can be used for communication without occupying the raspberry Send I2C1 in 40PIN GPIO.

For users who must use the Buster branch, we also provide related drivers, but because the DSI driver needs to load the KMS display driver by default, the default camera subsystem of raspicam under the Buster branch cannot be used and needs to be recompiled and installed. The libcamera camera subsystem (for beginners, it is difficult), and in order to make the raspicam camera subsystem not conflict with the DSI driver, the DSI driver will occupy the I2C1 in the 40PIN GPIO of the Raspberry Pi.

For the Bullseye branch, the Micro Snow R&D team will maintain the update for a long time. For the Buster branch, we will continue to support it until June 2024 (because the Raspberry Pi Foundation will not support the Buster branch after this time).

The following is a list of system support for this display:

SystemBranchOperating System Bits
2022-01-28-raspios-bullseye-arm64bullseye64 bits
2022-01-28-raspios-bullseye-armhfbullseye32 bits
2022-01-28-raspios-buster-armhfbuster32 bits
2021-10-30-raspios-bullseye-armhfbullseye32 bits
2021-12-02-raspios-buster-armhfbuster32 bits

Download Images
Dsi-lcd.png
Raspberry Pi OS and Raspberry Pi OS (64-bit) are the Bullseye branch, and Raspberry Pi OS (Legacy) is the Buster branch.
More detailed information can be found at:
Raspberry Pi Branch Details

Buster

Bullseye
Note: The above information was updated on February 10, 2022. Due to the frequent update of the Raspberry Pi image, when you see this information, the relevant information may be out of date. The actual performance of the image shall prevail. This is for reference only .

Precaution

Update the system, such as executing the following command

sudo apt-get update
sudo apt-get full-upgrade

After updating the system, some files of the originally installed driver may be overwritten, and the driver needs to be reinstalled to display normally.
2. Replace the motherboard
If the driver is originally installed on the Raspberry Pi 4 Model B, the user replaces the motherboard, such as modifying it to a Raspberry Pi 3 Model B+, the display will not display properly.
Because Pi4 and Pi3 need to load different driver files, you need to reinstall the driver on the new motherboard to display properly

Resource